diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..b17411b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,132 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    env:
+      # Qt without a display server (UiEventBridge tests create a QCoreApplication)
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libportaudio2 libasound2 \
+            libgl1-mesa-dev libegl1-mesa-dev libxkbcommon0 libfontconfig1 \
+            libdbus-1-3 libxcb-xinerama0 libxcb-cursor0 libxcb-shape0 \
+            libxcb-icccm4 libxcb-keysyms1 libxcb-render-util0 libxcb-image0 \
+            libnss3
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install Node dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+
+      - name: Setup Python environment
+        run: |
+          uv python install 3.12
+          uv venv --python 3.12 .venv
+          uv sync
+
+      - name: Version consistency
+        run: node scripts/version.mjs check
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Backend tests
+        # test_transcription is excluded — it downloads a whisper model.
+        # Clipboard tests self-skip headless (no DISPLAY/WAYLAND_DISPLAY).
+        run: uv run -p .venv pytest src-pyloid/tests/ -q --ignore=src-pyloid/tests/test_transcription.py
+
+  # Build verification without installers — catches PyInstaller spec drift
+  # (new modules/data files not bundled) before it surfaces on a release tag.
+  # Runs in parallel with `test` so test feedback isn't delayed. Free on
+  # public repos; no artifacts uploaded (dist/ is hundreds of MB and the
+  # release workflow's workflow_dispatch covers "build me this branch").
+  build:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 25
+    env:
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgl1-mesa-dev libegl1-mesa-dev libxkbcommon0 libfontconfig1 \
+            libdbus-1-3 libxcb-xinerama0 libxcb-cursor0 libxcb-shape0 \
+            libxcb-icccm4 libxcb-keysyms1 libxcb-render-util0 libxcb-image0 \
+            libnss3 libasound2
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install Node dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+
+      - name: Setup Python environment
+        run: |
+          uv python install 3.12
+          uv venv --python 3.12 .venv
+          uv sync
+
+      - name: Build application
+        run: pnpm run build
+
+      - name: Smoke test - binary exists and shared libraries resolve
+        run: |
+          test -x ./dist/VoiceFlow/VoiceFlow || { echo "::error::dist/VoiceFlow/VoiceFlow missing or not executable"; exit 1; }
+          MISSING=$(ldd ./dist/VoiceFlow/VoiceFlow 2>&1 | grep "not found" || true)
+          if [ -n "$MISSING" ]; then
+            echo "::error::Missing shared libraries:"
+            echo "$MISSING"
+            exit 1
+          fi
+          echo "Build OK: $(du -sh dist/VoiceFlow | cut -f1) bundle, all shared libraries resolved."
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 94c56db..0a19222 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -75,6 +75,19 @@ jobs:
           fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
+      - name: Verify version consistency
+        run: |
+          node scripts/version.mjs check
+          # On tag builds, the tag must match the committed version — catches
+          # tagging the wrong commit before 30 minutes of build time is spent.
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            PKG=$(node -p "require('./package.json').version")
+            if [[ "$PKG" != "${{ steps.version.outputs.version }}" ]]; then
+              echo "::error::Tag v${{ steps.version.outputs.version }} does not match package.json version $PKG — bump with scripts/version.mjs and re-tag."
+              exit 1
+            fi
+          fi
+
       - name: Build application
         run: pnpm run build
 
@@ -98,6 +111,24 @@ jobs:
           rm -f ./dist/VoiceFlow/_internal/libasound*
           echo "Removed bundled PortAudio + ALSA (will use system libraries at runtime)"
 
+      - name: Verify audio library layout
+        run: |
+          # Regression guard for the recurring "no mics in release build" bug
+          # (v1.3.x–v1.5.0): the bundled libasound/libportaudio MUST be gone...
+          LEFTOVER=$(find ./dist/VoiceFlow/_internal -maxdepth 1 \( -name 'libasound*' -o -name 'libportaudio*' \) | head -5)
+          if [ -n "$LEFTOVER" ]; then
+            echo "::error::Bundled audio libraries still present (would break mic enumeration on non-Ubuntu distros): $LEFTOVER"
+            exit 1
+          fi
+          # ...while PyAV's renamed copy MUST remain — libavdevice lists
+          # libasound-cfbebb71.so.2.0.0 in NEEDED and the app crashes at
+          # startup without it (different SONAME, coexists with system lib).
+          if ! ls ./dist/VoiceFlow/_internal/av.libs/libasound-* >/dev/null 2>&1; then
+            echo "::error::PyAV's av.libs/libasound-* is missing — startup will fail with ImportError. The cleanup step deleted too much."
+            exit 1
+          fi
+          echo "Audio library layout OK (system libasound/portaudio at runtime, PyAV copy intact)"
+
       - name: Clear executable stack flags
         run: |
           # python-build-standalone builds ship libpython with GNU_STACK RWE,
@@ -183,6 +214,18 @@ jobs:
           fi
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
+      - name: Verify version consistency
+        shell: bash
+        run: |
+          node scripts/version.mjs check
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            PKG=$(node -p "require('./package.json').version")
+            if [[ "$PKG" != "${{ steps.version.outputs.version }}" ]]; then
+              echo "::error::Tag v${{ steps.version.outputs.version }} does not match package.json version $PKG — bump with scripts/version.mjs and re-tag."
+              exit 1
+            fi
+          fi
+
       - name: Build application
         run: pnpm run build
 
diff --git a/CLAUDE.md b/CLAUDE.md
index af96a85..4d6d584 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 VoiceFlow is a cross-platform voice-to-text paste utility built with Pyloid (Python desktop framework using PySide6/Qt WebEngine) and React. Users hold a hotkey to record audio, release to transcribe using faster-whisper, and the text is automatically pasted at the cursor. Supports Windows, Linux (Wayland/X11), and macOS.
 
+As of v1.6.0, VoiceFlow also ships a **Meeting Mode** — long-form recording with mic + system-loopback capture, async transcription, and LLM-generated summaries. This is a separate feature surface from the push-to-talk paste flow, kept self-contained under `services/recording/` so it can evolve (or be extracted) without touching PTT code.
+
 ## Commands
 
 ```bash
@@ -26,19 +28,35 @@ pnpm run build:installer          # Windows (.exe via Inno Setup)
 pnpm run build:installer:linux    # Linux (.tar.gz + .AppImage)
 pnpm run build:installer:macos    # macOS (.dmg)
 
-# Run Python tests
-cd VoiceFlow && uv run -p .venv pytest src-pyloid/tests/
+# Run Python tests (fast suite — excludes test_transcription, which downloads a model)
+pnpm run test
+pnpm run test:all                 # includes test_transcription
 
 # Run single test file
 uv run -p .venv pytest src-pyloid/tests/test_transcription.py -v
 
+# Everything CI runs (lint + typecheck + tests + version consistency)
+pnpm run check
+
+# Version bump — updates all five version files (package.json, voiceflow.iss,
+# pyproject.toml, constants.ts, uv.lock); never edit them by hand
+pnpm run version:bump X.Y.Z
+pnpm run version:check
+
 # Run frontend only (for UI development)
 pnpm run vite
 
-# Lint frontend
+# Lint / typecheck frontend
 pnpm run lint
+pnpm run typecheck
 ```
 
+CI (`.github/workflows/ci.yml`) runs lint, typecheck, version check, and the fast
+test suite on every PR and push to main. The release workflow
+(`.github/workflows/release.yml`) additionally refuses tags that don't match
+package.json and verifies the Linux artifact's audio-library layout
+(bundled libasound/libportaudio removed, PyAV's av.libs copy intact).
+
 ## Architecture
 
 ### Backend (src-pyloid/)
@@ -46,8 +64,8 @@ pnpm run lint
 Python backend using Pyloid framework with PySide6:
 
 - **main.py** - Application entry point. Creates Pyloid app, tray icon, main dashboard window, and recording popup window. Sets up UI callbacks connecting backend events to popup state changes.
-- **server.py** - RPC server using `PyloidRPC`. Exposes methods (`get_settings`, `update_settings`, `get_history`, etc.) that frontend calls via `pyloid-js` RPC.
-- **app_controller.py** - Singleton controller orchestrating all services. Handles hotkey activate/deactivate flow: start recording -> stop recording -> transcribe -> paste at cursor -> save to history.
+- **server.py** - RPC server using `PyloidRPC`. Exposes PTT methods (`get_settings`, `update_settings`, `get_history`, etc.) plus the full Meeting Mode surface (`meetings.list_audio_sources`, `meetings.start`, `meetings.pause`, `meetings.resume`, `meetings.stop`, `meetings.transcribe`, `meetings.summarize`, `meetings.get_llm_config`, `meetings.test_llm_connection`, etc.) that frontend calls via `pyloid-js` RPC.
+- **app_controller.py** - Singleton controller orchestrating all services. Handles hotkey activate/deactivate flow: start recording -> stop recording -> transcribe -> paste at cursor -> save to history. Also constructs and owns the `MeetingsController` (exposed as `controller.meetings`) and runs an unfinished-recording recovery sweep on startup.
 
 **Services (src-pyloid/services/):**
 - `audio.py` - Microphone recording using sounddevice, streams amplitude for visualizer
@@ -56,21 +74,37 @@ Python backend using Pyloid framework with PySide6:
 - `clipboard.py` - Clipboard operations and paste-at-cursor using pyautogui
 - `settings.py` - Settings management with defaults
 - `database.py` - SQLite database for settings and history (stored at ~/.VoiceFlow/VoiceFlow.db)
-- `logger.py` - Domain-based logging with hybrid format `[timestamp] [LEVEL] [domain] message | {json}`. Supports domains: model, audio, hotkey, settings, database, clipboard, window. Configured with 100MB log rotation.
-- `model_manager.py` - Whisper model download/cache management using huggingface_hub. Provides download progress tracking (percent, speed, ETA), cancellation via CancelToken, daemon thread execution, and `clear_cache()` to delete only VoiceFlow's faster-whisper models.
+- `logger.py` - Domain-based logging with hybrid format `[timestamp] [LEVEL] [domain] message | {json}`. Supports domains: model, audio, hotkey, settings, database, clipboard, window, plus Meeting-Mode domains (recording, transcribe, summary, llm). Configured with 100MB log rotation.
+- `model_catalog.py` - Single source of truth for the Whisper model catalog (names, sizes, HF repo IDs). Imported by `model_manager`, `transcription`, and `settings`; the frontend gets repo IDs over RPC (`get_model_info` → `repoId`) rather than keeping its own copy. Never re-declare the model list elsewhere.
+- `model_manager.py` - Whisper model download/cache management using huggingface_hub. Owns the single-flight background download session (`start_download` / `cancel_download` / `get_download_status` — the RPC surface), download progress tracking (percent, speed, ETA), cancellation via CancelToken, and `delete_model()` / `clear_cache()`. Model *loading* lives in `TranscriptionService` (the only load path, since it resolves the user's device preference).
+
+**Meeting Mode services (src-pyloid/services/recording/):**
+Self-contained per `docs/adr/0003-meeting-mode-isolation.md`; do not call these from the PTT path and vice versa.
+- `controller.py` - `MeetingsController` — the feature's facade. All RPC handlers go through this object. Emits `recording-state`, `recording-transcribe-progress`, and `recording-summarize-progress` events to the frontend via the emitter installed by `main.py`.
+- `recorder.py` - Long-form recorder with pause/resume, segmented WAV writing, and clock tracking. Sources are fixed at `start()` and cannot change mid-recording.
+- `audio_source.py` - Enumerates available mic + loopback devices for the UI device picker.
+- `loopback_linux.py` / `loopback_pulse.py` / `loopback_windows.py` - Platform-specific system-audio capture (PulseAudio/PipeWire on Linux, WASAPI loopback on Windows).
+- `clock.py` - Monotonic recording clock that survives pause/resume.
+- `llm.py` - LLM client with preset + custom-endpoint support; used by summary/title generation.
+- `summary.py` / `title.py` - LLM-driven summary and auto-title generation for finished recordings.
+- `secrets.py` - API-key storage for LLM providers (kept out of the main settings table).
+- `export.py` - Exports a recording's transcript/summary to text formats.
+- `recovery.py` - On startup, sweeps recordings left in `recording` / `paused` state from a previous (crashed) session and rolls them forward.
+- `audio_scheme.py` / `audio_scheme_handler.py` - Custom Qt `audio://` URL scheme so the WebEngine `<audio>` element can stream recording WAVs from disk without a server.
 
 ### Frontend (src/)
 
 React 18 + TypeScript + Vite frontend:
 
 - **App.tsx** - Hash-based routing between `/popup`, `/onboarding`, and `/dashboard`. Checks model cache on startup and shows recovery modal if model is missing.
-- **lib/api.ts** - RPC wrapper using `pyloid-js` to call Python backend methods. Includes model management APIs (`getModelInfo`, `startModelDownload`, `cancelModelDownload`).
-- **lib/types.ts** - TypeScript interfaces for Settings, HistoryEntry, Stats, Options, ModelInfo, DownloadProgress
-- **pages/** - Popup (recording indicator), Onboarding (includes model download step), Dashboard
+- **lib/api.ts** - RPC wrapper using `pyloid-js` to call Python backend methods. Includes model management APIs (`getModelInfo`, `startModelDownload`, `cancelModelDownload`) plus the full `recordings*` / meetings RPC surface.
+- **lib/types.ts** - TypeScript interfaces for Settings, HistoryEntry, Stats, Options, ModelInfo, DownloadProgress, plus meeting types: `Recording`, `RecordingSegment`, `RecorderState`, and LLM config types.
+- **pages/** - Popup (recording indicator), Onboarding (includes model download step), Dashboard. Dashboard uses React Router for sub-routes: `history`, `meetings`, `meetings/record`, `meetings/:id`, `settings`.
 - **components/** - Feature components plus shadcn/ui components in `components/ui/`
   - `ModelDownloadProgress.tsx` - Download progress UI with progress bar, speed, ETA, and retry support
   - `ModelDownloadModal.tsx` - Dialog wrapper for model downloads triggered from settings
   - `ModelRecoveryModal.tsx` - Startup modal for missing model recovery
+  - `meetings/` - Meeting Mode UI: `MeetingsListPage`, `MeetingRecorderPage`, `MeetingDetailPage`, `MeetingImportDialog`, `MeetingRecorderContext` (cross-route recorder state), `AudioPlayer`, `LevelMeter`, `StatusLine`, `TranscriptView`, `SummaryView`, `RetranscribeDialog`, `LLMSettingsSection`, `MeetingsSettingsSection`.
 
 ### Frontend-Backend Communication
 
@@ -124,6 +158,27 @@ For transparent popup windows on Windows:
 6. On completion, model is cached in huggingface cache directory
 7. Turbo model uses `mobiuslabsgmbh/faster-whisper-large-v3-turbo` (same as faster-whisper internal mapping)
 
+### Meeting Mode (long-form recording)
+
+Separate from the PTT paste flow. Entrypoint: `controller.meetings` (`MeetingsController`). See `docs/adr/0001-stereo-channel-layout-for-recordings.md` for the on-disk audio layout decision.
+
+1. UI calls `meetings.list_audio_sources()` to populate the device picker (mic + loopback).
+2. `meetings.start(mic_device_id, loopback_device_id)` opens up to two simultaneous capture streams. Sources are fixed at start — they cannot be added/removed mid-recording.
+3. Audio is written to a WAV file under `~/.VoiceFlow/recordings/`:
+   - Two active sources → **stereo 16 kHz PCM16**, mic on **L**, loopback on **R** (kept separate on purpose; enables future speaker diarization with no ML — see ADR 0001).
+   - One active source → mono 16 kHz PCM16.
+4. `meetings.pause()` / `meetings.resume()` use a monotonic `Clock` to track real recording time; segments are stitched into one logical recording.
+5. `meetings.stop()` finalizes the WAV and persists metadata. Recording rows live in the same SQLite DB but in their own table.
+6. Transcription is **async and on-demand**: `meetings.transcribe(id)` runs faster-whisper in a daemon thread and emits `recording-transcribe-progress` events. Long jobs do not block the RPC channel (see fix `dc04d29`).
+7. After transcription, `meetings.summarize(id, prompt)` calls the configured LLM provider (preset or custom endpoint) to produce an AI summary, and `title.py` auto-generates a title. LLM config and API keys live in `services/recording/llm.py` + `secrets.py`, not in the main `settings` table.
+8. Audio playback in the detail page uses a custom Qt `audio://` URL scheme (`audio_scheme.py`) so the WebEngine can stream the WAV directly without an HTTP server.
+9. On startup, `recovery.py` rolls forward any recordings left in `recording` / `paused` state from a crashed previous session.
+
+**Platform quirks**:
+- Linux loopback uses PulseAudio/PipeWire monitor sources (`loopback_pulse.py` / `loopback_linux.py`).
+- Windows loopback uses WASAPI. Must open the loopback stream at the device's native channel count (`max_output_channels`) — opening at a forced channel count fails on many devices (fixes `96b0b73`, `13d45be`).
+- Pyloid validates window IDs on every RPC roundtrip from a background thread; long-running meeting RPCs work around this (see `135fdd7`).
+
 ## Key Patterns
 
 - **Singleton controller**: `get_controller()` returns singleton `AppController` instance
diff --git a/docs/adr/0001-stereo-channel-layout-for-recordings.md b/docs/adr/0001-stereo-channel-layout-for-recordings.md
new file mode 100644
index 0000000..a0281f5
--- /dev/null
+++ b/docs/adr/0001-stereo-channel-layout-for-recordings.md
@@ -0,0 +1,18 @@
+# Stereo channel layout for two-source Recordings
+
+When a Recording captures both a mic and a system-loopback source, the WAV is
+written as stereo 16 kHz PCM16 with the **mic on the left channel (ch 0)** and
+the **loopback on the right channel (ch 1)** — deliberately *not* mixed down to
+mono. Keeping the sides separate means "who said what" (you vs. them) is
+recoverable later by channel, enabling speaker attribution with zero ML
+diarization. A single-source Recording is mono.
+
+## Consequences
+
+- Sources are fixed at `start()`; a source cannot be added or removed
+  mid-recording, because the channel count of the WAV is decided up front.
+- In stereo mode the recorder pads a starved side with silence (starvation
+  detection in `recorder.py`) so the channels stay time-aligned — alignment is
+  the property that makes per-channel attribution trustworthy.
+- Playback of a stereo Recording sounds hard-panned (you fully left, them
+  fully right). That is accepted, not a bug.
diff --git a/docs/adr/0002-recording-vs-meeting-naming.md b/docs/adr/0002-recording-vs-meeting-naming.md
new file mode 100644
index 0000000..2a51672
--- /dev/null
+++ b/docs/adr/0002-recording-vs-meeting-naming.md
@@ -0,0 +1,11 @@
+# "Recording" in code, "Meeting" in the UI
+
+The meeting-notes entity is named **Recording** everywhere machine-facing —
+DB table (`recordings`), RPC methods (`recordings_*`), services, the audio
+folder, log domains — while the UI labels the same thing "Meeting" (nav item,
+page titles, copy), because the dominant use case is multi-party meeting
+capture. The split is deliberate: "recording" describes what the thing *is*
+(any captured audio, including imports and solo dictation experiments), while
+"meeting" describes the dominant *use*; marketing copy can change without a
+schema migration. Do not "fix" one side to match the other. See CONTEXT.md
+for the full glossary entry.
diff --git a/docs/adr/0003-meeting-mode-isolation.md b/docs/adr/0003-meeting-mode-isolation.md
new file mode 100644
index 0000000..a64a22a
--- /dev/null
+++ b/docs/adr/0003-meeting-mode-isolation.md
@@ -0,0 +1,17 @@
+# Meeting Mode is self-contained under services/recording/
+
+Meeting Mode (long-form Recording capture/transcribe/summarize) lives entirely
+under `src-pyloid/services/recording/` behind the `MeetingsController` facade,
+and must not call into the push-to-talk path (hotkey → record → paste) nor be
+called from it. The two features share only the leaf services injected at
+construction (`DatabaseService`, `SettingsService`, `TranscriptionService`).
+This keeps the newer, faster-evolving Meeting Mode extractable (or removable)
+without destabilizing the PTT flow that is the product's core promise.
+
+## Consequences
+
+- Shared needs (e.g. transcription) are met by injecting the shared service,
+  never by importing PTT modules from `services/recording/` or vice versa.
+- Recording persistence lives in `RecordingsRepository`
+  (`services/recording/repository.py`), not spread through the shared
+  `DatabaseService` surface.
diff --git a/package.json b/package.json
index 64429c7..763817d 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,13 @@
     "build:installer": "pnpm run build && cd installer && build-installer.bat",
     "build:installer:linux": "pnpm run build && bash installer/build-linux.sh",
     "build:installer:macos": "pnpm run build && bash installer/build-macos.sh",
+    "lint": "eslint src",
+    "typecheck": "tsc -b",
+    "test": "uv run -p .venv pytest src-pyloid/tests/ --ignore=src-pyloid/tests/test_transcription.py",
+    "test:all": "uv run -p .venv pytest src-pyloid/tests/",
+    "check": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run version:check",
+    "version:check": "node scripts/version.mjs check",
+    "version:bump": "node scripts/version.mjs bump",
     "setup": "pnpm install && uv venv && uv sync"
   },
   "dependencies": {
diff --git a/scripts/version.mjs b/scripts/version.mjs
new file mode 100644
index 0000000..308b250
--- /dev/null
+++ b/scripts/version.mjs
@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/* Single tool for the five files that declare the app version.
+ *
+ *   node scripts/version.mjs check        exit 1 if any file disagrees
+ *   node scripts/version.mjs bump 1.7.0   rewrite all five
+ *
+ * The five (see also the release guide):
+ *   package.json            "version"            (build-linux.sh artifact names)
+ *   installer/voiceflow.iss #define MyAppVersion (Windows installer; CI also
+ *                                                 patches this from the git tag)
+ *   pyproject.toml          version              (Python package metadata)
+ *   src/lib/constants.ts    APP_VERSION          (shown in the UI)
+ *   uv.lock                 voiceflow virtual root package version
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/* Each target: file path, a regex with the version in capture group 2
+ * (group 1 = prefix kept on rewrite). */
+const TARGETS = [
+  {
+    file: "package.json",
+    re: /("version":\s*")([^"]+)(")/,
+  },
+  {
+    file: "installer/voiceflow.iss",
+    re: /(#define MyAppVersion ")([^"]+)(")/,
+  },
+  {
+    file: "pyproject.toml",
+    re: /(^version = ")([^"]+)(")/m,
+  },
+  {
+    file: "src/lib/constants.ts",
+    re: /(APP_VERSION = ")([^"]+)(")/,
+  },
+  {
+    // uv.lock: the virtual root package block. The version line directly
+    // follows `name = "voiceflow"`.
+    file: "uv.lock",
+    re: /(name = "voiceflow"\nversion = ")([^"]+)(")/,
+  },
+];
+
+function readVersions() {
+  return TARGETS.map(({ file, re }) => {
+    const text = readFileSync(join(root, file), "utf8");
+    const m = text.match(re);
+    if (!m) {
+      console.error(`ERROR: version pattern not found in ${file}`);
+      process.exit(2);
+    }
+    return { file, re, text, version: m[2] };
+  });
+}
+
+const [mode, arg] = process.argv.slice(2);
+
+if (mode === "check") {
+  const entries = readVersions();
+  const versions = new Set(entries.map((e) => e.version));
+  for (const e of entries) console.log(`${e.version}  ${e.file}`);
+  if (versions.size !== 1) {
+    console.error("\nERROR: version drift detected — run: node scripts/version.mjs bump <version>");
+    process.exit(1);
+  }
+  console.log(`\nOK: all files at ${entries[0].version}`);
+} else if (mode === "bump") {
+  if (!/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(arg || "")) {
+    console.error(`Usage: node scripts/version.mjs bump <semver>   (got: ${arg})`);
+    process.exit(2);
+  }
+  for (const e of readVersions()) {
+    const next = e.text.replace(e.re, `$1${arg}$3`);
+    writeFileSync(join(root, e.file), next);
+    console.log(`${e.version} -> ${arg}  ${e.file}`);
+  }
+  console.log(`\nDone. Commit as: chore: bump version to ${arg}`);
+} else {
+  console.error("Usage: node scripts/version.mjs <check|bump <semver>>");
+  process.exit(2);
+}
diff --git a/src-pyloid/app_controller.py b/src-pyloid/app_controller.py
index c63f4c9..f2fea3c 100644
--- a/src-pyloid/app_controller.py
+++ b/src-pyloid/app_controller.py
@@ -1,32 +1,21 @@
-from typing import Optional, Callable, TypedDict
+from typing import Optional, Callable
 import threading
-import time
 import os
 import base64
-import wave
-import sqlite3
-from pathlib import Path
-import numpy as np
 
 from services.database import DatabaseService
-from services.settings import SettingsService
+from services.settings import SettingsService, settings_to_rpc, rpc_to_settings_kwargs
 from services.audio import AudioService
 from services.transcription import TranscriptionService
 from services.hotkey import HotkeyService
 from services.clipboard import ClipboardService
+from services.dictation import DictationPipeline
 from services.recording.controller import MeetingsController
 from services.logger import info, error, debug, warning, exception
 from services.gpu import is_cuda_available, get_gpu_name, get_cuda_compute_types, validate_device_setting, get_cudnn_status, reset_cuda_cache, has_nvidia_gpu
 from services.cudnn_downloader import download_cudnn, is_cuda_libs_installed, get_download_size_mb, get_download_progress, clear_cuda_dir
 
 
-class AudioAttachmentMeta(TypedDict):
-    audio_relpath: str
-    audio_duration_ms: int
-    audio_size_bytes: int
-    audio_mime: str
-
-
 class AppController:
     def __init__(self):
         # Initialize services
@@ -36,6 +25,15 @@ def __init__(self):
         self.transcription_service = TranscriptionService()
         self.hotkey_service = HotkeyService()
         self.clipboard_service = ClipboardService()
+        self.dictation = DictationPipeline(
+            settings_service=self.settings_service,
+            transcription_service=self.transcription_service,
+            clipboard_service=self.clipboard_service,
+            db=self.db,
+            audio_service=self.audio_service,
+            is_model_loaded=lambda: self._model_loaded,
+            is_model_loading=lambda: self._model_loading,
+        )
 
         # Meetings feature — its own self-contained controller. Constructed
         # after the shared services it depends on. See services/recording/.
@@ -194,70 +192,13 @@ def _handle_hotkey_deactivate(self):
 
         info(f"Recorded {len(audio)} samples")
 
-        # Transcribe in background
+        # Transcribe in background. The pipeline does the work; UI callbacks
+        # stay here so the pipeline remains testable without them.
         def transcribe():
             try:
-                # Wait for model to be loaded (with timeout)
-                wait_time = 0
-                while not self._model_loaded and wait_time < 30:
-                    if not self._model_loading:
-                        warning("Model not loaded and not loading, skipping transcription")
-                        if self._on_transcription_complete:
-                            self._on_transcription_complete("")
-                        return
-                    info(f"Waiting for model to load... ({wait_time}s)")
-                    time.sleep(1)
-                    wait_time += 1
-
-                if not self._model_loaded:
-                    error("Model load timeout, skipping transcription")
-                    if self._on_transcription_complete:
-                        self._on_transcription_complete("")
-                    return
-
-                settings = self.settings_service.get_settings()
-                info(f"Transcribing with language: {settings.language}")
-
-                text = self.transcription_service.transcribe(
-                    audio,
-                    language=settings.language,
-                )
-
-                info(f"Transcription result: '{text}'")
-
-                if text:
-                    # Prepend space if enabled (useful for continuous dictation)
-                    if settings.prepend_space:
-                        text = " " + text
-
-                    # Paste at cursor
-                    info("Pasting text at cursor...")
-                    self.clipboard_service.paste_at_cursor(text)
-
-                    # Save to history (and audio if enabled)
-                    history_id = self.db.add_history(text)
-
-                    if settings.save_audio_to_history:
-                        try:
-                            audio_meta = self._save_audio_attachment(history_id, audio)
-                            self.db.update_history_audio(
-                                history_id,
-                                audio_relpath=audio_meta["audio_relpath"],
-                                audio_duration_ms=audio_meta["audio_duration_ms"],
-                                audio_size_bytes=audio_meta["audio_size_bytes"],
-                                audio_mime=audio_meta["audio_mime"],
-                            )
-                            info(f"Saved audio attachment for history {history_id}")
-                        except (OSError, wave.Error, sqlite3.Error, ValueError) as exc:
-                            warning(f"Failed to save audio attachment: {exc}")
-
-                    if self._on_transcription_complete:
-                        self._on_transcription_complete(text)
-                else:
-                    warning("No text transcribed (empty result)")
-                    if self._on_transcription_complete:
-                        self._on_transcription_complete("")
-
+                text = self.dictation.run(audio)
+                if self._on_transcription_complete:
+                    self._on_transcription_complete(text)
             except Exception as e:
                 exception(f"Transcription error: {e}")
                 if self._on_error:
@@ -275,63 +216,22 @@ def _handle_amplitude(self, amplitude: float):
 
     # Settings methods for RPC
     def get_settings(self) -> dict:
-        settings = self.settings_service.get_settings()
-        return {
-            "language": settings.language,
-            "model": settings.model,
-            "device": settings.device,
-            "autoStart": settings.auto_start,
-            "retention": settings.retention,
-            "theme": settings.theme,
-            "onboardingComplete": settings.onboarding_complete,
-            "microphone": settings.microphone,
-            "saveAudioToHistory": settings.save_audio_to_history,
-            "showPopup": settings.show_popup,
-            "holdHotkey": settings.hold_hotkey,
-            "holdHotkeyEnabled": settings.hold_hotkey_enabled,
-            "toggleHotkey": settings.toggle_hotkey,
-            "toggleHotkeyEnabled": settings.toggle_hotkey_enabled,
-            "prependSpace": settings.prepend_space,
-            "recordingsAutoRenameTitle": settings.recordings_auto_rename_title,
-        }
+        return settings_to_rpc(self.settings_service.get_settings())
 
     def update_settings(self, **kwargs) -> dict:
         debug(f"update_settings called with: {kwargs}")
-        # Convert camelCase to snake_case
-        mapped = {}
-        if "autoStart" in kwargs:
-            mapped["auto_start"] = kwargs["autoStart"]
-        if "onboardingComplete" in kwargs:
-            mapped["onboarding_complete"] = kwargs["onboardingComplete"]
-        if "saveAudioToHistory" in kwargs:
-            mapped["save_audio_to_history"] = kwargs["saveAudioToHistory"]
-        if "showPopup" in kwargs:
-            mapped["show_popup"] = kwargs["showPopup"]
-        if "prependSpace" in kwargs:
-            mapped["prepend_space"] = kwargs["prependSpace"]
-        if "recordingsAutoRenameTitle" in kwargs:
-            mapped["recordings_auto_rename_title"] = kwargs["recordingsAutoRenameTitle"]
-        # Hotkey settings (camelCase to snake_case)
-        if "holdHotkey" in kwargs:
-            mapped["hold_hotkey"] = kwargs["holdHotkey"]
-        if "holdHotkeyEnabled" in kwargs:
-            mapped["hold_hotkey_enabled"] = kwargs["holdHotkeyEnabled"]
-        if "toggleHotkey" in kwargs:
-            mapped["toggle_hotkey"] = kwargs["toggleHotkey"]
-        if "toggleHotkeyEnabled" in kwargs:
-            mapped["toggle_hotkey_enabled"] = kwargs["toggleHotkeyEnabled"]
-
-        for key in ["language", "model", "device", "retention", "theme", "microphone"]:
-            if key in kwargs:
-                mapped[key] = kwargs[key]
-
+        mapped = rpc_to_settings_kwargs(kwargs)
         debug(f"Mapped settings: {mapped}")
         settings = self.settings_service.update_settings(**mapped)
 
-        # Reload model if model or device changed
+        # Reload model if model or device changed. The thread re-reads settings
+        # at execution time (not the snapshot from this call) so two rapid
+        # updates converge on the latest model regardless of thread scheduling;
+        # load_model itself serializes and short-circuits redundant loads.
         if "model" in mapped or "device" in mapped:
             def reload():
-                self.transcription_service.load_model(settings.model, settings.device)
+                latest = self.settings_service.get_settings()
+                self.transcription_service.load_model(latest.model, latest.device)
             threading.Thread(target=reload, daemon=True).start()
 
         # Update microphone if changed
@@ -477,15 +377,10 @@ def stop_test_recording(self) -> dict:
         info(f"Test recorded {len(audio)} samples")
 
         # Wait for model if needed
-        wait_time = 0
-        while not self._model_loaded and wait_time < 10:
-            if not self._model_loading:
-                return {"success": False, "error": "Model not loaded", "transcript": ""}
-            debug(f"Waiting for model... ({wait_time}s)")
-            time.sleep(0.5)
-            wait_time += 0.5
-
-        if not self._model_loaded:
+        readiness = self.dictation.wait_for_model(timeout_s=10, poll_s=0.5)
+        if readiness == "absent":
+            return {"success": False, "error": "Model not loaded", "transcript": ""}
+        if readiness == "timeout":
             return {"success": False, "error": "Model loading timeout", "transcript": ""}
 
         try:
@@ -558,49 +453,6 @@ def get_history_audio(self, history_id: int) -> dict:
             "durationMs": entry.get("audio_duration_ms"),
         }
 
-    def _save_audio_attachment(self, history_id: int, audio: np.ndarray) -> AudioAttachmentMeta:
-        """Persist recorded audio as WAV and return metadata for DB update."""
-        # Ensure audio directory exists
-        audio_dir = self.db.db_path.parent / "audio"
-        audio_dir.mkdir(parents=True, exist_ok=True)
-
-        relpath = Path("audio") / f"history_{history_id}.wav"
-        output_path = self.db.db_path.parent / relpath
-        tmp_path = output_path.with_suffix(".wav.tmp")
-
-        # Normalize audio into flat int16 PCM
-        audio_array = np.asarray(audio)
-        if audio_array.ndim > 1:
-            audio_array = audio_array.reshape(-1)
-
-        if np.issubdtype(audio_array.dtype, np.floating):
-            audio_clipped = np.clip(audio_array, -1.0, 1.0)
-            audio_int16 = (audio_clipped * 32767).astype(np.int16)
-        elif audio_array.dtype == np.int16:
-            audio_int16 = audio_array
-        else:
-            # Fallback: clip to int16 range
-            audio_clipped = np.clip(audio_array, -32768, 32767)
-            audio_int16 = audio_clipped.astype(np.int16)
-
-        with wave.open(str(tmp_path), "wb") as wf:
-            wf.setnchannels(self.audio_service.CHANNELS)
-            wf.setsampwidth(2)  # 16-bit PCM
-            wf.setframerate(self.audio_service.SAMPLE_RATE)
-            wf.writeframes(audio_int16.tobytes())
-
-        tmp_path.replace(output_path)
-
-        duration_ms = int((len(audio_int16) / float(self.audio_service.SAMPLE_RATE)) * 1000)
-        size_bytes = output_path.stat().st_size
-
-        return {
-            "audio_relpath": relpath.as_posix(),
-            "audio_duration_ms": duration_ms,
-            "audio_size_bytes": size_bytes,
-            "audio_mime": "audio/wav",
-        }
-
 
 # Singleton instance
 _controller: Optional[AppController] = None
diff --git a/src-pyloid/main.py b/src-pyloid/main.py
index e0e4087..7377415 100644
--- a/src-pyloid/main.py
+++ b/src-pyloid/main.py
@@ -28,62 +28,12 @@ def _preload_nvidia_libs():
     except Exception:
         pass  # Best-effort, don't crash on failure
 
-    # Imported lazily because services/* depends on env that we still need to
-    # configure below; keep the import inside the linux block so non-linux
-    # platforms don't pay the cost.
-    from services.process_env import system_env as _system_env_for_hyprctl
-
-    def _setup_hyprland_window_rules():
-        """Set Hyprland window rules for the popup overlay if running under Hyprland.
-
-        On Wayland, Qt clients cannot position their own toplevels — `set_position()`
-        is a silent no-op. We therefore rely on the compositor to place and pin the
-        popup. These rules use `windowrulev2` with the correct matcher syntax
-        `title:^(Recording)$`. The previous `windowrule "...,match:title Recording"`
-        form was silently rejected by hyprctl (no `match:` keyword exists), which
-        is why the popup spawned in the middle of the screen on production builds
-        even though the Python coordinate math was correct.
-
-        TODO(wayland-other-compositors): KDE and GNOME need wlr-layer-shell or
-        equivalent to dock a window — there's no portable Wayland positioning API.
-        Only Hyprland is handled here for now (the rest of the userbase is X11/win/mac).
-        """
-        if not os.environ.get('HYPRLAND_INSTANCE_SIGNATURE'):
-            return
-        import subprocess
-        # `move 50%-w/2 100%-h-100` puts the popup horizontally centered and
-        # 100 px above the bottom of the active monitor (matches the original
-        # Python intent at main.py: popup_y = _screen_y + _screen_height - 100).
-        rules = [
-            "float,title:^(Recording)$",
-            "pin,title:^(Recording)$",
-            "noinitialfocus,title:^(Recording)$",
-            "nofocus,title:^(Recording)$",
-            "noborder,title:^(Recording)$",
-            "noshadow,title:^(Recording)$",
-            "noblur,title:^(Recording)$",
-            "rounding 0,title:^(Recording)$",
-            "opacity 1.0 override 1.0 override,title:^(Recording)$",
-            "move onscreen 50%-w/2 100%-h-100,title:^(Recording)$",
-        ]
-        # Strip PyInstaller LD_LIBRARY_PATH/LD_PRELOAD before spawning
-        # hyprctl — without this, the AppImage's bundled libstdc++ shadows
-        # the system one and hyprctl fails with `GLIBCXX_3.4.32 not found`.
-        env = _system_env_for_hyprctl()
-        for rule in rules:
-            try:
-                result = subprocess.run(
-                    ['hyprctl', 'keyword', 'windowrulev2', rule],
-                    capture_output=True, timeout=2, text=True, env=env,
-                )
-                if result.returncode != 0:
-                    print(f"[WARN] hyprctl rejected rule {rule!r}: {result.stderr.strip() or result.stdout.strip()}",
-                          flush=True)
-            except (FileNotFoundError, subprocess.TimeoutExpired):
-                break
+    # Compositor integration lives in services/hyprland.py (import-light by
+    # design — safe in this pre-Qt early-boot block).
+    from services import hyprland as _hyprland
 
     try:
-        _setup_hyprland_window_rules()
+        _hyprland.setup_popup_window_rules()
     except Exception:
         pass
 
@@ -183,28 +133,19 @@ def _setup_hyprland_window_rules():
 
 
 # ============================================================================
-# Thread-safe signal emitter for cross-thread UI updates
+# Thread-safe event bridge for cross-thread UI updates — see
+# services/ui_event_bridge.py for the contract.
 # ============================================================================
-class ThreadSafeSignals(QObject):
-    """Emits signals that can be connected to slots running on the main thread."""
-    recording_started = Signal()
-    recording_stopped = Signal()
-    transcription_complete = Signal(str)
-    amplitude_changed = Signal(float)
-    # Meeting recorder state changes — payload is {state, durationMs}.
-    # Routed to the popup window so the user sees a "MEETING" indicator
-    # whenever the long-form recorder is active, distinct from PTT.
-    meeting_state_changed = Signal(dict)
-
+from services.ui_event_bridge import UiEventBridge
 
-# Global signal emitter instance (created after QApplication)
-_signals: ThreadSafeSignals = None
+# Global bridge instance (created after QApplication)
+_bridge: UiEventBridge = None
 
 
 def init_signals():
-    """Initialize the signal emitter - must be called after QApplication is created."""
-    global _signals
-    _signals = ThreadSafeSignals()
+    """Initialize the event bridge - must be called after QApplication is created."""
+    global _bridge
+    _bridge = UiEventBridge()
 
 
 # ============================================================================
@@ -382,36 +323,7 @@ def stop_active_meeting():
 _screen_height = 1080
 
 
-def _is_hyprland() -> bool:
-    return bool(os.environ.get('HYPRLAND_INSTANCE_SIGNATURE'))
-
-
-def _hypr_dispatch(*args: str) -> None:
-    """Run `hyprctl dispatch ...`; no-op if not on Hyprland or hyprctl missing.
-
-    Used at runtime to move/resize the floating popup whenever it changes
-    state (idle ↔ active), since Qt's `set_position()` is silently dropped on
-    Wayland — the compositor is the only authority on window placement.
-
-    Subprocess env is scrubbed via services.process_env.system_env() so the
-    AppImage's bundled libstdc++ doesn't shadow the system one and break
-    hyprctl with `GLIBCXX_3.4.32 not found` symbol errors.
-    """
-    if not _is_hyprland():
-        return
-    import subprocess
-    from services.process_env import system_env
-    try:
-        result = subprocess.run(
-            ['hyprctl', 'dispatch', *args],
-            capture_output=True, timeout=2, text=True, env=system_env(),
-        )
-        if result.returncode != 0:
-            log.warning("hyprctl dispatch failed",
-                        args=list(args),
-                        stderr=(result.stderr or '').strip())
-    except (FileNotFoundError, subprocess.TimeoutExpired) as e:
-        log.warning("hyprctl dispatch error", error=str(e))
+from services.hyprland import dispatch as _hypr_dispatch
 
 
 def get_active_monitor_info():
@@ -486,7 +398,7 @@ def resize_popup(width: int, height: int):
 
         # Wayland fallback: ask the compositor to re-dock the existing window.
         # `set_position()` and `set_size()` above are no-ops on Wayland for
-        # toplevels — the windowrulev2 from _setup_hyprland_window_rules() only
+        # toplevels — the windowrulev2 from hyprland.setup_popup_window_rules() only
         # fires on initial map, so we have to dispatch the move/resize here too.
         _hypr_dispatch('resizewindowpixel', f'exact {width} {height},title:^(Recording)$')
         _hypr_dispatch('movewindowpixel', f'exact {popup_x} {popup_y},title:^(Recording)$')
@@ -598,9 +510,9 @@ def _on_recording_start_slot():
     send_popup_event('popup-state', {'state': 'recording'})
 
 def on_recording_start():
-    """Called from hotkey thread - emits signal to main Qt thread."""
-    if _signals:
-        _signals.recording_started.emit()
+    """Called from hotkey thread - routes to main Qt thread via the bridge."""
+    if _bridge:
+        _bridge.emit_event("ptt-recording-start")
 
 def _on_recording_stop_slot():
     """Slot: Actual recording stop handler - runs on main thread via signal."""
@@ -609,9 +521,9 @@ def _on_recording_stop_slot():
     send_popup_event('popup-state', {'state': 'processing'})
 
 def on_recording_stop():
-    """Called from hotkey thread - emits signal to main Qt thread."""
-    if _signals:
-        _signals.recording_stopped.emit()
+    """Called from hotkey thread - routes to main Qt thread via the bridge."""
+    if _bridge:
+        _bridge.emit_event("ptt-recording-stop")
 
 
 def _on_meeting_state_slot(payload):
@@ -666,12 +578,6 @@ def _maybe_log_meeting_state(state: str, duration_ms: int) -> None:
     log.info("Meeting state", state=state, duration_ms=duration_ms)
 
 
-def on_meeting_state(name, payload):
-    """Called from MeetingsController's event_emitter on a background thread.
-    Filters to meeting-state events and hands off to the main Qt thread."""
-    if name != "meeting-state" or not _signals:
-        return
-    _signals.meeting_state_changed.emit(payload or {})
 
 def _on_transcription_complete_slot(text: str):
     """Slot: Actual transcription complete handler - runs on main thread via signal."""
@@ -681,9 +587,9 @@ def _on_transcription_complete_slot(text: str):
     send_popup_event('popup-state', {'state': 'idle'})
 
 def on_transcription_complete(text: str):
-    """Called from transcription thread - emits signal to main Qt thread."""
-    if _signals:
-        _signals.transcription_complete.emit(text)
+    """Called from transcription thread - routes to main Qt thread via the bridge."""
+    if _bridge:
+        _bridge.emit_event("ptt-transcription-complete", text)
 
 def send_main_window_event(name, detail):
     """Send event to main window using Pyloid's invoke method."""
@@ -702,9 +608,9 @@ def _on_amplitude_slot(amp: float):
     send_main_window_event('amplitude', amp)
 
 def on_amplitude(amp: float):
-    """Called from audio thread - emits signal to main Qt thread."""
-    if _signals:
-        _signals.amplitude_changed.emit(amp)
+    """Called from audio thread - routes to main Qt thread via the bridge."""
+    if _bridge:
+        _bridge.emit_event("ptt-amplitude", amp)
 
 
 def on_onboarding_complete():
@@ -776,13 +682,17 @@ def on_popup_visibility_changed(visible: bool):
 register_download_progress_callback(send_download_progress)
 register_popup_visibility_callback(on_popup_visibility_changed)
 
-# Connect thread-safe signals to their slot handlers
-# Qt.QueuedConnection ensures slots run on the main thread
-_signals.recording_started.connect(_on_recording_start_slot, Qt.QueuedConnection)
-_signals.recording_stopped.connect(_on_recording_stop_slot, Qt.QueuedConnection)
-_signals.transcription_complete.connect(_on_transcription_complete_slot, Qt.QueuedConnection)
-_signals.amplitude_changed.connect(_on_amplitude_slot, Qt.QueuedConnection)
-_signals.meeting_state_changed.connect(_on_meeting_state_slot, Qt.QueuedConnection)
+# Register main-thread handlers on the bridge (QueuedConnection inside the
+# bridge guarantees these run on the Qt main thread).
+_bridge.on("ptt-recording-start", lambda _payload: _on_recording_start_slot())
+_bridge.on("ptt-recording-stop", lambda _payload: _on_recording_stop_slot())
+_bridge.on("ptt-transcription-complete", _on_transcription_complete_slot)
+_bridge.on("ptt-amplitude", _on_amplitude_slot)
+# Meeting recorder state — drives the popup's "MEETING" pill. Other meetings
+# events (transcribe/summarize progress) have no popup handler and are
+# dropped by the bridge; the dashboard gets meeting state via its own poll
+# and push paths.
+_bridge.on("meeting-state", lambda payload: _on_meeting_state_slot(payload or {}))
 
 # Set UI callbacks
 controller.set_ui_callbacks(
@@ -792,8 +702,11 @@ def on_popup_visibility_changed(visible: bool):
     on_amplitude=on_amplitude,
 )
 
-# Route meeting recorder events to the popup (meeting-state pill).
-controller.set_meetings_event_emitter(on_meeting_state)
+# Route ALL meeting recorder events through the bridge; only handled names
+# reach the UI.
+controller.set_meetings_event_emitter(
+    lambda name, payload: _bridge.emit_event(name, payload) if _bridge else None
+)
 
 # Initialize controller (load model, start hotkey listener)
 print("[DEBUG] Initializing controller...", flush=True)
diff --git a/src-pyloid/server.py b/src-pyloid/server.py
index 6f8c5da..9e515b7 100644
--- a/src-pyloid/server.py
+++ b/src-pyloid/server.py
@@ -2,7 +2,7 @@
 from pyloid.rpc import PyloidRPC, RPCContext
 from app_controller import get_controller
 from services.logger import get_logger
-from services.model_manager import get_model_manager, CancelToken, DownloadProgress
+from services.model_manager import get_model_manager
 import threading
 
 log = get_logger("window")
@@ -16,9 +16,11 @@
 _on_popup_visibility_changed = None  # Callback when showPopup setting changes
 _send_download_progress = None  # Callback to send progress to frontend
 
-# Active download state
-_active_download_token: CancelToken = None
-_download_thread: threading.Thread = None
+
+def _emit_download_event(event_name: str, payload: dict) -> None:
+    """Forward a download event to the frontend if the bridge is registered."""
+    if _send_download_progress:
+        _send_download_progress(event_name, payload)
 
 
 def register_download_progress_callback(callback):
@@ -68,41 +70,29 @@ async def update_settings(
     holdHotkeyEnabled: Optional[bool] = None,
     toggleHotkey: Optional[str] = None,
     toggleHotkeyEnabled: Optional[bool] = None,
+    prependSpace: Optional[bool] = None,
     recordingsAutoRenameTitle: Optional[bool] = None,
 ):
     controller = get_controller()
-    kwargs = {}
-    if language is not None:
-        kwargs["language"] = language
-    if model is not None:
-        kwargs["model"] = model
-    if device is not None:
-        kwargs["device"] = device
-    if autoStart is not None:
-        kwargs["autoStart"] = autoStart
-    if retention is not None:
-        kwargs["retention"] = retention
-    if theme is not None:
-        kwargs["theme"] = theme
-    if onboardingComplete is not None:
-        kwargs["onboardingComplete"] = onboardingComplete
-    if microphone is not None:
-        kwargs["microphone"] = microphone
-    if saveAudioToHistory is not None:
-        kwargs["saveAudioToHistory"] = saveAudioToHistory
-    if showPopup is not None:
-        kwargs["showPopup"] = showPopup
-    # Hotkey settings
-    if holdHotkey is not None:
-        kwargs["holdHotkey"] = holdHotkey
-    if holdHotkeyEnabled is not None:
-        kwargs["holdHotkeyEnabled"] = holdHotkeyEnabled
-    if toggleHotkey is not None:
-        kwargs["toggleHotkey"] = toggleHotkey
-    if toggleHotkeyEnabled is not None:
-        kwargs["toggleHotkeyEnabled"] = toggleHotkeyEnabled
-    if recordingsAutoRenameTitle is not None:
-        kwargs["recordingsAutoRenameTitle"] = recordingsAutoRenameTitle
+    provided = {
+        "language": language,
+        "model": model,
+        "device": device,
+        "autoStart": autoStart,
+        "retention": retention,
+        "theme": theme,
+        "onboardingComplete": onboardingComplete,
+        "microphone": microphone,
+        "saveAudioToHistory": saveAudioToHistory,
+        "showPopup": showPopup,
+        "holdHotkey": holdHotkey,
+        "holdHotkeyEnabled": holdHotkeyEnabled,
+        "toggleHotkey": toggleHotkey,
+        "toggleHotkeyEnabled": toggleHotkeyEnabled,
+        "prependSpace": prependSpace,
+        "recordingsAutoRenameTitle": recordingsAutoRenameTitle,
+    }
+    kwargs = {key: value for key, value in provided.items() if value is not None}
 
     # Check if onboarding was already complete before this update
     old_settings = controller.get_settings()
@@ -427,7 +417,8 @@ async def get_model_info(model_name: str):
     return {
         "name": info.name,
         "sizeBytes": info.size_bytes,
-        "cached": info.cached
+        "cached": info.cached,
+        "repoId": info.repo_id
     }
 
 
@@ -470,84 +461,23 @@ async def start_model_download(model_name: str):
     Progress updates are sent via 'download-progress' event.
     Completion is signaled via 'download-complete' event.
     """
-    global _active_download_token, _download_thread
-
-    # Cancel any existing download
-    if _active_download_token and not _active_download_token.is_cancelled():
-        model_log.info("Cancelling previous download for new request")
-        _active_download_token.cancel()
-
-    # Check if already cached
-    manager = get_model_manager()
-    if manager.is_model_cached(model_name):
-        model_log.info("Model already cached", model=model_name)
-        # Send immediate completion
-        if _send_download_progress:
-            _send_download_progress("download-complete", {
-                "model": model_name,
-                "success": True,
-                "alreadyCached": True
-            })
-        return {"success": True, "alreadyCached": True}
-
-    # Create new cancel token
-    _active_download_token = CancelToken()
-
-    def do_download():
-        global _active_download_token
-
-        def on_progress(progress: DownloadProgress):
-            if _send_download_progress:
-                _send_download_progress("download-progress", {
-                    "model": progress.model_name,
-                    "percent": progress.percent,
-                    "downloadedBytes": progress.downloaded_bytes,
-                    "totalBytes": progress.total_bytes,
-                    "speedBps": progress.speed_bps,
-                    "etaSeconds": progress.eta_seconds
-                })
-
-        try:
-            success = manager.download_model(
-                model_name,
-                on_progress,
-                _active_download_token
-            )
-
-            if _send_download_progress:
-                _send_download_progress("download-complete", {
-                    "model": model_name,
-                    "success": success,
-                    "cancelled": _active_download_token.is_cancelled()
-                })
-        except Exception as e:
-            model_log.error("Download thread error", error=str(e))
-            if _send_download_progress:
-                _send_download_progress("download-complete", {
-                    "model": model_name,
-                    "success": False,
-                    "error": str(e)
-                })
-
-    # Start download in background thread
-    _download_thread = threading.Thread(target=do_download, daemon=True)
-    _download_thread.start()
-
-    model_log.info("Started model download", model=model_name)
-    return {"success": True, "started": True}
+    return get_model_manager().start_download(model_name, _emit_download_event)
 
 
 @server.method()
 async def cancel_model_download():
     """Cancel the current model download if any."""
-    global _active_download_token
+    return get_model_manager().cancel_download()
+
 
-    if _active_download_token and not _active_download_token.is_cancelled():
-        model_log.info("Cancelling model download")
-        _active_download_token.cancel()
-        return {"success": True, "cancelled": True}
+@server.method()
+async def get_download_status():
+    """Snapshot of the active model download, if any.
 
-    return {"success": True, "cancelled": False}
+    Lets a remounted UI re-attach to an in-flight download instead of
+    losing it when the settings page unmounts.
+    """
+    return get_model_manager().get_download_status()
 
 
 @server.method()
diff --git a/src-pyloid/services/database.py b/src-pyloid/services/database.py
index 7438116..524619a 100644
--- a/src-pyloid/services/database.py
+++ b/src-pyloid/services/database.py
@@ -1,12 +1,9 @@
-import json
 import sqlite3
 from pathlib import Path
 from datetime import datetime, timedelta
 from typing import Optional
 from services.logger import debug
-
-
-_RECORDING_UPDATABLE_FIELDS = frozenset({"title", "summary", "notes", "tags", "language"})
+from services.recording.repository import RecordingsRepository
 
 
 class DatabaseService:
@@ -18,6 +15,10 @@ def __init__(self, db_path: Optional[Path] = None):
 
         self.db_path = db_path
         self._init_db()
+        # Recording persistence lives in its own domain module (see
+        # services/recording/repository.py and CONTEXT.md "Recording").
+        # The delegating methods below stay for backward compatibility.
+        self.recordings = RecordingsRepository(self)
 
     def _get_connection(self) -> sqlite3.Connection:
         # timeout=5.0 + busy_timeout=5000 means SQLite returns SQLITE_BUSY
@@ -424,44 +425,16 @@ def _calculate_streak(self, days: list) -> int:
         return streak
 
     # ------------------------------------------------------------------ Recordings (Meetings)
+    #
+    # Recording persistence lives in RecordingsRepository
+    # (services/recording/repository.py). These thin delegates remain so
+    # existing callers (server.py, tests) keep working unchanged.
 
     def create_recording(self, title: str, sources: list[str]) -> int:
-        now = datetime.now().isoformat()
-        conn = self._get_connection()
-        try:
-            cursor = conn.cursor()
-            cursor.execute(
-                """INSERT INTO recordings (title, sources, created_at, updated_at)
-                   VALUES (?, ?, ?, ?)""",
-                (title, json.dumps(sources), now, now),
-            )
-            rid = cursor.lastrowid
-            conn.commit()
-            return rid
-        finally:
-            conn.close()
+        return self.recordings.create_recording(title, sources)
 
     def get_recording(self, recording_id: int, include_segments: bool = False) -> Optional[dict]:
-        conn = self._get_connection()
-        try:
-            row = conn.execute(
-                "SELECT * FROM recordings WHERE id = ?", (recording_id,)
-            ).fetchone()
-            if row is None:
-                return None
-            rec = self._row_to_recording(row)
-            if include_segments:
-                seg_rows = conn.execute(
-                    """SELECT id, recording_id, start_ms, end_ms, text
-                       FROM recording_segments
-                       WHERE recording_id = ?
-                       ORDER BY start_ms ASC, id ASC""",
-                    (recording_id,),
-                ).fetchall()
-                rec["segments"] = [dict(r) for r in seg_rows]
-            return rec
-        finally:
-            conn.close()
+        return self.recordings.get_recording(recording_id, include_segments=include_segments)
 
     def list_recordings(
         self,
@@ -469,44 +442,10 @@ def list_recordings(
         offset: int = 0,
         search: Optional[str] = None,
     ) -> list[dict]:
-        conn = self._get_connection()
-        try:
-            query = "SELECT * FROM recordings"
-            params: list = []
-            if search:
-                query += " WHERE title LIKE ?"
-                params.append(f"%{search}%")
-            query += " ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?"
-            params.extend([limit, offset])
-            rows = conn.execute(query, params).fetchall()
-            return [self._row_to_recording(r) for r in rows]
-        finally:
-            conn.close()
+        return self.recordings.list_recordings(limit=limit, offset=offset, search=search)
 
     def update_recording(self, recording_id: int, **fields) -> None:
-        unknown = set(fields) - _RECORDING_UPDATABLE_FIELDS
-        if unknown:
-            raise ValueError(f"unknown recording fields: {sorted(unknown)}")
-        if not fields:
-            return
-        sets, params = [], []
-        for name, value in fields.items():
-            if name == "tags":
-                value = json.dumps(value or [])
-            sets.append(f"{name} = ?")
-            params.append(value)
-        sets.append("updated_at = ?")
-        params.append(datetime.now().isoformat())
-        params.append(recording_id)
-
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.update_recording(recording_id, **fields)
 
     def set_recording_audio(
         self,
@@ -517,33 +456,12 @@ def set_recording_audio(
         sample_rate: Optional[int],
         channels: Optional[int],
     ) -> None:
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                """UPDATE recordings
-                   SET audio_relpath = ?, audio_duration_ms = ?, audio_size_bytes = ?,
-                       audio_sample_rate = ?, audio_channels = ?, updated_at = ?
-                   WHERE id = ?""",
-                (
-                    audio_relpath, duration_ms, size_bytes,
-                    sample_rate, channels, datetime.now().isoformat(),
-                    recording_id,
-                ),
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.set_recording_audio(
+            recording_id, audio_relpath, duration_ms, size_bytes, sample_rate, channels
+        )
 
     def set_recording_recorder_state(self, recording_id: int, state: Optional[str]) -> None:
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                "UPDATE recordings SET recorder_state = ?, updated_at = ? WHERE id = ?",
-                (state, datetime.now().isoformat(), recording_id),
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.set_recording_recorder_state(recording_id, state)
 
     def update_transcript_status(
         self,
@@ -552,23 +470,9 @@ def update_transcript_status(
         progress: Optional[float] = None,
         error: Optional[str] = None,
     ) -> None:
-        sets = ["transcript_status = ?", "updated_at = ?"]
-        params: list = [status, datetime.now().isoformat()]
-        if progress is not None:
-            sets.insert(1, "transcript_progress = ?")
-            params.insert(1, progress)
-        if error is not None:
-            sets.insert(-1, "transcript_error = ?")
-            params.insert(-1, error)
-        params.append(recording_id)
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.update_transcript_status(
+            recording_id, status, progress=progress, error=error
+        )
 
     def update_summary_status(
         self,
@@ -578,26 +482,9 @@ def update_summary_status(
         error: Optional[str] = None,
         provider: Optional[str] = None,
     ) -> None:
-        sets = ["summary_status = ?", "updated_at = ?"]
-        params: list = [status, datetime.now().isoformat()]
-        if progress is not None:
-            sets.insert(1, "summary_progress = ?")
-            params.insert(1, progress)
-        if error is not None:
-            sets.insert(-1, "summary_error = ?")
-            params.insert(-1, error)
-        if provider is not None:
-            sets.insert(-1, "summary_provider = ?")
-            params.insert(-1, provider)
-        params.append(recording_id)
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.update_summary_status(
+            recording_id, status, progress=progress, error=error, provider=provider
+        )
 
     def set_recording_transcript(
         self,
@@ -606,76 +493,18 @@ def set_recording_transcript(
         language: Optional[str] = None,
         model: Optional[str] = None,
     ) -> None:
-        """Persist the final transcript text. Segments go via replace_recording_segments.
-
-        `model` is the whisper model name that produced the transcript (e.g.
-        'tiny', 'large-v3'). Optional and backward-compatible — existing callers
-        that don't pass it leave the column NULL or unchanged on re-transcribe.
-        """
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                """UPDATE recordings
-                   SET transcript = ?,
-                       language = COALESCE(?, language),
-                       transcript_model = COALESCE(?, transcript_model),
-                       updated_at = ?
-                   WHERE id = ?""",
-                (transcript, language, model, datetime.now().isoformat(), recording_id),
-            )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.set_recording_transcript(
+            recording_id, transcript, language=language, model=model
+        )
 
     def replace_recording_segments(self, recording_id: int, segments: list[dict]) -> None:
-        conn = self._get_connection()
-        try:
-            conn.execute(
-                "DELETE FROM recording_segments WHERE recording_id = ?", (recording_id,)
-            )
-            if segments:
-                conn.executemany(
-                    """INSERT INTO recording_segments (recording_id, start_ms, end_ms, text)
-                       VALUES (?, ?, ?, ?)""",
-                    [
-                        (recording_id, int(s["start_ms"]), int(s["end_ms"]), str(s["text"]))
-                        for s in segments
-                    ],
-                )
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.replace_recording_segments(recording_id, segments)
 
     def delete_recording(self, recording_id: int) -> None:
-        # Capture the audio path so the caller can delete the file off disk.
-        rec = self.get_recording(recording_id)
-        if rec and rec.get("audio_relpath"):
-            self._delete_audio_file(rec["audio_relpath"])
-        conn = self._get_connection()
-        try:
-            conn.execute("DELETE FROM recordings WHERE id = ?", (recording_id,))
-            conn.commit()
-        finally:
-            conn.close()
+        return self.recordings.delete_recording(recording_id)
 
     def list_unfinished_recordings(self) -> list[dict]:
-        """Recordings that were left mid-flight (used by crash-recovery on startup)."""
-        conn = self._get_connection()
-        try:
-            rows = conn.execute(
-                "SELECT * FROM recordings WHERE recorder_state IS NOT NULL "
-                "ORDER BY created_at ASC"
-            ).fetchall()
-            return [self._row_to_recording(r) for r in rows]
-        finally:
-            conn.close()
-
-    @staticmethod
-    def _row_to_recording(row: sqlite3.Row) -> dict:
-        rec = dict(row)
-        rec["sources"] = json.loads(rec.get("sources") or "[]")
-        rec["tags"] = json.loads(rec.get("tags") or "[]")
-        return rec
+        return self.recordings.list_unfinished_recordings()
 
     def _delete_audio_file(self, relpath: str) -> None:
         """Delete an audio file, ignoring missing files."""
diff --git a/src-pyloid/services/dictation.py b/src-pyloid/services/dictation.py
new file mode 100644
index 0000000..4e1274e
--- /dev/null
+++ b/src-pyloid/services/dictation.py
@@ -0,0 +1,159 @@
+"""DictationPipeline — the release-to-paste sequence for one push-to-talk
+dictation (the History entity in CONTEXT.md terms).
+
+Owns everything that happens after the hotkey is released and audio is in
+hand: wait for the whisper model, transcribe, paste at the cursor, persist to
+history (optionally with the audio attachment). UI callbacks stay in
+AppController — `run()` returns the pasted text ("" when nothing usable) and
+raises on transcription errors, so the caller decides how to surface both.
+
+Extracted from AppController so this sequence is testable with fakes instead
+of mocking seven services through the hotkey path.
+"""
+
+import time
+import wave
+from pathlib import Path
+from typing import TypedDict
+
+import numpy as np
+
+from services.logger import info, warning, error
+
+
+class AudioAttachmentMeta(TypedDict):
+    audio_relpath: str
+    audio_duration_ms: int
+    audio_size_bytes: int
+    audio_mime: str
+
+
+class DictationPipeline:
+    def __init__(
+        self,
+        *,
+        settings_service,
+        transcription_service,
+        clipboard_service,
+        db,
+        audio_service,
+        is_model_loaded,
+        is_model_loading,
+    ):
+        self.settings_service = settings_service
+        self.transcription_service = transcription_service
+        self.clipboard_service = clipboard_service
+        self.db = db
+        self.audio_service = audio_service
+        self._is_model_loaded = is_model_loaded
+        self._is_model_loading = is_model_loading
+
+    def wait_for_model(self, timeout_s: float = 30, poll_s: float = 1.0) -> str:
+        """Block until the whisper model is usable.
+
+        Returns "ready", "absent" (not loaded and no load in flight), or
+        "timeout"."""
+        waited = 0.0
+        while not self._is_model_loaded() and waited < timeout_s:
+            if not self._is_model_loading():
+                return "absent"
+            info(f"Waiting for model to load... ({waited:g}s)")
+            time.sleep(poll_s)
+            waited += poll_s
+        return "ready" if self._is_model_loaded() else "timeout"
+
+    def run(self, audio: np.ndarray) -> str:
+        """Transcribe `audio`, paste the text at the cursor, save history.
+
+        Blocking — callers run it on a worker thread. Returns the pasted text,
+        or "" when nothing usable came out (model unavailable / empty
+        transcript). Raises on transcription/paste errors."""
+        readiness = self.wait_for_model()
+        if readiness == "absent":
+            warning("Model not loaded and not loading, skipping transcription")
+            return ""
+        if readiness == "timeout":
+            error("Model load timeout, skipping transcription")
+            return ""
+
+        settings = self.settings_service.get_settings()
+        info(f"Transcribing with language: {settings.language}")
+
+        text = self.transcription_service.transcribe(
+            audio,
+            language=settings.language,
+        )
+        info(f"Transcription result: '{text}'")
+
+        if not text:
+            warning("No text transcribed (empty result)")
+            return ""
+
+        # Prepend space if enabled (useful for continuous dictation)
+        if settings.prepend_space:
+            text = " " + text
+
+        info("Pasting text at cursor...")
+        self.clipboard_service.paste_at_cursor(text)
+
+        history_id = self.db.add_history(text)
+
+        if settings.save_audio_to_history:
+            import sqlite3
+            try:
+                audio_meta = self.save_audio_attachment(history_id, audio)
+                self.db.update_history_audio(
+                    history_id,
+                    audio_relpath=audio_meta["audio_relpath"],
+                    audio_duration_ms=audio_meta["audio_duration_ms"],
+                    audio_size_bytes=audio_meta["audio_size_bytes"],
+                    audio_mime=audio_meta["audio_mime"],
+                )
+                info(f"Saved audio attachment for history {history_id}")
+            except (OSError, wave.Error, sqlite3.Error, ValueError) as exc:
+                warning(f"Failed to save audio attachment: {exc}")
+
+        return text
+
+    def save_audio_attachment(self, history_id: int, audio: np.ndarray) -> AudioAttachmentMeta:
+        """Persist recorded audio as WAV and return metadata for DB update."""
+        # Ensure audio directory exists
+        audio_dir = self.db.db_path.parent / "audio"
+        audio_dir.mkdir(parents=True, exist_ok=True)
+
+        relpath = Path("audio") / f"history_{history_id}.wav"
+        output_path = self.db.db_path.parent / relpath
+        tmp_path = output_path.with_suffix(".wav.tmp")
+
+        # Normalize audio into flat int16 PCM
+        audio_array = np.asarray(audio)
+        if audio_array.ndim > 1:
+            audio_array = audio_array.reshape(-1)
+
+        if np.issubdtype(audio_array.dtype, np.floating):
+            audio_clipped = np.clip(audio_array, -1.0, 1.0)
+            audio_int16 = (audio_clipped * 32767).astype(np.int16)
+        elif audio_array.dtype == np.int16:
+            audio_int16 = audio_array
+        else:
+            # Fallback: clip to int16 range
+            audio_clipped = np.clip(audio_array, -32768, 32767)
+            audio_int16 = audio_clipped.astype(np.int16)
+
+        with wave.open(str(tmp_path), "wb") as wf:
+            wf.setnchannels(self.audio_service.CHANNELS)
+            wf.setsampwidth(2)  # 16-bit PCM
+            wf.setframerate(self.audio_service.SAMPLE_RATE)
+            wf.writeframes(audio_int16.tobytes())
+
+        tmp_path.replace(output_path)
+
+        duration_ms = int((len(audio_int16) / float(self.audio_service.SAMPLE_RATE)) * 1000)
+        size_bytes = output_path.stat().st_size
+
+        return {
+            "audio_relpath": relpath.as_posix(),
+            "audio_duration_ms": duration_ms,
+            "audio_size_bytes": size_bytes,
+            "audio_mime": "audio/wav",
+        }
diff --git a/src-pyloid/services/hyprland.py b/src-pyloid/services/hyprland.py
new file mode 100644
index 0000000..3ab898b
--- /dev/null
+++ b/src-pyloid/services/hyprland.py
@@ -0,0 +1,97 @@
+"""Hyprland compositor integration for the popup overlay.
+
+On Wayland, Qt clients cannot position their own toplevels — `set_position()`
+is a silent no-op. The compositor is the only authority on window placement,
+so when running under Hyprland we (a) install windowrulev2 rules that float /
+pin / place the popup, and (b) move/resize it at runtime via `hyprctl
+dispatch`.
+
+All hyprctl subprocesses run with a scrubbed env (services.process_env.
+system_env) — the AppImage's bundled libstdc++ otherwise shadows the system
+one and hyprctl fails with `GLIBCXX_3.4.32 not found`.
+
+TODO(wayland-other-compositors): KDE and GNOME need wlr-layer-shell or
+equivalent to dock a window — there's no portable Wayland positioning API.
+Only Hyprland is handled here for now (the rest of the userbase is
+X11/win/mac).
+
+This module is import-light on purpose: `setup_popup_window_rules()` runs in
+main.py's early-boot block before Qt/env configuration, so heavyweight
+imports (logger, subprocess) stay inside the functions.
+"""
+
+import os
+
+
+def is_hyprland() -> bool:
+    return bool(os.environ.get('HYPRLAND_INSTANCE_SIGNATURE'))
+
+
+def setup_popup_window_rules() -> None:
+    """Install Hyprland window rules for the popup overlay. Safe no-op when
+    not under Hyprland or when hyprctl is unavailable.
+
+    Rules use `windowrulev2` with the matcher syntax `title:^(Recording)$`.
+    The previous `windowrule "...,match:title Recording"` form was silently
+    rejected by hyprctl (no `match:` keyword exists), which is why the popup
+    spawned in the middle of the screen on production builds even though the
+    Python coordinate math was correct.
+
+    Runs pre-logging — warnings go to stdout via print().
+    """
+    if not is_hyprland():
+        return
+    import subprocess
+    from services.process_env import system_env
+    # `move 50%-w/2 100%-h-100` puts the popup horizontally centered and
+    # 100 px above the bottom of the active monitor (matches the original
+    # Python intent: popup_y = _screen_y + _screen_height - 100).
+    rules = [
+        "float,title:^(Recording)$",
+        "pin,title:^(Recording)$",
+        "noinitialfocus,title:^(Recording)$",
+        "nofocus,title:^(Recording)$",
+        "noborder,title:^(Recording)$",
+        "noshadow,title:^(Recording)$",
+        "noblur,title:^(Recording)$",
+        "rounding 0,title:^(Recording)$",
+        "opacity 1.0 override 1.0 override,title:^(Recording)$",
+        "move onscreen 50%-w/2 100%-h-100,title:^(Recording)$",
+    ]
+    env = system_env()
+    for rule in rules:
+        try:
+            result = subprocess.run(
+                ['hyprctl', 'keyword', 'windowrulev2', rule],
+                capture_output=True, timeout=2, text=True, env=env,
+            )
+            if result.returncode != 0:
+                print(f"[WARN] hyprctl rejected rule {rule!r}: {result.stderr.strip() or result.stdout.strip()}",
+                      flush=True)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            break
+
+
+def dispatch(*args: str) -> None:
+    """Run `hyprctl dispatch ...`; no-op if not on Hyprland or hyprctl missing.
+
+    Used at runtime to move/resize the floating popup whenever it changes
+    state (idle ↔ active).
+    """
+    if not is_hyprland():
+        return
+    import subprocess
+    from services.logger import get_logger
+    from services.process_env import system_env
+    log = get_logger("window")
+    try:
+        result = subprocess.run(
+            ['hyprctl', 'dispatch', *args],
+            capture_output=True, timeout=2, text=True, env=system_env(),
+        )
+        if result.returncode != 0:
+            log.warning("hyprctl dispatch failed",
+                        args=list(args),
+                        stderr=(result.stderr or '').strip())
+    except (FileNotFoundError, subprocess.TimeoutExpired) as e:
+        log.warning("hyprctl dispatch error", error=str(e))
diff --git a/src-pyloid/services/model_catalog.py b/src-pyloid/services/model_catalog.py
new file mode 100644
index 0000000..a98da86
--- /dev/null
+++ b/src-pyloid/services/model_catalog.py
@@ -0,0 +1,77 @@
+"""
+Single source of truth for the Whisper model catalog.
+
+Every backend module that needs to know which models exist, how big they
+are, or which HuggingFace repo they live in imports from here. Do not
+re-declare model names/repos anywhere else (that's how the catalog drifted
+across model_manager, settings, and transcription before this module).
+
+The frontend gets repo IDs over RPC (get_model_info -> repoId) rather than
+keeping its own copy of the mapping.
+"""
+
+# All models supported by faster-whisper with approximate download sizes (bytes)
+# Sizes are estimates based on the CTranslate2 converted models.
+# Order matters: it is the display order used by the settings UI
+# (multilingual first, then English-only, then distilled).
+MODEL_SIZES = {
+    # Standard models (multilingual)
+    "tiny": 75_000_000,           # ~75 MB
+    "base": 145_000_000,          # ~145 MB
+    "small": 466_000_000,         # ~466 MB
+    "medium": 1_530_000_000,      # ~1.53 GB
+    "large-v1": 3_090_000_000,    # ~3.09 GB
+    "large-v2": 3_090_000_000,    # ~3.09 GB
+    "large-v3": 3_090_000_000,    # ~3.09 GB
+    "turbo": 1_620_000_000,       # ~1.62 GB (large-v3-turbo)
+    # English-only models (slightly smaller, optimized for English)
+    "tiny.en": 75_000_000,        # ~75 MB
+    "base.en": 145_000_000,       # ~145 MB
+    "small.en": 466_000_000,      # ~466 MB
+    "medium.en": 1_530_000_000,   # ~1.53 GB
+    # Distilled models (faster inference, English-only)
+    "distil-small.en": 332_000_000,    # ~332 MB
+    "distil-medium.en": 756_000_000,   # ~756 MB
+    "distil-large-v2": 1_510_000_000,  # ~1.51 GB
+    "distil-large-v3": 1_510_000_000,  # ~1.51 GB
+}
+
+# Model name to HuggingFace repo ID mapping
+# Based on faster-whisper's internal mapping
+MODEL_REPOS = {
+    # Standard multilingual models
+    "tiny": "Systran/faster-whisper-tiny",
+    "base": "Systran/faster-whisper-base",
+    "small": "Systran/faster-whisper-small",
+    "medium": "Systran/faster-whisper-medium",
+    "large-v1": "Systran/faster-whisper-large-v1",
+    "large-v2": "Systran/faster-whisper-large-v2",
+    "large-v3": "Systran/faster-whisper-large-v3",
+    "turbo": "mobiuslabsgmbh/faster-whisper-large-v3-turbo",
+    # English-only models
+    "tiny.en": "Systran/faster-whisper-tiny.en",
+    "base.en": "Systran/faster-whisper-base.en",
+    "small.en": "Systran/faster-whisper-small.en",
+    "medium.en": "Systran/faster-whisper-medium.en",
+    # Distilled models
+    "distil-small.en": "Systran/faster-distil-whisper-small.en",
+    "distil-medium.en": "Systran/faster-distil-whisper-medium.en",
+    "distil-large-v2": "Systran/faster-distil-whisper-large-v2",
+    "distil-large-v3": "Systran/faster-distil-whisper-large-v3",
+}
+
+# Ordered list of model names (the settings dropdown / picker order)
+WHISPER_MODELS = list(MODEL_SIZES.keys())
+
+
+def get_repo_id(model_name: str) -> str:
+    """Get the HuggingFace repo ID for a model name."""
+    return MODEL_REPOS.get(model_name, f"Systran/faster-whisper-{model_name}")
+
+
+def hf_cache_folder_name(repo_id: str) -> str:
+    """HuggingFace hub cache folder name for a repo.
+
+    e.g. "Systran/faster-whisper-tiny" -> "models--Systran--faster-whisper-tiny"
+    """
+    return "models--" + repo_id.replace("/", "--")
diff --git a/src-pyloid/services/model_manager.py b/src-pyloid/services/model_manager.py
index d70902a..0cc8eaf 100644
--- a/src-pyloid/services/model_manager.py
+++ b/src-pyloid/services/model_manager.py
@@ -5,11 +5,15 @@
 - is_model_cached(): Check if model exists in cache
 - get_model_info(): Get model metadata
 - download_model(): Download with progress and cancellation support
-- load_model(): Load already-downloaded model
-- ensure_model_ready(): Download if needed + load
+- start_download() / cancel_download() / get_download_status(): single-flight
+  background download session with event emission (the RPC surface)
 - get_available_models(): Get list of all supported models
+- delete_model() / clear_cache(): Cache management
+
+Model loading lives in TranscriptionService (the only load path — it resolves
+the user's device preference). The model catalog (names, sizes, repos) lives
+in services.model_catalog.
 
-Uses faster_whisper's download_model() which handles HuggingFace Hub internally.
 Cache location: ~/.cache/huggingface/hub/
 """
 from dataclasses import dataclass
@@ -21,64 +25,16 @@
 import io
 
 from services.logger import get_logger
+from services.model_catalog import (
+    MODEL_SIZES,
+    MODEL_REPOS,
+    get_repo_id as _get_repo_id,
+    hf_cache_folder_name,
+)
 
 log = get_logger("model")
 
 
-# All models supported by faster-whisper with approximate download sizes (bytes)
-# Sizes are estimates based on the CTranslate2 converted models
-MODEL_SIZES = {
-    # Standard models (multilingual)
-    "tiny": 75_000_000,           # ~75 MB
-    "base": 145_000_000,          # ~145 MB
-    "small": 466_000_000,         # ~466 MB
-    "medium": 1_530_000_000,      # ~1.53 GB
-    "large-v1": 3_090_000_000,    # ~3.09 GB
-    "large-v2": 3_090_000_000,    # ~3.09 GB
-    "large-v3": 3_090_000_000,    # ~3.09 GB
-    "turbo": 1_620_000_000,       # ~1.62 GB (large-v3-turbo)
-    # English-only models (slightly smaller, optimized for English)
-    "tiny.en": 75_000_000,        # ~75 MB
-    "base.en": 145_000_000,       # ~145 MB
-    "small.en": 466_000_000,      # ~466 MB
-    "medium.en": 1_530_000_000,   # ~1.53 GB
-    # Distilled models (faster inference, English-only)
-    "distil-small.en": 332_000_000,    # ~332 MB
-    "distil-medium.en": 756_000_000,   # ~756 MB
-    "distil-large-v2": 1_510_000_000,  # ~1.51 GB
-    "distil-large-v3": 1_510_000_000,  # ~1.51 GB
-}
-
-# Model name to HuggingFace repo ID mapping
-# Based on faster-whisper's internal mapping
-MODEL_REPOS = {
-    # Standard multilingual models
-    "tiny": "Systran/faster-whisper-tiny",
-    "base": "Systran/faster-whisper-base",
-    "small": "Systran/faster-whisper-small",
-    "medium": "Systran/faster-whisper-medium",
-    "large-v1": "Systran/faster-whisper-large-v1",
-    "large-v2": "Systran/faster-whisper-large-v2",
-    "large-v3": "Systran/faster-whisper-large-v3",
-    "turbo": "mobiuslabsgmbh/faster-whisper-large-v3-turbo",
-    # English-only models
-    "tiny.en": "Systran/faster-whisper-tiny.en",
-    "base.en": "Systran/faster-whisper-base.en",
-    "small.en": "Systran/faster-whisper-small.en",
-    "medium.en": "Systran/faster-whisper-medium.en",
-    # Distilled models
-    "distil-small.en": "Systran/faster-distil-whisper-small.en",
-    "distil-medium.en": "Systran/faster-distil-whisper-medium.en",
-    "distil-large-v2": "Systran/faster-distil-whisper-large-v2",
-    "distil-large-v3": "Systran/faster-distil-whisper-large-v3",
-}
-
-
-def _get_repo_id(model_name: str) -> str:
-    """Get the HuggingFace repo ID for a model name."""
-    return MODEL_REPOS.get(model_name, f"Systran/faster-whisper-{model_name}")
-
-
 @dataclass
 class CancelToken:
     """Token for cancelling long-running operations."""
@@ -99,6 +55,7 @@ class ModelInfo:
     name: str
     size_bytes: int
     cached: bool
+    repo_id: str = ""
 
 
 @dataclass
@@ -196,6 +153,11 @@ class ModelManager:
 
     def __init__(self):
         self._download_lock = threading.Lock()
+        # Single-flight download session state. Guarded by _session_lock;
+        # only one background download runs at a time and its progress is
+        # queryable so the UI can re-attach after navigating away.
+        self._session_lock = threading.Lock()
+        self._session: Optional[dict] = None
 
     def get_available_models(self) -> list:
         """Get list of all supported model names."""
@@ -248,7 +210,8 @@ def get_model_info(self, model_name: str) -> ModelInfo:
         return ModelInfo(
             name=model_name,
             size_bytes=size_bytes,
-            cached=cached
+            cached=cached,
+            repo_id=_get_repo_id(model_name)
         )
 
     def download_model(
@@ -479,73 +442,117 @@ def download_thread():
             log.error("Model download failed", model=model_name, error=result["error"])
             return False
 
-    def load_model(self, model_name: str):
-        """
-        Load an already-downloaded model.
-
-        Args:
-            model_name: Name of the model to load
-
-        Returns:
-            WhisperModel instance
-
-        Raises:
-            RuntimeError: If model is not cached
-        """
-        if not self.is_model_cached(model_name):
-            raise RuntimeError(f"Model '{model_name}' is not cached. Download it first.")
-
-        from faster_whisper import WhisperModel
-
-        # Use repo_id for loading to ensure correct model is loaded
-        repo_id = _get_repo_id(model_name)
-        log.info("Loading model", model=model_name, repo_id=repo_id)
-        model = WhisperModel(
-            repo_id,
-            device="cpu",
-            compute_type="int8"
-        )
-        log.info("Model loaded successfully", model=model_name)
+    # ------------------------------------------------------------------
+    # Background download session (the RPC-facing surface)
+    #
+    # One download at a time. Starting a new download cancels the previous
+    # one. Progress and completion are pushed through the emit callback as
+    # ("download-progress", payload) / ("download-complete", payload) and the
+    # latest progress snapshot is queryable via get_download_status() so a
+    # remounted UI can re-attach to an in-flight download.
+    # ------------------------------------------------------------------
 
-        return model
-
-    def ensure_model_ready(
-        self,
-        model_name: str,
-        on_progress: Optional[Callable[[DownloadProgress], None]] = None,
-        cancel_token: Optional[CancelToken] = None
-    ):
-        """
-        Ensure a model is downloaded and load it.
-
-        Downloads the model if not cached, then loads it.
+    def start_download(self, model_name: str, emit: Callable[[str, dict], None]) -> dict:
+        """Start a background download session for a model.
 
         Args:
-            model_name: Name of the model
-            on_progress: Optional callback for download progress
-            cancel_token: Optional token to cancel the download
+            model_name: Name of the model to download
+            emit: Callback(event_name, payload) used for progress/completion
+                  events. Payload keys are camelCase (the frontend contract).
 
         Returns:
-            WhisperModel instance
-
-        Raises:
-            RuntimeError: If download fails or is cancelled
+            dict: {"success": True, "alreadyCached": True} if nothing to do,
+                  {"success": True, "started": True} if a session started.
         """
-        if not self.is_model_cached(model_name):
-            log.info("Model not cached, downloading", model=model_name)
-
-            # Set up defaults if not provided
-            if on_progress is None:
-                on_progress = lambda p: None
-            if cancel_token is None:
-                cancel_token = CancelToken()
-
-            success = self.download_model(model_name, on_progress, cancel_token)
-
-            if not success:
-                raise RuntimeError(f"Failed to download model '{model_name}'")
+        with self._session_lock:
+            # Cancel any in-flight session before starting a new one
+            if self._session is not None and not self._session["done"]:
+                log.info("Cancelling previous download for new request")
+                self._session["token"].cancel()
+
+            if self.is_model_cached(model_name):
+                log.info("Model already cached", model=model_name)
+                emit("download-complete", {
+                    "model": model_name,
+                    "success": True,
+                    "alreadyCached": True
+                })
+                return {"success": True, "alreadyCached": True}
+
+            token = CancelToken()
+            session = {
+                "model": model_name,
+                "token": token,
+                "done": False,
+                "progress": None,  # last DownloadProgress payload (camelCase)
+            }
 
-        return self.load_model(model_name)
+            def on_progress(progress: DownloadProgress):
+                payload = {
+                    "model": progress.model_name,
+                    "percent": progress.percent,
+                    "downloadedBytes": progress.downloaded_bytes,
+                    "totalBytes": progress.total_bytes,
+                    "speedBps": progress.speed_bps,
+                    "etaSeconds": progress.eta_seconds
+                }
+                session["progress"] = payload
+                emit("download-progress", payload)
+
+            def run():
+                try:
+                    success = self.download_model(model_name, on_progress, token)
+                    emit("download-complete", {
+                        "model": model_name,
+                        "success": success,
+                        "cancelled": token.is_cancelled()
+                    })
+                except Exception as e:
+                    log.error("Download thread error", error=str(e))
+                    emit("download-complete", {
+                        "model": model_name,
+                        "success": False,
+                        "error": str(e)
+                    })
+                finally:
+                    session["done"] = True
+
+            session["thread"] = threading.Thread(target=run, daemon=True)
+            self._session = session
+            session["thread"].start()
+
+        log.info("Started model download", model=model_name)
+        return {"success": True, "started": True}
+
+    def cancel_download(self) -> dict:
+        """Cancel the active download session, if any."""
+        with self._session_lock:
+            session = self._session
+            if session is not None and not session["done"] and not session["token"].is_cancelled():
+                log.info("Cancelling model download", model=session["model"])
+                session["token"].cancel()
+                return {"success": True, "cancelled": True}
+        return {"success": True, "cancelled": False}
+
+    def get_download_status(self) -> dict:
+        """Snapshot of the active download session (camelCase payload).
+
+        Returns {"active": False} when no download is running; otherwise the
+        last progress payload plus "active": True so the UI can re-attach.
+        """
+        with self._session_lock:
+            session = self._session
+            if session is None or session["done"] or session["token"].is_cancelled():
+                return {"active": False, "model": None}
+            progress = session["progress"] or {
+                "model": session["model"],
+                "percent": 0,
+                "downloadedBytes": 0,
+                "totalBytes": MODEL_SIZES.get(session["model"], 0),
+                "speedBps": 0,
+                "etaSeconds": 0,
+            }
+            return {"active": True, **progress}
 
     def clear_cache(self) -> dict:
         """
@@ -581,10 +588,7 @@ def clear_cache(self) -> dict:
             # Find and delete all faster-whisper model directories
             # HuggingFace stores models as: models--{org}--{repo}
             for model_name, repo_id in MODEL_REPOS.items():
-                # Convert repo_id to HuggingFace cache folder name
-                # e.g., "Systran/faster-whisper-tiny" -> "models--Systran--faster-whisper-tiny"
-                cache_folder_name = f"models--{repo_id.replace('/', '--')}"
-                model_cache_path = cache_dir / cache_folder_name
+                model_cache_path = cache_dir / hf_cache_folder_name(repo_id)
 
                 if model_cache_path.exists():
                     # Calculate size before deleting
@@ -642,8 +646,7 @@ def delete_model(self, model_name: str) -> dict:
 
         try:
             cache_dir = Path.home() / ".cache" / "huggingface" / "hub"
-            cache_folder_name = f"models--{repo_id.replace('/', '--')}"
-            model_cache_path = cache_dir / cache_folder_name
+            model_cache_path = cache_dir / hf_cache_folder_name(repo_id)
 
             if not model_cache_path.exists():
                 log.info("Model not cached, nothing to delete", model=model_name)
diff --git a/src-pyloid/services/recording/controller.py b/src-pyloid/services/recording/controller.py
index 443265d..993e9bc 100644
--- a/src-pyloid/services/recording/controller.py
+++ b/src-pyloid/services/recording/controller.py
@@ -22,18 +22,13 @@
 
 from services.database import DatabaseService
 from services.logger import get_logger
-from services.recording.audio_source import ParecAudioSource, SoundDeviceAudioSource
+from services.recording.audio_source import SoundDeviceAudioSource
 from services.recording.export import UnknownExportFormatError, export_recording
 from services.recording.llm import (
     LLMConnectionError,
     OpenAICompatibleProvider,
 )
-from services.recording.loopback_linux import _filter_linux_loopback
-from services.recording.loopback_pulse import (
-    PULSE_ID_BASE,
-    list_pulse_monitor_sources,
-)
-from services.recording.loopback_windows import _filter_wasapi_loopback
+from services.recording.loopback import LoopbackDiscovery
 from services.recording.recorder import (
     NoAudioSourcesError,
     RecorderAlreadyStartedError,
@@ -72,6 +67,9 @@
 class _Job:
     recording_id: int
     cancel_token: CancelToken
+    # Per-job transcription overrides (model/device/language) set by the
+    # Re-transcribe modal. None means "use global settings".
+    overrides: Optional[dict] = None
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -175,11 +173,11 @@ def __init__(self, name: str, runner: Callable[[_Job], None]) -> None:
         self._thread = threading.Thread(target=self._loop, daemon=True, name=f"meetings-{name}")
         self._thread.start()
 
-    def enqueue(self, recording_id: int) -> CancelToken:
+    def enqueue(self, recording_id: int, overrides: Optional[dict] = None) -> CancelToken:
         token = CancelToken()
         with self._lock:
             self._cancels[recording_id] = token
-        self._queue.put(_Job(recording_id=recording_id, cancel_token=token))
+        self._queue.put(_Job(recording_id=recording_id, cancel_token=token, overrides=overrides))
         return token
 
     def cancel(self, recording_id: int) -> bool:
@@ -230,6 +228,10 @@ def __init__(
         event_emitter: Optional[Callable[[str, dict], None]] = None,
     ) -> None:
         self.db = db
+        # Recording persistence — the domain's own repository
+        # (services/recording/repository.py). Non-recording tables
+        # (settings, history) stay behind `self.db` / `self.settings`.
+        self.repo = db.recordings
         self.settings = settings_service
         self.transcription = transcription_service
         self.data_root = data_root
@@ -244,22 +246,14 @@ def __init__(
         self.summary = SummaryService()
         # Pre-record source preview — see _SourcePreview for the why.
         self._preview = _SourcePreview()
-        # Session cache: PULSE_ID_BASE+N → PipeWire monitor source name. Populated
-        # by list_audio_sources() and read by start() so the user picks an int id
-        # in the dropdown but we open a ParecAudioSource with the actual name.
-        self._pulse_monitor_by_id: dict[int, str] = {}
+        # Loopback enumeration + source construction. Owns the pactl session
+        # cache (picker id → monitor source name); see loopback.py.
+        self._loopback = LoopbackDiscovery()
 
         # Background queues.
         self._transcribe_q = _SerialJobQueue("transcribe", self._run_transcribe)
         self._summarize_q = _SerialJobQueue("summarize", self._run_summarize)
 
-        # Per-recording transcription overrides — populated by transcribe(...)
-        # when the user picks a non-default model/device/language for a single
-        # job, consumed (and cleared) by _run_transcribe. Keeping it as a
-        # side-channel dict avoids reworking _SerialJobQueue's _Job dataclass.
-        self._transcribe_overrides: dict[int, dict[str, Optional[str]]] = {}
-        self._transcribe_overrides_lock = threading.Lock()
-
         # Server-side push ticker. Replaces the old 250 ms HTTP poll the
         # dashboard used to do: while a recording is active, fire `meeting-state`
         # events at TICK_INTERVAL_MS through `self._emit` so both popup and
@@ -285,26 +279,7 @@ def list_audio_sources(self) -> dict:
             log.warning("query_devices failed", error=str(exc))
             return {"mic": [], "loopback": []}
 
-        # Pick loopback sources via the platform-specific filter, then fall
-        # back to the OTHER platform's filter (in case PortAudio reports
-        # something unexpected). The filters are conservative — they won't
-        # double-list anything that doesn't look like loopback.
-        loopback = _filter_linux_loopback(devs, apis) + _filter_wasapi_loopback(devs, apis)
-
-        # PipeWire / PulseAudio monitor sources — pactl/parec path. This is
-        # what actually works on Linux for capturing Chrome / Teams audio,
-        # since PortAudio's JACK and ALSA backends both mangle monitor names.
-        self._pulse_monitor_by_id = {}
-        for entry in list_pulse_monitor_sources():
-            self._pulse_monitor_by_id[entry["id"]] = entry["pulseSourceName"]
-            loopback.append({
-                "id": entry["id"],
-                "name": entry["name"],
-                "kind": entry["kind"],
-                "hostApi": entry["hostApi"],
-                "isDefault": entry["isDefault"],
-            })
-
+        loopback = self._loopback.list_sources(devs, apis)
         loopback_ids = {item["id"] for item in loopback}
 
         # Mic = input devices that are NOT already classified as loopback.
@@ -413,7 +388,7 @@ def start(
         # busy when the recorder tries to open it.
         self._preview.stop()
 
-        recording_id = self.db.create_recording(title=title or _default_title(), sources=sources)
+        recording_id = self.repo.create_recording(title=title or _default_title(), sources=sources)
         wav_rel = f"recordings/{recording_id}_{_slug(title)}.wav"
         wav_abs = self.data_root / wav_rel
         wav_abs.parent.mkdir(parents=True, exist_ok=True)
@@ -429,11 +404,11 @@ def start(
                 loopback=loop_source,
             )
         except (RecorderAlreadyStartedError, RecorderNotRunningError, NoAudioSourcesError):
-            self.db.delete_recording(recording_id)
+            self.repo.delete_recording(recording_id)
             raise
 
-        self.db.set_recording_recorder_state(recording_id, "recording")
-        self.db.set_recording_audio(
+        self.repo.set_recording_recorder_state(recording_id, "recording")
+        self.repo.set_recording_audio(
             recording_id,
             audio_relpath=wav_rel,
             duration_ms=0,
@@ -451,18 +426,7 @@ def _build_mic_source(self, device_id: Optional[int]):
         return SoundDeviceAudioSource(device_id=device_id, loopback=False)
 
     def _build_loopback_source(self, device_id: Optional[int]):
-        if device_id is None:
-            return None
-        # Route PipeWire monitor sources through parec instead of PortAudio.
-        pulse_name = self._pulse_monitor_by_id.get(device_id)
-        if pulse_name is not None:
-            return ParecAudioSource(source_name=pulse_name)
-        return SoundDeviceAudioSource(
-            device_id=device_id,
-            # WASAPI loopback flag only matters on Windows; on Linux the
-            # PortAudio device IS the monitor source, no flag needed.
-            loopback=_is_windows(),
-        )
+        return self._loopback.build_source(device_id)
 
     # -------------------------------------------------------------- pre-record preview
 
@@ -498,7 +462,7 @@ def pause(self) -> dict:
         state = self.recorder.get_state()
         rid = state.get("recording_id")
         if rid is not None:
-            self.db.set_recording_recorder_state(rid, "paused")
+            self.repo.set_recording_recorder_state(rid, "paused")
         self._emit_meeting_state("paused")
         return {"ok": True}
 
@@ -507,7 +471,7 @@ def resume(self) -> dict:
         state = self.recorder.get_state()
         rid = state.get("recording_id")
         if rid is not None:
-            self.db.set_recording_recorder_state(rid, "recording")
+            self.repo.set_recording_recorder_state(rid, "recording")
         self._emit_meeting_state("recording")
         return {"ok": True}
 
@@ -518,21 +482,21 @@ def stop(self) -> dict:
         self._stop_tick()
         self._emit_meeting_state("idle", duration_ms=result.get("duration_ms", 0))
         if rid is not None:
-            self.db.set_recording_audio(
+            self.repo.set_recording_audio(
                 rid,
-                audio_relpath=self.db.get_recording(rid)["audio_relpath"],
+                audio_relpath=self.repo.get_recording(rid)["audio_relpath"],
                 duration_ms=result["duration_ms"],
                 size_bytes=result["size_bytes"],
                 sample_rate=result["sample_rate"],
                 channels=result["channels"],
             )
-            self.db.set_recording_recorder_state(rid, None)
+            self.repo.set_recording_recorder_state(rid, None)
 
             # Auto-transcribe if enabled (default true).
             settings = self.settings.get_settings()
             if getattr(settings, "recordings_auto_transcribe", True):
                 self._transcribe_q.enqueue(rid)
-        return self._to_dto(self.db.get_recording(rid)) if rid is not None else {}
+        return self._to_dto(self.repo.get_recording(rid)) if rid is not None else {}
 
     def get_recorder_state(self) -> dict:
         st = self.recorder.get_state()
@@ -563,11 +527,11 @@ def get_recorder_state(self) -> dict:
     # -------------------------------------------------------------- library CRUD
 
     def list_recordings(self, limit: int, offset: int, search: Optional[str]) -> list[dict]:
-        rows = self.db.list_recordings(limit=limit, offset=offset, search=search)
+        rows = self.repo.list_recordings(limit=limit, offset=offset, search=search)
         return [self._to_dto(r) for r in rows]
 
     def get_recording(self, recording_id: int) -> Optional[dict]:
-        row = self.db.get_recording(recording_id, include_segments=True)
+        row = self.repo.get_recording(recording_id, include_segments=True)
         if row is None:
             return None
         dto = self._to_dto(row)
@@ -591,11 +555,11 @@ def update_recording(self, recording_id: int, fields: dict) -> dict:
         if "notes" in fields: translated["notes"] = fields["notes"]
         if "tags" in fields: translated["tags"] = fields["tags"]
         if "language" in fields: translated["language"] = fields["language"]
-        self.db.update_recording(recording_id, **translated)
-        return self._to_dto(self.db.get_recording(recording_id))
+        self.repo.update_recording(recording_id, **translated)
+        return self._to_dto(self.repo.get_recording(recording_id))
 
     def delete_recording(self, recording_id: int) -> dict:
-        row = self.db.get_recording(recording_id)
+        row = self.repo.get_recording(recording_id)
         if row and row.get("audio_relpath"):
             audio_path = (self.data_root / row["audio_relpath"]).resolve()
             try:
@@ -604,14 +568,14 @@ def delete_recording(self, recording_id: int) -> dict:
                     audio_path.unlink()
             except (ValueError, OSError):
                 pass
-        self.db.delete_recording(recording_id)
+        self.repo.delete_recording(recording_id)
         return {"ok": True}
 
     def import_file(self, file_path: str, title: Optional[str]) -> dict:
         src = Path(file_path).expanduser().resolve()
         if not src.exists() or not src.is_file():
             raise FileNotFoundError(file_path)
-        rid = self.db.create_recording(title=title or src.stem, sources=[])
+        rid = self.repo.create_recording(title=title or src.stem, sources=[])
         ext = src.suffix.lower() or ".wav"
         rel = f"recordings/{rid}_{_slug(title or src.stem)}{ext}"
         dst = self.data_root / rel
@@ -631,7 +595,7 @@ def import_file(self, file_path: str, title: Optional[str]) -> dict:
             sample_rate = None
 
         size_bytes = dst.stat().st_size
-        self.db.set_recording_audio(
+        self.repo.set_recording_audio(
             rid, audio_relpath=rel, duration_ms=duration_ms,
             size_bytes=size_bytes, sample_rate=sample_rate, channels=channels,
         )
@@ -643,7 +607,7 @@ def import_file(self, file_path: str, title: Optional[str]) -> dict:
         return {"recording_id": rid}
 
     def export(self, recording_id: int, fmt: str) -> dict:
-        row = self.db.get_recording(recording_id, include_segments=True)
+        row = self.repo.get_recording(recording_id, include_segments=True)
         if row is None:
             raise FileNotFoundError(f"recording {recording_id} not found")
         try:
@@ -665,19 +629,16 @@ def transcribe(
         """Enqueue a transcription job for an existing recording.
 
         Pass `model` / `device` / `language` to override the global settings
-        for this single job (used by the Re-transcribe modal). Overrides are
-        consumed by `_run_transcribe`; on second enqueue, prior un-consumed
-        overrides for the same id are replaced.
+        for this single job (used by the Re-transcribe modal); they travel on
+        the _Job itself.
         """
+        overrides = None
         if model or device or language:
-            with self._transcribe_overrides_lock:
-                self._transcribe_overrides[recording_id] = {
-                    "model": model,
-                    "device": device,
-                    "language": language,
-                }
-        self._transcribe_q.enqueue(recording_id)
-        self.db.update_transcript_status(recording_id, "pending", progress=0)
+            overrides = {"model": model, "device": device, "language": language}
+        # Status is written before enqueueing so a fast worker can't have its
+        # own status write clobbered by this one.
+        self.repo.update_transcript_status(recording_id, "pending", progress=0)
+        self._transcribe_q.enqueue(recording_id, overrides=overrides)
         return {"ok": True}
 
     def cancel_transcribe(self, recording_id: int) -> dict:
@@ -688,8 +649,8 @@ def summarize(self, recording_id: int, prompt: Optional[str]) -> dict:
         # Store the override prompt (if any) on the recording's notes? No —
         # just hold it in the job. For v1 we always use the settings template
         # and ignore per-call overrides.
+        self.repo.update_summary_status(recording_id, "summarizing", progress=0)
         self._summarize_q.enqueue(recording_id)
-        self.db.update_summary_status(recording_id, "summarizing", progress=0)
         return {"ok": True}
 
     def cancel_summarize(self, recording_id: int) -> dict:
@@ -736,13 +697,20 @@ def set_llm_config(
             set_api_key(preset, apiKey)
         return {"ok": True}
 
+    def _probe_provider(
+        self, preset: str, endpoint: str, apiKey: Optional[str],
+    ) -> OpenAICompatibleProvider:
+        """Provider for connection tests / model listing against an endpoint
+        the user is still editing — falls back to the stored key when the
+        form's key field is blank."""
+        return OpenAICompatibleProvider(
+            endpoint=endpoint, api_key=apiKey or get_api_key(preset), default_model="probe",
+        )
+
     def test_llm_connection(
         self, preset: str, endpoint: str, apiKey: Optional[str] = None,
     ) -> dict:
-        key = apiKey or get_api_key(preset)
-        provider = OpenAICompatibleProvider(
-            endpoint=endpoint, api_key=key, default_model="probe",
-        )
+        provider = self._probe_provider(preset, endpoint, apiKey)
         try:
             models = provider.list_models()
             return {"ok": True, "error": None, "models": models}
@@ -752,11 +720,7 @@ def test_llm_connection(
     def list_llm_models(
         self, preset: str, endpoint: str, apiKey: Optional[str] = None,
     ) -> list[str]:
-        key = apiKey or get_api_key(preset)
-        provider = OpenAICompatibleProvider(
-            endpoint=endpoint, api_key=key, default_model="probe",
-        )
-        return provider.list_models()
+        return self._probe_provider(preset, endpoint, apiKey).list_models()
 
     # -------------------------------------------------------------- crash recovery
 
@@ -770,28 +734,60 @@ def recover_unfinished(self) -> list[int]:
         )
 
     # -------------------------------------------------------------- job runners
+    #
+    # Job status protocol: every terminal outcome is a paired DB status write
+    # + a `recording-<kind>-complete` event, and the frontend depends on the
+    # pairing. _fail_job/_complete_job are the only places that pairing lives.
+
+    def _job_status_writer(self, kind: str) -> Callable:
+        return self.repo.update_transcript_status if kind == "transcribe" else self.repo.update_summary_status
+
+    def _fail_job(self, kind: str, rid: int, *, status: str = "error",
+                  db_error: Optional[str] = None, event_error: Optional[str] = None) -> None:
+        """Terminal failure: write status (with error unless cancelled) + emit
+        the completion event. `event_error` lets the user-facing message differ
+        from the persisted one."""
+        writer = self._job_status_writer(kind)
+        if status == "cancelled":
+            writer(rid, status)
+        else:
+            writer(rid, status, error=db_error)
+        self._emit(f"recording-{kind}-complete", {
+            "recordingId": rid, "success": False, "error": event_error or db_error or status,
+        })
+
+    def _complete_job(self, kind: str, rid: int, **status_kwargs) -> None:
+        self._job_status_writer(kind)(rid, "done", **status_kwargs)
+        self._emit(f"recording-{kind}-complete", {"recordingId": rid, "success": True})
+
+    def _provider_from_config(self) -> tuple[OpenAICompatibleProvider, dict]:
+        """Build the LLM provider from the persisted config. All presets speak
+        the OpenAI chat API today; if a second provider shape ever lands, this
+        and _probe_provider are the only construction points that need a
+        registry."""
+        config = self.get_llm_config()
+        provider = OpenAICompatibleProvider(
+            endpoint=config["endpoint"],
+            api_key=get_api_key(config["preset"]),
+            default_model=config["model"],
+        )
+        return provider, config
 
     def _run_transcribe(self, job: _Job) -> None:
         rid = job.recording_id
-        row = self.db.get_recording(rid)
+        row = self.repo.get_recording(rid)
         if row is None or not row.get("audio_relpath"):
-            self.db.update_transcript_status(rid, "error", error="audio not found")
-            self._emit("recording-transcribe-complete", {"recordingId": rid, "success": False, "error": "audio not found"})
+            self._fail_job("transcribe", rid, db_error="audio not found")
             return
 
         audio_path = self.data_root / row["audio_relpath"]
         if not audio_path.exists():
-            self.db.update_transcript_status(rid, "error", error="audio missing on disk")
-            self._emit("recording-transcribe-complete", {"recordingId": rid, "success": False, "error": "audio missing"})
+            self._fail_job("transcribe", rid, db_error="audio missing on disk", event_error="audio missing")
             return
 
-        self.db.update_transcript_status(rid, "transcribing", progress=0)
+        self.repo.update_transcript_status(rid, "transcribing", progress=0)
 
-        # Pull any per-job overrides set by transcribe(model=, device=, language=).
-        # Once consumed, they're cleared so a subsequent default-mode rerun
-        # falls back to global settings.
-        with self._transcribe_overrides_lock:
-            override = self._transcribe_overrides.pop(rid, None) or {}
+        override = job.overrides or {}
         try:
             settings = self.settings.get_settings()
             target_model = override.get("model") or settings.model or "tiny"
@@ -805,7 +801,7 @@ def _run_transcribe(self, job: _Job) -> None:
             self.transcription.load_model(target_model, target_device)
 
             def on_progress(p: float, text: str) -> None:
-                self.db.update_transcript_status(rid, "transcribing", progress=p)
+                self.repo.update_transcript_status(rid, "transcribing", progress=p)
                 self._emit("recording-transcribe-progress", {
                     "recordingId": rid, "progress": p, "currentText": text,
                 })
@@ -817,22 +813,20 @@ def on_progress(p: float, text: str) -> None:
                 cancel_token=job.cancel_token,
             )
         except TranscriptionCancelled:
-            self.db.update_transcript_status(rid, "cancelled")
-            self._emit("recording-transcribe-complete", {"recordingId": rid, "success": False, "error": "cancelled"})
+            self._fail_job("transcribe", rid, status="cancelled", event_error="cancelled")
             return
         except Exception as exc:
             log.exception("transcription failed", recording_id=rid)
-            self.db.update_transcript_status(rid, "error", error=str(exc))
-            self._emit("recording-transcribe-complete", {"recordingId": rid, "success": False, "error": str(exc)})
+            self._fail_job("transcribe", rid, db_error=str(exc))
             return
 
-        self.db.set_recording_transcript(
+        self.repo.set_recording_transcript(
             rid,
             result["text"],
             language=result.get("language"),
             model=target_model,
         )
-        self.db.replace_recording_segments(rid, result["segments"])
+        self.repo.replace_recording_segments(rid, result["segments"])
 
         # Auto-rename the title from the transcript context. Best-effort —
         # runs while status is still "transcribing" so the detail page's
@@ -840,13 +834,12 @@ def on_progress(p: float, text: str) -> None:
         # that flips the status to done. Failure is logged and swallowed.
         self._maybe_auto_rename_title(rid, result["text"], job.cancel_token)
 
-        self.db.update_transcript_status(rid, "done", progress=1.0)
-        self._emit("recording-transcribe-complete", {"recordingId": rid, "success": True})
+        self._complete_job("transcribe", rid, progress=1.0)
 
         # Auto-summarize if enabled.
         if getattr(self.settings.get_settings(), "recordings_auto_summarize", False):
+            self.repo.update_summary_status(rid, "summarizing", progress=0)
             self._summarize_q.enqueue(rid)
-            self.db.update_summary_status(rid, "summarizing", progress=0)
 
     def _maybe_auto_rename_title(
         self,
@@ -864,7 +857,7 @@ def _maybe_auto_rename_title(
         if not getattr(settings, "recordings_auto_rename_title", True):
             return
 
-        row = self.db.get_recording(rid)
+        row = self.repo.get_recording(rid)
         if row is None:
             return
         current_title = row.get("title")
@@ -877,13 +870,7 @@ def _maybe_auto_rename_title(
             return
 
         try:
-            config = self.get_llm_config()
-            preset = config["preset"]
-            provider = OpenAICompatibleProvider(
-                endpoint=config["endpoint"],
-                api_key=get_api_key(preset),
-                default_model=config["model"],
-            )
+            provider, _config = self._provider_from_config()
             new_title = generate_title(
                 transcript, provider, cancel_token=cancel_token
             )
@@ -895,7 +882,7 @@ def _maybe_auto_rename_title(
             )
             return
 
-        self.db.update_recording(rid, title=new_title)
+        self.repo.update_recording(rid, title=new_title)
         log.info(
             "auto-renamed recording",
             recording_id=rid,
@@ -905,21 +892,12 @@ def _maybe_auto_rename_title(
 
     def _run_summarize(self, job: _Job) -> None:
         rid = job.recording_id
-        row = self.db.get_recording(rid, include_segments=True)
+        row = self.repo.get_recording(rid, include_segments=True)
         if row is None or not row.get("transcript"):
-            self.db.update_summary_status(rid, "error", error="no transcript yet")
-            self._emit("recording-summarize-complete", {"recordingId": rid, "success": False, "error": "no transcript"})
+            self._fail_job("summarize", rid, db_error="no transcript yet", event_error="no transcript")
             return
 
-        config = self.get_llm_config()
-        preset = config["preset"]
-        api_key = get_api_key(preset)
-
-        provider = OpenAICompatibleProvider(
-            endpoint=config["endpoint"],
-            api_key=api_key,
-            default_model=config["model"],
-        )
+        provider, config = self._provider_from_config()
 
         try:
             def on_stream(token: str) -> None:
@@ -937,14 +915,12 @@ def on_stream(token: str) -> None:
             )
         except Exception as exc:
             log.exception("summary failed", recording_id=rid)
-            self.db.update_summary_status(rid, "error", error=str(exc))
-            self._emit("recording-summarize-complete", {"recordingId": rid, "success": False, "error": str(exc)})
+            self._fail_job("summarize", rid, db_error=str(exc))
             return
 
-        self.db.update_recording(rid, summary=summary)
-        provider_label = f"{preset}:{config['model']}"
-        self.db.update_summary_status(rid, "done", progress=1.0, provider=provider_label)
-        self._emit("recording-summarize-complete", {"recordingId": rid, "success": True})
+        self.repo.update_recording(rid, summary=summary)
+        provider_label = f"{config['preset']}:{config['model']}"
+        self._complete_job("summarize", rid, progress=1.0, provider=provider_label)
 
     # -------------------------------------------------------------- dto
 
@@ -983,11 +959,6 @@ def _to_dto(rec: dict) -> dict:
 # helpers
 # ─────────────────────────────────────────────────────────────────────────────
 
-def _is_windows() -> bool:
-    import sys
-    return sys.platform.startswith("win")
-
-
 def _slug(s: str) -> str:
     import re
     clean = re.sub(r"[^a-zA-Z0-9._-]+", "-", (s or "rec").strip()).strip("-")
diff --git a/src-pyloid/services/recording/loopback.py b/src-pyloid/services/recording/loopback.py
new file mode 100644
index 0000000..cde229b
--- /dev/null
+++ b/src-pyloid/services/recording/loopback.py
@@ -0,0 +1,75 @@
+"""Loopback discovery — the one seam over the platform-specific backends.
+
+Three backends feed the system-audio device picker:
+  * PortAudio device filtering on Linux (`loopback_linux`) — ALSA/JACK monitor
+    devices, conservative fallback.
+  * pactl/parec (`loopback_pulse`) — PipeWire/PulseAudio monitor sources; the
+    path that actually works for capturing Chrome / Teams audio on Linux.
+  * WASAPI output filtering on Windows (`loopback_windows`).
+
+Callers (MeetingsController) see two operations: `list_sources()` to populate
+the picker, and `build_source(device_id)` to open whatever the user picked.
+The pactl ID range (PULSE_ID_BASE+N → source-name mapping) is a session cache
+owned HERE — `build_source` must be called on the same instance that listed,
+which is why this is a class and not free functions. A new platform backend
+means editing this module only.
+"""
+
+from typing import Optional
+
+from services.recording.audio_source import ParecAudioSource, SoundDeviceAudioSource
+from services.recording.loopback_linux import _filter_linux_loopback
+from services.recording.loopback_pulse import list_pulse_monitor_sources
+from services.recording.loopback_windows import _filter_wasapi_loopback
+
+
+def _is_windows() -> bool:
+    import sys
+    return sys.platform.startswith("win")
+
+
+class LoopbackDiscovery:
+    def __init__(self) -> None:
+        # Session cache: PULSE_ID_BASE+N → PipeWire monitor source name.
+        # Refreshed by list_sources() and read by build_source() so the user
+        # picks an int id in the dropdown but we open a ParecAudioSource with
+        # the actual name.
+        self._pulse_monitor_by_id: dict[int, str] = {}
+
+    def list_sources(self, devs: list, apis: list) -> list:
+        """All loopback candidates from every backend. `devs`/`apis` are the
+        caller's sounddevice query results (queried once, shared with mic
+        enumeration).
+
+        The PortAudio filters are conservative — they won't double-list
+        anything that doesn't look like loopback — so running both platform
+        filters unconditionally is safe."""
+        loopback = _filter_linux_loopback(devs, apis) + _filter_wasapi_loopback(devs, apis)
+
+        self._pulse_monitor_by_id = {}
+        for entry in list_pulse_monitor_sources():
+            self._pulse_monitor_by_id[entry["id"]] = entry["pulseSourceName"]
+            loopback.append({
+                "id": entry["id"],
+                "name": entry["name"],
+                "kind": entry["kind"],
+                "hostApi": entry["hostApi"],
+                "isDefault": entry["isDefault"],
+            })
+        return loopback
+
+    def build_source(self, device_id: Optional[int]):
+        """AudioSource for a loopback id previously returned by list_sources();
+        None passes through (source not picked)."""
+        if device_id is None:
+            return None
+        # Route PipeWire monitor sources through parec instead of PortAudio.
+        pulse_name = self._pulse_monitor_by_id.get(device_id)
+        if pulse_name is not None:
+            return ParecAudioSource(source_name=pulse_name)
+        return SoundDeviceAudioSource(
+            device_id=device_id,
+            # WASAPI loopback flag only matters on Windows; on Linux the
+            # PortAudio device IS the monitor source, no flag needed.
+            loopback=_is_windows(),
+        )
diff --git a/src-pyloid/services/recording/recovery.py b/src-pyloid/services/recording/recovery.py
index d75eace..5ff0d6c 100644
--- a/src-pyloid/services/recording/recovery.py
+++ b/src-pyloid/services/recording/recovery.py
@@ -38,7 +38,8 @@ def recover_unfinished_recordings(
     `on_recovered` callback is invoked for each — used by AppController to
     enqueue background transcription."""
     recovered: list[int] = []
-    rows = db.list_unfinished_recordings()
+    repo = db.recordings  # Recording persistence — RecordingsRepository
+    rows = repo.list_unfinished_recordings()
     if not rows:
         return recovered
 
@@ -47,10 +48,10 @@ def recover_unfinished_recordings(
         relpath = row.get("audio_relpath")
 
         if not relpath:
-            db.update_transcript_status(
+            repo.update_transcript_status(
                 rid, status="error", error="recorder crashed before audio file was created"
             )
-            db.set_recording_recorder_state(rid, None)
+            repo.set_recording_recorder_state(rid, None)
             log.warning("recovery: no audio file recorded", recording_id=rid)
             continue
 
@@ -58,16 +59,16 @@ def recover_unfinished_recordings(
         try:
             wav_path.relative_to(data_root.resolve())
         except ValueError:
-            db.update_transcript_status(rid, status="error", error="audio path outside data root")
-            db.set_recording_recorder_state(rid, None)
+            repo.update_transcript_status(rid, status="error", error="audio path outside data root")
+            repo.set_recording_recorder_state(rid, None)
             log.warning("recovery: refused path traversal", recording_id=rid, path=str(wav_path))
             continue
 
         if not wav_path.exists():
-            db.update_transcript_status(
+            repo.update_transcript_status(
                 rid, status="error", error=f"audio file missing on disk: {relpath}"
             )
-            db.set_recording_recorder_state(rid, None)
+            repo.set_recording_recorder_state(rid, None)
             log.warning("recovery: audio missing", recording_id=rid, path=str(wav_path))
             continue
 
@@ -79,12 +80,12 @@ def recover_unfinished_recordings(
             duration_ms = int(frames * 1000 / sample_rate) if sample_rate else 0
             size_bytes = wav_path.stat().st_size
         except Exception as exc:
-            db.update_transcript_status(rid, status="error", error=f"audio unreadable: {exc}")
-            db.set_recording_recorder_state(rid, None)
+            repo.update_transcript_status(rid, status="error", error=f"audio unreadable: {exc}")
+            repo.set_recording_recorder_state(rid, None)
             log.warning("recovery: audio unreadable", recording_id=rid, error=str(exc))
             continue
 
-        db.set_recording_audio(
+        repo.set_recording_audio(
             rid,
             audio_relpath=relpath,
             duration_ms=duration_ms,
@@ -92,8 +93,8 @@ def recover_unfinished_recordings(
             sample_rate=sample_rate,
             channels=channels,
         )
-        db.update_transcript_status(rid, status="pending", progress=0)
-        db.set_recording_recorder_state(rid, None)
+        repo.update_transcript_status(rid, status="pending", progress=0)
+        repo.set_recording_recorder_state(rid, None)
         log.info(
             "recovery: recording recovered",
             recording_id=rid, duration_ms=duration_ms, channels=channels,
diff --git a/src-pyloid/services/recording/repository.py b/src-pyloid/services/recording/repository.py
new file mode 100644
index 0000000..1841b35
--- /dev/null
+++ b/src-pyloid/services/recording/repository.py
@@ -0,0 +1,293 @@
+"""RecordingsRepository — persistence for the Recording entity.
+
+Canonical home of Recording persistence per CONTEXT.md ("Recording" entity):
+a Recording is the row in the `recordings` table, with its transcript
+segments in `recording_segments`. All reads/writes to those tables go
+through this repository.
+
+Schema creation/migration for the recordings tables stays in
+`DatabaseService._ensure_recordings_tables` — DatabaseService owns the schema
+lifecycle for every table in the DB file. This class only does row-level
+persistence, borrowing the DatabaseService connection helper so connection
+policy (timeouts, PRAGMAs) stays in one place.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from services.database import DatabaseService
+
+
+_RECORDING_UPDATABLE_FIELDS = frozenset({"title", "summary", "notes", "tags", "language"})
+
+
+class RecordingsRepository:
+    """Row-level persistence for `recordings` / `recording_segments`.
+
+    Constructed by DatabaseService in its __init__ and exposed as
+    `db.recordings`; DatabaseService keeps thin delegating methods for
+    backward compatibility with existing callers.
+    """
+
+    def __init__(self, db: "DatabaseService") -> None:
+        self._db = db
+
+    def _get_connection(self) -> sqlite3.Connection:
+        return self._db._get_connection()
+
+    def create_recording(self, title: str, sources: list[str]) -> int:
+        now = datetime.now().isoformat()
+        conn = self._get_connection()
+        try:
+            cursor = conn.cursor()
+            cursor.execute(
+                """INSERT INTO recordings (title, sources, created_at, updated_at)
+                   VALUES (?, ?, ?, ?)""",
+                (title, json.dumps(sources), now, now),
+            )
+            rid = cursor.lastrowid
+            conn.commit()
+            return rid
+        finally:
+            conn.close()
+
+    def get_recording(self, recording_id: int, include_segments: bool = False) -> Optional[dict]:
+        conn = self._get_connection()
+        try:
+            row = conn.execute(
+                "SELECT * FROM recordings WHERE id = ?", (recording_id,)
+            ).fetchone()
+            if row is None:
+                return None
+            rec = self._row_to_recording(row)
+            if include_segments:
+                seg_rows = conn.execute(
+                    """SELECT id, recording_id, start_ms, end_ms, text
+                       FROM recording_segments
+                       WHERE recording_id = ?
+                       ORDER BY start_ms ASC, id ASC""",
+                    (recording_id,),
+                ).fetchall()
+                rec["segments"] = [dict(r) for r in seg_rows]
+            return rec
+        finally:
+            conn.close()
+
+    def list_recordings(
+        self,
+        limit: int = 100,
+        offset: int = 0,
+        search: Optional[str] = None,
+    ) -> list[dict]:
+        conn = self._get_connection()
+        try:
+            query = "SELECT * FROM recordings"
+            params: list = []
+            if search:
+                query += " WHERE title LIKE ?"
+                params.append(f"%{search}%")
+            query += " ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?"
+            params.extend([limit, offset])
+            rows = conn.execute(query, params).fetchall()
+            return [self._row_to_recording(r) for r in rows]
+        finally:
+            conn.close()
+
+    def update_recording(self, recording_id: int, **fields) -> None:
+        unknown = set(fields) - _RECORDING_UPDATABLE_FIELDS
+        if unknown:
+            raise ValueError(f"unknown recording fields: {sorted(unknown)}")
+        if not fields:
+            return
+        sets, params = [], []
+        for name, value in fields.items():
+            if name == "tags":
+                value = json.dumps(value or [])
+            sets.append(f"{name} = ?")
+            params.append(value)
+        sets.append("updated_at = ?")
+        params.append(datetime.now().isoformat())
+        params.append(recording_id)
+
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def set_recording_audio(
+        self,
+        recording_id: int,
+        audio_relpath: str,
+        duration_ms: Optional[int],
+        size_bytes: Optional[int],
+        sample_rate: Optional[int],
+        channels: Optional[int],
+    ) -> None:
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                """UPDATE recordings
+                   SET audio_relpath = ?, audio_duration_ms = ?, audio_size_bytes = ?,
+                       audio_sample_rate = ?, audio_channels = ?, updated_at = ?
+                   WHERE id = ?""",
+                (
+                    audio_relpath, duration_ms, size_bytes,
+                    sample_rate, channels, datetime.now().isoformat(),
+                    recording_id,
+                ),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def set_recording_recorder_state(self, recording_id: int, state: Optional[str]) -> None:
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                "UPDATE recordings SET recorder_state = ?, updated_at = ? WHERE id = ?",
+                (state, datetime.now().isoformat(), recording_id),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def update_transcript_status(
+        self,
+        recording_id: int,
+        status: str,
+        progress: Optional[float] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        sets = ["transcript_status = ?", "updated_at = ?"]
+        params: list = [status, datetime.now().isoformat()]
+        if progress is not None:
+            sets.insert(1, "transcript_progress = ?")
+            params.insert(1, progress)
+        if error is not None:
+            sets.insert(-1, "transcript_error = ?")
+            params.insert(-1, error)
+        params.append(recording_id)
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def update_summary_status(
+        self,
+        recording_id: int,
+        status: str,
+        progress: Optional[float] = None,
+        error: Optional[str] = None,
+        provider: Optional[str] = None,
+    ) -> None:
+        sets = ["summary_status = ?", "updated_at = ?"]
+        params: list = [status, datetime.now().isoformat()]
+        if progress is not None:
+            sets.insert(1, "summary_progress = ?")
+            params.insert(1, progress)
+        if error is not None:
+            sets.insert(-1, "summary_error = ?")
+            params.insert(-1, error)
+        if provider is not None:
+            sets.insert(-1, "summary_provider = ?")
+            params.insert(-1, provider)
+        params.append(recording_id)
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                f"UPDATE recordings SET {', '.join(sets)} WHERE id = ?", params
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def set_recording_transcript(
+        self,
+        recording_id: int,
+        transcript: str,
+        language: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> None:
+        """Persist the final transcript text. Segments go via replace_recording_segments.
+
+        `model` is the whisper model name that produced the transcript (e.g.
+        'tiny', 'large-v3'). Optional and backward-compatible — existing callers
+        that don't pass it leave the column NULL or unchanged on re-transcribe.
+        """
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                """UPDATE recordings
+                   SET transcript = ?,
+                       language = COALESCE(?, language),
+                       transcript_model = COALESCE(?, transcript_model),
+                       updated_at = ?
+                   WHERE id = ?""",
+                (transcript, language, model, datetime.now().isoformat(), recording_id),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def replace_recording_segments(self, recording_id: int, segments: list[dict]) -> None:
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                "DELETE FROM recording_segments WHERE recording_id = ?", (recording_id,)
+            )
+            if segments:
+                conn.executemany(
+                    """INSERT INTO recording_segments (recording_id, start_ms, end_ms, text)
+                       VALUES (?, ?, ?, ?)""",
+                    [
+                        (recording_id, int(s["start_ms"]), int(s["end_ms"]), str(s["text"]))
+                        for s in segments
+                    ],
+                )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def delete_recording(self, recording_id: int) -> None:
+        # Capture the audio path so the caller can delete the file off disk.
+        rec = self.get_recording(recording_id)
+        if rec and rec.get("audio_relpath"):
+            self._db._delete_audio_file(rec["audio_relpath"])
+        conn = self._get_connection()
+        try:
+            conn.execute("DELETE FROM recordings WHERE id = ?", (recording_id,))
+            conn.commit()
+        finally:
+            conn.close()
+
+    def list_unfinished_recordings(self) -> list[dict]:
+        """Recordings that were left mid-flight (used by crash-recovery on startup)."""
+        conn = self._get_connection()
+        try:
+            rows = conn.execute(
+                "SELECT * FROM recordings WHERE recorder_state IS NOT NULL "
+                "ORDER BY created_at ASC"
+            ).fetchall()
+            return [self._row_to_recording(r) for r in rows]
+        finally:
+            conn.close()
+
+    @staticmethod
+    def _row_to_recording(row: sqlite3.Row) -> dict:
+        rec = dict(row)
+        rec["sources"] = json.loads(rec.get("sources") or "[]")
+        rec["tags"] = json.loads(rec.get("tags") or "[]")
+        return rec
diff --git a/src-pyloid/services/settings.py b/src-pyloid/services/settings.py
index 3ee37dd..93d5fbc 100644
--- a/src-pyloid/services/settings.py
+++ b/src-pyloid/services/settings.py
@@ -1,19 +1,8 @@
-from dataclasses import dataclass
-from typing import Literal, Optional
+from dataclasses import dataclass, fields
+from typing import Optional
 from .database import DatabaseService
 from .hotkey import normalize_hotkey
-
-
-# Whisper model options - all models supported by faster-whisper
-# Order: multilingual models first, then English-only, then distilled
-WHISPER_MODELS = [
-    # Multilingual models (most commonly used)
-    "tiny", "base", "small", "medium", "large-v1", "large-v2", "large-v3", "turbo",
-    # English-only models (optimized for English)
-    "tiny.en", "base.en", "small.en", "medium.en",
-    # Distilled models (faster inference, English-only)
-    "distil-small.en", "distil-medium.en", "distil-large-v2", "distil-large-v3",
-]
+from .model_catalog import WHISPER_MODELS
 
 # Supported languages (subset - full list at https://github.com/openai/whisper)
 WHISPER_LANGUAGES = [
@@ -85,6 +74,73 @@ class Settings:
     llm_prompt_template: str = DEFAULT_LLM_PROMPT
 
 
+# The Settings dataclass above is the single schema for all settings: field
+# names are the DB keys, defaults are the app defaults, and the camelCase
+# aliases used over RPC are derived mechanically by to_camel_case(). Adding a
+# setting = adding a field (plus RPC_SETTINGS_FIELDS if it is exposed on the
+# main settings RPC surface).
+
+# Hotkey fields are normalized before storage so stored values stay canonical.
+_HOTKEY_FIELDS = {"hold_hotkey", "toggle_hotkey"}
+
+# Settings exposed over the get_settings/update_settings RPC surface.
+# Recordings/LLM settings are managed through the meetings.* RPC methods and
+# are intentionally absent here.
+RPC_SETTINGS_FIELDS = (
+    "language",
+    "model",
+    "device",
+    "auto_start",
+    "retention",
+    "theme",
+    "onboarding_complete",
+    "microphone",
+    "save_audio_to_history",
+    "show_popup",
+    "hold_hotkey",
+    "hold_hotkey_enabled",
+    "toggle_hotkey",
+    "toggle_hotkey_enabled",
+    "prepend_space",
+    "recordings_auto_rename_title",
+)
+
+
+def to_camel_case(name: str) -> str:
+    head, *rest = name.split("_")
+    return head + "".join(part.capitalize() for part in rest)
+
+
+def settings_to_rpc(settings: "Settings") -> dict:
+    """Render the RPC-exposed subset of Settings as a camelCase dict."""
+    return {to_camel_case(name): getattr(settings, name) for name in RPC_SETTINGS_FIELDS}
+
+
+def rpc_to_settings_kwargs(payload: dict) -> dict:
+    """Map camelCase RPC keys back to Settings field names, dropping unknowns."""
+    mapped = {}
+    for name in RPC_SETTINGS_FIELDS:
+        camel = to_camel_case(name)
+        if camel in payload:
+            mapped[name] = payload[camel]
+    return mapped
+
+
+def _serialize(value) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _parse(raw: str, default):
+    # bool check must precede int: bool is a subclass of int.
+    if isinstance(default, bool):
+        return raw == "true"
+    if isinstance(default, int):
+        return int(raw)
+    return raw
+
+
 class SettingsService:
     def __init__(self, db: DatabaseService):
         self.db = db
@@ -94,121 +150,30 @@ def get_settings(self) -> Settings:
         if self._cache:
             return self._cache
 
-        settings = Settings(
-            language=self.db.get_setting("language", "auto"),
-            model=self.db.get_setting("model", "tiny"),
-            device=self.db.get_setting("device", "auto"),
-            auto_start=self.db.get_setting("auto_start", "true") == "true",
-            retention=int(self.db.get_setting("retention", "-1")),
-            theme=self.db.get_setting("theme", "dark"),
-            onboarding_complete=self.db.get_setting("onboarding_complete", "false") == "true",
-            microphone=int(self.db.get_setting("microphone", "-1")),
-            save_audio_to_history=self.db.get_setting("save_audio_to_history", "false") == "true",
-            # UI settings
-            show_popup=self.db.get_setting("show_popup", "true") == "true",
-            # Hotkey settings
-            hold_hotkey=self.db.get_setting("hold_hotkey", "ctrl+win"),
-            hold_hotkey_enabled=self.db.get_setting("hold_hotkey_enabled", "true") == "true",
-            toggle_hotkey=self.db.get_setting("toggle_hotkey", "ctrl+shift+win"),
-            toggle_hotkey_enabled=self.db.get_setting("toggle_hotkey_enabled", "false") == "true",
-            # Transcription settings
-            prepend_space=self.db.get_setting("prepend_space", "false") == "true",
-            # Recordings (Meetings)
-            recordings_mic_device=self.db.get_setting("recordings_mic_device", None),
-            recordings_loopback_device=self.db.get_setting("recordings_loopback_device", None),
-            recordings_auto_transcribe=self.db.get_setting("recordings_auto_transcribe", "true") == "true",
-            recordings_auto_summarize=self.db.get_setting("recordings_auto_summarize", "false") == "true",
-            recordings_auto_rename_title=self.db.get_setting("recordings_auto_rename_title", "true") == "true",
-            # LLM config
-            llm_preset=self.db.get_setting("llm_preset", "ollama"),
-            llm_endpoint=self.db.get_setting("llm_endpoint", "http://localhost:11434/v1"),
-            llm_model=self.db.get_setting("llm_model", "llama3.2"),
-            llm_prompt_template=self.db.get_setting("llm_prompt_template", DEFAULT_LLM_PROMPT),
-        )
+        values = {}
+        for field in fields(Settings):
+            raw = self.db.get_setting(field.name, None)
+            values[field.name] = field.default if raw is None else _parse(raw, field.default)
+
+        settings = Settings(**values)
         self._cache = settings
         return settings
 
-    def update_settings(
-        self,
-        *,
-        language: Optional[str] = None,
-        model: Optional[str] = None,
-        device: Optional[str] = None,
-        auto_start: Optional[bool] = None,
-        retention: Optional[int] = None,
-        theme: Optional[str] = None,
-        onboarding_complete: Optional[bool] = None,
-        microphone: Optional[int] = None,
-        save_audio_to_history: Optional[bool] = None,
-        hold_hotkey: Optional[str] = None,
-        hold_hotkey_enabled: Optional[bool] = None,
-        toggle_hotkey: Optional[str] = None,
-        toggle_hotkey_enabled: Optional[bool] = None,
-        show_popup: Optional[bool] = None,
-        prepend_space: Optional[bool] = None,
-        # Recordings
-        recordings_mic_device: Optional[str] = None,
-        recordings_loopback_device: Optional[str] = None,
-        recordings_auto_transcribe: Optional[bool] = None,
-        recordings_auto_summarize: Optional[bool] = None,
-        recordings_auto_rename_title: Optional[bool] = None,
-        # LLM
-        llm_preset: Optional[str] = None,
-        llm_endpoint: Optional[str] = None,
-        llm_model: Optional[str] = None,
-        llm_prompt_template: Optional[str] = None,
-    ) -> Settings:
-        if language is not None:
-            self.db.set_setting("language", language)
-        if model is not None:
-            self.db.set_setting("model", model)
-        if device is not None:
-            self.db.set_setting("device", device)
-        if auto_start is not None:
-            self.db.set_setting("auto_start", "true" if auto_start else "false")
-        if retention is not None:
-            self.db.set_setting("retention", str(retention))
-        if theme is not None:
-            self.db.set_setting("theme", theme)
-        if onboarding_complete is not None:
-            self.db.set_setting("onboarding_complete", "true" if onboarding_complete else "false")
-        if microphone is not None:
-            self.db.set_setting("microphone", str(microphone))
-        if save_audio_to_history is not None:
-            self.db.set_setting("save_audio_to_history", "true" if save_audio_to_history else "false")
-        if show_popup is not None:
-            self.db.set_setting("show_popup", "true" if show_popup else "false")
-        if prepend_space is not None:
-            self.db.set_setting("prepend_space", "true" if prepend_space else "false")
-        # Hotkey settings - normalize before storing for consistent format
-        if hold_hotkey is not None:
-            self.db.set_setting("hold_hotkey", normalize_hotkey(hold_hotkey))
-        if hold_hotkey_enabled is not None:
-            self.db.set_setting("hold_hotkey_enabled", "true" if hold_hotkey_enabled else "false")
-        if toggle_hotkey is not None:
-            self.db.set_setting("toggle_hotkey", normalize_hotkey(toggle_hotkey))
-        if toggle_hotkey_enabled is not None:
-            self.db.set_setting("toggle_hotkey_enabled", "true" if toggle_hotkey_enabled else "false")
-        # Recordings (Meetings)
-        if recordings_mic_device is not None:
-            self.db.set_setting("recordings_mic_device", recordings_mic_device)
-        if recordings_loopback_device is not None:
-            self.db.set_setting("recordings_loopback_device", recordings_loopback_device)
-        if recordings_auto_transcribe is not None:
-            self.db.set_setting("recordings_auto_transcribe", "true" if recordings_auto_transcribe else "false")
-        if recordings_auto_summarize is not None:
-            self.db.set_setting("recordings_auto_summarize", "true" if recordings_auto_summarize else "false")
-        if recordings_auto_rename_title is not None:
-            self.db.set_setting("recordings_auto_rename_title", "true" if recordings_auto_rename_title else "false")
-        # LLM config
-        if llm_preset is not None:
-            self.db.set_setting("llm_preset", llm_preset)
-        if llm_endpoint is not None:
-            self.db.set_setting("llm_endpoint", llm_endpoint)
-        if llm_model is not None:
-            self.db.set_setting("llm_model", llm_model)
-        if llm_prompt_template is not None:
-            self.db.set_setting("llm_prompt_template", llm_prompt_template)
+    def update_settings(self, **kwargs) -> Settings:
+        """Persist the given settings. Keys are Settings field names; None
+        values mean "leave unchanged". Unknown keys raise before anything is
+        written."""
+        known = {field.name for field in fields(Settings)}
+        unknown = set(kwargs) - known
+        if unknown:
+            raise TypeError(f"Unknown setting(s): {', '.join(sorted(unknown))}")
+
+        for key, value in kwargs.items():
+            if value is None:
+                continue
+            if key in _HOTKEY_FIELDS:
+                value = normalize_hotkey(value)
+            self.db.set_setting(key, _serialize(value))
 
         self._cache = None  # Invalidate cache
         return self.get_settings()
diff --git a/src-pyloid/services/transcription.py b/src-pyloid/services/transcription.py
index f78493e..e7f936f 100644
--- a/src-pyloid/services/transcription.py
+++ b/src-pyloid/services/transcription.py
@@ -7,7 +7,7 @@
 from faster_whisper import WhisperModel
 
 from services.logger import get_logger
-from services.model_manager import MODEL_REPOS
+from services.model_catalog import get_repo_id
 from services.gpu import resolve_device, get_compute_type
 
 log = get_logger("model")
@@ -32,11 +32,6 @@ class TranscriptionCancelled(Exception):
     """Raised by long-running transcription when the cancel token is tripped."""
 
 
-def _get_repo_id(model_name: str) -> str:
-    """Get the HuggingFace repo ID for a model name."""
-    return MODEL_REPOS.get(model_name, f"Systran/faster-whisper-{model_name}")
-
-
 class TranscriptionService:
     def __init__(self):
         self._model: Optional[WhisperModel] = None
@@ -66,7 +61,7 @@ def load_model(self, model_name: str = "tiny", device_preference: str = "auto"):
 
             self._loading = True
             try:
-                repo_id = _get_repo_id(model_name)
+                repo_id = get_repo_id(model_name)
                 log.info(
                     "Loading model",
                     model=model_name,
@@ -156,7 +151,7 @@ def transcribe(
             if "not found or cannot be loaded" in str(e) and self._current_device == "cuda":
                 log.warning("CUDA runtime error during transcription, reloading on CPU", error=str(e))
                 model_name = self._current_model_name
-                repo_id = _get_repo_id(model_name)
+                repo_id = get_repo_id(model_name)
                 self._model = WhisperModel(repo_id, device="cpu", compute_type="int8")
                 self._current_device = "cpu"
                 self._current_compute_type = "int8"
diff --git a/src-pyloid/services/ui_event_bridge.py b/src-pyloid/services/ui_event_bridge.py
new file mode 100644
index 0000000..d433c40
--- /dev/null
+++ b/src-pyloid/services/ui_event_bridge.py
@@ -0,0 +1,48 @@
+"""The single backend→UI event pathway.
+
+Backend code (hotkey/audio/transcription threads, MeetingsController) calls
+`emit_event(name, payload)` from any thread; one Qt signal with a
+QueuedConnection marshals it to the main thread, where the handler registered
+via `on(name, handler)` runs. Events with no registered handler are dropped
+silently — that's the contract for meetings events the popup doesn't care
+about (e.g. recording-transcribe-progress).
+
+Replaces the previous two parallel pathways (per-event Qt signals for PTT +
+a separately installed meetings emitter), which kept drifting apart and each
+had its own registration-order trap.
+
+Requires a running QCoreApplication/QApplication for queued delivery — same
+constraint the old per-event signals had.
+"""
+
+from PySide6.QtCore import QObject, Signal, Qt
+
+from services.logger import get_logger
+
+log = get_logger("window")
+
+
+class UiEventBridge(QObject):
+    _event = Signal(str, object)
+
+    def __init__(self):
+        super().__init__()
+        self._handlers = {}
+        self._event.connect(self._dispatch, Qt.QueuedConnection)
+
+    def on(self, name: str, handler):
+        """Register the main-thread handler for `name` (one per event)."""
+        self._handlers[name] = handler
+
+    def emit_event(self, name: str, payload=None):
+        """Thread-safe: queue `payload` to `name`'s handler on the main thread."""
+        self._event.emit(name, payload)
+
+    def _dispatch(self, name, payload):
+        handler = self._handlers.get(name)
+        if handler is None:
+            return
+        try:
+            handler(payload)
+        except Exception:
+            log.exception("ui event handler failed", event=name)
diff --git a/src-pyloid/tests/test_audio.py b/src-pyloid/tests/test_audio.py
index 41fba91..0616d08 100644
--- a/src-pyloid/tests/test_audio.py
+++ b/src-pyloid/tests/test_audio.py
@@ -3,12 +3,28 @@
 from services.audio import AudioService
 
 
+def _has_input_device() -> bool:
+    try:
+        import sounddevice as sd
+        sd.query_devices(kind="input")
+        return True
+    except Exception:
+        return False
+
+
+requires_input_device = pytest.mark.skipif(
+    not _has_input_device(),
+    reason="No audio input device available (headless CI)",
+)
+
+
 class TestAudioService:
     def test_initial_state_not_recording(self):
         """Audio service starts in non-recording state."""
         service = AudioService()
         assert service.is_recording() == False
 
+    @requires_input_device
     def test_start_recording_changes_state(self):
         """Starting recording changes state to recording."""
         service = AudioService()
@@ -19,6 +35,7 @@ def test_start_recording_changes_state(self):
         # Cleanup
         service.stop_recording()
 
+    @requires_input_device
     def test_stop_recording_changes_state(self):
         """Stopping recording changes state back to not recording."""
         service = AudioService()
@@ -27,6 +44,7 @@ def test_stop_recording_changes_state(self):
 
         assert service.is_recording() == False
 
+    @requires_input_device
     def test_stop_recording_returns_numpy_array(self):
         """Stopping recording returns numpy array of audio data."""
         service = AudioService()
@@ -49,6 +67,7 @@ def test_stop_without_start_returns_empty_array(self):
         assert isinstance(audio, np.ndarray)
         assert len(audio) == 0
 
+    @requires_input_device
     def test_start_twice_is_idempotent(self):
         """Starting recording twice doesn't cause issues."""
         service = AudioService()
@@ -74,6 +93,7 @@ def test_channels_is_mono(self):
         """Audio is recorded in mono."""
         assert AudioService.CHANNELS == 1
 
+    @requires_input_device
     def test_amplitude_callback_is_called(self):
         """Amplitude callback receives values during recording."""
         service = AudioService()
diff --git a/src-pyloid/tests/test_clipboard.py b/src-pyloid/tests/test_clipboard.py
index 3f3db0e..1d9c8a0 100644
--- a/src-pyloid/tests/test_clipboard.py
+++ b/src-pyloid/tests/test_clipboard.py
@@ -1,6 +1,17 @@
+import os
+
 import pytest
 from services.clipboard import ClipboardService
 
+# These are integration tests against the real clipboard (wl-copy / X
+# selection). Headless environments (CI runners) have neither, so skip there
+# rather than fail — exercising the platform fallback logic needs a live
+# display server to mean anything.
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("DISPLAY") and not os.environ.get("WAYLAND_DISPLAY"),
+    reason="clipboard tests need a real display server (X11 or Wayland)",
+)
+
 
 class TestClipboardService:
     def test_copy_to_clipboard(self):
diff --git a/src-pyloid/tests/test_dictation.py b/src-pyloid/tests/test_dictation.py
new file mode 100644
index 0000000..e91946b
--- /dev/null
+++ b/src-pyloid/tests/test_dictation.py
@@ -0,0 +1,127 @@
+"""Unit tests for DictationPipeline (services/dictation.py) — the
+release-to-paste sequence, testable with fakes instead of mocking seven
+services through the hotkey path."""
+
+import tempfile
+import wave
+from pathlib import Path
+from unittest.mock import Mock
+
+import numpy as np
+import pytest
+
+from services.database import DatabaseService
+from services.dictation import DictationPipeline
+from services.settings import Settings
+
+
+@pytest.fixture
+def db():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        yield DatabaseService(Path(tmpdir) / "test.db")
+
+
+def make_pipeline(db, *, settings=None, transcript="hello world",
+                  model_loaded=True, model_loading=False):
+    settings_service = Mock()
+    settings_service.get_settings.return_value = settings or Settings()
+    transcription = Mock()
+    transcription.transcribe.return_value = transcript
+    clipboard = Mock()
+    audio_service = Mock(CHANNELS=1, SAMPLE_RATE=16000)
+    pipeline = DictationPipeline(
+        settings_service=settings_service,
+        transcription_service=transcription,
+        clipboard_service=clipboard,
+        db=db,
+        audio_service=audio_service,
+        is_model_loaded=lambda: model_loaded,
+        is_model_loading=lambda: model_loading,
+    )
+    return pipeline, transcription, clipboard
+
+
+AUDIO = np.zeros(1600, dtype=np.float32)
+
+
+class TestRun:
+    def test_happy_path_pastes_and_saves_history(self, db):
+        pipeline, transcription, clipboard = make_pipeline(db)
+
+        text = pipeline.run(AUDIO)
+
+        assert text == "hello world"
+        clipboard.paste_at_cursor.assert_called_once_with("hello world")
+        history = db.get_history()
+        assert len(history) == 1
+        assert history[0]["text"] == "hello world"
+
+    def test_prepend_space_setting(self, db):
+        pipeline, _, clipboard = make_pipeline(
+            db, settings=Settings(prepend_space=True)
+        )
+
+        text = pipeline.run(AUDIO)
+
+        assert text == " hello world"
+        clipboard.paste_at_cursor.assert_called_once_with(" hello world")
+
+    def test_empty_transcript_skips_paste_and_history(self, db):
+        pipeline, _, clipboard = make_pipeline(db, transcript="")
+
+        assert pipeline.run(AUDIO) == ""
+        clipboard.paste_at_cursor.assert_not_called()
+        assert db.get_history() == []
+
+    def test_model_absent_skips_transcription(self, db):
+        pipeline, transcription, _ = make_pipeline(
+            db, model_loaded=False, model_loading=False
+        )
+
+        assert pipeline.run(AUDIO) == ""
+        transcription.transcribe.assert_not_called()
+
+    def test_model_timeout_returns_empty(self, db):
+        pipeline, transcription, _ = make_pipeline(
+            db, model_loaded=False, model_loading=True
+        )
+
+        # Tiny timeout so the test is fast.
+        assert pipeline.wait_for_model(timeout_s=0.02, poll_s=0.01) == "timeout"
+        transcription.transcribe.assert_not_called()
+
+    def test_transcription_error_propagates(self, db):
+        pipeline, transcription, clipboard = make_pipeline(db)
+        transcription.transcribe.side_effect = RuntimeError("boom")
+
+        with pytest.raises(RuntimeError):
+            pipeline.run(AUDIO)
+        clipboard.paste_at_cursor.assert_not_called()
+
+    def test_save_audio_attachment_writes_wav_and_metadata(self, db):
+        pipeline, _, _ = make_pipeline(
+            db, settings=Settings(save_audio_to_history=True)
+        )
+
+        text = pipeline.run(AUDIO)
+        assert text == "hello world"
+
+        entry = db.get_history(include_audio_meta=True)[0]
+        assert entry["audio_relpath"] == f"audio/history_{entry['id']}.wav"
+        wav_path = db.db_path.parent / entry["audio_relpath"]
+        assert wav_path.exists()
+        with wave.open(str(wav_path), "rb") as wf:
+            assert wf.getframerate() == 16000
+            assert wf.getnchannels() == 1
+        # 1600 samples @ 16 kHz = 100 ms
+        assert entry["audio_duration_ms"] == 100
+
+
+class TestWaitForModel:
+    def test_ready_immediately(self, db):
+        pipeline, _, _ = make_pipeline(db, model_loaded=True)
+        assert pipeline.wait_for_model() == "ready"
+
+    def test_absent(self, db):
+        pipeline, _, _ = make_pipeline(db, model_loaded=False, model_loading=False)
+        assert pipeline.wait_for_model() == "absent"
diff --git a/src-pyloid/tests/test_meeting_jobs.py b/src-pyloid/tests/test_meeting_jobs.py
new file mode 100644
index 0000000..e34f5aa
--- /dev/null
+++ b/src-pyloid/tests/test_meeting_jobs.py
@@ -0,0 +1,406 @@
+"""Tests for the MeetingsController background job runners.
+
+Covers `_run_transcribe` / `_run_summarize` plus the public `transcribe()` /
+`summarize()` entry points that enqueue them onto the serial job queues
+(`_SerialJobQueue` — one daemon worker per lane).
+
+These are pure characterization tests: they lock in CURRENT behavior. No
+network, no real whisper models — the TranscriptionService is a fake and the
+LLM provider class is patched at the controller module boundary
+(`services.recording.controller.OpenAICompatibleProvider`).
+
+Determinism notes:
+  * Jobs run on the queue's worker thread. Happy-path tests gate the fake
+    work function on a threading.Event released only after the public entry
+    point has returned, then wait for the completion event with a bounded
+    poll (10 s ceiling, normally <50 ms).
+  * Error-path tests call the runner directly (`_run_transcribe(_Job(...))`)
+    on the test thread — single-threaded and fully deterministic.
+
+Behavioral quirks pinned here (intentional — test what the code does):
+  * `transcribe()` enqueues the job FIRST and only then writes
+    transcript_status="pending"; `summarize()` likewise enqueues before
+    writing summary_status="summarizing". (Tiny production race: a very fast
+    worker could in principle be overwritten by the late status write.)
+  * Missing-file error strings differ between DB and event:
+    DB transcript_error = "audio missing on disk", event error = "audio missing".
+  * Row-with-no-audio_relpath: DB error = "audio not found", event error =
+    "audio not found" (these DO match).
+  * `_run_summarize` with no transcript: DB summary_error = "no transcript yet",
+    event error = "no transcript".
+"""
+
+from __future__ import annotations
+
+import tempfile
+import threading
+import time
+import wave
+from pathlib import Path
+
+import pytest
+
+from services.database import DatabaseService
+from services.recording.controller import MeetingsController, _Job
+from services.settings import SettingsService
+from services.transcription import CancelToken
+
+
+# ────────────────────────────────────────────────────────────────── helpers
+
+
+def _wait_until(predicate, timeout=10.0, interval=0.01):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(interval)
+    return False
+
+
+def _make_wav(path: Path, seconds: float = 0.1, sample_rate: int = 16000) -> None:
+    """Tiny valid mono PCM16 WAV written with the stdlib wave module."""
+    n_frames = int(seconds * sample_rate)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate)
+        w.writeframes(b"\x00\x00" * n_frames)
+
+
+_FAKE_SEGMENTS = [
+    {"start_ms": 0, "end_ms": 1500, "text": "hello there"},
+    {"start_ms": 1500, "end_ms": 3000, "text": "general kenobi"},
+]
+_FAKE_TEXT = "hello there general kenobi"
+
+
+class _FakeTranscriptionService:
+    """Stands in for TranscriptionService. transcribe_file matches the real
+    signature in services/transcription.py:
+        transcribe_file(audio_path, language="auto", on_progress=None, cancel_token=None)
+    Optionally blocks on `gate` so tests control when the job "finishes".
+    """
+
+    def __init__(self):
+        self.gate: threading.Event | None = None
+        self.load_calls: list[tuple[str, str]] = []
+        self.transcribe_calls: list[dict] = []
+        self._lock = threading.Lock()
+        self._active = 0
+        self.max_concurrent = 0
+        self.sleep_s = 0.0
+
+    def load_model(self, model_name="tiny", device_preference="auto"):
+        self.load_calls.append((model_name, device_preference))
+
+    def transcribe_file(self, audio_path, language="auto", on_progress=None, cancel_token=None):
+        with self._lock:
+            self._active += 1
+            self.max_concurrent = max(self.max_concurrent, self._active)
+        try:
+            if self.gate is not None:
+                assert self.gate.wait(timeout=10.0), "test gate never released"
+            if self.sleep_s:
+                time.sleep(self.sleep_s)
+            with self._lock:
+                self.transcribe_calls.append({
+                    "audio_path": audio_path,
+                    "language": language,
+                })
+            if on_progress is not None:
+                on_progress(0.5, "hello there")
+            return {"text": _FAKE_TEXT, "segments": list(_FAKE_SEGMENTS), "language": "en"}
+        finally:
+            with self._lock:
+                self._active -= 1
+
+
+class _FakeProvider:
+    """Replaces OpenAICompatibleProvider in the controller module. Records
+    constructor kwargs and chat() calls; returns a deterministic summary."""
+
+    RESPONSE = "## TL;DR\nA deterministic fake summary."
+    instances: list["_FakeProvider"] = []
+    gate: threading.Event | None = None
+
+    def __init__(self, endpoint=None, api_key=None, default_model=None):
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.default_model = default_model
+        self.chat_calls: list[dict] = []
+        type(self).instances.append(self)
+
+    def chat(self, messages, model=None, on_stream=None, cancel_token=None):
+        if type(self).gate is not None:
+            assert type(self).gate.wait(timeout=10.0), "test gate never released"
+        self.chat_calls.append({"messages": messages, "model": model})
+        if on_stream is not None:
+            on_stream(self.RESPONSE)
+        return self.RESPONSE
+
+
+class _Env:
+    def __init__(self, ctrl, db, root, fake_ts, events):
+        self.ctrl = ctrl
+        self.db = db
+        self.root = root
+        self.fake_ts = fake_ts
+        self.events = events
+
+    def events_named(self, name):
+        return [payload for (n, payload) in list(self.events) if n == name]
+
+    def seed_recording(self, title="Quarterly planning sync", with_wav=True):
+        """Create a recording row. Title is deliberately NOT a default
+        timestamp title so _maybe_auto_rename_title short-circuits before it
+        ever constructs an LLM provider (no network)."""
+        rid = self.db.create_recording(title=title, sources=["mic"])
+        rel = f"recordings/{rid}_test.wav"
+        if with_wav:
+            _make_wav(self.root / rel)
+        self.db.set_recording_audio(
+            rid, audio_relpath=rel, duration_ms=100, size_bytes=3200,
+            sample_rate=16000, channels=1,
+        )
+        return rid
+
+
+@pytest.fixture
+def env():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        root = Path(tmpdir)
+        db = DatabaseService(root / "test.db")
+        settings = SettingsService(db)
+        fake_ts = _FakeTranscriptionService()
+        events: list[tuple[str, dict]] = []
+        _FakeProvider.instances = []
+        _FakeProvider.gate = None
+
+        ctrl = MeetingsController(
+            db=db,
+            settings_service=settings,
+            transcription_service=fake_ts,
+            data_root=root,
+            event_emitter=lambda name, payload: events.append((name, payload)),
+        )
+        try:
+            yield _Env(ctrl, db, root, fake_ts, events)
+        finally:
+            ctrl._transcribe_q.shutdown()
+            ctrl._summarize_q.shutdown()
+
+
+# ────────────────────────────────────────────────────── transcribe happy path
+
+
+class TestTranscribeHappyPath:
+    def test_transcribe_persists_transcript_segments_and_emits_complete(self, env):
+        rid = env.seed_recording()
+
+        # Gate the fake so the enqueue→pending-write in transcribe() is done
+        # before the worker can finish the job.
+        env.fake_ts.gate = threading.Event()
+        result = env.ctrl.transcribe(rid)
+        assert result == {"ok": True}
+        env.fake_ts.gate.set()
+
+        # Exact completion event name used in controller.py is
+        # "recording-transcribe-complete" (NOT "meetings.transcribe-complete").
+        assert _wait_until(
+            lambda: any(
+                p.get("recordingId") == rid and p.get("success") is True
+                for p in env.events_named("recording-transcribe-complete")
+            )
+        ), f"no successful complete event; events={env.events}"
+
+        row = env.db.get_recording(rid, include_segments=True)
+        assert row["transcript"] == _FAKE_TEXT
+        assert row["transcript_status"] == "done"
+        assert row["transcript_progress"] == 1.0
+        assert row["language"] == "en"
+        # transcript_model is whatever model _run_transcribe resolved + loaded.
+        assert env.fake_ts.load_calls, "load_model was never called"
+        assert row["transcript_model"] == env.fake_ts.load_calls[0][0]
+
+        got_segments = [
+            {"start_ms": s["start_ms"], "end_ms": s["end_ms"], "text": s["text"]}
+            for s in row["segments"]
+        ]
+        assert got_segments == _FAKE_SEGMENTS
+
+        # transcribe_file received the on-disk audio path and a language.
+        call = env.fake_ts.transcribe_calls[0]
+        assert call["audio_path"] == str(env.root / row["audio_relpath"])
+
+        # on_progress is forwarded as a recording-transcribe-progress event.
+        progress = env.events_named("recording-transcribe-progress")
+        assert any(
+            p["recordingId"] == rid and p["progress"] == 0.5
+            and p["currentText"] == "hello there"
+            for p in progress
+        )
+
+        # Auto-summarize is off by default → nothing landed on the summarize
+        # lane and summary_status is untouched.
+        assert env.events_named("recording-summarize-complete") == []
+
+    def test_title_not_auto_renamed_when_user_titled(self, env):
+        # Custom (non-timestamp) title → _maybe_auto_rename_title skips before
+        # constructing any LLM provider. Locks in the no-network guarantee the
+        # happy-path tests rely on.
+        rid = env.seed_recording(title="Roadmap review with design")
+        env.ctrl.transcribe(rid)
+        assert _wait_until(
+            lambda: env.db.get_recording(rid)["transcript_status"] == "done"
+        )
+        assert env.db.get_recording(rid)["title"] == "Roadmap review with design"
+
+
+# ─────────────────────────────────────────────────── transcribe error paths
+
+
+class TestTranscribeErrors:
+    def test_missing_audio_file_sets_error_and_emits_failure(self, env):
+        # Row exists, audio_relpath set, but no file on disk. Run the job
+        # runner directly (single-threaded → deterministic).
+        rid = env.seed_recording(with_wav=False)
+
+        env.ctrl._run_transcribe(_Job(recording_id=rid, cancel_token=CancelToken()))
+
+        row = env.db.get_recording(rid)
+        assert row["transcript_status"] == "error"
+        # Quirk: DB error string and event error string differ.
+        assert row["transcript_error"] == "audio missing on disk"
+        assert env.events_named("recording-transcribe-complete") == [
+            {"recordingId": rid, "success": False, "error": "audio missing"}
+        ]
+        # Never reached the transcription service.
+        assert env.fake_ts.transcribe_calls == []
+
+    def test_recording_without_audio_relpath_errors_audio_not_found(self, env):
+        rid = env.db.create_recording(title="No audio yet", sources=["mic"])
+
+        env.ctrl._run_transcribe(_Job(recording_id=rid, cancel_token=CancelToken()))
+
+        row = env.db.get_recording(rid)
+        assert row["transcript_status"] == "error"
+        assert row["transcript_error"] == "audio not found"
+        assert env.events_named("recording-transcribe-complete") == [
+            {"recordingId": rid, "success": False, "error": "audio not found"}
+        ]
+
+
+# ──────────────────────────────────────────────────────── summarize happy path
+
+
+class TestSummarizeHappyPath:
+    def test_summarize_persists_summary_and_emits_complete(self, env, monkeypatch):
+        rid = env.seed_recording()
+        env.db.set_recording_transcript(rid, "we talked about roadmaps", language="en", model="tiny")
+        env.db.replace_recording_segments(rid, _FAKE_SEGMENTS)
+
+        # Patch the provider class where controller.py imported it, and the
+        # secrets accessors so no keyring/keychain is touched.
+        monkeypatch.setattr(
+            "services.recording.controller.OpenAICompatibleProvider", _FakeProvider
+        )
+        monkeypatch.setattr(
+            "services.recording.controller.get_api_key", lambda preset: "fake-key"
+        )
+        monkeypatch.setattr(
+            "services.recording.controller.has_api_key", lambda preset: True
+        )
+
+        _FakeProvider.gate = threading.Event()
+        result = env.ctrl.summarize(rid, prompt=None)
+        assert result == {"ok": True}
+        _FakeProvider.gate.set()
+
+        assert _wait_until(
+            lambda: any(
+                p.get("recordingId") == rid and p.get("success") is True
+                for p in env.events_named("recording-summarize-complete")
+            )
+        ), f"no successful summarize-complete event; events={env.events}"
+
+        row = env.db.get_recording(rid)
+        assert row["summary"] == _FakeProvider.RESPONSE
+        assert row["summary_status"] == "done"
+        assert row["summary_progress"] == 1.0
+        # Provider label is "<preset>:<model>" from the LLM config.
+        cfg = env.ctrl.get_llm_config()
+        assert row["summary_provider"] == f"{cfg['preset']}:{cfg['model']}"
+
+        # Provider was constructed from the LLM config + secret store.
+        provider = _FakeProvider.instances[0]
+        assert provider.endpoint == cfg["endpoint"]
+        assert provider.api_key == "fake-key"
+        assert provider.default_model == cfg["model"]
+        # Transcript was interpolated into the prompt sent to the LLM.
+        sent = provider.chat_calls[0]["messages"][-1]["content"]
+        assert "we talked about roadmaps" in sent
+
+        # Streaming tokens surface as recording-summarize-progress events.
+        progress = env.events_named("recording-summarize-progress")
+        assert any(
+            p["recordingId"] == rid and p["partialText"] == _FakeProvider.RESPONSE
+            for p in progress
+        )
+
+
+# ───────────────────────────────────────────────────── summarize error paths
+
+
+class TestSummarizeNoTranscript:
+    def test_no_transcript_sets_error_status_and_emits_failure(self, env):
+        # No transcript on the row → _run_summarize bails before constructing
+        # a provider (no patching needed; nothing external is touched).
+        rid = env.seed_recording()
+
+        env.ctrl._run_summarize(_Job(recording_id=rid, cancel_token=CancelToken()))
+
+        row = env.db.get_recording(rid)
+        assert row["summary_status"] == "error"
+        # Quirk: DB says "no transcript yet", event says "no transcript".
+        assert row["summary_error"] == "no transcript yet"
+        assert row["summary"] is None
+        assert env.events_named("recording-summarize-complete") == [
+            {"recordingId": rid, "success": False, "error": "no transcript"}
+        ]
+
+
+# ───────────────────────────────────────────────────────── queue serialization
+
+
+class TestSerialJobQueue:
+    def test_two_transcribe_jobs_run_serially_and_both_complete(self, env):
+        rid1 = env.seed_recording(title="First standup")
+        rid2 = env.seed_recording(title="Second standup")
+
+        # Small sleep inside the fake so an (incorrectly) parallel queue would
+        # show max_concurrent > 1.
+        env.fake_ts.sleep_s = 0.05
+
+        env.ctrl.transcribe(rid1)
+        env.ctrl.transcribe(rid2)
+
+        assert _wait_until(
+            lambda: len([
+                p for p in env.events_named("recording-transcribe-complete")
+                if p.get("success") is True
+            ]) == 2
+        ), f"both jobs did not complete; events={env.events}"
+
+        assert env.db.get_recording(rid1)["transcript_status"] == "done"
+        assert env.db.get_recording(rid2)["transcript_status"] == "done"
+        # _SerialJobQueue runs one worker thread → never more than one job
+        # in flight, and jobs finish in enqueue order.
+        assert env.fake_ts.max_concurrent == 1
+        completed = [
+            p["recordingId"]
+            for p in env.events_named("recording-transcribe-complete")
+            if p["success"]
+        ]
+        assert completed == [rid1, rid2]
diff --git a/src-pyloid/tests/test_model_manager.py b/src-pyloid/tests/test_model_manager.py
index ad757c8..558e7d7 100644
--- a/src-pyloid/tests/test_model_manager.py
+++ b/src-pyloid/tests/test_model_manager.py
@@ -498,6 +498,90 @@ def test_update_tracks_bytes_even_when_self_n_stays_zero(self):
             f"expected our counter to track bytes, got {bar._vf_n}"
 
 
+class TestDownloadSession:
+    """Tests for the single-flight background download session.
+
+    start_download/cancel_download/get_download_status own the lifecycle that
+    used to live as module globals in server.py. We patch download_model so no
+    network happens — only the session bookkeeping and event emission matter.
+    """
+
+    @pytest.fixture
+    def manager(self):
+        from services.model_manager import ModelManager
+        return ModelManager()
+
+    def test_already_cached_emits_complete_without_session(self, manager):
+        events = []
+        with patch.object(manager, "is_model_cached", return_value=True):
+            result = manager.start_download("tiny", lambda n, p: events.append((n, p)))
+
+        assert result == {"success": True, "alreadyCached": True}
+        assert events == [("download-complete", {
+            "model": "tiny", "success": True, "alreadyCached": True
+        })]
+        # No active session was created
+        assert manager.get_download_status() == {"active": False, "model": None}
+
+    def test_start_emits_progress_and_completion(self, manager):
+        from services.model_manager import DownloadProgress
+        import threading
+
+        events = []
+        done = threading.Event()
+
+        def fake_download(model_name, on_progress, token):
+            on_progress(DownloadProgress(model_name, 50.0, 5, 10, 100, 1))
+            return True
+
+        def emit(name, payload):
+            events.append((name, payload))
+            if name == "download-complete":
+                done.set()
+
+        with patch.object(manager, "is_model_cached", return_value=False), \
+             patch.object(manager, "download_model", side_effect=fake_download):
+            manager.start_download("base", emit)
+            assert done.wait(timeout=2), "download-complete never emitted"
+
+        names = [n for n, _ in events]
+        assert names == ["download-progress", "download-complete"]
+        progress = events[0][1]
+        assert progress["model"] == "base"
+        assert progress["downloadedBytes"] == 5
+        complete = events[1][1]
+        assert complete == {"model": "base", "success": True, "cancelled": False}
+
+    def test_status_reports_in_flight_progress(self, manager):
+        from services.model_manager import DownloadProgress
+        import threading
+
+        release = threading.Event()
+        saw_progress = threading.Event()
+
+        def fake_download(model_name, on_progress, token):
+            on_progress(DownloadProgress(model_name, 25.0, 250, 1000, 50, 15))
+            saw_progress.set()
+            release.wait(timeout=2)  # hold the session open
+            return True
+
+        with patch.object(manager, "is_model_cached", return_value=False), \
+             patch.object(manager, "download_model", side_effect=fake_download):
+            manager.start_download("small", lambda n, p: None)
+            assert saw_progress.wait(timeout=2)
+
+            status = manager.get_download_status()
+            assert status["active"] is True
+            assert status["model"] == "small"
+            assert status["percent"] == 25.0
+            assert status["downloadedBytes"] == 250
+
+            release.set()
+
+    def test_cancel_with_no_active_download(self, manager):
+        assert manager.cancel_download() == {"success": True, "cancelled": False}
+
+
 class TestDeleteModel:
     """Tests for single-model deletion.
 
diff --git a/src-pyloid/tests/test_recordings_repository.py b/src-pyloid/tests/test_recordings_repository.py
new file mode 100644
index 0000000..d59e04d
--- /dev/null
+++ b/src-pyloid/tests/test_recordings_repository.py
@@ -0,0 +1,68 @@
+"""Focused tests for RecordingsRepository (services/recording/repository.py).
+
+test_recordings_repo.py already exercises most moved methods through the
+DatabaseService delegating methods; this file covers what that one doesn't:
+
+  * the `db.recordings` attribute is the repository and is what the
+    delegates forward to (same rows visible from both surfaces),
+  * `set_recording_transcript` (not covered by test_recordings_repo.py),
+    including the COALESCE semantics for language / transcript_model.
+"""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from services.database import DatabaseService
+from services.recording.repository import RecordingsRepository
+
+
+@pytest.fixture
+def db():
+    with tempfile.TemporaryDirectory() as tmpdir:
+        yield DatabaseService(Path(tmpdir) / "test.db")
+
+
+@pytest.fixture
+def repo(db):
+    return db.recordings
+
+
+class TestRepositoryWiring:
+    def test_db_exposes_recordings_repository(self, db):
+        assert isinstance(db.recordings, RecordingsRepository)
+
+    def test_delegates_and_repo_share_the_same_table(self, db, repo):
+        rid = repo.create_recording(title="via repo", sources=["mic"])
+        # Visible through the backward-compat delegate...
+        assert db.get_recording(rid)["title"] == "via repo"
+        # ...and writes through the delegate are visible through the repo.
+        db.update_recording(rid, title="via delegate")
+        assert repo.get_recording(rid)["title"] == "via delegate"
+
+
+class TestSetRecordingTranscript:
+    def test_round_trip(self, repo):
+        rid = repo.create_recording(title="x", sources=["mic"])
+        repo.set_recording_transcript(rid, "hello world", language="en", model="tiny")
+        rec = repo.get_recording(rid)
+        assert rec["transcript"] == "hello world"
+        assert rec["language"] == "en"
+        assert rec["transcript_model"] == "tiny"
+
+    def test_none_language_and_model_preserve_existing(self, repo):
+        rid = repo.create_recording(title="x", sources=["mic"])
+        repo.set_recording_transcript(rid, "first", language="en", model="tiny")
+        # Re-transcribe without language/model must not clear the columns.
+        repo.set_recording_transcript(rid, "second")
+        rec = repo.get_recording(rid)
+        assert rec["transcript"] == "second"
+        assert rec["language"] == "en"
+        assert rec["transcript_model"] == "tiny"
+
+    def test_bumps_updated_at(self, repo):
+        rid = repo.create_recording(title="x", sources=["mic"])
+        before = repo.get_recording(rid)["updated_at"]
+        repo.set_recording_transcript(rid, "t")
+        assert repo.get_recording(rid)["updated_at"] >= before
diff --git a/src-pyloid/tests/test_settings.py b/src-pyloid/tests/test_settings.py
index 25823ae..2765205 100644
--- a/src-pyloid/tests/test_settings.py
+++ b/src-pyloid/tests/test_settings.py
@@ -28,7 +28,7 @@ def test_get_default_settings(self, settings_service):
         assert settings.model == "tiny"
         assert settings.auto_start == True
         assert settings.retention == -1  # Forever
-        assert settings.theme == "system"
+        assert settings.theme == "dark"
         assert settings.onboarding_complete == False
 
     def test_update_language(self, settings_service):
diff --git a/src-pyloid/tests/test_settings_rpc.py b/src-pyloid/tests/test_settings_rpc.py
new file mode 100644
index 0000000..f17b1ff
--- /dev/null
+++ b/src-pyloid/tests/test_settings_rpc.py
@@ -0,0 +1,68 @@
+"""Drift guards for the settings RPC surface.
+
+The Settings dataclass is the single schema (services/settings.py); these
+tests pin the derived pieces together so a new setting can't silently miss
+one layer — the failure mode that broke the prependSpace toggle (exposed in
+get_settings but absent from server.update_settings's signature).
+"""
+
+import inspect
+from dataclasses import fields
+
+import pytest
+
+from services.settings import (
+    RPC_SETTINGS_FIELDS,
+    Settings,
+    rpc_to_settings_kwargs,
+    settings_to_rpc,
+    to_camel_case,
+)
+
+
+class TestCamelCase:
+    def test_single_word_unchanged(self):
+        assert to_camel_case("language") == "language"
+
+    def test_multi_word(self):
+        assert to_camel_case("auto_start") == "autoStart"
+        assert to_camel_case("recordings_auto_rename_title") == "recordingsAutoRenameTitle"
+
+
+class TestSchemaConsistency:
+    def test_rpc_fields_are_real_settings_fields(self):
+        names = {f.name for f in fields(Settings)}
+        for name in RPC_SETTINGS_FIELDS:
+            assert name in names, f"RPC_SETTINGS_FIELDS lists unknown field {name}"
+
+    def test_settings_to_rpc_uses_camel_aliases(self):
+        d = settings_to_rpc(Settings())
+        assert set(d) == {to_camel_case(n) for n in RPC_SETTINGS_FIELDS}
+        assert "autoStart" in d
+        assert "prependSpace" in d  # the field the old hand-written maps lost
+
+    def test_rpc_kwargs_round_trip(self):
+        payload = settings_to_rpc(Settings(prepend_space=True, model="base"))
+        mapped = rpc_to_settings_kwargs(payload)
+        assert mapped["prepend_space"] is True
+        assert mapped["model"] == "base"
+        assert set(mapped) == set(RPC_SETTINGS_FIELDS)
+
+    def test_rpc_kwargs_drops_unknown_keys(self):
+        mapped = rpc_to_settings_kwargs({"notASetting": 1, "model": "tiny"})
+        assert mapped == {"model": "tiny"}
+
+
+class TestServerSignatureCoversSchema:
+    """server.update_settings declares explicit keyword params (the RPC
+    contract); every RPC-exposed setting must appear there or the frontend
+    can't set it."""
+
+    def test_every_rpc_field_is_a_server_param(self):
+        server = pytest.importorskip("server")
+        params = set(inspect.signature(server.update_settings).parameters)
+        missing = [
+            to_camel_case(n) for n in RPC_SETTINGS_FIELDS
+            if to_camel_case(n) not in params
+        ]
+        assert not missing, f"server.update_settings missing params: {missing}"
diff --git a/src-pyloid/tests/test_ui_event_bridge.py b/src-pyloid/tests/test_ui_event_bridge.py
new file mode 100644
index 0000000..7010173
--- /dev/null
+++ b/src-pyloid/tests/test_ui_event_bridge.py
@@ -0,0 +1,86 @@
+"""Tests for UiEventBridge — the single backend→UI event pathway.
+
+Queued Qt delivery needs a QCoreApplication and event-loop processing; these
+tests drive the loop manually with processEvents()."""
+
+import threading
+import time
+
+import pytest
+
+pytest.importorskip("PySide6")
+from PySide6.QtCore import QCoreApplication
+
+from services.ui_event_bridge import UiEventBridge
+
+
+@pytest.fixture(scope="module")
+def qt_app():
+    app = QCoreApplication.instance() or QCoreApplication([])
+    yield app
+
+
+def _pump_until(app, predicate, timeout_s=5.0):
+    deadline = time.monotonic() + timeout_s
+    while not predicate() and time.monotonic() < deadline:
+        app.processEvents()
+        time.sleep(0.005)
+    return predicate()
+
+
+class TestUiEventBridge:
+    def test_dispatches_to_registered_handler(self, qt_app):
+        bridge = UiEventBridge()
+        received = []
+        bridge.on("ptt-amplitude", received.append)
+
+        bridge.emit_event("ptt-amplitude", 0.5)
+
+        assert _pump_until(qt_app, lambda: received == [0.5])
+
+    def test_unregistered_event_is_dropped(self, qt_app):
+        bridge = UiEventBridge()
+        received = []
+        bridge.on("handled", received.append)
+
+        bridge.emit_event("recording-transcribe-progress", {"x": 1})
+        bridge.emit_event("handled", "ok")
+
+        assert _pump_until(qt_app, lambda: received == ["ok"])
+
+    def test_cross_thread_emit_delivers_on_pumping_thread(self, qt_app):
+        bridge = UiEventBridge()
+        received = []
+        handler_thread = []
+
+        def handler(payload):
+            handler_thread.append(threading.current_thread())
+            received.append(payload)
+
+        bridge.on("meeting-state", handler)
+
+        t = threading.Thread(
+            target=lambda: bridge.emit_event("meeting-state", {"state": "recording"})
+        )
+        t.start()
+        t.join()
+
+        assert _pump_until(qt_app, lambda: received == [{"state": "recording"}])
+        # Queued delivery: handler ran on the thread pumping the Qt loop
+        # (this test's main thread), not the emitting thread.
+        assert handler_thread == [threading.main_thread()]
+
+    def test_handler_exception_does_not_break_bridge(self, qt_app):
+        bridge = UiEventBridge()
+        received = []
+
+        def bad_handler(_payload):
+            raise RuntimeError("boom")
+
+        bridge.on("bad", bad_handler)
+        bridge.on("good", received.append)
+
+        bridge.emit_event("bad", None)
+        bridge.emit_event("good", 1)
+
+        assert _pump_until(qt_app, lambda: received == [1])
diff --git a/src/components/ModelDownloadProgress.tsx b/src/components/ModelDownloadProgress.tsx
index e21137c..4049baa 100644
--- a/src/components/ModelDownloadProgress.tsx
+++ b/src/components/ModelDownloadProgress.tsx
@@ -1,29 +1,10 @@
-import { useEffect, useState, useCallback, useRef } from "react";
+import { useEffect, useState } from "react";
 import { Download, X, Check, AlertCircle, Loader2, ExternalLink } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
 import { api } from "@/lib/api";
-import type { DownloadProgress, DownloadComplete } from "@/lib/types";
-
-// HuggingFace URLs for manual download
-const MODEL_HUGGINGFACE_URLS: Record<string, string> = {
-  "tiny": "https://huggingface.co/Systran/faster-whisper-tiny",
-  "base": "https://huggingface.co/Systran/faster-whisper-base",
-  "small": "https://huggingface.co/Systran/faster-whisper-small",
-  "medium": "https://huggingface.co/Systran/faster-whisper-medium",
-  "large-v1": "https://huggingface.co/Systran/faster-whisper-large-v1",
-  "large-v2": "https://huggingface.co/Systran/faster-whisper-large-v2",
-  "large-v3": "https://huggingface.co/Systran/faster-whisper-large-v3",
-  "turbo": "https://huggingface.co/Systran/faster-whisper-large-v3-turbo",
-  "tiny.en": "https://huggingface.co/Systran/faster-whisper-tiny.en",
-  "base.en": "https://huggingface.co/Systran/faster-whisper-base.en",
-  "small.en": "https://huggingface.co/Systran/faster-whisper-small.en",
-  "medium.en": "https://huggingface.co/Systran/faster-whisper-medium.en",
-  "distil-small.en": "https://huggingface.co/Systran/faster-distil-whisper-small.en",
-  "distil-medium.en": "https://huggingface.co/Systran/faster-distil-whisper-medium.en",
-  "distil-large-v2": "https://huggingface.co/Systran/faster-distil-whisper-large-v2",
-  "distil-large-v3": "https://huggingface.co/Systran/faster-distil-whisper-large-v3",
-};
+import { huggingFaceUrl } from "@/lib/models";
+import { useModelDownload } from "@/hooks/useModelDownload";
 
 interface ModelDownloadProgressProps {
   modelName: string;
@@ -52,8 +33,6 @@ function formatEta(seconds: number): string {
   return `${mins}:${secs.toString().padStart(2, "0")}`;
 }
 
-type DownloadState = "idle" | "downloading" | "completed" | "cancelled" | "error";
-
 export function ModelDownloadProgress({
   modelName,
   onStart,
@@ -61,92 +40,26 @@ export function ModelDownloadProgress({
   onCancel,
   autoStart = true,
 }: ModelDownloadProgressProps) {
-  const [state, setState] = useState<DownloadState>("idle");
-  const [progress, setProgress] = useState<DownloadProgress | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const hasStarted = useRef(false);
-
-  // Handle download progress events
-  const handleProgress = useCallback((e: CustomEvent<DownloadProgress>) => {
-    setProgress(e.detail);
-  }, []);
-
-  // Handle download complete events
-  const handleCompleteEvent = useCallback(
-    (e: CustomEvent<DownloadComplete>) => {
-      const result = e.detail;
-
-      if (result.success) {
-        setState("completed");
-        onComplete(true);
-      } else if (result.cancelled) {
-        setState("cancelled");
-        onCancel?.();
-      } else {
-        setState("error");
-        setError(result.error || "Download failed");
-        onComplete(false);
-      }
-    },
-    [onComplete, onCancel]
-  );
-
-  // Set up event listeners
+  const { state, progress, error, cancel, retry } = useModelDownload(modelName, {
+    autoStart,
+    onStart,
+    onComplete,
+    onCancel,
+  });
+
+  // Repo id powers the manual-download fallback in the error state. Fetched
+  // once from the backend rather than hardcoding a URL map on the frontend.
+  const [repoId, setRepoId] = useState<string | null>(null);
   useEffect(() => {
-    document.addEventListener("download-progress", handleProgress as EventListener);
-    document.addEventListener("download-complete", handleCompleteEvent as EventListener);
-
+    let active = true;
+    api
+      .getModelInfo(modelName)
+      .then((info) => active && setRepoId(info.repoId))
+      .catch(() => {});
     return () => {
-      document.removeEventListener("download-progress", handleProgress as EventListener);
-      document.removeEventListener("download-complete", handleCompleteEvent as EventListener);
+      active = false;
     };
-  }, [handleProgress, handleCompleteEvent]);
-
-  // Auto-start download
-  useEffect(() => {
-    if (autoStart && !hasStarted.current && state === "idle") {
-      hasStarted.current = true;
-      startDownload();
-    }
-  // eslint-disable-next-line react-hooks/exhaustive-deps -- startDownload is guarded by hasStarted.current ref
-  }, [autoStart, state]);
-
-  const startDownload = async () => {
-    try {
-      setError(null);
-
-      const result = await api.startModelDownload(modelName);
-
-      if (result.alreadyCached) {
-        // Model was already cached, show completed state immediately
-        setState("completed");
-      } else {
-        // Actually downloading - notify parent
-        setState("downloading");
-        onStart?.();
-      }
-    } catch (err) {
-      setState("error");
-      setError(err instanceof Error ? err.message : "Failed to start download");
-    }
-  };
-
-  const handleCancel = async () => {
-    try {
-      await api.cancelModelDownload();
-      // Don't update state here - wait for the complete event
-    } catch (err) {
-      console.error("Failed to cancel download:", err);
-    }
-  };
-
-  const handleRetry = () => {
-    hasStarted.current = false;
-    setState("idle");
-    setError(null);
-    setProgress(null);
-    startDownload();
-  };
+  }, [modelName]);
 
   // Render based on state
   if (state === "completed") {
@@ -168,7 +81,7 @@ export function ModelDownloadProgress({
   }
 
   if (state === "error") {
-    const huggingFaceUrl = MODEL_HUGGINGFACE_URLS[modelName];
+    const hfUrl = huggingFaceUrl(repoId);
 
     return (
       <div className="space-y-4 max-w-md w-full">
@@ -183,14 +96,14 @@ export function ModelDownloadProgress({
             {error || "An error occurred"}
           </p>
           <div className="flex flex-col gap-2">
-            <Button onClick={handleRetry} variant="outline" className="rounded-xl">
+            <Button onClick={retry} variant="outline" className="rounded-xl">
               Try Again
             </Button>
-            {huggingFaceUrl && (
+            {hfUrl && (
               <Button
                 variant="ghost"
                 className="rounded-xl text-xs"
-                onClick={() => api.openExternalUrl(huggingFaceUrl)}
+                onClick={() => api.openExternalUrl(hfUrl)}
               >
                 <ExternalLink className="w-3 h-3 mr-1.5" />
                 Download from HuggingFace
@@ -199,7 +112,7 @@ export function ModelDownloadProgress({
           </div>
         </div>
 
-        {huggingFaceUrl && (
+        {hfUrl && (
           <div className="glass-card p-4 text-left">
             <p className="text-xs font-medium text-foreground mb-2">Manual Download Instructions:</p>
             <ol className="text-xs text-muted-foreground space-y-1.5 list-decimal list-inside">
@@ -232,7 +145,7 @@ export function ModelDownloadProgress({
           <p className="text-sm text-muted-foreground mb-4">
             The model download was cancelled
           </p>
-          <Button onClick={handleRetry} variant="outline" className="rounded-xl">
+          <Button onClick={retry} variant="outline" className="rounded-xl">
             Start Again
           </Button>
         </div>
@@ -292,7 +205,7 @@ export function ModelDownloadProgress({
       {/* Cancel button */}
       <Button
         variant="ghost"
-        onClick={handleCancel}
+        onClick={cancel}
         className="w-full rounded-xl text-muted-foreground hover:text-destructive"
       >
         <X className="w-4 h-4 mr-2" />
diff --git a/src/components/SettingsTab.tsx b/src/components/SettingsTab.tsx
index 9918b8c..de38e0c 100644
--- a/src/components/SettingsTab.tsx
+++ b/src/components/SettingsTab.tsx
@@ -37,39 +37,13 @@ import {
 } from "@/components/ui/alert-dialog";
 import { api } from "@/lib/api";
 import type { Settings, Options, GpuInfo } from "@/lib/types";
+import { getModelOption, modelSizeMb, modelVram } from "@/lib/models";
 import { ModelDownloadModal } from "./ModelDownloadModal";
 import { HotkeyCapture } from "./HotkeyCapture";
 import { LLMSettingsSection } from "./meetings/LLMSettingsSection";
 import { MeetingsSettingsSection } from "./meetings/MeetingsSettingsSection";
 import { cn } from "@/lib/utils";
 
-// Hardcoded faster-whisper spec sheet. The backend exposes only model names,
-// so size/VRAM/speed/accuracy live here as the source of truth for the picker.
-type ModelMeta = {
-  sizeMb: number;
-  vram: string;
-  speed: 1 | 2 | 3 | 4 | 5;
-  accuracy: 1 | 2 | 3 | 4 | 5;
-  tagline: string;
-};
-
-const MODEL_META: Record<string, ModelMeta> = {
-  tiny:   { sizeMb: 75,   vram: "~1 GB",  speed: 5, accuracy: 1, tagline: "Fastest. Drafts and rough notes." },
-  base:   { sizeMb: 142,  vram: "~1 GB",  speed: 5, accuracy: 2, tagline: "Light footprint. Casual dictation." },
-  small:  { sizeMb: 466,  vram: "~2 GB",  speed: 4, accuracy: 3, tagline: "Balanced. Comfortable on CPU." },
-  medium: { sizeMb: 1500, vram: "~5 GB",  speed: 2, accuracy: 4, tagline: "More accurate. Heavier on resources." },
-  large:  { sizeMb: 2900, vram: "~10 GB", speed: 1, accuracy: 5, tagline: "Highest accuracy. Slowest." },
-  turbo:  { sizeMb: 1600, vram: "~6 GB",  speed: 4, accuracy: 5, tagline: "Fast and accurate. Recommended for GPU." },
-};
-
-const FALLBACK_META: ModelMeta = {
-  sizeMb: 0,
-  vram: "—",
-  speed: 3,
-  accuracy: 3,
-  tagline: "",
-};
-
 const THEME_ICONS: Record<string, React.ElementType> = {
   light: Sun,
   dark: Moon,
@@ -754,7 +728,10 @@ function ModelPicker({
   return (
     <div className="border border-border rounded-md overflow-hidden bg-surface">
       {models.map((model, i) => {
-        const meta = MODEL_META[model] ?? FALLBACK_META;
+        const option = getModelOption(model);
+        const tagline = option?.tradeoff ?? "";
+        const speed = option?.speed ?? 3;
+        const accuracy = option?.accuracy ?? 3;
         const cached = statuses[model];
         const isActive = model === currentModel;
         const cacheState =
@@ -800,14 +777,14 @@ function ModelPicker({
                   )}
                 </div>
                 <p className="text-xs text-cream-muted mt-1 truncate">
-                  {meta.tagline}
+                  {tagline}
                 </p>
               </div>
               <div className="hidden sm:flex items-center gap-6 flex-shrink-0">
-                <ModelMetaCol label="size" value={formatModelSize(meta.sizeMb)} />
-                <ModelMetaCol label="vram" value={meta.vram} />
-                <DotMeter label="speed" value={meta.speed} />
-                <DotMeter label="accuracy" value={meta.accuracy} />
+                <ModelMetaCol label="size" value={formatModelSize(modelSizeMb(model))} />
+                <ModelMetaCol label="vram" value={modelVram(model)} />
+                <DotMeter label="speed" value={speed} />
+                <DotMeter label="accuracy" value={accuracy} />
               </div>
             </button>
             {canDelete && <ModelDeleteButton model={model} onDelete={onDelete} />}
diff --git a/src/components/meetings/MeetingRecorderContext.tsx b/src/components/meetings/MeetingRecorderContext.tsx
index d1fa1d7..26a7559 100644
--- a/src/components/meetings/MeetingRecorderContext.tsx
+++ b/src/components/meetings/MeetingRecorderContext.tsx
@@ -29,6 +29,7 @@ import {
   type ReactNode,
 } from "react";
 import { api } from "@/lib/api";
+import { useBackendEvent } from "@/hooks/useBackendEvent";
 import type { RecorderState, RecorderStateName } from "@/lib/types";
 
 interface RecorderContextValue {
@@ -101,22 +102,16 @@ export function MeetingRecorderProvider({ children }: { children: ReactNode }) {
   }, [applyState]);
 
   // Listen for backend push events. This is the primary state channel.
-  useEffect(() => {
-    const handler = (e: Event) => {
-      const detail = (e as CustomEvent<MeetingStateEvent>).detail;
-      if (!detail || typeof detail.state !== "string") return;
-      applyState({
-        state: detail.state,
-        recordingId: detail.recordingId ?? null,
-        durationMs: Number(detail.durationMs ?? 0),
-        micPeakDb: detail.micPeakDb ?? null,
-        loopbackPeakDb: detail.loopbackPeakDb ?? null,
-      });
-    };
-    document.addEventListener("meeting-state", handler as EventListener);
-    return () =>
-      document.removeEventListener("meeting-state", handler as EventListener);
-  }, [applyState]);
+  useBackendEvent<MeetingStateEvent>("meeting-state", (detail) => {
+    if (!detail || typeof detail.state !== "string") return;
+    applyState({
+      state: detail.state,
+      recordingId: detail.recordingId ?? null,
+      durationMs: Number(detail.durationMs ?? 0),
+      micPeakDb: detail.micPeakDb ?? null,
+      loopbackPeakDb: detail.loopbackPeakDb ?? null,
+    });
+  });
 
   // Initial probe at mount — covers two cases:
   //   - Page just loaded mid-recording (e.g. after dev-server hot-reload),
diff --git a/src/components/meetings/MeetingRecorderPage.tsx b/src/components/meetings/MeetingRecorderPage.tsx
index 5c72b1d..7b3c89e 100644
--- a/src/components/meetings/MeetingRecorderPage.tsx
+++ b/src/components/meetings/MeetingRecorderPage.tsx
@@ -7,7 +7,7 @@
    Layout matches the rest of the app: standard page shell + `SettingRow`-style
    form rows so the visual rhythm tracks Settings. */
 
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { ArrowLeft, Mic, Monitor, Pause, Play, Square } from "lucide-react";
 import { toast } from "sonner";
@@ -25,6 +25,7 @@ import type { AudioSource } from "@/lib/types";
 import { cn } from "@/lib/utils";
 import { LevelMeter } from "./LevelMeter";
 import { useMeetingRecorder } from "./MeetingRecorderContext";
+import { useAudioSourcePreview } from "./useAudioSourcePreview";
 import { formatDuration } from "./utils";
 
 const NONE_VALUE = "__none__";
@@ -46,9 +47,7 @@ export function MeetingRecorderPage() {
 
   // Pre-record source preview — opens the picked source(s) without recording
   // so the user can confirm levels are flowing.
-  const [previewMicDb, setPreviewMicDb] = useState<number | null>(null);
-  const [previewLoopDb, setPreviewLoopDb] = useState<number | null>(null);
-  const previewActiveKey = useRef<string>("");
+  const preview = useAudioSourcePreview(micId, loopId, isLive);
 
   useEffect(() => {
     let cancelled = false;
@@ -73,72 +72,6 @@ export function MeetingRecorderPage() {
     };
   }, []);
 
-  // Drive the source preview from the currently-picked dropdown values.
-  useEffect(() => {
-    if (isLive) {
-      previewActiveKey.current = "";
-      return;
-    }
-    const key = `${micId || "-"}|${loopId || "-"}`;
-    if (key === "-|-") {
-      previewActiveKey.current = "";
-      api.recordingsPreviewStop().catch(() => {});
-      setPreviewMicDb(null);
-      setPreviewLoopDb(null);
-      return;
-    }
-    previewActiveKey.current = key;
-    let cancelled = false;
-    (async () => {
-      const result = await api
-        .recordingsPreviewStart(
-          micId ? Number(micId) : null,
-          loopId ? Number(loopId) : null,
-        )
-        .catch((err: unknown) => {
-          console.warn("preview start failed", err);
-          return { ok: false } as const;
-        });
-      if (cancelled || previewActiveKey.current !== key) return;
-      if (!result.ok) {
-        setPreviewMicDb(null);
-        setPreviewLoopDb(null);
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [micId, loopId, isLive]);
-
-  useEffect(() => {
-    return () => {
-      api.recordingsPreviewStop().catch(() => {});
-    };
-  }, []);
-
-  useEffect(() => {
-    if (isLive) return;
-    const hasAny = micId !== "" || loopId !== "";
-    if (!hasAny) return;
-    let cancelled = false;
-    const tick = async () => {
-      try {
-        const st = await api.recordingsPreviewState();
-        if (cancelled) return;
-        setPreviewMicDb(st.hasMic ? st.micPeakDb : null);
-        setPreviewLoopDb(st.hasLoopback ? st.loopbackPeakDb : null);
-      } catch {
-        /* RPC blip — keep last value. */
-      }
-    };
-    tick();
-    const id = window.setInterval(tick, 200);
-    return () => {
-      cancelled = true;
-      window.clearInterval(id);
-    };
-  }, [micId, loopId, isLive]);
-
   const handleStart = async () => {
     if (!micId && !loopId) {
       toast.error("Pick at least one source");
@@ -146,9 +79,7 @@ export function MeetingRecorderPage() {
     }
     setStarting(true);
     try {
-      previewActiveKey.current = "";
-      setPreviewMicDb(null);
-      setPreviewLoopDb(null);
+      preview.clear();
       await api.recordingsStart(
         title || defaultTitle(),
         micId ? Number(micId) : null,
@@ -220,8 +151,8 @@ export function MeetingRecorderPage() {
             onMic={setMicId}
             loopId={loopId}
             onLoop={setLoopId}
-            previewMicDb={previewMicDb}
-            previewLoopDb={previewLoopDb}
+            previewMicDb={preview.micPeakDb}
+            previewLoopDb={preview.loopbackPeakDb}
             onStart={handleStart}
             starting={starting}
           />
diff --git a/src/components/meetings/useAudioSourcePreview.ts b/src/components/meetings/useAudioSourcePreview.ts
new file mode 100644
index 0000000..563f881
--- /dev/null
+++ b/src/components/meetings/useAudioSourcePreview.ts
@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { api } from "@/lib/api";
+
+/* Pre-record source preview. Opens the picked source(s) backend-side without
+   recording so the user can confirm levels are flowing, polls peak levels at
+   5 Hz, and stops the preview on deselection/unmount. Suspended while a
+   recording is live — the live meters take over there.
+
+   `clear()` resets the preview before starting a real recording so the
+   preview stream releases the devices first. */
+export function useAudioSourcePreview(
+  micId: string,
+  loopId: string,
+  isLive: boolean,
+) {
+  const [micPeakDb, setMicPeakDb] = useState<number | null>(null);
+  const [loopbackPeakDb, setLoopbackPeakDb] = useState<number | null>(null);
+  const activeKey = useRef<string>("");
+
+  // Drive the source preview from the currently-picked dropdown values.
+  useEffect(() => {
+    if (isLive) {
+      activeKey.current = "";
+      api.recordingsPreviewStop().catch(() => {});
+      setMicPeakDb(null);
+      setLoopbackPeakDb(null);
+      return;
+    }
+    const key = `${micId || "-"}|${loopId || "-"}`;
+    if (key === "-|-") {
+      activeKey.current = "";
+      api.recordingsPreviewStop().catch(() => {});
+      setMicPeakDb(null);
+      setLoopbackPeakDb(null);
+      return;
+    }
+    activeKey.current = key;
+    let cancelled = false;
+    (async () => {
+      const result = await api
+        .recordingsPreviewStart(
+          micId ? Number(micId) : null,
+          loopId ? Number(loopId) : null,
+        )
+        .catch((err: unknown) => {
+          console.warn("preview start failed", err);
+          return { ok: false } as const;
+        });
+      if (cancelled || activeKey.current !== key) return;
+      if (!result.ok) {
+        setMicPeakDb(null);
+        setLoopbackPeakDb(null);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [micId, loopId, isLive]);
+
+  // Always release the preview stream on unmount.
+  useEffect(() => {
+    return () => {
+      api.recordingsPreviewStop().catch(() => {});
+    };
+  }, []);
+
+  // Poll peak levels while a preview is active.
+  useEffect(() => {
+    if (isLive) return;
+    const hasAny = micId !== "" || loopId !== "";
+    if (!hasAny) return;
+    let cancelled = false;
+    const tick = async () => {
+      try {
+        const st = await api.recordingsPreviewState();
+        if (cancelled) return;
+        setMicPeakDb(st.hasMic ? st.micPeakDb : null);
+        setLoopbackPeakDb(st.hasLoopback ? st.loopbackPeakDb : null);
+      } catch {
+        /* RPC blip — keep last value. */
+      }
+    };
+    tick();
+    const id = window.setInterval(tick, 200);
+    return () => {
+      cancelled = true;
+      window.clearInterval(id);
+    };
+  }, [micId, loopId, isLive]);
+
+  const clear = useCallback(() => {
+    activeKey.current = "";
+    api.recordingsPreviewStop().catch(() => {});
+    setMicPeakDb(null);
+    setLoopbackPeakDb(null);
+  }, []);
+
+  return { micPeakDb, loopbackPeakDb, clear };
+}
diff --git a/src/components/ui/dialog.tsx b/src/components/ui/dialog.tsx
index 6cb123b..2d706ec 100644
--- a/src/components/ui/dialog.tsx
+++ b/src/components/ui/dialog.tsx
@@ -28,12 +28,13 @@ function DialogClose({
   return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
 }
 
-function DialogOverlay({
-  className,
-  ...props
-}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentProps<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => {
   return (
     <DialogPrimitive.Overlay
+      ref={ref}
       data-slot="dialog-overlay"
       className={cn(
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
@@ -42,7 +43,8 @@ function DialogOverlay({
       {...props}
     />
   )
-}
+})
+DialogOverlay.displayName = "DialogOverlay"
 
 function DialogContent({
   className,
diff --git a/src/hooks/useBackendEvent.ts b/src/hooks/useBackendEvent.ts
new file mode 100644
index 0000000..97d4df2
--- /dev/null
+++ b/src/hooks/useBackendEvent.ts
@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Subscribe to a CustomEvent dispatched on `document` by the Python backend
+ * (window.invoke → CustomEvent bridge). Handles the EventListener cast and
+ * add/remove pairing in one place.
+ *
+ * The handler is held in a ref, so callers can pass inline closures without
+ * re-subscribing on every render — the subscription only resets if the event
+ * name changes.
+ */
+export function useBackendEvent<T>(name: string, handler: (detail: T) => void) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    const listener = (event: Event) => {
+      if (!(event instanceof CustomEvent)) return;
+      handlerRef.current(event.detail as T);
+    };
+    document.addEventListener(name, listener);
+    return () => document.removeEventListener(name, listener);
+  }, [name]);
+}
diff --git a/src/hooks/useModelDownload.ts b/src/hooks/useModelDownload.ts
new file mode 100644
index 0000000..189aa85
--- /dev/null
+++ b/src/hooks/useModelDownload.ts
@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { api } from "@/lib/api";
+import { useBackendEvent } from "@/hooks/useBackendEvent";
+import type { DownloadProgress, DownloadComplete } from "@/lib/types";
+
+export type DownloadState =
+  | "idle"
+  | "downloading"
+  | "completed"
+  | "cancelled"
+  | "error";
+
+interface UseModelDownloadOptions {
+  /** Begin downloading as soon as the hook mounts (default true). */
+  autoStart?: boolean;
+  onStart?: () => void;
+  onComplete?: (success: boolean) => void;
+  onCancel?: () => void;
+}
+
+interface UseModelDownload {
+  state: DownloadState;
+  progress: DownloadProgress | null;
+  error: string | null;
+  start: () => Promise<void>;
+  cancel: () => Promise<void>;
+  retry: () => void;
+}
+
+/**
+ * Owns the model-download state machine for one model.
+ *
+ * Before this hook the machine (5 states, 2 event subscriptions, start/cancel/
+ * retry) was re-implemented inline by ModelDownloadProgress and re-wired by
+ * SettingsTab, Onboarding, and the recovery/download modals. Now there is one
+ * interface and one place to test it.
+ *
+ * On mount it queries getDownloadStatus(): if a download for this model is
+ * already in flight (e.g. the user navigated away and came back), it re-attaches
+ * to that session instead of starting a duplicate.
+ */
+export function useModelDownload(
+  modelName: string,
+  { autoStart = true, onStart, onComplete, onCancel }: UseModelDownloadOptions = {}
+): UseModelDownload {
+  const [state, setState] = useState<DownloadState>("idle");
+  const [progress, setProgress] = useState<DownloadProgress | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const hasStarted = useRef(false);
+
+  // Only react to events for the model this hook tracks. The backend
+  // single-flights downloads, but filtering keeps stale events from a
+  // previous model out of this instance's state.
+  useBackendEvent<DownloadProgress>("download-progress", (p) => {
+    if (p.model === modelName) setProgress(p);
+  });
+
+  useBackendEvent<DownloadComplete>("download-complete", (result) => {
+    if (result.model !== modelName) return;
+    if (result.success) {
+      setState("completed");
+      onComplete?.(true);
+    } else if (result.cancelled) {
+      setState("cancelled");
+      onCancel?.();
+    } else {
+      setState("error");
+      setError(result.error || "Download failed");
+      onComplete?.(false);
+    }
+  });
+
+  const start = useCallback(async () => {
+    try {
+      setError(null);
+      const result = await api.startModelDownload(modelName);
+      if (result.alreadyCached) {
+        setState("completed");
+        onComplete?.(true);
+      } else {
+        setState("downloading");
+        onStart?.();
+      }
+    } catch (err) {
+      setState("error");
+      setError(err instanceof Error ? err.message : "Failed to start download");
+    }
+    // onStart is stable in practice; intentionally not a dep to avoid resubscribing
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [modelName]);
+
+  const cancel = useCallback(async () => {
+    try {
+      await api.cancelModelDownload();
+      // State transitions on the download-complete (cancelled) event.
+    } catch (err) {
+      console.error("Failed to cancel download:", err);
+    }
+  }, []);
+
+  const retry = useCallback(() => {
+    hasStarted.current = false;
+    setState("idle");
+    setError(null);
+    setProgress(null);
+    void start();
+  }, [start]);
+
+  // On mount: re-attach to an in-flight download for this model, else autoStart.
+  //
+  // The hasStarted ref guards against a double launch. We deliberately do NOT
+  // abort this run on effect cleanup: under React StrictMode the mount effect
+  // is invoked twice on the same instance (mount → cleanup → mount), so an
+  // abort-on-cleanup flag would cancel the only launched run while the ref
+  // guard blocks the retry — and the download would never start.
+  useEffect(() => {
+    if (!autoStart || hasStarted.current) return;
+    hasStarted.current = true;
+
+    (async () => {
+      try {
+        const status = await api.getDownloadStatus();
+        if (status.active && status.model === modelName) {
+          setState("downloading");
+          setProgress({
+            model: modelName,
+            percent: status.percent ?? 0,
+            downloadedBytes: status.downloadedBytes ?? 0,
+            totalBytes: status.totalBytes ?? 0,
+            speedBps: status.speedBps ?? 0,
+            etaSeconds: status.etaSeconds ?? 0,
+          });
+          onStart?.();
+          return;
+        }
+      } catch {
+        // Status probe failed — fall through to a normal start.
+      }
+      void start();
+    })();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [modelName, autoStart, start]);
+
+  return { state, progress, error, start, cancel, retry };
+}
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 5f8d951..5448ad2 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -11,6 +11,7 @@ import type {
   CudnnDownloadInfo,
   CudnnDownloadResult,
   CudnnDownloadProgress,
+  DownloadStatus,
   AudioSourceList,
   RecorderState,
   Recording,
@@ -124,6 +125,10 @@ export const api = {
     return rpc.call("cancel_model_download");
   },
 
+  async getDownloadStatus(): Promise<DownloadStatus> {
+    return rpc.call("get_download_status");
+  },
+
   async clearModelCache(): Promise<{ success: boolean; deleted_bytes: number; deleted_models: string[]; error: string | null }> {
     return rpc.call("clear_model_cache");
   },
diff --git a/src/lib/models.ts b/src/lib/models.ts
new file mode 100644
index 0000000..be74453
--- /dev/null
+++ b/src/lib/models.ts
@@ -0,0 +1,52 @@
+import { MODEL_OPTIONS } from "./constants";
+
+/**
+ * Frontend model-catalog helpers.
+ *
+ * `MODEL_OPTIONS` (constants.ts) is the single source of truth for model
+ * display metadata. Components read through these helpers instead of keeping
+ * their own (drift-prone) copies — SettingsTab used to maintain a 6-entry
+ * `MODEL_META` subset that left 10 models showing fallback specs.
+ *
+ * Repo ids / download URLs come from the backend (getModelInfo -> repoId),
+ * not from a hardcoded map here.
+ */
+
+export type ModelOption = (typeof MODEL_OPTIONS)[number];
+
+const BY_ID = new Map<string, ModelOption>(
+  MODEL_OPTIONS.map((m) => [m.id, m])
+);
+
+/** Look up a model's display metadata by id, or undefined if unknown. */
+export function getModelOption(id: string): ModelOption | undefined {
+  return BY_ID.get(id);
+}
+
+/** Parse the human-readable size string (e.g. "~466 MB", "~1.5 GB") to MB. */
+export function modelSizeMb(id: string): number {
+  const size = BY_ID.get(id)?.size;
+  if (!size) return 0;
+  const match = size.match(/([\d.]+)\s*(MB|GB)/i);
+  if (!match) return 0;
+  const value = parseFloat(match[1]);
+  return match[2].toUpperCase() === "GB" ? value * 1024 : value;
+}
+
+/** Approximate VRAM needed to run a model on GPU, derived from its size.
+ *  VRAM is inherently approximate, so deriving it from the size band avoids
+ *  maintaining yet another per-model table. */
+export function modelVram(id: string): string {
+  const mb = modelSizeMb(id);
+  if (mb === 0) return "—";
+  if (mb < 200) return "~1 GB";
+  if (mb < 600) return "~2 GB";
+  if (mb < 1100) return "~4 GB";
+  if (mb < 2200) return "~6 GB";
+  return "~10 GB";
+}
+
+/** Build the HuggingFace repo URL from a repo id. */
+export function huggingFaceUrl(repoId: string | undefined | null): string | null {
+  return repoId ? `https://huggingface.co/${repoId}` : null;
+}
diff --git a/src/lib/types.ts b/src/lib/types.ts
index 00eb361..be3b061 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -60,6 +60,21 @@ export interface ModelInfo {
   name: string;
   sizeBytes: number;
   cached: boolean;
+  /** HuggingFace repo id, e.g. "Systran/faster-whisper-tiny". Source of the
+   *  manual-download URL — the frontend no longer hardcodes the mapping. */
+  repoId: string;
+}
+
+/** Snapshot of an in-flight model download, returned by getDownloadStatus().
+ *  Lets a remounted view re-attach instead of losing the running download. */
+export interface DownloadStatus {
+  active: boolean;
+  model?: string | null;
+  percent?: number;
+  downloadedBytes?: number;
+  totalBytes?: number;
+  speedBps?: number;
+  etaSeconds?: number;
 }
 
 export interface DownloadProgress {
diff --git a/src/pages/Onboarding.tsx b/src/pages/Onboarding.tsx
index 3cc904f..d95b779 100644
--- a/src/pages/Onboarding.tsx
+++ b/src/pages/Onboarding.tsx
@@ -8,955 +8,21 @@ import {
   AlertCircle,
   Zap,
   Cpu,
-  Keyboard,
   Download,
   HardDrive,
   Sparkles,
 } from "lucide-react";
 import { Button } from "@/components/ui/button";
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@/components/ui/select";
-import { Switch } from "@/components/ui/switch";
-import { AudioVisualizer } from "@/components/AudioVisualizer";
 import { ModelDownloadProgress } from "@/components/ModelDownloadProgress";
 import { api } from "@/lib/api";
 import { cn } from "@/lib/utils";
 import type { Settings, Options, GpuInfo } from "@/lib/types";
-import {
-  MODEL_OPTIONS,
-  MODEL_CATEGORIES,
-  THEME_OPTIONS,
-  ONBOARDING_FEATURES,
-  isEnglishOnlyModel,
-} from "@/lib/constants";
-
-// ============================================================================
-// STEP: WELCOME
-// ============================================================================
-
-const StepWelcome = () => (
-  <div className="space-y-8 max-w-2xl w-full">
-    <p className="text-base md:text-lg leading-relaxed text-cream-muted text-center">
-      Dictation designed for{" "}
-      <span className="text-accent-500 font-medium">privacy</span> and{" "}
-      <span className="text-accent-500 font-medium">flow</span>.
-    </p>
-
-    <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
-      {ONBOARDING_FEATURES.map((feature) => (
-        <div
-          key={feature.label}
-          className="border border-border rounded-md bg-surface flex items-start gap-3 p-4 text-left"
-        >
-          <feature.icon
-            className="w-4 h-4 mt-0.5 flex-shrink-0 text-accent-500"
-            strokeWidth={2}
-          />
-          <div className="min-w-0">
-            <p className="font-medium text-cream text-sm leading-tight">
-              {feature.label}
-            </p>
-            <p className="text-[11px] text-cream-muted leading-relaxed mt-1">
-              {feature.desc}
-            </p>
-          </div>
-        </div>
-      ))}
-    </div>
-  </div>
-);
-
-// ============================================================================
-// STEP: AUDIO
-// ============================================================================
-
-const StepAudio = ({
-  microphone,
-  setMicrophone,
-  options,
-}: {
-  microphone: number;
-  setMicrophone: (id: number) => void;
-  options: Options;
-}) => {
-  const [amplitude, setAmplitude] = useState(0);
-  const [isListening, setIsListening] = useState(false);
-
-  useEffect(() => {
-    const handleAmplitude = (e: CustomEvent<number>) => {
-      setAmplitude(e.detail);
-    };
-    document.addEventListener("amplitude", handleAmplitude as EventListener);
-    return () => {
-      document.removeEventListener(
-        "amplitude",
-        handleAmplitude as EventListener
-      );
-    };
-  }, []);
-
-  useEffect(() => {
-    let mounted = true;
-    const startRecording = async () => {
-      try {
-        await api.updateSettings({ microphone });
-        await api.startTestRecording();
-        if (mounted) setIsListening(true);
-      } catch (error) {
-        console.error("[Audio] Failed to start test recording:", error);
-      }
-    };
-    const timer = setTimeout(startRecording, 100);
-    return () => {
-      mounted = false;
-      clearTimeout(timer);
-      api.stopTestRecording().catch(() => {});
-      setIsListening(false);
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  const handleDeviceChange = async (backendDeviceId: string) => {
-    const backendId = Number(backendDeviceId);
-    setMicrophone(backendId);
-    try {
-      await api.stopTestRecording();
-    } catch {
-      // ignore
-    }
-    try {
-      await api.updateSettings({ microphone: backendId });
-      await api.startTestRecording();
-      setIsListening(true);
-    } catch (error) {
-      console.error("[Audio] Failed to restart recording:", error);
-    }
-  };
-
-  return (
-    <div className="space-y-5 max-w-xl w-full">
-      <div>
-        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2">
-          input device
-        </p>
-        <Select value={String(microphone)} onValueChange={handleDeviceChange}>
-          <SelectTrigger className="h-12 text-sm bg-secondary/40 border-border hover:bg-secondary/60 transition-colors rounded-md">
-            <div className="flex items-center gap-2">
-              <Mic className="w-4 h-4 text-cream-muted/70" strokeWidth={2} />
-              <SelectValue placeholder="Select a microphone" />
-            </div>
-          </SelectTrigger>
-          <SelectContent>
-            {options.microphones.map((mic) => (
-              <SelectItem key={mic.id} value={String(mic.id)}>
-                {mic.name}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
-      </div>
-
-      <div>
-        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2 flex items-center justify-between">
-          <span>level meter</span>
-          <span
-            className={cn(
-              "flex items-center gap-1.5 normal-case tracking-normal text-[11px]",
-              isListening ? "text-accent-500" : "text-cream-muted/40"
-            )}
-          >
-            <span
-              className={cn(
-                "w-1.5 h-1.5 rounded-full",
-                isListening ? "bg-accent-500" : "bg-cream-muted/30"
-              )}
-            />
-            {isListening ? "listening" : "idle"}
-          </span>
-        </p>
-        <div className="h-24 w-full border border-border rounded-md bg-surface flex items-center justify-center px-4">
-          {isListening ? (
-            <AudioVisualizer
-              amplitude={amplitude}
-              bars={40}
-              className="gap-1 h-14 text-accent-500"
-            />
-          ) : (
-            <span className="font-mono text-xs text-cream-muted/60">
-              waiting for microphone…
-            </span>
-          )}
-        </div>
-      </div>
-
-      <p className="text-sm text-cream-muted leading-relaxed">
-        Speak now to test your input levels — the meter should respond to your
-        voice.
-      </p>
-    </div>
-  );
-};
-
-// ============================================================================
-// STEP: HARDWARE
-// ============================================================================
-
-const DEVICE_OPTIONS = [
-  {
-    id: "auto",
-    label: "Auto",
-    desc: "Recommended",
-    detail: "Best available",
-    description:
-      "Automatically selects the best available compute device. Uses GPU if available and properly configured, otherwise falls back to CPU.",
-    icon: Zap,
-    bestFor:
-      "Most users who want optimal performance without manual configuration.",
-  },
-  {
-    id: "cuda",
-    label: "CUDA GPU",
-    desc: "NVIDIA only",
-    detail: "Fastest",
-    description:
-      "Uses NVIDIA GPU with CUDA acceleration for maximum transcription speed. Requires compatible NVIDIA GPU with CUDA libraries (cuDNN + cuBLAS).",
-    icon: Cpu,
-    bestFor:
-      "Users with NVIDIA GPUs who want the fastest possible transcription.",
-  },
-  {
-    id: "cpu",
-    label: "CPU only",
-    desc: "Universal",
-    detail: "Compatible",
-    description:
-      "Uses CPU for transcription. Works on any system but slower than GPU acceleration. Good fallback option.",
-    icon: Cpu,
-    bestFor:
-      "Systems without compatible GPU or when GPU acceleration causes issues.",
-  },
-];
-
-const StepHardware = ({
-  device,
-  setDevice,
-  gpuInfo,
-  onGpuInfoUpdate,
-}: {
-  device: string;
-  setDevice: (d: string) => void;
-  gpuInfo: GpuInfo | null;
-  onGpuInfoUpdate: () => void;
-}) => {
-  const [deviceError, setDeviceError] = useState<string | null>(null);
-  const [downloading, setDownloading] = useState(false);
-  const [downloadError, setDownloadError] = useState<string | null>(null);
-  const [downloadProgress, setDownloadProgress] = useState<{
-    percent: number;
-    downloadedBytes: number;
-    totalBytes: number;
-  } | null>(null);
-
-  useEffect(() => {
-    if (!downloading) {
-      setDownloadProgress(null);
-      return;
-    }
-    const pollProgress = async () => {
-      try {
-        const progress = await api.getCudnnDownloadProgress();
-        if (progress.downloading) {
-          setDownloadProgress({
-            percent: progress.percent,
-            downloadedBytes: progress.downloadedBytes,
-            totalBytes: progress.totalBytes,
-          });
-        } else if (progress.complete) {
-          setDownloading(false);
-          if (progress.success) onGpuInfoUpdate();
-          else if (progress.error) setDownloadError(progress.error);
-        }
-      } catch (err) {
-        console.error("Failed to poll progress:", err);
-      }
-    };
-    const interval = setInterval(pollProgress, 500);
-    pollProgress();
-    return () => clearInterval(interval);
-  }, [downloading, onGpuInfoUpdate]);
-
-  const handleDeviceSelect = async (newDevice: string) => {
-    setDeviceError(null);
-    const validation = await api.validateDevice(newDevice);
-    if (!validation.valid) {
-      setDeviceError(validation.error);
-      return;
-    }
-    setDevice(newDevice);
-  };
-
-  const handleDownloadCudnn = async () => {
-    setDownloading(true);
-    setDownloadError(null);
-    setDownloadProgress(null);
-    try {
-      const result = await api.downloadCudnn();
-      if (!result.success) {
-        setDownloadError(result.error || "Failed to start download");
-        setDownloading(false);
-      }
-    } catch {
-      setDownloadError("Download failed. Check your internet connection.");
-      setDownloading(false);
-    }
-  };
-
-  const formatBytes = (bytes: number) => {
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-  };
-
-  const showDownloadButton = gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable;
-  const resolvedDevice =
-    device === "auto"
-      ? gpuInfo?.cudaAvailable
-        ? "cuda"
-        : "cpu"
-      : device;
-
-  return (
-    <div className="grid grid-cols-1 lg:grid-cols-[1fr_280px] gap-6 w-full max-w-5xl h-full min-h-0">
-      <div className="space-y-4 min-w-0 overflow-y-auto pr-2">
-        <div className="flex items-center justify-between">
-          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-            compute device
-          </p>
-          <p className="font-mono text-[10px] flex items-center gap-2">
-            <span className="text-cream-muted/40 uppercase tracking-widest">
-              resolves to
-            </span>
-            <span
-              className={cn(
-                resolvedDevice === "cuda"
-                  ? "text-accent-500"
-                  : "text-cream-muted",
-                "uppercase tracking-widest"
-              )}
-            >
-              {resolvedDevice}
-            </span>
-          </p>
-        </div>
-
-        <div
-          className="grid grid-cols-3 gap-2"
-          role="radiogroup"
-          aria-label="Select compute device"
-        >
-          {DEVICE_OPTIONS.map((d) => {
-            const isActive = device === d.id;
-            const isDisabled = d.id === "cuda" && !gpuInfo?.cudaAvailable;
-            return (
-              <button
-                key={d.id}
-                type="button"
-                role="radio"
-                aria-checked={isActive}
-                disabled={isDisabled}
-                className={cn(
-                  "relative p-4 rounded-md text-left transition-colors flex flex-col gap-2 border",
-                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
-                  isActive
-                    ? "bg-accent-500/[0.06] border-accent-500/40"
-                    : isDisabled
-                      ? "border-border bg-secondary/20 opacity-50 cursor-not-allowed"
-                      : "border-border bg-secondary/30 hover:bg-secondary/60"
-                )}
-                onClick={() => !isDisabled && handleDeviceSelect(d.id)}
-              >
-                <div className="flex items-center justify-between w-full">
-                  <span
-                    className={cn(
-                      "font-display text-sm font-medium tracking-tight",
-                      isActive ? "text-cream" : "text-cream"
-                    )}
-                  >
-                    {d.label}
-                  </span>
-                  {isActive && (
-                    <span
-                      className="w-1.5 h-1.5 rounded-full bg-accent-500 flex-shrink-0"
-                      aria-hidden="true"
-                    />
-                  )}
-                </div>
-                <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60">
-                  {d.desc}
-                </span>
-                {isDisabled && (
-                  <span className="font-mono text-[10px] uppercase tracking-widest text-amber-500/80 mt-auto">
-                    unavailable
-                  </span>
-                )}
-              </button>
-            );
-          })}
-        </div>
-
-        {deviceError && (
-          <p className="font-mono text-[11px] text-destructive flex items-center gap-2 border-l-2 border-destructive/40 pl-3 py-1">
-            <AlertCircle className="w-3.5 h-3.5 flex-shrink-0" strokeWidth={2} />
-            {deviceError}
-          </p>
-        )}
-
-        {showDownloadButton && (
-          <div className="border border-amber-500/30 bg-amber-500/[0.03] rounded-md p-4 space-y-3">
-            <div className="flex items-center gap-2">
-              <span className="w-1.5 h-1.5 rounded-full bg-amber-500" />
-              <p className="font-mono text-[11px] uppercase tracking-[0.2em] text-amber-500/90">
-                gpu acceleration available
-              </p>
-            </div>
-            <p className="text-xs text-cream-muted leading-relaxed">
-              Download NVIDIA CUDA libraries (cuDNN + cuBLAS) to enable GPU
-              acceleration.
-            </p>
-            <button
-              type="button"
-              onClick={handleDownloadCudnn}
-              disabled={downloading}
-              className="w-full flex items-center justify-center gap-2 h-10 rounded-md bg-accent-500 text-zinc-950 hover:bg-accent-600 transition-colors text-sm font-medium disabled:opacity-50"
-            >
-              {downloading ? (
-                <>
-                  <span className="w-3.5 h-3.5 border-2 border-current/30 border-t-current rounded-full animate-spin" />
-                  {downloadProgress
-                    ? `downloading… ${downloadProgress.percent}%`
-                    : "starting…"}
-                </>
-              ) : (
-                <>
-                  <Download className="w-4 h-4" strokeWidth={2.5} />
-                  Download CUDA libraries (~880 MB)
-                </>
-              )}
-            </button>
-            {downloading && downloadProgress && (
-              <div className="space-y-1.5">
-                <div className="h-1 w-full bg-secondary/50 rounded-full overflow-hidden">
-                  <div
-                    className="h-full bg-accent-500 transition-[width] duration-300 ease-out"
-                    style={{ width: `${downloadProgress.percent}%` }}
-                  />
-                </div>
-                <p className="font-mono text-[10px] text-cream-muted/70 text-center">
-                  {formatBytes(downloadProgress.downloadedBytes)} /{" "}
-                  {formatBytes(downloadProgress.totalBytes)}
-                </p>
-              </div>
-            )}
-            {downloadError && (
-              <p className="font-mono text-[11px] text-destructive">
-                {downloadError}
-              </p>
-            )}
-          </div>
-        )}
-      </div>
-
-      <HardwareDetailsPanel device={device} gpuInfo={gpuInfo} />
-    </div>
-  );
-};
-
-function HardwareDetailsPanel({
-  device,
-  gpuInfo,
-}: {
-  device: string;
-  gpuInfo: GpuInfo | null;
-}) {
-  const selected = DEVICE_OPTIONS.find((d) => d.id === device);
-  const status = gpuInfo?.cudaAvailable
-    ? { label: "ready", tone: "accent" as const }
-    : gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable
-      ? { label: "setup needed", tone: "amber" as const }
-      : { label: "cpu mode", tone: "muted" as const };
-
-  return (
-    <div className="border border-border rounded-md bg-surface p-5 space-y-5 h-full overflow-y-auto min-h-0">
-      {selected && (
-        <>
-          <div className="space-y-2">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              selection
-            </p>
-            <h3 className="font-display text-lg font-medium text-cream tracking-tight leading-tight">
-              {selected.label}
-            </h3>
-            <p className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60">
-              {selected.detail}
-            </p>
-          </div>
-
-          <div className="space-y-1.5 pt-4 border-t border-border">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              best for
-            </p>
-            <p className="text-xs text-cream-muted leading-relaxed">
-              {selected.bestFor}
-            </p>
-          </div>
-
-          <div className="space-y-1.5">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              about
-            </p>
-            <p className="text-[11px] text-cream-muted leading-relaxed">
-              {selected.description}
-            </p>
-          </div>
-        </>
-      )}
-
-      <div className="space-y-3 pt-4 border-t border-border">
-        <div className="flex items-center justify-between">
-          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-            hardware
-          </p>
-          <span
-            className={cn(
-              "font-mono text-[10px] uppercase tracking-widest",
-              status.tone === "accent" && "text-accent-500",
-              status.tone === "amber" && "text-amber-500",
-              status.tone === "muted" && "text-cream-muted/60"
-            )}
-          >
-            {status.label}
-          </span>
-        </div>
-
-        <dl className="font-mono text-[11px] grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
-          {gpuInfo?.gpuName && (
-            <>
-              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-                gpu
-              </dt>
-              <dd className="text-cream truncate" title={gpuInfo.gpuName}>
-                {gpuInfo.gpuName}
-              </dd>
-              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-                cuda
-              </dt>
-              <dd
-                className={
-                  gpuInfo.cudaAvailable ? "text-accent-500" : "text-cream-muted"
-                }
-              >
-                {gpuInfo.cudaAvailable ? "available" : "unavailable"}
-              </dd>
-              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-                cudnn
-              </dt>
-              <dd
-                className={
-                  gpuInfo.cudnnAvailable ? "text-accent-500" : "text-amber-500"
-                }
-              >
-                {gpuInfo.cudnnAvailable ? "installed" : "missing"}
-              </dd>
-            </>
-          )}
-          {!gpuInfo?.gpuName && (
-            <>
-              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-                device
-              </dt>
-              <dd className="text-cream">cpu only</dd>
-            </>
-          )}
-        </dl>
-
-        {gpuInfo?.supportedComputeTypes &&
-          gpuInfo.supportedComputeTypes.length > 0 && (
-            <div className="space-y-1.5">
-              <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-                compute types
-              </p>
-              <div className="flex flex-wrap gap-1">
-                {gpuInfo.supportedComputeTypes.map((ct) => (
-                  <span
-                    key={ct}
-                    className="font-mono text-[10px] px-1.5 py-0.5 rounded bg-secondary/50 text-cream-muted"
-                  >
-                    {ct}
-                  </span>
-                ))}
-              </div>
-            </div>
-          )}
-
-        <p className="text-[11px] text-cream-muted/70 leading-relaxed pt-1">
-          {gpuInfo?.cudaAvailable
-            ? "Your system is fully configured for GPU acceleration."
-            : gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable
-              ? "Download CUDA libraries from the left to enable GPU acceleration."
-              : "No compatible NVIDIA GPU detected. CPU transcription works well — just slower."}
-        </p>
-      </div>
-    </div>
-  );
-}
-
-// ============================================================================
-// STEP: MODEL
-// ============================================================================
-
-const RatingBar = ({
-  value,
-  max = 5,
-  label,
-}: {
-  value: number;
-  max?: number;
-  label: string;
-}) => (
-  <div className="flex items-center gap-3">
-    <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60 w-16 flex-shrink-0">
-      {label}
-    </span>
-    <div className="flex gap-0.5 flex-1">
-      {Array.from({ length: max }).map((_, i) => (
-        <div
-          key={i}
-          className={cn(
-            "h-1 flex-1 rounded-full",
-            i < value ? "bg-accent-500" : "bg-cream-muted/15"
-          )}
-        />
-      ))}
-    </div>
-  </div>
-);
-
-const StepModel = ({
-  language,
-  setLanguage,
-  model,
-  setModel,
-  options,
-  device,
-  gpuInfo,
-}: {
-  language: string;
-  setLanguage: (l: string) => void;
-  model: string;
-  setModel: (m: string) => void;
-  options: Options;
-  device: string;
-  gpuInfo: GpuInfo | null;
-}) => {
-  const selectedModel = MODEL_OPTIONS.find((m) => m.id === model);
-  const categoryInfo = selectedModel
-    ? MODEL_CATEGORIES[selectedModel.category]
-    : null;
-  const resolvedDevice =
-    device === "auto" ? (gpuInfo?.cudaAvailable ? "cuda" : "cpu") : device;
-
-  const handleModelSelect = (modelId: string) => {
-    setModel(modelId);
-    if (isEnglishOnlyModel(modelId) && language !== "en") setLanguage("en");
-  };
-
-  return (
-    <div className="grid grid-cols-1 lg:grid-cols-[1fr_280px] gap-6 w-full max-w-6xl h-full min-h-0">
-      <div className="space-y-5 min-w-0 overflow-y-auto pr-2">
-        <div>
-          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2">
-            language
-          </p>
-          <Select value={language} onValueChange={setLanguage}>
-            <SelectTrigger className="h-10 bg-secondary/40 border-border hover:bg-secondary/60 transition-colors rounded-md max-w-sm">
-              <SelectValue />
-            </SelectTrigger>
-            <SelectContent className="max-h-[280px]">
-              {options.languages.map((lang) => (
-                <SelectItem key={lang} value={lang}>
-                  {lang === "auto" ? "Auto-detect" : lang.toUpperCase()}
-                </SelectItem>
-              ))}
-            </SelectContent>
-          </Select>
-        </div>
-
-        <div className="space-y-3">
-          <div className="flex items-center justify-between">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              model
-            </p>
-            <div className="flex items-center gap-3 font-mono text-[10px] uppercase tracking-widest">
-              <span
-                className={
-                  resolvedDevice === "cuda"
-                    ? "text-accent-500"
-                    : "text-cream-muted/60"
-                }
-              >
-                {resolvedDevice}
-              </span>
-              <span className="text-cream-muted/30">·</span>
-              <span className="text-accent-500/80">local only</span>
-            </div>
-          </div>
-
-          <div
-            className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-2"
-            role="radiogroup"
-            aria-label="Select processing model"
-          >
-            {MODEL_OPTIONS.map((m) => {
-              const isActive = model === m.id;
-              return (
-                <button
-                  key={m.id}
-                  type="button"
-                  role="radio"
-                  aria-checked={isActive}
-                  className={cn(
-                    "relative p-3 rounded-md text-left transition-colors flex flex-col gap-1 border",
-                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
-                    isActive
-                      ? "bg-accent-500/[0.06] border-accent-500/40"
-                      : "border-border bg-secondary/30 hover:bg-secondary/60"
-                  )}
-                  onClick={() => handleModelSelect(m.id)}
-                >
-                  <div className="flex items-center justify-between w-full">
-                    <span className="font-display text-sm font-medium tracking-tight text-cream">
-                      {m.label}
-                    </span>
-                    {isActive && (
-                      <span
-                        className="w-1.5 h-1.5 rounded-full bg-accent-500 flex-shrink-0"
-                        aria-hidden="true"
-                      />
-                    )}
-                  </div>
-                  <span className="font-mono text-[10px] text-cream-muted/70">
-                    {m.detail}
-                  </span>
-                </button>
-              );
-            })}
-          </div>
-        </div>
-      </div>
-
-      {selectedModel && (
-        <div className="border border-border rounded-md bg-surface p-5 space-y-5 h-full overflow-y-auto min-h-0">
-          <div className="space-y-2">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 flex items-center justify-between">
-              <span>model</span>
-              {categoryInfo && (
-                <span
-                  className={cn(
-                    "normal-case tracking-normal text-[11px]",
-                    categoryInfo.color
-                  )}
-                >
-                  {categoryInfo.label}
-                </span>
-              )}
-            </p>
-            <h3 className="font-display text-lg font-medium text-cream tracking-tight leading-tight">
-              {selectedModel.label}
-            </h3>
-            <p className="text-xs text-cream-muted leading-relaxed">
-              {selectedModel.desc}
-            </p>
-          </div>
-
-          <div className="space-y-2 pt-4 border-t border-border">
-            <RatingBar value={selectedModel.speed} label="speed" />
-            <RatingBar value={selectedModel.accuracy} label="accuracy" />
-          </div>
-
-          <dl className="font-mono text-[11px] grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 pt-4 border-t border-border">
-            <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-              detail
-            </dt>
-            <dd className="text-cream">{selectedModel.detail}</dd>
-            <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
-              size
-            </dt>
-            <dd className="text-cream">{selectedModel.size}</dd>
-          </dl>
-
-          <div className="space-y-1.5 pt-4 border-t border-border">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              best for
-            </p>
-            <p className="text-xs text-cream-muted leading-relaxed">
-              {selectedModel.bestFor}
-            </p>
-          </div>
-
-          <div className="space-y-1.5">
-            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-              about
-            </p>
-            <p className="text-[11px] text-cream-muted leading-relaxed">
-              {selectedModel.description}
-            </p>
-          </div>
-        </div>
-      )}
-    </div>
-  );
-};
-
-// ============================================================================
-// STEP: THEME
-// ============================================================================
-
-const StepTheme = ({
-  theme,
-  setTheme,
-  autoStart,
-  setAutoStart,
-}: {
-  theme: Settings["theme"];
-  setTheme: (t: Settings["theme"]) => void;
-  autoStart: boolean;
-  setAutoStart: (b: boolean) => void;
-}) => (
-  <div className="space-y-8 max-w-md w-full">
-    <fieldset className="space-y-3">
-      <legend className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
-        interface theme
-      </legend>
-      <div
-        className="grid grid-cols-3 gap-3"
-        role="radiogroup"
-        aria-label="Theme selection"
-      >
-        {THEME_OPTIONS.map((opt) => {
-          const isActive = theme === opt.val;
-          return (
-            <button
-              key={opt.val}
-              type="button"
-              role="radio"
-              aria-checked={isActive}
-              className={cn(
-                "relative p-5 rounded-md flex flex-col items-center gap-3 transition-colors border",
-                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
-                isActive
-                  ? "border-accent-500/40 bg-accent-500/[0.06]"
-                  : "border-border bg-secondary/30 hover:bg-secondary/60"
-              )}
-              onClick={() => setTheme(opt.val as Settings["theme"])}
-            >
-              <div
-                className={cn(
-                  "w-12 h-12 rounded-md border border-border",
-                  opt.val === "light"
-                    ? "bg-[#fafafa]"
-                    : opt.val === "dark"
-                      ? "bg-[#09090b]"
-                      : "bg-gradient-to-br from-[#fafafa] to-[#09090b]"
-                )}
-                aria-hidden
-              />
-              <span
-                className={cn(
-                  "font-mono text-[11px] uppercase tracking-widest",
-                  isActive ? "text-cream" : "text-cream-muted"
-                )}
-              >
-                {opt.label}
-              </span>
-              {isActive && (
-                <span
-                  className="absolute top-2 right-2 w-1.5 h-1.5 rounded-full bg-accent-500"
-                  aria-hidden
-                />
-              )}
-            </button>
-          );
-        })}
-      </div>
-    </fieldset>
-
-    <div className="border-t border-border" />
-
-    <div className="flex items-start justify-between gap-6">
-      <div className="flex-1 min-w-0">
-        <label
-          htmlFor="onboarding-autostart"
-          className="text-sm font-medium text-cream cursor-pointer"
-        >
-          Launch at login
-        </label>
-        <p className="text-xs text-cream-muted mt-1 leading-relaxed">
-          Start VoiceFlow when you sign in to your computer.
-        </p>
-      </div>
-      <Switch
-        id="onboarding-autostart"
-        checked={autoStart}
-        onCheckedChange={setAutoStart}
-        className="mt-0.5 flex-shrink-0"
-      />
-    </div>
-  </div>
-);
-
-// ============================================================================
-// STEP: FINAL
-// ============================================================================
-
-const StepFinal = () => (
-  <div className="space-y-5 max-w-lg w-full">
-    <div className="border border-border rounded-md bg-surface p-8 space-y-5">
-      <div className="text-center space-y-3">
-        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 flex items-center justify-center gap-2">
-          <Keyboard className="w-3 h-3 text-accent-500" strokeWidth={2.5} />
-          global shortcut
-        </p>
-        <div className="flex items-center justify-center gap-3 pt-1">
-          <kbd className="min-w-[72px] py-2.5 rounded-md bg-secondary border border-border text-base font-mono font-medium text-cream">
-            Ctrl
-          </kbd>
-          <span className="text-base text-cream-muted/40 font-mono">+</span>
-          <kbd className="min-w-[72px] py-2.5 rounded-md bg-secondary border border-border text-base font-mono font-medium text-cream">
-            Win
-          </kbd>
-        </div>
-        <p className="text-sm text-cream-muted">
-          Hold to record, release to transcribe.
-        </p>
-      </div>
-    </div>
-
-    <div className="flex items-center gap-3 px-4 py-3 border-l-2 border-accent-500/40">
-      <Sparkles
-        className="w-4 h-4 text-accent-500 flex-shrink-0"
-        strokeWidth={2}
-      />
-      <p className="text-sm text-cream-muted leading-relaxed">
-        VoiceFlow runs quietly in your system tray. Press the shortcut anytime,
-        anywhere to start dictating.
-      </p>
-    </div>
-  </div>
-);
+import { StepWelcome } from "@/pages/onboarding/StepWelcome";
+import { StepAudio } from "@/pages/onboarding/StepAudio";
+import { StepHardware } from "@/pages/onboarding/StepHardware";
+import { StepModel } from "@/pages/onboarding/StepModel";
+import { StepTheme } from "@/pages/onboarding/StepTheme";
+import { StepFinal } from "@/pages/onboarding/StepFinal";
 
 // ============================================================================
 // STEP CONFIGURATION
diff --git a/src/pages/Popup.tsx b/src/pages/Popup.tsx
index b6eb283..cfbeafb 100644
--- a/src/pages/Popup.tsx
+++ b/src/pages/Popup.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState, useLayoutEffect, useRef } from "react";
 import { motion, AnimatePresence } from "framer-motion";
 import { api } from "@/lib/api";
+import { useBackendEvent } from "@/hooks/useBackendEvent";
 
 type PopupState =
   | "idle"
@@ -106,25 +107,17 @@ export function Popup() {
     };
   }, []);
 
-  useEffect(() => {
-    const handleAmplitude = (e: CustomEvent<number>) => setAmplitude(e.detail);
-    const handleState = (e: CustomEvent<{ state: PopupState; durationMs?: number }>) => {
-      const next = e.detail.state;
-      setState(next);
-      if (typeof e.detail.durationMs === "number") {
-        meetingBaseRef.current = { at: Date.now(), dur: e.detail.durationMs };
-        setMeetingDurationMs(e.detail.durationMs);
+  useBackendEvent<number>("amplitude", setAmplitude);
+  useBackendEvent<{ state: PopupState; durationMs?: number }>(
+    "popup-state",
+    (detail) => {
+      setState(detail.state);
+      if (typeof detail.durationMs === "number") {
+        meetingBaseRef.current = { at: Date.now(), dur: detail.durationMs };
+        setMeetingDurationMs(detail.durationMs);
       }
-    };
-
-    document.addEventListener("amplitude", handleAmplitude as EventListener);
-    document.addEventListener("popup-state", handleState as EventListener);
-
-    return () => {
-      document.removeEventListener("amplitude", handleAmplitude as EventListener);
-      document.removeEventListener("popup-state", handleState as EventListener);
-    };
-  }, []);
+    }
+  );
 
   // Client-side meeting duration ticker. Runs only while actively recording
   // (paused → frozen at whatever the backend last reported). Resyncs whenever
diff --git a/src/pages/onboarding/StepAudio.tsx b/src/pages/onboarding/StepAudio.tsx
new file mode 100644
index 0000000..6ab4784
--- /dev/null
+++ b/src/pages/onboarding/StepAudio.tsx
@@ -0,0 +1,136 @@
+import { useEffect, useState } from "react";
+import { Mic } from "lucide-react";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { AudioVisualizer } from "@/components/AudioVisualizer";
+import { api } from "@/lib/api";
+import { useBackendEvent } from "@/hooks/useBackendEvent";
+import { cn } from "@/lib/utils";
+import type { Options } from "@/lib/types";
+
+// ============================================================================
+// STEP: AUDIO
+// ============================================================================
+
+export const StepAudio = ({
+  microphone,
+  setMicrophone,
+  options,
+}: {
+  microphone: number;
+  setMicrophone: (id: number) => void;
+  options: Options;
+}) => {
+  const [amplitude, setAmplitude] = useState(0);
+  const [isListening, setIsListening] = useState(false);
+
+  useBackendEvent<number>("amplitude", setAmplitude);
+
+  useEffect(() => {
+    let mounted = true;
+    const startRecording = async () => {
+      try {
+        await api.updateSettings({ microphone });
+        await api.startTestRecording();
+        if (mounted) setIsListening(true);
+      } catch (error) {
+        console.error("[Audio] Failed to start test recording:", error);
+      }
+    };
+    const timer = setTimeout(startRecording, 100);
+    return () => {
+      mounted = false;
+      clearTimeout(timer);
+      api.stopTestRecording().catch(() => {});
+      setIsListening(false);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleDeviceChange = async (backendDeviceId: string) => {
+    const backendId = Number(backendDeviceId);
+    setIsListening(false);
+    try {
+      await api.stopTestRecording();
+    } catch {
+      // ignore
+    }
+    try {
+      await api.updateSettings({ microphone: backendId });
+      await api.startTestRecording();
+      setMicrophone(backendId);
+      setIsListening(true);
+    } catch (error) {
+      setIsListening(false);
+      console.error("[Audio] Failed to restart recording:", error);
+    }
+  };
+
+  return (
+    <div className="space-y-5 max-w-xl w-full">
+      <div>
+        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2">
+          input device
+        </p>
+        <Select value={String(microphone)} onValueChange={handleDeviceChange}>
+          <SelectTrigger className="h-12 text-sm bg-secondary/40 border-border hover:bg-secondary/60 transition-colors rounded-md">
+            <div className="flex items-center gap-2">
+              <Mic className="w-4 h-4 text-cream-muted/70" strokeWidth={2} />
+              <SelectValue placeholder="Select a microphone" />
+            </div>
+          </SelectTrigger>
+          <SelectContent>
+            {options.microphones.map((mic) => (
+              <SelectItem key={mic.id} value={String(mic.id)}>
+                {mic.name}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      <div>
+        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2 flex items-center justify-between">
+          <span>level meter</span>
+          <span
+            className={cn(
+              "flex items-center gap-1.5 normal-case tracking-normal text-[11px]",
+              isListening ? "text-accent-500" : "text-cream-muted/40"
+            )}
+          >
+            <span
+              className={cn(
+                "w-1.5 h-1.5 rounded-full",
+                isListening ? "bg-accent-500" : "bg-cream-muted/30"
+              )}
+            />
+            {isListening ? "listening" : "idle"}
+          </span>
+        </p>
+        <div className="h-24 w-full border border-border rounded-md bg-surface flex items-center justify-center px-4">
+          {isListening ? (
+            <AudioVisualizer
+              amplitude={amplitude}
+              bars={40}
+              className="gap-1 h-14 text-accent-500"
+            />
+          ) : (
+            <span className="font-mono text-xs text-cream-muted/60">
+              waiting for microphone…
+            </span>
+          )}
+        </div>
+      </div>
+
+      <p className="text-sm text-cream-muted leading-relaxed">
+        Speak now to test your input levels — the meter should respond to your
+        voice.
+      </p>
+    </div>
+  );
+};
diff --git a/src/pages/onboarding/StepFinal.tsx b/src/pages/onboarding/StepFinal.tsx
new file mode 100644
index 0000000..f1aa166
--- /dev/null
+++ b/src/pages/onboarding/StepFinal.tsx
@@ -0,0 +1,52 @@
+import { Keyboard, Sparkles } from "lucide-react";
+
+// ============================================================================
+// STEP: FINAL
+// ============================================================================
+
+// The default hold hotkey is `ctrl+win` on every platform (see settings.py),
+// but the Super key is labelled differently per OS — show the right one.
+const platform =
+  (navigator as unknown as { userAgentData?: { platform: string } }).userAgentData
+    ?.platform ?? navigator.userAgent;
+const superKeyLabel = /Mac/i.test(platform)
+  ? "⌘"
+  : /Linux/i.test(platform)
+    ? "Super"
+    : "Win";
+
+export const StepFinal = () => (
+  <div className="space-y-5 max-w-lg w-full">
+    <div className="border border-border rounded-md bg-surface p-8 space-y-5">
+      <div className="text-center space-y-3">
+        <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 flex items-center justify-center gap-2">
+          <Keyboard className="w-3 h-3 text-accent-500" strokeWidth={2.5} />
+          global shortcut
+        </p>
+        <div className="flex items-center justify-center gap-3 pt-1">
+          <kbd className="min-w-[72px] py-2.5 rounded-md bg-secondary border border-border text-base font-mono font-medium text-cream">
+            Ctrl
+          </kbd>
+          <span className="text-base text-cream-muted/40 font-mono">+</span>
+          <kbd className="min-w-[72px] py-2.5 rounded-md bg-secondary border border-border text-base font-mono font-medium text-cream">
+            {superKeyLabel}
+          </kbd>
+        </div>
+        <p className="text-sm text-cream-muted">
+          Hold to record, release to transcribe.
+        </p>
+      </div>
+    </div>
+
+    <div className="flex items-center gap-3 px-4 py-3 border-l-2 border-accent-500/40">
+      <Sparkles
+        className="w-4 h-4 text-accent-500 flex-shrink-0"
+        strokeWidth={2}
+      />
+      <p className="text-sm text-cream-muted leading-relaxed">
+        VoiceFlow runs quietly in your system tray. Press the shortcut anytime,
+        anywhere to start dictating.
+      </p>
+    </div>
+  </div>
+);
diff --git a/src/pages/onboarding/StepHardware.tsx b/src/pages/onboarding/StepHardware.tsx
new file mode 100644
index 0000000..0d27584
--- /dev/null
+++ b/src/pages/onboarding/StepHardware.tsx
@@ -0,0 +1,417 @@
+import { useEffect, useState } from "react";
+import { AlertCircle, Zap, Cpu, Download } from "lucide-react";
+import { api } from "@/lib/api";
+import { cn } from "@/lib/utils";
+import type { GpuInfo } from "@/lib/types";
+
+// ============================================================================
+// STEP: HARDWARE
+// ============================================================================
+
+const DEVICE_OPTIONS = [
+  {
+    id: "auto",
+    label: "Auto",
+    desc: "Recommended",
+    detail: "Best available",
+    description:
+      "Automatically selects the best available compute device. Uses GPU if available and properly configured, otherwise falls back to CPU.",
+    icon: Zap,
+    bestFor:
+      "Most users who want optimal performance without manual configuration.",
+  },
+  {
+    id: "cuda",
+    label: "CUDA GPU",
+    desc: "NVIDIA only",
+    detail: "Fastest",
+    description:
+      "Uses NVIDIA GPU with CUDA acceleration for maximum transcription speed. Requires compatible NVIDIA GPU with CUDA libraries (cuDNN + cuBLAS).",
+    icon: Cpu,
+    bestFor:
+      "Users with NVIDIA GPUs who want the fastest possible transcription.",
+  },
+  {
+    id: "cpu",
+    label: "CPU only",
+    desc: "Universal",
+    detail: "Compatible",
+    description:
+      "Uses CPU for transcription. Works on any system but slower than GPU acceleration. Good fallback option.",
+    icon: Cpu,
+    bestFor:
+      "Systems without compatible GPU or when GPU acceleration causes issues.",
+  },
+];
+
+export const StepHardware = ({
+  device,
+  setDevice,
+  gpuInfo,
+  onGpuInfoUpdate,
+}: {
+  device: string;
+  setDevice: (d: string) => void;
+  gpuInfo: GpuInfo | null;
+  onGpuInfoUpdate: () => void;
+}) => {
+  const [deviceError, setDeviceError] = useState<string | null>(null);
+  const [downloading, setDownloading] = useState(false);
+  const [downloadError, setDownloadError] = useState<string | null>(null);
+  const [downloadProgress, setDownloadProgress] = useState<{
+    percent: number;
+    downloadedBytes: number;
+    totalBytes: number;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!downloading) {
+      setDownloadProgress(null);
+      return;
+    }
+    const pollProgress = async () => {
+      try {
+        const progress = await api.getCudnnDownloadProgress();
+        if (progress.downloading) {
+          setDownloadProgress({
+            percent: progress.percent,
+            downloadedBytes: progress.downloadedBytes,
+            totalBytes: progress.totalBytes,
+          });
+        } else if (progress.complete) {
+          setDownloading(false);
+          if (progress.success) onGpuInfoUpdate();
+          else if (progress.error) setDownloadError(progress.error);
+        }
+      } catch (err) {
+        console.error("Failed to poll progress:", err);
+      }
+    };
+    const interval = setInterval(pollProgress, 500);
+    pollProgress();
+    return () => clearInterval(interval);
+  }, [downloading, onGpuInfoUpdate]);
+
+  const handleDeviceSelect = async (newDevice: string) => {
+    setDeviceError(null);
+    const validation = await api.validateDevice(newDevice);
+    if (!validation.valid) {
+      setDeviceError(validation.error);
+      return;
+    }
+    setDevice(newDevice);
+  };
+
+  const handleDownloadCudnn = async () => {
+    setDownloading(true);
+    setDownloadError(null);
+    setDownloadProgress(null);
+    try {
+      const result = await api.downloadCudnn();
+      if (!result.success) {
+        setDownloadError(result.error || "Failed to start download");
+        setDownloading(false);
+      }
+    } catch {
+      setDownloadError("Download failed. Check your internet connection.");
+      setDownloading(false);
+    }
+  };
+
+  const formatBytes = (bytes: number) => {
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  };
+
+  const showDownloadButton = gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable;
+  const resolvedDevice =
+    device === "auto"
+      ? gpuInfo?.cudaAvailable
+        ? "cuda"
+        : "cpu"
+      : device;
+
+  return (
+    <div className="grid grid-cols-1 lg:grid-cols-[1fr_280px] gap-6 w-full max-w-5xl h-full min-h-0">
+      <div className="space-y-4 min-w-0 overflow-y-auto pr-2">
+        <div className="flex items-center justify-between">
+          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+            compute device
+          </p>
+          <p className="font-mono text-[10px] flex items-center gap-2">
+            <span className="text-cream-muted/40 uppercase tracking-widest">
+              resolves to
+            </span>
+            <span
+              className={cn(
+                resolvedDevice === "cuda"
+                  ? "text-accent-500"
+                  : "text-cream-muted",
+                "uppercase tracking-widest"
+              )}
+            >
+              {resolvedDevice}
+            </span>
+          </p>
+        </div>
+
+        <div
+          className="grid grid-cols-3 gap-2"
+          role="radiogroup"
+          aria-label="Select compute device"
+        >
+          {DEVICE_OPTIONS.map((d) => {
+            const isActive = device === d.id;
+            const isDisabled = d.id === "cuda" && !gpuInfo?.cudaAvailable;
+            return (
+              <button
+                key={d.id}
+                type="button"
+                role="radio"
+                aria-checked={isActive}
+                disabled={isDisabled}
+                className={cn(
+                  "relative p-4 rounded-md text-left transition-colors flex flex-col gap-2 border",
+                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
+                  isActive
+                    ? "bg-accent-500/[0.06] border-accent-500/40"
+                    : isDisabled
+                      ? "border-border bg-secondary/20 opacity-50 cursor-not-allowed"
+                      : "border-border bg-secondary/30 hover:bg-secondary/60"
+                )}
+                onClick={() => !isDisabled && handleDeviceSelect(d.id)}
+              >
+                <div className="flex items-center justify-between w-full">
+                  <span
+                    className={cn(
+                      "font-display text-sm font-medium tracking-tight",
+                      isActive ? "text-cream" : "text-cream"
+                    )}
+                  >
+                    {d.label}
+                  </span>
+                  {isActive && (
+                    <span
+                      className="w-1.5 h-1.5 rounded-full bg-accent-500 flex-shrink-0"
+                      aria-hidden="true"
+                    />
+                  )}
+                </div>
+                <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60">
+                  {d.desc}
+                </span>
+                {isDisabled && (
+                  <span className="font-mono text-[10px] uppercase tracking-widest text-amber-500/80 mt-auto">
+                    unavailable
+                  </span>
+                )}
+              </button>
+            );
+          })}
+        </div>
+
+        {deviceError && (
+          <p className="font-mono text-[11px] text-destructive flex items-center gap-2 border-l-2 border-destructive/40 pl-3 py-1">
+            <AlertCircle className="w-3.5 h-3.5 flex-shrink-0" strokeWidth={2} />
+            {deviceError}
+          </p>
+        )}
+
+        {showDownloadButton && (
+          <div className="border border-amber-500/30 bg-amber-500/[0.03] rounded-md p-4 space-y-3">
+            <div className="flex items-center gap-2">
+              <span className="w-1.5 h-1.5 rounded-full bg-amber-500" />
+              <p className="font-mono text-[11px] uppercase tracking-[0.2em] text-amber-500/90">
+                gpu acceleration available
+              </p>
+            </div>
+            <p className="text-xs text-cream-muted leading-relaxed">
+              Download NVIDIA CUDA libraries (cuDNN + cuBLAS) to enable GPU
+              acceleration.
+            </p>
+            <button
+              type="button"
+              onClick={handleDownloadCudnn}
+              disabled={downloading}
+              className="w-full flex items-center justify-center gap-2 h-10 rounded-md bg-accent-500 text-zinc-950 hover:bg-accent-600 transition-colors text-sm font-medium disabled:opacity-50"
+            >
+              {downloading ? (
+                <>
+                  <span className="w-3.5 h-3.5 border-2 border-current/30 border-t-current rounded-full animate-spin" />
+                  {downloadProgress
+                    ? `downloading… ${downloadProgress.percent}%`
+                    : "starting…"}
+                </>
+              ) : (
+                <>
+                  <Download className="w-4 h-4" strokeWidth={2.5} />
+                  Download CUDA libraries (~880 MB)
+                </>
+              )}
+            </button>
+            {downloading && downloadProgress && (
+              <div className="space-y-1.5">
+                <div className="h-1 w-full bg-secondary/50 rounded-full overflow-hidden">
+                  <div
+                    className="h-full bg-accent-500 transition-[width] duration-300 ease-out"
+                    style={{ width: `${downloadProgress.percent}%` }}
+                  />
+                </div>
+                <p className="font-mono text-[10px] text-cream-muted/70 text-center">
+                  {formatBytes(downloadProgress.downloadedBytes)} /{" "}
+                  {formatBytes(downloadProgress.totalBytes)}
+                </p>
+              </div>
+            )}
+            {downloadError && (
+              <p className="font-mono text-[11px] text-destructive">
+                {downloadError}
+              </p>
+            )}
+          </div>
+        )}
+      </div>
+
+      <HardwareDetailsPanel device={device} gpuInfo={gpuInfo} />
+    </div>
+  );
+};
+
+function HardwareDetailsPanel({
+  device,
+  gpuInfo,
+}: {
+  device: string;
+  gpuInfo: GpuInfo | null;
+}) {
+  const selected = DEVICE_OPTIONS.find((d) => d.id === device);
+  const status = gpuInfo?.cudaAvailable
+    ? { label: "ready", tone: "accent" as const }
+    : gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable
+      ? { label: "setup needed", tone: "amber" as const }
+      : { label: "cpu mode", tone: "muted" as const };
+
+  return (
+    <div className="border border-border rounded-md bg-surface p-5 space-y-5 h-full overflow-y-auto min-h-0">
+      {selected && (
+        <>
+          <div className="space-y-2">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              selection
+            </p>
+            <h3 className="font-display text-lg font-medium text-cream tracking-tight leading-tight">
+              {selected.label}
+            </h3>
+            <p className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60">
+              {selected.detail}
+            </p>
+          </div>
+
+          <div className="space-y-1.5 pt-4 border-t border-border">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              best for
+            </p>
+            <p className="text-xs text-cream-muted leading-relaxed">
+              {selected.bestFor}
+            </p>
+          </div>
+
+          <div className="space-y-1.5">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              about
+            </p>
+            <p className="text-[11px] text-cream-muted leading-relaxed">
+              {selected.description}
+            </p>
+          </div>
+        </>
+      )}
+
+      <div className="space-y-3 pt-4 border-t border-border">
+        <div className="flex items-center justify-between">
+          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+            hardware
+          </p>
+          <span
+            className={cn(
+              "font-mono text-[10px] uppercase tracking-widest",
+              status.tone === "accent" && "text-accent-500",
+              status.tone === "amber" && "text-amber-500",
+              status.tone === "muted" && "text-cream-muted/60"
+            )}
+          >
+            {status.label}
+          </span>
+        </div>
+
+        <dl className="font-mono text-[11px] grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+          {gpuInfo?.gpuName && (
+            <>
+              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+                gpu
+              </dt>
+              <dd className="text-cream truncate" title={gpuInfo.gpuName}>
+                {gpuInfo.gpuName}
+              </dd>
+              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+                cuda
+              </dt>
+              <dd
+                className={
+                  gpuInfo.cudaAvailable ? "text-accent-500" : "text-cream-muted"
+                }
+              >
+                {gpuInfo.cudaAvailable ? "available" : "unavailable"}
+              </dd>
+              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+                cudnn
+              </dt>
+              <dd
+                className={
+                  gpuInfo.cudnnAvailable ? "text-accent-500" : "text-amber-500"
+                }
+              >
+                {gpuInfo.cudnnAvailable ? "installed" : "missing"}
+              </dd>
+            </>
+          )}
+          {!gpuInfo?.gpuName && (
+            <>
+              <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+                device
+              </dt>
+              <dd className="text-cream">cpu only</dd>
+            </>
+          )}
+        </dl>
+
+        {gpuInfo?.supportedComputeTypes &&
+          gpuInfo.supportedComputeTypes.length > 0 && (
+            <div className="space-y-1.5">
+              <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+                compute types
+              </p>
+              <div className="flex flex-wrap gap-1">
+                {gpuInfo.supportedComputeTypes.map((ct) => (
+                  <span
+                    key={ct}
+                    className="font-mono text-[10px] px-1.5 py-0.5 rounded bg-secondary/50 text-cream-muted"
+                  >
+                    {ct}
+                  </span>
+                ))}
+              </div>
+            </div>
+          )}
+
+        <p className="text-[11px] text-cream-muted/70 leading-relaxed pt-1">
+          {gpuInfo?.cudaAvailable
+            ? "Your system is fully configured for GPU acceleration."
+            : gpuInfo?.gpuName && !gpuInfo?.cudnnAvailable
+              ? "Download CUDA libraries from the left to enable GPU acceleration."
+              : "No compatible NVIDIA GPU detected. CPU transcription works well — just slower."}
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/onboarding/StepModel.tsx b/src/pages/onboarding/StepModel.tsx
new file mode 100644
index 0000000..2ee665b
--- /dev/null
+++ b/src/pages/onboarding/StepModel.tsx
@@ -0,0 +1,228 @@
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import type { Options, GpuInfo } from "@/lib/types";
+import {
+  MODEL_OPTIONS,
+  MODEL_CATEGORIES,
+  isEnglishOnlyModel,
+} from "@/lib/constants";
+
+// ============================================================================
+// STEP: MODEL
+// ============================================================================
+
+const RatingBar = ({
+  value,
+  max = 5,
+  label,
+}: {
+  value: number;
+  max?: number;
+  label: string;
+}) => (
+  <div className="flex items-center gap-3">
+    <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-cream-muted/60 w-16 flex-shrink-0">
+      {label}
+    </span>
+    <div className="flex gap-0.5 flex-1">
+      {Array.from({ length: max }).map((_, i) => (
+        <div
+          key={i}
+          className={cn(
+            "h-1 flex-1 rounded-full",
+            i < value ? "bg-accent-500" : "bg-cream-muted/15"
+          )}
+        />
+      ))}
+    </div>
+  </div>
+);
+
+export const StepModel = ({
+  language,
+  setLanguage,
+  model,
+  setModel,
+  options,
+  device,
+  gpuInfo,
+}: {
+  language: string;
+  setLanguage: (l: string) => void;
+  model: string;
+  setModel: (m: string) => void;
+  options: Options;
+  device: string;
+  gpuInfo: GpuInfo | null;
+}) => {
+  const selectedModel = MODEL_OPTIONS.find((m) => m.id === model);
+  const categoryInfo = selectedModel
+    ? MODEL_CATEGORIES[selectedModel.category]
+    : null;
+  const resolvedDevice =
+    device === "auto" ? (gpuInfo?.cudaAvailable ? "cuda" : "cpu") : device;
+
+  const handleModelSelect = (modelId: string) => {
+    setModel(modelId);
+    if (isEnglishOnlyModel(modelId) && language !== "en") setLanguage("en");
+  };
+
+  const handleLanguageChange = (nextLanguage: string) => {
+    // English-only models can't transcribe other languages — keep "en" locked
+    // in while one is selected.
+    if (isEnglishOnlyModel(model) && nextLanguage !== "en") return;
+    setLanguage(nextLanguage);
+  };
+
+  return (
+    <div className="grid grid-cols-1 lg:grid-cols-[1fr_280px] gap-6 w-full max-w-6xl h-full min-h-0">
+      <div className="space-y-5 min-w-0 overflow-y-auto pr-2">
+        <div>
+          <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 mb-2">
+            language
+          </p>
+          <Select value={language} onValueChange={handleLanguageChange}>
+            <SelectTrigger className="h-10 bg-secondary/40 border-border hover:bg-secondary/60 transition-colors rounded-md max-w-sm">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent className="max-h-[280px]">
+              {options.languages.map((lang) => (
+                <SelectItem key={lang} value={lang}>
+                  {lang === "auto" ? "Auto-detect" : lang.toUpperCase()}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+
+        <div className="space-y-3">
+          <div className="flex items-center justify-between">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              model
+            </p>
+            <div className="flex items-center gap-3 font-mono text-[10px] uppercase tracking-widest">
+              <span
+                className={
+                  resolvedDevice === "cuda"
+                    ? "text-accent-500"
+                    : "text-cream-muted/60"
+                }
+              >
+                {resolvedDevice}
+              </span>
+              <span className="text-cream-muted/30">·</span>
+              <span className="text-accent-500/80">local only</span>
+            </div>
+          </div>
+
+          <div
+            className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-2"
+            role="radiogroup"
+            aria-label="Select processing model"
+          >
+            {MODEL_OPTIONS.map((m) => {
+              const isActive = model === m.id;
+              return (
+                <button
+                  key={m.id}
+                  type="button"
+                  role="radio"
+                  aria-checked={isActive}
+                  className={cn(
+                    "relative p-3 rounded-md text-left transition-colors flex flex-col gap-1 border",
+                    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
+                    isActive
+                      ? "bg-accent-500/[0.06] border-accent-500/40"
+                      : "border-border bg-secondary/30 hover:bg-secondary/60"
+                  )}
+                  onClick={() => handleModelSelect(m.id)}
+                >
+                  <div className="flex items-center justify-between w-full">
+                    <span className="font-display text-sm font-medium tracking-tight text-cream">
+                      {m.label}
+                    </span>
+                    {isActive && (
+                      <span
+                        className="w-1.5 h-1.5 rounded-full bg-accent-500 flex-shrink-0"
+                        aria-hidden="true"
+                      />
+                    )}
+                  </div>
+                  <span className="font-mono text-[10px] text-cream-muted/70">
+                    {m.detail}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+
+      {selectedModel && (
+        <div className="border border-border rounded-md bg-surface p-5 space-y-5 h-full overflow-y-auto min-h-0">
+          <div className="space-y-2">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60 flex items-center justify-between">
+              <span>model</span>
+              {categoryInfo && (
+                <span
+                  className={cn(
+                    "normal-case tracking-normal text-[11px]",
+                    categoryInfo.color
+                  )}
+                >
+                  {categoryInfo.label}
+                </span>
+              )}
+            </p>
+            <h3 className="font-display text-lg font-medium text-cream tracking-tight leading-tight">
+              {selectedModel.label}
+            </h3>
+            <p className="text-xs text-cream-muted leading-relaxed">
+              {selectedModel.desc}
+            </p>
+          </div>
+
+          <div className="space-y-2 pt-4 border-t border-border">
+            <RatingBar value={selectedModel.speed} label="speed" />
+            <RatingBar value={selectedModel.accuracy} label="accuracy" />
+          </div>
+
+          <dl className="font-mono text-[11px] grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5 pt-4 border-t border-border">
+            <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+              detail
+            </dt>
+            <dd className="text-cream">{selectedModel.detail}</dd>
+            <dt className="text-cream-muted/60 uppercase tracking-widest text-[9px] self-center">
+              size
+            </dt>
+            <dd className="text-cream">{selectedModel.size}</dd>
+          </dl>
+
+          <div className="space-y-1.5 pt-4 border-t border-border">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              best for
+            </p>
+            <p className="text-xs text-cream-muted leading-relaxed">
+              {selectedModel.bestFor}
+            </p>
+          </div>
+
+          <div className="space-y-1.5">
+            <p className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+              about
+            </p>
+            <p className="text-[11px] text-cream-muted leading-relaxed">
+              {selectedModel.description}
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/src/pages/onboarding/StepTheme.tsx b/src/pages/onboarding/StepTheme.tsx
new file mode 100644
index 0000000..618faef
--- /dev/null
+++ b/src/pages/onboarding/StepTheme.tsx
@@ -0,0 +1,101 @@
+import { Switch } from "@/components/ui/switch";
+import { cn } from "@/lib/utils";
+import type { Settings } from "@/lib/types";
+import { THEME_OPTIONS } from "@/lib/constants";
+
+// ============================================================================
+// STEP: THEME
+// ============================================================================
+
+export const StepTheme = ({
+  theme,
+  setTheme,
+  autoStart,
+  setAutoStart,
+}: {
+  theme: Settings["theme"];
+  setTheme: (t: Settings["theme"]) => void;
+  autoStart: boolean;
+  setAutoStart: (b: boolean) => void;
+}) => (
+  <div className="space-y-8 max-w-md w-full">
+    <fieldset className="space-y-3">
+      <legend className="font-mono text-[10px] uppercase tracking-[0.25em] text-cream-muted/60">
+        interface theme
+      </legend>
+      <div
+        className="grid grid-cols-3 gap-3"
+        role="radiogroup"
+        aria-label="Theme selection"
+      >
+        {THEME_OPTIONS.map((opt) => {
+          const isActive = theme === opt.val;
+          return (
+            <button
+              key={opt.val}
+              type="button"
+              role="radio"
+              aria-checked={isActive}
+              className={cn(
+                "relative p-5 rounded-md flex flex-col items-center gap-3 transition-colors border",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-500/40 focus-visible:ring-offset-1",
+                isActive
+                  ? "border-accent-500/40 bg-accent-500/[0.06]"
+                  : "border-border bg-secondary/30 hover:bg-secondary/60"
+              )}
+              onClick={() => setTheme(opt.val as Settings["theme"])}
+            >
+              <div
+                className={cn(
+                  "w-12 h-12 rounded-md border border-border",
+                  opt.val === "light"
+                    ? "bg-[#fafafa]"
+                    : opt.val === "dark"
+                      ? "bg-[#09090b]"
+                      : "bg-gradient-to-br from-[#fafafa] to-[#09090b]"
+                )}
+                aria-hidden
+              />
+              <span
+                className={cn(
+                  "font-mono text-[11px] uppercase tracking-widest",
+                  isActive ? "text-cream" : "text-cream-muted"
+                )}
+              >
+                {opt.label}
+              </span>
+              {isActive && (
+                <span
+                  className="absolute top-2 right-2 w-1.5 h-1.5 rounded-full bg-accent-500"
+                  aria-hidden
+                />
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </fieldset>
+
+    <div className="border-t border-border" />
+
+    <div className="flex items-start justify-between gap-6">
+      <div className="flex-1 min-w-0">
+        <label
+          htmlFor="onboarding-autostart"
+          className="text-sm font-medium text-cream cursor-pointer"
+        >
+          Launch at login
+        </label>
+        <p className="text-xs text-cream-muted mt-1 leading-relaxed">
+          Start VoiceFlow when you sign in to your computer.
+        </p>
+      </div>
+      <Switch
+        id="onboarding-autostart"
+        checked={autoStart}
+        onCheckedChange={setAutoStart}
+        className="mt-0.5 flex-shrink-0"
+      />
+    </div>
+  </div>
+);
diff --git a/src/pages/onboarding/StepWelcome.tsx b/src/pages/onboarding/StepWelcome.tsx
new file mode 100644
index 0000000..ad38fea
--- /dev/null
+++ b/src/pages/onboarding/StepWelcome.tsx
@@ -0,0 +1,37 @@
+import { ONBOARDING_FEATURES } from "@/lib/constants";
+
+// ============================================================================
+// STEP: WELCOME
+// ============================================================================
+
+export const StepWelcome = () => (
+  <div className="space-y-8 max-w-2xl w-full">
+    <p className="text-base md:text-lg leading-relaxed text-cream-muted text-center">
+      Dictation designed for{" "}
+      <span className="text-accent-500 font-medium">privacy</span> and{" "}
+      <span className="text-accent-500 font-medium">flow</span>.
+    </p>
+
+    <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+      {ONBOARDING_FEATURES.map((feature) => (
+        <div
+          key={feature.label}
+          className="border border-border rounded-md bg-surface flex items-start gap-3 p-4 text-left"
+        >
+          <feature.icon
+            className="w-4 h-4 mt-0.5 flex-shrink-0 text-accent-500"
+            strokeWidth={2}
+          />
+          <div className="min-w-0">
+            <p className="font-medium text-cream text-sm leading-tight">
+              {feature.label}
+            </p>
+            <p className="text-[11px] text-cream-muted leading-relaxed mt-1">
+              {feature.desc}
+            </p>
+          </div>
+        </div>
+      ))}
+    </div>
+  </div>
+);