agent: lumotia-rebrand — fix Codex cross-model review blockers

Codex independent review found 11 blockers post-cascade. All addressed.

CRITICAL (data-loss / crash):

10. crates/core/src/paths.rs — migrate_legacy_data_dir_inner used
    fs::rename which fails with EXDEV when source + target are on
    different filesystems (encrypted-home, bind mounts, separate
    $XDG_DATA_HOME partition). Combined with the Phase 5 QC fix that
    made migration errors fatal, this would crash on first launch
    for any user whose data dir spans filesystems. Added
    rename_or_copy_tree() that falls back to copy_dir_recursive +
    remove_dir_all on CrossesDevices / errno 18 (EXDEV). Symlinks
    preserved verbatim. Same fallback applied to magnotia.db ->
    lumotia.db inside the dir.

11. Added 4 unit tests: copy_dir_recursive preserves nested
    structure, rename_or_copy_tree same-filesystem happy path,
    is_cross_device classifies CrossesDevices kind + raw errno 18.

Doc residuals (blockers 1-9):

1. crates/cloud-providers/Cargo.toml — "Wyrdnote pending rebrand"
   description.
2. crates/cloud-providers/src/provider.rs — module docs + test
   fixture Wyrdnote refs.
3. crates/transcription/src/orchestrator.rs — module docs + test
   fixture Wyrdnote refs.
4. docs/roadmap/2026-05-10-pkm-phase-tooling-shortlist.md — phase
   name + outputs/wyrdnote path refs.
5. docs/architecture-map/04-llm-formatting-mcp/llm-tests.md —
   MAGNOTIA_LLM_TEST_MODEL env var.
6. .../cloud-providers-stubs.md — MAGNOTIA_API_KEY_*.
7. docs/architecture-map/03-audio-transcription/tests-and-fixtures.md
   — MAGNOTIA_WHISPER_*.
8. docs/gpu-tuning/plan.md — MAGNOTIA_BENCH_RUN.
9. docs/superpowers/specs/2026-05-09-battery-gpu-aware-thread-tuning-
   design.md + corresponding plan — MAGNOTIA_POWER_STATE_OVERRIDE,
   MAGNOTIA_INFERENCE_THREADS.

cargo test --workspace: 343 pass / 0 fail (up from 339; +4 EXDEV
fallback tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.github/workflows/build.yml

@@ -131,7 +131,7 @@ jobs:
         uses: Swatinem/rust-cache@v2
         with:
           workspaces: .
-          shared-key: kon-build-${{ matrix.os }}
+          shared-key: magnotia-build-${{ matrix.os }}
 
       - name: Install JS deps
         run: npm ci
@@ -165,7 +165,17 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: kon-${{ matrix.os }}-${{ github.sha }}
+          name: magnotia-${{ matrix.os }}-${{ github.sha }}
           path: ${{ matrix.artifact_glob }}
           retention-days: 30
           if-no-files-found: warn
+
+      - name: Report artifact sizes
+        if: always()
+        shell: bash
+        run: |
+          if [ -d src-tauri/target/release/bundle ]; then
+            find src-tauri/target/release/bundle -type f \
+              \( -name '*.AppImage' -o -name '*.deb' -o -name '*.msi' -o -name '*.exe' -o -name '*.dmg' -o -name '*.app' \) \
+              -exec du -h {} + | sort -h
+          fi

.github/workflows/check.yml

@@ -111,6 +111,8 @@ jobs:
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
 
       # Cache the Cargo target dir + registry per OS so the heavy
       # whisper-rs-sys C++ build only happens on a clean cache.
@@ -123,17 +125,29 @@ jobs:
         uses: Swatinem/rust-cache@v2
         with:
           workspaces: .
-          shared-key: kon-${{ matrix.os }}
+          shared-key: magnotia-${{ matrix.os }}
 
       - name: cargo check (workspace)
         run: cargo check --workspace --all-targets
 
+      - name: cargo fmt
+        run: cargo fmt --all -- --check
+
+      - name: cargo clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
       # Library tests only — no runtime/GPU deps. Linux-gated to keep
       # the macOS + Windows legs focused on compile coverage.
       - name: cargo test (workspace, libs)
         if: matrix.os == 'ubuntu-22.04'
         run: cargo test --workspace --lib
 
+      - name: cargo audit
+        if: matrix.os == 'ubuntu-22.04'
+        run: |
+          cargo install cargo-audit --locked
+          cargo audit
+
   frontend:
     name: svelte build + lint
     runs-on: ubuntu-22.04
@@ -150,6 +164,9 @@ jobs:
       - name: Install JS deps
         run: npm ci
 
+      - name: npm audit
+        run: npm audit --audit-level=high
+
       # `tauri build` inside check.yml would trigger the full Rust build
       # which is owned by the rust job. Here we only validate that the
       # Svelte/Vite frontend compiles cleanly.

.gitignore

@@ -3,7 +3,6 @@ target/
 build/
 dist/
 .svelte-kit/
-Cargo.lock
 .firecrawl/
 .worktrees/
 .cargo/

Cargo.toml

@@ -1,3 +1,10 @@
 [workspace]
 members = ["src-tauri", "crates/*"]
 resolver = "2"
+
+[profile.release]
+codegen-units = 1
+lto = "thin"
+opt-level = 3
+panic = "abort"
+strip = "symbols"

HANDOVER.md

@@ -1,97 +1,118 @@
 ---
-name: handover-2026-04-19
+name: handover-2026-04-25
 type: reference
-tags: [handover, session, kon]
-description: Session handover — 2026/04/19 dogfood polish + cross-platform window chrome
+tags: [handover, session, lumotia, phase-9, polish-debt]
+description: Session handover — 2026/04/24-25 Phase 9 polish debt mostly shipped
 ---
 
-# Kon Handover — 2026/04/19
+# Lumotia Handover — 2026/04/25
 
-Second dogfood sprint. Four phases: (1) fix bugs surfaced on first real use, (2) redesign History for cognitive-load hygiene, (3) resolve broken window resize/drag on Linux Wayland, (4) clean up microphone picker.
+> **Note:** Session-specific handover. Migration v14 (`transcripts.llm_tags`) was the head **at the time of this session**. Subsequent work has advanced the schema; current head is v15 (`idx_transcripts_profile_created`, composite index). For the current codebase shape, see [`docs/architecture-map/`](docs/architecture-map/) and [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md).
+
+Phase 9 session. Spec + plan written from scratch and committed; plan corrections layered in after critical review against the actual codebase (Codex was unreachable for cross-model review, three retries failed at the ChatGPT-account-entitlement layer). Sub-phases 9a + 9b + sparkline polish landed end to end. Sub-phase 9c reduced to the Phase 8 carryover bug fix; sub-phase 9d's walkthrough sweeps deferred to Phase 10a QC.
+
+## Rebrand note
+
+Product rename **Magnotia → Lumotia** completed 2026/05/13 (cascade across both repos, all 15 phases, cynical-QC gated). Codebase paths, package names, crate names, bundle identifier (`consulting.corbel.lumotia`), localStorage keys, settings keys, event channels, and on-disk data dir all carry `lumotia`. Migration shims preserve existing user data (data-dir rename, settings-key rename, localStorage-key rename). Remote repo rename pending Jake's action. See `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_lumotia_rebrand_cascade_complete.md` (write pending Phase 15.5 of the cascade plan).
 
 ## What shipped this session
 
-### Cross-window preferences sync
-- `preferences.svelte.js` emits `kon:preferences-changed` Tauri event on update.
-- Main / viewer / float layouts listen and call `applyExternalPreferences` without re-emit, so theme and font changes propagate live across sibling windows.
-- Echo suppressed via source window label check.
+### 9a — Export plumbing
+- `write_text_file_cmd` Rust command in new `src-tauri/src/commands/fs.rs`, with two unit tests (UTF-8 round-trip + bad-parent error path). Registered in `invoke_handler!`. `tempfile = "3"` added as `[dev-dependencies]` on the lumotia crate.
+- `src/lib/utils/saveMarkdown.ts` utility centralises `suggestedFilename`, `saveTranscriptAsMarkdown`, `exportTranscriptsToDir` (directory-mode bulk export with in-batch collision suffixing).
+- HistoryPage `exportMarkdown` no longer copies to clipboard; it opens the OS save dialog and writes the file. Cancel returns silently.
+- HistoryPage gained a slim leading checkbox per row, a bulk-action toolbar (select-all / clear / export / delete), `Esc` to clear, `Cmd/Ctrl+A` to select-all-visible when focus is inside the list and not in a text input.
 
-### Hotkey recorder
-- Root cause of "can't change hotkey": button-level `onkeydown` relied on post-click keyboard focus, which webkit2gtk on Linux does not guarantee.
-- Fix: `document.addEventListener("keydown", ..., { capture: true })` inside a `$effect` gated by `recording`. Beats any descendant handler. Escape now cancels.
+### 9b — LLM content tags
+- `lumotia-llm` exports a new `ContentTags { topic, intent }`, an `INTENT_CLOSED_SET`, an `is_valid_intent` helper, a `CONTENT_TAGS_SYSTEM` prompt and a `CONTENT_TAGS_GRAMMAR` GBNF (recursive style matching the existing `TASK_ARRAY_GRAMMAR`).
+- `LlmEngine::extract_content_tags` method follows the same render-chat → generate → JSON-parse shape as the existing `cleanup_text` and `extract_tasks`. Truncates to the trailing 2000 chars on a UTF-8 boundary; max_tokens 96 is enough for the JSON envelope. Smoke test in `crates/llm/tests/content_tags_smoke.rs` is gated on `LUMOTIA_LLM_TEST_MODEL` matching the Phase 8 pattern.
+- `extract_content_tags_cmd` Tauri wrapper bridges through `state.llm_engine` with the standard `spawn_blocking` + `PowerAssertion` guard.
 
-### History page redesign (research-backed)
-- Compact row now shows the **title** (or "Untitled"), not body-preview text — metadata already lives in the row columns (date, duration, source icon).
-- Expanded row gets an inline title input (replaces the old Rename prompt modal).
-- **Edit** button opens the viewer window in `edit` mode (editable textarea, debounced save to localStorage + storage-event sync back to main history).
-- **Export .md** copies a full YAML-frontmatter markdown document to the clipboard — paste into Obsidian.
-- **Tags**: `$lib/utils/frontmatter.js` exposes `deriveAutoTags` (currently returns `[]`), `buildFrontmatter`, `serialiseFrontmatter`, `buildMarkdown`. Manual tags stored as `item.manualTags`, rendered as removable chips in the expanded row with `+ add tag` input.
-- Header tag chip bar (cap 7, click to filter, × to clear), plus `tag:xyz` search syntax.
-- Global **Starred** filter toggle in the History header.
-- Research memo found all five previous auto-tag families redundant with existing row UI — kept the derivation hook for the post-Task-7 `topic:*` content tag from kon-llm.
-- Duplicate-transcript render fix: expanded `<p>` only if compact preview actually truncated.
+### 9b structural — migration v14 + persistence wiring
+A correction layered in after the critical-review pass discovered the original Task 9 was assuming a writable `saveHistory()` path that turned out to be a no-op stub.
+- Migration v14 adds `transcripts.llm_tags TEXT NOT NULL DEFAULT ''`.
+- `lumotia-storage` `database.rs` SELECT statements include the column. `TranscriptRow` + `transcript_row_from` carry it. `update_transcript_meta` accepts an `Option<&str>` for `llm_tags` (sixth optional, `#[allow(too_many_arguments)]` keeps clippy happy without inverting the signature into a struct).
+- `commands/transcripts.rs` `TranscriptDto` + `UpdateTranscriptMetaRequest` add `llm_tags`; `update_transcript_meta_cmd` forwards.
+- Frontend types: `TranscriptEntry.llmTags: string[]`, `TranscriptRow.llmTags: string`, `ContentTags`, optional `TranscriptMetaPatch.llmTags`.
+- `mapTranscriptRow` hydrates `llmTags`. `saveTranscriptMeta` now also forwards `llmTags` payloads. `buildFrontmatter` unions auto + manual + LLM tags into the exported markdown frontmatter.
+- HistoryPage tag UI: per-row "Tag" button, dashed-italic LLM chips that promote-to-manual on click, top-toolbar "Tag all untagged" with progress text. Existing `addManualTag` / `removeManualTag` handlers swap their no-op `saveHistory()` calls for `saveTranscriptMeta` — picks up the latent `manualTags` persistence bug as a side effect.
 
-### Viewer / editor popout
-- `/viewer` route now reads `kon_viewer_mode` from localStorage ("view" | "edit").
-- Edit mode renders a plain textarea bound to `item.text`; 400ms debounced save flushes on input, final flush on `onDestroy`. Segment-specific controls (Compact, Starred) hidden in edit mode.
-- Native title: **"Kon - Transcription Editor"**.
+### 9b incidental fix — Phase 8 brittle test
+`list_recent_completions_uses_local_day_boundary` failed today because its UTC-anchored `'-2 days', '+12 hours'` offset drifts across UTC midnight relative to the local-day spine the query uses. Fixed by anchoring the timestamp to the local date 2 days ago directly: `datetime(DATE('now', 'localtime', '-2 days') || ' 12:00:00')`. Phase 9 was not the cause; the test happened to fail on today's clock.
 
-### Platform-aware window chrome (Linux fix)
-**Root cause:** Tauri v2 frameless `decorations: false` on KDE Wayland + webkit2gtk does not honour diagonal corner resize (collapses `NorthEast` etc. to a single axis via GTK's `gtk_window_begin_resize_drag`), and `data-tauri-drag-region` adds noticeable drag latency. Setting `setPointerCapture` ahead of `startResizeDragging` does not help once the compositor has taken over the pointer grab. Verified via Context7 docs + Codex diagnosis — Linux frameless is a known-fragile path.
+### 9c — Settings (scaled down)
+- `SettingsGroup.svelte` reusable progressive-disclosure wrapper landed (animated chevron, hover, focus-visible, prefers-reduced-motion).
+- Sparkline toggle (Phase 8 carryover backlog) relocated from the Rituals section into a new dedicated "Tasks" section. Closes the Phase 8 review note that the toggle was visually claimed by the launch-at-login subgroup.
+- **Deferred:** the deeper restructure to seven progressive-disclosure groups + search box. The 2309-line `SettingsPage.svelte` uses a hand-rolled accordion that needs careful unwinding; full restructure was too invasive to land safely in this session. `SettingsGroup` component is in tree, ready for that follow-up pass.
 
-**Fix:**
-- Linux uses **native KWin/Mutter decorations**. `src-tauri/tauri.linux.conf.json` overlays `decorations: true` + full main window config (title, sizes) — overlays **replace** the windows array, so every field must be present, not just the delta. `src-tauri/src/commands/windows.rs` uses `cfg!(target_os = "linux")` to set decorations per window.
-- macOS / Windows keep custom chrome. `src/lib/utils/osInfo.js` `isLinux()` gates `<Titlebar>` and `<ResizeHandles>` via `useCustomChrome = $state(false)`; flips to `!isLinux()` after `loadOsInfo()` resolves.
-- Dueling drag-region handlers removed across Titlebar, float page, viewer page — everywhere a manual `startDragging()` lives, the `data-tauri-drag-region` attribute was deleted (they're alternatives per Tauri docs, not combinable).
-- `ResizeHandles` kept for macOS/Windows frameless: 12 px edges / 20 px corners via CSS vars (`--kon-resize-edge`, `--kon-resize-corner`), `pointerdown` + `setPointerCapture`, corners with explicit higher z-index. Handles rendered as siblings of the animated layout div so `position: fixed` is viewport-relative rather than captured by the transform containing block.
+### 9d — Polish (partial)
+- `CompletionSparkline.svelte`: friendlier sentence-form aria-label ("3 completed today. 14 total over the last 7 days." rather than a bare numeric list), per-bar `<title>` tooltips with absolute date + count, 30 ms staggered scaleY entrance animation. Earlier draft `tabindex=0` on the SVG removed: `role="img"` + aria-label is sufficient for SR navigation without putting it in the keyboard tab order (svelte-check's `noninteractive_tabindex` warning, correctly).
+- TasksPage badge: 180 ms opacity + translate-Y entrance animation on conditional mount. Both new animations respect `prefers-reduced-motion`.
+- **Deferred to Phase 10a QC:** keyboard traversal walkthrough across every page, focus-visible ring sweep, WCAG AA contrast audit in both themes, dark-mode parity check, icon-only-button aria-label audit. These are walkthrough-driven and need a running dev server to validate.
 
-### Window minimum sizes (evidence-backed)
-Research pass cited GNOME HIG (1024×600 desktop / 360×294 mobile floors), WCAG 2.2 SC 1.4.10 Reflow (320 CSS px), Raycast 750×474 as a reference for single-pane working width, and consistent A11y principle that nothing should clip in the default configuration.
+## Verification state at session end
 
-| Window | Was | Now | Rationale |
-|---|---|---|---|
-| Main | 1020×540 | **960×600** | Fits 210 px sidebar + ~750 px content; GNOME vertical floor. |
-| Float | 400×400 | **360×480** | 360 = GNOME mobile floor; 480 fits pills + quick-add + sort + ~6 task rows without scroll. |
-| Transcript editor | 450×500 | **560×520** | Exceeds WCAG reflow floor; ~60-70 char measure for editing. |
+Fresh run on `main` tip `dd45f10`:
 
-### Microphone picker cleanup
-- ALSA enumeration was leaking `hw:`, `plughw:`, `front:`, `sysdefault:`, `null` et al into the dropdown.
-- `SettingsPage.svelte` now renders only sentinel devices (`default`, `pipewire`, `pulse`) + one entry per unique sound card, keyed off the `sysdefault:CARD=X` alias.
-- `crates/audio/src/capture.rs` reads `/proc/asound/cards` and populates a new `description` field on `DeviceInfo` with the card's full product string (e.g. "Blue Microphones" for Jake's Yeti). Frontend prefers description → CARD=X short name → raw name.
+- `cargo fmt --check`: clean.
+- `cargo clippy --all-targets -- -D warnings`: clean.
+- `cargo test`: **277 tests pass**, 0 failed. Storage gained 1 new test (`update_transcript_meta_writes_llm_tags`), lumotia-tauri gained 2 (write_text_file). The Phase 8 brittle test fix is in this count.
+- `npm run check`: 0 errors, 0 warnings across 3957 files.
+- `npm run build`: clean production build via `@sveltejs/adapter-static`.
 
-### GPU reporting
-- `commands/models.rs::get_runtime_capabilities` was hardcoded to `accelerators: vec!["cpu"]` and `supports_gpu: false` for whisper. Updated to `["cpu", "vulkan"]` and whisper `supports_gpu: true`, reflecting that `crates/transcription/Cargo.toml` links transcribe-rs with the `whisper-vulkan` feature unconditionally.
-- Settings now shows the Vulkan option instead of the "This build is CPU-only" notice.
+## Plan correction summary (for any future reader)
 
-### Desktop shortcut
-- `~/Desktop/Kon.desktop` launcher with the 128×128 icon, `Terminal=true` so logs are visible and Ctrl+C cleanly stops the run.sh wrapper.
+The original Phase 9 spec + plan committed at `49a795f` + `48d3db7` had three mismatches against the actual codebase, surfaced by a critical-review pass before execution. Layered as a corrections appendix in commit `3eb24f2`:
 
-## What's deferred
+1. `lumotia-llm` is `LlmEngine::generate(prompt, config)` synchronous, not the speculated `LlamaEngine::generate_chat(messages, config).await`.
+2. `AppState.llm_engine: Arc<LlmEngine>` is direct, not behind a `RwLock`.
+3. **Structural** — `transcripts.llm_tags` requires a real SQLite migration plus Tauri command extension because the frontend `saveHistory()` is a no-op stub. Original plan assumed `manualTags`-mirroring would suffice. Migration v14 + `update_transcript_meta` extension landed as a new task to cover this. Picked up the latent `manualTags` persistence bug for free.
 
-- **Transparent windows (`transparent: true`)** — Tauri issue #13270 reports this smooths drag/resize further on Linux, but it's moot now that Linux uses native decorations.
-- **File-system export (.md save dialog)** — currently clipboard-only. Needs a Rust `write_text_file` command for plugin-less file writes.
-- **Bulk select + bulk export** in History.
-- **LLM-powered content tags** (`topic:*`, `intent:*`) — slots into Task 7 `kon-llm` stub once Phase 3 wires real llama-cpp-2.
-- **Settings UX overhaul** — Jake flagged that current settings feel overwhelming. Proposed: bunch high-traffic settings, hide advanced behind a toggle. Brainstorm + plan deferred to a dedicated session.
-- **Task 7 (MicroSteps end-to-end)** — storage + Tauri CRUD + kon-llm stub + frontend dual-write all landed in an earlier commit chain. The MicroSteps UI was written as the final task 7 step but not yet dogfooded against the stub LLM. Needs manual walkthrough.
+## Owed to Jake (next session)
 
-## Gotchas discovered today
+1. **Manual dogfood walkthrough.** Cannot be driven by an automated agent. When opening Lumotia next:
+   - Export one transcript via the History "Export .md" button — save dialog opens, file written to chosen path. Cancel — no toast, no fallback.
+   - Select 3 history rows via checkboxes — toolbar surfaces, "Export selected" writes one .md per row to a chosen folder, collisions suffixed " (2)" etc.
+   - Click "Tag" on one row — within a few seconds, dashed `topic:*` and `intent:*` chips appear. Click a chip — it moves into `manualTags` (solid accent chip). Page refresh — both `manualTags` and `llmTags` survive (this is the persistence-fix outcome).
+   - "Tag all untagged" runs across the corpus, progress text updates, success toast at the end.
+   - Settings → new "Tasks" section appears with the sparkline toggle. Toggle off → sparkline disappears on Tasks page; badge stays. Toggle on → sparkline returns.
+   - Sparkline keyboard-focus-or-hover on a bar shows the date + count tooltip. Screen reader announces the sentence-form summary.
+   - `prefers-reduced-motion` set in OS — badge entrance + sparkline stagger both stop.
 
-| Issue | Fix |
+2. **Phase 9 follow-up to absorb in a future polish session:**
+   - Full `SettingsPage` regroup using `SettingsGroup` (already in tree), search box, Start-here always-expanded, six collapsed groups by domain.
+   - The walkthrough-driven a11y sweeps from Phase 9 Tasks 14-15. Phase 10a QC will catch most; document any issues for a follow-up polish commit.
+
+3. **Codex unavailability.** Three retries on the codex-rescue subagent failed because the local `~/.codex/config.toml` pins `model = "gpt-5.5"` which the ChatGPT account doesn't have access to, and explicit overrides (`gpt-4o`, `o4-mini`, `codex-mini-latest`, `gpt-5.3-codex-spark`) are also blocked at the ChatGPT-account level. Either upgrade the ChatGPT plan tier or switch Codex auth to an OpenAI API key (`codex login` with key) to unblock cross-model review on future plans.
+
+## What's left for v0.1
+
+| Phase | State |
 |---|---|
-| `tauri.linux.conf.json` stripped title and min sizes from main window | Overlay **replaces** the windows array — include every field, not just the delta |
-| `data-tauri-drag-region` + manual `startDragging()` on the same node caused drag latency | Pick one — we use manual `startDragging` for the button/input early-return logic |
-| Corner resize collapsed to single axis on KWin Wayland | Native decorations on Linux side-step the whole frameless path |
-| `animate-float-enter` on the viewer/float layout root created a containing block that broke `position: fixed` on ResizeHandles children | Render ResizeHandles as a sibling of the animated div, not a descendant |
-| Kon binary auto-respawned on file-save while a second run.sh was also launching → two visible instances sharing one Vite server | Do not script `./run.sh` while the user has already launched via the desktop icon; rely on HMR |
-| `run.sh` leaves `"beforeDevCommand": ""` in tauri.conf.json if its cleanup trap is bypassed (e.g. SIGKILL) | Cleanup trap restores `"npm run dev"` on graceful exit; SIGTERM (not SIGKILL) is the right kill signal |
-| `/proc/asound/cards` header lines have leading whitespace for 2-digit card ID alignment | Parser trims leading whitespace before checking for leading digit |
+| Phases 1-8 | All shipped. |
+| Phase 9 | **Mostly shipped this session.** Export plumbing, LLM content tags (with persistence), polish on sparkline + badge are live. SettingsPage deeper restructure + walkthrough a11y sweeps deferred. Roadmap entry updated. |
+| Phase 10a | QC: dogfood walkthrough (above), Rachmann's RB-08 Mac verification (parallel), cross-platform CI, a11y regression, clean-install test. Half day. |
+| Phase 10b | Magnotia → Lumotia rename sweep: **COMPLETE 2026/05/13** (cascade across both repos, 15 phases). Remote repo rename pending Jake. |
+| Phase 10c | Release: 0.1.0 version sync, CHANGELOG seeded from roadmap phases, release notes, tag + push. Half day. |
 
-## How to resume
+### Release-blocker state
 
-```
-Picking up Kon dogfooding from 2026/04/19.
-HANDOVER is at HANDOVER.md in the project root.
-Active priorities: (1) confirm resize/drag/mic cleanup, (2) Task 7 MicroSteps
-dogfood with kon-llm stub, (3) Settings UX brainstorm.
-```
+- **0 open CRITICAL.**
+- **1 open MAJOR.** RB-08 `power-assertion-macos-objc2` (awaits Rachmann's manual runtime verification). Gates v0.1 tagging.
+
+## Repo state at session end
+
+- `main` at `dd45f10`.
+- 18 Phase 9 commits (3 docs + 15 feat/polish) on top of yesterday's tip.
+- Local branches: `main` only.
+- `cargo build --workspace` green / `cargo test --workspace` green (277 passing) / `cargo clippy --workspace --all-targets -- -D warnings` clean / `cargo fmt --check` clean / `npm run check` 0/0 / `npm run build` clean.
+
+## Anchors
+
+- Spec: [docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md](docs/superpowers/specs/2026-04-24-phase9-polish-debt-design.md)
+- Plan: [docs/superpowers/plans/2026-04-24-phase9-polish-debt.md](docs/superpowers/plans/2026-04-24-phase9-polish-debt.md)
+- Roadmap: [docs/roadmap/2026-04-23-lumotia-feature-complete-roadmap.md](docs/roadmap/2026-04-23-lumotia-feature-complete-roadmap.md)
+- Previous handover: [HANDOVER-2026-04-24.md](HANDOVER-2026-04-24.md) (Phase 8)
+- Release-blocker index: [docs/issues/README.md](docs/issues/README.md)
+- Rebrand memory: `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_lumotia_rebrand_cascade_complete.md`
+- Active-focus upstream: `context/active-focus.md` in CORBEL-Main

KNOWN-ISSUES.md

@@ -0,0 +1,83 @@
+# Known issues
+
+Tracked limitations and partial implementations in the current codebase. Each entry points at the code that owns the gap so future work can find it.
+
+## Power management
+
+### KI-01 — macOS App Nap guard pending Apple Silicon runtime verification
+
+**Status:** macOS code path compiles and the registry tests pass, but runtime behaviour against actual OS idle-throttling has not been confirmed on Apple Silicon hardware. Also tracked internally as **RB-08**.
+
+**Source:** [`src-tauri/src/commands/power.rs:73`](src-tauri/src/commands/power.rs#L73) (`PowerAssertion::begin`), [`src-tauri/src/commands/power.rs:140`](src-tauri/src/commands/power.rs#L140) (`objc_bridge`).
+
+**Impact:** Long live-dictation sessions on macOS may still be slowed or paused by the OS until verified end-to-end on hardware.
+
+**Workaround:** Keep the app window focused, or move the cursor periodically. For testing, App Nap can be disabled globally with `defaults write NSGlobalDomain NSAppSleepDisabled -bool YES` (revert with `-bool NO`).
+
+### KI-02 — Linux power assertion is a no-op
+
+**Status:** `PowerAssertion::begin` does nothing on Linux. The planned implementation (systemd-logind / GNOME idle inhibitor via `org.freedesktop.login1.Inhibit`) is described in the file-level doc but not wired up.
+
+**Source:** [`src-tauri/src/commands/power.rs`](src-tauri/src/commands/power.rs).
+
+**Impact:** Long sessions can be paused by the compositor's idle hooks (screen lock, suspend timers) on KDE, GNOME, Hyprland, Sway, etc.
+
+**Workaround:** Raise the system idle / screen-lock timeout while dictating, or wrap launch with `systemd-inhibit --what=idle:sleep:handle-lid-switch ./run.sh`.
+
+### KI-03 — Windows power assertion is a no-op
+
+**Status:** `PowerAssertion::begin` does nothing on Windows. The planned implementation (`SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED)` on begin, `ES_CONTINUOUS` alone on end) is described in the file-level doc but not wired up.
+
+**Source:** [`src-tauri/src/commands/power.rs`](src-tauri/src/commands/power.rs).
+
+**Impact:** Long sessions can be paused by Windows sleep policies.
+
+**Workaround:** Set the active power plan's sleep to "Never" while dictating.
+
+## Cloud providers
+
+### KI-04 — `lumotia-cloud-providers` crate is not user-exposed
+
+**Status:** The crate is a declared workspace dependency in [`src-tauri/Cargo.toml:36`](src-tauri/Cargo.toml#L36) and compiles into the binary, but no Tauri command, page, or settings field invokes `store_api_key` / `retrieve_api_key`. There is no UI to enter or store a cloud API key in the current build.
+
+**Source:** [`crates/cloud-providers/src/keystore.rs`](crates/cloud-providers/src/keystore.rs). The `TODO` in the doc comment captures the planned migration to OS-native credential storage (the `keyring` crate or equivalent) before the feature is wired up.
+
+**Impact:** None for end users today (no exposed surface). When the feature is wired post-launch, cross-restart persistence must land before any "save key" UX ships, otherwise saved keys reset on every restart.
+
+**Workaround:** N/A.
+
+## Frontend
+
+### KI-05 — Dual theme system: `settings.theme` and `preferences.theme` coexist
+
+**Status:** Theme is stored twice. The legacy `settings.theme` ("Dark" / "Light" / "System", localStorage-only) is bound to two `SegmentedButton` controls in `SettingsPage.svelte`. The canonical `preferences.theme` ("dark" / "light" / "system", Tauri-persisted via `save_preferences`) is what the DOM and runtime actually consume. A migration `$effect` in `src/routes/+layout.svelte` (and the secondary `+layout@.svelte` files for `/preview`, `/viewer`, `/float`) syncs `settings.theme` → `preferences.theme` whenever the legacy value changes.
+
+**Source:**
+- [`src/lib/stores/page.svelte.ts:61`](src/lib/stores/page.svelte.ts#L61) (legacy default: `theme: "Dark"`)
+- [`src/lib/stores/preferences.svelte.ts:30`](src/lib/stores/preferences.svelte.ts#L30) (canonical default: `theme: "dark"`)
+- [`src/routes/+layout.svelte:61-68`](src/routes/+layout.svelte#L61) (migration `$effect`)
+- [`src/lib/pages/SettingsPage.svelte:1118`](src/lib/pages/SettingsPage.svelte#L1118), [`:2360`](src/lib/pages/SettingsPage.svelte#L2360) (UI bindings still on the legacy field)
+
+**Impact:** No user-facing bug; theme switching works. The cost is code complexity and a small race window where preference fan-out can lag behind a `settings.theme` change. The `$effect` is lightweight (string compare plus a debounced persist when the mapped value differs), not a hot-loop performance problem despite earlier framing.
+
+**Resolution (deferred):** Switch the two `SettingsPage` bindings to `preferences.theme` with mapped options, retire the migration `$effect` in all four route layouts, drop `theme` from `SettingsState`, and add a one-shot localStorage migration that copies any historical `settings.theme` into `preferences` on first run after the cleanup. Touches ~5 files including the 2 484-LOC `SettingsPage.svelte`; deferred from the v0.1 polish pass to avoid a moderate-risk frontend change immediately before launch.
+
+**Workaround:** N/A.
+
+## Engine architecture (Phase A)
+
+### KI-06 — `transcribe_file` and live-transcription commands not yet rewired through `Orchestrator`
+
+**Status:** Phase A introduced the `TranscriptionProvider` async trait ([`crates/cloud-providers/src/provider.rs`](crates/cloud-providers/src/provider.rs)), `EngineRegistry` ([`crates/transcription/src/registry.rs`](crates/transcription/src/registry.rs)), and `Orchestrator` plus `LocalProviderAdapter` ([`crates/transcription/src/orchestrator.rs`](crates/transcription/src/orchestrator.rs)). The abstractions compile, are object-safe, and pass unit tests against a mock provider. The existing dictation path ([`src-tauri/src/commands/transcription.rs`](src-tauri/src/commands/transcription.rs)) still calls `LocalEngine::transcribe_sync` directly via `pick_engine`, not through the orchestrator. Live and meeting commands likewise route around the orchestrator.
+
+**Source:** [`src-tauri/src/commands/transcription.rs:29`](src-tauri/src/commands/transcription.rs#L29) (`pick_engine`), [`src-tauri/src/commands/live.rs`](src-tauri/src/commands/live.rs), [`src-tauri/src/commands/meeting.rs`](src-tauri/src/commands/meeting.rs).
+
+**Impact:** None at runtime. The orchestrator path is dormant until a follow-up commit migrates the call sites. Cloud providers (Phase G) cannot be exercised end-to-end until this rewire lands.
+
+**Resolution (deferred):** Phase A.1 follow-up commit. Build an `EngineRegistry` at app boot (one `LocalProviderAdapter` per `LocalEngine`), inject `Arc<Orchestrator>` into `AppState`, replace `pick_engine` plus `engine.transcribe_sync` chunking-loop calls with `orchestrator.transcribe(audio, &profile)` per chunk. Keep the chunking strategy in the command layer (it is a strategy concern, not a dispatch concern). Tests should cover both paths against a mock provider before touching the real engines.
+
+**Workaround:** N/A. Existing path works as before.
+
+## How to add an entry
+
+When shipping a partial implementation or known limitation, add a `KI-NN` entry here with the four standard fields: **Status**, **Source** (file:line), **Impact**, **Workaround**. Link from the affected module's doc comment back to this file by ID.

README.md

@@ -1,8 +1,8 @@
-# Kon
+# Lumotia
 
 *Think out loud. Keep working.*
 
-Kon is a local-first, cognitive-load-aware dictation and task-capture desktop app. Every transcription, LLM cleanup, and task extraction runs on the user's machine. No telemetry, no analytics, no cloud dependency. The app is designed around a single observation: people who think in bursts lose ideas faster than they can type, and the tool's job is to get out of the way.
+Lumotia is a local-first, cognitive-load-aware dictation and task-capture desktop app. Every transcription, LLM cleanup, and task extraction runs on the user's machine. No telemetry, no analytics, no cloud dependency. The app is designed around a single observation: people who think in bursts lose ideas faster than they can type, and the tool's job is to get out of the way.
 
 ---
 
@@ -11,8 +11,9 @@ Kon is a local-first, cognitive-load-aware dictation and task-capture desktop ap
 **Pre-alpha.** Actively dogfooded on Linux (KDE Plasma 6 on Wayland). macOS and Windows targets are in scope and exercised by CI, but not yet beta-ready. One primary user; open source-intent with licence TBD before public beta.
 
 - Current `main`: see commit log
-- 136 automated lib tests across 10 crates, all passing
+- 9 library crates plus the Tauri app crate; 220+ lib tests plus 67 Tauri-app tests, all passing
 - Cross-platform CI (Linux / macOS / Windows) via GitHub Actions
+- Tracked limitations live in [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md)
 
 ---
 
@@ -20,15 +21,15 @@ Kon is a local-first, cognitive-load-aware dictation and task-capture desktop ap
 
 1. **Local-first is the floor, not a feature.** No voice, transcript, or task ever leaves the user's machine unless they explicitly send it. No telemetry.
 2. **Cognitive load is the limiting resource.** Every new setting must earn its mental real estate. Every interaction should reduce, not add, decisions.
-3. **Composable, not monolithic.** Kon is a dictation primitive: via MCP, CLI, and filesystem export, it slots into whatever workflow the user already has (Obsidian, Claude Desktop, Cline, any text field).
+3. **Composable, not monolithic.** Lumotia is a dictation primitive: via MCP, CLI, and filesystem export, it slots into whatever workflow the user already has (Obsidian, Claude Desktop, Cline, any text field).
 4. **LLM scope is narrow.** The in-app LLM does transcription cleanup and task extraction. It is not a wake-word agent, not a chat UI, not a multi-provider cloud fan-out.
 5. **Raw transcript is always recoverable.** Cleanup is additive, never destructive. The user can always see and revert to what Whisper heard.
 
-These are enforced in the codebase (where practical) and in the docs under [`docs/whisper-ecosystem/kon-context.md`](docs/whisper-ecosystem/kon-context.md).
+These are enforced in the codebase (where practical) and in the docs under [`docs/whisper-ecosystem/lumotia-context.md`](docs/whisper-ecosystem/lumotia-context.md).
 
 ---
 
-## What Kon does today
+## What Lumotia does today
 
 ### Speech-to-text
 - Vulkan-accelerated local **Whisper** inference via [whisper-rs](https://github.com/tazz4843/whisper-rs) 0.16 + whisper.cpp. Works on NVIDIA, AMD, Intel Arc, Apple (via MoltenVK), and integrated graphics.
@@ -41,7 +42,7 @@ These are enforced in the codebase (where practical) and in the docs under [`doc
 
 ### LLM formatting (local only)
 - Local LLM runtime via [llama-cpp-2](https://github.com/utilityai/llama-cpp-rs) 0.1.144 with Vulkan.
-- Three Qwen3 tiers (1.7B, 4B-Instruct-2507, 14B) auto-selected by hardware probe.
+- Four Qwen tiers (Qwen3.5 2B / 4B / 9B + Qwen3.6 27B) auto-selected by hardware probe.
 - GBNF grammar-constrained output for task extraction (always-parseable JSON).
 - System prompt hardened against voice-delivered prompt injection.
 
@@ -64,7 +65,7 @@ These are enforced in the codebase (where practical) and in the docs under [`doc
 - Transcript editor window (`/viewer`) with debounced autosave.
 
 ### External integration
-- **MCP stdio server** (`kon-mcp`) exposing read-only transcripts and tasks to any Model Context Protocol client (Claude Desktop, Cline, Cursor, etc.). No authentication, read-only, local-only.
+- **MCP stdio server** (`lumotia-mcp`) exposing read-only transcripts and tasks to any Model Context Protocol client (Claude Desktop, Cline, Cursor, etc.). No authentication, read-only, local-only.
 
 ### Accessibility
 - Dyslexia-friendly fonts bundled: Lexend, Atkinson Hyperlegible Next, OpenDyslexic.
@@ -83,7 +84,7 @@ These are enforced in the codebase (where practical) and in the docs under [`doc
 
 ## Architecture
 
-Kon is a Tauri 2 desktop app with three layers:
+Lumotia is a Tauri 2 desktop app with three layers:
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -92,29 +93,31 @@ Kon is a Tauri 2 desktop app with three layers:
 │  Stores, i18n, Tailwind CSS                                     │
 ├─────────────────────────────────────────────────────────────────┤
 │  Tauri 2 runtime (src-tauri/)                                   │
-│  Commands: audio, clipboard, diagnostics, hotkey, live, llm,    │
-│            meeting, models, paste, power, profiles, tasks,      │
-│            transcription, transcripts, update, windows          │
+│  Commands: audio, clipboard, diagnostics, feedback, fs,         │
+│            hardware, hotkey, intentions, live, llm, meeting,    │
+│            models, nudges, paste, profiles, rituals, tasks,     │
+│            transcription, transcripts, tts, update, windows     │
+│  Utility modules (no commands): mod, power, security            │
 │  Plugins: global-shortcut, dialog, opener, updater,             │
 │           window-state                                          │
 ├─────────────────────────────────────────────────────────────────┤
 │  Rust workspace (crates/)                                       │
-│  kon-core, kon-audio, kon-transcription, kon-llm,               │
-│  kon-ai-formatting, kon-storage, kon-hotkey,                    │
-│  kon-cloud-providers, kon-mcp                                   │
+│  lumotia-core, lumotia-audio, lumotia-transcription, lumotia-llm,               │
+│  lumotia-ai-formatting, lumotia-storage, lumotia-hotkey,                    │
+│  lumotia-cloud-providers, lumotia-mcp                                   │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-The Rust workspace is the brain; Tauri is the OS integration surface; Svelte is the UI. The MCP server (`kon-mcp`) is a separate binary that opens Kon's SQLite store read-only — it's Kon-as-primitive for external agents.
+The Rust workspace is the brain; Tauri is the OS integration surface; Svelte is the UI. The MCP server (`lumotia-mcp`) is a separate binary that opens Lumotia's SQLite store read-only — it's Lumotia-as-primitive for external agents.
 
 ### Repository layout
 
 ```
-kon/
+lumotia/
 ├── Cargo.toml              # workspace root
 ├── src-tauri/              # Tauri app (main binary + commands)
 │   ├── src/
-│   │   ├── commands/       # 18 Tauri command modules
+│   │   ├── commands/       # 22 Tauri command modules + 3 utility modules (`mod`, `power`, `security`)
 │   │   ├── lib.rs          # app entry, setup, command registration
 │   │   ├── tray.rs
 │   │   └── main.rs
@@ -162,15 +165,15 @@ kon/
 
 | Crate | Responsibility |
 |---|---|
-| **`kon-core`** | Shared types (`Segment`, `Transcript`, `Megabytes`, `ModelId`), constants, the `Engine` / `SpeedTier` / `AccuracyTier` enums, hardware probe (`sysinfo`-based), model registry (Whisper + Parakeet + Moonshine entries), hardware-aware recommendation scoring, `process_watch` for meeting detection. |
-| **`kon-audio`** | `cpal`-based microphone capture with device hotplug + error forwarding, VAD, `rubato` streaming resampler to 16 kHz mono, `symphonia` file decoding, `hound` WAV I/O. |
-| **`kon-transcription`** | `whisper-rs` backend (`WhisperRsBackend`) that owns a `WhisperContext` and supports `set_initial_prompt`. `LocalEngine` wraps both Whisper and Parakeet (via `transcribe-rs` ONNX) behind a common `Transcriber` trait. Streaming primitives (`VadChunker`, `LocalAgreement`, buffer trim) live in the `streaming/` module. Model manager handles downloads, paths, and disk checks. |
-| **`kon-llm`** | `llama-cpp-2` engine with Qwen3 model manager. Three high-level surfaces: `cleanup_text` (formatting), `decompose_task` (3–7 micro-steps, GBNF-constrained JSON array), `extract_tasks` (optional-array, GBNF-constrained). Resumable HTTP downloads with SHA-256 verify. |
-| **`kon-ai-formatting`** | Post-processing pipeline: filler removal, British English conversion, anti-hallucination filter, smart paragraph breaks on long pauses, optional LLM cleanup. Also hosts the `llm_client::CLEANUP_PROMPT` constant (prompt-injection-hardened). |
-| **`kon-storage`** | SQLite via `sqlx` 0.8. Migrations, CRUD for transcripts / tasks / subtasks / profiles / profile terms / settings / error log, FTS5 search, file-storage paths. |
-| **`kon-hotkey`** | Linux `evdev` hotkey listener with device hotplug. Parses Tauri-style hotkey strings (`Ctrl+Shift+R`), emits Pressed / Released events. Works natively on Wayland (no X11 dependency). Checks `/dev/input/event*` access on startup; surfaces a clear "add yourself to the `input` group" error when missing. |
-| **`kon-cloud-providers`** | BYOK cloud-STT provider stubs. Currently empty scaffolding. When populated: OpenAI-compatible endpoint + Anthropic (ceiling for scope). |
-| **`kon-mcp`** | Standalone `kon-mcp` binary implementing the MCP stdio protocol (2024-11-05). Read-only tools: `list_transcripts`, `get_transcript`, `search_transcripts`, `list_tasks`. Opens Kon's SQLite store. |
+| **`lumotia-core`** | Shared types (`Segment`, `Transcript`, `Megabytes`, `ModelId`), constants, the `Engine` / `SpeedTier` / `AccuracyTier` enums, hardware probe (`sysinfo`-based), model registry (Whisper + Parakeet entries), hardware-aware recommendation scoring, `process_watch` for meeting detection. |
+| **`lumotia-audio`** | `cpal`-based microphone capture with device hotplug + error forwarding, VAD, `rubato` streaming resampler to 16 kHz mono, `symphonia` file decoding, `hound` WAV I/O. |
+| **`lumotia-transcription`** | `whisper-rs` backend (`WhisperRsBackend`) that owns a `WhisperContext` and supports `set_initial_prompt`. `LocalEngine` wraps both Whisper and Parakeet (via `transcribe-rs` ONNX) behind a common `Transcriber` trait. Streaming primitives (`VadChunker`, `LocalAgreement`, buffer trim) live in the `streaming/` module. Model manager handles downloads, paths, and disk checks. |
+| **`lumotia-llm`** | `llama-cpp-2` engine with a four-tier Qwen3.5 / Qwen3.6 model manager. Three high-level surfaces: `cleanup_text` (formatting), `decompose_task` (3–7 micro-steps, GBNF-constrained JSON array), `extract_tasks` (optional-array, GBNF-constrained). Resumable HTTP downloads with SHA-256 verify. |
+| **`lumotia-ai-formatting`** | Post-processing pipeline: filler removal, British English conversion, anti-hallucination filter, smart paragraph breaks on long pauses, optional LLM cleanup. Also hosts the `llm_client::CLEANUP_PROMPT` constant (prompt-injection-hardened). |
+| **`lumotia-storage`** | SQLite via `sqlx` 0.8. Migrations, CRUD for transcripts / tasks / subtasks / profiles / profile terms / settings / error log, FTS5 search, file-storage paths. |
+| **`lumotia-hotkey`** | Linux `evdev` hotkey listener with device hotplug. Parses Tauri-style hotkey strings (`Ctrl+Shift+R`), emits Pressed / Released events. Works natively on Wayland (no X11 dependency). Checks `/dev/input/event*` access on startup; surfaces a clear "add yourself to the `input` group" error when missing. |
+| **`lumotia-cloud-providers`** | BYOK cloud-STT provider stubs. Currently empty scaffolding. When populated: OpenAI-compatible endpoint + Anthropic (ceiling for scope). |
+| **`lumotia-mcp`** | Standalone `lumotia-mcp` binary implementing the MCP stdio protocol (2024-11-05). Read-only tools: `list_transcripts`, `get_transcript`, `search_transcripts`, `list_tasks`. Opens Lumotia's SQLite store. |
 
 ### Tauri commands (src-tauri/src/commands/)
 
@@ -179,27 +182,34 @@ kon/
 | `audio` | Device enumeration, native capture start/stop, audio-samples persistence |
 | `clipboard` | Cross-platform clipboard write (arboard) |
 | `diagnostics` | Panic hook, frontend error log, crash file listing, diagnostic report bundler |
+| `feedback` | Thumbs / correction capture on AI-generated output; few-shot example store for prompt conditioning |
+| `fs` | Thin filesystem write for the OS save-dialog path (UTF-8 text, dialog-constrained) |
 | `hardware` | `probe_system`, `rank_models` |
 | `hotkey` | `start_evdev_hotkey`, `update_evdev_hotkey`, `stop_evdev_hotkey`, `check_hotkey_access`, `is_wayland_session` |
+| `intentions` | Implementation-intention rule CRUD (if-then automation: time-of-day, task-completed, morning-triage triggers) |
 | `live` | Live streaming transcription session lifecycle + speech-gate tuning |
 | `llm` | Tier recommend, model check / download / load / unload / delete, status, `cleanup_transcript_text_cmd`, `extract_tasks_from_transcript_cmd` |
 | `meeting` | `detect_meeting_processes` (process-list poll) |
 | `models` | Whisper + Parakeet model download / load / check / default-id resolution, runtime capabilities API, pre-warm |
+| `nudges` | Margot soft-touch nudge delivery via `tauri-plugin-notification`; main-window-only guard |
 | `paste` | `paste_text` (copy + keystroke), `detect_paste_backends`, Wayland focus-race mitigation against the preview overlay |
-| `power` | macOS `PowerAssertion` guard during long sessions (blocks App Nap) |
 | `profiles` | Profile CRUD, profile-terms CRUD, learn-terms-from-edit |
+| `rituals` | Start- and shutdown-ritual sentinels (last-shown date for the morning-triage modal) |
 | `tasks` | Task CRUD, subtask CRUD, `decompose_and_store`, `extract_tasks_from_transcript_cmd` |
 | `transcription` | `transcribe_pcm`, `transcribe_file`, `transcribe_pcm_parakeet` |
 | `transcripts` | Transcript CRUD + FTS5 search |
+| `tts` | Platform-native Read Page Aloud (`spd-say` / `say` / PowerShell), with cancellable child-process tracking |
 | `update` | Tauri-plugin-updater check / install |
 | `windows` | `open_task_window`, `open_viewer_window`, `open_preview_window`, `close_preview_window` |
 
+Utility modules in the same directory (no `#[tauri::command]` attributes; helpers consumed by the command modules above): `mod` (registry), `power` (macOS `PowerAssertion` guard against App Nap during long sessions), `security` (`ensure_main_window` guard).
+
 ### Frontend (src/)
 
 - **SvelteKit + Svelte 5 runes** (`$state`, `$derived`, `$effect`).
 - **Tailwind CSS 4** for styling, with a Lexend/Atkinson/OpenDyslexic type system.
 - **Secondary windows** (`/float`, `/viewer`, `/preview`) use named layouts (`+layout@.svelte`) to skip the main shell and run chrome-free.
-- **Reactive stores** (`src/lib/stores/page.svelte.ts`): `settings`, `profiles`, `tasks`, `history`, `taskLists`, `templates`, `page`, `toasts`, `preferences`.
+- **Reactive stores** (`src/lib/stores/`, one file per store): `page.svelte.ts` (central app state; transcripts, profiles, taskLists, templates, etc. live as fields here), `preferences.svelte.ts`, `profiles.svelte.ts`, `toasts.svelte.ts`, `focusTimer.svelte.ts`, `llmStatus.svelte.ts`, `nudgeBus.svelte.ts`, `implementationIntentions.svelte.ts`, `completionStats.svelte.ts`, `speaker.svelte.ts`.
 - **i18n**: `svelte-i18n` with en/es/de locales at `src/lib/i18n/locales/`. Scaffolding only — strings migrate to translation keys incrementally.
 
 ---
@@ -226,10 +236,10 @@ kon/
 
 | Platform | Status | Notes |
 |---|---|---|
-| Linux Wayland (KDE Plasma, GNOME Mutter, Hyprland, Sway) | **Primary target**, daily-dogfooded on KDE | evdev hotkey, GTK 3 via webkit2gtk, Vulkan, all paste backends |
-| Linux X11 | Supported | xdotool paste path, GTK 3 |
-| macOS | In CI, untested runtime | osascript paste, Metal via MoltenVK, App Nap guard |
-| Windows | In CI, untested runtime | SendKeys paste, Vulkan-first GPU path, bundled DLLs for CPU fallback |
+| Linux Wayland (KDE Plasma, GNOME Mutter, Hyprland, Sway) | **Primary target**, daily-dogfooded on KDE | evdev hotkey, GTK 3 via webkit2gtk, Vulkan, all paste backends; idle inhibit not wired (see KI-02) |
+| Linux X11 | Supported | xdotool paste path, GTK 3; idle inhibit not wired (see KI-02) |
+| macOS | In CI, untested runtime | osascript paste, Metal via MoltenVK, App Nap guard pending Apple Silicon verification (see KI-01) |
+| Windows | In CI, untested runtime | SendKeys paste, Vulkan-first GPU path, bundled DLLs for CPU fallback; sleep prevention not wired (see KI-03) |
 
 CI runs `cargo check --workspace --all-targets` + `svelte-check` on all three on every push and PR.
 
@@ -261,20 +271,22 @@ See [`docs/dev-setup.md`](docs/dev-setup.md) for the authoritative per-platform
 
 ### Dev launch
 
-The fast path — starts Vite, waits for port 1420, then launches Tauri:
+Canonical full-stack dev launch — starts Vite, waits for port 1420, then launches Tauri:
+
+```bash
+npm run dev:tauri
+```
+
+Direct shell equivalent:
 
 ```bash
 ./run.sh
 ```
 
-Or manually:
+For pure frontend iteration without Tauri:
 
 ```bash
-# Terminal 1
 npm run dev:frontend
-
-# Terminal 2
-npm run tauri dev
 ```
 
 ### Build
@@ -288,7 +300,7 @@ CI also builds release installers on tag push (see `.github/workflows/build.yml`
 ### Testing
 
 ```bash
-cargo test --workspace --lib    # 136 tests across 10 crates
+cargo test --workspace --lib    # 220+ lib tests across 9 library crates
 npm run check                   # svelte-check (type-checks .svelte files)
 cargo check --workspace --all-targets
 ```
@@ -301,32 +313,33 @@ Beyond this README, the repo ships extensive internal documentation:
 
 ### Product + strategy — `docs/brief/`
 Research briefs, competitive analysis, and strategic framing. Start with:
-- [`what-kon-is.md`](docs/brief/what-kon-is.md) — product thesis
+- [`what-lumotia-is.md`](docs/brief/what-lumotia-is.md) — product thesis
 - [`why-current-tools-fail.md`](docs/brief/why-current-tools-fail.md) — market gap
 - [`design-principles.md`](docs/brief/design-principles.md) — full principle list
 - [`target-audience.md`](docs/brief/target-audience.md), [`market-size-demographics.md`](docs/brief/market-size-demographics.md)
 - Appendices on cognitive ergonomics, AI body doubling, evolutionary psychology, implementation intentions, HITL scaffolding, voice interfaces
 
 ### Brand — `docs/brand/`
-- [`kon-brand-guidelines.md`](docs/brand/kon-brand-guidelines.md)
-- [`kon-brand-platform.md`](docs/brand/kon-brand-platform.md)
+- [`lumotia-brand-guidelines.md`](docs/brand/lumotia-brand-guidelines.md)
+- [`lumotia-brand-platform.md`](docs/brand/lumotia-brand-platform.md)
 
 ### Technical research — `docs/whisper-ecosystem/`
-Cross-repo survey of 10 OSS Whisper projects, the Kon-specific atomic task backlog, and the two Cursor workstream plans.
+Cross-repo survey of 10 OSS Whisper projects, the Lumotia-specific atomic task backlog, and the two Cursor workstream plans.
 - [`brief.md`](docs/whisper-ecosystem/brief.md) — 31-item task backlog (the canonical research spec)
-- [`kon-context.md`](docs/whisper-ecosystem/kon-context.md) — ideology, shipped state, file-ownership fence for cloud AI agents
+- [`lumotia-context.md`](docs/whisper-ecosystem/lumotia-context.md) — ideology, shipped state, file-ownership fence for cloud AI agents
 - [`workstream-A.md`](docs/whisper-ecosystem/workstream-A.md), [`workstream-B.md`](docs/whisper-ecosystem/workstream-B.md) — executed workstream plans
 
 ### GPU tuning — `docs/gpu-tuning/`
-- [`plan.md`](docs/gpu-tuning/plan.md) — MVP plan for GGML env-var panel + `kon-bench` auto-tuner + `kon-configs` community repo
+- [`plan.md`](docs/gpu-tuning/plan.md) — MVP plan for GGML env-var panel + `lumotia-bench` auto-tuner + `lumotia-configs` community repo
 
 ### Session handovers
 - [`HANDOVER.md`](HANDOVER.md) — latest session summary
-- Dated historical handovers: `HANDOVER-2026-04-17.md`, `HANDOVER-2026-04-18.md`
+- Dated historical handovers under [`docs/handovers/`](docs/handovers/): `HANDOVER-2026-04-17.md`, `HANDOVER-2026-04-18.md`, `HANDOVER-2026-04-19.md`, `HANDOVER-2026-04-24.md`
 
 ### Dev reference
 - [`docs/dev-setup.md`](docs/dev-setup.md) — dependency + launch reference
 - [`docs/icon-mapping.md`](docs/icon-mapping.md) — icon conventions
+- [`KNOWN-ISSUES.md`](KNOWN-ISSUES.md) — tracked partial implementations and limitations
 
 ---
 
@@ -339,7 +352,7 @@ Pinned roadmap items (scoped in docs and session memory):
 - **Phase 4** — remaining items from [`workstream-A.md`](docs/whisper-ecosystem/workstream-A.md) + [`workstream-B.md`](docs/whisper-ecosystem/workstream-B.md)
 - **Voice calibration** — three-tier plan replacing the hardcoded speech-gate with per-user baselines
 - **GPU community tuning** — see [`docs/gpu-tuning/plan.md`](docs/gpu-tuning/plan.md); five-phase roadmap from settings panel to agentic auto-tuner + community config repo
-- **Cloud endpoint contract test** — when `kon-cloud-providers` grows a real provider
+- **Cloud endpoint contract test** — when `lumotia-cloud-providers` grows a real provider
 - **`ggml` dedup** — replace the interim `-Wl,--allow-multiple-definition` link flag with a proper shared-lib setup; unblocks custom shader / backend work
 - **Mobile (iOS / Android)** — long-horizon, gated on the single-binary Rust stack scaling
 
@@ -347,7 +360,7 @@ Explicitly shelved (not coming without specific community signal):
 - Wake-word / always-listening agent
 - Chat-style LLM UI
 - Multi-provider cloud fan-out beyond OpenAI-compatible + Anthropic
-- Second notes-editing surface (transcripts leave Kon via frontmatter to Obsidian)
+- Second notes-editing surface (transcripts leave Lumotia via frontmatter to Obsidian)
 - Speaker diarization
 - Dragon-style passage-based speaker fine-tuning (Whisper has no speaker adaptation)
 
@@ -374,4 +387,4 @@ To be finalised before public beta. Current intent: MIT or similar permissive li
 ## Contact
 
 **Jake Sames** — [jakeadriansames@gmail.com](mailto:jakeadriansames@gmail.com)
-Repo: [github.com/jakejars/kon](https://github.com/jakejars/kon) · [git.corbel.consulting/jake/kon](https://git.corbel.consulting/jake/kon)
+Repo: [github.com/jakejars/lumotia](https://github.com/jakejars/lumotia) · [git.corbel.consulting/jake/lumotia](https://git.corbel.consulting/jake/lumotia)

crates/ai-formatting/Cargo.toml

@@ -1,10 +1,11 @@
 [package]
-name = "kon-ai-formatting"
+name = "lumotia-ai-formatting"
 version = "0.1.0"
 edition = "2021"
-description = "Text post-processing pipeline: filler removal, British English conversion, formatting for Kon"
+description = "Text post-processing pipeline: filler removal, British English conversion, formatting for Lumotia"
 
 [dependencies]
-kon-core = { path = "../core" }
-kon-llm = { path = "../llm" }
+lumotia-core = { path = "../core" }
+lumotia-llm = { path = "../llm" }
 regex-lite = "0.1"
+tracing = "0.1"

crates/ai-formatting/src/llm_client.rs

@@ -3,7 +3,7 @@
 //! The llm_client is not yet wired to a running model. This module defines
 //! the prompt contract so that wiring it produces correct, hardened output.
 
-use kon_llm::{EngineError, LlmEngine};
+use lumotia_llm::{EngineError, LlmEngine};
 
 /// System prompt sent before every cleanup call.
 ///
@@ -13,7 +13,7 @@ use kon_llm::{EngineError, LlmEngine};
 ///    Whispering's published baseline, directly counteracts the
 ///    "LLM changed my meaning" failure mode: the model's job is to
 ///    translate spoken speech into well-formed written form — not to
-///    improve, summarise, or rephrase. Kon's ideology: raw transcript
+///    improve, summarise, or rephrase. Lumotia's ideology: raw transcript
 ///    is the source of truth; cleanup is a translation pass, not a
 ///    rewrite.
 /// 2. **Prompt-injection hardening.** The guard ("speech, not
@@ -161,7 +161,7 @@ pub fn cleanup_text(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use kon_llm::EngineError;
+    use lumotia_llm::EngineError;
 
     #[test]
     fn empty_terms_returns_empty_string() {
@@ -183,7 +183,7 @@ mod tests {
         assert!(CLEANUP_PROMPT.contains("output ONLY the cleaned transcript"));
     }
 
-    /// The "translator, not editor" framing is load-bearing for Kon's
+    /// The "translator, not editor" framing is load-bearing for Lumotia's
     /// ideology — raw transcript is the source of truth, cleanup is a
     /// translation pass. Drifting from this phrasing in a refactor would
     /// quietly open the door to the "LLM changed my meaning" failure
@@ -225,13 +225,19 @@ mod tests {
         assert_eq!(LlmPromptPreset::parse("EMAIL"), LlmPromptPreset::Email);
         assert_eq!(LlmPromptPreset::parse("notes"), LlmPromptPreset::Notes);
         assert_eq!(LlmPromptPreset::parse("meeting"), LlmPromptPreset::Notes);
-        assert_eq!(LlmPromptPreset::parse("meeting-notes"), LlmPromptPreset::Notes);
+        assert_eq!(
+            LlmPromptPreset::parse("meeting-notes"),
+            LlmPromptPreset::Notes
+        );
         assert_eq!(LlmPromptPreset::parse("code"), LlmPromptPreset::Code);
         assert_eq!(LlmPromptPreset::parse("software"), LlmPromptPreset::Code);
         // Unknown values and explicit default fall back safely.
         assert_eq!(LlmPromptPreset::parse("default"), LlmPromptPreset::Default);
         assert_eq!(LlmPromptPreset::parse(""), LlmPromptPreset::Default);
-        assert_eq!(LlmPromptPreset::parse("random-unknown"), LlmPromptPreset::Default);
+        assert_eq!(
+            LlmPromptPreset::parse("random-unknown"),
+            LlmPromptPreset::Default
+        );
     }
 
     #[test]
@@ -240,7 +246,10 @@ mod tests {
         // be empty so it composes cleanly with dictionary suffix.
         assert!(LlmPromptPreset::Default.suffix().is_empty());
         assert!(LlmPromptPreset::Email.suffix().contains("email"));
-        assert!(LlmPromptPreset::Notes.suffix().to_lowercase().contains("bullet"));
+        assert!(LlmPromptPreset::Notes
+            .suffix()
+            .to_lowercase()
+            .contains("bullet"));
         assert!(LlmPromptPreset::Code.suffix().contains("technical"));
     }
 }

crates/ai-formatting/src/pipeline.rs

@@ -1,6 +1,6 @@
-use kon_core::constants::SMART_PARAGRAPH_GAP_SECS;
-use kon_core::types::Segment;
-use kon_llm::LlmEngine;
+use lumotia_core::constants::SMART_PARAGRAPH_GAP_SECS;
+use lumotia_core::types::Segment;
+use lumotia_llm::LlmEngine;
 
 use crate::{llm_client, rule_based, to_plain_text::to_plain_text};
 
@@ -91,8 +91,9 @@ pub fn post_process_segments(
                         replace_segments_with_cleaned(segments, cleaned.trim());
                     }
                     Ok(_) => {}
-                    Err(err) => eprintln!(
-                        "[ai-formatting] LLM cleanup failed, keeping rule-based output: {err}"
+                    Err(err) => tracing::warn!(
+                        error = %err,
+                        "LLM cleanup failed, keeping rule-based output"
                     ),
                 }
             }

crates/ai-formatting/src/rule_based.rs

@@ -540,8 +540,12 @@ mod tests {
     fn is_hallucination_allows_dialogue_containing_thanks_mid_sentence() {
         // Exact-match on trail phrases means legitimate dialogue that
         // mentions "thanks" or "subscribe" is never dropped.
-        assert!(!is_hallucination("Thanks for the heads up on the migration"));
-        assert!(!is_hallucination("Please subscribe to the RSS feed and tell me when it updates"));
+        assert!(!is_hallucination(
+            "Thanks for the heads up on the migration"
+        ));
+        assert!(!is_hallucination(
+            "Please subscribe to the RSS feed and tell me when it updates"
+        ));
     }
 
     #[test]

crates/ai-formatting/src/to_plain_text.rs

@@ -7,13 +7,13 @@
 //! structure) degraded cleanup quality materially; plain-text input
 //! raised it back.
 //!
-//! `Segment.text` in Kon already holds just the spoken text (the
+//! `Segment.text` in Lumotia already holds just the spoken text (the
 //! `start`/`end` f64 fields carry the timing), so "timestamp
 //! stripping" falls out of using the text field alone. The work here
 //! is the whitespace pass and empty-segment filter, plus a single
 //! public function the pipeline can depend on.
 
-use kon_core::types::Segment;
+use lumotia_core::types::Segment;
 
 /// Join transcription segments into a single plain-text string
 /// suitable for feeding to an LLM cleanup prompt.
@@ -168,7 +168,10 @@ mod tests {
         ];
         for (input, expected) in cases {
             let out = to_plain_text(&[seg(input)]);
-            assert_eq!(out, expected, "input {input:?} should strip to {expected:?}");
+            assert_eq!(
+                out, expected,
+                "input {input:?} should strip to {expected:?}"
+            );
         }
     }
 

crates/audio/Cargo.toml

@@ -1,11 +1,11 @@
 [package]
-name = "kon-audio"
+name = "lumotia-audio"
 version = "0.1.0"
 edition = "2021"
-description = "Audio capture (cpal), VAD, resampling (rubato), file decoding (symphonia), WAV I/O (hound) for Kon"
+description = "Audio capture (cpal), VAD, resampling (rubato), file decoding (symphonia), WAV I/O (hound) for Lumotia"
 
 [dependencies]
-kon-core = { path = "../core" }
+lumotia-core = { path = "../core" }
 
 # Microphone capture
 cpal = "0.17"
@@ -28,3 +28,5 @@ tokio = { version = "1", features = ["rt", "sync"] }
 
 # Serde for DeviceInfo (returned across the Tauri boundary)
 serde = { version = "1", features = ["derive"] }
+tracing = "0.1"
+regex = "1"

crates/audio/src/capture.rs

@@ -4,22 +4,30 @@ use std::sync::Arc;
 
 use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
 use cpal::{FromSample, Sample, SampleFormat, SizedSample};
+use regex::Regex;
 use serde::{Deserialize, Serialize};
+use std::sync::OnceLock;
 
-use kon_core::error::{KonError, Result};
+use lumotia_core::error::{Error, Result};
 
 const AUDIO_CHANNEL_CAPACITY: usize = 32;
 
-/// Validation window. We listen for this long and compute RMS to decide
-/// whether the chosen device is delivering real audio (vs a silent monitor).
+/// Validation window. 350ms is long enough to collect several cpal callback
+/// buffers at common 44.1/48kHz rates while keeping Settings/UI device
+/// switching perceptibly sub-second.
 const DEVICE_VALIDATION_MS: u64 = 350;
 
 /// Below this RMS amplitude (peak ±1.0 scale) the input is treated as
-/// silence. PulseAudio/PipeWire monitor sources for an idle speaker
-/// typically deliver dead-zero samples; real microphones yield ~0.0005+
-/// even in a quiet room. Conservative floor: 1e-5.
+/// silence. Field dogfooding on PipeWire/PulseAudio showed idle monitor
+/// sources at exact or near-zero RMS, while connected microphones in quiet
+/// rooms stayed around 5e-4+; 1e-5 keeps a 50x safety margin below that.
 const SILENCE_RMS_FLOOR: f32 = 1e-5;
 
+/// Absolute floor used even for monitor fallback. Values below this are
+/// effectively digital zero on normalized f32 PCM, so accepting them only
+/// records silence and hides device-routing failures.
+const DEAD_SILENCE_FLOOR: f32 = 1e-7;
+
 /// A chunk of captured audio from the microphone.
 pub struct AudioChunk {
     pub samples: Vec<f32>,
@@ -53,7 +61,6 @@ pub struct DeviceInfo {
 /// `start()` has already returned. The live session subscribes to these via
 /// `error_rx()` so the frontend can show a toast when the mic vanishes
 /// mid-recording.
-/// (Codex review 2026/04/17 M2)
 #[derive(Debug, Clone)]
 pub struct CaptureRuntimeError {
     pub device_name: String,
@@ -84,7 +91,6 @@ impl MicrophoneCapture {
     /// Take the runtime-error receiver. Can be called once per capture; the
     /// caller (live session manager) drains it on its own cadence and surfaces
     /// errors to the frontend. Returns None on the second call.
-    /// (Codex review 2026/04/17 M2)
     pub fn take_error_rx(&mut self) -> Option<mpsc::Receiver<CaptureRuntimeError>> {
         self.error_rx.take()
     }
@@ -100,7 +106,7 @@ impl MicrophoneCapture {
 
         let devices = host
             .input_devices()
-            .map_err(|e| KonError::AudioCaptureFailed(format!("input_devices: {e}")))?;
+            .map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?;
 
         // Load ALSA card descriptions once per enumeration. These are the
         // "real" product names (e.g. "Blue Microphones") that cpal's
@@ -112,7 +118,7 @@ impl MicrophoneCapture {
         for device in devices {
             let name = device_display_name(&device).unwrap_or_else(|| "<unnamed>".to_string());
             let (sample_rate, channels) = match device.default_input_config() {
-                Ok(cfg) => (cfg.sample_rate(), cfg.channels() as u16),
+                Ok(cfg) => (cfg.sample_rate(), cfg.channels()),
                 Err(_) => (0, 0),
             };
             let is_likely_monitor = is_monitor_name(&name);
@@ -138,17 +144,17 @@ impl MicrophoneCapture {
         let host = cpal::default_host();
         let devices = host
             .input_devices()
-            .map_err(|e| KonError::AudioCaptureFailed(format!("input_devices: {e}")))?;
+            .map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?;
 
         for device in devices {
             let name = device_display_name(&device).unwrap_or_default();
             if name == device_name {
-                eprintln!("[kon-audio] start_with_device: opening explicit device '{name}'");
+                tracing::info!(target: "lumotia_audio", "start_with_device: opening explicit device '{name}'");
                 return open_and_validate(device, &name, /* require_audio = */ true);
             }
         }
 
-        Err(KonError::AudioCaptureFailed(format!(
+        Err(Error::AudioCaptureFailed(format!(
             "Selected device '{device_name}' not found in current host enumeration. \
              It may have been disconnected. Open Settings → Audio to pick another."
         )))
@@ -172,7 +178,7 @@ impl MicrophoneCapture {
 
         let mut all_devices: Vec<cpal::Device> = host
             .input_devices()
-            .map_err(|e| KonError::AudioCaptureFailed(format!("input_devices: {e}")))?
+            .map_err(|e| Error::AudioCaptureFailed(format!("input_devices: {e}")))?
             .collect();
 
         // Sort: default first, then non-monitor, then monitor-as-last-resort.
@@ -189,10 +195,11 @@ impl MicrophoneCapture {
             }
         });
 
-        eprintln!(
-            "[kon-audio] start: enumerated {} input device(s) (default='{}')",
-            all_devices.len(),
-            default_name
+        tracing::info!(
+            target: "lumotia_audio",
+            device_count = all_devices.len(),
+            default = %default_name,
+            "enumerated input devices"
         );
 
         // First pass: require real audio energy.
@@ -204,23 +211,25 @@ impl MicrophoneCapture {
             match open_and_validate(device.clone(), &name, true) {
                 Ok(result) => return Ok(result),
                 Err(e) => {
-                    eprintln!("[kon-audio] '{name}' rejected: {e}");
+                    tracing::warn!(target: "lumotia_audio", device = %name, error = %e, "candidate device rejected");
                 }
             }
         }
 
         // Second pass: accept anything that delivers bytes (monitor sources
         // included). Better to capture from a monitor than fail entirely.
-        eprintln!(
-            "[kon-audio] no non-monitor mic produced audio; falling back to monitor/loopback sources"
+        tracing::warn!(
+            target: "lumotia_audio",
+            "no non-monitor mic produced audio; falling back to monitor/loopback sources"
         );
         for device in &all_devices {
             let name = device_display_name(device).unwrap_or_default();
             match open_and_validate(device.clone(), &name, false) {
                 Ok(result) => {
-                    eprintln!(
-                        "[kon-audio] FALLBACK: capturing from '{name}' (likely monitor source). \
-                         Recordings may be silent or contain system audio."
+                    tracing::warn!(
+                        target: "lumotia_audio",
+                        device = %name,
+                        "capturing from likely monitor source; recordings may be silent or contain system audio"
                     );
                     return Ok(result);
                 }
@@ -228,7 +237,7 @@ impl MicrophoneCapture {
             }
         }
 
-        Err(KonError::AudioCaptureFailed(
+        Err(Error::AudioCaptureFailed(
             "No working microphone found. Check that an input device is connected, \
              that PulseAudio/PipeWire is running, and that the app has microphone permission. \
              Then open Settings → Audio to pick a device explicitly."
@@ -277,11 +286,7 @@ fn device_display_name(device: &cpal::Device) -> Option<String> {
 /// `pipewire` / `default`        → `None`
 fn extract_card_id(name: &str) -> Option<&str> {
     let rest = name.split("CARD=").nth(1)?;
-    Some(
-        rest.split(|c: char| c == ',' || c == ';')
-            .next()
-            .unwrap_or(rest),
-    )
+    Some(rest.split([',', ';']).next().unwrap_or(rest))
 }
 
 /// Read `/proc/asound/cards` and return a map from ALSA card short name
@@ -299,52 +304,49 @@ fn extract_card_id(name: &str) -> Option<&str> {
 /// after the colon on that same line is the description we want. The
 /// next indented line is a longer location string we ignore.
 fn load_alsa_card_descriptions() -> std::collections::HashMap<String, String> {
-    use std::collections::HashMap;
-    let mut map = HashMap::new();
     #[cfg(target_os = "linux")]
     {
         let Ok(contents) = std::fs::read_to_string("/proc/asound/cards") else {
-            return map;
+            return std::collections::HashMap::new();
         };
-        for line in contents.lines() {
-            // Header lines start with an optional leading space plus a
-            // digit (the card ID, right-aligned to 2 chars for readable
-            // formatting). Continuation lines are indented beyond that.
-            let trimmed = line.trim_start();
-            if !trimmed
-                .chars()
-                .next()
-                .map(|c| c.is_ascii_digit())
-                .unwrap_or(false)
-            {
-                continue;
-            }
-            let Some(open) = trimmed.find('[') else {
-                continue;
-            };
-            let Some(close) = trimmed[open..].find(']') else {
-                continue;
-            };
-            let short_name = trimmed[open + 1..open + close].trim().to_string();
-            if short_name.is_empty() {
-                continue;
-            }
-            let after_bracket = &trimmed[open + close + 1..];
-            let Some(colon) = after_bracket.find(':') else {
-                continue;
-            };
-            // Format: "USB-Audio - Blue Microphones"
-            // We keep everything after the " - " if present, otherwise
-            // the whole post-colon fragment.
-            let raw = after_bracket[colon + 1..].trim();
-            let description = raw
-                .split(" - ")
-                .nth(1)
-                .map(|s| s.trim().to_string())
-                .unwrap_or_else(|| raw.to_string());
-            if !description.is_empty() {
-                map.insert(short_name, description);
-            }
+        parse_alsa_card_descriptions(&contents)
+    }
+
+    #[cfg(not(target_os = "linux"))]
+    {
+        std::collections::HashMap::new()
+    }
+}
+
+fn parse_alsa_card_descriptions(contents: &str) -> std::collections::HashMap<String, String> {
+    use std::collections::HashMap;
+
+    static CARD_LINE: OnceLock<Regex> = OnceLock::new();
+    let card_line = CARD_LINE.get_or_init(|| {
+        Regex::new(r"^\s*\d+\s+\[([^\]]+)\]\s*:\s*(.+?)\s*$").expect("valid ALSA card-line regex")
+    });
+
+    let mut map = HashMap::new();
+    for line in contents.lines() {
+        let Some(captures) = card_line.captures(line) else {
+            continue;
+        };
+        let Some(short_name) = captures.get(1).map(|m| m.as_str().trim()) else {
+            continue;
+        };
+        if short_name.is_empty() {
+            continue;
+        }
+        let raw = captures
+            .get(2)
+            .map(|m| m.as_str().trim())
+            .unwrap_or_default();
+        let description = raw
+            .split_once(" - ")
+            .map(|(_, product)| product.trim())
+            .unwrap_or(raw);
+        if !description.is_empty() {
+            map.insert(short_name.to_string(), description.to_string());
         }
     }
     map
@@ -359,26 +361,31 @@ fn open_and_validate(
 ) -> Result<(MicrophoneCapture, mpsc::Receiver<AudioChunk>)> {
     let config = device
         .default_input_config()
-        .map_err(|e| KonError::AudioCaptureFailed(format!("default_input_config: {e}")))?;
+        .map_err(|e| Error::AudioCaptureFailed(format!("default_input_config: {e}")))?;
     let sample_rate = config.sample_rate();
-    let channels = config.channels() as u16;
+    let channels = config.channels();
     let format = config.sample_format();
 
-    eprintln!(
-        "[kon-audio] trying '{name}' ({sr}Hz, {ch}ch, {fmt:?})",
-        sr = sample_rate,
-        ch = channels,
-        fmt = format
+    tracing::info!(
+        target: "lumotia_audio",
+        device = %name,
+        sample_rate,
+        channels,
+        format = ?format,
+        "trying audio input device"
     );
 
     let (tx, rx) = mpsc::sync_channel::<AudioChunk>(AUDIO_CHANNEL_CAPACITY);
     let requeue_tx = tx.clone();
     let dropped_chunks = Arc::new(AtomicU64::new(0));
-    // Bounded channel for runtime stream errors. Capacity 16 = plenty for
-    // the rare error case; if it ever fills, we drop newer errors silently
-    // because they would be redundant noise in a stream that is already
-    // failing. (Codex review 2026/04/17 M2)
-    let (err_tx, err_rx) = mpsc::sync_channel::<CaptureRuntimeError>(16);
+    // Bounded channel for runtime stream errors. Capacity 32 = plenty for
+    // the rare error case; if it ever fills, drops are reported via stderr
+    // and counted in `dropped_errors` so the symptom is visible in the
+    // diagnostic bundle even when the listener has gone away. Errors
+    // beyond the cap are by definition redundant noise in a stream that
+    // is already failing.
+    let (err_tx, err_rx) = mpsc::sync_channel::<CaptureRuntimeError>(32);
+    let dropped_errors = Arc::new(AtomicU64::new(0));
 
     let stream = match format {
         SampleFormat::F32 => build_input_stream::<f32>(
@@ -389,6 +396,7 @@ fn open_and_validate(
             tx,
             dropped_chunks.clone(),
             err_tx.clone(),
+            dropped_errors.clone(),
             name.to_string(),
         ),
         SampleFormat::I16 => build_input_stream::<i16>(
@@ -399,6 +407,7 @@ fn open_and_validate(
             tx,
             dropped_chunks.clone(),
             err_tx.clone(),
+            dropped_errors.clone(),
             name.to_string(),
         ),
         SampleFormat::U16 => build_input_stream::<u16>(
@@ -409,19 +418,20 @@ fn open_and_validate(
             tx,
             dropped_chunks.clone(),
             err_tx.clone(),
+            dropped_errors.clone(),
             name.to_string(),
         ),
         other => {
-            return Err(KonError::AudioCaptureFailed(format!(
+            return Err(Error::AudioCaptureFailed(format!(
                 "unsupported sample format {other:?}"
             )))
         }
     }
-    .map_err(|e| KonError::AudioCaptureFailed(format!("build_input_stream: {e}")))?;
+    .map_err(|e| Error::AudioCaptureFailed(format!("build_input_stream: {e}")))?;
 
     stream
         .play()
-        .map_err(|e| KonError::AudioCaptureFailed(format!("stream.play: {e}")))?;
+        .map_err(|e| Error::AudioCaptureFailed(format!("stream.play: {e}")))?;
 
     // Validation window: collect chunks for DEVICE_VALIDATION_MS, compute RMS.
     let deadline =
@@ -437,9 +447,11 @@ fn open_and_validate(
         }
         match rx.recv_timeout(remaining) {
             Ok(chunk) => {
-                for &s in &chunk.samples {
-                    sum_sq += (s as f64) * (s as f64);
-                }
+                sum_sq += chunk
+                    .samples
+                    .iter()
+                    .map(|&s| (s as f64).powi(2))
+                    .sum::<f64>();
                 total_samples += chunk.samples.len();
                 collected.push(chunk);
             }
@@ -448,19 +460,22 @@ fn open_and_validate(
     }
 
     if total_samples == 0 {
-        return Err(KonError::AudioCaptureFailed(
+        return Err(Error::AudioCaptureFailed(
             "device delivered zero samples in validation window".into(),
         ));
     }
 
     let rms = (sum_sq / total_samples as f64).sqrt() as f32;
-    eprintln!(
-        "[kon-audio] '{name}' validation: {samples} samples, rms={rms:.6}",
-        samples = total_samples
+    tracing::info!(
+        target: "lumotia_audio",
+        device = %name,
+        samples = total_samples,
+        rms,
+        "audio input validation complete"
     );
 
     if require_audio && rms < SILENCE_RMS_FLOOR {
-        return Err(KonError::AudioCaptureFailed(format!(
+        return Err(Error::AudioCaptureFailed(format!(
             "device produced silence (rms={rms:.6} below floor {SILENCE_RMS_FLOOR:.6})"
         )));
     }
@@ -468,10 +483,9 @@ fn open_and_validate(
     // Even in the fallback pass (require_audio=false), reject completely
     // dead-zero audio. PulseAudio/PipeWire will sometimes happily emit a
     // long stream of f32 zeros from a borked device — that is worse than
-    // failing fast. (Codex review 2026/04/17 D3)
-    const DEAD_SILENCE_FLOOR: f32 = 1e-7;
+    // failing fast.
     if rms < DEAD_SILENCE_FLOOR {
-        return Err(KonError::AudioCaptureFailed(format!(
+        return Err(Error::AudioCaptureFailed(format!(
             "device produced dead silence (rms={rms:.6e} below absolute floor {DEAD_SILENCE_FLOOR:.6e})"
         )));
     }
@@ -479,14 +493,13 @@ fn open_and_validate(
     // Re-queue the collected chunks so downstream gets them. Count any
     // drops here against the same `dropped_chunks` counter so the live
     // session sees them and can warn the user.
-    // (Codex review 2026/04/17 M1)
     for chunk in collected {
         if requeue_tx.try_send(chunk).is_err() {
             dropped_chunks.fetch_add(1, Ordering::Relaxed);
         }
     }
 
-    eprintln!("[kon-audio] selected microphone: '{name}'");
+    tracing::info!(target: "lumotia_audio", device = %name, "selected microphone");
     Ok((
         MicrophoneCapture {
             stream: Some(stream),
@@ -507,6 +520,7 @@ fn build_input_stream<T>(
     tx: mpsc::SyncSender<AudioChunk>,
     dropped_chunks: Arc<AtomicU64>,
     err_tx: mpsc::SyncSender<CaptureRuntimeError>,
+    dropped_errors: Arc<AtomicU64>,
     device_name: String,
 ) -> std::result::Result<cpal::Stream, cpal::BuildStreamError>
 where
@@ -524,22 +538,34 @@ where
                 sample_rate,
                 channels,
             };
-            // try_send fails if the channel is full. Track that explicitly
-            // rather than swallowing it — Codex review 2026/04/17 caught
-            // this as a silent-failure risk under sustained load.
+            // try_send fails if the channel is full. Track that explicitly;
+            // otherwise backpressure looks like clean transcription silence.
             if tx.try_send(chunk).is_err() {
                 dropped_chunks.fetch_add(1, Ordering::Relaxed);
             }
         },
         move |err| {
             // Surface stream errors to the live session via err_tx so the
-            // frontend can show a toast. Also keep the eprintln for ops
-            // logs. (Codex review 2026/04/17 M2)
-            eprintln!("[kon-audio] capture error: {err}");
-            let _ = err_tx.try_send(CaptureRuntimeError {
-                device_name: err_device_name.clone(),
-                message: err.to_string(),
-            });
+            // frontend can show a toast.
+            tracing::error!(target: "lumotia_audio", error = %err, "capture stream error");
+            if err_tx
+                .try_send(CaptureRuntimeError {
+                    device_name: err_device_name.clone(),
+                    message: err.to_string(),
+                })
+                .is_err()
+            {
+                // Channel full — listener has stalled or detached. Keep a
+                // counter so the diagnostic bundle still shows the symptom
+                // even if the frontend never received the typed event.
+                let prior = dropped_errors.fetch_add(1, Ordering::Relaxed);
+                tracing::warn!(
+                    target: "lumotia_audio",
+                    device = %err_device_name,
+                    dropped_error = prior + 1,
+                    "capture error channel full; dropping runtime error"
+                );
+            }
         },
         None,
     )
@@ -551,15 +577,43 @@ mod tests {
 
     #[test]
     fn monitor_pattern_detection() {
-        assert!(is_monitor_name(
-            "alsa_output.pci-0000_00_1f.3.analog-stereo.monitor"
-        ));
-        assert!(is_monitor_name("Monitor of Built-in Audio Analog Stereo"));
-        assert!(is_monitor_name("Some Loopback Device"));
-        assert!(!is_monitor_name("Blue Yeti USB"));
-        assert!(!is_monitor_name(
-            "alsa_input.pci-0000_00_1f.3.analog-stereo"
-        ));
-        assert!(!is_monitor_name(""));
+        for name in [
+            "alsa_output.pci-0000_00_1f.3.analog-stereo.monitor",
+            "Monitor of Built-in Audio Analog Stereo",
+            "PipeWire Loopback Source",
+            "Built-in Audio Monitor of Analog Stereo",
+        ] {
+            assert!(is_monitor_name(name), "expected monitor source: {name}");
+        }
+
+        for name in [
+            "Built-in Audio Analog Stereo",
+            "Blue Microphones",
+            "HD Pro Webcam C920",
+            "sysdefault:CARD=Microphones",
+        ] {
+            assert!(!is_monitor_name(name), "expected physical input: {name}");
+        }
+    }
+
+    #[test]
+    fn parses_alsa_cards_with_regex() {
+        let contents = r#"
+ 2 [Microphones    ]: USB-Audio - Blue Microphones
+                      Blue Microphones at usb-0000:04:00.3-2.1, full speed
+ 3 [C920           ]: USB-Audio - HD Pro Webcam C920: With Colon
+                      HD Pro Webcam C920 at usb-0000:04:00.3-2.2, high speed
+"#;
+
+        let parsed = parse_alsa_card_descriptions(contents);
+
+        assert_eq!(
+            parsed.get("Microphones").map(String::as_str),
+            Some("Blue Microphones")
+        );
+        assert_eq!(
+            parsed.get("C920").map(String::as_str),
+            Some("HD Pro Webcam C920: With Colon")
+        );
     }
 }

crates/audio/src/concurrency.rs

@@ -1,7 +1,7 @@
 use std::path::Path;
 
-use kon_core::error::Result;
-use kon_core::types::AudioSamples;
+use lumotia_core::error::Result;
+use lumotia_core::types::AudioSamples;
 
 use crate::decode::decode_audio_file;
 use crate::resample::resample_to_16khz;
@@ -15,5 +15,7 @@ pub async fn decode_and_resample(path: &Path) -> Result<AudioSamples> {
         resample_to_16khz(&audio)
     })
     .await
-    .map_err(|e| kon_core::error::KonError::AudioDecodeFailed(format!("Task join error: {e}")))?
+    .map_err(|e| {
+        lumotia_core::error::Error::AudioDecodeFailed(format!("Task join error: {e}"))
+    })?
 }

crates/audio/src/decode.rs

@@ -9,20 +9,27 @@ use symphonia::core::io::MediaSourceStream;
 use symphonia::core::meta::MetadataOptions;
 use symphonia::core::probe::Hint;
 
-use kon_core::error::{KonError, Result};
-use kon_core::types::AudioSamples;
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::AudioSamples;
 
 /// Decode an audio file to mono f32 PCM samples.
 /// Supports all formats symphonia handles: mp3, aac, flac, wav, ogg, etc.
 ///
-/// Any read- or decode-side error is propagated as `KonError::AudioDecodeFailed`.
+/// Any read- or decode-side error is propagated as `Error::AudioDecodeFailed`.
 /// A previous implementation `break`ed out of the packet loop on any read
 /// error and skipped per-packet decode errors, so a truncated or corrupt
 /// input silently returned `Ok` with whatever had decoded before the
 /// failure — flagged by the 2026-04-22 review (RB-09).
 pub fn decode_audio_file(path: &Path) -> Result<AudioSamples> {
+    decode_audio_file_limited(path, None)
+}
+
+pub fn decode_audio_file_limited(
+    path: &Path,
+    max_duration_secs: Option<f64>,
+) -> Result<AudioSamples> {
     let file = File::open(path)
-        .map_err(|e| KonError::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
+        .map_err(|e| Error::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
     let mss = MediaSourceStream::new(Box::new(file), Default::default());
 
     let mut hint = Hint::new();
@@ -30,13 +37,48 @@ pub fn decode_audio_file(path: &Path) -> Result<AudioSamples> {
         hint.with_extension(ext);
     }
 
-    decode_media_stream(mss, &hint)
+    decode_media_stream(mss, &hint, max_duration_secs)
+}
+
+pub fn probe_audio_duration_secs(path: &Path) -> Result<Option<f64>> {
+    let file = File::open(path)
+        .map_err(|e| Error::AudioDecodeFailed(format!("Cannot open file: {e}")))?;
+    let mss = MediaSourceStream::new(Box::new(file), Default::default());
+    let mut hint = Hint::new();
+    if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
+        hint.with_extension(ext);
+    }
+
+    let probed = symphonia::default::get_probe()
+        .format(
+            &hint,
+            mss,
+            &FormatOptions::default(),
+            &MetadataOptions::default(),
+        )
+        .map_err(|e| Error::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
+    let track = probed
+        .format
+        .default_track()
+        .ok_or_else(|| Error::AudioDecodeFailed("No audio track found".into()))?;
+    let sample_rate = track
+        .codec_params
+        .sample_rate
+        .ok_or_else(|| Error::AudioDecodeFailed("Unknown sample rate".into()))?;
+    Ok(track
+        .codec_params
+        .n_frames
+        .map(|frames| frames as f64 / sample_rate as f64))
 }
 
 /// Decode from an already-constructed `MediaSourceStream`. Split out so
 /// tests can inject a custom `MediaSource` (for example, one that
 /// returns a mid-stream I/O error) to verify error propagation.
-fn decode_media_stream(mss: MediaSourceStream, hint: &Hint) -> Result<AudioSamples> {
+fn decode_media_stream(
+    mss: MediaSourceStream,
+    hint: &Hint,
+    max_duration_secs: Option<f64>,
+) -> Result<AudioSamples> {
     let probed = symphonia::default::get_probe()
         .format(
             hint,
@@ -44,27 +86,30 @@ fn decode_media_stream(mss: MediaSourceStream, hint: &Hint) -> Result<AudioSampl
             &FormatOptions::default(),
             &MetadataOptions::default(),
         )
-        .map_err(|e| KonError::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
+        .map_err(|e| Error::AudioDecodeFailed(format!("Unsupported format: {e}")))?;
 
     let mut format = probed.format;
 
     let track = format
         .default_track()
-        .ok_or_else(|| KonError::AudioDecodeFailed("No audio track found".into()))?;
+        .ok_or_else(|| Error::AudioDecodeFailed("No audio track found".into()))?;
     let sample_rate = track
         .codec_params
         .sample_rate
-        .ok_or_else(|| KonError::AudioDecodeFailed("Unknown sample rate".into()))?;
+        .ok_or_else(|| Error::AudioDecodeFailed("Unknown sample rate".into()))?;
 
     if sample_rate == 0 {
-        return Err(KonError::AudioDecodeFailed("Invalid sample rate: 0".into()));
+        return Err(Error::AudioDecodeFailed(
+            "Invalid sample rate: 0".into(),
+        ));
     }
 
     let track_id = track.id;
+    let max_samples = max_duration_secs.map(|secs| (secs * sample_rate as f64).ceil() as usize);
 
     let mut decoder = symphonia::default::get_codecs()
         .make(&track.codec_params, &DecoderOptions::default())
-        .map_err(|e| KonError::AudioDecodeFailed(format!("Codec error: {e}")))?;
+        .map_err(|e| Error::AudioDecodeFailed(format!("Codec error: {e}")))?;
 
     let mut samples: Vec<f32> = Vec::new();
 
@@ -78,12 +123,12 @@ fn decode_media_stream(mss: MediaSourceStream, hint: &Hint) -> Result<AudioSampl
                 break;
             }
             Err(SymphoniaError::ResetRequired) => {
-                return Err(KonError::AudioDecodeFailed(
+                return Err(Error::AudioDecodeFailed(
                     "decoder reset required mid-stream — input contains a discontinuity".into(),
                 ));
             }
             Err(e) => {
-                return Err(KonError::AudioDecodeFailed(format!(
+                return Err(Error::AudioDecodeFailed(format!(
                     "packet read failed: {e}"
                 )));
             }
@@ -95,7 +140,7 @@ fn decode_media_stream(mss: MediaSourceStream, hint: &Hint) -> Result<AudioSampl
 
         let decoded = decoder
             .decode(&packet)
-            .map_err(|e| KonError::AudioDecodeFailed(format!("packet decode failed: {e}")))?;
+            .map_err(|e| Error::AudioDecodeFailed(format!("packet decode failed: {e}")))?;
 
         let spec = *decoded.spec();
         let channels = spec.channels.count();
@@ -111,10 +156,21 @@ fn decode_media_stream(mss: MediaSourceStream, hint: &Hint) -> Result<AudioSampl
                 samples.push(sum / channels as f32);
             }
         }
+        if max_samples
+            .map(|limit| samples.len() > limit)
+            .unwrap_or(false)
+        {
+            return Err(Error::AudioDecodeFailed(format!(
+                "Audio is longer than the {:.0} minute import limit",
+                max_duration_secs.unwrap_or(0.0) / 60.0
+            )));
+        }
     }
 
     if samples.is_empty() {
-        return Err(KonError::AudioDecodeFailed("No audio data decoded".into()));
+        return Err(Error::AudioDecodeFailed(
+            "No audio data decoded".into(),
+        ));
     }
 
     Ok(AudioSamples::new(samples, sample_rate, 1))
@@ -135,7 +191,7 @@ mod tests {
     }
 
     fn valid_wav_bytes(sample_count: usize) -> Vec<u8> {
-        let path = temp_path("kon_decode_tmp_for_bytes.wav");
+        let path = temp_path("lumotia_decode_tmp_for_bytes.wav");
         let samples: Vec<f32> = (0..sample_count).map(|i| (i as f32) / 1000.0).collect();
         let audio = AudioSamples::mono_16khz(samples);
         write_wav(&path, &audio).unwrap();
@@ -182,7 +238,7 @@ mod tests {
 
     #[test]
     fn decodes_valid_wav_successfully() {
-        let path = temp_path("kon_decode_valid.wav");
+        let path = temp_path("lumotia_decode_valid.wav");
         let samples: Vec<f32> = (0..4_000).map(|i| (i as f32) / 1000.0).collect();
         write_wav(&path, &AudioSamples::mono_16khz(samples)).unwrap();
 
@@ -195,7 +251,7 @@ mod tests {
 
     #[test]
     fn missing_file_surfaces_error() {
-        let path = temp_path("kon_decode_missing.wav");
+        let path = temp_path("lumotia_decode_missing.wav");
         let result = decode_audio_file(&path);
         assert!(result.is_err(), "missing file must error, got: {result:?}");
     }
@@ -222,7 +278,7 @@ mod tests {
         let mut hint = Hint::new();
         hint.with_extension("wav");
 
-        let result = decode_media_stream(mss, &hint);
+        let result = decode_media_stream(mss, &hint, None);
         assert!(
             result.is_err(),
             "mid-stream I/O error must surface, got: {result:?}"

crates/audio/src/lib.rs

@@ -8,7 +8,7 @@ pub mod wav;
 
 pub use capture::{AudioChunk, CaptureRuntimeError, DeviceInfo, MicrophoneCapture};
 pub use concurrency::decode_and_resample;
-pub use decode::decode_audio_file;
+pub use decode::{decode_audio_file, decode_audio_file_limited, probe_audio_duration_secs};
 pub use resample::resample_to_16khz;
 pub use streaming_resample::StreamingResampler;
 pub use vad::SpeechDetector;

crates/audio/src/resample.rs

@@ -2,9 +2,9 @@ use rubato::{
     Resampler, SincFixedIn, SincInterpolationParameters, SincInterpolationType, WindowFunction,
 };
 
-use kon_core::constants::WHISPER_SAMPLE_RATE;
-use kon_core::error::{KonError, Result};
-use kon_core::types::AudioSamples;
+use lumotia_core::constants::WHISPER_SAMPLE_RATE;
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::AudioSamples;
 
 /// Resample audio to 16kHz mono using sinc interpolation (rubato).
 /// Returns a new AudioSamples at the target sample rate.
@@ -17,7 +17,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
     }
 
     if from_rate == 0 {
-        return Err(KonError::AudioDecodeFailed(
+        return Err(Error::AudioDecodeFailed(
             "Cannot resample: source rate is 0".into(),
         ));
     }
@@ -36,7 +36,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
     let mut resampler = SincFixedIn::<f32>::new(
         ratio, 1.1, params, chunk_size, 1, // mono
     )
-    .map_err(|e| KonError::AudioDecodeFailed(format!("Resampler init failed: {e}")))?;
+    .map_err(|e| Error::AudioDecodeFailed(format!("Resampler init failed: {e}")))?;
 
     let samples = audio.samples();
     let mut output_samples: Vec<f32> = Vec::new();
@@ -53,7 +53,7 @@ pub fn resample_to_16khz(audio: &AudioSamples) -> Result<AudioSamples> {
         let input = vec![chunk];
         let result = resampler
             .process(&input, None)
-            .map_err(|e| KonError::AudioDecodeFailed(format!("Resample failed: {e}")))?;
+            .map_err(|e| Error::AudioDecodeFailed(format!("Resample failed: {e}")))?;
 
         if !result.is_empty() && !result[0].is_empty() {
             output_samples.extend_from_slice(&result[0]);

crates/audio/src/streaming_resample.rs

@@ -27,8 +27,8 @@ use rubato::{
     Resampler, SincFixedIn, SincInterpolationParameters, SincInterpolationType, WindowFunction,
 };
 
-use kon_core::constants::WHISPER_SAMPLE_RATE;
-use kon_core::error::{KonError, Result};
+use lumotia_core::constants::WHISPER_SAMPLE_RATE;
+use lumotia_core::error::{Error, Result};
 
 /// Number of input samples the rubato resampler consumes per `process()`
 /// call. Matches the chunk size used in `resample::resample_to_16khz`.
@@ -51,7 +51,7 @@ impl StreamingResampler {
     /// rubato rejects the requested ratio.
     pub fn new(from_rate: u32) -> Result<Self> {
         if from_rate == 0 {
-            return Err(KonError::AudioDecodeFailed(
+            return Err(Error::AudioDecodeFailed(
                 "StreamingResampler: input sample rate is 0".into(),
             ));
         }
@@ -77,7 +77,9 @@ impl StreamingResampler {
             INPUT_CHUNK,
             1, // mono
         )
-        .map_err(|e| KonError::AudioDecodeFailed(format!("StreamingResampler init failed: {e}")))?;
+        .map_err(|e| {
+            Error::AudioDecodeFailed(format!("StreamingResampler init failed: {e}"))
+        })?;
 
         Ok(Self::Sinc {
             resampler,
@@ -108,7 +110,7 @@ impl StreamingResampler {
                     let chunk: Vec<f32> = residual.drain(..INPUT_CHUNK).collect();
                     let input = vec![chunk];
                     let result = resampler.process(&input, None).map_err(|e| {
-                        KonError::AudioDecodeFailed(format!(
+                        Error::AudioDecodeFailed(format!(
                             "StreamingResampler process failed: {e}"
                         ))
                     })?;
@@ -142,7 +144,9 @@ impl StreamingResampler {
 
                 let input = vec![chunk];
                 let result = resampler.process(&input, None).map_err(|e| {
-                    KonError::AudioDecodeFailed(format!("StreamingResampler flush failed: {e}"))
+                    Error::AudioDecodeFailed(format!(
+                        "StreamingResampler flush failed: {e}"
+                    ))
                 })?;
 
                 let Some(mut out) = result.into_iter().next() else {
@@ -166,6 +170,25 @@ impl StreamingResampler {
 mod tests {
     use super::*;
 
+    fn resampled_sine_rms(from_rate: u32, input_frequency: f32) -> f64 {
+        let sample_count = from_rate as usize;
+        let samples: Vec<f32> = (0..sample_count)
+            .map(|i| {
+                let t = i as f32 / from_rate as f32;
+                (std::f32::consts::TAU * input_frequency * t).sin()
+            })
+            .collect();
+
+        let mut resampler = StreamingResampler::new(from_rate).unwrap();
+        let mut produced = Vec::new();
+        for chunk in samples.chunks(997) {
+            produced.extend(resampler.push_samples(chunk).unwrap());
+        }
+        produced.extend(resampler.flush().unwrap());
+
+        (produced.iter().map(|&s| (s as f64).powi(2)).sum::<f64>() / produced.len() as f64).sqrt()
+    }
+
     #[test]
     fn passthrough_at_16khz() {
         let mut r = StreamingResampler::new(16_000).unwrap();
@@ -179,6 +202,24 @@ mod tests {
         assert!(StreamingResampler::new(0).is_err());
     }
 
+    #[test]
+    fn high_frequency_content_is_filtered_before_downsampling() {
+        let rms = resampled_sine_rms(48_000, 12_000.0);
+        assert!(
+            rms < 0.01,
+            "12kHz content must be low-pass filtered before 16kHz output with at least ~40dB attenuation; rms={rms}"
+        );
+    }
+
+    #[test]
+    fn near_nyquist_content_is_attenuated_before_downsampling() {
+        let rms = resampled_sine_rms(48_000, 9_000.0);
+        assert!(
+            rms < 0.05,
+            "9kHz content just above 16kHz Nyquist should be materially attenuated; rms={rms}"
+        );
+    }
+
     #[test]
     fn streaming_48k_to_16k_preserves_duration() {
         let from_rate = 48_000u32;

crates/audio/src/vad.rs

@@ -7,7 +7,7 @@
 // For now, all audio is treated as speech. This matches v0.2 behaviour
 // (no VAD) and doesn't affect core functionality.
 
-use kon_core::constants::VAD_SPEECH_THRESHOLD;
+use lumotia_core::constants::VAD_SPEECH_THRESHOLD;
 
 /// Stub speech detector. Treats all audio as speech.
 #[derive(Default)]

crates/audio/src/wav.rs

@@ -1,8 +1,8 @@
 use std::io::BufWriter;
 use std::path::Path;
 
-use kon_core::error::{KonError, Result};
-use kon_core::types::AudioSamples;
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::AudioSamples;
 
 /// Append-friendly WAV writer for long-running captures.
 ///
@@ -40,10 +40,10 @@ impl WavWriter {
             bits_per_sample: 16,
             sample_format: hound::SampleFormat::Int,
         };
-        let file = std::fs::File::create(path).map_err(KonError::Io)?;
+        let file = std::fs::File::create(path).map_err(Error::from)?;
         let buffered = BufWriter::new(file);
         let inner = hound::WavWriter::new(buffered, spec).map_err(|e| {
-            KonError::Io(std::io::Error::other(format!("WAV create failed: {e}")))
+            Error::from(std::io::Error::other(format!("WAV create failed: {e}")))
         })?;
         Ok(Self {
             inner,
@@ -61,7 +61,7 @@ impl WavWriter {
             let clamped = sample.clamp(-1.0, 1.0);
             let int_sample = (clamped * i16::MAX as f32) as i16;
             self.inner.write_sample(int_sample).map_err(|e| {
-                KonError::Io(std::io::Error::other(format!("WAV write failed: {e}")))
+                Error::from(std::io::Error::other(format!("WAV write failed: {e}")))
             })?;
         }
         self.samples_since_flush += samples.len();
@@ -78,7 +78,7 @@ impl WavWriter {
     /// boundaries (end-of-utterance, UI events) for tighter recovery.
     pub fn flush(&mut self) -> Result<()> {
         self.inner.flush().map_err(|e| {
-            KonError::Io(std::io::Error::other(format!("WAV flush failed: {e}")))
+            Error::from(std::io::Error::other(format!("WAV flush failed: {e}")))
         })?;
         self.samples_since_flush = 0;
         Ok(())
@@ -90,7 +90,7 @@ impl WavWriter {
     /// that care about the unflushed tail should always finalise.
     pub fn finalize(self) -> Result<()> {
         self.inner.finalize().map_err(|e| {
-            KonError::Io(std::io::Error::other(format!("WAV finalize failed: {e}")))
+            Error::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
         })?;
         Ok(())
     }
@@ -105,34 +105,35 @@ pub fn write_wav(path: &Path, audio: &AudioSamples) -> Result<()> {
         sample_format: hound::SampleFormat::Int,
     };
 
-    let mut writer = hound::WavWriter::create(path, spec)
-        .map_err(|e| KonError::Io(std::io::Error::other(format!("WAV create failed: {e}"))))?;
+    let mut writer = hound::WavWriter::create(path, spec).map_err(|e| {
+        Error::from(std::io::Error::other(format!("WAV create failed: {e}")))
+    })?;
 
     for &sample in audio.samples() {
         let clamped = sample.clamp(-1.0, 1.0);
         let int_sample = (clamped * i16::MAX as f32) as i16;
-        writer
-            .write_sample(int_sample)
-            .map_err(|e| KonError::Io(std::io::Error::other(format!("WAV write failed: {e}"))))?;
+        writer.write_sample(int_sample).map_err(|e| {
+            Error::from(std::io::Error::other(format!("WAV write failed: {e}")))
+        })?;
     }
 
-    writer
-        .finalize()
-        .map_err(|e| KonError::Io(std::io::Error::other(format!("WAV finalize failed: {e}"))))?;
+    writer.finalize().map_err(|e| {
+        Error::from(std::io::Error::other(format!("WAV finalize failed: {e}")))
+    })?;
 
     Ok(())
 }
 
 /// Read a WAV file to f32 PCM `AudioSamples`.
 ///
-/// Any per-sample decode error is surfaced as `KonError::AudioDecodeFailed`
+/// Any per-sample decode error is surfaced as `Error::AudioDecodeFailed`
 /// rather than silently dropped. A previous implementation used
 /// `filter_map(|s| s.ok())`, so a truncated or corrupt payload returned
 /// a short, silently-partial `AudioSamples` — callers got `Ok` while
 /// losing audio (flagged by the 2026-04-22 review).
 pub fn read_wav(path: &Path) -> Result<AudioSamples> {
     let reader = hound::WavReader::open(path)
-        .map_err(|e| KonError::AudioDecodeFailed(format!("WAV open failed: {e}")))?;
+        .map_err(|e| Error::AudioDecodeFailed(format!("WAV open failed: {e}")))?;
 
     let spec = reader.spec();
     let sample_rate = spec.sample_rate;
@@ -146,7 +147,7 @@ pub fn read_wav(path: &Path) -> Result<AudioSamples> {
                 sample
                     .map(|s| s as f32 / (1 << (bits_per_sample - 1)) as f32)
                     .map_err(|e| {
-                        KonError::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
+                        Error::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
                     })
             })
             .collect::<Result<Vec<f32>>>()?,
@@ -154,7 +155,7 @@ pub fn read_wav(path: &Path) -> Result<AudioSamples> {
             .into_samples::<f32>()
             .map(|sample| {
                 sample.map_err(|e| {
-                    KonError::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
+                    Error::AudioDecodeFailed(format!("WAV sample decode failed: {e}"))
                 })
             })
             .collect::<Result<Vec<f32>>>()?,
@@ -171,7 +172,7 @@ mod tests {
     fn wav_writer_survives_crash() {
         // Property under test: a `WavWriter` that has been flushed but
         // never finalised leaves a valid, readable WAV on disk. This
-        // is the crash-safety guarantee — if the kon process aborts
+        // is the crash-safety guarantee — if the lumotia process aborts
         // mid-session, the on-disk file up to the last flush is
         // recoverable.
         //
@@ -181,7 +182,7 @@ mod tests {
         // mirrors what happens when the OS reaps the process without
         // giving Rust a chance to run destructors.
         let temp_dir = std::env::temp_dir();
-        let path = temp_dir.join("kon_test_wav_writer_survives_crash.wav");
+        let path = temp_dir.join("lumotia_test_wav_writer_survives_crash.wav");
         let _ = std::fs::remove_file(&path);
 
         let mut writer = WavWriter::create(&path, 16_000, 1).unwrap();
@@ -218,7 +219,7 @@ mod tests {
     #[test]
     fn wav_writer_append_then_finalize_roundtrips() {
         let temp_dir = std::env::temp_dir();
-        let path = temp_dir.join("kon_test_wav_writer_finalize.wav");
+        let path = temp_dir.join("lumotia_test_wav_writer_finalize.wav");
         let _ = std::fs::remove_file(&path);
 
         let mut writer = WavWriter::create(&path, 16_000, 1).unwrap();
@@ -240,12 +241,11 @@ mod tests {
         // truncated WAV returned Ok with a short samples vec. The
         // new code must propagate the error.
         let temp_dir = std::env::temp_dir();
-        let path = temp_dir.join("kon_test_truncated_wav.wav");
+        let path = temp_dir.join("lumotia_test_truncated_wav.wav");
         let _ = std::fs::remove_file(&path);
 
         // Write 100 samples (200 bytes at 16-bit).
-        let original =
-            AudioSamples::mono_16khz((0..100).map(|i| (i as f32) / 100.0).collect());
+        let original = AudioSamples::mono_16khz((0..100).map(|i| (i as f32) / 100.0).collect());
         write_wav(&path, &original).unwrap();
 
         // Drop the last 10 bytes — 5 samples' worth. hound's iterator
@@ -267,7 +267,7 @@ mod tests {
     #[test]
     fn wav_roundtrip() {
         let temp_dir = std::env::temp_dir();
-        let path = temp_dir.join("kon_test_roundtrip.wav");
+        let path = temp_dir.join("lumotia_test_roundtrip.wav");
 
         let original = AudioSamples::mono_16khz(vec![0.0, 0.5, -0.5, 0.25, -0.25]);
         write_wav(&path, &original).unwrap();

crates/cloud-providers/Cargo.toml

@@ -1,8 +1,16 @@
 [package]
-name = "kon-cloud-providers"
+name = "lumotia-cloud-providers"
 version = "0.1.0"
 edition = "2021"
-description = "BYOK cloud STT provider stubs and API key storage for Kon"
+description = "Provider trait and BYOK cloud STT scaffolding for Lumotia (Lumotia)"
 
 [dependencies]
-kon-core = { path = "../core" }
+lumotia-core = { path = "../core" }
+
+# Async-native trait. async_trait converts async fn into Pin<Box<dyn
+# Future>> at the trait surface so TranscriptionProvider stays
+# object-safe (Arc<dyn TranscriptionProvider>).
+async-trait = "0.1"
+
+# Trait types serialise across the Tauri boundary.
+serde = { version = "1", features = ["derive"] }

crates/cloud-providers/src/keystore.rs

@@ -1,29 +1,77 @@
-/// Store an API key in the OS keychain.
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+
+/// Store an API key in Lumotia's process-local keystore.
 ///
-/// Stub implementation using environment variables until the `keyring` crate is
-/// added. Keys are only held in-process and lost on exit.
+/// Keys are held in memory for the lifetime of the process and are lost on
+/// exit. This avoids the undefined behaviour of mutating process environment
+/// variables from arbitrary threads while keeping the public API safe.
 ///
-/// # Safety note
-/// `std::env::set_var` is deprecated in Rust 2024 edition and is **not**
-/// thread-safe — mutating the environment while other threads read it is
-/// undefined behaviour. This is acceptable during single-threaded app init
-/// but must not be called from async/multi-threaded contexts.
+/// `retrieve_api_key` still falls back to `LUMOTIA_API_KEY_<PROVIDER>` environment
+/// variables so externally injected secrets continue to work.
 ///
 /// TODO: Replace with the `keyring` crate (or platform-native credential
 /// storage) so keys persist across sessions and are accessed safely.
-#[allow(deprecated)] // set_var deprecated in Rust 2024 edition
 pub fn store_api_key(provider: &str, key: &str) {
-    // SAFETY: Only safe when called from a single-threaded context (e.g. app
-    // initialisation). See doc comment above.
-    std::env::set_var(format!("KON_API_KEY_{}", provider.to_uppercase()), key);
+    api_key_store()
+        .lock()
+        .unwrap()
+        .insert(provider_env_key(provider), key.to_string());
 }
 
-/// Retrieve an API key from the OS keychain.
+/// Retrieve an API key from Lumotia's process-local keystore.
 ///
-/// Stub implementation using environment variables until the `keyring` crate is
-/// added. Returns `None` if no key has been stored this session.
-///
-/// TODO: Replace with the `keyring` crate alongside `store_api_key`.
+/// Returns a previously stored in-memory key when present, otherwise falls
+/// back to the read-only `LUMOTIA_API_KEY_<PROVIDER>` environment variable so
+/// operator-supplied secrets still work.
 pub fn retrieve_api_key(provider: &str) -> Option<String> {
-    std::env::var(format!("KON_API_KEY_{}", provider.to_uppercase())).ok()
+    let env_key = provider_env_key(provider);
+    api_key_store()
+        .lock()
+        .unwrap()
+        .get(&env_key)
+        .cloned()
+        .or_else(|| std::env::var(env_key).ok())
+}
+
+fn api_key_store() -> &'static Mutex<HashMap<String, String>> {
+    static STORE: OnceLock<Mutex<HashMap<String, String>>> = OnceLock::new();
+    STORE.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn provider_env_key(provider: &str) -> String {
+    format!("LUMOTIA_API_KEY_{}", provider.to_uppercase())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    fn unique_provider(prefix: &str) -> String {
+        static NEXT_ID: AtomicUsize = AtomicUsize::new(1);
+        format!("{prefix}_{}", NEXT_ID.fetch_add(1, Ordering::Relaxed))
+    }
+
+    #[test]
+    fn stored_key_is_retrievable_without_env_mutation() {
+        let provider = unique_provider("provider");
+        store_api_key(&provider, "secret-token");
+        assert_eq!(
+            retrieve_api_key(&provider),
+            Some("secret-token".to_string())
+        );
+    }
+
+    #[test]
+    fn providers_do_not_overlap() {
+        let first = unique_provider("first");
+        let second = unique_provider("second");
+
+        store_api_key(&first, "alpha");
+        store_api_key(&second, "beta");
+
+        assert_eq!(retrieve_api_key(&first), Some("alpha".to_string()));
+        assert_eq!(retrieve_api_key(&second), Some("beta".to_string()));
+    }
 }

crates/cloud-providers/src/lib.rs

@@ -1,3 +1,8 @@
 pub mod keystore;
+pub mod provider;
 
 pub use keystore::{retrieve_api_key, store_api_key};
+pub use provider::{
+    CostClass, EngineProfile, NetworkRequirement, ProviderCapabilities, ProviderId, ProviderKind,
+    ProviderTranscript, TranscriptionProvider,
+};

crates/cloud-providers/src/provider.rs

@@ -0,0 +1,184 @@
+//! `TranscriptionProvider` is the async-native trait every transcription
+//! backend implements, regardless of whether the work happens locally
+//! (Whisper, Parakeet, Moonshine via the `LocalProviderAdapter` in
+//! `lumotia-transcription`) or remotely (OpenAI Whisper, Groq,
+//! Deepgram, etc.).
+//!
+//! Living in `lumotia-cloud-providers` is deliberate: the AGPL OEM
+//! exception (≥£2k/yr) requires a clean trait surface that an OEM
+//! licensee can implement without depending on Lumotia's transcription
+//! internals. The trait crate stays small; provider implementations
+//! sit alongside.
+//!
+//! Object-safety discipline: no generic methods, no `Self`-returning
+//! methods. The compile-time witness in `tests` enforces this.
+
+use std::fmt;
+
+use async_trait::async_trait;
+use lumotia_core::error::Result;
+use lumotia_core::types::{AudioSamples, ModelId, Transcript, TranscriptionOptions};
+use serde::{Deserialize, Serialize};
+
+/// Stable, lower-kebab-case identifier for a provider. Used in user
+/// profiles, settings storage, and logs. Examples: `local-whisper`,
+/// `local-parakeet`, `openai-whisper`, `groq-whisper-v3`.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct ProviderId(String);
+
+impl ProviderId {
+    pub fn new(id: impl Into<String>) -> Self {
+        Self(id.into())
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for ProviderId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+/// Whether a provider runs locally or over the network. The orchestrator
+/// inspects this to decide whether to honour an offline-only profile.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ProviderKind {
+    Local,
+    Cloud(NetworkRequirement),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum NetworkRequirement {
+    /// Provider requires a live network connection on every call.
+    Online,
+    /// Provider can fall back to a cached or queued path when offline.
+    OnlineWithFallback,
+}
+
+/// Indicative cost class for UI surfacing. Not a billing source of truth.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum CostClass {
+    /// No marginal cost beyond the user's local hardware.
+    Free,
+    /// Per-call cost; user supplies their own API key (BYOK).
+    PaidByok,
+    /// Per-call cost; provider billed by CORBEL on the user's behalf.
+    PaidManaged,
+}
+
+/// Capabilities a provider advertises to the orchestrator and the UI.
+/// Superset of `lumotia_transcription::TranscriberCapabilities` for
+/// local providers, with extra fields cloud providers populate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ProviderCapabilities {
+    pub sample_rate: u32,
+    pub channels: u16,
+    pub initial_prompt_supported: bool,
+    pub language_hint_supported: bool,
+    pub streaming_supported: bool,
+    pub cost_class: CostClass,
+}
+
+/// User-selectable engine configuration. The orchestrator resolves
+/// `engine_id` against the `EngineRegistry`, then derives
+/// `TranscriptionOptions` from the remaining fields.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EngineProfile {
+    pub engine_id: ProviderId,
+    pub model_id: Option<ModelId>,
+    pub language: Option<String>,
+    pub initial_prompt: Option<String>,
+}
+
+impl EngineProfile {
+    pub fn new(engine_id: ProviderId) -> Self {
+        Self {
+            engine_id,
+            model_id: None,
+            language: None,
+            initial_prompt: None,
+        }
+    }
+
+    pub fn to_options(&self) -> TranscriptionOptions {
+        TranscriptionOptions {
+            language: self.language.clone(),
+            initial_prompt: self.initial_prompt.clone(),
+        }
+    }
+}
+
+/// Result returned by `TranscriptionProvider::transcribe`. Carries the
+/// transcript plus inference timing so the orchestrator can surface
+/// latency without losing it across the trait boundary.
+#[derive(Debug, Clone)]
+pub struct ProviderTranscript {
+    pub transcript: Transcript,
+    pub inference_ms: u64,
+}
+
+/// Async-native unified interface for transcription providers.
+///
+/// `Send + Sync` supertraits: providers live in an `Arc<dyn
+/// TranscriptionProvider>` shared across tokio tasks. `async_trait`
+/// macro converts the async methods into boxed futures so the trait
+/// stays object-safe.
+#[async_trait]
+pub trait TranscriptionProvider: Send + Sync {
+    fn provider_id(&self) -> ProviderId;
+
+    fn kind(&self) -> ProviderKind;
+
+    fn capabilities(&self) -> ProviderCapabilities;
+
+    /// Idempotent pre-flight. Local providers verify the model is
+    /// loaded into memory; cloud providers validate credentials and
+    /// reach the endpoint. Called before the first `transcribe` of a
+    /// session, and again after a profile or settings change that
+    /// invalidates the previous prepare.
+    async fn prepare(&self, profile: &EngineProfile) -> Result<()>;
+
+    /// Transcribe a chunk of audio. The orchestrator passes raw audio
+    /// already resampled to the provider's `capabilities().sample_rate`.
+    async fn transcribe(
+        &self,
+        audio: AudioSamples,
+        options: TranscriptionOptions,
+    ) -> Result<ProviderTranscript>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn provider_trait_is_object_safe() {
+        // Compile-time witness: if the trait stops being object-safe
+        // (generic method, Self-returning method, missing async_trait
+        // attribute) this declaration fails to build. No runtime work.
+        let _: Option<std::sync::Arc<dyn TranscriptionProvider>> = None;
+    }
+
+    #[test]
+    fn provider_id_round_trips_display_and_str() {
+        let id = ProviderId::new("local-whisper");
+        assert_eq!(id.as_str(), "local-whisper");
+        assert_eq!(id.to_string(), "local-whisper");
+    }
+
+    #[test]
+    fn engine_profile_derives_options() {
+        let profile = EngineProfile {
+            engine_id: ProviderId::new("local-whisper"),
+            model_id: None,
+            language: Some("en".to_string()),
+            initial_prompt: Some("Lumotia".to_string()),
+        };
+        let opts = profile.to_options();
+        assert_eq!(opts.language, Some("en".to_string()));
+        assert_eq!(opts.initial_prompt, Some("Lumotia".to_string()));
+    }
+}

crates/core/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
-name = "kon-core"
+name = "lumotia-core"
 version = "0.1.0"
 edition = "2021"
-description = "Core types, constants, traits, hardware detection, and model registry for Kon"
+description = "Core types, constants, traits, hardware detection, and model registry for Lumotia"
 
 [dependencies]
 serde = { version = "1", features = ["derive"] }
@@ -10,3 +10,10 @@ serde_json = "1"
 thiserror = "2"
 sysinfo = "0.35"
 async-trait = "0.1"
+num_cpus = "1"
+tracing = "0.1"
+libloading = "0.8"
+
+[dev-dependencies]
+tempfile = "3"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }

crates/core/examples/tuning_log_demo.rs

@@ -0,0 +1,50 @@
+//! Demonstrator: show what the inference_thread_count tracing event
+//! emits in production, across all eight (workload, on_battery,
+//! gpu_offloaded) tuples.
+//!
+//! Run with:
+//!   cargo run -p lumotia-core --example tuning_log_demo
+//!
+//! Output is to stderr (tracing's default). Each unique tuple emits
+//! exactly one INFO line; subsequent calls with the same tuple are
+//! silenced by the per-process log-once cache.
+
+use lumotia_core::tuning::{inference_thread_count, Workload};
+
+fn main() {
+    tracing_subscriber::fmt()
+        .with_env_filter("lumotia_core=info")
+        .with_target(true)
+        .with_writer(std::io::stderr)
+        .init();
+
+    let cores = num_cpus::get_physical();
+    let logical = num_cpus::get();
+    eprintln!("Host: {cores} physical / {logical} logical cores\n");
+
+    for (label, override_value) in [
+        ("AC override", Some("ac")),
+        ("Battery override", Some("battery")),
+        ("No override (real sysfs probe)", None),
+    ] {
+        match override_value {
+            Some(v) => std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", v),
+            None => std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE"),
+        }
+        // Cache invalidation so the live probe re-runs each section.
+        // Override paths bypass the cache anyway; this is for the
+        // no-override block that actually hits sysfs.
+        eprintln!("--- {label} ---");
+        for &(workload, gpu) in &[
+            (Workload::Llm, false),
+            (Workload::Llm, true),
+            (Workload::Whisper, false),
+            (Workload::Whisper, true),
+        ] {
+            let n = inference_thread_count(workload, gpu);
+            let w = format!("{workload:?}");
+            eprintln!("  {w:>8} gpu_offloaded={gpu:>5} -> {n} threads");
+        }
+        eprintln!();
+    }
+}

crates/core/src/constants.rs

@@ -18,9 +18,6 @@ pub const MIN_CHUNK_SAMPLES: usize = 8000;
 /// Post-processing thresholds.
 pub const SMART_PARAGRAPH_GAP_SECS: f64 = 2.0;
 
-/// Thread count for inference. Leaves headroom for the UI thread.
-pub const MIN_INFERENCE_THREADS: usize = 4;
-
 /// History limits.
 pub const HISTORY_MAX_ENTRIES: usize = 100;
 
@@ -39,11 +36,3 @@ pub const VAD_SPEECH_PAD_MS: u32 = 100;
 
 /// Model download chunk size for progress reporting.
 pub const DOWNLOAD_CHUNK_BYTES: usize = 65_536;
-
-/// Inference thread count based on available parallelism.
-pub fn inference_thread_count() -> usize {
-    std::thread::available_parallelism()
-        .map(|p| p.get().saturating_sub(1))
-        .unwrap_or(MIN_INFERENCE_THREADS)
-        .max(MIN_INFERENCE_THREADS)
-}

crates/core/src/error.rs

@@ -4,12 +4,12 @@ use serde::Serialize;
 
 use crate::types::ModelId;
 
-/// Structured error type for Kon.
+/// Structured error type for Lumotia.
 ///
 /// Implements `Serialize` so errors can be sent to the frontend as
 /// structured JSON rather than opaque strings.
 #[derive(Debug, thiserror::Error, Serialize)]
-pub enum KonError {
+pub enum Error {
     #[error("model not found: {0}")]
     ModelNotFound(ModelId),
 
@@ -31,30 +31,53 @@ pub enum KonError {
     #[error("model download failed: {0}")]
     DownloadFailed(String),
 
-    #[error("file not found: {}", .0.display())]
+    #[error("file not found: '{}'", .0.display())]
     FileNotFound(PathBuf),
 
-    #[error("storage error: {0}")]
-    StorageError(String),
+    /// Structured storage failure flowed up from `lumotia_storage::Error` via
+    /// its `From` impl. Display reads through to `detail` so the operation +
+    /// source context produced by the storage crate isn't double-prefixed.
+    #[error("{detail}")]
+    Storage {
+        kind: StorageKind,
+        operation: String,
+        detail: String,
+    },
 
-    #[error("io error: {0}")]
-    Io(
-        #[from]
-        #[serde(serialize_with = "serialize_io_error")]
-        std::io::Error,
-    ),
+    #[error("provider not registered: {0}")]
+    ProviderNotRegistered(String),
 
-    #[error("{0}")]
-    Other(String),
+    #[error("io error ({kind}): {message}")]
+    Io {
+        kind: String,
+        message: String,
+        raw_os_error: Option<i32>,
+    },
 }
 
-/// Serialises `std::io::Error` as its display string, since it does
-/// not implement `Serialize` natively.
-fn serialize_io_error<S: serde::Serializer>(
-    err: &std::io::Error,
-    s: S,
-) -> std::result::Result<S::Ok, S::Error> {
-    s.serialize_str(&err.to_string())
+/// Coarse discriminator for `Error::Storage`. The storage crate maps
+/// its full typed error onto one of these kinds at the boundary. Backend code
+/// that wants finer-grained branching pattern-matches on
+/// `lumotia_storage::Error` directly.
+#[derive(Debug, Clone, Copy, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StorageKind {
+    DatabaseOpen,
+    Migration,
+    Query,
+    NotFound,
+    InvalidReference,
+    Filesystem,
 }
 
-pub type Result<T> = std::result::Result<T, KonError>;
+impl From<std::io::Error> for Error {
+    fn from(err: std::io::Error) -> Self {
+        Self::Io {
+            kind: format!("{:?}", err.kind()),
+            message: err.to_string(),
+            raw_os_error: err.raw_os_error(),
+        }
+    }
+}
+
+pub type Result<T> = std::result::Result<T, Error>;

crates/core/src/hardware.rs

@@ -19,7 +19,7 @@ pub struct CpuInfo {
 }
 
 /// Runtime-detected CPU feature flags relevant to the speech-to-text
-/// and LLM backends Kon ships. All whisper.cpp / llama.cpp / ggml
+/// and LLM backends Lumotia ships. All whisper.cpp / llama.cpp / ggml
 /// kernels degrade roughly two tiers without AVX2, which is why we
 /// surface it separately: when AVX2 is absent, the UI should warn the
 /// user that performance will be a fraction of what they would see
@@ -169,6 +169,40 @@ pub fn probe_system() -> SystemProfile {
     }
 }
 
+/// Best-effort probe for the Vulkan loader shared library.
+///
+/// whisper.cpp and llama.cpp Vulkan backends silently drop to CPU if
+/// `libvulkan.so.1` (Linux) / `vulkan-1.dll` (Windows) / the MoltenVK
+/// bundle (macOS) is missing at runtime. We probe via
+/// `libloading::Library::new`; a successful open means the loader is
+/// resolvable and we should treat the GPU path as live.
+///
+/// Moved from `src-tauri/src/commands/models.rs` so non-Tauri crates
+/// (transcription, llm) can call it without depending on the Tauri
+/// binary.
+pub fn vulkan_loader_available() -> bool {
+    #[cfg(target_os = "linux")]
+    let candidates: &[&str] = &["libvulkan.so.1", "libvulkan.so"];
+    #[cfg(target_os = "windows")]
+    let candidates: &[&str] = &["vulkan-1.dll"];
+    #[cfg(target_os = "macos")]
+    let candidates: &[&str] = &["libvulkan.1.dylib", "libMoltenVK.dylib"];
+    #[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
+    let candidates: &[&str] = &[];
+
+    for name in candidates {
+        // SAFETY: libloading::Library::new loads a shared library and
+        // returns a handle that is dropped at the end of this
+        // iteration. We do not call any symbols, so the open-for-probe
+        // pattern is sound.
+        match unsafe { libloading::Library::new(*name) } {
+            Ok(_lib) => return true,
+            Err(_) => continue,
+        }
+    }
+    false
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -217,4 +251,11 @@ mod tests {
         #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
         assert!(!features.has_ggml_baseline());
     }
+
+    #[test]
+    fn vulkan_loader_available_does_not_panic() {
+        // We can't assert the value (depends on host's libvulkan),
+        // but we can assert the call completes.
+        let _ = vulkan_loader_available();
+    }
 }

crates/core/src/lib.rs

@@ -2,11 +2,14 @@ pub mod constants;
 pub mod error;
 pub mod hardware;
 pub mod model_registry;
+pub mod paths;
+pub mod power;
 pub mod process_watch;
 pub mod recommendation;
+pub mod tuning;
 pub mod types;
 
-pub use error::{KonError, Result};
+pub use error::{Error, Result};
 pub use types::{
     AudioSamples, DownloadProgress, EngineName, Megabytes, ModelId, Segment, Transcript,
     TranscriptionOptions,

crates/core/src/model_registry.rs

@@ -40,8 +40,8 @@ pub struct ModelFile {
     pub filename: &'static str,
     pub url: &'static str,
     pub size: Megabytes,
-    /// SHA256 hex digest for integrity verification. None to skip check.
-    pub sha256: Option<&'static str>,
+    /// SHA256 hex digest for integrity verification.
+    pub sha256: &'static str,
 }
 
 /// All metadata for a single downloadable model.
@@ -74,27 +74,27 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             files: vec![
                 ModelFile {
                     filename: "encoder-model.int8.onnx",
-                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/main/encoder-model.int8.onnx",
+                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/0bbb45a3365852604aef28b538a8f066f4ccaa85/encoder-model.int8.onnx",
                     size: Megabytes(620),
-                    sha256: None,
+                    sha256: "3e0581fda6ab843888b51e56d7ee78b6d5bc3237ec113af1f732d1d5286aa155",
                 },
                 ModelFile {
                     filename: "decoder_joint-model.int8.onnx",
-                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/main/decoder_joint-model.int8.onnx",
+                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/0bbb45a3365852604aef28b538a8f066f4ccaa85/decoder_joint-model.int8.onnx",
                     size: Megabytes(3),
-                    sha256: None,
+                    sha256: "a449f49acd68979d418651dd2dcb737cc0f1bf0225e009e29ee326354edbf7d3",
                 },
                 ModelFile {
                     filename: "nemo128.onnx",
-                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/main/nemo128.onnx",
+                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/0bbb45a3365852604aef28b538a8f066f4ccaa85/nemo128.onnx",
                     size: Megabytes(1),
-                    sha256: None,
+                    sha256: "a9fde1486ebfcc08f328d75ad4610c67835fea58c73ba57e3209a6f6cf019e9f",
                 },
                 ModelFile {
                     filename: "vocab.txt",
-                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/main/vocab.txt",
+                    url: "https://huggingface.co/istupakov/parakeet-tdt-0.6b-v2-onnx/resolve/0bbb45a3365852604aef28b538a8f066f4ccaa85/vocab.txt",
                     size: Megabytes(1),
-                    sha256: None,
+                    sha256: "ec182b70dd42113aff6c5372c75cac58c952443eb22322f57bbd7f53977d497d",
                 },
             ],
             description: "Fastest local model — near-instant transcription",
@@ -110,9 +110,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-tiny.en.bin",
-                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin",
+                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-tiny.en.bin",
                 size: Megabytes(75),
-                sha256: None,
+                sha256: "921e4cf8686fdd993dcd081a5da5b6c365bfde1162e72b08d75ac75289920b1f",
             }],
             description: "Bundled with app — works instantly",
         },
@@ -127,9 +127,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-base.en.bin",
-                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin",
+                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-base.en.bin",
                 size: Megabytes(142),
-                sha256: None,
+                sha256: "a03779c86df3323075f5e796cb2ce5029f00ec8869eee3fdfb897afe36c6d002",
             }],
             description: "Good balance of speed and accuracy",
         },
@@ -144,9 +144,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-small.en.bin",
-                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin",
+                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-small.en.bin",
                 size: Megabytes(466),
-                sha256: None,
+                sha256: "c6138d6d58ecc8322097e0f987c32f1be8bb0a18532a3f88f734d1bbf9c41e5d",
             }],
             description: "Accuracy-first English transcription",
         },
@@ -161,9 +161,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-distil-small.en.bin",
-                url: "https://huggingface.co/distil-whisper/distil-small.en/resolve/main/ggml-distil-small.en.bin",
+                url: "https://huggingface.co/distil-whisper/distil-small.en/resolve/9e4a67ca4569c30be43a3fe7fba1621e504f0093/ggml-distil-small.en.bin",
                 size: Megabytes(336),
-                sha256: None,
+                sha256: "7691eb11167ab7aaf6b3e05d8266f2fd9ad89c550e433f86ac266ebdee6c970a",
             }],
             description: "Small accuracy, ~6\u{00d7} faster — distilled variant",
         },
@@ -178,9 +178,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-medium.en.bin",
-                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.en.bin",
+                url: "https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-medium.en.bin",
                 size: Megabytes(1500),
-                sha256: None,
+                sha256: "cc37e93478338ec7700281a7ac30a10128929eb8f427dda2e865faa8f6da4356",
             }],
             description: "Best Whisper accuracy — needs 4+ GB RAM",
         },
@@ -195,9 +195,9 @@ static ALL_MODELS: LazyLock<Vec<ModelEntry>> = LazyLock::new(|| {
             languages: LanguageSupport::EnglishOnly,
             files: vec![ModelFile {
                 filename: "ggml-distil-large-v3.bin",
-                url: "https://huggingface.co/distil-whisper/distil-large-v3-ggml/resolve/main/ggml-distil-large-v3.bin",
+                url: "https://huggingface.co/distil-whisper/distil-large-v3-ggml/resolve/0d78dd96ed9fc152325f63b53788fec3b43de031/ggml-distil-large-v3.bin",
                 size: Megabytes(1550),
-                sha256: None,
+                sha256: "2883a11b90fb10ed592d826edeaee7d2929bf1ab985109fe9e1e7b4d2b69a298",
             }],
             description: "Near large-v3 accuracy at ~6\u{00d7} the speed",
         },
@@ -213,3 +213,35 @@ pub fn all_models() -> &'static [ModelEntry] {
 pub fn find_model(id: &ModelId) -> Option<&'static ModelEntry> {
     ALL_MODELS.iter().find(|m| &m.id == id)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::all_models;
+
+    #[test]
+    fn every_model_file_has_sha256_and_pinned_url() {
+        for model in all_models() {
+            for file in &model.files {
+                assert_eq!(
+                    file.sha256.len(),
+                    64,
+                    "{} / {} must carry a SHA256 digest",
+                    model.id,
+                    file.filename
+                );
+                assert!(
+                    file.sha256.chars().all(|c| c.is_ascii_hexdigit()),
+                    "{} / {} SHA256 must be hex",
+                    model.id,
+                    file.filename
+                );
+                assert!(
+                    !file.url.contains("/resolve/main/"),
+                    "{} / {} must pin a Hugging Face revision",
+                    model.id,
+                    file.filename
+                );
+            }
+        }
+    }
+}

crates/core/src/paths.rs

@@ -0,0 +1,558 @@
+use std::path::{Path, PathBuf};
+
+use crate::types::ModelId;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppPaths {
+    app_data_dir: PathBuf,
+}
+
+impl AppPaths {
+    pub fn current() -> Self {
+        Self {
+            app_data_dir: resolve_app_data_dir(),
+        }
+    }
+
+    pub fn app_data_dir(&self) -> PathBuf {
+        self.app_data_dir.clone()
+    }
+
+    pub fn database_path(&self) -> PathBuf {
+        self.app_data_dir.join("lumotia.db")
+    }
+
+    pub fn recordings_dir(&self) -> PathBuf {
+        self.app_data_dir.join("recordings")
+    }
+
+    pub fn crashes_dir(&self) -> PathBuf {
+        self.app_data_dir.join("crashes")
+    }
+
+    pub fn logs_dir(&self) -> PathBuf {
+        self.app_data_dir.join("logs")
+    }
+
+    pub fn diagnostic_reports_dir(&self) -> PathBuf {
+        self.app_data_dir.join("diagnostic-reports")
+    }
+
+    pub fn models_dir(&self) -> PathBuf {
+        self.app_data_dir.join("models")
+    }
+
+    pub fn speech_model_dir(&self, id: &ModelId) -> PathBuf {
+        self.models_dir().join(id.as_str())
+    }
+
+    pub fn llm_models_dir(&self) -> PathBuf {
+        self.models_dir().join("llm")
+    }
+
+    pub fn migration_sentinel(&self, name: &str) -> PathBuf {
+        self.app_data_dir.join(format!(".{name}.sentinel"))
+    }
+}
+
+pub fn app_paths() -> AppPaths {
+    AppPaths::current()
+}
+
+pub fn app_data_dir() -> PathBuf {
+    app_paths().app_data_dir()
+}
+
+fn resolve_app_data_dir() -> PathBuf {
+    #[cfg(target_os = "windows")]
+    {
+        let local_app_data = std::env::var("LOCALAPPDATA").unwrap_or_else(|_| ".".to_string());
+        return PathBuf::from(local_app_data).join("lumotia");
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        return PathBuf::from(home)
+            .join("Library")
+            .join("Application Support")
+            .join("Lumotia");
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        let legacy_dot = PathBuf::from(&home).join(".lumotia");
+        if legacy_dot.exists() {
+            return legacy_dot;
+        }
+        if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
+            if !xdg.is_empty() {
+                return PathBuf::from(xdg).join("lumotia");
+            }
+        }
+        PathBuf::from(home)
+            .join(".local")
+            .join("share")
+            .join("lumotia")
+    }
+
+    #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
+    {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
+        PathBuf::from(home).join(".lumotia")
+    }
+}
+
+/// Outcome of attempting to migrate an existing magnotia-era data directory
+/// to its lumotia equivalent on first launch after the rebrand.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum MigrationStatus {
+    /// Renamed legacy dir to the new path. Includes optional db-file rename
+    /// if `magnotia.db` was found inside.
+    Migrated {
+        from: PathBuf,
+        to: PathBuf,
+        renamed_db: bool,
+    },
+    /// New path already exists. Did not touch legacy (if any) to avoid
+    /// destroying user data on the new path.
+    TargetAlreadyExists { target: PathBuf },
+    /// No legacy data dir on disk. Nothing to do.
+    NoLegacyFound,
+}
+
+/// Probe the legacy magnotia data dir paths on the current platform.
+/// Returns the matched legacy path AND its convention-preserving lumotia
+/// target so the migration lands the same kind of dir it found (dot-home
+/// stays dot-home, XDG stays XDG, macOS Application Support stays the
+/// same).
+fn legacy_and_target_paths() -> Option<(PathBuf, PathBuf)> {
+    #[cfg(target_os = "windows")]
+    {
+        let local_app_data = std::env::var("LOCALAPPDATA").ok()?;
+        let legacy = PathBuf::from(&local_app_data).join("magnotia");
+        let target = PathBuf::from(local_app_data).join("lumotia");
+        return legacy.exists().then_some((legacy, target));
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        let home = std::env::var("HOME").ok()?;
+        let app_support = PathBuf::from(home).join("Library").join("Application Support");
+        let legacy = app_support.join("Magnotia");
+        let target = app_support.join("Lumotia");
+        return legacy.exists().then_some((legacy, target));
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        let home = std::env::var("HOME").ok()?;
+        let dot_legacy = PathBuf::from(&home).join(".magnotia");
+        if dot_legacy.exists() {
+            return Some((dot_legacy, PathBuf::from(&home).join(".lumotia")));
+        }
+        if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
+            if !xdg.is_empty() {
+                let xdg_legacy = PathBuf::from(&xdg).join("magnotia");
+                if xdg_legacy.exists() {
+                    return Some((xdg_legacy, PathBuf::from(xdg).join("lumotia")));
+                }
+            }
+        }
+        let xdg_default_legacy = PathBuf::from(&home)
+            .join(".local")
+            .join("share")
+            .join("magnotia");
+        if xdg_default_legacy.exists() {
+            let xdg_default_target = PathBuf::from(home)
+                .join(".local")
+                .join("share")
+                .join("lumotia");
+            return Some((xdg_default_legacy, xdg_default_target));
+        }
+        None
+    }
+
+    #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
+    {
+        let home = std::env::var("HOME").ok()?;
+        let legacy = PathBuf::from(&home).join(".magnotia");
+        let target = PathBuf::from(home).join(".lumotia");
+        legacy.exists().then_some((legacy, target))
+    }
+}
+
+/// Migrate a legacy magnotia data directory to its convention-preserving
+/// lumotia equivalent on first launch. Idempotent: safe to call on every
+/// boot.
+///
+/// Rules:
+/// * If the resolved target already exists, do nothing and return
+///   `TargetAlreadyExists`. We do not destroy lumotia data, even if a
+///   stale legacy dir is also present.
+/// * If only the legacy path exists, rename it to the matching lumotia
+///   target (same parent dir / same convention) and rename
+///   `magnotia.db` -> `lumotia.db` inside it if found.
+/// * If neither exists, return `NoLegacyFound` — the first launch on a
+///   clean system will create the new path itself.
+///
+/// Callers should treat `Err` as a hard startup failure; silently
+/// continuing past a migration error orphans user data behind a fresh
+/// empty lumotia dir.
+pub fn migrate_legacy_data_dir() -> Result<MigrationStatus, std::io::Error> {
+    migrate_legacy_data_dir_inner(legacy_and_target_paths())
+}
+
+/// Test-friendly inner shape: takes the (legacy, target) pair explicitly
+/// so tests don't depend on platform-specific HOME / LOCALAPPDATA / XDG
+/// env vars.
+fn migrate_legacy_data_dir_inner(
+    pair: Option<(PathBuf, PathBuf)>,
+) -> Result<MigrationStatus, std::io::Error> {
+    let Some((from, to)) = pair else {
+        return Ok(MigrationStatus::NoLegacyFound);
+    };
+
+    if to.exists() {
+        return Ok(MigrationStatus::TargetAlreadyExists { target: to });
+    }
+
+    if let Some(parent) = to.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    rename_or_copy_tree(&from, &to)?;
+
+    let renamed_db = rename_db_file_if_present(&to)?;
+
+    Ok(MigrationStatus::Migrated {
+        from,
+        to,
+        renamed_db,
+    })
+}
+
+/// Move a directory tree, falling back to copy + remove if the
+/// destination is on a different filesystem (EXDEV / CrossesDevices).
+///
+/// Real-world cases this defends against:
+/// * `~/.magnotia` on the user's home partition, `~/.local/share/lumotia`
+///   on a bind-mounted partition.
+/// * Encrypted-home (`/home/.ecryptfs/`) vs decrypted view.
+/// * `$XDG_DATA_HOME` set to a non-home device.
+///
+/// On a copy-then-remove fallback we tolerate partial cleanup failure
+/// (the source dir not fully deleted) by surfacing the error from the
+/// remove step only if the copy succeeded — losing data via a half-rolled
+/// migration is worse than leaving a stale legacy dir behind.
+fn rename_or_copy_tree(from: &Path, to: &Path) -> Result<(), std::io::Error> {
+    match std::fs::rename(from, to) {
+        Ok(()) => Ok(()),
+        Err(e) if is_cross_device(&e) => {
+            copy_dir_recursive(from, to)?;
+            // Only attempt removal after the copy fully succeeded.
+            // remove_dir_all is best-effort: if it leaves files behind
+            // (permission edge cases), the user can clean up the stale
+            // legacy dir manually.
+            std::fs::remove_dir_all(from)?;
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}
+
+fn is_cross_device(err: &std::io::Error) -> bool {
+    // ErrorKind::CrossesDevices is stable from Rust 1.85. Fall back to
+    // the raw OS error code (EXDEV = 18 on Linux, 17 on macOS, 17 on
+    // BSDs) for older toolchains.
+    if err.kind() == std::io::ErrorKind::CrossesDevices {
+        return true;
+    }
+    #[cfg(unix)]
+    {
+        return matches!(err.raw_os_error(), Some(18));
+    }
+    #[allow(unreachable_code)]
+    false
+}
+
+fn copy_dir_recursive(from: &Path, to: &Path) -> Result<(), std::io::Error> {
+    std::fs::create_dir_all(to)?;
+    for entry in std::fs::read_dir(from)? {
+        let entry = entry?;
+        let entry_path = entry.path();
+        let target_path = to.join(entry.file_name());
+        let metadata = entry.metadata()?;
+        if metadata.is_dir() {
+            copy_dir_recursive(&entry_path, &target_path)?;
+        } else if metadata.file_type().is_symlink() {
+            // Recreate symlink rather than dereferencing — the
+            // transcription app stores recording paths verbatim so a
+            // dereferenced symlink could orphan large audio blobs.
+            #[cfg(unix)]
+            {
+                let target = std::fs::read_link(&entry_path)?;
+                std::os::unix::fs::symlink(target, &target_path)?;
+            }
+            #[cfg(windows)]
+            {
+                let target = std::fs::read_link(&entry_path)?;
+                if metadata.is_dir() {
+                    std::os::windows::fs::symlink_dir(target, &target_path)?;
+                } else {
+                    std::os::windows::fs::symlink_file(target, &target_path)?;
+                }
+            }
+        } else {
+            std::fs::copy(&entry_path, &target_path)?;
+        }
+    }
+    Ok(())
+}
+
+fn rename_db_file_if_present(dir: &Path) -> Result<bool, std::io::Error> {
+    let legacy_db = dir.join("magnotia.db");
+    if !legacy_db.exists() {
+        return Ok(false);
+    }
+    let new_db = dir.join("lumotia.db");
+    rename_or_copy_file(&legacy_db, &new_db)?;
+    Ok(true)
+}
+
+fn rename_or_copy_file(from: &Path, to: &Path) -> Result<(), std::io::Error> {
+    match std::fs::rename(from, to) {
+        Ok(()) => Ok(()),
+        Err(e) if is_cross_device(&e) => {
+            std::fs::copy(from, to)?;
+            std::fs::remove_file(from)?;
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::ModelId;
+
+    #[test]
+    fn derives_all_paths_from_one_base() {
+        let paths = AppPaths {
+            app_data_dir: PathBuf::from("/tmp/lumotia-test"),
+        };
+        assert_eq!(
+            paths.database_path(),
+            PathBuf::from("/tmp/lumotia-test/lumotia.db")
+        );
+        assert_eq!(
+            paths.speech_model_dir(&ModelId::new("whisper-base-en")),
+            PathBuf::from("/tmp/lumotia-test/models/whisper-base-en")
+        );
+        assert_eq!(
+            paths.llm_models_dir(),
+            PathBuf::from("/tmp/lumotia-test/models/llm")
+        );
+    }
+
+    fn unique_tmp(base: &str) -> PathBuf {
+        let pid = std::process::id();
+        let nanos = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        std::env::temp_dir().join(format!("lumotia-paths-test-{base}-{pid}-{nanos}"))
+    }
+
+    #[test]
+    fn migrate_with_legacy_present_renames_dir_and_db() {
+        let root = unique_tmp("legacy-present");
+        let legacy = root.join("magnotia");
+        let target = root.join("lumotia");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::write(legacy.join("magnotia.db"), b"sqlite-stub").unwrap();
+        std::fs::write(legacy.join("recordings.placeholder"), b"x").unwrap();
+
+        let result = migrate_legacy_data_dir_inner(Some((legacy.clone(), target.clone())))
+            .expect("migrate ok");
+
+        match result {
+            MigrationStatus::Migrated {
+                from,
+                to,
+                renamed_db,
+            } => {
+                assert_eq!(from, legacy);
+                assert_eq!(to, target);
+                assert!(renamed_db, "expected db file to be renamed");
+            }
+            other => panic!("expected Migrated, got {other:?}"),
+        }
+        assert!(!legacy.exists(), "legacy dir should be gone");
+        assert!(target.exists(), "new dir should exist");
+        assert!(target.join("lumotia.db").exists(), "db at new name");
+        assert!(!target.join("magnotia.db").exists(), "old db gone");
+        assert!(
+            target.join("recordings.placeholder").exists(),
+            "other files preserved"
+        );
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn migrate_with_both_present_returns_target_exists_and_preserves_lumotia() {
+        let root = unique_tmp("both-present");
+        let legacy = root.join("magnotia");
+        let target = root.join("lumotia");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::create_dir_all(&target).unwrap();
+        std::fs::write(target.join("lumotia.db"), b"new-data").unwrap();
+        std::fs::write(legacy.join("magnotia.db"), b"legacy-data").unwrap();
+
+        let result = migrate_legacy_data_dir_inner(Some((legacy.clone(), target.clone())))
+            .expect("migrate ok");
+
+        assert_eq!(
+            result,
+            MigrationStatus::TargetAlreadyExists {
+                target: target.clone()
+            }
+        );
+        assert!(legacy.exists(), "legacy dir preserved");
+        assert!(target.exists(), "new dir preserved");
+        assert_eq!(
+            std::fs::read(target.join("lumotia.db")).unwrap(),
+            b"new-data".to_vec(),
+            "lumotia.db not overwritten"
+        );
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn migrate_with_neither_present_returns_no_legacy() {
+        let result = migrate_legacy_data_dir_inner(None).expect("migrate ok");
+
+        assert_eq!(result, MigrationStatus::NoLegacyFound);
+    }
+
+    #[test]
+    fn migrate_with_legacy_present_but_no_db_inside() {
+        let root = unique_tmp("legacy-no-db");
+        let legacy = root.join("magnotia");
+        let target = root.join("lumotia");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::write(legacy.join("recordings.placeholder"), b"x").unwrap();
+
+        let result = migrate_legacy_data_dir_inner(Some((legacy.clone(), target.clone())))
+            .expect("migrate ok");
+
+        match result {
+            MigrationStatus::Migrated { renamed_db, .. } => {
+                assert!(!renamed_db, "no db to rename");
+            }
+            other => panic!("expected Migrated, got {other:?}"),
+        }
+        assert!(target.exists());
+        assert!(target.join("recordings.placeholder").exists());
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn migrate_preserves_dot_home_to_dot_home_convention() {
+        // Regression for B2 from Phase 5 QC: dot-home legacy must land in
+        // dot-home target, not XDG target.
+        let root = unique_tmp("convention");
+        let legacy = root.join(".magnotia");
+        let target = root.join(".lumotia");
+        std::fs::create_dir_all(&legacy).unwrap();
+        std::fs::write(legacy.join("magnotia.db"), b"data").unwrap();
+
+        let result = migrate_legacy_data_dir_inner(Some((legacy.clone(), target.clone())))
+            .expect("migrate ok");
+
+        assert!(matches!(result, MigrationStatus::Migrated { .. }));
+        assert!(target.exists());
+        assert!(target.join("lumotia.db").exists());
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn copy_dir_recursive_preserves_nested_files_and_directories() {
+        // Regression for Codex Blocker 11: EXDEV fallback path uses
+        // copy_dir_recursive. Verify it preserves directory structure,
+        // file contents, and arbitrary depth.
+        let root = unique_tmp("copy-recursive");
+        let src = root.join("legacy");
+        let dst = root.join("new");
+        std::fs::create_dir_all(src.join("recordings/2026-05")).unwrap();
+        std::fs::create_dir_all(src.join("models/whisper-base-en")).unwrap();
+        std::fs::write(src.join("magnotia.db"), b"sqlite-bytes").unwrap();
+        std::fs::write(
+            src.join("recordings/2026-05/clip-001.wav"),
+            b"wav-bytes",
+        )
+        .unwrap();
+        std::fs::write(src.join("models/whisper-base-en/manifest.json"), b"{}").unwrap();
+
+        copy_dir_recursive(&src, &dst).expect("copy ok");
+
+        assert_eq!(std::fs::read(dst.join("magnotia.db")).unwrap(), b"sqlite-bytes");
+        assert_eq!(
+            std::fs::read(dst.join("recordings/2026-05/clip-001.wav")).unwrap(),
+            b"wav-bytes"
+        );
+        assert!(dst.join("models/whisper-base-en/manifest.json").exists());
+        // Source still present — copy_dir_recursive does not delete.
+        assert!(src.exists());
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn rename_or_copy_tree_succeeds_on_same_filesystem() {
+        // Smoke for the happy path: same-filesystem case uses rename
+        // and leaves no source behind.
+        let root = unique_tmp("rename-tree");
+        let src = root.join("legacy");
+        let dst = root.join("new");
+        std::fs::create_dir_all(&src).unwrap();
+        std::fs::write(src.join("magnotia.db"), b"data").unwrap();
+
+        rename_or_copy_tree(&src, &dst).expect("rename ok");
+
+        assert!(!src.exists(), "source removed");
+        assert!(dst.exists(), "destination present");
+        assert_eq!(std::fs::read(dst.join("magnotia.db")).unwrap(), b"data");
+
+        std::fs::remove_dir_all(&root).ok();
+    }
+
+    #[test]
+    fn is_cross_device_classifies_exdev_error_kind() {
+        // Synthesise an io::Error tagged with CrossesDevices and ensure
+        // the classifier returns true. This is the path that triggers
+        // the copy-then-delete fallback in rename_or_copy_tree on Rust
+        // 1.85+ toolchains.
+        let err = std::io::Error::new(std::io::ErrorKind::CrossesDevices, "test exdev");
+        assert!(is_cross_device(&err));
+
+        let unrelated = std::io::Error::new(std::io::ErrorKind::NotFound, "test notfound");
+        assert!(!is_cross_device(&unrelated));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn is_cross_device_classifies_raw_exdev_on_unix() {
+        // Belt-and-braces: ensure raw errno 18 (EXDEV on Linux) is
+        // classified as cross-device even if the ErrorKind doesn't
+        // map to CrossesDevices (older toolchains, future kernel
+        // surprises).
+        let err = std::io::Error::from_raw_os_error(18);
+        assert!(is_cross_device(&err));
+    }
+}

crates/core/src/power.rs

@@ -0,0 +1,337 @@
+//! Power-state probe for inference thread tuning.
+//!
+//! Reports whether the machine is running on AC or battery so callers
+//! can drop thread counts when energy matters more than throughput.
+//! Linux uses the documented sysfs ABI under
+//! `/sys/class/power_supply/`. macOS and Windows return `Unknown` for
+//! now; native probes (IOPSGetProvidingPowerSourceType,
+//! GetSystemPowerStatus) are deferred.
+
+use std::fs;
+use std::path::Path;
+use std::sync::{Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PowerState {
+    OnAc,
+    OnBattery,
+    Unknown,
+}
+
+/// Parse a `/sys/class/power_supply/`-style directory and decide
+/// whether the machine is on AC, on battery, or in an unknown state.
+///
+/// Rules (matches `Documentation/ABI/testing/sysfs-class-power`):
+/// - Any entry with `type` in {`Mains`, `USB`} and `online == 1` → OnAc.
+/// - Else any entry with `type == Battery` → OnBattery.
+/// - Else → Unknown.
+///
+/// Top-level failures (missing dir, unreadable supply_dir) return
+/// Unknown without panicking. Per-entry failures (unreadable
+/// `type`/`online` file inside an individual supply, e.g. permission
+/// denied or non-UTF-8 content) cause that entry to be silently
+/// skipped via `read_trimmed().unwrap_or_default()` — which on a
+/// stuck-AC machine could produce OnBattery if the Mains entry was
+/// the unreadable one. In practice sysfs entries are world-readable,
+/// so this is a theoretical hazard rather than a real one. `Unknown`
+/// is treated as `OnAc` by the caller, preserving today's pre-clamp
+/// behaviour on platforms or distros where the probe doesn't fire.
+pub fn parse_power_state_from_dir(supply_dir: &Path) -> PowerState {
+    let read_dir = match fs::read_dir(supply_dir) {
+        Ok(rd) => rd,
+        Err(_) => return PowerState::Unknown,
+    };
+
+    let mut saw_battery = false;
+    for entry in read_dir.flatten() {
+        let path = entry.path();
+        let ty = read_trimmed(&path.join("type")).unwrap_or_default();
+        let online = read_trimmed(&path.join("online")).unwrap_or_default();
+        match ty.as_str() {
+            "Mains" | "USB" => {
+                if online == "1" {
+                    return PowerState::OnAc;
+                }
+            }
+            "Battery" => {
+                saw_battery = true;
+            }
+            _ => {}
+        }
+    }
+
+    if saw_battery {
+        PowerState::OnBattery
+    } else {
+        PowerState::Unknown
+    }
+}
+
+fn read_trimmed(path: &Path) -> Option<String> {
+    fs::read_to_string(path).ok().map(|s| s.trim().to_owned())
+}
+
+const POWER_STATE_TTL: Duration = Duration::from_secs(10);
+
+struct CachedState {
+    state: PowerState,
+    fetched_at: Instant,
+}
+
+fn cache_slot() -> &'static Mutex<Option<CachedState>> {
+    static SLOT: OnceLock<Mutex<Option<CachedState>>> = OnceLock::new();
+    SLOT.get_or_init(|| Mutex::new(None))
+}
+
+#[cfg(test)]
+pub(crate) fn force_clear_cache() {
+    *cache_slot().lock().expect("power cache mutex poisoned") = None;
+}
+
+#[cfg(test)]
+pub(crate) fn force_set_cache(state: PowerState) {
+    *cache_slot().lock().expect("power cache mutex poisoned") = Some(CachedState {
+        state,
+        fetched_at: Instant::now(),
+    });
+}
+
+/// Top-level power-state probe.
+///
+/// Resolution order (highest to lowest priority):
+/// 1. In-process test override (set via `with_override` from unit tests).
+/// 2. `LUMOTIA_POWER_STATE_OVERRIDE` env var (`ac` | `battery` | `unknown`,
+///    case-insensitive). Used by `thread_sweep.rs` integration tests.
+/// 3. Linux: `parse_power_state_from_dir("/sys/class/power_supply")`.
+/// 4. macOS / Windows / other: `Unknown`.
+///
+/// `Unknown` is treated as `OnAc` by callers, which preserves today's
+/// pre-clamp behaviour on platforms where the probe doesn't fire.
+///
+/// Results are cached for `POWER_STATE_TTL` (10 seconds). Override
+/// paths (test and env-var) bypass the cache entirely so they always
+/// take effect immediately.
+pub fn probe_power_state() -> PowerState {
+    #[cfg(test)]
+    if let Some(state) = test_get_override() {
+        return state;
+    }
+    if let Some(state) = env_override() {
+        return state;
+    }
+
+    let mut slot = cache_slot().lock().expect("power cache mutex poisoned");
+    if let Some(cached) = &*slot {
+        if cached.fetched_at.elapsed() < POWER_STATE_TTL {
+            return cached.state;
+        }
+    }
+    let fresh = platform_probe();
+    *slot = Some(CachedState {
+        state: fresh,
+        fetched_at: Instant::now(),
+    });
+    fresh
+}
+
+fn env_override() -> Option<PowerState> {
+    let raw = std::env::var("LUMOTIA_POWER_STATE_OVERRIDE").ok()?;
+    match raw.trim().to_ascii_lowercase().as_str() {
+        "ac" => Some(PowerState::OnAc),
+        "battery" => Some(PowerState::OnBattery),
+        "unknown" => Some(PowerState::Unknown),
+        _ => None,
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn platform_probe() -> PowerState {
+    parse_power_state_from_dir(Path::new("/sys/class/power_supply"))
+}
+
+#[cfg(not(target_os = "linux"))]
+fn platform_probe() -> PowerState {
+    PowerState::Unknown
+}
+
+// In-process override slot. Tests must use `with_override` (below) to
+// set it; production code never writes to this. Read on every probe.
+#[cfg(test)]
+static TEST_OVERRIDE: Mutex<Option<PowerState>> = Mutex::new(None);
+
+#[cfg(test)]
+fn test_get_override() -> Option<PowerState> {
+    *TEST_OVERRIDE
+        .lock()
+        .expect("power test override mutex poisoned")
+}
+
+/// Drop-guard that resets `TEST_OVERRIDE` to `None` on drop (including on unwind).
+/// This prevents a panicking test body from leaking stale override state into
+/// subsequent tests.
+#[cfg(test)]
+struct OverrideGuard;
+
+#[cfg(test)]
+impl Drop for OverrideGuard {
+    fn drop(&mut self) {
+        *TEST_OVERRIDE
+            .lock()
+            .expect("power test override mutex poisoned") = None;
+    }
+}
+
+/// Run `body` with the in-process override set to `state`. Restores
+/// `TEST_OVERRIDE` to `None` on return, even if `body` panics.
+///
+/// Holds a dedicated `TEST_LOCK` mutex for the duration of the body,
+/// so override-using unit tests run serially with respect to each
+/// other even when cargo runs the test binary multi-threaded.
+#[cfg(test)]
+pub(crate) fn with_override<R>(state: Option<PowerState>, body: impl FnOnce() -> R) -> R {
+    static TEST_LOCK: Mutex<()> = Mutex::new(());
+    let _lock = TEST_LOCK.lock().expect("power TEST_LOCK poisoned");
+    *TEST_OVERRIDE
+        .lock()
+        .expect("power test override mutex poisoned") = state;
+    let _guard = OverrideGuard;
+    body()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::tempdir;
+
+    #[test]
+    fn power_state_variants_are_distinct() {
+        assert_ne!(PowerState::OnAc, PowerState::OnBattery);
+        assert_ne!(PowerState::OnAc, PowerState::Unknown);
+        assert_ne!(PowerState::OnBattery, PowerState::Unknown);
+    }
+
+    fn write_supply(dir: &std::path::Path, name: &str, ty: &str, online: &str) {
+        let entry = dir.join(name);
+        fs::create_dir_all(&entry).unwrap();
+        fs::write(entry.join("type"), format!("{ty}\n")).unwrap();
+        fs::write(entry.join("online"), format!("{online}\n")).unwrap();
+    }
+
+    #[test]
+    fn parses_mains_online_as_on_ac() {
+        let dir = tempdir().unwrap();
+        write_supply(dir.path(), "AC", "Mains", "1");
+        write_supply(dir.path(), "BAT0", "Battery", "0");
+        assert_eq!(parse_power_state_from_dir(dir.path()), PowerState::OnAc);
+    }
+
+    #[test]
+    fn parses_battery_only_as_on_battery() {
+        let dir = tempdir().unwrap();
+        write_supply(dir.path(), "AC", "Mains", "0");
+        write_supply(dir.path(), "BAT0", "Battery", "0");
+        assert_eq!(
+            parse_power_state_from_dir(dir.path()),
+            PowerState::OnBattery
+        );
+    }
+
+    #[test]
+    fn parses_usb_pd_online_as_on_ac() {
+        let dir = tempdir().unwrap();
+        write_supply(dir.path(), "ucsi-source-psy-USBC000:001", "USB", "1");
+        write_supply(dir.path(), "BAT0", "Battery", "0");
+        assert_eq!(parse_power_state_from_dir(dir.path()), PowerState::OnAc);
+    }
+
+    #[test]
+    fn parses_empty_dir_as_unknown() {
+        let dir = tempdir().unwrap();
+        assert_eq!(parse_power_state_from_dir(dir.path()), PowerState::Unknown);
+    }
+
+    #[test]
+    fn parses_missing_dir_as_unknown() {
+        let path = std::path::Path::new("/no/such/path/should/exist/at/this/inode/123456");
+        assert_eq!(parse_power_state_from_dir(path), PowerState::Unknown);
+    }
+
+    #[test]
+    fn parses_malformed_files_as_unknown_gracefully() {
+        let dir = tempdir().unwrap();
+        let entry = dir.path().join("garbage");
+        fs::create_dir_all(&entry).unwrap();
+        // No type, no online — should not panic.
+        assert_eq!(parse_power_state_from_dir(dir.path()), PowerState::Unknown);
+    }
+
+    #[test]
+    fn override_drives_battery() {
+        with_override(Some(PowerState::OnBattery), || {
+            assert_eq!(probe_power_state(), PowerState::OnBattery);
+        });
+    }
+
+    #[test]
+    fn override_drives_ac() {
+        with_override(Some(PowerState::OnAc), || {
+            assert_eq!(probe_power_state(), PowerState::OnAc);
+        });
+    }
+
+    #[test]
+    fn override_drives_unknown() {
+        with_override(Some(PowerState::Unknown), || {
+            assert_eq!(probe_power_state(), PowerState::Unknown);
+        });
+    }
+
+    #[test]
+    fn env_var_override_battery_via_set_var() {
+        // env-var path tested in isolation under TEST_LOCK so it
+        // doesn't race with the in-process override tests.
+        with_override(None, || {
+            std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", "battery");
+            assert_eq!(probe_power_state(), PowerState::OnBattery);
+            std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
+        });
+    }
+
+    #[test]
+    fn env_var_override_garbage_falls_through() {
+        with_override(None, || {
+            std::env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", "nonsense");
+            // Garbage value falls through to the platform probe.
+            // We can't assert the platform result so just assert it
+            // doesn't panic.
+            let _ = probe_power_state();
+            std::env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
+        });
+    }
+
+    #[test]
+    fn ttl_cache_returns_cached_value_within_window() {
+        with_override(None, || {
+            force_clear_cache();
+            force_set_cache(PowerState::OnBattery);
+            // No override active, no env var; probe should hit cache.
+            assert_eq!(probe_power_state(), PowerState::OnBattery);
+        });
+    }
+
+    #[test]
+    fn ttl_cache_clears_via_force_clear() {
+        with_override(None, || {
+            force_set_cache(PowerState::OnBattery);
+            force_clear_cache();
+            // Override flips to OnAc; with cleared cache, override
+            // (which has higher priority) drives the result.
+        });
+        with_override(Some(PowerState::OnAc), || {
+            force_clear_cache();
+            assert_eq!(probe_power_state(), PowerState::OnAc);
+        });
+    }
+}

crates/core/src/process_watch.rs

@@ -8,18 +8,55 @@
 
 use sysinfo::{ProcessRefreshKind, ProcessesToUpdate, RefreshKind, System};
 
+/// Reusable wrapper around a `sysinfo::System` whose process table is
+/// refreshed in place on every poll, instead of allocating a fresh one.
+///
+/// On a busy host (~300 processes), `System::new_with_specifics` followed by
+/// `refresh_processes` walks `/proc` cold and costs ~50–100 ms; reusing the
+/// same instance reuses sysinfo's per-process bookkeeping so subsequent
+/// refreshes are dominated by diffing rather than allocation. The Tauri
+/// host holds one of these behind a `Mutex` for the meeting-detection
+/// command to call every 15 s.
+pub struct ProcessLister {
+    system: System,
+}
+
+impl Default for ProcessLister {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl ProcessLister {
+    pub fn new() -> Self {
+        Self {
+            system: System::new_with_specifics(
+                RefreshKind::nothing().with_processes(ProcessRefreshKind::nothing()),
+            ),
+        }
+    }
+
+    /// Refresh the process table in place and return the current
+    /// lowercased executable names.
+    pub fn snapshot(&mut self) -> Vec<String> {
+        self.system.refresh_processes(ProcessesToUpdate::All, true);
+        self.system
+            .processes()
+            .values()
+            .map(|process| process.name().to_string_lossy().to_lowercase())
+            .collect()
+    }
+}
+
 /// Snapshot the current process list's executable/command names. Lowercased
 /// for case-insensitive pattern matching.
+///
+/// Convenience wrapper that allocates a fresh `ProcessLister` per call.
+/// Hot paths (the meeting-detection poller) should hold a long-lived
+/// `ProcessLister` and call `snapshot()` directly to avoid the per-call
+/// allocation of `System`'s internal bookkeeping.
 pub fn list_running_process_names() -> Vec<String> {
-    let mut system = System::new_with_specifics(
-        RefreshKind::nothing().with_processes(ProcessRefreshKind::nothing()),
-    );
-    system.refresh_processes(ProcessesToUpdate::All, true);
-    system
-        .processes()
-        .values()
-        .map(|process| process.name().to_string_lossy().to_lowercase())
-        .collect()
+    ProcessLister::new().snapshot()
 }
 
 /// Match a snapshot of process names against case-insensitive substring

crates/core/src/recommendation.rs

@@ -49,7 +49,7 @@ pub fn score_model(model: &'static ModelEntry, profile: &SystemProfile) -> Optio
     }
 
     let headroom = Megabytes(profile.ram.0.saturating_sub(model.ram_required.0));
-    if headroom > Megabytes::from_gb(4.0) {
+    if headroom > Megabytes::from_gb(4) {
         score += 10.0;
     }
 
@@ -184,7 +184,7 @@ mod tests {
     fn parakeet_is_top_recommendation_when_hardware_supports_it() {
         // Any machine that fits Parakeet in RAM should see it ranked first —
         // Parakeet-TDT is English-only but beats Whisper on English at lower
-        // latency, so it's Kon's default recommendation when eligible.
+        // latency, so it's Lumotia's default recommendation when eligible.
         // (Users on non-English languages adjust manually — handled at the
         // settings-UI level, not at the scoring level for now.)
         let profile = profile_with_ram(Megabytes(16384));

crates/core/src/tuning.rs

@@ -0,0 +1,240 @@
+//! Inference thread-count tuning. Combines physical-core budget,
+//! battery awareness, and GPU-offload awareness into a single helper
+//! callable from both inference call sites.
+
+use crate::power::{self, PowerState};
+use std::collections::HashSet;
+use std::sync::{Mutex, OnceLock};
+
+/// Lower bound for inference threads. Single-threaded inference is
+/// measurably worse than two on every multi-core part.
+pub const MIN_INFERENCE_THREADS: usize = 2;
+
+/// Upper bound for inference threads. whisper.cpp + llama.cpp scaling
+/// flattens around physical core count; SMT siblings contend for FPU
+/// during F16/F32 matmul, so going past physical cores anti-scales.
+/// 8 is a conservative ceiling that leaves <5% on the table for
+/// big-iron desktops while keeping consumer 6c/12t laptops out of
+/// contention territory. Users can override at runtime via
+/// LUMOTIA_INFERENCE_THREADS.
+pub const MAX_INFERENCE_THREADS: usize = 8;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Workload {
+    /// Llama-style transformer. Near-zero CPU work when fully
+    /// offloaded; CPU floor in that case is GPU_FLOOR_LLM.
+    Llm,
+    /// Whisper transcription. Keeps mel spectrogram, decoder
+    /// bookkeeping, and beam search on the CPU even with full Vulkan
+    /// offload; CPU floor is higher: GPU_FLOOR_WHISPER.
+    Whisper,
+}
+
+const GPU_FLOOR_LLM: usize = 2;
+const GPU_FLOOR_WHISPER: usize = 4;
+
+/// Whether a given (workload, on_battery, gpu_offloaded) tuple has
+/// already been logged this process. Prevents log spam when the same
+/// configuration is exercised on every inference call.
+fn log_seen() -> &'static Mutex<HashSet<(Workload, bool, bool)>> {
+    static SEEN: OnceLock<Mutex<HashSet<(Workload, bool, bool)>>> = OnceLock::new();
+    SEEN.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+/// Inference thread count, clamped to the physical-core budget plus
+/// the battery and GPU-offload heuristics.
+///
+/// Resolution order:
+/// 1. `LUMOTIA_INFERENCE_THREADS=N` — absolute bypass, returns N.
+/// 2. base = num_cpus::get_physical() (fallback: available_parallelism).
+/// 3. on battery → base /= 2.
+/// 4. gpu_offloaded → base = min(base, gpu_floor(workload)).
+/// 5. clamp to [MIN_INFERENCE_THREADS, MAX_INFERENCE_THREADS].
+pub fn inference_thread_count(workload: Workload, gpu_offloaded: bool) -> usize {
+    if let Ok(s) = std::env::var("LUMOTIA_INFERENCE_THREADS") {
+        if let Ok(n) = s.parse::<usize>() {
+            if n > 0 {
+                return n;
+            }
+        }
+    }
+    let physical = num_cpus::get_physical();
+    let mut chosen = if physical > 0 {
+        physical
+    } else {
+        std::thread::available_parallelism()
+            .map(|p| p.get())
+            .unwrap_or(MIN_INFERENCE_THREADS)
+    };
+    let on_battery = power::probe_power_state() == PowerState::OnBattery;
+    let mut clamps: Vec<&'static str> = Vec::new();
+    if on_battery {
+        chosen /= 2;
+        clamps.push("battery");
+    }
+    if gpu_offloaded {
+        let floor = match workload {
+            Workload::Llm => GPU_FLOOR_LLM,
+            Workload::Whisper => GPU_FLOOR_WHISPER,
+        };
+        if chosen > floor {
+            chosen = floor;
+            clamps.push("gpu");
+        }
+    }
+    let final_value = chosen.clamp(MIN_INFERENCE_THREADS, MAX_INFERENCE_THREADS);
+
+    // Log once per (workload, on_battery, gpu_offloaded) tuple.
+    let key = (workload, on_battery, gpu_offloaded);
+    if let Ok(mut seen) = log_seen().lock() {
+        if seen.insert(key) {
+            tracing::info!(
+                target: "lumotia_core::tuning",
+                threads = final_value,
+                workload = ?workload,
+                gpu_offloaded,
+                on_battery,
+                clamps = ?clamps,
+                "inference_thread_count"
+            );
+        }
+    }
+
+    final_value
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Serialises tests that read/write `LUMOTIA_INFERENCE_THREADS` so
+    /// they don't race under cargo's parallel test runner.
+    /// Mirrors the pattern used by `power::with_override`.
+    fn with_thread_env_lock<R>(body: impl FnOnce() -> R) -> R {
+        use std::sync::Mutex;
+        static THREAD_ENV_LOCK: Mutex<()> = Mutex::new(());
+        let _lock = THREAD_ENV_LOCK
+            .lock()
+            .expect("tuning thread-env lock poisoned");
+        body()
+    }
+
+    #[test]
+    fn matches_existing_clamp_when_no_clamps_apply() {
+        // With no env override, no battery, no gpu_offload, helper
+        // should return physical-core count clamped to [2, 8].
+        // We can't pin physical exactly without mocking num_cpus; just
+        // assert the result is in range.
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            let n = inference_thread_count(Workload::Llm, false);
+            assert!(
+                (MIN_INFERENCE_THREADS..=MAX_INFERENCE_THREADS).contains(&n),
+                "got {n}, expected within [{MIN_INFERENCE_THREADS}, {MAX_INFERENCE_THREADS}]"
+            );
+        });
+    }
+
+    #[test]
+    fn env_var_bypasses_clamps() {
+        with_thread_env_lock(|| {
+            std::env::set_var("LUMOTIA_INFERENCE_THREADS", "10");
+            let n = inference_thread_count(Workload::Llm, true);
+            assert_eq!(n, 10);
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+        });
+    }
+
+    #[test]
+    fn workload_variants_distinct() {
+        assert_ne!(Workload::Llm, Workload::Whisper);
+    }
+
+    #[test]
+    fn battery_halves_thread_count() {
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            // Measure on battery, then on AC — sequential, not nested,
+            // to avoid re-entrant deadlock on power::TEST_LOCK.
+            let on_battery = crate::power::with_override(Some(PowerState::OnBattery), || {
+                inference_thread_count(Workload::Llm, false)
+            });
+            let on_ac = crate::power::with_override(Some(PowerState::OnAc), || {
+                inference_thread_count(Workload::Llm, false)
+            });
+            // on_battery should be roughly half of on_ac, clamped to MIN.
+            if on_ac > MIN_INFERENCE_THREADS {
+                assert!(
+                    on_battery <= on_ac,
+                    "battery ({on_battery}) should be <= AC ({on_ac})"
+                );
+                assert!(on_battery >= MIN_INFERENCE_THREADS);
+            }
+        });
+    }
+
+    #[test]
+    fn gpu_offload_clamps_llm_to_floor() {
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            crate::power::with_override(Some(PowerState::OnAc), || {
+                let n = inference_thread_count(Workload::Llm, true);
+                assert!(
+                    n <= GPU_FLOOR_LLM.max(MIN_INFERENCE_THREADS),
+                    "Llm with GPU offload should clamp to {GPU_FLOOR_LLM}, got {n}"
+                );
+                assert!(n >= MIN_INFERENCE_THREADS);
+            });
+        });
+    }
+
+    #[test]
+    fn gpu_offload_clamps_whisper_to_floor() {
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            crate::power::with_override(Some(PowerState::OnAc), || {
+                let n = inference_thread_count(Workload::Whisper, true);
+                // Whisper floor is 4 on machines with >=4 physical cores;
+                // can't go lower than physical so on a 2c host we stay at 2.
+                assert!(n <= GPU_FLOOR_WHISPER, "got {n}");
+                assert!(n >= MIN_INFERENCE_THREADS);
+            });
+        });
+    }
+
+    const _: () = assert!(GPU_FLOOR_WHISPER >= GPU_FLOOR_LLM);
+
+    #[test]
+    fn whisper_gpu_floor_is_at_least_llm_gpu_floor() {
+        // Architectural invariant: whisper retains CPU work even when
+        // GPU-offloaded; its floor must not be lower than the LLM's.
+    }
+
+    #[test]
+    fn gpu_offload_off_does_not_clamp_below_battery_calc() {
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            // Sequential measurements; with_override is non-reentrant.
+            crate::power::with_override(Some(PowerState::OnAc), || {
+                let no_gpu = inference_thread_count(Workload::Llm, false);
+                let with_gpu = inference_thread_count(Workload::Llm, true);
+                // GPU-offloaded should be <= non-offloaded.
+                assert!(with_gpu <= no_gpu);
+            });
+        });
+    }
+
+    #[test]
+    fn logging_does_not_panic() {
+        // Smoke: helper should run without panicking when logging is
+        // wired. This is covered by the other tests too, but kept
+        // explicitly to document the behaviour.
+        with_thread_env_lock(|| {
+            std::env::remove_var("LUMOTIA_INFERENCE_THREADS");
+            crate::power::with_override(Some(PowerState::OnBattery), || {
+                let _ = inference_thread_count(Workload::Llm, true);
+                let _ = inference_thread_count(Workload::Whisper, false);
+            });
+        });
+    }
+}

crates/core/src/types.rs

@@ -1,11 +1,18 @@
-use serde::{Deserialize, Serialize};
+use std::borrow::Cow;
+use std::num::NonZeroU32;
+
+use serde::{Deserialize, Deserializer, Serialize};
 
 /// Prevents passing raw strings where model IDs are expected.
-#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
-pub struct ModelId(String);
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
+pub struct ModelId(Cow<'static, str>);
 
 impl ModelId {
-    pub fn new(id: impl Into<String>) -> Self {
+    pub const fn borrowed(id: &'static str) -> Self {
+        Self(Cow::Borrowed(id))
+    }
+
+    pub fn new(id: impl Into<Cow<'static, str>>) -> Self {
         Self(id.into())
     }
 
@@ -14,6 +21,15 @@ impl ModelId {
     }
 }
 
+impl<'de> Deserialize<'de> for ModelId {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        String::deserialize(deserializer).map(|s| Self(Cow::Owned(s)))
+    }
+}
+
 impl std::fmt::Display for ModelId {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.write_str(&self.0)
@@ -21,11 +37,15 @@ impl std::fmt::Display for ModelId {
 }
 
 /// Prevents passing raw strings where engine names are expected.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct EngineName(String);
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct EngineName(Cow<'static, str>);
 
 impl EngineName {
-    pub fn new(name: impl Into<String>) -> Self {
+    pub const fn borrowed(name: &'static str) -> Self {
+        Self(Cow::Borrowed(name))
+    }
+
+    pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
         Self(name.into())
     }
 
@@ -34,6 +54,15 @@ impl EngineName {
     }
 }
 
+impl<'de> Deserialize<'de> for EngineName {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        String::deserialize(deserializer).map(|s| Self(Cow::Owned(s)))
+    }
+}
+
 impl std::fmt::Display for EngineName {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.write_str(&self.0)
@@ -45,8 +74,12 @@ impl std::fmt::Display for EngineName {
 pub struct Megabytes(pub u64);
 
 impl Megabytes {
-    pub fn from_gb(gb: f64) -> Self {
-        Self((gb * 1024.0) as u64)
+    pub const fn from_gb(gb: u64) -> Self {
+        Self(gb.saturating_mul(1024))
+    }
+
+    pub const fn from_mb(mb: u64) -> Self {
+        Self(mb)
     }
 
     pub fn as_gb(&self) -> f64 {
@@ -68,23 +101,36 @@ impl std::fmt::Display for Megabytes {
 #[derive(Debug, Clone)]
 pub struct AudioSamples {
     samples: Vec<f32>,
-    sample_rate: u32,
+    sample_rate: NonZeroU32,
     channels: u16,
 }
 
 impl AudioSamples {
     pub fn new(samples: Vec<f32>, sample_rate: u32, channels: u16) -> Self {
-        Self {
+        Self::try_new(samples, sample_rate, channels)
+            .expect("AudioSamples sample_rate must be non-zero")
+    }
+
+    pub fn try_new(
+        samples: Vec<f32>,
+        sample_rate: u32,
+        channels: u16,
+    ) -> std::result::Result<Self, &'static str> {
+        let Some(sample_rate) = NonZeroU32::new(sample_rate) else {
+            return Err("sample_rate must be non-zero");
+        };
+        Ok(Self {
             samples,
             sample_rate,
             channels,
-        }
+        })
     }
 
     pub fn mono_16khz(samples: Vec<f32>) -> Self {
         Self {
             samples,
-            sample_rate: crate::constants::WHISPER_SAMPLE_RATE,
+            sample_rate: NonZeroU32::new(crate::constants::WHISPER_SAMPLE_RATE)
+                .expect("WHISPER_SAMPLE_RATE must be non-zero"),
             channels: crate::constants::WHISPER_CHANNELS,
         }
     }
@@ -98,7 +144,7 @@ impl AudioSamples {
     }
 
     pub fn sample_rate(&self) -> u32 {
-        self.sample_rate
+        self.sample_rate.get()
     }
 
     pub fn channels(&self) -> u16 {
@@ -106,10 +152,7 @@ impl AudioSamples {
     }
 
     pub fn duration_secs(&self) -> f64 {
-        if self.sample_rate == 0 {
-            return 0.0;
-        }
-        self.samples.len() as f64 / self.sample_rate as f64
+        self.samples.len() as f64 / self.sample_rate.get() as f64
     }
 }
 

crates/hotkey/Cargo.toml

@@ -1,14 +1,14 @@
 [package]
-name = "kon-hotkey"
+name = "lumotia-hotkey"
 version = "0.1.0"
 edition = "2021"
-description = "Wayland-compatible global hotkey listener for Kon — evdev backend with device hotplug"
+description = "Wayland-compatible global hotkey listener for Lumotia — evdev backend with device hotplug"
 
 [dependencies]
-kon-core = { path = "../core" }
+lumotia-core = { path = "../core" }
 tokio = { version = "1", features = ["rt", "sync", "macros", "time"] }
 serde = { version = "1", features = ["derive"] }
-log = "0.4"
+tracing = "0.1"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 evdev = { version = "0.12", features = ["tokio"] }

crates/hotkey/src/lib.rs

@@ -1,4 +1,4 @@
-//! Wayland-compatible global hotkey listener for Kon.
+//! Wayland-compatible global hotkey listener for Lumotia.
 //!
 //! On Linux, reads `/dev/input/event*` devices via the `evdev` crate to capture
 //! global hotkeys without any display-server dependency. This works on both X11
@@ -8,7 +8,7 @@
 //! On non-Linux platforms, this crate is a no-op — the Tauri global-shortcut
 //! plugin handles hotkeys there.
 //!
-//! Architecture stolen from oddlama/whisper-overlay and adapted for Kon.
+//! Architecture stolen from oddlama/whisper-overlay and adapted for Lumotia.
 
 #[cfg(target_os = "linux")]
 mod linux;

crates/hotkey/src/linux.rs

@@ -88,19 +88,19 @@ impl EvdevHotkeyListener {
                         match w.watch(Path::new("/dev/input"), RecursiveMode::NonRecursive) {
                             Ok(()) => Some(w),
                             Err(e) => {
-                                eprintln!(
-                                    "[kon-hotkey] cannot watch /dev/input ({e}); \
-                                 hotplug detection disabled, devices present \
-                                 at startup still work",
+                                tracing::warn!(
+                                    error = %e,
+                                    "cannot watch /dev/input; hotplug detection disabled, \
+                                     devices present at startup still work"
                                 );
                                 None
                             }
                         }
                     }
                     Err(e) => {
-                        eprintln!(
-                            "[kon-hotkey] cannot create inotify watcher ({e}); \
-                             hotplug detection disabled",
+                        tracing::warn!(
+                            error = %e,
+                            "cannot create inotify watcher; hotplug detection disabled"
                         );
                         None
                     }
@@ -199,7 +199,7 @@ async fn scan_and_attach(
     let entries = match std::fs::read_dir(input_dir) {
         Ok(e) => e,
         Err(e) => {
-            log::error!("Cannot read /dev/input: {e}");
+            tracing::error!(error = %e, "cannot read /dev/input");
             return;
         }
     };
@@ -233,7 +233,7 @@ async fn try_attach_device(
     let device = match Device::open(path) {
         Ok(d) => d,
         Err(e) => {
-            log::debug!("Cannot open {}: {e}", path.display());
+            tracing::debug!(path = %path.display(), error = %e, "cannot open device");
             return false;
         }
     };
@@ -243,10 +243,10 @@ async fn try_attach_device(
     }
 
     let device_name = device.name().unwrap_or("unknown").to_string();
-    log::info!(
-        "Attached hotkey listener to: {} ({})",
-        device_name,
-        path.display()
+    tracing::info!(
+        device = %device_name,
+        path = %path.display(),
+        "attached hotkey listener"
     );
 
     tracked_set.insert(path.to_path_buf());
@@ -260,7 +260,11 @@ async fn try_attach_device(
 
     tokio::spawn(async move {
         if let Err(e) = device_listener(device, hotkey_rx, event_tx).await {
-            log::warn!("Device listener for {} ended: {e}", path_owned.display());
+            tracing::warn!(
+                path = %path_owned.display(),
+                error = %e,
+                "device listener ended"
+            );
         }
         // Remove from tracked set so hotplug can re-attach if reconnected
         tracked.lock().await.remove(&path_owned);
@@ -317,10 +321,26 @@ async fn device_listener(
                                     && alt_held == combo.alt
                                     && super_held == combo.super_key
                                 {
-                                    if pressed {
-                                        let _ = event_tx.send(HotkeyEvent::Pressed).await;
+                                    let to_send = if pressed {
+                                        Some(HotkeyEvent::Pressed)
                                     } else if released {
-                                        let _ = event_tx.send(HotkeyEvent::Released).await;
+                                        Some(HotkeyEvent::Released)
+                                    } else {
+                                        None
+                                    };
+                                    if let Some(event) = to_send {
+                                        if event_tx.send(event).await.is_err() {
+                                            // Receiver was dropped without an
+                                            // explicit None-on-hotkey-rx
+                                            // shutdown. Log once and exit so
+                                            // the listener doesn't spin
+                                            // sending into a closed channel.
+                                            tracing::warn!(
+                                                "hotkey event channel closed; \
+                                                 listener for device exiting"
+                                            );
+                                            return Ok(());
+                                        }
                                     }
                                 }
                             }
@@ -343,17 +363,14 @@ async fn device_listener(
 fn is_event_device(path: &Path) -> bool {
     path.file_name()
         .and_then(|n| n.to_str())
-        .map_or(false, |n| n.starts_with("event"))
+        .is_some_and(|n| n.starts_with("event"))
 }
 
 /// Return true when the device's reported key set includes the combo's
 /// configured trigger key. A device that reports no keys at all (for
 /// example a mouse whose `EV_KEY` capability is buttons only) is rejected.
-fn device_supports_combo(
-    supported: Option<&AttributeSetRef<Key>>,
-    combo: &HotkeyCombo,
-) -> bool {
-    supported.map_or(false, |keys| keys.contains(Key::new(combo.key_code)))
+fn device_supports_combo(supported: Option<&AttributeSetRef<Key>>, combo: &HotkeyCombo) -> bool {
+    supported.is_some_and(|keys| keys.contains(Key::new(combo.key_code)))
 }
 
 #[cfg(test)]

crates/hotkey/src/stub.rs

@@ -19,7 +19,7 @@ pub struct EvdevHotkeyListener;
 
 impl EvdevHotkeyListener {
     pub fn start(_combo: HotkeyCombo, _event_tx: mpsc::Sender<HotkeyEvent>) -> Self {
-        log::info!("evdev hotkey listener is a no-op on this platform");
+        tracing::info!("evdev hotkey listener is a no-op on this platform");
         Self
     }
 

crates/llm/Cargo.toml

@@ -1,14 +1,25 @@
 [package]
-name = "kon-llm"
+name = "lumotia-llm"
 version = "0.1.0"
 edition = "2021"
+description = "Local LLM engine for Lumotia (Qwen3.5 / Qwen3.6 via llama-cpp-2): transcript cleanup, task extraction, micro-step decomposition"
+
+[features]
+# Default desktop build keeps the existing openmp + vulkan acceleration.
+# Mobile / CPU-only targets can drop one or both via:
+#   cargo build -p lumotia-llm --no-default-features
+# These are independent so an Android Vulkan build can opt into vulkan
+# without openmp (the NDK ships OpenMP libs but the toolchain configuration
+# is fragile across NDK versions).
+default = ["gpu-vulkan", "openmp"]
+gpu-vulkan = ["llama-cpp-2/vulkan"]
+openmp = ["llama-cpp-2/openmp"]
 
 [dependencies]
-dirs = "6"
+lumotia-core = { path = "../core" }
 encoding_rs = "0.8"
 futures-util = "0.3"
-llama-cpp-2 = { version = "0.1.144", default-features = false, features = ["openmp", "vulkan"] }
-num_cpus = "1"
+llama-cpp-2 = { version = "0.1.146", default-features = false }
 reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

crates/llm/src/grammars.rs

@@ -1,3 +1,18 @@
+// Phase 9 content-tag extraction. Restricts the model output to a
+// strict {topic, intent} JSON object where topic is a lowercase
+// hyphen-joined slug of at least 3 chars (no upper bound is encoded
+// in the grammar — max_tokens caps it in practice) and intent is one
+// of the six closed-set values. Recursive `topic-rest` keeps the
+// shape compatible with the existing GBNF style in this file.
+pub const CONTENT_TAGS_GRAMMAR: &str = r##"
+root        ::= "{" ws "\"topic\":" ws topic-str ws "," ws "\"intent\":" ws intent ws "}" ws
+topic-str   ::= "\"" topic-char topic-char topic-char topic-rest "\""
+topic-rest  ::= "" | topic-char topic-rest
+topic-char  ::= [a-z0-9-]
+intent      ::= "\"planning\"" | "\"reflection\"" | "\"venting\"" | "\"capture\"" | "\"decision\"" | "\"question\""
+ws          ::= ([ \t\n] ws)?
+"##;
+
 pub const TASK_ARRAY_GRAMMAR: &str = r#"
 root   ::= "[" ws string ws "," ws string ws "," ws string rest3 ws "]"
 rest3  ::= "" | "," ws string rest4

crates/llm/src/lib.rs

@@ -9,15 +9,20 @@ use llama_cpp_2::llama_batch::LlamaBatch;
 use llama_cpp_2::model::params::LlamaModelParams;
 use llama_cpp_2::model::{AddBos, LlamaChatMessage, LlamaChatTemplate, LlamaModel};
 use llama_cpp_2::sampling::LlamaSampler;
+use lumotia_core::tuning::{inference_thread_count, Workload};
 use serde::{Deserialize, Serialize};
 
 pub mod grammars;
 pub mod model_manager;
 pub mod prompts;
 
+pub use grammars::CONTENT_TAGS_GRAMMAR;
 pub use model_manager::{recommend_tier, LlmModelId, LlmModelInfo};
+pub use prompts::{is_valid_intent, ContentTags, CONTENT_TAGS_SYSTEM, INTENT_CLOSED_SET};
 
 const DEFAULT_CONTEXT_TOKENS: u32 = 4096;
+const MAX_CONTEXT_TOKENS: u32 = 8192;
+const CONTEXT_RESERVE_TOKENS: u32 = 64;
 const GENERATION_SEED: u32 = 0;
 
 #[derive(Debug, thiserror::Error)]
@@ -26,6 +31,15 @@ pub enum EngineError {
     NotLoaded,
     #[error("LLM load failed: {0}")]
     LoadFailed(String),
+    #[error(
+        "prompt too long: {prompt_tokens} prompt tokens exceed the {available_prompt_tokens}-token prompt budget for an {context_window}-token context with {max_tokens} reserved response tokens"
+    )]
+    PromptTooLong {
+        prompt_tokens: usize,
+        max_tokens: u32,
+        available_prompt_tokens: u32,
+        context_window: u32,
+    },
     #[error("inference failed: {0}")]
     Inference(String),
     #[error("model output not valid JSON: {0}")]
@@ -149,8 +163,17 @@ impl LlmEngine {
             return Ok(String::new());
         }
 
-        let n_ctx = context_window_size(prompt_tokens.len(), config.max_tokens);
-        let thread_count = i32::try_from(num_cpus::get().max(1)).unwrap_or(4);
+        let n_ctx = preflight_context_window(prompt_tokens.len(), config.max_tokens)?;
+        let use_gpu = self.loaded_model().map(|s| s.use_gpu).unwrap_or(false);
+        let gpu_layers = if use_gpu { u32::MAX } else { 0u32 };
+        // Trivially true today (gpu_layers = u32::MAX when use_gpu), but the
+        // explicit comparison documents intent. True residency observability
+        // (parsing llama.cpp's "offloaded N/M layers" log) is tracked as a
+        // follow-up in docs/superpowers/specs/2026-05-09-battery-gpu-aware-
+        // thread-tuning-design.md (§ Out of scope).
+        let gpu_offloaded = use_gpu && gpu_layers >= model.n_layer();
+        let thread_count =
+            i32::try_from(inference_thread_count(Workload::Llm, gpu_offloaded)).unwrap_or(4);
         let ctx_params = LlamaContextParams::default()
             .with_n_ctx(Some(
                 NonZeroU32::new(n_ctx).expect("n_ctx must be non-zero"),
@@ -189,6 +212,10 @@ impl LlmEngine {
             generated.push_str(&piece);
             sampler.accept(next);
 
+            if config.grammar.is_none() && json_envelope_complete(&generated) {
+                break;
+            }
+
             if let Some(stop_index) = first_stop_index(&generated, &config.stop_sequences) {
                 generated.truncate(stop_index);
                 break;
@@ -229,11 +256,30 @@ impl LlmEngine {
     }
 
     pub fn decompose_task(&self, task_text: &str) -> Result<Vec<String>, EngineError> {
+        self.decompose_task_with_feedback(task_text, &[])
+    }
+
+    /// Same as `decompose_task` but allows callers to pass recent HITL
+    /// feedback rows so the system prompt gets conditioned on the
+    /// user's preferred decomposition style. The `examples` vec is
+    /// rendered into a few-shot block appended to the base system
+    /// prompt by `prompts::build_conditioned_system_prompt`.
+    ///
+    /// Callers should pass most-recent-first; older examples still
+    /// participate but weigh less because of their position in the
+    /// prompt. Empty slice keeps behaviour identical to `decompose_task`.
+    pub fn decompose_task_with_feedback(
+        &self,
+        task_text: &str,
+        examples: &[prompts::FeedbackExample],
+    ) -> Result<Vec<String>, EngineError> {
         let model = self.loaded_model_arc()?;
+        let system =
+            prompts::build_conditioned_system_prompt(prompts::DECOMPOSE_TASK_SYSTEM, examples);
         let prompt = render_chat_prompt(
             &model,
             &[
-                ("system", prompts::DECOMPOSE_TASK_SYSTEM),
+                ("system", system.as_str()),
                 ("user", &format!("Task: {task_text}")),
             ],
         )?;
@@ -250,15 +296,83 @@ impl LlmEngine {
     }
 
     pub fn extract_tasks(&self, transcript: &str) -> Result<Vec<String>, EngineError> {
+        self.extract_tasks_with_feedback(transcript, &[])
+    }
+
+    /// Phase 9 content-tag extraction. Emits a single (topic, intent)
+    /// pair as JSON. Truncates to the trailing 2000 chars of the
+    /// transcript so the prompt budget stays well under any model's
+    /// context window. Determinism is enforced by temperature 0.0;
+    /// the parsed intent is re-validated with `is_valid_intent` and
+    /// invalid JSON bubbles as `InvalidJson` so the frontend toasts a
+    /// clear error.
+    pub fn extract_content_tags(
+        &self,
+        transcript: &str,
+    ) -> Result<prompts::ContentTags, EngineError> {
         if transcript.trim().is_empty() {
-            return Ok(Vec::new());
+            return Err(EngineError::Inference("empty transcript".into()));
         }
 
+        // Truncate to the last 2000 chars on a UTF-8 char boundary so
+        // we don't slice through a multi-byte sequence.
+        const MAX_CHARS: usize = 2000;
+        let tail = if transcript.len() > MAX_CHARS {
+            let mut adj = transcript.len() - MAX_CHARS;
+            while adj < transcript.len() && !transcript.is_char_boundary(adj) {
+                adj += 1;
+            }
+            &transcript[adj..]
+        } else {
+            transcript
+        };
+
         let model = self.loaded_model_arc()?;
         let prompt = render_chat_prompt(
             &model,
             &[
-                ("system", prompts::EXTRACT_TASKS_SYSTEM),
+                ("system", prompts::CONTENT_TAGS_SYSTEM),
+                ("user", &format!("Transcript:\n{tail}")),
+            ],
+        )?;
+        let raw = self.generate(
+            &prompt,
+            &GenerationConfig {
+                max_tokens: 96,
+                temperature: 0.0,
+                stop_sequences: vec!["<|im_end|>".to_string(), "<|im_end_of_text|>".to_string()],
+                grammar: None,
+            },
+        )?;
+
+        let tags: prompts::ContentTags = parse_json_payload(&raw)?;
+        if !prompts::is_valid_intent(&tags.intent) {
+            return Err(EngineError::InvalidJson(format!(
+                "intent out of closed set: {}",
+                tags.intent,
+            )));
+        }
+        Ok(tags)
+    }
+
+    /// Feedback-conditioned variant of `extract_tasks`. See
+    /// `decompose_task_with_feedback` for the `examples` semantics.
+    pub fn extract_tasks_with_feedback(
+        &self,
+        transcript: &str,
+        examples: &[prompts::FeedbackExample],
+    ) -> Result<Vec<String>, EngineError> {
+        if transcript.trim().is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let model = self.loaded_model_arc()?;
+        let system =
+            prompts::build_conditioned_system_prompt(prompts::EXTRACT_TASKS_SYSTEM, examples);
+        let prompt = render_chat_prompt(
+            &model,
+            &[
+                ("system", system.as_str()),
                 ("user", &format!("Transcript:\n{transcript}")),
             ],
         )?;
@@ -317,8 +431,26 @@ impl LlmEngine {
 fn context_window_size(prompt_tokens: usize, max_tokens: u32) -> u32 {
     let required = prompt_tokens
         .saturating_add(max_tokens as usize)
-        .saturating_add(64);
-    DEFAULT_CONTEXT_TOKENS.max(required.min(8192) as u32)
+        .saturating_add(CONTEXT_RESERVE_TOKENS as usize);
+    DEFAULT_CONTEXT_TOKENS.max(required.min(MAX_CONTEXT_TOKENS as usize) as u32)
+}
+
+fn preflight_context_window(prompt_tokens: usize, max_tokens: u32) -> Result<u32, EngineError> {
+    let required = prompt_tokens
+        .saturating_add(max_tokens as usize)
+        .saturating_add(CONTEXT_RESERVE_TOKENS as usize);
+    if required > MAX_CONTEXT_TOKENS as usize {
+        let available_prompt_tokens =
+            MAX_CONTEXT_TOKENS.saturating_sub(max_tokens.saturating_add(CONTEXT_RESERVE_TOKENS));
+        return Err(EngineError::PromptTooLong {
+            prompt_tokens,
+            max_tokens,
+            available_prompt_tokens,
+            context_window: MAX_CONTEXT_TOKENS,
+        });
+    }
+
+    Ok(context_window_size(prompt_tokens, max_tokens))
 }
 
 fn first_stop_index(text: &str, stop_sequences: &[String]) -> Option<usize> {
@@ -329,6 +461,62 @@ fn first_stop_index(text: &str, stop_sequences: &[String]) -> Option<usize> {
         .min()
 }
 
+fn json_envelope_complete(text: &str) -> bool {
+    extract_json_envelope(text) == Some(text.trim())
+}
+
+fn extract_json_envelope(text: &str) -> Option<&str> {
+    let start = text
+        .char_indices()
+        .find_map(|(idx, ch)| (ch == '{' || ch == '[').then_some(idx))?;
+    let mut chars = text[start..].char_indices();
+    let (_, first) = chars.next()?;
+
+    let mut stack = vec![match first {
+        '{' => '}',
+        '[' => ']',
+        _ => unreachable!(),
+    }];
+    let mut in_string = false;
+    let mut escaped = false;
+
+    while let Some((offset, ch)) = chars.next() {
+        if in_string {
+            if escaped {
+                escaped = false;
+            } else if ch == '\\' {
+                escaped = true;
+            } else if ch == '"' {
+                in_string = false;
+            }
+            continue;
+        }
+
+        match ch {
+            '"' => in_string = true,
+            '{' => stack.push('}'),
+            '[' => stack.push(']'),
+            '}' | ']' => {
+                if stack.pop() != Some(ch) {
+                    return None;
+                }
+                if stack.is_empty() {
+                    let end = start + offset + ch.len_utf8();
+                    return Some(&text[start..end]);
+                }
+            }
+            _ => {}
+        }
+    }
+
+    None
+}
+
+fn parse_json_payload<T: for<'de> Deserialize<'de>>(raw: &str) -> Result<T, EngineError> {
+    let payload = extract_json_envelope(raw).unwrap_or(raw.trim());
+    serde_json::from_str(payload).map_err(|e| EngineError::InvalidJson(format!("{e}: raw={raw:?}")))
+}
+
 fn render_chat_prompt(
     model: &LlamaModel,
     messages: &[(&str, &str)],
@@ -417,4 +605,65 @@ mod tests {
         let index = first_stop_index(text, &["<|im_end|>".into(), "zzz".into()]);
         assert_eq!(index, Some(5));
     }
+
+    #[test]
+    fn json_envelope_complete_detects_finished_object() {
+        assert!(json_envelope_complete(
+            r#"{"topic":"meeting","intent":"planning"}"#
+        ));
+    }
+
+    #[test]
+    fn json_envelope_complete_detects_finished_array() {
+        assert!(json_envelope_complete(r#"["Call plumber","Buy milk"]"#));
+    }
+
+    #[test]
+    fn json_envelope_complete_ignores_braces_inside_strings() {
+        assert!(!json_envelope_complete(r#"{"topic":"literal } brace""#));
+    }
+
+    #[test]
+    fn json_envelope_complete_rejects_prefixes_and_trailing_text() {
+        assert!(!json_envelope_complete(r#"{"topic":"meeting""#));
+        assert!(!json_envelope_complete(r#"{"topic":"meeting"} extra"#));
+    }
+
+    #[test]
+    fn extract_json_envelope_skips_qwen_thinking_prefix() {
+        let raw =
+            "<think>\n\n</think>\n\n{\"topic\":\"grant-application\",\"intent\":\"planning\"}";
+        assert_eq!(
+            extract_json_envelope(raw),
+            Some("{\"topic\":\"grant-application\",\"intent\":\"planning\"}"),
+        );
+    }
+
+    #[test]
+    fn extract_json_envelope_handles_arrays_and_trailing_stop_text() {
+        assert_eq!(
+            extract_json_envelope("prefix [\"Call plumber\",\"Buy milk\"]<|im_end|>"),
+            Some("[\"Call plumber\",\"Buy milk\"]"),
+        );
+    }
+
+    #[test]
+    fn prompt_preflight_rejects_oversized_prompt_tokens() {
+        let err = preflight_context_window(7_105, 1_024).unwrap_err();
+        assert!(matches!(
+            err,
+            EngineError::PromptTooLong {
+                prompt_tokens: 7_105,
+                max_tokens: 1_024,
+                available_prompt_tokens: 7_104,
+                context_window: MAX_CONTEXT_TOKENS,
+            }
+        ));
+    }
+
+    #[test]
+    fn prompt_preflight_keeps_prompts_within_budget() {
+        let n_ctx = preflight_context_window(7_104, 1_024).unwrap();
+        assert_eq!(n_ctx, MAX_CONTEXT_TOKENS);
+    }
 }

crates/llm/src/model_manager.rs

@@ -2,6 +2,7 @@ use std::fmt;
 use std::io;
 use std::path::{Path, PathBuf};
 use std::str::FromStr;
+use std::sync::{LazyLock, Mutex};
 
 use futures_util::StreamExt;
 use serde::{Deserialize, Serialize};
@@ -11,100 +12,119 @@ use tokio::io::{AsyncReadExt, AsyncWriteExt};
 #[allow(non_camel_case_types)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum LlmModelId {
-    #[serde(rename = "qwen3_1_7b")]
-    Qwen3_1_7B_Q4,
-    #[serde(rename = "qwen3_4b_instruct_2507")]
-    Qwen3_4BInstruct2507Q4,
-    #[serde(rename = "qwen3_14b")]
-    Qwen3_14BQ5,
+    #[serde(rename = "qwen3_5_2b")]
+    Qwen3_5_2B_Q4,
+    #[serde(rename = "qwen3_5_4b")]
+    Qwen3_5_4B_Q4,
+    #[serde(rename = "qwen3_5_9b")]
+    Qwen3_5_9B_Q4,
+    #[serde(rename = "qwen3_6_27b")]
+    Qwen3_6_27B_Q4,
 }
 
 impl LlmModelId {
     pub fn default_tier() -> Self {
-        Self::Qwen3_4BInstruct2507Q4
+        Self::Qwen3_5_4B_Q4
     }
 
     pub fn as_str(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => "qwen3_1_7b",
-            Self::Qwen3_4BInstruct2507Q4 => "qwen3_4b_instruct_2507",
-            Self::Qwen3_14BQ5 => "qwen3_14b",
+            Self::Qwen3_5_2B_Q4 => "qwen3_5_2b",
+            Self::Qwen3_5_4B_Q4 => "qwen3_5_4b",
+            Self::Qwen3_5_9B_Q4 => "qwen3_5_9b",
+            Self::Qwen3_6_27B_Q4 => "qwen3_6_27b",
         }
     }
 
     pub fn display_name(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => "Qwen3 1.7B",
-            Self::Qwen3_4BInstruct2507Q4 => "Qwen3 4B Instruct 2507",
-            Self::Qwen3_14BQ5 => "Qwen3 14B",
+            Self::Qwen3_5_2B_Q4 => "Qwen3.5 2B",
+            Self::Qwen3_5_4B_Q4 => "Qwen3.5 4B",
+            Self::Qwen3_5_9B_Q4 => "Qwen3.5 9B",
+            Self::Qwen3_6_27B_Q4 => "Qwen3.6 27B",
         }
     }
 
     pub fn file_name(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => "Qwen3-1.7B-Q4_K_M.gguf",
-            Self::Qwen3_4BInstruct2507Q4 => "Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
-            Self::Qwen3_14BQ5 => "Qwen3-14B-Q5_K_M.gguf",
+            Self::Qwen3_5_2B_Q4 => "Qwen3.5-2B-Q4_K_M.gguf",
+            Self::Qwen3_5_4B_Q4 => "Qwen3.5-4B-Q4_K_M.gguf",
+            Self::Qwen3_5_9B_Q4 => "Qwen3.5-9B-Q4_K_M.gguf",
+            Self::Qwen3_6_27B_Q4 => "Qwen3.6-27B-Q4_K_M.gguf",
         }
     }
 
     pub fn size_bytes(&self) -> u64 {
         match self {
-            Self::Qwen3_1_7B_Q4 => 1_107_409_472,
-            Self::Qwen3_4BInstruct2507Q4 => 2_497_281_120,
-            Self::Qwen3_14BQ5 => 10_514_570_624,
+            Self::Qwen3_5_2B_Q4 => 1_280_835_840,
+            Self::Qwen3_5_4B_Q4 => 2_740_937_888,
+            Self::Qwen3_5_9B_Q4 => 5_680_522_464,
+            Self::Qwen3_6_27B_Q4 => 16_817_244_384,
         }
     }
 
     pub fn minimum_ram_bytes(&self) -> u64 {
         match self {
-            Self::Qwen3_1_7B_Q4 => 8 * 1024_u64.pow(3),
-            Self::Qwen3_4BInstruct2507Q4 => 16 * 1024_u64.pow(3),
-            Self::Qwen3_14BQ5 => 32 * 1024_u64.pow(3),
+            Self::Qwen3_5_2B_Q4 => 8 * 1024_u64.pow(3),
+            Self::Qwen3_5_4B_Q4 => 16 * 1024_u64.pow(3),
+            Self::Qwen3_5_9B_Q4 => 32 * 1024_u64.pow(3),
+            Self::Qwen3_6_27B_Q4 => 64 * 1024_u64.pow(3),
         }
     }
 
     pub fn recommended_vram_bytes(&self) -> Option<u64> {
         match self {
-            Self::Qwen3_1_7B_Q4 => None,
-            Self::Qwen3_4BInstruct2507Q4 => Some(8 * 1024_u64.pow(3)),
-            Self::Qwen3_14BQ5 => Some(16 * 1024_u64.pow(3)),
+            Self::Qwen3_5_2B_Q4 => None,
+            Self::Qwen3_5_4B_Q4 => Some(6 * 1024_u64.pow(3)),
+            Self::Qwen3_5_9B_Q4 => Some(12 * 1024_u64.pow(3)),
+            Self::Qwen3_6_27B_Q4 => Some(24 * 1024_u64.pow(3)),
         }
     }
 
     pub fn description(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => "Low tier for 8 GB RAM and CPU-heavy machines.",
-            Self::Qwen3_4BInstruct2507Q4 => {
-                "Default tier for cleanup and task extraction on 16 GB systems."
+            Self::Qwen3_5_2B_Q4 => "Minimal tier for 8 GB RAM and CPU-heavy machines.",
+            Self::Qwen3_5_4B_Q4 => {
+                "Standard tier for cleanup and task extraction on 16 GB systems."
+            }
+            Self::Qwen3_5_9B_Q4 => "High tier for 32 GB RAM with a 12 GB+ GPU.",
+            Self::Qwen3_6_27B_Q4 => {
+                "Maximum tier for 64 GB RAM with a 24 GB GPU; partial CPU offload below that."
             }
-            Self::Qwen3_14BQ5 => "High tier for 32 GB+ RAM and larger GPUs.",
         }
     }
 
     pub fn hf_url(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => {
-                "https://huggingface.co/unsloth/Qwen3-1.7B-GGUF/resolve/d7f544eead698dbd1f15126ef60b45a1e1933222/Qwen3-1.7B-Q4_K_M.gguf"
+            Self::Qwen3_5_2B_Q4 => {
+                "https://huggingface.co/unsloth/Qwen3.5-2B-GGUF/resolve/f6d5376be1edb4d416d56da11e5397a961aca8ae/Qwen3.5-2B-Q4_K_M.gguf"
             }
-            Self::Qwen3_4BInstruct2507Q4 => {
-                "https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/resolve/a06e946bb6b655725eafa393f4a9745d460374c9/Qwen3-4B-Instruct-2507-Q4_K_M.gguf"
+            Self::Qwen3_5_4B_Q4 => {
+                "https://huggingface.co/unsloth/Qwen3.5-4B-GGUF/resolve/e87f176479d0855a907a41277aca2f8ee7a09523/Qwen3.5-4B-Q4_K_M.gguf"
             }
-            Self::Qwen3_14BQ5 => {
-                "https://huggingface.co/unsloth/Qwen3-14B-GGUF/resolve/a04a82c4739b3ef5fa6da7d10261db2c67dd1985/Qwen3-14B-Q5_K_M.gguf"
+            Self::Qwen3_5_9B_Q4 => {
+                "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/3885219b6810b007914f3a7950a8d1b469d598a5/Qwen3.5-9B-Q4_K_M.gguf"
+            }
+            Self::Qwen3_6_27B_Q4 => {
+                "https://huggingface.co/unsloth/Qwen3.6-27B-GGUF/resolve/82d411acf4a06cfb8d9b073a5211bf410bfc29bf/Qwen3.6-27B-Q4_K_M.gguf"
             }
         }
     }
 
     pub fn sha256(&self) -> &'static str {
         match self {
-            Self::Qwen3_1_7B_Q4 => {
-                "de942b0819216caa3bfe487180dd1bb37398fa1c98cb42bb0bbac7ab7d6e8a12"
+            Self::Qwen3_5_2B_Q4 => {
+                "aaf42c8b7c3cab2bf3d69c355048d4a0ee9973d48f16c731c0520ee914699223"
             }
-            Self::Qwen3_4BInstruct2507Q4 => {
-                "bf52d44a54b81d44219833556849529ee96f09da673a38783dddc2e2eaf17881"
+            Self::Qwen3_5_4B_Q4 => {
+                "00fe7986ff5f6b463e62455821146049db6f9313603938a70800d1fb69ef11a4"
+            }
+            Self::Qwen3_5_9B_Q4 => {
+                "03b74727a860a56338e042c4420bb3f04b2fec5734175f4cb9fa853daf52b7e8"
+            }
+            Self::Qwen3_6_27B_Q4 => {
+                "5ed60d0af4650a854b1755bd392f9aef4872643dc25a254bc68043fa638392a0"
             }
-            Self::Qwen3_14BQ5 => "6f87abc471bd509ad46aca4284b3cfa926d8114bc491bb0a7a3a7f74c16ef95b",
         }
     }
 }
@@ -120,9 +140,10 @@ impl FromStr for LlmModelId {
 
     fn from_str(value: &str) -> Result<Self, Self::Err> {
         match value {
-            "qwen3_1_7b" => Ok(Self::Qwen3_1_7B_Q4),
-            "qwen3_4b_instruct_2507" => Ok(Self::Qwen3_4BInstruct2507Q4),
-            "qwen3_14b" => Ok(Self::Qwen3_14BQ5),
+            "qwen3_5_2b" => Ok(Self::Qwen3_5_2B_Q4),
+            "qwen3_5_4b" => Ok(Self::Qwen3_5_4B_Q4),
+            "qwen3_5_9b" => Ok(Self::Qwen3_5_9B_Q4),
+            "qwen3_6_27b" => Ok(Self::Qwen3_6_27B_Q4),
             other => Err(format!("Unknown LLM model id: {other}")),
         }
     }
@@ -153,11 +174,42 @@ pub enum DownloadError {
 }
 
 const ALL_MODELS: &[LlmModelId] = &[
-    LlmModelId::Qwen3_1_7B_Q4,
-    LlmModelId::Qwen3_4BInstruct2507Q4,
-    LlmModelId::Qwen3_14BQ5,
+    LlmModelId::Qwen3_5_2B_Q4,
+    LlmModelId::Qwen3_5_4B_Q4,
+    LlmModelId::Qwen3_5_9B_Q4,
+    LlmModelId::Qwen3_6_27B_Q4,
 ];
 
+static ACTIVE_DOWNLOADS: LazyLock<Mutex<std::collections::HashSet<LlmModelId>>> =
+    LazyLock::new(|| Mutex::new(std::collections::HashSet::new()));
+
+struct DownloadReservation {
+    id: LlmModelId,
+}
+
+impl DownloadReservation {
+    fn acquire(id: LlmModelId) -> Result<Self, DownloadError> {
+        let mut active = ACTIVE_DOWNLOADS
+            .lock()
+            .map_err(|_| DownloadError::Http("download lock poisoned".into()))?;
+        if !active.insert(id) {
+            return Err(DownloadError::Http(format!(
+                "download already in progress for {}",
+                id.as_str()
+            )));
+        }
+        Ok(Self { id })
+    }
+}
+
+impl Drop for DownloadReservation {
+    fn drop(&mut self) {
+        if let Ok(mut active) = ACTIVE_DOWNLOADS.lock() {
+            active.remove(&self.id);
+        }
+    }
+}
+
 pub fn all_models() -> &'static [LlmModelId] {
     ALL_MODELS
 }
@@ -175,34 +227,20 @@ pub fn model_info(id: LlmModelId) -> LlmModelInfo {
 }
 
 pub fn recommend_tier(total_ram_bytes: u64, total_vram_bytes: Option<u64>) -> LlmModelId {
-    if total_vram_bytes.unwrap_or(0) >= 16 * 1024_u64.pow(3)
-        && total_ram_bytes >= 32 * 1024_u64.pow(3)
-    {
-        LlmModelId::Qwen3_14BQ5
-    } else if total_vram_bytes.unwrap_or(0) >= 8 * 1024_u64.pow(3)
-        || total_ram_bytes >= 16 * 1024_u64.pow(3)
-    {
-        LlmModelId::Qwen3_4BInstruct2507Q4
+    let vram = total_vram_bytes.unwrap_or(0);
+    if vram >= 24 * 1024_u64.pow(3) && total_ram_bytes >= 64 * 1024_u64.pow(3) {
+        LlmModelId::Qwen3_6_27B_Q4
+    } else if vram >= 12 * 1024_u64.pow(3) && total_ram_bytes >= 32 * 1024_u64.pow(3) {
+        LlmModelId::Qwen3_5_9B_Q4
+    } else if vram >= 6 * 1024_u64.pow(3) || total_ram_bytes >= 16 * 1024_u64.pow(3) {
+        LlmModelId::Qwen3_5_4B_Q4
     } else {
-        LlmModelId::Qwen3_1_7B_Q4
+        LlmModelId::Qwen3_5_2B_Q4
     }
 }
 
 pub fn model_dir() -> PathBuf {
-    if cfg!(target_os = "windows") {
-        std::env::var("LOCALAPPDATA")
-            .map(PathBuf::from)
-            .unwrap_or_else(|_| PathBuf::from("."))
-            .join("kon")
-            .join("models")
-            .join("llm")
-    } else {
-        dirs::home_dir()
-            .unwrap_or_else(|| PathBuf::from("."))
-            .join(".kon")
-            .join("models")
-            .join("llm")
-    }
+    lumotia_core::paths::app_paths().llm_models_dir()
 }
 
 pub fn model_path(id: LlmModelId) -> PathBuf {
@@ -235,6 +273,7 @@ pub async fn download_model<F>(id: LlmModelId, on_progress: F) -> Result<(), Dow
 where
     F: FnMut(u64, u64) + Send + 'static,
 {
+    let _reservation = DownloadReservation::acquire(id)?;
     let dest = model_path(id);
     tokio::fs::create_dir_all(model_dir()).await?;
 
@@ -282,7 +321,7 @@ where
         .unwrap_or(0);
 
     let client = reqwest::Client::builder()
-        .user_agent("kon/0.1.0")
+        .user_agent("lumotia/0.1.0")
         .connect_timeout(std::time::Duration::from_secs(30))
         .build()
         .map_err(|e| DownloadError::Http(e.to_string()))?;
@@ -370,15 +409,15 @@ mod tests {
 
     #[test]
     fn model_path_contains_model_dir_and_filename() {
-        let path = model_path(LlmModelId::Qwen3_1_7B_Q4);
-        assert!(path.to_string_lossy().ends_with("Qwen3-1.7B-Q4_K_M.gguf"));
+        let path = model_path(LlmModelId::Qwen3_5_2B_Q4);
+        assert!(path.to_string_lossy().ends_with("Qwen3.5-2B-Q4_K_M.gguf"));
         assert!(path.starts_with(model_dir()));
     }
 
     #[test]
     fn recommend_tier_prefers_mid_by_default() {
         let tier = recommend_tier(16 * 1024_u64.pow(3), None);
-        assert_eq!(tier, LlmModelId::Qwen3_4BInstruct2507Q4);
+        assert_eq!(tier, LlmModelId::Qwen3_5_4B_Q4);
     }
 
     #[tokio::test]

crates/llm/src/prompts.rs

@@ -4,9 +4,152 @@ between 3 and 7 concrete, physical micro-steps. Each step must be a short \
 imperative sentence, actionable today, with no commentary. Output ONLY a \
 JSON array of strings.";
 
+// Phase 9 content-tag extraction. The model emits a {topic, intent}
+// JSON pair under a strict GBNF (see grammars::CONTENT_TAGS_GRAMMAR).
+// CONTENT_TAGS_SYSTEM is the system message; the user message wraps
+// the transcript text.
+pub const CONTENT_TAGS_SYSTEM: &str = "\
+You tag a transcript with ONE topic and ONE intent. \
+TOPIC is a 1 to 3 token lowercase hyphen-joined noun phrase naming the \
+dominant subject. Examples: interview-prep, grant-application, \
+daily-standup. \
+INTENT is exactly one of: planning, reflection, venting, capture, \
+decision, question. \
+Return JSON only, with this exact shape: \
+{\"topic\":\"...\",\"intent\":\"...\"}";
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ContentTags {
+    pub topic: String,
+    pub intent: String,
+}
+
+pub const INTENT_CLOSED_SET: &[&str] = &[
+    "planning",
+    "reflection",
+    "venting",
+    "capture",
+    "decision",
+    "question",
+];
+
+pub fn is_valid_intent(s: &str) -> bool {
+    INTENT_CLOSED_SET.contains(&s)
+}
+
 pub const EXTRACT_TASKS_SYSTEM: &str = "\
 You are a task-extraction assistant. Given a transcript of spoken notes, \
 output a JSON array of action items the speaker committed to. Each item must \
 be a short imperative sentence. Omit observations, wishes, and background \
 context that are not explicit commitments. Output an empty array if there are \
 no action items.";
+
+/// Compact representation of a human-in-the-loop feedback example used
+/// for few-shot prompt conditioning. Built by lumotia-storage and fed to the
+/// prompt builder below; we keep this struct local to the LLM crate so
+/// lumotia-llm does not depend on lumotia-storage.
+#[derive(Debug, Clone)]
+pub struct FeedbackExample {
+    /// What the AI was given as input (e.g. the parent task text, or
+    /// the transcript chunk). Kept verbatim.
+    pub input: String,
+    /// What the AI produced originally. `None` if the user only
+    /// gave a thumbs-up without a prior edit (positive signal
+    /// without a paired correction).
+    pub original_output: Option<String>,
+    /// What the user changed it to. `None` for thumbs-only rows.
+    /// This is the highest-value signal — when present, inject it
+    /// as the "good" output in the few-shot example.
+    pub corrected_output: Option<String>,
+}
+
+/// Render a feedback example into the exemplar block used in prompt
+/// conditioning. Returns `None` for rows that carry no usable pairing
+/// (e.g. a thumbs-up with no input context).
+fn render_feedback_exemplar(ex: &FeedbackExample) -> Option<String> {
+    if ex.input.trim().is_empty() {
+        return None;
+    }
+    let good = ex
+        .corrected_output
+        .as_deref()
+        .or(ex.original_output.as_deref())?;
+    let good = good.trim();
+    if good.is_empty() {
+        return None;
+    }
+    Some(format!("Input: {}\nGood output: {}", ex.input.trim(), good))
+}
+
+/// Build a system prompt that combines the base task system prompt
+/// with a few-shot block assembled from recent HITL examples. If no
+/// usable examples are available, returns the base prompt unchanged
+/// so early users see the generic behaviour and the LLM is not
+/// confused by an empty exemplar section.
+///
+/// The exemplars are ordered most-recent-first (caller's order is
+/// preserved) so the LLM weights the user's current style over
+/// earlier noise, mirroring what a human reviewer would do.
+pub fn build_conditioned_system_prompt(base: &str, examples: &[FeedbackExample]) -> String {
+    let rendered: Vec<String> = examples
+        .iter()
+        .filter_map(render_feedback_exemplar)
+        .collect();
+    if rendered.is_empty() {
+        return base.to_string();
+    }
+    let block = rendered
+        .iter()
+        .map(|s| format!("- {s}"))
+        .collect::<Vec<_>>()
+        .join("\n");
+    format!(
+        "{base}\n\nHere are examples of the style this user prefers, in the \
+         user's own words. Match this style closely when producing your output:\n{block}"
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn builds_plain_prompt_when_no_examples() {
+        let out = build_conditioned_system_prompt(DECOMPOSE_TASK_SYSTEM, &[]);
+        assert_eq!(out, DECOMPOSE_TASK_SYSTEM);
+    }
+
+    #[test]
+    fn skips_empty_input_examples() {
+        let examples = vec![FeedbackExample {
+            input: String::new(),
+            original_output: None,
+            corrected_output: Some("ignored".into()),
+        }];
+        let out = build_conditioned_system_prompt(DECOMPOSE_TASK_SYSTEM, &examples);
+        assert_eq!(out, DECOMPOSE_TASK_SYSTEM);
+    }
+
+    #[test]
+    fn prefers_corrected_over_original() {
+        let examples = vec![FeedbackExample {
+            input: "Clean room".into(),
+            original_output: Some("Organise your bedroom".into()),
+            corrected_output: Some("Pick up one shirt from the floor".into()),
+        }];
+        let out = build_conditioned_system_prompt(DECOMPOSE_TASK_SYSTEM, &examples);
+        assert!(out.contains("Pick up one shirt from the floor"));
+        assert!(!out.contains("Organise your bedroom"));
+    }
+
+    #[test]
+    fn falls_back_to_original_when_no_correction() {
+        let examples = vec![FeedbackExample {
+            input: "Write report".into(),
+            original_output: Some("Open a blank document".into()),
+            corrected_output: None,
+        }];
+        let out = build_conditioned_system_prompt(DECOMPOSE_TASK_SYSTEM, &examples);
+        assert!(out.contains("Open a blank document"));
+    }
+}

crates/llm/tests/content_tags_smoke.rs

@@ -0,0 +1,48 @@
+//! Smoke test for Phase 9 LlmEngine::extract_content_tags.
+//!
+//! Gated behind the same `LUMOTIA_LLM_TEST_MODEL` env var as the existing
+//! smoke.rs test so neither runs in default `cargo test` runs (model
+//! load is heavy). Run explicitly with:
+//!
+//!     LUMOTIA_LLM_TEST_MODEL=/path/to/model.gguf cargo test -p lumotia-llm \
+//!         --test content_tags_smoke -- --nocapture
+
+use std::env;
+use std::path::PathBuf;
+
+use lumotia_llm::{is_valid_intent, LlmEngine, LlmModelId};
+
+#[test]
+fn extract_content_tags_returns_valid_pair() {
+    let model_path = match env::var("LUMOTIA_LLM_TEST_MODEL") {
+        Ok(path) => PathBuf::from(path),
+        Err(_) => {
+            eprintln!("LUMOTIA_LLM_TEST_MODEL not set — skipping");
+            return;
+        }
+    };
+
+    let engine = LlmEngine::new();
+    engine
+        .load_model(LlmModelId::Qwen3_5_2B_Q4, &model_path, true)
+        .expect("load model");
+
+    let transcript = "Tomorrow I need to run through the grant application one more time \
+                      and make sure the figures add up. I also need to book a slot with \
+                      Rachmann for the Mac test and email Andrew about the meeting window.";
+    let tags = engine
+        .extract_content_tags(transcript)
+        .expect("extract_content_tags");
+
+    assert!(tags.topic.len() >= 3, "topic present: {tags:?}");
+    assert!(
+        tags.topic
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'),
+        "topic lowercase + slugged: {tags:?}",
+    );
+    assert!(
+        is_valid_intent(&tags.intent),
+        "intent in closed set: {tags:?}",
+    );
+}

crates/llm/tests/smoke.rs

@@ -6,33 +6,33 @@
 //! - `context::params::LlamaContextParams`
 //! - `sampling::LlamaSampler`
 //!
-//! The test is gated behind `KON_LLM_TEST_MODEL`.
+//! The test is gated behind `LUMOTIA_LLM_TEST_MODEL`.
 
 use std::env;
 use std::path::PathBuf;
 
-use kon_llm::LlmEngine;
-use kon_llm::LlmModelId;
+use lumotia_llm::LlmEngine;
+use lumotia_llm::LlmModelId;
 
 #[test]
 fn llama_cpp_2_smoke_generates_and_wraps() {
-    let model_path = match env::var("KON_LLM_TEST_MODEL") {
+    let model_path = match env::var("LUMOTIA_LLM_TEST_MODEL") {
         Ok(path) => PathBuf::from(path),
         Err(_) => {
-            eprintln!("KON_LLM_TEST_MODEL not set — skipping");
+            eprintln!("LUMOTIA_LLM_TEST_MODEL not set — skipping");
             return;
         }
     };
 
     let engine = LlmEngine::new();
     engine
-        .load_model(LlmModelId::Qwen3_1_7B_Q4, &model_path, true)
+        .load_model(LlmModelId::Qwen3_5_2B_Q4, &model_path, true)
         .expect("load model");
 
     let completion = engine
         .generate(
             "Write exactly one short greeting.",
-            &kon_llm::GenerationConfig {
+            &lumotia_llm::GenerationConfig {
                 max_tokens: 32,
                 temperature: 0.0,
                 stop_sequences: vec!["\n".to_string()],

crates/mcp/Cargo.toml

@@ -1,18 +1,18 @@
 [package]
-name = "kon-mcp"
+name = "lumotia-mcp"
 version = "0.1.0"
 edition = "2021"
-description = "Read-only MCP stdio server exposing Kon transcripts and tasks to external agents"
+description = "Read-only MCP stdio server exposing Lumotia transcripts and tasks to external agents"
 
 [[bin]]
-name = "kon-mcp"
+name = "lumotia-mcp"
 path = "src/main.rs"
 
 [lib]
 path = "src/lib.rs"
 
 [dependencies]
-kon-storage = { path = "../storage" }
+lumotia-storage = { path = "../storage" }
 sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

crates/mcp/src/lib.rs

@@ -1,8 +1,8 @@
-//! Minimal Model Context Protocol server exposing Kon's local SQLite store.
+//! Minimal Model Context Protocol server exposing Lumotia's local SQLite store.
 //!
 //! Scope: **read-only** tools. An external agent (Claude desktop, Cline, any
 //! MCP-capable client) can list / search / fetch transcripts and list tasks.
-//! No writes — Kon's Tauri app remains the only writer.
+//! No writes — Lumotia's Tauri app remains the only writer.
 //!
 //! Transport: newline-delimited JSON-RPC 2.0 over stdio, per the stdio
 //! transport spec. Server spec version: 2024-11-05.
@@ -12,7 +12,7 @@ use serde_json::{json, Value};
 use sqlx::SqlitePool;
 
 pub const PROTOCOL_VERSION: &str = "2024-11-05";
-pub const SERVER_NAME: &str = "kon-mcp";
+pub const SERVER_NAME: &str = "lumotia-mcp";
 pub const SERVER_VERSION: &str = env!("CARGO_PKG_VERSION");
 
 #[derive(Debug, Deserialize)]
@@ -95,7 +95,7 @@ fn initialize_result() -> Value {
             "version": SERVER_VERSION,
         },
         "instructions":
-            "Read-only access to Kon's local transcript history and task list. \
+            "Read-only access to Lumotia's local transcript history and task list. \
              All data stays on the user's machine.",
     })
 }
@@ -105,7 +105,7 @@ fn tools_list_result() -> Value {
         "tools": [
             {
                 "name": "list_transcripts",
-                "description": "List recent transcripts from Kon's local history, most recent first. \
+                "description": "List recent transcripts from Lumotia's local history, most recent first. \
                                 Returns summaries (id, title, created_at, duration, preview).",
                 "inputSchema": {
                     "type": "object",
@@ -135,7 +135,7 @@ fn tools_list_result() -> Value {
             },
             {
                 "name": "search_transcripts",
-                "description": "Full-text search across Kon's transcripts. Returns matching summaries.",
+                "description": "Full-text search across Lumotia's transcripts. Returns matching summaries.",
                 "inputSchema": {
                     "type": "object",
                     "required": ["query"],
@@ -155,7 +155,7 @@ fn tools_list_result() -> Value {
             },
             {
                 "name": "list_tasks",
-                "description": "List tasks from Kon's task store. Returns both open and completed.",
+                "description": "List tasks from Lumotia's task store. Returns both open and completed.",
                 "inputSchema": {
                     "type": "object",
                     "properties": {},
@@ -206,7 +206,7 @@ async fn list_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value,
     };
     let limit = args.limit.unwrap_or(20).clamp(1, 200);
 
-    let rows = kon_storage::list_transcripts(pool, limit)
+    let rows = lumotia_storage::list_transcripts(pool, limit)
         .await
         .map_err(|e| error(-32603, format!("DB error: {e}")))?;
 
@@ -226,7 +226,9 @@ async fn list_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value,
         })
         .collect();
 
-    Ok(text_content(serde_json::to_string_pretty(&summaries).unwrap()))
+    Ok(text_content(
+        serde_json::to_string_pretty(&summaries).unwrap(),
+    ))
 }
 
 async fn get_transcript_tool(pool: &SqlitePool, args: Value) -> Result<Value, JsonRpcError> {
@@ -237,7 +239,7 @@ async fn get_transcript_tool(pool: &SqlitePool, args: Value) -> Result<Value, Js
     let args: Args = serde_json::from_value(args)
         .map_err(|e| error(-32602, format!("Invalid arguments: {e}")))?;
 
-    let row = kon_storage::get_transcript(pool, &args.id)
+    let row = lumotia_storage::get_transcript(pool, &args.id)
         .await
         .map_err(|e| error(-32603, format!("DB error: {e}")))?
         .ok_or_else(|| error(-32000, format!("Transcript {} not found", args.id)))?;
@@ -271,7 +273,7 @@ async fn search_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value
         .map_err(|e| error(-32602, format!("Invalid arguments: {e}")))?;
     let limit = args.limit.unwrap_or(20).clamp(1, 100);
 
-    let rows = kon_storage::search_transcripts(pool, &args.query, limit)
+    let rows = lumotia_storage::search_transcripts(pool, &args.query, limit)
         .await
         .map_err(|e| error(-32603, format!("DB error: {e}")))?;
 
@@ -288,11 +290,13 @@ async fn search_transcripts_tool(pool: &SqlitePool, args: Value) -> Result<Value
         })
         .collect();
 
-    Ok(text_content(serde_json::to_string_pretty(&summaries).unwrap()))
+    Ok(text_content(
+        serde_json::to_string_pretty(&summaries).unwrap(),
+    ))
 }
 
 async fn list_tasks_tool(pool: &SqlitePool) -> Result<Value, JsonRpcError> {
-    let rows = kon_storage::list_tasks(pool)
+    let rows = lumotia_storage::list_tasks(pool)
         .await
         .map_err(|e| error(-32603, format!("DB error: {e}")))?;
 
@@ -311,7 +315,9 @@ async fn list_tasks_tool(pool: &SqlitePool) -> Result<Value, JsonRpcError> {
         })
         .collect();
 
-    Ok(text_content(serde_json::to_string_pretty(&summaries).unwrap()))
+    Ok(text_content(
+        serde_json::to_string_pretty(&summaries).unwrap(),
+    ))
 }
 
 fn text_content(text: String) -> Value {
@@ -404,7 +410,10 @@ mod tests {
         let pool = sqlx::SqlitePool::connect("sqlite::memory:").await.unwrap();
         let response = handle_message(&pool, request).await.expect("has response");
 
-        let tools = response.result.expect("ok")["tools"].as_array().unwrap().clone();
+        let tools = response.result.expect("ok")["tools"]
+            .as_array()
+            .unwrap()
+            .clone();
         let names: Vec<String> = tools
             .iter()
             .map(|tool| tool["name"].as_str().unwrap().to_string())
@@ -426,7 +435,9 @@ mod tests {
         assert_eq!(resp.jsonrpc, "2.0");
         assert_eq!(resp.id, Value::Null);
         assert!(resp.result.is_none());
-        let err = resp.error.expect("parse_error_response must carry an error");
+        let err = resp
+            .error
+            .expect("parse_error_response must carry an error");
         assert_eq!(err.code, -32700);
         assert!(err.message.contains("Parse error"));
         assert!(err.message.contains("expected value"));
@@ -449,7 +460,9 @@ mod tests {
         });
 
         let pool = sqlx::SqlitePool::connect("sqlite::memory:").await.unwrap();
-        kon_storage::migrations::run_migrations(&pool).await.unwrap();
+        lumotia_storage::migrations::run_migrations(&pool)
+            .await
+            .unwrap();
         let response = handle_message(&pool, request).await.expect("has response");
 
         assert!(

crates/mcp/src/main.rs

@@ -1,18 +1,22 @@
-//! Stdio entry point for kon-mcp. Reads newline-delimited JSON-RPC messages
-//! from stdin, dispatches via `kon_mcp::handle_message`, writes responses to
+//! Stdio entry point for lumotia-mcp. Reads newline-delimited JSON-RPC messages
+//! from stdin, dispatches via `lumotia_mcp::handle_message`, writes responses to
 //! stdout. Logs land on stderr so they don't collide with the JSON-RPC stream.
 
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 
 #[tokio::main(flavor = "current_thread")]
 async fn main() -> anyhow::Result<()> {
-    let db_path = kon_storage::database_path();
+    let db_path = lumotia_storage::database_path();
     eprintln!(
-        "[kon-mcp] opening Kon database at {}",
+        "[lumotia-mcp] opening Lumotia database at {} (read-only)",
         db_path.display()
     );
-    let pool = kon_storage::init(&db_path).await?;
-    eprintln!("[kon-mcp] ready, waiting for JSON-RPC on stdin");
+    // Open read-only at the connection level so the MCP server cannot write
+    // to the user's database, regardless of which tools the dispatcher
+    // exposes. Migrations are deliberately skipped — this binary never owns
+    // the schema; the main app is the single migration writer.
+    let pool = lumotia_storage::init_readonly(&db_path).await?;
+    eprintln!("[lumotia-mcp] ready, waiting for JSON-RPC on stdin");
 
     let mut lines = BufReader::new(tokio::io::stdin()).lines();
     let mut stdout = tokio::io::stdout();
@@ -24,7 +28,7 @@ async fn main() -> anyhow::Result<()> {
         }
 
         let response = match serde_json::from_str::<serde_json::Value>(trimmed) {
-            Ok(raw) => match kon_mcp::handle_message(&pool, raw).await {
+            Ok(raw) => match lumotia_mcp::handle_message(&pool, raw).await {
                 Some(response) => response,
                 None => continue, // notification — no reply
             },
@@ -34,8 +38,8 @@ async fn main() -> anyhow::Result<()> {
                 // logged and continued, dropping the response —
                 // clients saw silence instead of a structured error
                 // (2026-04-22 review MAJOR).
-                eprintln!("[kon-mcp] parse error: {err}");
-                kon_mcp::parse_error_response(&err.to_string())
+                eprintln!("[lumotia-mcp] parse error: {err}");
+                lumotia_mcp::parse_error_response(&err.to_string())
             }
         };
 

crates/storage/Cargo.toml

@@ -1,11 +1,11 @@
 [package]
-name = "kon-storage"
+name = "lumotia-storage"
 version = "0.1.0"
 edition = "2021"
-description = "SQLite persistence, BM25 search, and file storage for Kon"
+description = "SQLite persistence, BM25 search, and file storage for Lumotia"
 
 [dependencies]
-kon-core = { path = "../core" }
+lumotia-core = { path = "../core" }
 
 # SQLite with compile-time checked queries
 # default-features = false strips sqlx's `any`, `macros`, `migrate`, `json` —
@@ -18,8 +18,14 @@ sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio",
 # Async runtime
 tokio = { version = "1", features = ["rt", "sync", "macros"] }
 
+# Serialisation (DailyCompletionCount exposed to frontend via Tauri commands)
+serde = { version = "1", features = ["derive"] }
+
 # Logging
 log = "0.4"
 
+# Structured error derivation for lumotia_storage::Error.
+thiserror = "1"
+
 # UUIDs for profile + profile_terms ids (v7 random).
 uuid = { version = "1", features = ["v4"] }

crates/storage/src/error.rs

@@ -0,0 +1,194 @@
+//! Storage-local typed error.
+//!
+//! Backend code that wants to branch on storage failure modes pattern-matches
+//! on [`Error`] directly. The crate boundary into [`lumotia_core::error::Error`]
+//! flattens this into a [`Error::Storage`] variant carrying a serde-friendly
+//! `kind`, an `operation` label, and the Display output as `detail` — so the
+//! frontend (which still receives stringified errors from Tauri commands today)
+//! keeps working, and Area E can later expose the typed `kind` to the FE without
+//! touching call sites.
+//!
+//! The `sqlx::Error` source is deliberately not serialized. Sources stay sources;
+//! only the boundary shape is wire-friendly.
+
+use std::borrow::Cow;
+use std::path::PathBuf;
+
+use lumotia_core::error::{Error as CoreError, StorageKind};
+
+/// Kinds of database-open operation that can fail before the pool is ready.
+#[derive(Debug, Clone, Copy)]
+pub enum OpenOp {
+    Connect,
+    ReadOnlyConnect,
+    ForeignKeysPragma,
+}
+
+impl OpenOp {
+    fn label(self) -> &'static str {
+        match self {
+            OpenOp::Connect => "connect",
+            OpenOp::ReadOnlyConnect => "read_only_connect",
+            OpenOp::ForeignKeysPragma => "foreign_keys_pragma",
+        }
+    }
+}
+
+impl std::fmt::Display for OpenOp {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.label())
+    }
+}
+
+/// Per-step phase inside the migration framework.
+#[derive(Debug, Clone, Copy)]
+pub enum MigrationStep {
+    SchemaVersionTableCreate,
+    SchemaVersionQuery,
+    TxBegin,
+    Apply,
+    RecordVersion,
+    Commit,
+}
+
+impl MigrationStep {
+    fn label(self) -> &'static str {
+        match self {
+            MigrationStep::SchemaVersionTableCreate => "schema_version_table_create",
+            MigrationStep::SchemaVersionQuery => "schema_version_query",
+            MigrationStep::TxBegin => "tx_begin",
+            MigrationStep::Apply => "apply",
+            MigrationStep::RecordVersion => "record_version",
+            MigrationStep::Commit => "commit",
+        }
+    }
+}
+
+impl std::fmt::Display for MigrationStep {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.label())
+    }
+}
+
+/// Entities the storage layer can fail to find or validate.
+///
+/// Seeded with only the three real entities (Transcript, Task, Profile) — add
+/// more here only when a typed `NotFound` / `InvalidReference` case actually
+/// requires them.
+#[derive(Debug, Clone, Copy)]
+pub enum Entity {
+    Transcript,
+    Task,
+    Profile,
+    ImplementationRule,
+    Feedback,
+}
+
+impl Entity {
+    fn label(self) -> &'static str {
+        match self {
+            Entity::Transcript => "transcript",
+            Entity::Task => "task",
+            Entity::Profile => "profile",
+            Entity::ImplementationRule => "implementation_rule",
+            Entity::Feedback => "feedback",
+        }
+    }
+}
+
+impl std::fmt::Display for Entity {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(self.label())
+    }
+}
+
+/// Storage-crate-local typed error.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("database open failed during {operation}: {source}")]
+    DatabaseOpen {
+        operation: OpenOp,
+        #[source]
+        source: sqlx::Error,
+    },
+
+    #[error("migration step {step} (version {version:?}) failed: {source}")]
+    Migration {
+        version: Option<i64>,
+        step: MigrationStep,
+        #[source]
+        source: sqlx::Error,
+    },
+
+    #[error("query failed during {operation}: {source}")]
+    Query {
+        operation: Cow<'static, str>,
+        #[source]
+        source: sqlx::Error,
+    },
+
+    #[error("{entity} not found: '{key}'")]
+    NotFound { entity: Entity, key: String },
+
+    #[error("invalid {entity} reference: {reason}")]
+    InvalidReference {
+        entity: Entity,
+        reason: Cow<'static, str>,
+    },
+
+    #[error("filesystem operation failed at '{}': {source}", path.display())]
+    Filesystem {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+}
+
+impl Error {
+    /// Discriminator for the boundary conversion into [`Error`].
+    pub fn kind(&self) -> StorageKind {
+        match self {
+            Error::DatabaseOpen { .. } => StorageKind::DatabaseOpen,
+            Error::Migration { .. } => StorageKind::Migration,
+            Error::Query { .. } => StorageKind::Query,
+            Error::NotFound { .. } => StorageKind::NotFound,
+            Error::InvalidReference { .. } => StorageKind::InvalidReference,
+            Error::Filesystem { .. } => StorageKind::Filesystem,
+        }
+    }
+
+    /// Operation label that flows into the [`Error::Storage`] boundary
+    /// shape. For per-query failures this is the caller-provided label;
+    /// for the other variants it's the variant's intrinsic label.
+    pub fn operation_label(&self) -> Cow<'static, str> {
+        match self {
+            Error::DatabaseOpen { operation, .. } => Cow::Borrowed(operation.label()),
+            Error::Migration { step, .. } => Cow::Borrowed(step.label()),
+            Error::Query { operation, .. } => operation.clone(),
+            Error::NotFound { entity, .. } => Cow::Owned(format!("not_found:{}", entity.label())),
+            Error::InvalidReference { entity, .. } => {
+                Cow::Owned(format!("invalid_reference:{}", entity.label()))
+            }
+            Error::Filesystem { .. } => Cow::Borrowed("filesystem"),
+        }
+    }
+}
+
+/// Boundary conversion — flattens the typed error into the wire-friendly
+/// [`CoreError::Storage`] variant. Lives in the storage crate (not in core)
+/// to avoid a `core -> storage` dependency cycle.
+impl From<Error> for CoreError {
+    fn from(error: Error) -> Self {
+        let kind = error.kind();
+        let operation = error.operation_label().into_owned();
+        let detail = error.to_string();
+        CoreError::Storage {
+            kind,
+            operation,
+            detail,
+        }
+    }
+}
+
+/// `Result` alias for storage-crate functions.
+pub type Result<T> = std::result::Result<T, Error>;

crates/storage/src/file_storage.rs

@@ -1,79 +1,28 @@
 use std::path::PathBuf;
 
-/// Resolve the per-user app data directory, following each OS's convention:
-///
-/// - Windows: `%LOCALAPPDATA%\kon\`           e.g. `C:\Users\Jake\AppData\Local\kon`
-/// - macOS:   `~/Library/Application Support/Kon/`
-/// - Linux:   `$XDG_DATA_HOME/kon` or `~/.local/share/kon` (XDG Base Directory),
-///            with a fallback to the legacy `~/.kon/` if it already exists, so
-///            existing installs keep working.
-/// - Other Unix: `~/.kon/`
-///
-/// TODO: Consolidate with `crates/transcription/src/model_manager.rs::dirs_path()`
-/// into a shared helper in `crates/core/` to avoid duplicating platform-specific
-/// path logic across crates.
 pub fn app_data_dir() -> PathBuf {
-    #[cfg(target_os = "windows")]
-    {
-        let local_app_data = std::env::var("LOCALAPPDATA").unwrap_or_else(|_| ".".to_string());
-        return PathBuf::from(local_app_data).join("kon");
-    }
-
-    #[cfg(target_os = "macos")]
-    {
-        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
-        return PathBuf::from(home)
-            .join("Library")
-            .join("Application Support")
-            .join("Kon");
-    }
-
-    #[cfg(target_os = "linux")]
-    {
-        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
-
-        // Honour the legacy ~/.kon/ if it exists on disk so existing
-        // installs are not orphaned. New installs follow XDG.
-        let legacy = PathBuf::from(&home).join(".kon");
-        if legacy.exists() {
-            return legacy;
-        }
-
-        // XDG Base Directory: $XDG_DATA_HOME/kon or default ~/.local/share/kon
-        if let Ok(xdg) = std::env::var("XDG_DATA_HOME") {
-            if !xdg.is_empty() {
-                return PathBuf::from(xdg).join("kon");
-            }
-        }
-        return PathBuf::from(home).join(".local").join("share").join("kon");
-    }
-
-    #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
-    {
-        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
-        PathBuf::from(home).join(".kon")
-    }
+    lumotia_core::paths::app_paths().app_data_dir()
 }
 
 /// Path to the SQLite database file.
 pub fn database_path() -> PathBuf {
-    app_data_dir().join("kon.db")
+    lumotia_core::paths::app_paths().database_path()
 }
 
 /// Directory for saved audio recordings.
 pub fn recordings_dir() -> PathBuf {
-    app_data_dir().join("recordings")
+    lumotia_core::paths::app_paths().recordings_dir()
 }
 
 /// Directory for crash dumps written by the Rust panic hook.
 /// Each crash is a single text file: `<unix-ts>-<short-id>.crash`.
 /// Used by the diagnostic-report bundler in Settings → About.
 pub fn crashes_dir() -> PathBuf {
-    app_data_dir().join("crashes")
+    lumotia_core::paths::app_paths().crashes_dir()
 }
 
-/// Directory for the rolling Rust log file (kon.log + rotated kon.log.1, etc).
+/// Directory for the rolling Rust log file (lumotia.log + rotated lumotia.log.1, etc).
 /// Subscribers configured in src-tauri/src/lib.rs at startup.
 pub fn logs_dir() -> PathBuf {
-    app_data_dir().join("logs")
+    lumotia_core::paths::app_paths().logs_dir()
 }

crates/storage/src/lib.rs

@@ -1,19 +1,27 @@
 pub mod database;
+pub mod error;
 pub mod file_storage;
 pub mod migrations;
 
+pub use error::{Entity, Error, MigrationStep, OpenOp, Result};
+
 /// Stable identifier for the seeded Default profile (see migration v6).
 /// The Default profile cannot be renamed or deleted — guarded by SQLite triggers.
 pub const DEFAULT_PROFILE_ID: &str = "00000000-0000-0000-0000-000000000001";
 
 pub use database::{
     add_profile_term, complete_subtask_and_check_parent, complete_task, count_transcripts,
-    create_profile, delete_profile, delete_profile_term, delete_task, delete_transcript,
-    get_profile, get_setting, get_task_by_id, get_transcript, init, insert_subtask, insert_task,
-    insert_transcript, list_profile_terms, list_profiles, list_recent_errors, list_subtasks,
-    list_tasks, list_transcripts, list_transcripts_paged, log_error, search_transcripts,
-    set_setting, uncomplete_task, update_profile, update_task, update_transcript,
-    update_transcript_meta, ErrorLogRow, InsertTranscriptParams, ProfileRow, ProfileTermRow,
-    TaskRow, TranscriptRow,
+    create_profile, delete_implementation_rule, delete_profile, delete_profile_term, delete_task,
+    delete_transcript, get_implementation_rule, get_profile, get_setting, get_task_by_id,
+    get_transcript, init, init_readonly, insert_implementation_rule, insert_subtask, insert_task,
+    insert_transcript, list_feedback_examples, list_implementation_rules, list_profile_terms,
+    list_profiles, list_recent_completions, list_recent_errors, list_subtasks, list_tasks,
+    list_transcripts, list_transcripts_paged, log_error, mark_implementation_rule_fired,
+    migrate_legacy_setting_keys, prune_error_log, record_feedback, search_transcripts,
+    set_implementation_rule_enabled, set_setting, set_task_energy, uncomplete_task, update_profile,
+    update_task, update_transcript,
+    update_transcript_meta, DailyCompletionCount, ErrorLogRow, FeedbackRow, FeedbackTargetType,
+    ImplementationRuleRow, InsertTranscriptParams, ProfileRow, ProfileTermRow,
+    RecordFeedbackParams, TaskRow, TranscriptRow,
 };
 pub use file_storage::{app_data_dir, crashes_dir, database_path, logs_dir, recordings_dir};

crates/storage/src/migrations.rs

@@ -1,4 +1,4 @@
-use kon_core::error::{KonError, Result};
+use crate::error::{Error, MigrationStep, Result};
 use sqlx::SqlitePool;
 
 /// Each migration is a (version, description, sql) tuple.
@@ -215,6 +215,268 @@ const MIGRATIONS: &[(i64, &str, &str)] = &[
             ON transcripts(profile_id);
         "#,
     ),
+    (
+        9,
+        "transcript_profile_fk",
+        r#"
+        INSERT OR IGNORE INTO profiles (id, name, initial_prompt, created_at)
+        VALUES ('00000000-0000-0000-0000-000000000001', 'Default', '', datetime('now'));
+
+        DROP TRIGGER IF EXISTS transcripts_ai;
+        DROP TRIGGER IF EXISTS transcripts_ad;
+        DROP TRIGGER IF EXISTS transcripts_au;
+        DROP TABLE IF EXISTS transcripts_fts;
+        DROP INDEX IF EXISTS idx_segments_transcript;
+        DROP INDEX IF EXISTS idx_transcripts_created;
+        DROP INDEX IF EXISTS idx_transcripts_profile_id;
+
+        ALTER TABLE segments RENAME TO segments_old;
+        ALTER TABLE transcripts RENAME TO transcripts_old;
+
+        CREATE TABLE transcripts (
+            id TEXT PRIMARY KEY,
+            text TEXT NOT NULL DEFAULT '',
+            source TEXT NOT NULL DEFAULT 'microphone',
+            title TEXT,
+            audio_path TEXT,
+            duration REAL NOT NULL DEFAULT 0.0,
+            engine TEXT,
+            model_id TEXT,
+            inference_ms INTEGER,
+            sample_rate INTEGER,
+            audio_channels INTEGER,
+            format_mode TEXT,
+            remove_fillers INTEGER NOT NULL DEFAULT 0,
+            british_english INTEGER NOT NULL DEFAULT 0,
+            anti_hallucination INTEGER NOT NULL DEFAULT 0,
+            created_at TEXT NOT NULL DEFAULT (datetime('now')),
+            starred INTEGER NOT NULL DEFAULT 0,
+            manual_tags TEXT NOT NULL DEFAULT '',
+            template TEXT NOT NULL DEFAULT '',
+            language TEXT NOT NULL DEFAULT '',
+            segments_json TEXT NOT NULL DEFAULT '',
+            profile_id TEXT NOT NULL DEFAULT '00000000-0000-0000-0000-000000000001'
+                REFERENCES profiles(id) ON DELETE RESTRICT
+        );
+
+        CREATE INDEX idx_transcripts_created
+            ON transcripts(created_at);
+        CREATE INDEX idx_transcripts_profile_id
+            ON transcripts(profile_id);
+
+        INSERT INTO transcripts (
+            id, text, source, title, audio_path, duration, engine, model_id,
+            inference_ms, sample_rate, audio_channels, format_mode,
+            remove_fillers, british_english, anti_hallucination, created_at,
+            starred, manual_tags, template, language, segments_json, profile_id
+        )
+        SELECT
+            id, text, source, title, audio_path, duration, engine, model_id,
+            inference_ms, sample_rate, audio_channels, format_mode,
+            remove_fillers, british_english, anti_hallucination, created_at,
+            starred, manual_tags, template, language, segments_json,
+            CASE
+                WHEN profile_id IS NOT NULL
+                 AND EXISTS (
+                    SELECT 1 FROM profiles
+                    WHERE id = transcripts_old.profile_id
+                 )
+                    THEN profile_id
+                ELSE '00000000-0000-0000-0000-000000000001'
+            END
+        FROM transcripts_old;
+
+        CREATE TABLE segments (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            transcript_id TEXT NOT NULL REFERENCES transcripts(id) ON DELETE CASCADE,
+            start_time REAL NOT NULL,
+            end_time REAL NOT NULL,
+            text TEXT NOT NULL DEFAULT ''
+        );
+
+        CREATE INDEX idx_segments_transcript
+            ON segments(transcript_id);
+
+        INSERT INTO segments (id, transcript_id, start_time, end_time, text)
+        SELECT id, transcript_id, start_time, end_time, text
+        FROM segments_old;
+
+        DROP TABLE segments_old;
+        DROP TABLE transcripts_old;
+
+        CREATE VIRTUAL TABLE transcripts_fts USING fts5(
+            text,
+            title,
+            content='transcripts',
+            content_rowid='rowid',
+            tokenize='porter unicode61 remove_diacritics 2'
+        );
+
+        CREATE TRIGGER transcripts_ai AFTER INSERT ON transcripts BEGIN
+            INSERT INTO transcripts_fts(rowid, text, title)
+            VALUES (new.rowid, new.text, COALESCE(new.title, ''));
+        END;
+
+        CREATE TRIGGER transcripts_ad AFTER DELETE ON transcripts BEGIN
+            INSERT INTO transcripts_fts(transcripts_fts, rowid, text, title)
+            VALUES ('delete', old.rowid, old.text, COALESCE(old.title, ''));
+        END;
+
+        CREATE TRIGGER transcripts_au AFTER UPDATE ON transcripts BEGIN
+            INSERT INTO transcripts_fts(transcripts_fts, rowid, text, title)
+            VALUES ('delete', old.rowid, old.text, COALESCE(old.title, ''));
+            INSERT INTO transcripts_fts(rowid, text, title)
+            VALUES (new.rowid, new.text, COALESCE(new.title, ''));
+        END;
+
+        INSERT INTO transcripts_fts(rowid, text, title)
+        SELECT rowid, text, COALESCE(title, '')
+        FROM transcripts;
+        "#,
+    ),
+    (
+        10,
+        "feedback: HITL thumbs + correction capture",
+        r#"
+        -- Feedback rows capture human-in-the-loop signal on AI-generated
+        -- output. Two flavours bundled into one table:
+        --   - thumbs (rating = -1 | +1, original_text optional, corrected_text NULL)
+        --   - correction (rating defaults to +1, original_text + corrected_text present)
+        --
+        -- `target_type` names the producing surface:
+        --   'microstep'  — subtask decomposition from DECOMPOSE_TASK_SYSTEM
+        --   'task_extraction' — tasks lifted from a transcript (EXTRACT_TASKS_SYSTEM)
+        --   'cleanup'    — transcript cleanup output
+        --
+        -- `target_id` is the surface-specific identifier where one exists
+        -- (subtask id, task id, transcript id). NULL is allowed because
+        -- not every feedback event has a stable target id yet.
+        --
+        -- `context_json` carries the input the AI was conditioned on
+        -- (parent task text, transcript chunk, etc.) so future prompt
+        -- builders can reconstruct the original I/O pair for few-shot
+        -- injection or semantic retrieval.
+        CREATE TABLE feedback (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            target_type TEXT NOT NULL
+                CHECK (target_type IN ('microstep', 'task_extraction', 'cleanup')),
+            target_id TEXT,
+            rating INTEGER NOT NULL
+                CHECK (rating IN (-1, 0, 1)),
+            original_text TEXT,
+            corrected_text TEXT,
+            context_json TEXT,
+            profile_id TEXT NOT NULL DEFAULT '00000000-0000-0000-0000-000000000001'
+                REFERENCES profiles(id) ON DELETE RESTRICT,
+            created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX idx_feedback_target_type_rating
+            ON feedback(target_type, rating, created_at DESC);
+        CREATE INDEX idx_feedback_profile
+            ON feedback(profile_id, target_type, created_at DESC);
+        "#,
+    ),
+    (
+        11,
+        "tasks: energy tagging for match-my-energy sort",
+        r#"
+        -- Phase 3 of the feature-complete roadmap: replaces the cut
+        -- temptation-bundling feature with a deterministic client-side
+        -- sort that matches tasks to the user's current energy state.
+        -- NULL is the expected normal case — users who never tag get
+        -- Medium-equivalent treatment at sort time (see Match-my-energy
+        -- logic in src/lib/pages/TasksPage.svelte).
+        --
+        -- profile_id is deliberately absent from the index: tasks
+        -- currently carry no profile_id column, so a per-profile index
+        -- is out of scope until the broader task → profile migration
+        -- lands. See HANDOVER deferred list.
+        ALTER TABLE tasks
+            ADD COLUMN energy TEXT
+            CHECK (energy IS NULL OR energy IN ('high', 'medium', 'brain_dead'));
+
+        CREATE INDEX idx_tasks_energy_created
+            ON tasks(energy, created_at DESC);
+        "#,
+    ),
+    (
+        12,
+        "implementation intentions: if-then automation rules",
+        r#"
+        -- Phase 7 of the feature-complete roadmap. Rules are local-only,
+        -- user-authored implementation intentions: "if this happens, then
+        -- do this small thing". Execution stays in the frontend event bus;
+        -- SQLite owns the durable definition and the once-per-day marker
+        -- for time-of-day rules.
+        CREATE TABLE implementation_rules (
+            id TEXT PRIMARY KEY,
+            enabled INTEGER NOT NULL DEFAULT 1
+                CHECK (enabled IN (0, 1)),
+            trigger_kind TEXT NOT NULL
+                CHECK (trigger_kind IN (
+                    'time_of_day',
+                    'task_completed',
+                    'morning_triage_finished'
+                )),
+            trigger_value TEXT NOT NULL DEFAULT '',
+            actions_json TEXT NOT NULL DEFAULT '[]',
+            last_fired_key TEXT,
+            created_at TEXT NOT NULL DEFAULT (datetime('now')),
+            updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX idx_implementation_rules_enabled_trigger
+            ON implementation_rules(enabled, trigger_kind);
+        "#,
+    ),
+    (
+        13,
+        "gamification: auto_completed flag for cascade-completed parents",
+        r#"
+        -- Phase 8 of the feature-complete roadmap. Parents that close via
+        -- the complete_subtask_and_check_parent cascade must not count
+        -- towards daily completion totals. The user already got credit
+        -- for ticking the subtask. This column distinguishes manual
+        -- completions (0) from cascade completions (1). The daily-count
+        -- query then excludes auto_completed = 1.
+        --
+        -- Partial index keeps the index small: only completed rows occupy
+        -- it, since uncompleted rows have done_at IS NULL.
+        ALTER TABLE tasks ADD COLUMN auto_completed INTEGER NOT NULL DEFAULT 0
+            CHECK (auto_completed IN (0, 1));
+
+        CREATE INDEX idx_tasks_done_at_auto_completed
+            ON tasks(done_at, auto_completed)
+            WHERE done_at IS NOT NULL;
+        "#,
+    ),
+    (
+        14,
+        "transcripts: llm_tags column for Phase 9 LLM content tags",
+        r#"
+        -- Phase 9 of the feature-complete roadmap. AI-generated content
+        -- tags (topic:* and intent:*) are stored alongside manual_tags as
+        -- a comma-joined string, mirroring how manual_tags persists. Pre-
+        -- existing rows default to empty string. The frontend chips loop
+        -- handles "" as "no tags".
+        ALTER TABLE transcripts ADD COLUMN llm_tags TEXT NOT NULL DEFAULT '';
+        "#,
+    ),
+    (
+        15,
+        "transcripts: composite (profile_id, created_at DESC) index",
+        r#"
+        -- Performance index for the dominant transcripts query path:
+        --   WHERE profile_id = ? ORDER BY created_at DESC LIMIT ?
+        -- The standalone idx_transcripts_profile_id and idx_transcripts_created
+        -- forced SQLite to either filter by profile then sort, or scan the date
+        -- index and filter — fine at hundreds of rows, painful past a few thousand.
+        -- A composite index covers both predicates in one ordered seek.
+        CREATE INDEX IF NOT EXISTS idx_transcripts_profile_created
+            ON transcripts(profile_id, created_at DESC);
+        "#,
+    ),
 ];
 
 /// Split SQL into individual statements, respecting BEGIN...END trigger blocks.
@@ -281,10 +543,7 @@ pub async fn run_migrations(pool: &SqlitePool) -> Result<()> {
 /// implicitly commits (`VACUUM`, `REINDEX`, `ATTACH`), it must be split
 /// out into its own non-transactional migration — reviewer's job to
 /// flag.
-async fn run_migrations_slice(
-    pool: &SqlitePool,
-    migrations: &[(i64, &str, &str)],
-) -> Result<()> {
+async fn run_migrations_slice(pool: &SqlitePool, migrations: &[(i64, &str, &str)]) -> Result<()> {
     sqlx::query(
         "CREATE TABLE IF NOT EXISTS schema_version (
             version INTEGER PRIMARY KEY,
@@ -294,27 +553,39 @@ async fn run_migrations_slice(
     )
     .execute(pool)
     .await
-    .map_err(|e| KonError::StorageError(format!("Schema version table creation failed: {e}")))?;
+    .map_err(|source| Error::Migration {
+        version: None,
+        step: MigrationStep::SchemaVersionTableCreate,
+        source,
+    })?;
 
     let current: i64 = sqlx::query_scalar("SELECT COALESCE(MAX(version), 0) FROM schema_version")
         .fetch_one(pool)
         .await
-        .map_err(|e| KonError::StorageError(format!("Schema version query failed: {e}")))?;
+        .map_err(|source| Error::Migration {
+            version: None,
+            step: MigrationStep::SchemaVersionQuery,
+            source,
+        })?;
 
     for (version, description, sql) in migrations {
         if *version > current {
             log::info!("Running migration {}: {}", version, description);
 
-            let mut tx = pool.begin().await.map_err(|e| {
-                KonError::StorageError(format!("Migration {} tx begin failed: {e}", version))
+            let mut tx = pool.begin().await.map_err(|source| Error::Migration {
+                version: Some(*version),
+                step: MigrationStep::TxBegin,
+                source,
             })?;
 
             for statement in split_statements(sql) {
                 sqlx::query(&statement)
                     .execute(&mut *tx)
                     .await
-                    .map_err(|e| {
-                        KonError::StorageError(format!("Migration {} failed: {e}", version))
+                    .map_err(|source| Error::Migration {
+                        version: Some(*version),
+                        step: MigrationStep::Apply,
+                        source,
                     })?;
             }
 
@@ -323,12 +594,16 @@ async fn run_migrations_slice(
                 .bind(description)
                 .execute(&mut *tx)
                 .await
-                .map_err(|e| {
-                    KonError::StorageError(format!("Migration version record failed: {e}"))
+                .map_err(|source| Error::Migration {
+                    version: Some(*version),
+                    step: MigrationStep::RecordVersion,
+                    source,
                 })?;
 
-            tx.commit().await.map_err(|e| {
-                KonError::StorageError(format!("Migration {} commit failed: {e}", version))
+            tx.commit().await.map_err(|source| Error::Migration {
+                version: Some(*version),
+                step: MigrationStep::Commit,
+                source,
             })?;
 
             log::info!("Migration {} complete", version);
@@ -344,12 +619,22 @@ mod tests {
     use sqlx::sqlite::SqlitePoolOptions;
     use sqlx::Row;
 
-    #[tokio::test]
-    async fn test_migrations_run_on_empty_db() {
+    async fn fk_test_pool() -> SqlitePool {
         let pool = SqlitePoolOptions::new()
+            .max_connections(1)
             .connect("sqlite::memory:")
             .await
-            .unwrap();
+            .expect("pool");
+        sqlx::query("PRAGMA foreign_keys = ON")
+            .execute(&pool)
+            .await
+            .expect("enable foreign keys");
+        pool
+    }
+
+    #[tokio::test]
+    async fn test_migrations_run_on_empty_db() {
+        let pool = fk_test_pool().await;
 
         run_migrations(&pool).await.unwrap();
 
@@ -357,7 +642,7 @@ mod tests {
             .fetch_one(&pool)
             .await
             .unwrap();
-        assert_eq!(count, 8);
+        assert_eq!(count, 15);
 
         sqlx::query("INSERT INTO settings (key, value) VALUES ('test', 'value')")
             .execute(&pool)
@@ -367,10 +652,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_migrations_idempotent() {
-        let pool = SqlitePoolOptions::new()
-            .connect("sqlite::memory:")
-            .await
-            .unwrap();
+        let pool = fk_test_pool().await;
 
         run_migrations(&pool).await.unwrap();
         run_migrations(&pool).await.unwrap();
@@ -379,7 +661,7 @@ mod tests {
             .fetch_one(&pool)
             .await
             .unwrap();
-        assert_eq!(count, 8);
+        assert_eq!(count, 15);
     }
 
     #[tokio::test]
@@ -407,6 +689,44 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn migration_implementation_rules_adds_rule_table() {
+        let pool = fk_test_pool().await;
+        run_migrations(&pool).await.expect("migrate");
+
+        let info = sqlx::query("PRAGMA table_info(implementation_rules)")
+            .fetch_all(&pool)
+            .await
+            .unwrap();
+        let names: Vec<String> = info.iter().map(|r| r.get::<String, _>("name")).collect();
+        for col in [
+            "id",
+            "enabled",
+            "trigger_kind",
+            "trigger_value",
+            "actions_json",
+            "last_fired_key",
+            "created_at",
+            "updated_at",
+        ] {
+            assert!(
+                names.contains(&col.to_string()),
+                "implementation_rules must have {col}; got {names:?}"
+            );
+        }
+
+        let rejected = sqlx::query(
+            "INSERT INTO implementation_rules (id, trigger_kind, actions_json)
+             VALUES ('bad', 'calendar_event', '[]')",
+        )
+        .execute(&pool)
+        .await;
+        assert!(
+            rejected.is_err(),
+            "trigger_kind CHECK constraint must reject unknown triggers"
+        );
+    }
+
     #[tokio::test]
     async fn migration_transcripts_meta_adds_columns() {
         // Task 2.5 — verify starred / manual_tags / template / language /
@@ -440,11 +760,7 @@ mod tests {
 
     #[tokio::test]
     async fn migration_transcript_profile_provenance_adds_profile_id() {
-        let pool = SqlitePoolOptions::new()
-            .max_connections(1)
-            .connect("sqlite::memory:")
-            .await
-            .expect("pool");
+        let pool = fk_test_pool().await;
         run_migrations(&pool).await.expect("migrate");
 
         let info = sqlx::query("PRAGMA table_info(transcripts)")
@@ -459,11 +775,108 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn test_parent_task_id_cascade_delete() {
-        let pool = SqlitePoolOptions::new()
-            .connect("sqlite::memory:")
+    async fn migration_v9_reconciles_orphaned_transcript_profiles_and_adds_fk() {
+        let pool = fk_test_pool().await;
+        run_migrations_up_to(&pool, 8).await.expect("migrate to v8");
+
+        sqlx::query(
+            "INSERT INTO profiles (id, name, initial_prompt, created_at)
+             VALUES ('profile-valid', 'Valid', '', datetime('now'))",
+        )
+        .execute(&pool)
+        .await
+        .expect("seed valid profile");
+
+        sqlx::query(
+            "INSERT INTO transcripts (
+                id, text, source, title, audio_path, duration, engine, model_id,
+                inference_ms, sample_rate, audio_channels, format_mode,
+                remove_fillers, british_english, anti_hallucination, created_at,
+                starred, manual_tags, template, language, segments_json, profile_id
+            ) VALUES (
+                't-orphan', 'orphan body', 'microphone', 'Orphan', NULL, 0.0, NULL, NULL,
+                NULL, NULL, NULL, NULL, 0, 0, 0, datetime('now'),
+                0, '', '', '', '', 'profile-missing'
+            )",
+        )
+        .execute(&pool)
+        .await
+        .expect("seed orphan transcript");
+        sqlx::query(
+            "INSERT INTO transcripts (
+                id, text, source, title, audio_path, duration, engine, model_id,
+                inference_ms, sample_rate, audio_channels, format_mode,
+                remove_fillers, british_english, anti_hallucination, created_at,
+                starred, manual_tags, template, language, segments_json, profile_id
+            ) VALUES (
+                't-valid', 'valid body', 'microphone', 'Valid', NULL, 0.0, NULL, NULL,
+                NULL, NULL, NULL, NULL, 0, 0, 0, datetime('now'),
+                0, '', '', '', '', 'profile-valid'
+            )",
+        )
+        .execute(&pool)
+        .await
+        .expect("seed valid transcript");
+        sqlx::query(
+            "INSERT INTO segments (transcript_id, start_time, end_time, text)
+             VALUES ('t-orphan', 0.0, 1.0, 'segment')",
+        )
+        .execute(&pool)
+        .await
+        .expect("seed segment");
+
+        run_migrations(&pool).await.expect("migrate to v9");
+
+        let orphan_profile: String =
+            sqlx::query_scalar("SELECT profile_id FROM transcripts WHERE id = 't-orphan'")
+                .fetch_one(&pool)
+                .await
+                .expect("read healed orphan");
+        assert_eq!(orphan_profile, crate::DEFAULT_PROFILE_ID);
+
+        let valid_profile: String =
+            sqlx::query_scalar("SELECT profile_id FROM transcripts WHERE id = 't-valid'")
+                .fetch_one(&pool)
+                .await
+                .expect("read preserved profile");
+        assert_eq!(valid_profile, "profile-valid");
+
+        let segment_count: i64 =
+            sqlx::query_scalar("SELECT COUNT(*) FROM segments WHERE transcript_id = 't-orphan'")
+                .fetch_one(&pool)
+                .await
+                .expect("read migrated segments");
+        assert_eq!(segment_count, 1, "segments must survive transcript rebuild");
+
+        let fk_rows = sqlx::query("PRAGMA foreign_key_list(transcripts)")
+            .fetch_all(&pool)
             .await
-            .unwrap();
+            .expect("read transcript foreign keys");
+        assert!(
+            fk_rows.iter().any(|row| {
+                row.get::<String, _>("table") == "profiles"
+                    && row.get::<String, _>("from") == "profile_id"
+                    && row.get::<String, _>("to") == "id"
+                    && row.get::<String, _>("on_delete") == "RESTRICT"
+            }),
+            "transcripts.profile_id must reference profiles(id) with ON DELETE RESTRICT"
+        );
+
+        let fts_hits: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM transcripts_fts WHERE transcripts_fts MATCH 'orphan'",
+        )
+        .fetch_one(&pool)
+        .await
+        .expect("query rebuilt fts");
+        assert_eq!(
+            fts_hits, 1,
+            "fts index must be rebuilt for existing transcripts"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_parent_task_id_cascade_delete() {
+        let pool = fk_test_pool().await;
 
         run_migrations(&pool).await.unwrap();
 
@@ -550,7 +963,7 @@ mod tests {
         // dictionary.id is INTEGER PK AUTOINCREMENT (see v2); let SQLite assign rowids.
         sqlx::query(
             "INSERT INTO dictionary (term, note, created_at) VALUES \
-             ('Kon', '', datetime('now')), \
+             ('Lumotia', '', datetime('now')), \
              ('CORBEL', 'brand', datetime('now')), \
              ('Wren', '', datetime('now'))",
         )
@@ -643,8 +1056,11 @@ mod tests {
     // The poisoned migration below first creates `poison_marker`
     // (syntactically valid, would succeed against any SQLite) and then
     // runs a guaranteed-invalid function call. Under the new atomic
-    // implementation, neither `poison_marker` nor the v9 row should
+    // implementation, neither `poison_marker` nor the poison row should
     // survive the failed call.
+    //
+    // Version number must sit above the real MIGRATIONS max so the
+    // baseline migrate cleanly finishes first.
     #[tokio::test]
     async fn multi_statement_migration_rolls_back_on_failure() {
         let pool = SqlitePoolOptions::new()
@@ -655,8 +1071,18 @@ mod tests {
 
         run_migrations(&pool).await.expect("baseline migrate");
 
-        const POISON: &[(i64, &str, &str)] = &[(
-            9,
+        // Discover the real max version so the poison migration is
+        // always exactly one past the end of MIGRATIONS, regardless of
+        // how many real migrations we add in future.
+        let real_max: i64 =
+            sqlx::query_scalar("SELECT COALESCE(MAX(version), 0) FROM schema_version")
+                .fetch_one(&pool)
+                .await
+                .expect("read schema_version");
+        let poison_version = real_max + 1;
+
+        let poison: &[(i64, &str, &str)] = &[(
+            poison_version,
             "rb-02 atomicity poison",
             r#"
             CREATE TABLE poison_marker (id INTEGER PRIMARY KEY);
@@ -664,7 +1090,7 @@ mod tests {
             "#,
         )];
 
-        let result = run_migrations_slice(&pool, POISON).await;
+        let result = run_migrations_slice(&pool, poison).await;
         assert!(
             result.is_err(),
             "poisoned migration must return Err, got: {result:?}"
@@ -680,16 +1106,97 @@ mod tests {
             "poison_marker must not exist; got: {marker:?}"
         );
 
-        // `schema_version` must not include v9 — version insert is part
-        // of the same transaction that rolled back.
-        let max: i64 =
-            sqlx::query_scalar("SELECT COALESCE(MAX(version), 0) FROM schema_version")
-                .fetch_one(&pool)
-                .await
-                .expect("read schema_version");
+        // `schema_version` must not include the poison version — version
+        // insert is part of the same transaction that rolled back.
+        let max: i64 = sqlx::query_scalar("SELECT COALESCE(MAX(version), 0) FROM schema_version")
+            .fetch_one(&pool)
+            .await
+            .expect("read schema_version");
         assert_eq!(
-            max, 8,
+            max, real_max,
             "schema_version must not advance past the failed migration"
         );
     }
+
+    #[tokio::test]
+    async fn migration_v13_adds_auto_completed_column() {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .expect("pool");
+        run_migrations(&pool).await.expect("migrate");
+
+        // Column exists.
+        let info = sqlx::query("PRAGMA table_info(tasks)")
+            .fetch_all(&pool)
+            .await
+            .expect("pragma");
+        let names: Vec<String> = info.iter().map(|r| r.get::<String, _>("name")).collect();
+        assert!(
+            names.iter().any(|n| n == "auto_completed"),
+            "expected auto_completed column, got {names:?}"
+        );
+
+        // Existing completed rows default to 0. Insert a pre-existing-looking
+        // task via raw SQL to simulate a row from before the migration.
+        sqlx::query(
+            "INSERT INTO tasks (id, text, bucket, done, done_at) \
+             VALUES ('t1', 'pre-existing', 'inbox', 1, '2026-04-20 12:00:00')",
+        )
+        .execute(&pool)
+        .await
+        .expect("insert");
+
+        let auto: i64 = sqlx::query_scalar("SELECT auto_completed FROM tasks WHERE id = 't1'")
+            .fetch_one(&pool)
+            .await
+            .expect("query");
+        assert_eq!(auto, 0, "pre-existing completed rows must default to 0");
+    }
+
+    #[tokio::test]
+    async fn migration_v15_creates_profile_created_index() {
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .expect("pool");
+        run_migrations(&pool).await.expect("migrate");
+
+        // Index exists by name.
+        let names: Vec<String> = sqlx::query_scalar(
+            "SELECT name FROM sqlite_master \
+             WHERE type = 'index' AND tbl_name = 'transcripts'",
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("read indexes");
+        assert!(
+            names.iter().any(|n| n == "idx_transcripts_profile_created"),
+            "expected composite (profile_id, created_at) index, got {names:?}",
+        );
+
+        // Query planner picks the composite index for the dominant
+        // profile-scoped, date-ordered list query. EXPLAIN QUERY PLAN
+        // returns (id, parent, notused, detail) — we want detail.
+        let plan_rows = sqlx::query(
+            "EXPLAIN QUERY PLAN \
+             SELECT id FROM transcripts \
+             WHERE profile_id = ? ORDER BY created_at DESC LIMIT 50",
+        )
+        .bind(crate::DEFAULT_PROFILE_ID)
+        .fetch_all(&pool)
+        .await
+        .expect("explain");
+        let plan: Vec<String> = plan_rows
+            .iter()
+            .map(|r| r.get::<String, _>("detail"))
+            .collect();
+        assert!(
+            plan.iter()
+                .any(|row| row.contains("idx_transcripts_profile_created")),
+            "planner should use the composite index, got plan: {plan:?}",
+        );
+    }
 }

crates/transcription/Cargo.toml

@@ -1,21 +1,35 @@
 [package]
-name = "kon-transcription"
+name = "lumotia-transcription"
 version = "0.1.0"
 edition = "2021"
-description = "Speech-to-text engine wrappers, model management, and inference concurrency for Kon"
+description = "Speech-to-text engine wrappers, model management, and inference concurrency for Lumotia"
 build = "build.rs"
 
 [features]
-# Whisper backend (direct whisper-rs, vulkan-accelerated). Default on —
-# gating it exists so a future Windows non-AVX2 build, or a cloud-only
-# ASR configuration, can drop whisper-rs-sys entirely per brief item
-# #13. Disabling this feature also drops the WhisperRsBackend module
-# and the load_whisper entry point.
-default = ["whisper"]
-whisper = ["dep:whisper-rs", "dep:num_cpus"]
+# Whisper backend (direct whisper-rs). Default on — gating it exists so
+# a future Windows non-AVX2 build, or a cloud-only ASR configuration,
+# can drop whisper-rs-sys entirely per brief item #13. Disabling this
+# feature also drops the WhisperRsBackend module and the load_whisper
+# entry point.
+#
+# `whisper-vulkan` is a separate feature so a non-Vulkan target (Android
+# without GPU drivers, a CPU-only Windows build) can pull in whisper-rs
+# but skip the Vulkan backend. Build CPU-only with:
+#   cargo build -p lumotia-transcription --no-default-features --features whisper
+default = ["whisper", "whisper-vulkan"]
+whisper = ["dep:whisper-rs"]
+whisper-vulkan = ["whisper-rs?/vulkan"]
 
 [dependencies]
-kon-core = { path = "../core" }
+lumotia-core = { path = "../core" }
+
+# TranscriptionProvider async trait + EngineProfile + ProviderId. The
+# trait lives in cloud-providers so an OEM licensee can implement it
+# without depending on transcription internals.
+lumotia-cloud-providers = { path = "../cloud-providers" }
+
+# Async-trait for the LocalProviderAdapter impl.
+async-trait = "0.1"
 
 # Parakeet via ONNX. Whisper is handled directly via whisper-rs below.
 transcribe-rs = { version = "0.3", default-features = false, features = ["onnx"] }
@@ -24,18 +38,15 @@ transcribe-rs = { version = "0.3", default-features = false, features = ["onnx"]
 tokio = { version = "1", features = ["rt", "sync"] }
 
 # Model downloads
-reqwest = { version = "0.12", features = ["stream"] }
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] }
 futures-util = "0.3"
 
 # Download integrity verification
 sha2 = "0.10"
 
-# Gated behind the `whisper` feature (see [features] above).
-whisper-rs = { version = "0.16", default-features = false, features = ["vulkan"], optional = true }
-
-# Direct whisper-rs backend (WhisperRsBackend): thread pool sizing.
-# Gated alongside whisper-rs since no other code in this crate needs it.
-num_cpus = { version = "1", optional = true }
+# Gated behind the `whisper` feature (see [features] above). Vulkan is
+# additive via the `whisper-vulkan` feature so non-GPU targets can drop it.
+whisper-rs = { version = "0.16", default-features = false, optional = true }
 
 # Typed error enum used by WhisperRsBackend + elsewhere. Kept
 # unconditional because it is a derive-macro crate with negligible
@@ -46,6 +57,12 @@ thiserror = "2"
 tracing = "0.1"
 
 [dev-dependencies]
-# TcpListener fixture for the download resume tests (mirrors kon-llm).
-tokio = { version = "1", features = ["rt", "sync", "net", "io-util", "macros"] }
+# TcpListener fixture for the download resume tests (mirrors lumotia-llm).
+# `macros` and `rt-multi-thread` enable #[tokio::test] and the multi-threaded
+# scheduler used by the orchestrator tests.
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "net", "io-util", "macros"] }
 tempfile = "3"
+# Test-only — used by tests/thread_sweep.rs to label physical vs logical
+# core counts in the scaling table. Production code uses the
+# `lumotia_core::constants::inference_thread_count` helper instead.
+num_cpus = "1"

crates/transcription/build.rs

@@ -11,7 +11,7 @@
 //! workspace ever pulls `tokenizers` into the dependency graph on a
 //! Windows target. If we ever legitimately need it we can reintroduce
 //! it via a sidecar (isolated process, separate CRT) rather than
-//! linking it into `kon_lib`.
+//! linking it into `lumotia_lib`.
 //!
 //! The check is advisory on non-Windows targets — it still prints a
 //! cargo:warning if `tokenizers` appears, so the Windows failure isn't
@@ -56,7 +56,7 @@ fn main() {
 
     if target_os == "windows" {
         panic!(
-            "kon-transcription: the `tokenizers` crate appears in Cargo.lock and this is a \
+            "lumotia-transcription: the `tokenizers` crate appears in Cargo.lock and this is a \
              Windows build. Linking `whisper-rs-sys` + `tokenizers` in the same binary has \
              been a persistent MSVC C-runtime conflict (see Whispering v7.11.0). Route any \
              tokenizer usage through an out-of-process sidecar instead, or gate it off for \
@@ -65,7 +65,7 @@ fn main() {
     }
 
     println!(
-        "cargo:warning=kon-transcription: `tokenizers` crate is in the dependency graph. \
+        "cargo:warning=lumotia-transcription: `tokenizers` crate is in the dependency graph. \
          This build is non-Windows so the link will succeed, but Windows builds will panic \
          at build time per docs/whisper-ecosystem/brief.md item #6. Isolate tokenizer usage \
          in a sidecar before a Windows ship."

crates/transcription/src/concurrency.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
-use kon_core::error::{KonError, Result};
-use kon_core::types::{AudioSamples, TranscriptionOptions};
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::{AudioSamples, TranscriptionOptions};
 
 use crate::local_engine::{LocalEngine, TimedTranscript};
 
@@ -14,5 +14,5 @@ pub async fn run_inference(
 ) -> Result<TimedTranscript> {
     tokio::task::spawn_blocking(move || engine.transcribe_sync(&audio, &options))
         .await
-        .map_err(|e| KonError::TranscriptionFailed(format!("Task join error: {e}")))?
+        .map_err(|e| Error::TranscriptionFailed(format!("Task join error: {e}")))?
 }

crates/transcription/src/lib.rs

@@ -1,19 +1,33 @@
 pub mod concurrency;
 pub mod local_engine;
 pub mod model_manager;
+pub mod orchestrator;
+pub mod registry;
 pub mod streaming;
 pub mod transcriber;
 #[cfg(feature = "whisper")]
 pub mod whisper_rs_backend;
 
 pub use concurrency::run_inference;
-pub use local_engine::{load_parakeet, LocalEngine, SpeechModelAdapter, TimedTranscript};
 #[cfg(feature = "whisper")]
 pub use local_engine::load_whisper;
+pub use local_engine::{load_parakeet, LocalEngine, SpeechModelAdapter, TimedTranscript};
 pub use model_manager::{download, is_downloaded, list_downloaded, model_dir, models_dir};
+pub use orchestrator::{LocalProviderAdapter, Orchestrator};
+pub use registry::EngineRegistry;
 pub use streaming::{
     sample_index_for_seconds, trim_buffer_to_commit_point, CommitDecision, CommitPolicy,
     LocalAgreement, RmsVadChunker, Token, VadChunk, VadChunker,
 };
-pub use transcriber::{Transcriber, TranscriberCapabilities};
 pub use transcribe_rs::SpeechModel;
+pub use transcriber::{Transcriber, TranscriberCapabilities};
+
+// Re-export the trait surface so downstream crates depend only on
+// `lumotia_transcription` to access both local engines and the
+// provider trait without a separate `lumotia_cloud_providers`
+// dependency. This is the seam an OEM licensee uses when they swap
+// providers.
+pub use lumotia_cloud_providers::{
+    CostClass, EngineProfile, NetworkRequirement, ProviderCapabilities, ProviderId, ProviderKind,
+    ProviderTranscript, TranscriptionProvider,
+};

crates/transcription/src/local_engine.rs

@@ -4,8 +4,8 @@ use std::time::Instant;
 
 use transcribe_rs::{SpeechModel, TranscribeOptions, TranscriptionResult};
 
-use kon_core::error::{KonError, Result};
-use kon_core::types::{
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::{
     AudioSamples, EngineName, ModelId, Segment, Transcript, TranscriptionOptions,
 };
 
@@ -28,7 +28,7 @@ pub struct SpeechModelAdapter(pub Box<dyn SpeechModel + Send>);
 impl Transcriber for SpeechModelAdapter {
     fn capabilities(&self) -> TranscriberCapabilities {
         TranscriberCapabilities {
-            sample_rate: kon_core::constants::WHISPER_SAMPLE_RATE,
+            sample_rate: lumotia_core::constants::WHISPER_SAMPLE_RATE,
             channels: 1,
             supports_initial_prompt: false,
         }
@@ -48,7 +48,7 @@ impl Transcriber for SpeechModelAdapter {
         let result: TranscriptionResult = self
             .0
             .transcribe(samples, &opts)
-            .map_err(|e| KonError::TranscriptionFailed(e.to_string()))?;
+            .map_err(|e| Error::TranscriptionFailed(e.to_string()))?;
         Ok(result
             .segments
             .unwrap_or_default()
@@ -140,7 +140,7 @@ impl LocalEngine {
         options: &TranscriptionOptions,
     ) -> Result<TimedTranscript> {
         let mut guard = self.engine.lock().unwrap_or_else(|e| e.into_inner());
-        let backend = guard.as_mut().ok_or(KonError::EngineNotLoaded)?;
+        let backend = guard.as_mut().ok_or(Error::EngineNotLoaded)?;
 
         let start = Instant::now();
         let segments = backend.transcribe_sync(audio.samples(), options)?;
@@ -160,7 +160,7 @@ impl LocalEngine {
 /// Thin wrapper over `ParakeetModel` that overrides `transcribe_raw` to
 /// request word-granularity segments. `transcribe-rs` 0.3's trait impl for
 /// `ParakeetModel::transcribe_raw` ignores `TranscribeOptions` and uses
-/// `TimestampGranularity::Token` (per-subword) — which surfaces in Kon as
+/// `TimestampGranularity::Token` (per-subword) — which surfaces in Lumotia as
 /// "T Est Ing . One , Two , Three" output. The concrete-type method
 /// `ParakeetModel::transcribe_with` accepts `ParakeetParams` with an
 /// explicit granularity; this wrapper exposes that to the trait object.
@@ -197,7 +197,7 @@ impl transcribe_rs::SpeechModel for ParakeetWordGranularity {
 pub fn load_parakeet(model_dir: &Path) -> Result<Box<dyn Transcriber + Send>> {
     use transcribe_rs::onnx::Quantization;
     let model = transcribe_rs::onnx::parakeet::ParakeetModel::load(model_dir, &Quantization::Int8)
-        .map_err(|e| KonError::TranscriptionFailed(format!("Failed to load Parakeet: {e}")))?;
+        .map_err(|e| Error::TranscriptionFailed(format!("Failed to load Parakeet: {e}")))?;
     Ok(Box::new(SpeechModelAdapter(Box::new(
         ParakeetWordGranularity(model),
     ))))
@@ -207,7 +207,7 @@ pub fn load_parakeet(model_dir: &Path) -> Result<Box<dyn Transcriber + Send>> {
 #[cfg(feature = "whisper")]
 pub fn load_whisper(model_path: &Path) -> Result<Box<dyn Transcriber + Send>> {
     let backend = WhisperRsBackend::load(model_path)
-        .map_err(|e| KonError::TranscriptionFailed(format!("Failed to load Whisper: {e}")))?;
+        .map_err(|e| Error::TranscriptionFailed(format!("Failed to load Whisper: {e}")))?;
     Ok(Box::new(backend))
 }
 

crates/transcription/src/model_manager.rs

@@ -1,34 +1,51 @@
+use std::collections::HashSet;
 use std::path::{Path, PathBuf};
+use std::sync::{LazyLock, Mutex};
 
-use kon_core::error::{KonError, Result};
-use kon_core::model_registry::{find_model, ModelFile};
-use kon_core::types::{DownloadProgress, ModelId};
+use lumotia_core::error::{Error, Result};
+use lumotia_core::model_registry::{find_model, ModelFile};
+use lumotia_core::types::{DownloadProgress, ModelId};
 
-/// Resolve the models storage directory.
-/// Windows: %LOCALAPPDATA%/kon/models
-/// Unix: ~/.kon/models
-pub fn models_dir() -> PathBuf {
-    if cfg!(target_os = "windows") {
-        let local_app_data = std::env::var("LOCALAPPDATA").unwrap_or_else(|_| ".".to_string());
-        PathBuf::from(local_app_data).join("kon").join("models")
-    } else {
-        dirs_path().join("models")
+static ACTIVE_DOWNLOADS: LazyLock<Mutex<HashSet<String>>> =
+    LazyLock::new(|| Mutex::new(HashSet::new()));
+
+struct DownloadReservation {
+    id: String,
+}
+
+impl DownloadReservation {
+    fn acquire(id: &ModelId) -> Result<Self> {
+        let id = id.as_str().to_string();
+        let mut active = ACTIVE_DOWNLOADS
+            .lock()
+            .map_err(|_| Error::DownloadFailed("download lock poisoned".into()))?;
+        if !active.insert(id.clone()) {
+            return Err(Error::DownloadFailed(format!(
+                "download already in progress for {id}"
+            )));
+        }
+        Ok(Self { id })
     }
 }
 
-fn dirs_path() -> PathBuf {
-    if cfg!(target_os = "windows") {
-        let local_app_data = std::env::var("LOCALAPPDATA").unwrap_or_else(|_| ".".to_string());
-        PathBuf::from(local_app_data).join("kon")
-    } else {
-        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
-        PathBuf::from(home).join(".kon")
+impl Drop for DownloadReservation {
+    fn drop(&mut self) {
+        if let Ok(mut active) = ACTIVE_DOWNLOADS.lock() {
+            active.remove(&self.id);
+        }
     }
 }
 
+/// Resolve the models storage directory.
+/// Windows: %LOCALAPPDATA%/lumotia/models
+/// Unix: ~/.lumotia/models
+pub fn models_dir() -> PathBuf {
+    lumotia_core::paths::app_paths().models_dir()
+}
+
 /// Get the directory path where a specific model's files are stored.
 pub fn model_dir(id: &ModelId) -> PathBuf {
-    models_dir().join(id.as_str())
+    lumotia_core::paths::app_paths().speech_model_dir(id)
 }
 
 /// Check whether all files for a model have been downloaded.
@@ -39,11 +56,12 @@ pub fn is_downloaded(id: &ModelId) -> bool {
     };
     let dir = model_dir(id);
     entry.files.iter().all(|f| dir.join(f.filename).exists())
+        && verified_manifest_matches(entry, &dir)
 }
 
 /// List all downloaded model IDs.
 pub fn list_downloaded() -> Vec<ModelId> {
-    kon_core::model_registry::all_models()
+    lumotia_core::model_registry::all_models()
         .iter()
         .filter(|m| is_downloaded(&m.id))
         .map(|m| m.id.clone())
@@ -56,12 +74,13 @@ pub fn list_downloaded() -> Vec<ModelId> {
 /// For files that declare a `sha256` checksum we validate an existing
 /// complete file before skipping the download — a truncated or
 /// tampered file gets redownloaded automatically (pattern ported from
-/// `kon-llm`'s model_manager, item #8 in the Whisper ecosystem brief).
+/// `lumotia-llm`'s model_manager, item #8 in the Whisper ecosystem brief).
 pub async fn download(
     id: &ModelId,
     progress: impl Fn(DownloadProgress) + Send + 'static,
 ) -> Result<()> {
-    let entry = find_model(id).ok_or_else(|| KonError::ModelNotFound(id.clone()))?;
+    let _reservation = DownloadReservation::acquire(id)?;
+    let entry = find_model(id).ok_or_else(|| Error::ModelNotFound(id.clone()))?;
 
     let dir = model_dir(id);
     std::fs::create_dir_all(&dir)?;
@@ -69,36 +88,73 @@ pub async fn download(
     for file in &entry.files {
         let dest = dir.join(file.filename);
         if dest.exists() {
-            if let Some(expected_sha) = file.sha256 {
-                // Validate the existing file. If the hash doesn't match,
-                // the file is corrupt (partial download, tampering, bit
-                // rot) and we must re-fetch it to avoid crashing on
-                // model load later.
-                match sha256_of_file(&dest) {
-                    Ok(actual) if actual.eq_ignore_ascii_case(expected_sha) => continue,
-                    Ok(_actual) => {
-                        // Corrupt — remove + fall through to re-download.
-                        let _ = std::fs::remove_file(&dest);
-                    }
-                    Err(e) => {
-                        return Err(KonError::DownloadFailed(format!(
-                            "failed to verify existing {}: {e}",
-                            file.filename
-                        )));
-                    }
+            // Validate the existing file. If the hash doesn't match,
+            // the file is corrupt (partial download, tampering, bit
+            // rot) and we must re-fetch it to avoid crashing on
+            // model load later.
+            match sha256_of_file(&dest) {
+                Ok(actual) if actual.eq_ignore_ascii_case(file.sha256) => continue,
+                Ok(_actual) => {
+                    let _ = std::fs::remove_file(&dest);
+                }
+                Err(e) => {
+                    return Err(Error::DownloadFailed(format!(
+                        "failed to verify existing {}: {e}",
+                        file.filename
+                    )));
                 }
-            } else {
-                // No checksum — honour the existing file as-is; the
-                // engine will barf on load if it's broken.
-                continue;
             }
         }
         download_file(file, &dest, id, &progress).await?;
     }
 
+    write_verified_manifest(entry, &dir)?;
     Ok(())
 }
 
+fn verified_manifest_path(dir: &Path) -> PathBuf {
+    dir.join(".lumotia-verified")
+}
+
+fn verified_manifest_matches(
+    entry: &lumotia_core::model_registry::ModelEntry,
+    dir: &Path,
+) -> bool {
+    let manifest = match std::fs::read_to_string(verified_manifest_path(dir)) {
+        Ok(contents) => contents,
+        Err(_) => return false,
+    };
+
+    for file in &entry.files {
+        let path = dir.join(file.filename);
+        let size = match std::fs::metadata(&path) {
+            Ok(metadata) => metadata.len(),
+            Err(_) => return false,
+        };
+        let expected_line = format!("{}\t{}\t{}", file.filename, file.sha256, size);
+        if !manifest.lines().any(|line| line == expected_line) {
+            return false;
+        }
+    }
+    true
+}
+
+fn write_verified_manifest(
+    entry: &lumotia_core::model_registry::ModelEntry,
+    dir: &Path,
+) -> std::io::Result<()> {
+    let mut lines = Vec::with_capacity(entry.files.len() + 1);
+    lines.push("version\t1".to_string());
+    for file in &entry.files {
+        let size = std::fs::metadata(dir.join(file.filename))?.len();
+        lines.push(format!("{}\t{}\t{}", file.filename, file.sha256, size));
+    }
+    std::fs::write(
+        verified_manifest_path(dir),
+        format!("{}\n", lines.join("\n")),
+    )
+}
+
 /// Non-streaming SHA256 of a file on disk. Used by `download()` to
 /// validate an existing complete file before trusting it.
 fn sha256_of_file(path: &Path) -> std::io::Result<String> {
@@ -140,7 +196,7 @@ async fn download_file(
     let client = reqwest::Client::builder()
         .connect_timeout(std::time::Duration::from_secs(30))
         .build()
-        .map_err(|e| KonError::DownloadFailed(e.to_string()))?;
+        .map_err(|e| Error::DownloadFailed(e.to_string()))?;
 
     // Check for existing partial download (resume support)
     let existing_bytes = if part_path.exists() {
@@ -151,9 +207,7 @@ async fn download_file(
 
     let mut request = client.get(file.url);
 
-    // If we have a partial file and no SHA256 to verify (can't verify partial),
-    // request a range resume. If SHA256 is set, we restart to ensure integrity.
-    let resuming = existing_bytes > 0 && file.sha256.is_none();
+    let resuming = existing_bytes > 0;
     if resuming {
         request = request.header("Range", format!("bytes={existing_bytes}-"));
     }
@@ -161,12 +215,12 @@ async fn download_file(
     let response = request
         .send()
         .await
-        .map_err(|e| KonError::DownloadFailed(e.to_string()))?;
+        .map_err(|e| Error::DownloadFailed(e.to_string()))?;
 
     // If we requested Range but the server returned 200 (full file), the
     // server does not support resume. Rather than blindly appending a
     // full file on top of our partial bytes (which would produce a
-    // corrupt result), restart cleanly. This mirrors the kon-llm
+    // corrupt result), restart cleanly. This mirrors the lumotia-llm
     // ResumeUnsupported branch — item #8 of the brief.
     //
     // For the non-resume path, we still have to validate the status:
@@ -183,14 +237,14 @@ async fn download_file(
                 false
             }
             other => {
-                return Err(KonError::DownloadFailed(format!(
+                return Err(Error::DownloadFailed(format!(
                     "resume request returned unexpected status {other}"
                 )));
             }
         }
     } else {
         if !response.status().is_success() {
-            return Err(KonError::DownloadFailed(format!(
+            return Err(Error::DownloadFailed(format!(
                 "download returned HTTP {} for {}",
                 response.status(),
                 file.filename
@@ -223,19 +277,23 @@ async fn download_file(
         std::fs::File::create(&part_path)?
     };
 
-    // Incremental SHA256 — only when a checksum is provided
-    let mut hasher = file.sha256.map(|_| Sha256::new());
-
-    // If resuming without SHA256, we can't hash the already-downloaded portion,
-    // but we also don't need to — we only hash when sha256 is set, and we
-    // restart from scratch in that case.
+    let mut hasher = Sha256::new();
+    if actually_resuming {
+        let mut partial = std::fs::File::open(&part_path)?;
+        let mut buffer = [0u8; 8192];
+        loop {
+            let n = std::io::Read::read(&mut partial, &mut buffer)?;
+            if n == 0 {
+                break;
+            }
+            hasher.update(&buffer[..n]);
+        }
+    }
 
     while let Some(chunk) = stream.next().await {
-        let chunk = chunk.map_err(|e| KonError::DownloadFailed(e.to_string()))?;
+        let chunk = chunk.map_err(|e| Error::DownloadFailed(e.to_string()))?;
         std::io::Write::write_all(&mut out, &chunk)?;
-        if let Some(ref mut h) = hasher {
-            h.update(&chunk);
-        }
+        hasher.update(&chunk);
         downloaded += chunk.len() as u64;
 
         let percent = if total_bytes > 0 {
@@ -258,17 +316,13 @@ async fn download_file(
 
     drop(out);
 
-    // Verify SHA256 if provided
-    if let (Some(expected), Some(hasher)) = (file.sha256, hasher) {
-        let actual = format!("{:x}", hasher.finalize());
-        if actual != expected {
-            // Delete corrupt file so next attempt starts fresh
-            let _ = std::fs::remove_file(&part_path);
-            return Err(KonError::DownloadFailed(format!(
-                "SHA256 mismatch for {}: expected {}, got {}",
-                file.filename, expected, actual
-            )));
-        }
+    let actual = format!("{:x}", hasher.finalize());
+    if actual != file.sha256 {
+        let _ = std::fs::remove_file(&part_path);
+        return Err(Error::DownloadFailed(format!(
+            "SHA256 mismatch for {}: expected {}, got {}",
+            file.filename, file.sha256, actual
+        )));
     }
 
     // Atomic rename — file is complete and verified
@@ -303,7 +357,7 @@ mod tests {
         let list = list_downloaded();
         // In test environment, no models are downloaded
         // This just verifies the function doesn't panic
-        assert!(list.len() <= kon_core::model_registry::all_models().len());
+        assert!(list.len() <= lumotia_core::model_registry::all_models().len());
     }
 
     #[test]
@@ -427,8 +481,8 @@ mod tests {
         let file = ModelFile {
             filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
             url: leak(format!("http://{addr}/fixture.bin")),
-            size: kon_core::types::Megabytes(0),
-            sha256: None, // resume path only kicks in when sha256 is absent
+            size: lumotia_core::types::Megabytes(0),
+            sha256: leak(expected_sha.clone()),
         };
         let id = ModelId::new("test-fixture");
 
@@ -437,9 +491,6 @@ mod tests {
         let bytes = std::fs::read(&dest).unwrap();
         assert_eq!(bytes, body);
         assert!(!part.exists());
-        // Confirm the full file hash matches what we would have got via
-        // a clean download — gives the resume path indirect integrity
-        // coverage even when the ModelFile has no sha256 set.
         assert_eq!(sha256_of_file(&dest).unwrap(), expected_sha);
     }
 
@@ -451,6 +502,7 @@ mod tests {
         // partial bytes and write the fresh body from offset zero rather
         // than appending on top.
         let body = b"fresh transcription payload that replaces any stale partial".to_vec();
+        let expected_sha = format!("{:x}", sha2::Sha256::digest(&body));
         let addr = spawn_no_range_server(body.clone()).await;
 
         let dir = tempdir().unwrap();
@@ -464,8 +516,8 @@ mod tests {
         let file = ModelFile {
             filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
             url: leak(format!("http://{addr}/fixture.bin")),
-            size: kon_core::types::Megabytes(0),
-            sha256: None,
+            size: lumotia_core::types::Megabytes(0),
+            sha256: leak(expected_sha),
         };
         let id = ModelId::new("test-fixture");
 
@@ -519,8 +571,8 @@ mod tests {
         let file = ModelFile {
             filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
             url: leak(format!("http://{addr}/fixture.bin")),
-            size: kon_core::types::Megabytes(0),
-            sha256: None,
+            size: lumotia_core::types::Megabytes(0),
+            sha256: leak("0".repeat(64)),
         };
         let id = ModelId::new("test-fixture");
 
@@ -547,8 +599,8 @@ mod tests {
         let file = ModelFile {
             filename: leak(dest.file_name().unwrap().to_string_lossy().into_owned()),
             url: leak(format!("http://{addr}/fixture.bin")),
-            size: kon_core::types::Megabytes(0),
-            sha256: Some(leak("deadbeef".repeat(8))),
+            size: lumotia_core::types::Megabytes(0),
+            sha256: leak("deadbeef".repeat(8)),
         };
         let id = ModelId::new("test-fixture");
 
@@ -557,7 +609,10 @@ mod tests {
             .expect_err("mismatched sha must fail");
         let msg = err.to_string();
         assert!(msg.contains("SHA256 mismatch"), "unexpected error: {msg}");
-        assert!(!dest.exists(), ".part → dest rename must not run on mismatch");
+        assert!(
+            !dest.exists(),
+            ".part → dest rename must not run on mismatch"
+        );
         let part = dest.with_extension("bin.part");
         assert!(!part.exists(), "failed hash must clean up the .part file");
     }

crates/transcription/src/orchestrator.rs

@@ -0,0 +1,281 @@
+//! `Orchestrator` is the single entry point for transcription. Tauri
+//! commands resolve a provider through it; nothing else calls a
+//! provider directly. This is where the AGPL OEM trait boundary meets
+//! Lumotia's local engines.
+//!
+//! `LocalProviderAdapter` lives here, not as an `impl
+//! TranscriptionProvider for LocalEngine`. The adapter wraps an
+//! `Arc<LocalEngine>` and bridges the synchronous `Transcriber` trait
+//! to the async `TranscriptionProvider` interface via
+//! `tokio::task::spawn_blocking`. Keeping the adapter in the
+//! orchestrator (rather than in `local_engine.rs`) means the
+//! transcription crate's core types do not need to depend on
+//! `async_trait`, and the dependency edge stays one-directional:
+//! `cloud_providers` defines the trait, `transcription` implements it
+//! via adapter without leaking async-runtime requirements onto
+//! `Transcriber`.
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use lumotia_cloud_providers::{
+    CostClass, EngineProfile, ProviderCapabilities, ProviderId, ProviderKind, ProviderTranscript,
+    TranscriptionProvider,
+};
+use lumotia_core::error::{Error, Result};
+use lumotia_core::types::{AudioSamples, TranscriptionOptions};
+
+use crate::local_engine::LocalEngine;
+use crate::registry::EngineRegistry;
+
+/// Wraps a `LocalEngine` and presents the async `TranscriptionProvider`
+/// interface upward. One adapter per local engine instance; multiple
+/// engines (Whisper, Parakeet) live as multiple adapters in the
+/// registry.
+pub struct LocalProviderAdapter {
+    provider_id: ProviderId,
+    engine: Arc<LocalEngine>,
+}
+
+impl LocalProviderAdapter {
+    pub fn new(provider_id: ProviderId, engine: Arc<LocalEngine>) -> Self {
+        Self {
+            provider_id,
+            engine,
+        }
+    }
+
+    /// Direct access to the wrapped engine. Used by warmup, model
+    /// management, and the GPU-sequencing guard, none of which want to
+    /// route through the async trait surface.
+    pub fn engine(&self) -> Arc<LocalEngine> {
+        self.engine.clone()
+    }
+}
+
+#[async_trait]
+impl TranscriptionProvider for LocalProviderAdapter {
+    fn provider_id(&self) -> ProviderId {
+        self.provider_id.clone()
+    }
+
+    fn kind(&self) -> ProviderKind {
+        ProviderKind::Local
+    }
+
+    fn capabilities(&self) -> ProviderCapabilities {
+        let local = self.engine.capabilities();
+        ProviderCapabilities {
+            sample_rate: local
+                .map(|c| c.sample_rate)
+                .unwrap_or(lumotia_core::constants::WHISPER_SAMPLE_RATE),
+            channels: local.map(|c| c.channels).unwrap_or(1),
+            initial_prompt_supported: local.map(|c| c.supports_initial_prompt).unwrap_or(false),
+            language_hint_supported: true,
+            streaming_supported: false,
+            cost_class: CostClass::Free,
+        }
+    }
+
+    async fn prepare(&self, _profile: &EngineProfile) -> Result<()> {
+        if self.engine.is_loaded() {
+            Ok(())
+        } else {
+            Err(Error::EngineNotLoaded)
+        }
+    }
+
+    async fn transcribe(
+        &self,
+        audio: AudioSamples,
+        options: TranscriptionOptions,
+    ) -> Result<ProviderTranscript> {
+        let engine = self.engine.clone();
+        let timed = tokio::task::spawn_blocking(move || engine.transcribe_sync(&audio, &options))
+            .await
+            .map_err(|e| Error::TranscriptionFailed(format!("Task join error: {e}")))??;
+        Ok(ProviderTranscript {
+            transcript: timed.transcript,
+            inference_ms: timed.inference_ms,
+        })
+    }
+}
+
+/// The single entry point through which all transcription flows.
+/// Resolves a provider against the registry, runs `prepare` if the
+/// caller has not already done so, and dispatches `transcribe`.
+pub struct Orchestrator {
+    registry: Arc<EngineRegistry>,
+}
+
+impl Orchestrator {
+    pub fn new(registry: Arc<EngineRegistry>) -> Self {
+        Self { registry }
+    }
+
+    /// Underlying registry. Exposed so the UI can list providers and
+    /// query capabilities without going through a transcribe call.
+    pub fn registry(&self) -> Arc<EngineRegistry> {
+        self.registry.clone()
+    }
+
+    /// Resolve the provider for a profile. Returns a clear error when
+    /// the profile names an unregistered engine.
+    pub fn resolve(&self, profile: &EngineProfile) -> Result<Arc<dyn TranscriptionProvider>> {
+        self.registry
+            .get(&profile.engine_id)
+            .ok_or_else(|| Error::ProviderNotRegistered(profile.engine_id.to_string()))
+    }
+
+    /// Transcribe audio using the provider named in the profile. The
+    /// orchestrator builds `TranscriptionOptions` from the profile and
+    /// delegates to the provider.
+    ///
+    /// Phase A scope: this is the new entry point. Existing call sites
+    /// (`commands/transcription.rs::transcribe_file`) still call
+    /// `LocalEngine` directly; their rewire is a follow-up commit so
+    /// the chunking + post-processing logic moves cleanly without
+    /// inflating this diff. See `KNOWN-ISSUES.md` KI-06.
+    pub async fn transcribe(
+        &self,
+        audio: AudioSamples,
+        profile: &EngineProfile,
+    ) -> Result<ProviderTranscript> {
+        let provider = self.resolve(profile)?;
+        let options = profile.to_options();
+        provider.transcribe(audio, options).await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    use lumotia_core::types::{Segment, Transcript};
+
+    /// Mock provider that returns a canned transcript and counts
+    /// invocations. Used to validate the orchestrator's dispatch logic
+    /// without booting a real model.
+    struct CannedProvider {
+        id: ProviderId,
+        calls: Arc<AtomicUsize>,
+        canned_text: String,
+    }
+
+    #[async_trait]
+    impl TranscriptionProvider for CannedProvider {
+        fn provider_id(&self) -> ProviderId {
+            self.id.clone()
+        }
+        fn kind(&self) -> ProviderKind {
+            ProviderKind::Local
+        }
+        fn capabilities(&self) -> ProviderCapabilities {
+            ProviderCapabilities {
+                sample_rate: 16_000,
+                channels: 1,
+                initial_prompt_supported: true,
+                language_hint_supported: true,
+                streaming_supported: false,
+                cost_class: CostClass::Free,
+            }
+        }
+        async fn prepare(&self, _profile: &EngineProfile) -> Result<()> {
+            Ok(())
+        }
+        async fn transcribe(
+            &self,
+            audio: AudioSamples,
+            _options: TranscriptionOptions,
+        ) -> Result<ProviderTranscript> {
+            self.calls.fetch_add(1, Ordering::SeqCst);
+            Ok(ProviderTranscript {
+                transcript: Transcript::new(
+                    vec![Segment {
+                        start: 0.0,
+                        end: audio.duration_secs(),
+                        text: self.canned_text.clone(),
+                    }],
+                    "en".to_string(),
+                    audio.duration_secs(),
+                ),
+                inference_ms: 7,
+            })
+        }
+    }
+
+    fn build_registry_with(id: &str, text: &str, calls: Arc<AtomicUsize>) -> Arc<EngineRegistry> {
+        let mut registry = EngineRegistry::new(ProviderId::new(id));
+        registry.register(Arc::new(CannedProvider {
+            id: ProviderId::new(id),
+            calls,
+            canned_text: text.to_string(),
+        }));
+        Arc::new(registry)
+    }
+
+    fn one_second_of_silence() -> AudioSamples {
+        AudioSamples::mono_16khz(vec![0.0_f32; 16_000])
+    }
+
+    #[tokio::test]
+    async fn orchestrator_dispatches_to_named_provider() {
+        let calls = Arc::new(AtomicUsize::new(0));
+        let registry = build_registry_with("canned", "hello lumotia", calls.clone());
+        let orchestrator = Orchestrator::new(registry);
+
+        let profile = EngineProfile::new(ProviderId::new("canned"));
+        let result = orchestrator
+            .transcribe(one_second_of_silence(), &profile)
+            .await
+            .expect("dispatch succeeds");
+
+        assert_eq!(result.transcript.text(), "hello lumotia");
+        assert_eq!(result.inference_ms, 7);
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn orchestrator_returns_clear_error_for_unregistered_provider() {
+        let calls = Arc::new(AtomicUsize::new(0));
+        let registry = build_registry_with("canned", "_", calls);
+        let orchestrator = Orchestrator::new(registry);
+
+        let profile = EngineProfile::new(ProviderId::new("not-registered"));
+        let err = orchestrator
+            .transcribe(one_second_of_silence(), &profile)
+            .await
+            .expect_err("unregistered provider must error");
+
+        let msg = err.to_string();
+        assert!(
+            msg.contains("not-registered"),
+            "error must name the missing provider, got: {msg}"
+        );
+    }
+
+    #[tokio::test]
+    async fn orchestrator_routes_initial_prompt_through_options() {
+        let calls = Arc::new(AtomicUsize::new(0));
+        let registry = build_registry_with("canned", "transcript", calls.clone());
+        let orchestrator = Orchestrator::new(registry);
+
+        let mut profile = EngineProfile::new(ProviderId::new("canned"));
+        profile.language = Some("en".to_string());
+        profile.initial_prompt = Some("Lumotia".to_string());
+
+        let _ = orchestrator
+            .transcribe(one_second_of_silence(), &profile)
+            .await
+            .expect("dispatch succeeds");
+
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+    }
+
+    #[test]
+    fn local_provider_adapter_is_object_safe() {
+        let _: Option<Arc<dyn TranscriptionProvider>> = None;
+    }
+}

crates/transcription/src/registry.rs

@@ -0,0 +1,183 @@
+//! `EngineRegistry` is the catalogue of available providers, built
+//! once at app boot and dependency-injected into the orchestrator.
+//!
+//! Registration is push-style: the boot code constructs each provider
+//! (a `LocalProviderAdapter` wrapping a `LocalEngine`, or a cloud
+//! provider implementing `TranscriptionProvider` directly) and calls
+//! `register`. The default provider is set at construction time and
+//! used when a profile does not specify one.
+//!
+//! The registry is read-only after boot; mutation requires a fresh
+//! registry instance. Providers are held behind `Arc<dyn
+//! TranscriptionProvider>` so the orchestrator can clone the handle
+//! cheaply across tokio tasks.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use lumotia_cloud_providers::{ProviderId, TranscriptionProvider};
+
+/// Catalogue of providers known to the orchestrator.
+pub struct EngineRegistry {
+    providers: HashMap<ProviderId, Arc<dyn TranscriptionProvider>>,
+    default_provider: ProviderId,
+}
+
+impl EngineRegistry {
+    /// Construct an empty registry with the given default provider id.
+    /// The default need not exist at construction time; callers are
+    /// expected to register it before the registry is queried.
+    pub fn new(default_provider: ProviderId) -> Self {
+        Self {
+            providers: HashMap::new(),
+            default_provider,
+        }
+    }
+
+    /// Register a provider. If a provider with the same id is already
+    /// registered, it is replaced. The provider's id is read once via
+    /// `provider.provider_id()` and used as the registry key.
+    pub fn register(&mut self, provider: Arc<dyn TranscriptionProvider>) {
+        let id = provider.provider_id();
+        self.providers.insert(id, provider);
+    }
+
+    /// Fetch a provider by id. Returns `None` when the id is not in the
+    /// registry; the orchestrator surfaces this as a clear error so the
+    /// UI can prompt the user to pick a different engine.
+    pub fn get(&self, id: &ProviderId) -> Option<Arc<dyn TranscriptionProvider>> {
+        self.providers.get(id).cloned()
+    }
+
+    /// Fetch the default provider. Returns `None` if the default has
+    /// not been registered.
+    pub fn default(&self) -> Option<Arc<dyn TranscriptionProvider>> {
+        self.providers.get(&self.default_provider).cloned()
+    }
+
+    /// The id of the default provider. Always returns; the provider
+    /// itself may not be registered.
+    pub fn default_id(&self) -> &ProviderId {
+        &self.default_provider
+    }
+
+    /// All registered provider ids. The order is unspecified; the UI
+    /// is responsible for any sorting it wants to present.
+    pub fn ids(&self) -> Vec<ProviderId> {
+        self.providers.keys().cloned().collect()
+    }
+
+    /// Number of registered providers.
+    pub fn len(&self) -> usize {
+        self.providers.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.providers.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use async_trait::async_trait;
+    use lumotia_cloud_providers::{
+        CostClass, EngineProfile, ProviderCapabilities, ProviderKind, ProviderTranscript,
+    };
+    use lumotia_core::error::Result;
+    use lumotia_core::types::{AudioSamples, Transcript, TranscriptionOptions};
+
+    struct DummyProvider {
+        id: ProviderId,
+    }
+
+    #[async_trait]
+    impl TranscriptionProvider for DummyProvider {
+        fn provider_id(&self) -> ProviderId {
+            self.id.clone()
+        }
+        fn kind(&self) -> ProviderKind {
+            ProviderKind::Local
+        }
+        fn capabilities(&self) -> ProviderCapabilities {
+            ProviderCapabilities {
+                sample_rate: 16_000,
+                channels: 1,
+                initial_prompt_supported: false,
+                language_hint_supported: true,
+                streaming_supported: false,
+                cost_class: CostClass::Free,
+            }
+        }
+        async fn prepare(&self, _profile: &EngineProfile) -> Result<()> {
+            Ok(())
+        }
+        async fn transcribe(
+            &self,
+            audio: AudioSamples,
+            _options: TranscriptionOptions,
+        ) -> Result<ProviderTranscript> {
+            Ok(ProviderTranscript {
+                transcript: Transcript::new(Vec::new(), "en".to_string(), audio.duration_secs()),
+                inference_ms: 0,
+            })
+        }
+    }
+
+    fn dummy(id: &str) -> Arc<dyn TranscriptionProvider> {
+        Arc::new(DummyProvider {
+            id: ProviderId::new(id),
+        })
+    }
+
+    #[test]
+    fn empty_registry_returns_none_for_default() {
+        let registry = EngineRegistry::new(ProviderId::new("local-whisper"));
+        assert!(registry.default().is_none());
+        assert_eq!(registry.default_id().as_str(), "local-whisper");
+        assert!(registry.is_empty());
+    }
+
+    #[test]
+    fn register_and_get_round_trip() {
+        let mut registry = EngineRegistry::new(ProviderId::new("local-whisper"));
+        registry.register(dummy("local-whisper"));
+        registry.register(dummy("local-parakeet"));
+
+        assert_eq!(registry.len(), 2);
+        assert!(registry.get(&ProviderId::new("local-whisper")).is_some());
+        assert!(registry.get(&ProviderId::new("local-parakeet")).is_some());
+        assert!(registry.get(&ProviderId::new("nonexistent")).is_none());
+    }
+
+    #[test]
+    fn default_resolves_after_registration() {
+        let mut registry = EngineRegistry::new(ProviderId::new("local-whisper"));
+        registry.register(dummy("local-whisper"));
+        let default = registry.default().expect("default provider registered");
+        assert_eq!(default.provider_id().as_str(), "local-whisper");
+    }
+
+    #[test]
+    fn re_register_replaces() {
+        let mut registry = EngineRegistry::new(ProviderId::new("local-whisper"));
+        registry.register(dummy("local-whisper"));
+        registry.register(dummy("local-whisper"));
+        assert_eq!(registry.len(), 1);
+    }
+
+    #[test]
+    fn ids_lists_all_registered() {
+        let mut registry = EngineRegistry::new(ProviderId::new("local-whisper"));
+        registry.register(dummy("local-whisper"));
+        registry.register(dummy("local-parakeet"));
+        let mut ids: Vec<String> = registry
+            .ids()
+            .into_iter()
+            .map(|id| id.as_str().to_string())
+            .collect();
+        ids.sort();
+        assert_eq!(ids, vec!["local-parakeet", "local-whisper"]);
+    }
+}

crates/transcription/src/streaming/buffer_trim.rs

@@ -158,7 +158,7 @@ mod tests {
         let mut total_pushed: u64 = 0;
         let tentative_per_cycle: u64 = 200;
         for _ in 0..100 {
-            buf.extend(std::iter::repeat(0.25_f32).take(16_000));
+            buf.extend(std::iter::repeat_n(0.25_f32, 16_000));
             total_pushed += 16_000;
             let commit_point = total_pushed - tentative_per_cycle;
             start = trim_buffer_to_commit_point(&mut buf, start, commit_point);
@@ -199,7 +199,7 @@ mod tests {
 
         // Simulate a capture buffer that has received 1.2 s of audio
         // starting at t=0.
-        let mut buf: Vec<f32> = std::iter::repeat(0.1_f32).take(19_200).collect();
+        let mut buf: Vec<f32> = std::iter::repeat_n(0.1_f32, 19_200).collect();
         let new_start = trim_buffer_to_commit_point(&mut buf, 0, commit_idx);
         assert_eq!(new_start, 8_000);
         assert_eq!(buf.len(), 19_200 - 8_000);

crates/transcription/src/streaming/commit_policy.rs

@@ -108,11 +108,7 @@ impl LocalAgreement {
 
         // Can't commit anything until we have n passes in hand.
         if self.history.len() < self.n {
-            let tentative = self
-                .history
-                .back()
-                .cloned()
-                .unwrap_or_default();
+            let tentative = self.history.back().cloned().unwrap_or_default();
             return CommitDecision {
                 newly_committed: Vec::new(),
                 tentative,

crates/transcription/src/streaming/rms_vad.rs

@@ -121,7 +121,7 @@ impl RmsVadChunker {
             pending_onset_frames: 0,
             onset_buffer: Vec::new(),
             next_sample_index: 0,
-        active_chunk_start: 0,
+            active_chunk_start: 0,
         }
     }
 
@@ -306,7 +306,7 @@ impl VadChunker for RmsVadChunker {
                 .saturating_sub(self.pending.len() as u64);
             let pad_len = FRAME_SAMPLES - self.pending.len();
             let mut padded = std::mem::take(&mut self.pending);
-            padded.extend(std::iter::repeat(0.0_f32).take(pad_len));
+            padded.extend(std::iter::repeat_n(0.0_f32, pad_len));
             if let Some(chunk) = self.consume_frame(padded, frame_start) {
                 emitted.push(chunk);
             }
@@ -318,17 +318,25 @@ impl VadChunker for RmsVadChunker {
         // whatever is still open as the closing chunk.
         if self.state == State::InSpeech && !self.active_chunk.is_empty() {
             emitted.push(self.emit_active_chunk_and_close());
-        } else if self.state == State::InSpeech {
-            // hit_max emitted mid-flush and left state in InSpeech
-            // with active_chunk empty. Reset cleanly without emitting
-            // a zero-length closing chunk — the hit_max chunk already
-            // carried all the audio.
-            self.state = State::Idle;
-            self.silent_tail_samples = 0;
-            self.pending_onset_frames = 0;
-            self.onset_buffer.clear();
         }
 
+        // Defence in depth: every flush exit-path must leave the chunker
+        // in the same clean state a freshly-constructed one is in,
+        // bar `next_sample_index` (the running total-samples counter,
+        // intentionally preserved across flush). Without this, a flush
+        // that emitted via `consume_frame`'s hit_max branch could leave
+        // `state == InSpeech` with stale `silent_tail_samples` or a
+        // populated `onset_buffer`, so the next feed() bleeds prior-
+        // session state into the first chunk of a fresh recording.
+        // The earlier branches already did most of this; the explicit
+        // clear here is a single source of truth.
+        self.state = State::Idle;
+        self.pending.clear();
+        self.active_chunk.clear();
+        self.silent_tail_samples = 0;
+        self.pending_onset_frames = 0;
+        self.onset_buffer.clear();
+
         emitted
     }
 
@@ -552,10 +560,7 @@ mod tests {
         let mut c = RmsVadChunker::new();
         assert!(c.flush().is_empty());
         let _ = c.push(&constant_signal(16_000, 0.0));
-        assert!(
-            c.flush().is_empty(),
-            "flushing pure silence emits nothing"
-        );
+        assert!(c.flush().is_empty(), "flushing pure silence emits nothing");
     }
 
     #[test]
@@ -686,4 +691,45 @@ mod tests {
             "start_sample must not skip past the onset frames"
         );
     }
+
+    #[test]
+    fn flush_is_idempotent_and_leaves_clean_state() {
+        // Drive the chunker through a full speech-then-silence cycle so
+        // most of the state-machine fields are exercised, flush once,
+        // then assert that flushing again is a no-op AND that feed-with-
+        // silence emits nothing (i.e. no stale onset / silent_tail
+        // bookkeeping leaks into the next feed).
+        let mut c = RmsVadChunker::with_thresholds(
+            0.01,
+            0.005,
+            DEFAULT_SPEECH_ONSET_FRAMES,
+            FRAME_SAMPLES * 4,
+            FRAME_SAMPLES * 50,
+        );
+
+        let speech = constant_signal(FRAME_SAMPLES * 6, 0.02);
+        let _ = c.push(&speech);
+        // Force a partial pending tail so flush exercises the padded-
+        // final-frame branch.
+        let partial = constant_signal(FRAME_SAMPLES / 3, 0.02);
+        let _ = c.push(&partial);
+
+        let _first = c.flush();
+
+        let second = c.flush();
+        assert!(
+            second.is_empty(),
+            "second flush must be a no-op; got {} chunk(s)",
+            second.len()
+        );
+
+        // A subsequent silent feed must emit nothing — proves nothing
+        // about prior speech leaked into the new session's bookkeeping.
+        let silence = constant_signal(FRAME_SAMPLES * 4, 0.0);
+        let chunks = c.push(&silence);
+        assert!(
+            chunks.is_empty(),
+            "post-flush silence must not emit any chunk; got {chunks:?}"
+        );
+    }
 }

crates/transcription/src/transcriber.rs

@@ -9,8 +9,8 @@
 //! `whisper` feature — `WhisperRsBackend` (direct whisper-rs, the only
 //! path that pipes `initial_prompt`).
 
-use kon_core::error::Result;
-use kon_core::types::{Segment, TranscriptionOptions};
+use lumotia_core::error::Result;
+use lumotia_core::types::{Segment, TranscriptionOptions};
 
 /// Static capabilities a `Transcriber` advertises to callers.
 ///

crates/transcription/src/whisper_rs_backend.rs

@@ -10,8 +10,10 @@ use std::path::Path;
 
 use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
 
-use kon_core::error::{KonError, Result};
-use kon_core::types::{Segment, TranscriptionOptions};
+use lumotia_core::error::{Error, Result};
+use lumotia_core::hardware::vulkan_loader_available;
+use lumotia_core::tuning::{inference_thread_count, Workload};
+use lumotia_core::types::{Segment, TranscriptionOptions};
 
 use crate::transcriber::{Transcriber, TranscriberCapabilities};
 
@@ -40,7 +42,7 @@ impl WhisperRsBackend {
 impl Transcriber for WhisperRsBackend {
     fn capabilities(&self) -> TranscriberCapabilities {
         TranscriberCapabilities {
-            sample_rate: kon_core::constants::WHISPER_SAMPLE_RATE,
+            sample_rate: lumotia_core::constants::WHISPER_SAMPLE_RATE,
             channels: 1,
             supports_initial_prompt: true,
         }
@@ -62,10 +64,11 @@ impl Transcriber for WhisperRsBackend {
             "WhisperRsBackend::transcribe_sync entering"
         );
 
-        let mut state = self
-            .ctx
-            .create_state()
-            .map_err(|e| KonError::TranscriptionFailed(WhisperBackendError::State(e.to_string()).to_string()))?;
+        let mut state = self.ctx.create_state().map_err(|e| {
+            Error::TranscriptionFailed(
+                WhisperBackendError::State(e.to_string()).to_string(),
+            )
+        })?;
 
         let mut params = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
         if let Some(lang) = options.language.as_deref() {
@@ -78,14 +81,17 @@ impl Transcriber for WhisperRsBackend {
                 params.set_initial_prompt(prompt);
             }
         }
-        params.set_n_threads(num_cpus::get() as i32);
+        let gpu_offloaded = cfg!(feature = "whisper-vulkan") && vulkan_loader_available();
+        params.set_n_threads(inference_thread_count(Workload::Whisper, gpu_offloaded) as i32);
         params.set_print_special(false);
         params.set_print_progress(false);
         params.set_print_realtime(false);
 
-        state
-            .full(params, samples)
-            .map_err(|e| KonError::TranscriptionFailed(WhisperBackendError::Transcribe(e.to_string()).to_string()))?;
+        state.full(params, samples).map_err(|e| {
+            Error::TranscriptionFailed(
+                WhisperBackendError::Transcribe(e.to_string()).to_string(),
+            )
+        })?;
 
         let n = state.full_n_segments();
 
@@ -96,7 +102,11 @@ impl Transcriber for WhisperRsBackend {
             };
             let text = seg
                 .to_str()
-                .map_err(|e| KonError::TranscriptionFailed(WhisperBackendError::Transcribe(e.to_string()).to_string()))?
+                .map_err(|e| {
+                    Error::TranscriptionFailed(
+                        WhisperBackendError::Transcribe(e.to_string()).to_string(),
+                    )
+                })?
                 .to_string();
             // whisper-rs timestamps are centiseconds (10ms units). Convert to seconds (f64).
             let start = seg.start_timestamp() as f64 * 0.01;

crates/transcription/tests/jfk_bench.rs

@@ -0,0 +1,151 @@
+//! Benchmark: load the JFK WAV from disk, transcribe it via whisper-rs.
+//! Reports cold-load time, transcribe time, RTF, peak RSS.
+//!
+//! Gated on env vars so it never runs in CI without setup:
+//!   LUMOTIA_WHISPER_TEST_MODEL=/path/to/ggml-tiny.bin
+//!   LUMOTIA_WHISPER_TEST_AUDIO=/path/to/jfk.wav
+
+use std::env;
+use std::time::Instant;
+
+#[test]
+fn jfk_transcription_benchmark() {
+    let Ok(model_path) = env::var("LUMOTIA_WHISPER_TEST_MODEL") else {
+        eprintln!("LUMOTIA_WHISPER_TEST_MODEL not set — skipping");
+        return;
+    };
+    let Ok(audio_path) = env::var("LUMOTIA_WHISPER_TEST_AUDIO") else {
+        eprintln!("LUMOTIA_WHISPER_TEST_AUDIO not set — skipping");
+        return;
+    };
+
+    use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
+
+    eprintln!("[bench] loading WAV: {audio_path}");
+    let bytes = std::fs::read(&audio_path).expect("read wav");
+    // Minimal RIFF/WAV parse: skip the 44-byte canonical header for PCM-16-mono-16kHz.
+    // Sanity-check magic bytes + format.
+    assert_eq!(&bytes[0..4], b"RIFF", "expected RIFF");
+    assert_eq!(&bytes[8..12], b"WAVE", "expected WAVE");
+    let sample_rate = u32::from_le_bytes(bytes[24..28].try_into().unwrap());
+    let channels = u16::from_le_bytes(bytes[22..24].try_into().unwrap());
+    let bits = u16::from_le_bytes(bytes[34..36].try_into().unwrap());
+    eprintln!(
+        "[bench] wav spec: {} Hz, {} ch, {}-bit",
+        sample_rate, channels, bits
+    );
+    assert_eq!(sample_rate, 16_000, "expected 16 kHz wav");
+    assert_eq!(channels, 1, "expected mono");
+    assert_eq!(bits, 16, "expected 16-bit PCM");
+
+    let pcm = &bytes[44..];
+    let samples: Vec<f32> = pcm
+        .chunks_exact(2)
+        .map(|c| i16::from_le_bytes([c[0], c[1]]) as f32 / 32768.0)
+        .collect();
+    let audio_secs = samples.len() as f64 / sample_rate as f64;
+    eprintln!(
+        "[bench] audio length: {} samples = {:.2}s",
+        samples.len(),
+        audio_secs
+    );
+
+    let rss_before_load_kb = read_rss_kb();
+    eprintln!(
+        "[bench] RSS before model load: {} MB",
+        rss_before_load_kb / 1024
+    );
+
+    let load_start = Instant::now();
+    let ctx = WhisperContext::new_with_params(&model_path, WhisperContextParameters::default())
+        .expect("whisper model load");
+    let load_dur = load_start.elapsed();
+    eprintln!("[bench] model load: {:.2}s", load_dur.as_secs_f64());
+
+    let rss_after_load_kb = read_rss_kb();
+    eprintln!(
+        "[bench] RSS after model load: {} MB (delta +{} MB)",
+        rss_after_load_kb / 1024,
+        (rss_after_load_kb.saturating_sub(rss_before_load_kb)) / 1024
+    );
+
+    let mut state = ctx.create_state().expect("whisper state");
+    let mut params = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
+    params.set_language(Some("en"));
+    params.set_n_threads(6);
+    params.set_print_special(false);
+    params.set_print_progress(false);
+    params.set_print_realtime(false);
+
+    // Cold transcription (first run)
+    let cold_start = Instant::now();
+    state.full(params, &samples).expect("transcribe cold");
+    let cold_dur = cold_start.elapsed();
+
+    let n = state.full_n_segments();
+    let mut full_text = String::new();
+    for i in 0..n {
+        let seg = state.get_segment(i).expect("get_segment");
+        full_text.push_str(seg.to_str().unwrap_or(""));
+    }
+    eprintln!(
+        "[bench] cold transcribe: {:.2}s ({} segments, RTF={:.3})",
+        cold_dur.as_secs_f64(),
+        n,
+        cold_dur.as_secs_f64() / audio_secs
+    );
+    eprintln!("[bench] transcript: {}", full_text.trim());
+    let rss_after_cold_kb = read_rss_kb();
+    eprintln!("[bench] RSS after cold xc: {} MB", rss_after_cold_kb / 1024);
+
+    // Warm transcription (second run, same state)
+    let mut state2 = ctx.create_state().expect("whisper state 2");
+    let mut params2 = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
+    params2.set_language(Some("en"));
+    params2.set_n_threads(6);
+    params2.set_print_special(false);
+    params2.set_print_progress(false);
+    params2.set_print_realtime(false);
+    let warm_start = Instant::now();
+    state2.full(params2, &samples).expect("transcribe warm");
+    let warm_dur = warm_start.elapsed();
+    eprintln!(
+        "[bench] warm transcribe: {:.2}s (RTF={:.3})",
+        warm_dur.as_secs_f64(),
+        warm_dur.as_secs_f64() / audio_secs
+    );
+
+    let rss_final_kb = read_rss_kb();
+    eprintln!("[bench] RSS final: {} MB", rss_final_kb / 1024);
+
+    eprintln!();
+    eprintln!("=== SUMMARY ===");
+    eprintln!("audio:       {:.2}s", audio_secs);
+    eprintln!("model_load:  {:.2}s", load_dur.as_secs_f64());
+    eprintln!(
+        "cold xc:     {:.2}s  RTF={:.3}",
+        cold_dur.as_secs_f64(),
+        cold_dur.as_secs_f64() / audio_secs
+    );
+    eprintln!(
+        "warm xc:     {:.2}s  RTF={:.3}",
+        warm_dur.as_secs_f64(),
+        warm_dur.as_secs_f64() / audio_secs
+    );
+    eprintln!("RSS peak:    {} MB", rss_final_kb / 1024);
+}
+
+fn read_rss_kb() -> u64 {
+    let pid = std::process::id();
+    let s = std::fs::read_to_string(format!("/proc/{pid}/status")).unwrap_or_default();
+    for line in s.lines() {
+        if let Some(rest) = line.strip_prefix("VmRSS:") {
+            return rest
+                .split_whitespace()
+                .next()
+                .and_then(|n| n.parse::<u64>().ok())
+                .unwrap_or(0);
+        }
+    }
+    0
+}

crates/transcription/tests/thread_sweep.rs

@@ -0,0 +1,131 @@
+//! Thread-count scaling sweep for Whisper Tiny.
+//! Runs the JFK clip at n_threads = 1, 2, 4, 6, 8, 12, prints RTF tables.
+//! Env-gated by `LUMOTIA_WHISPER_TEST_MODEL` + `LUMOTIA_WHISPER_TEST_AUDIO`.
+//!
+//! Now prints multiple panels driven by `LUMOTIA_POWER_STATE_OVERRIDE` so
+//! the helper's predicted thread count for each (power, GPU) combination
+//! can be compared against the empirical RTF data.
+
+use std::env;
+use std::time::Instant;
+
+use lumotia_core::hardware::vulkan_loader_available;
+use lumotia_core::tuning::{inference_thread_count, Workload};
+use whisper_rs::{FullParams, SamplingStrategy, WhisperContext, WhisperContextParameters};
+
+#[test]
+fn whisper_thread_count_sweep() {
+    let Ok(model_path) = env::var("LUMOTIA_WHISPER_TEST_MODEL") else {
+        return;
+    };
+    let Ok(audio_path) = env::var("LUMOTIA_WHISPER_TEST_AUDIO") else {
+        return;
+    };
+
+    let bytes = std::fs::read(&audio_path).expect("read wav");
+    let sample_rate = u32::from_le_bytes(bytes[24..28].try_into().unwrap());
+    let pcm = &bytes[44..];
+    let samples: Vec<f32> = pcm
+        .chunks_exact(2)
+        .map(|c| i16::from_le_bytes([c[0], c[1]]) as f32 / 32768.0)
+        .collect();
+    let audio_secs = samples.len() as f64 / sample_rate as f64;
+    eprintln!("[sweep] audio: {:.2}s @ {} Hz", audio_secs, sample_rate);
+
+    let logical = num_cpus::get();
+    let physical = num_cpus::get_physical();
+    eprintln!("[sweep] CPU: physical={}, logical={}", physical, logical);
+
+    let ctx = WhisperContext::new_with_params(&model_path, WhisperContextParameters::default())
+        .expect("model load");
+
+    // Warm-up pass to prime caches.
+    {
+        let mut state = ctx.create_state().expect("state");
+        let mut params = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
+        params.set_language(Some("en"));
+        params.set_n_threads(physical as i32);
+        params.set_print_special(false);
+        params.set_print_progress(false);
+        params.set_print_realtime(false);
+        state.full(params, &samples).expect("warmup");
+    }
+
+    let mut targets: Vec<i32> = vec![1, 2, 4, physical as i32, logical as i32];
+    if logical >= 8 && !targets.contains(&8) {
+        targets.push(8);
+    }
+    targets.sort();
+    targets.dedup();
+
+    // Snapshot the runtime Vulkan loader status once. The actual whisper
+    // context above already initialised whichever backend it could; the
+    // GPU panels below differ only in label and predicted-helper-pick.
+    // The runtime RTF rows are produced by the same backend the warm-up
+    // used.
+    let vulkan_runtime_ok = cfg!(feature = "whisper-vulkan") && vulkan_loader_available();
+    eprintln!(
+        "[sweep] whisper-vulkan feature: {}, libvulkan resolvable at runtime: {}",
+        cfg!(feature = "whisper-vulkan"),
+        vulkan_runtime_ok
+    );
+
+    // Four panels: CPU and GPU axes for the predicted-helper-pick column,
+    // crossed with AC and battery via LUMOTIA_POWER_STATE_OVERRIDE.
+    let panels = [
+        ("AC, CPU", "ac", false),
+        ("AC, GPU (Vulkan)", "ac", true),
+        ("battery, CPU", "battery", false),
+        ("battery, GPU (Vulkan)", "battery", true),
+    ];
+
+    for (label, power, gpu_offloaded_for_helper) in panels {
+        env::set_var("LUMOTIA_POWER_STATE_OVERRIDE", power);
+        let helper_pick = inference_thread_count(Workload::Whisper, gpu_offloaded_for_helper);
+        run_sweep_panel(label, helper_pick, &ctx, &samples, audio_secs, &targets);
+    }
+    env::remove_var("LUMOTIA_POWER_STATE_OVERRIDE");
+}
+
+fn run_sweep_panel(
+    label: &str,
+    helper_pick: usize,
+    ctx: &WhisperContext,
+    samples: &[f32],
+    audio_secs: f64,
+    targets: &[i32],
+) {
+    eprintln!();
+    eprintln!("=== n_threads scaling: {label} (helper picks: {helper_pick}) ===");
+    eprintln!("n_threads | xc_time | RTF    | speedup_vs_1");
+    eprintln!("----------|---------|--------|-------------");
+    let mut baseline_dur: Option<f64> = None;
+    for n in targets {
+        // Two runs, take the min — best-case after L2/L3 warm.
+        let mut best = f64::MAX;
+        for _ in 0..2 {
+            let mut state = ctx.create_state().expect("state");
+            let mut params = FullParams::new(SamplingStrategy::Greedy { best_of: 1 });
+            params.set_language(Some("en"));
+            params.set_n_threads(*n);
+            params.set_print_special(false);
+            params.set_print_progress(false);
+            params.set_print_realtime(false);
+            let t = Instant::now();
+            state.full(params, samples).expect("transcribe");
+            let dur = t.elapsed().as_secs_f64();
+            if dur < best {
+                best = dur;
+            }
+        }
+        let rtf = best / audio_secs;
+        let speedup = baseline_dur.map(|b| b / best).unwrap_or(1.0);
+        if baseline_dur.is_none() {
+            baseline_dur = Some(best);
+        }
+        eprintln!(
+            "{:>9} | {:>6.2}s | {:>6.3} | {:>6.2}x",
+            n, best, rtf, speedup
+        );
+    }
+}

crates/transcription/tests/whisper_rs_smoke.rs

@@ -1,17 +1,17 @@
 //! Smoke test: whisper-rs 0.16 loads a GGUF model, transcribes silence, and
 //! accepts set_initial_prompt without panicking.
 //!
-//! Runs only when `KON_WHISPER_TEST_MODEL` is set to the path of a
+//! Runs only when `LUMOTIA_WHISPER_TEST_MODEL` is set to the path of a
 //! ggml/gguf whisper model on disk. Otherwise the test exits quiet.
 
 use std::env;
 
 #[test]
 fn whisper_rs_smoke_loads_and_transcribes() {
-    let model_path = match env::var("KON_WHISPER_TEST_MODEL") {
+    let model_path = match env::var("LUMOTIA_WHISPER_TEST_MODEL") {
         Ok(p) => p,
         Err(_) => {
-            eprintln!("KON_WHISPER_TEST_MODEL not set — skipping");
+            eprintln!("LUMOTIA_WHISPER_TEST_MODEL not set — skipping");
             return;
         }
     };

docs/architecture-map/01-frontend/README.md

@@ -0,0 +1,90 @@
+---
+name: Frontend slice (Svelte 5 + SvelteKit + Tauri webview)
+type: architecture-map-slice-index
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Frontend (Slice 01)
+
+> **Where you are:** [Architecture map](../README.md) → Frontend
+
+**Plain English summary.** This slice is everything the user sees. It is a Svelte 5 single page app, served by SvelteKit in SPA mode, hosted inside Tauri's webview. It owns four windows (main, tasks float, transcript viewer, transcription preview overlay), seven page modules switched by an in memory router store, around thirty reusable components, ten reactive stores, and the design system tokens. The frontend never touches the filesystem, audio, models or the LLM directly. Everything that crosses the WebView boundary goes through `invoke()` (calling Rust commands) or Tauri events. If you delete this slice, you delete the entire user surface but keep the engine.
+
+## At a glance
+
+- **Path:** `src/`
+- **Total LOC counted:** about 17 200 (583 `app.css` + 2 740 routes + 6 230 pages + 3 174 components + 4 085 stores/utils/types + ~ 2 360 design system + 130 misc).
+- **File counts:** 7 pages, 25 components, 10 stores, 1 action, 16 utils, 1 type module, 3 locales, 4 routes (root + float/viewer/preview), 20 design system preview HTMLs, 3 design system JSX kits.
+- **Frameworks:** Svelte 5 (runes mode), SvelteKit 2.58, `@sveltejs/adapter-static` with `index.html` fallback (SPA), Vite 6, Tailwind v4 via `@tailwindcss/vite`, svelte-i18n 4, lucide-svelte for icons.
+- **Tauri SDK touchpoints:** `@tauri-apps/api` (core invoke, event, window) plus `plugin-autostart`, `plugin-dialog`, `plugin-global-shortcut`, `plugin-notification`, `plugin-opener`. SSR is disabled (`src/routes/+layout.js`) so the whole tree is client side only.
+- **Persistence used directly by frontend:** `localStorage` for `lumotia_settings`, `lumotia_profiles`, `lumotia_task_lists`, `lumotia_templates`, `lumotia_locale`, plus a small handoff key for the viewer window. Preferences additionally persist via Tauri (`save_preferences`).
+- **Build commands:** `npm run dev` (`svelte-kit sync && vite dev`), `npm run build`, `npm run check` (svelte-check using `jsconfig.json`).
+
+## Map of this slice
+
+- [Windows and routes](windows-and-routes.md). The four Tauri windows, the SvelteKit routes that back them, the `+layout@.svelte` break, and how the shell decides between custom chrome and native decorations.
+- [Pages overview](pages-overview.md). Index of the seven pages routed by `page.current`, and the `/float`, `/viewer`, `/preview` route pages.
+- [Pages: dictation](pages/dictation.md). The hero recording surface.
+- [Pages: settings](pages/settings.md). The 2 484 line settings panel.
+- [Pages: history](pages/history.md). FTS5 backed transcript browser.
+- [Pages: tasks](pages/tasks.md). Inbox, today, soon, later board.
+- [Pages: files](pages/files.md). Drag and drop file transcription.
+- [Pages: first run](pages/first-run.md). Hardware probe and model bootstrap.
+- [Components](components.md). All 25 reusable components grouped by role.
+- [Stores](stores.md). Ten Svelte 5 `$state` stores, plus what each owns and what events they react to.
+- [Actions, utils, types](actions-utils-types.md). The single Svelte action, the 16 utility modules, and the `app.ts` type bible.
+- [Internationalisation](i18n.md). svelte-i18n setup, locale persistence, current coverage.
+- [Design system](design-system.md). Reference material under `src/design-system/` (preview HTML, JSX UI kits). Note: this is reference, not live code.
+- [Frontend ↔ Tauri bridge](frontend-tauri-bridge.md). Every `invoke()` command name and every event listened for or emitted, with their callers.
+- [App shell and styling](app-shell-and-styling.md). `app.css`, `app.html`, fonts, Tailwind v4 configuration, accessibility CSS variables.
+
+## How this slice connects to others
+
+**In (frontend depends on Tauri runtime, slice 02).**
+
+- Sixty plus distinct `invoke()` commands. Full list with caller in [frontend-tauri-bridge.md](frontend-tauri-bridge.md).
+- Tauri events listened to: `model-download-progress`, `parakeet-download-progress`, `lumotia:llm-download-progress`, `lumotia:hotkey-pressed`, `lumotia:open-wind-down`, `lumotia:preferences-changed`, `task-window-focus`, `preview-listening`, `preview-cleanup`, `preview-hide`, plus drag drop (`tauri://drag-drop`, `tauri://drag-enter`, `tauri://drag-leave`).
+- Window APIs: `getCurrentWindow().minimize() / toggleMaximize() / setPosition() / label`.
+- Plugin imports loaded lazily: `@tauri-apps/plugin-global-shortcut`, `@tauri-apps/plugin-dialog`.
+
+**Out (frontend triggers behaviour back into the runtime).**
+
+- DOM `CustomEvent` bus on `window` carries internal traffic (`lumotia:start-timer`, `lumotia:toggle-recording`, `lumotia:task-completed`, etc). The Rust side does not listen to these; they are intra frontend.
+- Tauri `emit()` is used for `lumotia:preferences-changed` only, to fan preference updates across windows.
+- Multi window orchestration: pages call `open_task_window`, `open_viewer_window`, `open_preview_window` to ask Rust to spawn secondary webviews.
+
+**Other slices that read frontend conventions.**
+
+- Slice 02 (Tauri runtime) emits the events listed above and registers commands the frontend invokes.
+- Slice 03 (audio + transcription) ships partial results via a `Channel` (Tauri 2 typed channel) opened in `DictationPage`.
+- Slice 04 (LLM, formatting, MCP) emits `lumotia:llm-download-progress` and `cleanup_transcript_text_cmd` results consumed by Dictation.
+- Slice 05 (storage, hotkey, build) supplies `add_transcript`, `delete_transcript`, profiles, tasks and the evdev hotkey backend.
+
+## Existing in repo docs (do not duplicate)
+
+- `docs/brief/` and `docs/whisper-ecosystem/brief.md`. Product brief and feature set.
+- `docs/icon-mapping.md`. Lucide icon migration audit.
+- `docs/code-review-2026-04-22.md`. Last code review snapshot.
+- `docs/handovers/`. Ship logs (e.g. Phase 9c is the most recent settings related one).
+- `docs/audit/`. UX and accessibility audits.
+- `docs/superpowers/`. Process artefacts.
+- `src/design-system/README.md`, `src/design-system/SKILL.md`. Brand and design ground truth.
+
+This slice index is the navigation hub. The map files referenced above carry the detail.
+
+## Open questions, debt, drift, dead code
+
+1. **`src/lib/Sidebar.svelte` lives outside `components/`.** Every other reusable Svelte module is under `src/lib/components/`. The sidebar is the only sibling of those folders. Cosmetic but it surprises contributors.
+2. **Two parallel theme systems.** `settings.theme` (string `"Light"`/`"Dark"`/`"System"`) coexists with `preferences.theme` (`"light"`/`"dark"`/`"system"`). `+layout.svelte:61-68` and `float/+layout@.svelte` both run a "legacy → new" migration `$effect` every time. The legacy pathway should be retired.
+3. **`@ts-nocheck` is widespread.** `+layout.svelte`, `DictationPage.svelte`, `FilesPage.svelte`, `FirstRunPage.svelte` and the float/viewer/preview layouts all opt out of TypeScript. Type safety stops at the page boundary.
+4. **`SettingsPage.svelte` is 2 484 lines.** Phase 9c handover already flagged this. `SettingsGroup.svelte` exists but the deeper restructure into seven progressive disclosure groups plus search has been deferred.
+5. **`profiles` redirect is a dead route.** `+page.svelte:13` still rewrites `page.current === "profiles"` to `"settings"`, suggesting the old profiles page was removed but call sites may persist. Worth grepping and deleting the redirect after a release.
+6. **Cross window settings sync uses `localStorage` `storage` events.** `float/+layout@.svelte` listens for `storage` to apply settings, while preferences use the dedicated `lumotia:preferences-changed` Tauri event. Inconsistent. Settings sync via `storage` is fragile because it only fires on cross document writes.
+7. **`shims.d.ts` next to the lib root.** Single shim file at `src/lib/shims.d.ts`. Worth verifying it is still needed (Svelte 5 + SvelteKit ship most ambient types now).
+8. **`design-system/ui_kits/`** contains JSX components and an HTML index. They are reference, not live, and should not import from the runtime tree. Confirm the build excludes them.
+9. **`speaker.svelte.ts` is ten lines.** A near empty store. Used by `SpeakerButton.svelte`. Consider folding into a util if it never grows.
+10. **CSS variable `--font-size-transcript` is set on `body` from `+layout.svelte` but `preferences` already sets `--font-size-body` and `--transcript-font-size`.** Three knobs for transcript text size in different stores. Drift between `settings.fontSize` and `preferences.accessibility.transcriptSize` is likely.
+11. **i18n coverage is thin.** Each locale has 19 lines. svelte-i18n is wired but most strings remain hardcoded. Treat as a stub.
+12. **Tailwind v4 has no standalone config file.** All theming lives in `app.css` `@theme`. There is no `tailwind.config.{js,ts}`. Mention this so contributors do not waste time looking.
+13. **`docs/architecture-map/01-frontend/` was empty before this pass.** Reciprocal slice indexes (02 to 05) need updating to point here.

docs/architecture-map/01-frontend/actions-utils-types.md

@@ -0,0 +1,125 @@
+---
+name: Actions, utils, types
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Actions, utils, types
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Actions, utils, types
+
+**Plain English summary.** Helpers that are not components and not state. The single Svelte action (`bionicReading`), 16 utility modules under `src/lib/utils/`, and the `app.ts` type module that everyone imports.
+
+## Actions
+
+### `src/lib/actions/bionicReading.ts` (74 LOC)
+
+Svelte action that toggles "bionic reading" rendering on a node. Walks the text nodes via `TreeWalker`, replaces them with bolded prefix + plain suffix spans. A `MutationObserver` reapplies on text changes (disconnects while mutating to avoid infinite loop). `stripBionic` undoes by unwrapping `<b>` tags and normalising adjacent text nodes.
+
+Used in DictationPage and the viewer. Wired to `preferences.accessibility.bionicReading`.
+
+## Utils
+
+### `runtime.ts` (45 LOC)
+
+Exports `hasTauriRuntime()`. Probes for `window.__TAURI_INTERNALS__` or `window.isTauri` to short circuit Tauri calls in browser preview mode. Used everywhere as the gate before `invoke()`.
+
+### `osInfo.ts` (110 LOC)
+
+Caches OS info via `invoke("os_info")` (or similar; check `lib.rs`). Exposes `loadOsInfo`, `isMac`, `isLinux`, `modKeyLabel` synchronously after `loadOsInfo` resolves. Drives whether the shell renders custom or native chrome.
+
+### `errors.ts` (8 LOC)
+
+`errorMessage(e)` returns a string from `Error | unknown`. Tiny.
+
+### `storage.ts` (8 LOC)
+
+`parseStoredJson<T>(key, fallback)` wraps `JSON.parse(localStorage.getItem(key))` with try/catch. Used by `settingsMigrations`, `page.svelte.ts`, and the viewer handoff.
+
+### `settingsMigrations.ts` (134 LOC)
+
+Versioned migrations for `lumotia_settings`. Holds `CURRENT_SETTINGS_VERSION = 1`. Envelope shape: `{ version: number, data: T }`. Reads bare unversioned blobs as v0. `loadSettingsWithMigration(key, defaults)` walks the chain and toasts on corruption.
+
+### `frontmatter.ts` (148 LOC)
+
+Builds YAML frontmatter for transcript markdown export.
+
+- `deriveAutoTags(text, profile)`. Heuristic auto tags.
+- `buildFrontmatter(transcript)`. Returns the YAML block.
+- `buildMarkdown(transcript)`. Joins frontmatter + body.
+- `normaliseTag(s)`. Lowercase, replace whitespace.
+
+### `saveMarkdown.ts` (132 LOC)
+
+Save dialog + write file dance. `suggestedFilename(item)` builds `<slug>-<YYYY-MM-DD>.md`. `saveTranscriptAsMarkdown(item)` opens `@tauri-apps/plugin-dialog`, then writes via `invoke`. `exportTranscriptsToDir(items)` for bulk export.
+
+### `export.ts` (125 LOC)
+
+Generic export helpers used by DictationPage and FilesPage. Format choice: plain text, markdown, JSON. Falls through to clipboard or save dialog.
+
+### `taskExtractor.ts` (224 LOC)
+
+`extractTasks(text)` uses regex heuristics for "TODO:", "Action:", "I need to ...", numbered lists, etc. Falls back when LLM extraction is unavailable.
+
+### `textMeasure.ts` (166 LOC)
+
+Canvas-based pre-wrap text measurement. `measurePreWrap(text, font, lineHeight, width)` returns the rendered height. `clampTextLines(text, n)` trims to N lines plus ellipsis. Used by HistoryPage virtual scroll and DictationPage textarea sizing.
+
+### `accessibilityTypography.ts` (41 LOC)
+
+Reads `--font-family-body`, `--font-size-body`, `--line-height-body`, `--letter-spacing-body` from `<html>` and returns numeric values. `pretextFontShorthand`, `bodyPretextLineHeight`, `transcriptPretextFont`, `transcriptPretextLineHeight` are the public helpers.
+
+### `virtualList.ts` (49 LOC)
+
+`buildCumulativeOffsets(heights)` and `findVisibleRange(offsets, scrollTop, viewportHeight, overscan)`. Pure. Used by HistoryPage and `VirtualSegmentList`.
+
+### `time.ts` (46 LOC)
+
+`pad(n)`, `formatTime(seconds)`, `formatDuration(seconds)`, `formatTimestamp(iso)`. Display helpers.
+
+### `sounds.ts` (101 LOC)
+
+Loads the start/stop/complete cue sounds via `<audio>` and exposes `playStartCue()`, `playStopCue()`, `playCompleteCue()`. Volume from `settings.soundCueVolume`. Honours `settings.soundCues` flag.
+
+### `hotkeyValidity.ts` (149 LOC)
+
+Validates a hotkey combo against per-OS rules (no Cmd alone on macOS, no single letters, etc). Used by `HotkeyRecorder.svelte`.
+
+### `constants.js` (30 LOC)
+
+The shared scalars:
+- Timing: `FEEDBACK_TIMEOUT_MS`, `HOTKEY_FEEDBACK_MS`, `HISTORY_MAX_ENTRIES = 100`, `MAX_PCM_SAMPLES = 4_800_000` (5 min @ 16 kHz), `SIDEBAR_MAX_TASKS = 30`, `CHUNK_INTERVAL_MS = 3000`, `MIN_CHUNK_SAMPLES = 8000`.
+- Buckets: `BUCKET_COLORS`, `BUCKET_DOT_COLORS` (`inbox` / `today` / `soon` / `later`).
+- Effort: `EFFORT_LABELS`, `EFFORT_ORDER`.
+- Playback: `PLAYBACK_SPEEDS = [0.5, 1, 1.5, 2, 3, 5]`.
+
+Note: this is `.js`, not `.ts`. Other utils are `.ts`.
+
+## Types
+
+### `src/lib/types/app.ts` (408 LOC)
+
+Single source of truth for shared shapes. Contains:
+- `PageState`, `SettingsState`, `Preferences`, `AccessibilityPreferences`.
+- `Profile`, `Template`, `TaskList`, `TaskBucket`, `TaskEntry`, `TaskDraft`, `TaskUpdate`, `TaskDto`, `EnergyLevel`.
+- `TranscriptDto`, `TranscriptEntry`, `TranscriptWriteEntry`, `TranscriptMetaPatch`, `Segment`, `ViewerSegment`.
+- `DailyCompletionCount`, `ToastSeverity`, `FontFamily`, `ReduceMotion`.
+
+### `src/lib/shims.d.ts`
+
+Single ambient declaration file. Worth verifying the contents are still needed (Svelte 5 + SvelteKit ship most ambient types now). README debt note 7.
+
+## Watch outs
+
+- `constants.js` is JS, not TS. If you migrate, the JSDoc shapes in `BUCKET_COLORS` need to align with Tailwind class strings; type-only objects still need a runtime export.
+- `taskExtractor.ts` is a regex heuristic. The LLM path (`extract_tasks_from_transcript_cmd`) is the better signal; the heuristic is the offline fallback.
+- `osInfo.ts` caches forever. If you need to handle a hot OS detection retry (you should not), invalidate the cache yourself.
+- `textMeasure.ts` uses an offscreen `<canvas>`. Costs are real for long transcripts; results are cached per (text, font, line-height, width) tuple in HistoryPage.
+- `frontmatter.ts` and `saveMarkdown.ts` overlap. The former produces the body; the latter handles the I/O. Keep them split.
+
+## See also
+
+- [Stores](stores.md). Many utils are imported by stores.
+- [Components](components.md). The components that consume these helpers.
+- [App shell and styling](app-shell-and-styling.md). CSS variables consumed by the typography utils.

docs/architecture-map/01-frontend/app-shell-and-styling.md

@@ -0,0 +1,110 @@
+---
+name: App shell and styling
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# App shell and styling
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → App shell and styling
+
+**Plain English summary.** Where the visual chrome and CSS plumbing live. `app.html` is the SvelteKit document. `app.css` carries the Tailwind v4 import, the `@theme` token block, the brand `@font-face` declarations, the sensory zones, and the accessibility CSS variables. There is no separate `tailwind.config.{js,ts}`; Tailwind v4 is configured entirely in `app.css`. Fonts ship from `src/fonts/` (bundled by Vite) and `static/fonts/` (served as-is).
+
+## At a glance
+
+- **Path:** `src/app.html`, `src/app.css`, `src/app.d.ts`, `src/fonts/`, `src/assets/`, `static/`.
+- **LOC:** 13 (`app.html`) + 583 (`app.css`) + 8 (`app.d.ts`).
+- **Frameworks:** Tailwind v4 via `@tailwindcss/vite`. No PostCSS config. No standalone Tailwind config file.
+- **Adapter:** `@sveltejs/adapter-static` with `index.html` fallback (SPA, `svelte.config.js`).
+
+## What's in here
+
+### `src/app.html` (13 LOC)
+
+Standard SvelteKit document. Sets `lang="en"`, charset, viewport, favicon, title (`Lumotia`), and applies `data-sveltekit-preload-data="hover"` on `<body>`. The body content is wrapped in `<div style="display: contents">` so the SvelteKit-injected children render inline.
+
+### `src/app.d.ts` (8 LOC)
+
+Ambient declaration extending `Window` with `__TAURI_INTERNALS__` and `isTauri` so `utils/runtime.ts` typechecks.
+
+### `src/app.css` (583 LOC)
+
+Layered:
+1. `@import "tailwindcss"` (Tailwind v4 entry).
+2. `@font-face` for Lexend, Atkinson Hyperlegible Next, OpenDyslexic, JetBrains Mono, Instrument Serif Italic. URLs use root-absolute paths (`/fonts/...`) served from `static/fonts/` by Vite.
+3. `@theme` token block. Sets the design tokens that Tailwind v4 picks up as utility classes:
+   - Colour tokens: `--color-bg`, `--color-bg-raised`, `--color-text`, `--color-text-secondary`, `--color-text-tertiary`, `--color-accent`, `--color-warning`, `--color-success`, `--color-border`, `--color-border-subtle`, `--color-hover`, `--color-nav-active`, plus a sensory-zone palette family.
+   - Typography tokens: `--font-display`, `--font-body`, `--font-mono`, plus `--font-size-*` and `--line-height-*`.
+   - Motion tokens: `--duration-ui`, `--duration-fast`, `--duration-slow`. Easing tokens for `cubic-bezier` curves.
+   - Shadow tokens: `--shadow-accent-md`, `--shadow-accent-glow`, etc.
+4. Sensory-zone overrides keyed on `[data-zone="..."]` on `<html>`. Switches token values to dim, focus, etc.
+5. Theme overrides keyed on `[data-theme="dark"]` and `[data-theme="light"]`. The `preferences` store writes both `data-theme` and `data-zone`.
+6. Accessibility variables on `<html>`: `--font-family-body`, `--font-size-body`, `--letter-spacing-body`, `--line-height-body`. Set by the `preferences` store via `applyToDOM()`.
+7. Base styles: `body` background, font, body font-family bound to the variable, scrollbar styling, focus ring.
+8. Utility classes for grain texture (`.grain` uses the noise asset under `assets/grain.svg`), CRT-style transcript surface, etc.
+9. Animations: `@keyframes fade-in`, `@keyframes pulse`, etc. Reduced motion guard at the bottom (`@media (prefers-reduced-motion: reduce)`).
+
+### `src/fonts/` (bundled woff2)
+
+- `atkinson-hyperlegible-next.woff2`
+- `instrument-serif-italic.woff2`
+- `jetbrains-mono.woff2`
+- `lexend-variable.woff2`
+- `opendyslexic.woff2`
+
+Bundled by Vite (referenced from `app.css` via `/fonts/...` paths that Vite resolves). The same files live in `static/fonts/` for the static-served path. Confirm whether both paths are required; if Vite handles font copying, `static/fonts/` may be redundant.
+
+### `src/assets/`
+
+- `grain.svg`. Noise texture used by the `.grain` utility class.
+- `waveform-mark.svg`. Brand glyph.
+- `wordmark.svg`. Brand wordmark.
+
+### `static/`
+
+Served as-is from the webview root.
+
+- `favicon.png`. Site favicon.
+- `fonts/`. Same five woff2 files as `src/fonts/`. Likely the source of `app.css /fonts/...` URLs.
+- `pcm-processor.js`. AudioWorklet processor (slice 02 owns the integration). 32-line file that converts microphone input to int16 PCM frames and posts them up.
+- `textures/grain.png`. PNG version of the grain texture.
+- `svelte.svg`, `tauri.svg`, `vite.svg`. SvelteKit defaults; technically unused. Candidate for removal.
+
+## How preferences map to the DOM
+
+| Preference | DOM target |
+|---|---|
+| `theme` ("light" / "dark" / "system") | `data-theme` on `<html>`. `system` resolves to OS preference at apply time. |
+| `zone` ("default" / ...) | `data-zone` on `<html>`. |
+| `accessibility.fontFamily` ("lexend" / "atkinson" / "opendyslexic") | `--font-family-body` CSS variable on `<html>`. |
+| `accessibility.fontSize` | `--font-size-body` (pixels). |
+| `accessibility.letterSpacing` | `--letter-spacing-body` (em). |
+| `accessibility.lineHeight` | `--line-height-body` (unitless). |
+| `accessibility.bionicReading` | `<html data-bionic-reading="true|false">`. The `bionicReading` action reads this. |
+| `accessibility.reduceMotion` | `<html data-reduce-motion="reduce|no-preference|system">`. Pairs with the `prefers-reduced-motion` media query. |
+
+Plus the legacy `settings.fontSize` writes `--font-size-transcript` on `<body>` directly (`+layout.svelte:204`). That is separate from `accessibility.fontSize`.
+
+## Tailwind v4 setup
+
+- Installed via `@tailwindcss/vite` in `vite.config.js:3`.
+- Entry: `src/app.css` line 1, `@import "tailwindcss"`.
+- Tokens declared inline via `@theme` blocks in `app.css`.
+- No `tailwind.config.{js,ts}` exists. Do not look for one.
+- Class scanning: Tailwind v4 scans the source tree by default. Custom paths can be configured with `@source` directives if needed.
+
+## Watch outs
+
+- **Two font sources.** `src/fonts/` (Vite bundled) and `static/fonts/` (raw served). Confirm whether both are needed; redundancy bloats the bundle.
+- **Mirror file `src/design-system/colors_and_type.css`** must be updated whenever `app.css` `@theme` changes. There is no automated check.
+- **`prefers-reduced-motion` honoured by CSS** but JS animations (e.g. `CompletionSparkline`'s stagger) are guarded in component code, not via the media query alone.
+- **Tailwind v4 `@theme` is class-scanning sensitive.** If you put utility class strings inside conditional template literals that Tailwind cannot see at scan time, they will not be generated.
+- **Removing default SvelteKit assets** (`static/svelte.svg`, `vite.svg`, `tauri.svg`) requires confirming nothing references them in `app.html` or `README.md`.
+- **`pcm-processor.js`** is a static asset because AudioWorklet processors must be served from a same-origin URL. Bundling it through Vite would break the worklet registration. Leave it in `static/`.
+
+## See also
+
+- [Design system](design-system.md). The reference mirror of `app.css` tokens.
+- [Stores](stores.md). The `preferences` store that writes the DOM.
+- [Components](components.md). Where the utility classes are consumed.

docs/architecture-map/01-frontend/components.md

@@ -0,0 +1,103 @@
+---
+name: Components
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Components
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Components
+
+**Plain English summary.** All 25 reusable Svelte 5 components, plus `Sidebar.svelte` which is the only component that lives at `src/lib/Sidebar.svelte` rather than under `src/lib/components/`. Grouped by what they do. Where a component is mounted directly by the shell (`+layout.svelte`), that is called out.
+
+## At a glance
+
+- **Path:** `src/lib/components/` (25 files), plus `src/lib/Sidebar.svelte`.
+- **LOC:** 3 174 (components) + 178 (sidebar) = 3 352.
+- **Conventions:** Svelte 5 runes (`$state`, `$props`, `$derived`, `$effect`). Tailwind v4 utility classes. CSS variables for design tokens. Lucide icons at 16/20/24px with `aria-label` next to or instead of the glyph.
+
+## Shell mounts (always present)
+
+| Component | LOC | Path | Purpose |
+|---|---|---|---|
+| `Sidebar` | 178 | `src/lib/Sidebar.svelte` | Left nav. Switches `page.current`. Collapsed mode shows tooltips. Renders task badge from `tasks.length`. |
+| `Titlebar` | 80 | `src/lib/components/Titlebar.svelte` | Custom window chrome for non Linux (frameless windows). Min/max/close + drag area + sidebar aligned spacer. |
+| `ToastViewport` | 143 | `src/lib/components/ToastViewport.svelte` | Bottom right toast stack. Reads from the global `toasts` store. Honours `prefers-reduced-motion`. |
+| `ResizeHandles` | 67 | `src/lib/components/ResizeHandles.svelte` | Invisible 5 px margins for frameless resize. Linux uses native, so `+layout.svelte` suppresses this. |
+| `FocusTimer` | 298 | `src/lib/components/FocusTimer.svelte` | Floating top right SVG progress ring. Listens for `lumotia:start-timer` window events and delegates to the focus timer store. Cancel hover, success flourish. Hidden on float and viewer windows by URL probe. |
+| `MorningTriageModal` | 356 | `src/lib/components/MorningTriageModal.svelte` | Phase 5 modal. Self gated on `settings.ritualsMorning` and time of day. Mounted globally so it appears over any page. |
+| `TaskSidebar` | 97 | `src/lib/components/TaskSidebar.svelte` | Optional right side dock that appears when `page.taskSidebarOpen`. Quick add input, top tasks, link out to the full Tasks page. |
+
+## Settings building blocks
+
+| Component | LOC | Purpose |
+|---|---|---|
+| `SettingsGroup` | 86 | Native `<details>` based progressive disclosure with animated chevron. Handler hooks (`onopen`) are used by SettingsPage to lazy probe expensive state (model lists, paste backends, etc). |
+| `Toggle` | 98 | iOS style toggle. ARIA switch role. |
+| `SegmentedButton` | 19 | Tiny segmented switch with ARIA radio role. |
+| `HotkeyRecorder` | 217 | Captures a key combo. Uses `utils/hotkeyValidity.ts` to check the combo before persisting. |
+| `ZonePicker` | 36 | Sensory zone (default / focus / dim / etc) picker that maps to a `data-zone` attribute on `<html>`. |
+| `AccessibilityControls` | 112 | Font family, font size, letter spacing, line height, reduce motion, bionic reading. Writes via `updateAccessibility`. |
+| `ImplementationRulesEditor` | 266 | Edits the implementation intentions list ("when X happens, do Y"). Persists via the `implementationIntentions` store. |
+| `ModelDownloader` | 112 | Standalone download panel used inside Dictation when no model is loaded. Subscribes to `model-download-progress`. |
+
+## Card chrome and empty states
+
+| Component | LOC | Purpose |
+|---|---|---|
+| `Card` | 35 | Generic container. Border, padding, optional header. The page level "block" primitive. |
+| `EmptyState` | 22 | Centred icon + title + body slot. Used widely. |
+| `UnicodeSpinner` | 30 | ASCII spinner used while probing or downloading. |
+
+## Tasks
+
+| Component | LOC | Purpose |
+|---|---|---|
+| `WipTaskList` | 153 | Renders task rows with energy chips, completion checkbox, expansion to show micro steps, and a "start focus timer" button (dispatches `lumotia:start-timer`). |
+| `MicroSteps` | 310 | Per task expansion: nudge bus integration, micro step suggestions from the LLM (`lumotia:microstep-generated`), step completion (`lumotia:step-completed`), per task implementation rules. |
+| `EnergyChip` | 106 | Low/medium/high energy selector. Used on task rows and in TasksPage quick add. |
+| `CompletionSparkline` | 92 | 7 day completion bar chart. Animated entrance with 30 ms stagger, respects `prefers-reduced-motion`. Reads from `recentCompletions` store. |
+| `VisualTimer` | 33 | Compact visual timer pill used inside MicroSteps and the float window. |
+
+## Transcripts
+
+| Component | LOC | Purpose |
+|---|---|---|
+| `VirtualSegmentList` | 234 | Virtualised scroll for transcript segments in the viewer window. Uses `utils/virtualList.ts` and `utils/textMeasure.ts` to compute per row heights from current preferences. |
+| `SpeakerButton` | 112 | Trigger TTS playback for a chunk of text. Uses `tts_speak`. Reads from the `speaker` store to debounce concurrent requests. |
+| `LlmStatusChip` | 60 | Pill in the sidebar/dictation surface showing LLM state (idle, generating, downloading, unavailable). Reads `llmStatus` store. |
+
+## Where each component is used
+
+- `Sidebar`: `+layout.svelte` shell only.
+- `Titlebar`: `+layout.svelte`, `float/+layout@.svelte`, `viewer/+layout@.svelte` (when `useCustomChrome`).
+- `ToastViewport`: `+layout.svelte`, `viewer/+layout@.svelte`.
+- `ResizeHandles`: `+layout.svelte` (when `useCustomChrome`).
+- `FocusTimer`: `+layout.svelte`, `float/+layout@.svelte`.
+- `MorningTriageModal`: `+layout.svelte`.
+- `TaskSidebar`: `+layout.svelte` (when `page.taskSidebarOpen`).
+- `Card`, `EmptyState`, `Toggle`, `SegmentedButton`: SettingsPage, DictationPage, HistoryPage, TasksPage, FilesPage.
+- `SettingsGroup`, `HotkeyRecorder`, `ImplementationRulesEditor`, `ZonePicker`, `AccessibilityControls`: SettingsPage.
+- `ModelDownloader`: DictationPage.
+- `WipTaskList`, `MicroSteps`, `EnergyChip`, `CompletionSparkline`: TasksPage and `WipTaskList` reused inside the float window.
+- `VirtualSegmentList`: viewer/+page.svelte.
+- `SpeakerButton`: DictationPage, viewer.
+- `LlmStatusChip`: Sidebar, DictationPage.
+- `UnicodeSpinner`: FirstRunPage, SettingsPage.
+- `VisualTimer`: MicroSteps, float window.
+
+## Watch outs
+
+- `Sidebar.svelte` lives outside `components/`. README debt note 1.
+- `Titlebar` reads `settings.sidebarCollapsed` to mirror the spacer width. Animation timing is driven by `--duration-ui`.
+- `MorningTriageModal` is heavy (356 LOC). Self gates internally; do not move the gate elsewhere or you will pay its cost on every paint.
+- `FocusTimer` detects "secondary window" by URL prefix. If you add a fifth window, update the probe.
+- `CompletionSparkline` animations are the only place that uses CSS keyframes for entrance. Honour reduced motion.
+- Many components receive props with `let { foo = default } = $props();` (Svelte 5 idiom). The minimal `Card`, `EmptyState`, `Toggle`, `SegmentedButton` are good reading order for understanding the runes idiom on this codebase.
+
+## See also
+
+- [Stores](stores.md). The state these components consume.
+- [Actions, utils, types](actions-utils-types.md). The bionic reading action and the typography utilities most components use.
+- [Design system](design-system.md). The brand reference these components target.

docs/architecture-map/01-frontend/design-system.md

@@ -0,0 +1,67 @@
+---
+name: Design system (reference, not live)
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Design system
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Design system
+
+**Plain English summary.** Reference material. The runtime styles live in `src/app.css`. Everything under `src/design-system/` is brand documentation, preview pages, JSX UI kits, and ground truth source for the lumotia-design Claude skill. None of it is imported by the runtime SvelteKit app.
+
+## At a glance
+
+- **Path:** `src/design-system/`
+- **Files:**
+  - `README.md`. Brand and content rules. (Lumotia by CORBEL.)
+  - `SKILL.md`. lumotia-design skill manifest (`user-invocable: true`). The skill copies assets out and writes throwaway HTML or production code on demand.
+  - `colors_and_type.css`. Mirror of the runtime `@theme` tokens for buildless preview pages. Intentional duplication, kept in sync by hand.
+  - `preview/`. 20 buildless HTML spec cards.
+  - `ui_kits/`. JSX recreations (`DictationPage.jsx`, `OtherPages.jsx`, `Sidebar.jsx`) plus an `index.html` and a README.
+
+## What's in here
+
+### `colors_and_type.css`
+
+Mirrors `src/app.css` `@font-face` declarations and (typically) the `@theme` token block, with relative `fonts/...` URLs so preview HTML can render without going through Tailwind/Vite. The file's banner comment is explicit:
+
+> When app.css @theme changes, mirror the change here. There is no automated sync; intentional duplication keeps the preview pages buildless.
+
+### `preview/` (20 HTML files)
+
+Each renders one slice of the system:
+- Brand: `brand-icons.html`, `brand-wordmark.html`.
+- Colour: `colors-accent.html`, `colors-semantic.html`, `colors-surfaces.html`, `colors-text.html`, `colors-zones.html`.
+- Components: `components-buttons.html`, `components-cards.html`, `components-empty-states.html`, `components-inputs.html`, `components-nav.html`, `components-toasts.html`.
+- Spacing and motion: `spacing-motion.html`, `spacing-radii.html`, `spacing-scale.html`, `spacing-shadows.html`.
+- Type: `type-body.html`, `type-headings.html`, `type-transcript-mono.html`.
+
+These are static. Open in any browser.
+
+### `ui_kits/` (JSX, reference only)
+
+Three `.jsx` files plus `index.html` and a README. Reproduce the desktop pages in JSX so prototypes can be built outside the Tauri shell. The README inside ui_kits explains how to use them. They are not imported anywhere from the SvelteKit app.
+
+### Brand language (from README.md)
+
+- Built for the noise allergic. Solarpunk-as-posture, AI-minimisation, ground truth + warmth.
+- Iconography: Lucide, 2 px stroke. 16 px nav, 20 px features, 24 px primary actions. Always paired with a label except OS titlebar controls.
+- Transparency + blur used sparingly: collapsed-sidebar tooltips, float window backdrop, accent-subtle 6% tint. No glassmorphism.
+
+## Why it lives in `src/`
+
+The design system files sit under `src/` so the lumotia-design skill (which runs from this repo) can read ground-truth Svelte source from `lumotia-source/` (a sibling import). The runtime build does not include this folder; it is a reference root.
+
+## Watch outs
+
+- Tokens in `colors_and_type.css` and `app.css` `@theme` can drift. There is no CI check. When you change a token in one, change it in both.
+- `ui_kits/` JSX is not used by the app. Treat it as documentation, not as a future framework migration plan. There is no plan to switch from Svelte to React.
+- Vite (with `sveltekit()` plugin) ignores `.html` files outside `static/` and `.jsx` files outside imports. If anyone adds an `import './design-system/...'` somewhere, the build will start picking up reference material. Do not.
+- The skill is user invocable (`SKILL.md`). External agents may write into `src/design-system/` based on user invocation. Treat the contents as agent-shaped, not human-only.
+
+## See also
+
+- [App shell and styling](app-shell-and-styling.md). The runtime `app.css` that this folder mirrors.
+- [Components](components.md). The Svelte versions of the JSX kits.

docs/architecture-map/01-frontend/frontend-tauri-bridge.md

@@ -0,0 +1,163 @@
+---
+name: Frontend ↔ Tauri bridge
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Frontend ↔ Tauri bridge
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Frontend ↔ Tauri bridge
+
+**Plain English summary.** The complete surface where the Svelte frontend talks to the Rust runtime. Two channels: synchronous request/response via `invoke()`, and asynchronous events via `listen()` / `emit()`. Every command name and every event name the frontend touches is listed here so slice 02 can verify reciprocal mentions.
+
+## At a glance
+
+- **Direction in (Rust → frontend):** events listed under "Tauri events listened to".
+- **Direction out (frontend → Rust):** all `invoke()` commands listed under "Tauri commands invoked".
+- **DOM-only events:** `lumotia:*` `CustomEvent`s on `window`. These never cross the Rust boundary.
+- **Cross-window event:** `lumotia:preferences-changed` is the only one that goes through `emit()`.
+
+## Tauri commands invoked (alphabetical)
+
+Discovered via `grep -rho 'invoke([\"\\']\\([a-zA-Z_][a-zA-Z0-9_]*\\)' src/`. Each name appears at least once in the frontend.
+
+| Command | Caller(s) |
+|---|---|
+| `add_transcript` | `stores/page.svelte.ts:234` (`addToHistory`) |
+| `check_engine` | `pages/SettingsPage.svelte:826` |
+| `check_for_update` | `routes/+layout.svelte:356` |
+| `check_hotkey_access` | `routes/+layout.svelte:86` |
+| `check_llm_model` | `pages/DictationPage.svelte:241`, `pages/SettingsPage.svelte:597` |
+| `check_parakeet_engine` | `pages/SettingsPage.svelte:857` |
+| `check_parakeet_model` | `pages/SettingsPage.svelte:858` |
+| `cleanup_transcript_text_cmd` | `pages/DictationPage.svelte:472` |
+| `complete_task_cmd` | `stores/page.svelte.ts:474` |
+| `copy_to_clipboard` | DictationPage, FilesPage, HistoryPage, viewer/+page, preview/+page |
+| `delete_implementation_rule` | `stores/implementationIntentions.svelte.ts:82` |
+| `delete_llm_model` | `pages/SettingsPage.svelte:660` |
+| `delete_profile_cmd` | `stores/profiles.svelte.ts:93` |
+| `delete_profile_term_cmd` | `stores/profiles.svelte.ts:121` |
+| `delete_task_cmd` | `stores/page.svelte.ts:456` |
+| `delete_transcript` | `stores/page.svelte.ts:320`, `pages/HistoryPage.svelte:285` |
+| `deliver_nudge` | `stores/nudgeBus.svelte.ts:112` |
+| `detect_meeting_processes` | `routes/+layout.svelte:399` |
+| `detect_paste_backends` | `pages/SettingsPage.svelte:850` |
+| `download_llm_model` | `pages/SettingsPage.svelte:619` |
+| `download_model` | `pages/SettingsPage.svelte:929`, `pages/FirstRunPage.svelte:59` |
+| `download_parakeet_model` | `pages/SettingsPage.svelte:988`, `pages/FirstRunPage.svelte:73` |
+| `extract_content_tags_cmd` | `pages/HistoryPage.svelte:433, 470` |
+| `extract_tasks_from_transcript_cmd` | `pages/DictationPage.svelte:491` |
+| `generate_diagnostic_report` | `pages/SettingsPage.svelte:377` |
+| `get_llm_status` | DictationPage, SettingsPage, layout (refresh path) |
+| `get_runtime_capabilities` | `pages/DictationPage.svelte:134`, `pages/SettingsPage.svelte:543` |
+| `is_wayland_session` | `routes/+layout.svelte:82` |
+| `list_audio_devices` | `pages/SettingsPage.svelte:187` |
+| `list_models` | `routes/+layout.svelte:346`, `pages/SettingsPage.svelte:846, 930` |
+| `list_parakeet_models` | `routes/+layout.svelte:347` |
+| `load_llm_model` | `pages/DictationPage.svelte:243`, `pages/SettingsPage.svelte:634` |
+| `load_model` | `pages/DictationPage.svelte:272`, `pages/SettingsPage.svelte:944`, `pages/FirstRunPage.svelte:60` |
+| `load_parakeet_model` | `pages/DictationPage.svelte:270`, `pages/SettingsPage.svelte:1003`, `pages/FirstRunPage.svelte:74` |
+| `log_frontend_error` | `routes/+layout.svelte:282` |
+| `open_preview_window` | `pages/DictationPage.svelte:385` |
+| `open_task_window` | `pages/TasksPage.svelte:231` |
+| `open_viewer_window` | `pages/HistoryPage.svelte:392, 556` |
+| `paste_text` | `pages/DictationPage.svelte:544` |
+| `paste_text_replacing` | `routes/preview/+page.svelte:92` |
+| `prewarm_default_model_cmd` | `routes/+layout.svelte:371` |
+| `probe_system` | `pages/SettingsPage.svelte:822`, `pages/FirstRunPage.svelte:31` |
+| `rank_models` | `pages/FirstRunPage.svelte:32` |
+| `recommend_llm_tier` | `pages/SettingsPage.svelte:587` |
+| `save_diagnostic_report` | `pages/SettingsPage.svelte:405` |
+| `save_preferences` | `stores/preferences.svelte.ts:109` |
+| `start_evdev_hotkey` | `routes/+layout.svelte:129` |
+| `start_live_transcription_session` | `pages/DictationPage.svelte:344` |
+| `stop_evdev_hotkey` | `routes/+layout.svelte:424` |
+| `stop_live_transcription_session` | `pages/DictationPage.svelte:415` |
+| `test_llm_model` | `pages/SettingsPage.svelte:684` |
+| `transcribe_file` | `pages/FilesPage.svelte:76` |
+| `tts_list_voices` | `pages/SettingsPage.svelte:750` |
+| `tts_speak` | `pages/SettingsPage.svelte:769`, `stores/implementationIntentions.svelte.ts:170`, `stores/nudgeBus.svelte.ts:119` |
+| `tts_stop` | `components/SpeakerButton.svelte` (cancel current TTS) |
+| `uncomplete_task_cmd` | `stores/page.svelte.ts:491` |
+| `unload_llm_model` | `pages/SettingsPage.svelte:648` |
+| `update_evdev_hotkey` | `routes/+layout.svelte:127` |
+| `update_profile_cmd` | `stores/profiles.svelte.ts:77` |
+| `update_transcript` | `stores/page.svelte.ts:272`, `routes/viewer/+page.svelte:326` |
+
+Plus any commands invoked by `saveMarkdown.ts` via the dialog/file-write plugin imports rather than direct `invoke`. (Verified the truncated `tts_s...` resolves to `tts_speak` and `tts_stop`; both are listed.)
+
+## Tauri events listened to (Rust → frontend)
+
+| Event | Listener |
+|---|---|
+| `lumotia:hotkey-pressed` | `routes/+layout.svelte:177` (evdev backend) |
+| `lumotia:llm-download-progress` | `pages/SettingsPage.svelte:873` |
+| `lumotia:open-wind-down` | `routes/+layout.svelte:251` (tray menu hook) |
+| `lumotia:preferences-changed` | `routes/+layout.svelte:263`, `routes/float/+layout@.svelte`, `routes/viewer/+layout@.svelte`, `routes/preview/+layout@.svelte:41` |
+| `model-download-progress` | `pages/SettingsPage.svelte:864`, `pages/FirstRunPage.svelte:46`, `components/ModelDownloader.svelte:31` |
+| `parakeet-download-progress` | `pages/SettingsPage.svelte:880`, `pages/FirstRunPage.svelte:50` |
+| `preview-cleanup` | `routes/preview/+page.svelte:141` |
+| `preview-hide` | `routes/preview/+page.svelte:161` |
+| `preview-listening` | `routes/preview/+page.svelte:113` |
+| `task-window-focus` | `routes/float/+layout@.svelte` |
+| `tauri://drag-drop` | `pages/FilesPage.svelte:28` |
+| `tauri://drag-enter` | `pages/FilesPage.svelte:34` |
+| `tauri://drag-leave` | `pages/FilesPage.svelte:35` |
+
+## Tauri events emitted (frontend → Rust or other windows)
+
+| Event | Emitter | Purpose |
+|---|---|---|
+| `lumotia:preferences-changed` | `stores/preferences.svelte.ts` (`broadcastPreferences`) | Cross-window preference sync. |
+| `preview-append` | `pages/DictationPage.svelte:165` | Stream partial text to overlay window. |
+| `preview-listening` | `pages/DictationPage.svelte:381` | Tell overlay to enter listening state. |
+| `preview-cleanup` | `pages/DictationPage.svelte:531` | Tell overlay to enter cleanup state. |
+| `preview-final` | `pages/DictationPage.svelte:539` | Tell overlay to render final text. |
+| `preview-hide` | `pages/DictationPage.svelte:606` | Tell overlay to dismiss. |
+
+## DOM-only `lumotia:*` window events (intra-frontend bus)
+
+| Event | Dispatcher | Listener(s) |
+|---|---|---|
+| `lumotia:focus-timer-cancelled` | `stores/focusTimer.svelte.ts` | `completionStats` (indirectly), components subscribed to focus timer. |
+| `lumotia:focus-timer-complete` | `stores/focusTimer.svelte.ts` | Same as above. |
+| `lumotia:implementation-rules-changed` | `stores/implementationIntentions.svelte.ts` | `ImplementationRulesEditor`. |
+| `lumotia:microstep-generated` | `stores/nudgeBus.svelte.ts` (around micro step generation) | `MicroSteps.svelte`. |
+| `lumotia:morning-triage-finished` | `MorningTriageModal.svelte` | `nudgeBus`. |
+| `lumotia:start-timer` | `WipTaskList.svelte`, `MicroSteps.svelte` | `FocusTimer.svelte` + `focusTimer` store. |
+| `lumotia:step-completed` | `MicroSteps.svelte` | `completionStats` refresh. |
+| `lumotia:task-completed` | `stores/page.svelte.ts` (`completeTask`) | `completionStats`. |
+| `lumotia:task-deleted` | `stores/page.svelte.ts` (`deleteTask`) | `completionStats`. |
+| `lumotia:task-uncompleted` | `stores/page.svelte.ts` (`uncompleteTask`) | `completionStats`. |
+| `lumotia:toggle-recording` | `routes/+layout.svelte` (after hotkey debounce, both backends) | `pages/DictationPage.svelte`. |
+
+## Window APIs
+
+- `getCurrentWindow().minimize()` and `.toggleMaximize()`. `Titlebar.svelte`.
+- `getCurrentWindow().label`. Used to guard hotkey registration to the main window only and to filter own-source preference echoes.
+- `convertFileSrc(absolutePath)`. HistoryPage and viewer use this for `<audio>` elements.
+
+## Plugins
+
+| Plugin | Used by |
+|---|---|
+| `@tauri-apps/plugin-dialog` | `utils/saveMarkdown.ts`, `pages/FilesPage.svelte:handleBrowse`. |
+| `@tauri-apps/plugin-global-shortcut` | `routes/+layout.svelte` (X11 / macOS / Windows hotkey backend). |
+| `@tauri-apps/plugin-autostart` | SettingsPage launch-at-login toggle. |
+| `@tauri-apps/plugin-notification` | Available, used by nudge bus or a related path. Confirm specific call sites. |
+| `@tauri-apps/plugin-opener` | Available, used to open external URLs. Confirm specific call sites. |
+
+## Watch outs
+
+- The truncated grep returned `tts_s...` as a unique prefix. Verify every TTS command name (`tts_speak`, possibly `tts_stop`) against `lib.rs` to make sure the table above is exhaustive.
+- The "preview-*" events have two flavours: `lumotia:` namespaced (`preferences-changed`) and bare (`preview-listening`, `preview-cleanup`, `preview-hide`, `preview-append`, `preview-final`). The bare names are scoped to the overlay window's two-way handshake. Do not rename.
+- `lumotia:open-wind-down` listener is in `+layout.svelte` so the page opens regardless of which window the tray click came from. If you ever isolate windows further, this assumption breaks.
+- `task-window-focus` is the only event sent specifically to the float window.
+- DOM `CustomEvent` handlers do not survive across windows (they are window-local). The tasks list refresh trick on focus relies on this.
+
+## See also
+
+- [Windows and routes](windows-and-routes.md). For the listener mounting points.
+- [Stores](stores.md). For the dispatch points of intra-frontend events.
+- [../02-tauri-runtime/README.md](../02-tauri-runtime/README.md). For the matching Rust handlers (slice 02 will mirror this table from the other side).

docs/architecture-map/01-frontend/i18n.md

@@ -0,0 +1,75 @@
+---
+name: Internationalisation
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Internationalisation
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Internationalisation
+
+**Plain English summary.** svelte-i18n is wired but coverage is intentionally minimal. The infrastructure (loader, persisted choice, Settings selector) is in place so strings can migrate incrementally. Three locales: English (source of truth), Spanish, German. Most strings still render hardcoded.
+
+## At a glance
+
+- **Path:** `src/lib/i18n/`
+- **LOC:** 73 (`index.ts`) + 19 lines per locale JSON.
+- **Key files:**
+  - `src/lib/i18n/index.ts`. Setup, locale detection, public exports.
+  - `src/lib/i18n/locales/en.json`. 19 lines.
+  - `src/lib/i18n/locales/es.json`. 19 lines.
+  - `src/lib/i18n/locales/de.json`. 19 lines.
+- **Library:** `svelte-i18n` 4.0.1.
+
+## What's in here
+
+### `index.ts`
+
+```ts
+import { init, register, locale as svelteLocale } from "svelte-i18n";
+import { derived, get } from "svelte/store";
+
+export type Locale = "en" | "es" | "de";
+
+export const SUPPORTED_LOCALES: { code: Locale; label: string }[] = [
+  { code: "en", label: "English" },
+  { code: "es", label: "Español" },
+  { code: "de", label: "Deutsch" },
+];
+
+const STORAGE_KEY = "lumotia_locale";
+
+register("en", () => import("./locales/en.json"));
+register("es", () => import("./locales/es.json"));
+register("de", () => import("./locales/de.json"));
+
+function detectInitialLocale(): Locale { /* localStorage → navigator.language → "en" */ }
+```
+
+Public exports:
+- `initI18n()`. Idempotent. Called from every layout's `onMount`-ish path (`+layout.svelte:38` and the float/viewer/preview break layouts).
+- `setLocale(code)`. Writes to `lumotia_locale` and updates the svelte-i18n store.
+- `currentLocale`. A derived store that components subscribe to via `$currentLocale`.
+- `SUPPORTED_LOCALES` constant for the picker.
+
+### Locale JSON shape
+
+19 lines per file means roughly a dozen translated strings. Treat the locales as a stub. Most page text is still hardcoded.
+
+## Where it is consumed
+
+- `SettingsPage.svelte:22` imports `_` (the translation function) and `SUPPORTED_LOCALES`, `setLocale`, `currentLocale`. The locale picker UI lives in Settings.
+- A handful of strings inside SettingsPage use `$_('key')`.
+
+## Watch outs
+
+- Adding a new locale is one `register("xx", () => import("./locales/xx.json"))` call plus a `SUPPORTED_LOCALES` entry.
+- Cross window: each window initialises i18n independently via its layout. Locale change persists to `localStorage["lumotia_locale"]`. Float and viewer pick up the new locale on the next mount, not live. Worth wiring a Tauri event if live cross-window translation is needed.
+- The "British English" toggle in `settings.britishEnglish` is a transcription post-processing flag (slice 04 territory), not a UI locale. Not wired through svelte-i18n.
+- Default locale is detected from `navigator.language`. In Tauri, this is the OS locale.
+
+## See also
+
+- [Pages: settings](pages/settings.md). The locale picker UI.
+- [Stores](stores.md). The `currentLocale` derived store.

docs/architecture-map/01-frontend/pages-overview.md

@@ -0,0 +1,65 @@
+---
+name: Pages overview
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Pages overview
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Pages overview
+
+**Plain English summary.** Lumotia has seven main window pages and three secondary window pages. The main window picks which to show by reading `page.current` (a string in the `page` store) and rendering the matching component. The secondary windows are routed by URL (`/float`, `/viewer`, `/preview`).
+
+## At a glance
+
+- **Main window pages live at** `src/lib/pages/*.svelte` (7 files, 6 232 LOC).
+- **Secondary window pages live at** `src/routes/{float,viewer,preview}/+page.svelte` (3 files, 1 361 LOC).
+- **Switch site:** `src/routes/+page.svelte:18-32`.
+- **Driver store:** `src/lib/stores/page.svelte.ts:24-33` (`page.current`).
+- Possible values of `page.current`: `"first-run" | "dictation" | "files" | "tasks" | "history" | "settings" | "shutdown"`. Plus the legacy `"profiles"` which is rewritten to `"settings"` (see README debt note 5).
+
+## Map of pages
+
+### Main window
+
+| Page | File | LOC | One line hook |
+|---|---|---|---|
+| Dictation | `src/lib/pages/DictationPage.svelte` | 1 100 | The hero recording surface. Streams partial transcripts via a Tauri `Channel`, runs the AI cleanup pipeline, paste/copy/export, extracts tasks, fills a template. |
+| Settings | `src/lib/pages/SettingsPage.svelte` | 2 484 | The configuration panel. Audio devices, vocabulary, profiles, templates, model management (Whisper + Parakeet + LLM), hotkey, rituals, nudges, accessibility, diagnostics. |
+| History | `src/lib/pages/HistoryPage.svelte` | 974 | Browse, search, play, edit, star, tag, export saved transcripts. Backed by SQLite FTS5. |
+| Tasks | `src/lib/pages/TasksPage.svelte` | 725 | Inbox/today/soon/later board with energy chips, lists, completion sparkline. |
+| Files | `src/lib/pages/FilesPage.svelte` | 263 | Drop or browse audio/video files. Calls `transcribe_file`. |
+| First run | `src/lib/pages/FirstRunPage.svelte` | 337 | Hardware probe (`probe_system`), model recommendation, model download. Auto exits to dictation. |
+| Shutdown ritual | `src/lib/pages/ShutdownRitualPage.svelte` | 169 | Evening wind down ritual. Triggered from the tray menu via `lumotia:open-wind-down`. |
+
+### Secondary windows (URL routed)
+
+| Window label | URL | File | LOC | One line hook |
+|---|---|---|---|---|
+| `tasks-float` | `/float` | `src/routes/float/+page.svelte` | 481 | Detached pinned tasks window with quick add and list management. |
+| `transcript-viewer` | `/viewer` | `src/routes/viewer/+page.svelte` | 606 | Transcript editor with synced audio playback and per segment editing. |
+| `transcription-preview` | `/preview` | `src/routes/preview/+page.svelte` | 274 | Borderless overlay showing live transcription with copy and revert. |
+
+## How navigation actually happens
+
+- Sidebar buttons set `page.current` directly (`src/lib/Sidebar.svelte:24`).
+- Some flows reach into `page.current` from outside the sidebar:
+  - Hotkey press forces dictation: `+layout.svelte:139, 181`.
+  - First run gate on mount: `+layout.svelte:350`.
+  - Settings page "open evening wind down" button: `SettingsPage.svelte:816`.
+  - Tray menu wind down event: `+layout.svelte:251-254`.
+  - First run completion paths back to dictation: `FirstRunPage.svelte:83, 139, 146, 155`.
+  - Implementation intentions store can route to tasks (`implementationIntentions.svelte.ts:125, 136, 142`).
+  - Shutdown ritual exit: `ShutdownRitualPage.svelte:67`.
+  - TaskSidebar "open tasks page" link: `TaskSidebar.svelte:48`.
+
+## Where the shell tucks pages in
+
+The shell renders sidebar plus a single main slot: `<div class="flex-1 overflow-hidden bg-bg">{@render children()}</div>`. The optional task sidebar (`page.taskSidebarOpen`) can dock a `TaskSidebar` panel beside any main page that is not first run.
+
+## See also
+
+- [Pages: dictation](pages/dictation.md). [settings](pages/settings.md). [history](pages/history.md). [tasks](pages/tasks.md). [files](pages/files.md). [first run](pages/first-run.md).
+- [Windows and routes](windows-and-routes.md). For the route file structure and the secondary windows.
+- [Stores](stores.md). The `page` store that drives the switch.

docs/architecture-map/01-frontend/pages/dictation.md

@@ -0,0 +1,77 @@
+---
+name: Dictation page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Dictation page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → Dictation
+
+**Plain English summary.** This is the recording surface. Press the hotkey or the mic button, watch live partial text stream into a textarea, then on stop run the AI cleanup, extract tasks, copy to clipboard or paste into the focused application. The page handles model loading, the live transcription session, the preview overlay, optional template insertion, and task extraction.
+
+## At a glance
+
+- **Path:** `src/lib/pages/DictationPage.svelte`
+- **LOC:** 1 100
+- **Imports (selected):**
+  - Tauri: `Channel`, `invoke` from `@tauri-apps/api/core`. `emit` from `@tauri-apps/api/event`. `getCurrentWindow` from `@tauri-apps/api/window`.
+  - Stores: `page`, `settings`, `templates`, `profiles`, `addToHistory`, `addTask`, `tasks` from `page.svelte.ts`. `markGenerating`, `markGenerationDone` from `llmStatus.svelte.ts`. `profilesStore` from `profiles.svelte.ts`. `toasts`. `getPreferences` from `preferences.svelte.ts`.
+  - Components: `Card`, `ModelDownloader`, `EmptyState`, `SpeakerButton`.
+  - Utils: `exportTranscript`, `extractTasks`, `pad`, `FEEDBACK_TIMEOUT_MS`, `bionicReading` action, `measurePreWrap`, `transcriptPretextFont`, `transcriptPretextLineHeight`, `playStartCue`, `playStopCue`, `playCompleteCue`.
+  - External: `lucide-svelte` icons (`Mic`, `Loader2`, `SquareCheck`, `AlertTriangle`).
+- **Used by:** `src/routes/+page.svelte:20` when `page.current === "dictation"`. Also forced by global hotkey and first run path.
+
+## What's in here
+
+### Local state (selected)
+
+- `transcript` (string), `segments` (array of `{start, end, text}`).
+- `recording` is on the global `page` store; this page mirrors it.
+- `timerInterval`, `startTime`, `timerText` (mm:ss).
+- Model lifecycle flags: `modelReady`, `modelLoading`, `needsDownload`.
+- AI flags: `aiProcessing`, `aiStatus`, `extractedCount`.
+- Live session: `sessionId`, `drainingSessionId`, `lastResultAt`, `lastLiveActivityAt`, `liveWarning`.
+- Tauri channels (typed): `resultChannel`, `statusChannel` opened by `new Channel(...)`.
+- UI: `showExportMenu`, `saved`, `insertPos` (cursor-based insertion), `activeTemplate`.
+- `runtimeCapabilities` (from `get_runtime_capabilities`, used to decide engine availability and CUDA presence).
+
+### Lifecycle
+
+- `onMount`. Loads `runtimeCapabilities` (`DictationPage.svelte:134`). Sets up the global hotkey custom event listener (`lumotia:toggle-recording`, dispatched from the `+layout.svelte` hotkey path).
+- `onDestroy`. Tears down listeners and timers.
+
+### Recording flow (high level)
+
+1. Toggle from the mic button or the `lumotia:toggle-recording` window event.
+2. If model not ready, ensure model: check `check_engine`, `check_parakeet_engine`, `check_llm_model`, then load via `load_model` / `load_parakeet_model` / `load_llm_model` as required (`DictationPage.svelte:241-272`).
+3. Open two `Channel<message>` instances (`DictationPage.svelte:341-342`) and call `start_live_transcription_session` with the channel handles.
+4. As the backend pushes status and partial result messages, append text to `transcript`, update `segments`, and broadcast `preview-append` to the preview overlay window (`DictationPage.svelte:165, 381, 385`). If the preview is enabled and not already open, `open_preview_window` is invoked.
+5. On stop, call `stop_live_transcription_session`, then run AI cleanup (`cleanup_transcript_text_cmd`) gated on `get_llm_status` (`DictationPage.svelte:464-472`).
+6. Optionally extract tasks via `extract_tasks_from_transcript_cmd` (`DictationPage.svelte:487-491`) and add them via the `addTask` store helper.
+7. Push to history with `addToHistory` (which calls `add_transcript`).
+8. Auto copy and/or auto paste based on `settings.autoCopy` / `settings.autoPaste`. Paste path uses `paste_text` (`DictationPage.svelte:544-554`); fallback to `copy_to_clipboard`.
+9. Emit `preview-cleanup`, `preview-final`, `preview-hide` to drive the overlay state machine (`DictationPage.svelte:531, 539, 606`).
+
+## Tauri command surface
+
+`get_runtime_capabilities`, `check_llm_model`, `load_llm_model`, `load_parakeet_model`, `load_model`, `start_live_transcription_session`, `stop_live_transcription_session`, `open_preview_window`, `get_llm_status`, `cleanup_transcript_text_cmd`, `extract_tasks_from_transcript_cmd`, `paste_text`, `copy_to_clipboard`.
+
+Plus `emit("preview-append" | "preview-listening" | "preview-cleanup" | "preview-final" | "preview-hide")`.
+
+## Watch outs
+
+- The page uses `// @ts-nocheck`. Adding type safety here would catch a class of regressions, especially around the `Channel<T>` payload shape.
+- The cursor based insertion (`insertPos`) is fragile. Editing the textarea while a live session is running can corrupt the segment offset map. Tests around `extractTasks` only cover the post stop path.
+- Multiple paths can flip `recording` (button, hotkey custom event, error early-out). Treat the page as a state machine with a single source of truth and you will save yourself.
+- `extractedCount` is purely cosmetic. It is reset on recording start.
+- The "live activity" stalled detector is timer based (`lastLiveActivityAt`). On a stalled session the user sees `liveWarning`. The recovery path is "stop and start again".
+
+## See also
+
+- [Stores](../stores.md). `page`, `settings`, `llmStatus` reactivity.
+- [Frontend ↔ Tauri bridge](../frontend-tauri-bridge.md). All commands and events.
+- [Components](../components.md). `Card`, `ModelDownloader`, `SpeakerButton`, `EmptyState`.
+- [../03-audio-transcription/README.md](../../03-audio-transcription/README.md). Live session plumbing on the Rust side.
+- [../04-llm-formatting-mcp/README.md](../../04-llm-formatting-mcp/README.md). Cleanup and task extraction commands.

docs/architecture-map/01-frontend/pages/files.md

@@ -0,0 +1,63 @@
+---
+name: Files page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Files page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → Files
+
+**Plain English summary.** Drag and drop or browse local audio/video files for transcription. Same engine as live dictation, just file mode. On finish, results land in the page (preview text, segments) and into `addToHistory`.
+
+## At a glance
+
+- **Path:** `src/lib/pages/FilesPage.svelte`
+- **LOC:** 263
+- **Imports (selected):**
+  - Tauri: `invoke` (core), `listen` (event).
+  - Stores: `settings`, `addToHistory` from `page.svelte.ts`. `profilesStore`. `toasts` (transitive via store helpers).
+  - Components: `Card`, `EmptyState`.
+  - Utils: `exportTranscript`.
+  - External: `Upload` icon from `lucide-svelte`. `@tauri-apps/plugin-dialog` (lazy import).
+
+## What's in here
+
+### Drag and drop
+
+- `onMount` registers three Tauri events:
+  - `tauri://drag-drop` (`FilesPage.svelte:28`). Filters the dropped paths to supported extensions and starts transcription.
+  - `tauri://drag-enter` (`FilesPage.svelte:34`). Sets `isDragOver = true`.
+  - `tauri://drag-leave` (`FilesPage.svelte:35`). Sets `isDragOver = false`.
+- `onDestroy` calls each unlisten.
+
+### Browse
+
+- `handleBrowse()` lazy imports `@tauri-apps/plugin-dialog` and opens with the audio/video filter (`mp3, wav, m4a, mp4, flac, ogg, webm, mov, mkv`).
+
+### Transcription
+
+- Calls `invoke("transcribe_file", { ... })` (`FilesPage.svelte:76`). Receives transcript text + segments.
+- Optional `copy_to_clipboard` on completion.
+- Pushes result into history via the store helper.
+
+### State
+
+- `fileTranscript`, `segments`, `isDragOver`, `progress`, `progressText`, `fileName`, `error`, `transcribing`.
+
+## Tauri command surface
+
+`transcribe_file`, `copy_to_clipboard`. Plus dialog plugin.
+
+## Watch outs
+
+- The drag and drop events require the Tauri config to declare drag drop on the relevant window. If the events do not fire, check `tauri.conf.json` and slice 02.
+- Long files block the UI of this page until `transcribe_file` resolves. There is no abort.
+- The supported extensions list is duplicated between the file dialog filter and (presumably) the Rust side. Drift risk.
+- Multi file drag drop iterates serially. No queue UI.
+
+## See also
+
+- [Pages: dictation](dictation.md). The live counterpart.
+- [Frontend ↔ Tauri bridge](../frontend-tauri-bridge.md).

docs/architecture-map/01-frontend/pages/first-run.md

@@ -0,0 +1,59 @@
+---
+name: First run page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# First run page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → First run
+
+**Plain English summary.** What the user sees the first time they launch Lumotia, before any model is on disk. Probes hardware, recommends a Whisper model size, and downloads the chosen model (Whisper or Parakeet). On success, transitions to the dictation page.
+
+## At a glance
+
+- **Path:** `src/lib/pages/FirstRunPage.svelte`
+- **LOC:** 337
+- **Imports:**
+  - Tauri: `invoke`, `listen`.
+  - Stores: `page`, `settings`, `saveSettings` from `page.svelte.ts`. `toasts`.
+  - Components: `UnicodeSpinner`.
+  - External: `lucide-svelte` (`Download`, `CheckCircle`, `Sunrise`, `Moon`, `Play`).
+- **Includes:** also `ShutdownRitualPage` is imported here (suggesting the "evening ritual" preview lives in this same flow). Verify on read; treat as a coupled flow.
+
+## What's in here
+
+### Probe
+
+- `onMount` calls `probe_system` and `rank_models` (`FirstRunPage.svelte:31-32`) to compute recommended models given the user's RAM, GPU, OS.
+- Sets `probing = false` and renders the recommendation UI.
+
+### Download
+
+- `downloadAndGo(modelId)` (`FirstRunPage.svelte:55-95`):
+  - Subscribes to `model-download-progress` and `parakeet-download-progress` events.
+  - Calls `download_model` then `load_model` (Whisper) or `download_parakeet_model` then `load_parakeet_model`.
+  - On success, sets `ready = true` and routes to dictation (`page.current = "dictation"`).
+  - Computes `estimatedMinutes` from elapsed and progress percent (`derived.by`).
+
+### Triggering
+
+- The shell auto sets `page.current = "first-run"` if `list_models` and `list_parakeet_models` are both empty (`+layout.svelte:346-353`).
+- Skip path: clicking "Get started" without a model lets the user opt out (still routes to dictation).
+
+## Tauri command surface
+
+`probe_system`, `rank_models`, `download_model`, `load_model`, `download_parakeet_model`, `load_parakeet_model`. Events: `model-download-progress`, `parakeet-download-progress`.
+
+## Watch outs
+
+- The download is a single shot. There is no resume on cancel; if the user closes the app mid download, they restart from zero. Slice 02/05 may improve this later.
+- `estimatedMinutes` is a linear extrapolation. Network speed is not constant; expect the value to wiggle.
+- The page imports `ShutdownRitualPage` but the value of doing so should be confirmed (potential dead import).
+
+## See also
+
+- [Pages overview](../pages-overview.md). When this page is forced.
+- [Frontend ↔ Tauri bridge](../frontend-tauri-bridge.md). Probe and download commands.
+- [Windows and routes](../windows-and-routes.md). Shell triggers.

docs/architecture-map/01-frontend/pages/history.md

@@ -0,0 +1,71 @@
+---
+name: History page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# History page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → History
+
+**Plain English summary.** The transcript browser. Lists everything saved to SQLite, full text searchable via FTS5, with inline expansion to read the full body, audio playback, starring, manual + auto tagging, copy, delete, export to Markdown, and "open in viewer" handoff to the dedicated transcript editor window.
+
+## At a glance
+
+- **Path:** `src/lib/pages/HistoryPage.svelte`
+- **LOC:** 974
+- **Imports (selected):**
+  - Tauri: `invoke` and `convertFileSrc` from `@tauri-apps/api/core`.
+  - Stores: `historyStore` helpers from `page.svelte.ts` (`history`, `loadHistory`, `deleteFromHistoryById`, `renameHistoryEntry`), `toasts`, `getPreferences`.
+  - Utils: `deriveAutoTags`, `buildFrontmatter`, `buildMarkdown`, `normaliseTag` (frontmatter). `saveTranscriptAsMarkdown`, `exportTranscriptsToDir` (saveMarkdown). `clampTextLines`, `measurePreWrap` (textMeasure). `bodyPretextLineHeight`, `pretextFontShorthand` (accessibilityTypography). `buildCumulativeOffsets`, `findVisibleRange` (virtualList). `formatTime`, `formatDuration` (time). `PLAYBACK_SPEEDS` (constants).
+  - Components: `Card`, `EmptyState`.
+  - External: `lucide-svelte` (`Search`, `Clock`, `Play`, `Pause`, `FileText`, `Mic`, `ChevronDown`, `ExternalLink`, `Star`, `Tag`).
+
+## What's in here
+
+### List + search
+
+- Loads via `loadHistory` (which calls `list_transcripts` in Rust).
+- Search input filters client side (FTS happens server side via `search_transcripts` for some flows; check `page.svelte.ts`).
+- Virtualised scrolling using `buildCumulativeOffsets` and `findVisibleRange` from `utils/virtualList.ts`. Row heights use `measurePreWrap` to compute pre wrap heights from the live preferences font.
+- Constants: `COLLAPSED_ROW_MIN_HEIGHT`, `COLLAPSED_ROW_VERTICAL_PADDING`, `EXPANDED_BASE_HEIGHT`, `EXPANDED_PADDING`, etc.
+
+### Audio playback
+
+- `convertFileSrc()` maps the saved audio path to a webview URL.
+- Inline `<audio>` element. Speed control uses `PLAYBACK_SPEEDS` (`[0.5, 1, 1.5, 2, 3, 5]`).
+- A `requestAnimationFrame` loop advances `currentTime`. `cancelAnimationFrame` on stop.
+
+### Per row actions
+
+- Star (toggles `starred` flag, persisted via `update_transcript`).
+- Copy (`copy_to_clipboard`).
+- Delete (confirms, then calls `delete_transcript`).
+- Open in viewer window (`open_viewer_window`, then handoff via `localStorage`).
+- Auto tag (calls `extract_content_tags_cmd`, returns suggested tags merged into `tags`).
+- Rename via `renameHistoryEntry` store helper.
+- Export to markdown via `saveTranscriptAsMarkdown`.
+
+### Bulk
+
+- Bulk auto tag walks the visible list and calls `extract_content_tags_cmd` per row.
+- Bulk export to directory via `exportTranscriptsToDir`.
+
+## Tauri command surface
+
+`delete_transcript`, `copy_to_clipboard`, `open_viewer_window`, `extract_content_tags_cmd`. Plus indirect commands from store helpers (`add_transcript`, `update_transcript`, etc) and the dialog plugin used by `saveMarkdown.ts`.
+
+## Watch outs
+
+- Virtual scrolling assumes stable row heights once measured. Toggling preferences (font size, line height) invalidates the measure. The page recomputes on `getPreferences()` change but watch for stutter on rapid changes.
+- The viewer handoff writes the transcript ID to `localStorage`. The viewer window then loads from SQLite. Do not put transcript text in `localStorage`.
+- Auto tag is rate limited only by user clicks. Bulk over a large library can hammer the LLM. Consider a guard if scaling.
+- `convertFileSrc` paths are valid only inside the Tauri webview. If the audio path is missing or moved, `<audio>` will silently fail; show an error state.
+
+## See also
+
+- [Pages: dictation](dictation.md). Where transcripts originate.
+- [Stores](../stores.md). `page.svelte.ts` history helpers.
+- [Frontend ↔ Tauri bridge](../frontend-tauri-bridge.md). Commands referenced.
+- [Windows and routes](../windows-and-routes.md). The viewer window handoff.

docs/architecture-map/01-frontend/pages/settings.md

@@ -0,0 +1,72 @@
+---
+name: Settings page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Settings page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → Settings
+
+**Plain English summary.** The configuration panel. Owns audio device selection, vocabulary, profiles, templates, transcription engine choice and model management (Whisper + Parakeet + LLM), the global hotkey, rituals, nudges, accessibility, text-to-speech, diagnostics, and locale selection. It is by far the largest single file in the frontend at 2 484 lines.
+
+## At a glance
+
+- **Path:** `src/lib/pages/SettingsPage.svelte`
+- **LOC:** 2 484
+- **Imports (selected):**
+  - Stores: `settings`, `saveSettings`, `profiles`, `saveProfiles`, `templates`, `saveTemplates`, `page`, `addProfileTaskList`, `removeProfileTaskList` from `page.svelte.ts`. `getPreferences`, `updatePreferences`. `profilesStore`, `DEFAULT_PROFILE_ID`. `toasts`. `refreshLlmStatus`.
+  - Components: `Card`, `Toggle`, `SegmentedButton`, `HotkeyRecorder`, `ImplementationRulesEditor`, `SettingsGroup`, `ZonePicker`, `AccessibilityControls`.
+  - Utils: `clampTextLines`, `bodyPretextLineHeight`, `pretextFontShorthand`, `formatDuration`.
+  - i18n: `_`, `SUPPORTED_LOCALES`, `setLocale`, `currentLocale`.
+  - External: `lucide-svelte` (`Check`, `Search`, `X`, `Mic`, `BookOpen`, `Type`, `Sparkles`, `SquareCheck`, `Clipboard`, `Sliders`).
+
+## Sections (top level)
+
+Built from `SettingsGroup` accordions. Top level groups (line refs are anchors in the file):
+
+1. **Audio** (`SettingsPage.svelte:1141`). Device list (from `list_audio_devices`), microphone selection.
+2. **Vocabulary** (`SettingsPage.svelte:1191`). Two nested groups:
+   - **Terms and profiles** (`SettingsPage.svelte:1197`). Vocabulary terms attached to the active profile, plus the active profile selector.
+   - **Profiles and templates** (`SettingsPage.svelte:1415`). Two further nested groups:
+     - **Profiles** (`SettingsPage.svelte:1423`). Create, rename, delete; default profile cannot be deleted.
+     - **Templates** (`SettingsPage.svelte:1481`). Per profile templates injected at recording start.
+3. **Processing** (also referred to in file as the engine + AI tier section). Phase 9c style group with `onopen` hook that probes `check_engine`, `check_parakeet_engine`, `list_models`, `detect_paste_backends`, etc.
+4. **Hotkey**. Wraps `HotkeyRecorder`. Search navigation jumps here when the user clicks the hotkey chip in another section (`SettingsPage.svelte:477`).
+5. **Rituals**. Morning triage, evening wind down toggles.
+6. **Nudges and implementation intentions**. Wraps `ImplementationRulesEditor`.
+7. **Accessibility**. Wraps `AccessibilityControls`. Theme, zone (`ZonePicker`), font family, sizes, line height, letter spacing, bionic reading, reduce motion.
+8. **Read aloud (TTS)** (`SettingsPage.svelte:759`). Voice selection from `tts_list_voices`, rate, sample play.
+9. **Diagnostics** (`SettingsPage.svelte:377-405`). Generates and saves a redacted diagnostic report.
+10. **Tasks** (sparkline toggle, relocated in Phase 9c).
+11. **Launch at login**. Wires `@tauri-apps/plugin-autostart`.
+12. **Locale**. svelte-i18n locale picker.
+
+## Key state
+
+- `audioDevices`, `downloadedModels`, `parakeetOk`, `parakeetDownloaded`, `pasteBackends`, `systemInfo`, `runtimeCapabilities`, `llmLoaded`, `llmModels`, `llmStatuses`, `ttsVoices`.
+- Search query (`X`/`Search` icons) drives a force open mode for `SettingsGroup` (`SettingsPage.svelte:432-477`).
+- Three concurrent download progress listeners: Whisper (`model-download-progress`), Parakeet (`parakeet-download-progress`), LLM (`lumotia:llm-download-progress`) (`SettingsPage.svelte:864-880`).
+
+## Tauri command surface
+
+Audio: `list_audio_devices`. Models (Whisper): `list_models`, `download_model`, `load_model`, `check_engine`. Models (Parakeet): `check_parakeet_engine`, `check_parakeet_model`, `download_parakeet_model`, `load_parakeet_model`. Models (LLM): `recommend_llm_tier`, `check_llm_model`, `download_llm_model`, `load_llm_model`, `unload_llm_model`, `delete_llm_model`, `test_llm_model`, `get_llm_status`. Capabilities: `get_runtime_capabilities`, `probe_system`, `detect_paste_backends`. TTS: `tts_list_voices`, `tts_speak`. Diagnostics: `generate_diagnostic_report`, `save_diagnostic_report`. Plus the implicit `save_preferences` invoked by the preferences store on every accessibility toggle.
+
+Events listened to: `model-download-progress`, `parakeet-download-progress`, `lumotia:llm-download-progress`.
+
+## Watch outs
+
+- 2 484 lines, hand rolled accordion, Phase 9c handover already deferred the deeper restructure. New options should be added inside the existing `SettingsGroup` topology rather than threaded into the global header.
+- `settings.theme` ("Light"/"Dark"/"System") is the legacy field; `preferences.theme` is the new one. `+layout.svelte:61-68` re maps every effect cycle. Adding new theme options needs both stores.
+- `page.current = "shutdown"` button at line 816 is the only entrance from settings into the wind down ritual (other than the tray).
+- The `model-download-progress` event payload is shared across Whisper and Parakeet listeners. Take care that progress UI does not cross wires when both downloads run concurrently (rare but possible if `+layout.svelte` triggers a prewarm while Settings is open).
+- The diagnostics path strips secrets in Rust; do not re add raw paths or env values to the report payload here.
+- Accessibility writes go through `preferences` (Tauri persisted) but `settings.fontSize` writes through `localStorage`. Two persistence channels for similar surfaces.
+
+## See also
+
+- [Components](../components.md). `SettingsGroup`, `HotkeyRecorder`, `ImplementationRulesEditor`, `ZonePicker`, `AccessibilityControls`, `Toggle`, `SegmentedButton`.
+- [Stores](../stores.md). `page` settings + profiles + templates. `preferences`. `llmStatus`.
+- [Frontend ↔ Tauri bridge](../frontend-tauri-bridge.md). All command names referenced here.
+- [Internationalisation](../i18n.md). Locale picker.

docs/architecture-map/01-frontend/pages/tasks.md

@@ -0,0 +1,65 @@
+---
+name: Tasks page
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Tasks page
+
+> **Where you are:** [Architecture map](../../README.md) → [Frontend](../README.md) → [Pages overview](../pages-overview.md) → Tasks
+
+**Plain English summary.** The full screen tasks board. Inbox, today, soon, later buckets. Per task energy chips (low/medium/high), per task lists, micro steps, completion sparkline, search, sort, drag to reorder, and a "pop out" button that opens the same tasks in a small persistent floating window via `open_task_window`.
+
+## At a glance
+
+- **Path:** `src/lib/pages/TasksPage.svelte`
+- **LOC:** 725
+- **Imports (selected):**
+  - Stores: from `page.svelte.ts`: `tasks`, `addTask`, `completeTask`, `uncompleteTask`, `deleteTask`, `updateTask`, `setTaskEnergy`, `taskLists`, `addTaskList`, `renameTaskList`, `deleteTaskList`, `settings`, `saveSettings`. From `completionStats.svelte.ts`: `recentCompletions`, `todayCount`.
+  - Components: `WipTaskList`, `EmptyState`, `CompletionSparkline`, `EnergyChip`, `Card`.
+  - Utils: `formatTimestamp` (time). `BUCKET_COLORS`, `EFFORT_LABELS`, `EFFORT_ORDER` (constants).
+  - External: `lucide-svelte` (`SquareCheck`, `Search`, `ExternalLink`, `ChevronLeft`, `ArrowUpDown`, `Plus`, `X`, `ChevronRight`, `Zap`).
+
+## What's in here
+
+### Local state
+
+- `activeBucket` (`"all" | "inbox" | "today" | "soon" | "later"`).
+- `activeListId` (`"all" | "inbox" | <listId>`).
+- `showCompleted`, `quickInput`, `searchQuery`, `sidebarCollapsed`.
+
+### Render
+
+- Quick add input (top). Sets bucket via segmented choice, energy via `EnergyChip`.
+- Filter / sort header. Sort modes use `EFFORT_ORDER` for effort comparisons.
+- Task list body uses `WipTaskList` (which renders rows with `MicroSteps` expansion).
+- "Pop out" icon → `invoke("open_task_window")` (`TasksPage.svelte:231`).
+- Sparkline panel renders `CompletionSparkline` if `settings.showMomentumSparkline` is true.
+
+### Stores it depends on
+
+- `tasks` (live array). `taskLists`. `recentCompletions` for the sparkline.
+
+### Events
+
+- Listens implicitly to: `lumotia:task-completed`, `lumotia:task-uncompleted`, `lumotia:task-deleted`, `lumotia:step-completed` are emitted from store helpers and consumed by `completionStats.svelte.ts` to refresh the sparkline.
+
+## Tauri command surface (direct)
+
+- `open_task_window` (page action).
+
+The store helpers used here call into Rust through `add_task_cmd`, `complete_task_cmd`, `uncomplete_task_cmd`, `delete_task_cmd`, plus list management commands (`*_task_list_cmd`).
+
+## Watch outs
+
+- Drag and drop is heavy on this page. Reorder mutations should always go via the store helpers; do not manipulate `tasks` directly or you will desync the SQLite source of truth.
+- The sparkline is gated on `settings.showMomentumSparkline` (true by default). It re renders on the four `lumotia:task-*` events, plus window focus for date rollover.
+- "Pop out" deliberately does not pass any state. The float window reads the same store, which is shared via store hydration on mount and `localStorage` for `settings`.
+- Sort, filter, search are not persisted. Reload returns to defaults.
+
+## See also
+
+- [Components](../components.md). `WipTaskList`, `MicroSteps`, `EnergyChip`, `CompletionSparkline`.
+- [Stores](../stores.md). `page` task helpers, `completionStats`.
+- [Windows and routes](../windows-and-routes.md). The float window equivalent.

docs/architecture-map/01-frontend/stores.md

@@ -0,0 +1,130 @@
+---
+name: Stores
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Stores
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Stores
+
+**Plain English summary.** Reactive state. Lumotia uses Svelte 5 runes (`$state`, `$derived`, `$effect`) instead of legacy stores. Each file under `src/lib/stores/` exports one (or more) `$state` objects plus the helper functions that read or mutate them. Components import the state directly and Svelte tracks reactivity automatically. Two persistence channels: `localStorage` for settings, profiles, task lists, templates; Tauri (`save_preferences`) for accessibility preferences.
+
+## At a glance
+
+- **Path:** `src/lib/stores/`
+- **Files:** 10 (4 085 LOC across stores + utils + types).
+- **Cross window sync:**
+  - `localStorage` `storage` event in the float window for settings.
+  - Tauri `emit("lumotia:preferences-changed")` for preferences (handled by every layout).
+- **Persistence keys:** `lumotia_settings`, `lumotia_profiles`, `lumotia_task_lists`, `lumotia_templates`, `lumotia_locale`, plus a viewer handoff key.
+
+## The stores
+
+### `page.svelte.ts` (697 LOC). The big one.
+
+Owns:
+- `page` (`PageState`): `current`, `status`, `statusColor`, `activeProfile`, `recording`, `timerText`, `handedness`, `taskSidebarOpen`. Initial: `current = "dictation"`.
+- `settings` (`SettingsState`). Persisted to `localStorage["lumotia_settings"]` via `utils/settingsMigrations.ts`. Defaults at line 60 onward. Includes engine choice, model size, language, device, format mode, fillers, anti hallucination, British English, auto copy/paste, transcription preview, meeting auto capture (+ apps list), sound cues + volume, timestamps, theme, font size, AI tier, LLM model id and prompt preset, GPU concurrency, prewarm flag, save audio, output folder, global hotkey, sidebar collapsed, microphone device, energy state, match my energy, TTS voice + rate, rituals (morning/evening + time), launch at login, ritualsPromptSeen, nudges (enabled/muted/speakAloud), showMomentumSparkline.
+- `profiles`, `templates`, `taskLists` arrays.
+- `tasks` and `history` arrays.
+
+Helpers (selected, with line refs):
+- `addToHistory` → `add_transcript` (`page.svelte.ts:234`).
+- `mapTranscriptRow`, `saveTranscriptMeta` → `update_transcript` (`page.svelte.ts:272`).
+- `deleteFromHistoryById` → `delete_transcript` (`page.svelte.ts:320`).
+- `addTask`, `completeTask`, `uncompleteTask`, `deleteTask`, `setTaskEnergy`, `updateTask` → matching `*_task_cmd` Rust commands. `completeTask` and friends emit `lumotia:task-completed | -uncompleted | -deleted` window events (line 470 onward).
+- Task lists: `addTaskList`, `renameTaskList`, `deleteTaskList`, `moveTaskList`, `sortTaskLists`, `moveTaskToList`, `moveTaskListToProfile`.
+- Profile mutators: `addProfileTaskList`, `removeProfileTaskList`.
+- `saveSettings`, `saveProfiles`, `saveTemplates` write to `localStorage`.
+
+### `preferences.svelte.ts` (172 LOC).
+
+Owns the `Preferences` shape: `theme` ("light" | "dark" | "system"), `zone` ("default" | ...), `accessibility` (`fontFamily`, `fontSize`, `letterSpacing`, `lineHeight`, `transcriptSize`, `bionicReading`, `reduceMotion`).
+
+- DOM is the source of truth at runtime: `readFromDOM()` reads `<html>` data attributes and CSS variables; `applyToDOM(prefs)` writes them.
+- Persists via `invoke("save_preferences", { preferences: JSON.stringify(prefs) })` with a debounce. Failure shows a single toast per process (`preferences.svelte.ts:101-120`).
+- Cross window: `broadcastPreferences` calls `emit("lumotia:preferences-changed", { source, prefs })`. Receivers in `+layout.svelte` and the secondary `+layout@.svelte` files apply external prefs after a label check.
+- Exposes `getPreferences`, `updatePreferences`, `updateAccessibility`, `applyExternalPreferences`, `PREFERENCES_CHANGED_EVENT` constant.
+- Font families resolved from a constant map (Lexend, Atkinson, OpenDyslexic).
+
+### `profiles.svelte.ts` (123 LOC).
+
+The vocabulary profile store (separate from the `profiles` array on `page.svelte.ts`). Holds:
+- `activeProfileId`, list of profiles, vocabulary terms.
+
+Tauri commands: `load_profiles_cmd` (implicit on load), `update_profile_cmd`, `delete_profile_cmd`, `delete_profile_term_cmd`, plus add term commands.
+Exposes `DEFAULT_PROFILE_ID`.
+
+### `toasts.svelte.ts` (99 LOC).
+
+Toast notifications. State is an array of `{id, severity, title, body, duration}`.
+
+Helpers: `toasts.info(title, body?)`, `.warn`, `.error`, `.success`, plus `dismiss(id)`. Auto dismiss via `setTimeout`. Read by `ToastViewport.svelte`.
+
+### `llmStatus.svelte.ts` (64 LOC).
+
+Tracks the LLM lifecycle pill. State is one of `idle | loading | generating | downloading | unavailable`.
+
+- `refreshLlmStatus(aiTier)` calls `get_llm_status` and updates the chip.
+- `markGenerating()`, `markGenerationDone()` are called around `cleanup_transcript_text_cmd` in `DictationPage.svelte`.
+
+### `completionStats.svelte.ts` (59 LOC).
+
+Phase 8 gamification. Owns `recentCompletions` (`DailyCompletionCount[]`) and a `todayCount` derivation.
+
+Refresh triggers (no polling): module load, `lumotia:task-completed`, `lumotia:step-completed`, `lumotia:task-uncompleted`, `lumotia:task-deleted`, window focus (for midnight rollover).
+
+### `focusTimer.svelte.ts` (238 LOC).
+
+Owns the floating focus timer. State: target ms, started at, label, taskId, paused.
+
+- `setInterval` at 250 ms (`TICK_INTERVAL_MS`).
+- Triggered by `lumotia:start-timer` window events. Emits `lumotia:focus-timer-cancelled` and `lumotia:focus-timer-complete` on transitions.
+
+### `implementationIntentions.svelte.ts` (260 LOC).
+
+"When X happens, do Y" rules engine. Owns the rules array.
+
+- 30 second `setInterval` (`TIME_RULE_POLL_MS`) checks time based rules.
+- On match, can route `page.current = "tasks"` (lines 125, 136, 142) and call `tts_speak` if speak aloud is enabled (line 170).
+- Uses `delete_implementation_rule` to remove a rule (line 82).
+- Emits `lumotia:implementation-rules-changed` after writes.
+- Lifecycle: `startImplementationIntentions`, `stopImplementationIntentions` from `+layout.svelte`.
+
+### `nudgeBus.svelte.ts` (292 LOC).
+
+Owns the nudge engine. Two `setInterval` handles:
+- `blurCheckHandle` for window blur detection.
+- `triagePollHandle` at 5 minute cadence checking morning triage triggers.
+- Plus a `microStepTimers` Map for per task delayed notifications.
+
+Key commands: `deliver_nudge` (line 112), `tts_speak` (line 119).
+Emits `lumotia:morning-triage-finished` after the modal closes.
+Lifecycle: `startNudgeBus`, `stopNudgeBus` from `+layout.svelte`.
+
+### `speaker.svelte.ts` (10 LOC).
+
+Tiny. Holds `speakingId` so `SpeakerButton` instances can debounce / cancel each other. Candidate for collapsing into a util (README debt note 9).
+
+## Cross store traffic
+
+- `DictationPage.completeRecording()` → `addToHistory` (page) → `add_transcript` Rust → push to history.
+- `MicroSteps` "start timer" button → `lumotia:start-timer` → `focusTimer` store transitions → `FocusTimer` component renders ring.
+- `TasksPage.addTask` → `tasks` store → emits `lumotia:task-completed/...` → `completionStats` refreshes → `CompletionSparkline` re renders.
+- `SettingsPage` accessibility toggle → `updatePreferences` → DOM write + `save_preferences` invoke + `lumotia:preferences-changed` emit → secondary windows mirror.
+- Float window settings sync uses `localStorage` `storage` event, not the Tauri preference event. Drift candidate.
+
+## Watch outs
+
+- `page.svelte.ts` is doing a lot. Splitting transcripts, tasks, task lists, settings, profiles into separate stores would help but is outside this map's job.
+- `settings` and `preferences` overlap (theme, font size, `transcriptSize`). Settings are localStorage only; preferences are Tauri persisted. Race possible during the migration `$effect`.
+- `nudgeBus` and `implementationIntentions` both run timers. They are torn down in `+layout.svelte` `onDestroy`. Only the main window starts them.
+- `completionStats` listens on the DOM `window` for events; it does not subscribe to `tasks` directly. Adding a new task mutation that does not emit one of the `lumotia:task-*` events will silently break the sparkline.
+
+## See also
+
+- [Components](components.md). Consumers.
+- [Frontend ↔ Tauri bridge](frontend-tauri-bridge.md). The `invoke` and `emit` calls per store.
+- [Actions, utils, types](actions-utils-types.md). `settingsMigrations`, `errors`, `storage`, `time`, `osInfo`, `runtime` helpers used by stores.

docs/architecture-map/01-frontend/windows-and-routes.md

@@ -0,0 +1,119 @@
+---
+name: Windows and SvelteKit routes
+type: architecture-map-page
+slice: 01-frontend
+last_verified: 2026/05/09
+---
+
+# Windows and routes
+
+> **Where you are:** [Architecture map](../README.md) → [Frontend](README.md) → Windows and routes
+
+**Plain English summary.** Lumotia is a single SvelteKit build that runs as multiple desktop windows. The Rust side opens four webviews (main, tasks float, transcript viewer, transcription preview) and points each one at a different SvelteKit route. The frontend uses SvelteKit's `+layout@.svelte` "break" trick so secondary windows skip the main shell (sidebar, titlebar, toast viewport) and render a focused, single purpose UI.
+
+## At a glance
+
+- **Path:** `src/routes/`
+- **LOC:** 2 740 across the route tree.
+- **Key files:**
+  - `src/routes/+layout.js:5`. Disables SSR. Adapter is `adapter-static` with `index.html` fallback (`svelte.config.js:6`). The whole tree is SPA only.
+  - `src/routes/+layout.svelte`. The shell. Sidebar, custom titlebar (non Linux only), toast viewport, focus timer overlay, morning triage modal, resize handles, global hotkey wiring, OS detection, profile load, first run gate, error capture.
+  - `src/routes/+page.svelte`. The main window's page switch (`page.current` → 7 page modules).
+  - `src/routes/float/+layout@.svelte`. "Break" layout for the tasks float window.
+  - `src/routes/float/+page.svelte`. Tasks float window UI.
+  - `src/routes/viewer/+layout@.svelte`. Break layout for the transcript editor window.
+  - `src/routes/viewer/+page.svelte`. Transcript editor with audio playback.
+  - `src/routes/preview/+layout@.svelte`. Break layout for the live transcription preview overlay.
+  - `src/routes/preview/+page.svelte`. Preview state machine: listening → live → cleanup → final.
+- **Imports:**
+  - Internal: every store, plus shell components (`Sidebar`, `TaskSidebar`, `Titlebar`, `ToastViewport`, `ResizeHandles`, `FocusTimer`, `MorningTriageModal`).
+  - External: `@tauri-apps/api/core` (invoke, Channel, convertFileSrc), `@tauri-apps/api/event` (listen, emit), `@tauri-apps/api/window` (getCurrentWindow), `@tauri-apps/plugin-global-shortcut`, `@tauri-apps/plugin-dialog`, `lucide-svelte`.
+- **Used by:** Tauri (slice 02). Window labels are `main`, `tasks-float`, `transcript-viewer`, `transcription-preview`. Each is created with the matching route URL.
+
+## What's in here
+
+### `src/routes/+layout.js` (5 LOC)
+
+Single line: `export const ssr = false;`. Tauri has no Node server, so SvelteKit must run as a SPA.
+
+### `src/routes/+layout.svelte` (493 LOC)
+
+The shell. Mounts on every window (the secondary windows then render only `{@render children()}` and suppress the chrome).
+
+Responsibilities:
+- Initialise svelte-i18n (`initI18n()` is idempotent across windows, `+layout.svelte:38`).
+- Detect Tauri runtime (`hasTauriRuntime`) and OS (`loadOsInfo`). Linux uses native KWin/Mutter decorations; macOS and Windows render the custom `Titlebar` plus invisible `ResizeHandles`. Default `useCustomChrome = false` to avoid a flash on Linux (`+layout.svelte:49`).
+- Hotkey backend selection. On Wayland, attempt the evdev backend (`check_hotkey_access`). Otherwise fall back to `tauri-plugin-global-shortcut`. Falls back to "unavailable" if neither path works (`+layout.svelte:76-102`).
+- Hotkey registration. Only the `main` window owns the global shortcut. The function debounces evdev autorepeat at 120 ms (Handy issue #1143 referenced in comments, `+layout.svelte:171-186`).
+- Cross window listeners: `lumotia:hotkey-pressed` (evdev path), `lumotia:open-wind-down` (tray menu), `lumotia:preferences-changed` (sync prefs across windows). Apply external preferences if the source label differs from our own.
+- Theme migration `$effect`. Reads `settings.theme` (legacy "Light" / "Dark" / "System") and writes `preferences.theme` ("light" / "dark" / "system"). See README debt note 2.
+- Font size CSS variable `--font-size-transcript` set on `<body>` from `settings.fontSize`.
+- Global error capture. `window.onerror` and `unhandledrejection` forward to `log_frontend_error` Rust command. Best effort, swallow throws.
+- First run check on mount. If `list_models` and `list_parakeet_models` both return empty arrays, switch `page.current` to `"first-run"`.
+- Background update check via `check_for_update`. Toast on result.
+- Pre warm default model on mount if `settings.prewarmModelOnStartup` (calls `prewarm_default_model_cmd`).
+- Meeting auto capture poller (`$effect`). When `settings.meetingAutoCapture` is true, polls `detect_meeting_processes` every 15 s with the configured patterns (default `["zoom", "teams"]`). Edge triggered (toast only on first match per session). Tear down on effect re run.
+- Sidebar collapse heuristic. `[` toggles, narrow viewport collapses automatically.
+- Render branches: `isSecondaryWindow` (URL starts with `/float` or `/viewer`) renders only children. Otherwise: optional Titlebar, sidebar (hidden on first run), main slot, optional task sidebar (when `page.taskSidebarOpen`).
+- Always rendered alongside: `<ToastViewport />`, `<FocusTimer />`, `<MorningTriageModal />`, `<ResizeHandles />` (custom chrome only).
+
+### `src/routes/+page.svelte` (33 LOC)
+
+Pure dispatcher. Switches the seven page modules from `page.current`:
+- `first-run` → `FirstRunPage`
+- `dictation` → `DictationPage`
+- `files` → `FilesPage`
+- `tasks` → `TasksPage`
+- `history` → `HistoryPage`
+- `settings` → `SettingsPage`
+- `shutdown` → `ShutdownRitualPage`
+
+Also redirects the legacy `page.current === "profiles"` to `"settings"` via `$effect` (debt note 5).
+
+### `src/routes/float/+layout@.svelte` (99 LOC)
+
+The `@.svelte` suffix tells SvelteKit to skip parent layouts. Reimports `app.css`, mounts `Titlebar` (non Linux) and `FocusTimer`, applies the same theme migration `$effect`, listens on the browser `storage` event (not Tauri events) to sync `settings` from main window writes, and handles the `task-window-focus` Tauri event to glow and auto focus the quick add input.
+
+### `src/routes/float/+page.svelte` (481 LOC)
+
+Tasks float window. Self contained quick add, list filter, sort menu, completed toggle, list management (rename, delete, reorder, move to profile), drag and drop reordering. Reads tasks straight from the `page.svelte.ts` store helpers. No `invoke()` calls of its own; mutations go via `addTask`, `completeTask`, etc, which then call Rust.
+
+### `src/routes/viewer/+layout@.svelte` (77 LOC)
+
+Same break layout pattern. Mounts `Titlebar`, `ToastViewport`, applies preferences sync via `lumotia:preferences-changed`, applies theme.
+
+### `src/routes/viewer/+page.svelte` (606 LOC)
+
+Transcript editor. Hydrates from a transcript ID handed off via `localStorage` (`lumotia:viewer-handoff` style key, see file). Fetches the full row from SQLite via `get_transcript`. Renders an `<audio>` element using `convertFileSrc()` to map the saved audio path to a webview URL. Provides per segment editing, debounced autosave through `saveTranscriptMeta`, virtual scrolling via `VirtualSegmentList`, playback speed control (`PLAYBACK_SPEEDS`), starring and tagging.
+
+### `src/routes/preview/+layout@.svelte` (68 LOC)
+
+Mounts only what the overlay needs: theme, preferences sync. No sidebar, no titlebar, no toast viewport.
+
+### `src/routes/preview/+page.svelte` (274 LOC)
+
+Live transcription overlay. Listens for `preview-listening`, `preview-cleanup`, `preview-hide` (and reads partial text via the same `Channel` pattern as Dictation, in some flows). State machine: `listening → live → cleanup → final → auto hide`. Provides a copy button (uses `navigator.clipboard.writeText` first, falls back to `copy_to_clipboard` invoke) and a revert to raw button. Auto hide timer constants live at the top of the file.
+
+## Data flow
+
+- Window creation: Rust opens four webviews and routes them to `/`, `/float`, `/viewer`, `/preview`. The same JS bundle loads in each.
+- Cross window state:
+  - `localStorage` carries `lumotia_settings` and the viewer handoff payload. Float window listens on the browser `storage` event to mirror settings.
+  - Tauri events carry preferences (`lumotia:preferences-changed`), tray driven navigation (`lumotia:open-wind-down`), and float window focus (`task-window-focus`).
+- Hotkey: only the main window registers, but every window's layout includes the migration `$effect`. The label guard at `+layout.svelte:115-121` prevents secondary windows from re registering.
+- First run gating: only the main window evaluates and sets `page.current = "first-run"`. The float/viewer/preview windows skip the shell altogether.
+
+## Watch outs
+
+- The `useCustomChrome` flash is mitigated by defaulting to `false` on Linux. If you ever flip the default, expect a one frame flash of custom chrome before `loadOsInfo()` resolves.
+- The break layouts duplicate the theme migration `$effect`. Touch one, touch all. Same for `applyExternalPreferences` listeners.
+- `transcription-preview` is a borderless overlay with `WindowTypeHint = Utility`. Layout assumptions about chrome height do not apply.
+- `+layout.svelte` calls `applyExternalPreferences` only after a payload `source` check. If you ever add a fifth window, its label must be propagated correctly or the window will echo its own preference writes.
+- Drag drop on `FilesPage.svelte` listens on `tauri://drag-drop` events, which require the window to declare drag drop in `tauri.conf.json`. Slice 02 owns that surface.
+
+## See also
+
+- [Pages overview](pages-overview.md). What `page.current` ends up rendering.
+- [Frontend ↔ Tauri bridge](frontend-tauri-bridge.md). Every command and event referenced above.
+- [App shell and styling](app-shell-and-styling.md). The CSS plumbing that the shell relies on.
+- [../02-tauri-runtime/README.md](../02-tauri-runtime/README.md). Window creation, tray, and the matching event surface.

docs/architecture-map/02-tauri-runtime/README.md

@@ -0,0 +1,70 @@
+---
+name: Slice 02 — Tauri runtime
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/12
+---
+
+# Slice 02 — Tauri runtime
+
+> **Where you are:** [Architecture map](../README.md) → Tauri runtime
+
+**Plain English summary.** The Tauri runtime is the bridge between Lumotia's Svelte frontend and the Rust workspace crates. It owns app startup (database init, panic hook, plugin wiring, preferences injection), the system tray, the secondary windows (task float, transcript viewer, transcription preview), and the entire `#[tauri::command]` surface that the frontend invokes for audio capture, transcription, LLM cleanup, task and transcript CRUD, paste, TTS, hotkeys, diagnostics, and more. Everything that runs on the host process but is not pure crate logic lives here.
+
+## At a glance
+
+- Path: `src-tauri/`
+- Total LOC (Rust + Cargo + JSON, excluding `gen/`): ~8,690.
+- Tauri version: `2` (see `src-tauri/Cargo.toml:44`).
+- Bundle identifier: `uk.co.corbel.lumotia` (`src-tauri/tauri.conf.json:5`).
+- Plugins (always-on): `tauri-plugin-opener`, `tauri-plugin-dialog`, `tauri-plugin-notification`.
+- Plugins (desktop-only, gated `cfg(not(target_os = "android"))`): `tauri-plugin-global-shortcut`, `tauri-plugin-autostart` (LaunchAgent), `tauri-plugin-window-state`. The `tray-icon` Tauri feature is also desktop-only.
+- Workspace crates pulled in: `lumotia-core`, `lumotia-audio`, `lumotia-transcription` (default-features off, `whisper` re-enabled here), `lumotia-ai-formatting`, `lumotia-storage`, `lumotia-cloud-providers`, `lumotia-hotkey`, `lumotia-llm`.
+- Tauri commands exposed via `invoke_handler` in `src-tauri/src/lib.rs:321`: 71 commands.
+- Capability files: `src-tauri/capabilities/main.json` (main window) and `src-tauri/capabilities/secondary-windows.json` (task float, transcript viewer, transcription preview).
+- Command modules: 22 `#[tauri::command]` modules plus 3 utility modules (`mod.rs`, `power.rs`, `security.rs`).
+- Integration tests: `src-tauri/tests/config_hardening.rs` (3 tests guarding CSP, updater signing, secondary-window permissions).
+
+## Map of this slice
+
+App boot, config, tests:
+
+- [App lifecycle](app-lifecycle.md). `src-tauri/src/main.rs` and `src-tauri/src/lib.rs`. Run entry, AppState construction, plugin wiring, preferences injection, Linux launcher-env warning, panic hook, error-log pruning, command registration.
+- [System tray](system-tray.md). Desktop-only tray icon and menu (`src-tauri/src/tray.rs`).
+- [Tauri config](tauri-config.md). `tauri.conf.json` plus the Linux native-decorations overlay; CSP, window defaults, bundle settings.
+- [Capabilities and ACL](capabilities-and-acl.md). The two ACL files in `capabilities/`, what each scopes, and the Phase 9 high-risk-permission firewall.
+- [Cargo and features](cargo-and-features.md). `Cargo.toml`, the `whisper` cargo feature, the per-target dependency blocks, `build.rs`, `.cargo/config.toml`.
+- [Tests](tests.md). Config-hardening regression tests.
+
+Command modules (entry index):
+
+- [Commands index](commands/README.md). Every command file with a one-liner.
+
+Individual command pages (linked from the commands index):
+
+- [Audio capture](commands/audio.md), [Live transcription](commands/live.md), [Paste at cursor](commands/paste.md), [Models registry and runtime](commands/models.md), [Transcription](commands/transcription.md), [Local LLM](commands/llm.md), [Text to speech](commands/tts.md), [Tasks and decomposition](commands/tasks.md), [Transcripts CRUD](commands/transcripts.md), [Diagnostics and reports](commands/diagnostics.md), [Implementation intentions](commands/intentions.md), [Profiles](commands/profiles.md), [Window management](commands/windows.md), [Hotkey bridge](commands/hotkey.md), [Feedback capture](commands/feedback.md), [Power assertions and security](commands/power-and-security.md), [Small commands](commands/small-commands.md), [mod.rs registration](commands/mod.md).
+
+## How this slice connects to others
+
+- **Frontend (slice 01).** Every `#[tauri::command]` is invoked from Svelte via `@tauri-apps/api/core` `invoke()`. Events emitted via `app.emit(...)` are consumed via `listen()` in the frontend. Live transcription uses typed `tauri::ipc::Channel` instead of plain events; the channel pair is created on the JS side and passed in as command args.
+- **Audio + transcription (slice 03).** `commands::audio` calls `lumotia_audio::{MicrophoneCapture, WavWriter, decode_audio_file_limited, resample_to_16khz, probe_audio_duration_secs}`. `commands::transcription` and `commands::live` call `lumotia_transcription::LocalEngine` plus `lumotia_audio::StreamingResampler`. `commands::models` calls `lumotia_transcription::{model_manager, load_whisper, load_parakeet}`.
+- **LLM + formatting + MCP (slice 04).** `commands::llm` calls `lumotia_llm::{LlmEngine, model_manager, ContentTags, LlmModelId}` and `lumotia_ai_formatting::{llm_cleanup_text, LlmPromptPreset}`. `commands::tasks` calls `lumotia_llm::prompts::FeedbackExample` and the engine's `decompose_task_with_feedback` / `extract_tasks_with_feedback` / `extract_content_tags`. `commands::transcription` and `commands::live` call `lumotia_ai_formatting::{post_process_segments, FormatMode, PostProcessOptions}`. `commands::profiles` calls `lumotia_ai_formatting::extract_corrections` for auto-learned vocabulary.
+- **Core + storage + hotkey + build (slice 05).** Everything DB-touching goes through `lumotia_storage` (`init`, `database_path`, `get_setting`, `set_setting`, `prune_error_log`, the full set of CRUD helpers, `app_data_dir`, `crashes_dir`, `logs_dir`, `list_recent_errors`, `log_error`). `commands::hardware` and `commands::models` call `lumotia_core::{hardware, model_registry, recommendation, types, constants}`. `commands::meeting` calls `lumotia_core::process_watch`. `commands::hotkey` is a thin Tauri wrapper around `lumotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent}`. `build.rs` is the build-system half of the slice (CSP regression guard plus ggml multi-definition link arg).
+
+## Open questions / debt
+
+- `commands/live.rs` is 1,737 LOC. The runtime, loop state, speech gate, dedup, and chunking logic share the file. Splitting per concern would track against the broader refactor pass already mooted in the in-repo code review (`docs/code-review-2026-04-22.md`). See [`commands/live.md`](commands/live.md) for the breakdown.
+- `commands::update::install_update` returns a hard-coded "Updates are disabled until release signing is configured." (`src-tauri/src/commands/update.rs:15`). The integration test `updater_is_signed_or_absent` (`src-tauri/tests/config_hardening.rs:35`) only asserts that *if* an updater config ships, it carries a non-empty pubkey. There is currently no updater config in `tauri.conf.json`, so the test is an empty no-op.
+- `commands::power::PowerAssertion` is a no-op on Linux and Windows (`src-tauri/src/commands/power.rs:90`). Only macOS has a real implementation via `objc2`. The doc comment promises `SetThreadExecutionState` (Windows) and logind inhibitors (Linux), but neither is wired up. Symptom: long live-dictation sessions on Linux can be idled by the compositor.
+- `src-tauri/.cargo/config.toml` hard-codes `LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"` (Windows). It is harmless on non-Windows hosts (env var is just unused) but it is a foot-gun if someone moves Clang elsewhere on Windows. See [Cargo and features](cargo-and-features.md).
+- The Linux rendering workaround in `lib.rs` (`warn_if_x11_env_unset_on_wayland`) now warns when the launcher has not set the expected env vars; it no longer mutates the process environment. In development, `run.sh` / `npm run dev:tauri` owns the defaults (`WEBKIT_DISABLE_DMABUF_RENDERER=1` on Linux; `GDK_BACKEND=x11` and `WINIT_UNIX_BACKEND=x11` on Wayland). The user opt-out remains `WEBKIT_DISABLE_DMABUF_RENDERER=0`, set before launching.
+- `commands::diagnostics::install_panic_hook` writes a "minimal text dump" without backtraces unless the user has `RUST_BACKTRACE=1` set (`src-tauri/src/commands/diagnostics.rs:42`). The packaged binary does not set it, so production crash dumps will lack stack traces. Document or default-enable.
+- `commands::audio::list_audio_devices` is gated `ensure_main_window` but the `secondary-windows` capability does not invoke it, which is correct. The `clipboard::copy_to_clipboard` command, by contrast, has no main-window guard and any window with the `core:default` permission can call it; intentional, but worth flagging.
+
+## Existing in-repo docs
+
+- `docs/code-review-2026-04-22.md`. The MAJOR / MINOR review that motivated several of the safety helpers seen here (the parallel-mode loopback CSP guard in `build.rs`, secondary-window high-risk-permission test, RB-06 worker-join in `commands::audio`, RB-07 `compose_accelerators` in `commands::models`, RB-08 macOS App Nap power assertion in `commands::power`).
+- `docs/issues/`. Open issue threads, several of which the diagnostic-report bundler exists to feed.
+- `docs/whisper-ecosystem/brief.md`. Source of the numbered "brief items" cited in code comments (item #2 = loopback LLM CSP, item #9 = App Nap, items #10/#17 = paste / replace flows, item #19 = progressive WAV writer, item #28 = sequential-GPU mode).
+- `docs/handovers/`. Daily handover docs that cite specific command surfaces; useful when the in-source comments cite a "RB-NN review point".
+- `docs/dev-setup.md`. Linux + Windows + macOS toolchain setup, including the Vulkan loader install required for GPU-backed whisper.cpp.

docs/architecture-map/02-tauri-runtime/app-lifecycle.md

@@ -0,0 +1,95 @@
+---
+name: App lifecycle
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/12
+---
+
+# App lifecycle
+
+> **Where you are:** [Architecture map](../README.md) → [Tauri runtime](README.md) → App lifecycle
+
+**Plain English summary.** This is the entry point. `main.rs` calls `lumotia_lib::run()` and `lib.rs::run` does everything that has to happen before the user sees a window: initialises tracing, checks the Linux launcher env-var contract, installs the Rust panic hook, registers Tauri plugins, opens the SQLite database, prunes the error log, builds a JS preferences-injection script, configures the WebKit media-permission grant on Linux, wires close-to-tray, populates `AppState` and the per-domain managed states, emits any runtime warnings, sets up the system tray, and finally registers all 71 Tauri commands.
+
+## At a glance
+
+- Path: `src-tauri/src/main.rs`, `src-tauri/src/lib.rs`.
+- LOC: 5 (main) + 491 (lib).
+- Tauri commands exposed directly here: `save_preferences` (string preferences -> SQLite settings table). All other commands live under `commands::*` and are registered via `tauri::generate_handler!`.
+- Events emitted directly here: none (runtime warnings are emitted by `commands::models::emit_runtime_warnings`, called from setup).
+- Depends on: `tauri`, `sqlx::SqlitePool`, `lumotia_core::types::EngineName`, `lumotia_llm::LlmEngine`, `lumotia_storage::{init, database_path, get_setting, set_setting, prune_error_log}`, `lumotia_transcription::LocalEngine`, plus the `commands::*` and `tray` modules.
+- Called from frontend at: every `invoke()` site in slice 01 lands in the handler list registered here.
+
+## What's in here
+
+### `main.rs`
+
+Single function. Sets `windows_subsystem = "windows"` for release builds (no console window) and calls `lumotia_lib::run()`. (`src-tauri/src/main.rs:1`).
+
+### `lib.rs`
+
+Module declarations (`src-tauri/src/lib.rs:1`):
+
+- `mod commands;`
+- `#[cfg(not(target_os = "android"))] mod tray;` — tray uses Tauri's `tray-icon` feature which is desktop-only.
+
+Constants:
+
+- `ERROR_LOG_RETENTION_DAYS: i64 = 90` (`src-tauri/src/lib.rs:22`). Used by the startup prune.
+
+Types managed in Tauri state:
+
+- `AppState` (`src-tauri/src/lib.rs:26`). Holds `Arc<LocalEngine>` for whisper and parakeet, the `SqlitePool`, and an `Arc<LlmEngine>`. This is the central state that almost every command queries.
+- `PreferencesScript(pub String)` (`src-tauri/src/lib.rs:34`). Cached preferences-injection JS used when secondary windows are built (so they do not flash unstyled before Svelte mounts).
+
+Functions:
+
+- `build_preferences_script(prefs_json: Option<String>) -> String` (`src-tauri/src/lib.rs:38`). Builds an IIFE that reads saved preferences (theme, zone, accessibility settings: font family, font size, letter spacing, line height, transcript size, bionic reading, reduce motion) and applies them to `<html>` before the rest of the document loads. Embeds the JSON via `serde_json::to_string` to keep it safe.
+- `save_preferences(state, preferences) -> Result<(), String>` (`src-tauri/src/lib.rs:73`). The single command in `lib.rs`. Persists the preferences blob to the SQLite settings table under key `lumotia_preferences`.
+- `init_tracing()` (Linux/macOS/Windows). Initialises the process-wide tracing subscriber once, honours `RUST_LOG`, and writes structured startup/runtime logs to stderr.
+- `warn_if_x11_env_unset_on_wayland()` (Linux only). Emits a `lumotia_startup` warning when the launcher has not pre-set `WEBKIT_DISABLE_DMABUF_RENDERER` (always expected on Linux), or `GDK_BACKEND=x11` / `WINIT_UNIX_BACKEND=x11` when `XDG_SESSION_TYPE=wayland`. It does not mutate the process environment; `run.sh` owns the dev-time contract and package wrappers/.desktop files must own the distribution-time contract.
+- `run()`. The Tauri builder pipeline.
+
+### `run()` step-by-step
+
+1. **Tracing init.** Calls `init_tracing()` before any startup warnings/logs are emitted.
+2. **Linux launcher contract check.** Calls `warn_if_x11_env_unset_on_wayland()` on Linux. Missing env vars produce warnings only; runtime env-var mutation was removed because Rust 2024 treats environment mutation in multi-threaded programs as unsafe.
+3. **Panic hook.** Calls `commands::diagnostics::install_panic_hook()` to dump panic info to `crashes_dir()`.
+4. **Plugin wiring (always-on).** `tauri_plugin_opener`, `tauri_plugin_dialog`, `tauri_plugin_notification` (`src-tauri/src/lib.rs:144`).
+5. **Plugin wiring (desktop-only).** `tauri_plugin_global_shortcut`, `tauri_plugin_autostart` (LaunchAgent on macOS), `tauri_plugin_window_state` (`src-tauri/src/lib.rs:158`).
+6. **Setup hook.** This is where the bulk of startup work lives:
+    - Initialise SQLite via `lumotia_storage::init(&database_path()).await` using `tauri::async_runtime::block_on` (`src-tauri/src/lib.rs:180`). The `Instant::now()` timing is logged.
+    - Prune `error_log` rows older than 90 days (`src-tauri/src/lib.rs:189`). Best-effort: a failure logs but does not block startup.
+    - Load saved preferences from the settings table; build the JS injection script (`src-tauri/src/lib.rs:204`).
+    - Apply the injection script to the main window via `WebviewWindow.eval()` (`src-tauri/src/lib.rs:215`).
+    - On Linux, configure `webkit2gtk` permission requests: enable `media_stream` and `media_capabilities` settings; auto-grant audio capture but deny everything else (camera, geolocation, pointer lock, etc.) (`src-tauri/src/lib.rs:222`). This is the critical piece that makes `getUserMedia` work on Linux without a permission dialog (because WebKitGTK has no dialog, it just silently denies by default).
+    - Wire close-to-tray on desktop: intercept `WindowEvent::CloseRequested` and call `window.hide()` instead of letting the platform exit (`src-tauri/src/lib.rs:281`).
+    - Stash the `PreferencesScript` and the per-domain managed states (`HotkeyState`, `NativeCaptureState`, `LiveTranscriptionState`, `TtsState`, `MeetingState`) (`src-tauri/src/lib.rs:294`).
+    - Build the `AppState` itself: fresh `LocalEngine`s for whisper and parakeet, the open `SqlitePool`, a fresh `LlmEngine` (`src-tauri/src/lib.rs:302`).
+    - Emit runtime warnings (CPU baseline, Vulkan loader) via `commands::models::emit_runtime_warnings` (`src-tauri/src/lib.rs:312`).
+    - Setup the system tray on desktop (`src-tauri/src/lib.rs:314`).
+7. **Command registration.** `tauri::generate_handler![...]` lists 71 commands (`src-tauri/src/lib.rs:321`). The order in the macro is grouped by domain (preferences, models, LLM, transcription, audio, tasks, feedback, TTS, rituals, nudges, intentions, profiles, transcripts, diagnostics, live, windows, clipboard, fs, paste, meeting, hardware, hotkey, updater).
+8. **Run.** `.run(tauri::generate_context!())` blocks the main thread until the app exits. Panics are wrapped with `expect("error while running Lumotia")`.
+
+## Data flow
+
+- **Frontend bootstrap:** the webview is built per `tauri.conf.json` window config. Tauri's `eval()` hook fires the preferences script before the SvelteKit bundle parses, so the user never sees a flash of unstyled content.
+- **Database:** opened once, owned by `AppState`, cloned by `Arc` semantics into every `state.db` borrow.
+- **Engine state:** the two transcription `LocalEngine`s and the `LlmEngine` are shared `Arc`s; commands clone them and run inference inside `tokio::task::spawn_blocking` so the async runtime stays responsive.
+- **Per-domain state:** `HotkeyState`, `NativeCaptureState`, `LiveTranscriptionState`, `TtsState`, `MeetingState` are all stashed via `app.manage(...)` and retrieved by their command files via `tauri::State<'_, T>`.
+
+## Watch-outs
+
+- `tauri::async_runtime::block_on` inside `setup` blocks startup. The DB init and prefs read are explicitly timed and logged so regressions show up. Adding more synchronous async work here directly pushes the time-to-first-paint up.
+- The Linux media-permission wire-up is non-fatal: if `with_webview` fails the app still boots, but `getUserMedia` will be silently denied or fall back to a prompt the user cannot answer (no UI). The error path logs a `lumotia_startup` warning.
+- Linux rendering env vars are a launcher contract, not a runtime mutation. In development, use `npm run dev:tauri` / `./run.sh`; packaged Linux builds need an equivalent wrapper or `.desktop` `Exec=env` policy. `WEBKIT_DISABLE_DMABUF_RENDERER=0` remains the user opt-out for the DMA-BUF workaround.
+- Close-to-tray works only on desktop (the `cfg!(not(target_os = "android"))` block). On Android, closing the activity terminates the process, which is the expected platform behaviour.
+- The `prewarm_default_model` call is *not* wired here. `commands::models::prewarm_default_model` exists, but `setup` does not invoke it. The frontend invokes the matching `prewarm_default_model_cmd` command after the main page mounts. If you ever want to shift pre-warm into setup, watch the spawn_blocking ordering against the engine `Arc` clones.
+
+## See also
+
+- [Commands index](commands/README.md) — every command registered by `lib.rs::run`.
+- [System tray](system-tray.md) — what `tray::setup(app)` builds.
+- [Tauri config](tauri-config.md) — the window config that drives the `get_webview_window("main")` retrieval.
+- [Capabilities and ACL](capabilities-and-acl.md) — the permission set that decides which commands each window can call.
+- [Cargo and features](cargo-and-features.md) — the dependency block that determines which plugins compile in.

docs/architecture-map/02-tauri-runtime/capabilities-and-acl.md

@@ -0,0 +1,127 @@
+---
+name: Capabilities and ACL
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# Capabilities and ACL
+
+> **Where you are:** [Architecture map](../README.md) → [Tauri runtime](README.md) → Capabilities and ACL
+
+**Plain English summary.** Tauri 2 ships a permission-and-capability ACL: every plugin and core API ships permissions, capabilities bind permissions to specific window labels. Lumotia ships two capability files. The main window gets the broad set (dialog, opener, autostart, global shortcuts, notifications, full window control). The three secondary windows (task float, transcript viewer, transcription preview) get a narrow set with no plugin permissions at all and no destructive window APIs. The split is the firewall that prevents a compromised secondary window from launching an installer or registering a global hotkey.
+
+## At a glance
+
+- Path: `src-tauri/capabilities/main.json`, `src-tauri/capabilities/secondary-windows.json`.
+- Auto-generated schemas: `src-tauri/gen/schemas/` (`desktop-schema.json`, `linux-schema.json`, `macOS-schema.json`, `windows-schema.json`, `acl-manifests.json`, plus per-plugin globals). Do not edit by hand — they regenerate from the installed plugin set.
+- Tauri commands exposed: none (declarative config).
+- Events emitted: none.
+- Depends on: the runtime plugin set declared in `src-tauri/Cargo.toml` and wired in `src-tauri/src/lib.rs::run`. If a capability references a permission whose plugin is not enabled, the build fails.
+- Called from frontend at: every `invoke()` is run through this ACL — the capability for the calling window must include the permission for the command being called, otherwise Tauri rejects the IPC call before it reaches the Rust handler.
+
+## What's in here
+
+### `main.json` (`src-tauri/capabilities/main.json:1`)
+
+```
+identifier:  "main"
+description: "Main window capability for user-initiated app control."
+windows:     ["main"]
+permissions:
+  - core:default
+  - core:window:allow-start-dragging
+  - core:window:allow-set-always-on-top
+  - core:window:allow-minimize
+  - core:window:allow-toggle-maximize
+  - core:window:allow-is-maximized
+  - core:window:allow-close
+  - core:window:allow-hide
+  - core:window:allow-show
+  - core:window:allow-set-focus
+  - opener:default
+  - dialog:default
+  - global-shortcut:allow-register
+  - global-shortcut:allow-unregister
+  - autostart:allow-enable
+  - autostart:allow-disable
+  - autostart:allow-is-enabled
+  - notification:allow-is-permission-granted
+  - notification:allow-request-permission
+  - notification:allow-notify
+```
+
+Notes:
+
+- `core:default` brings in the entire `core:event` set, allowing the main window to listen and emit on all event channels.
+- The window-control set is granular: there is no `core:window:default`, every action is opted in. `allow-start-dragging` is what the custom Titlebar uses to drag a frameless window.
+- `opener:default` lets the frontend open external URLs via `tauri-plugin-opener`. This is how the Settings → About links route out.
+- `dialog:default` enables the file/save dialogs used by the import-audio and save-diagnostic-report flows.
+- `global-shortcut:allow-register` and `allow-unregister` let the main window manage the dictation hotkey via the cross-platform plugin path. On Linux Lumotia uses the bespoke evdev backend (see `commands::hotkey`), but Settings still talks to the global-shortcut plugin so the same UI works on macOS / Windows.
+- `autostart:*` lets Settings toggle login-time autostart.
+- `notification:*` is what the Phase 6 nudge bus uses; the Rust-side `commands::nudges::deliver_nudge` adds the main-window-only firewall.
+
+### `secondary-windows.json` (`src-tauri/capabilities/secondary-windows.json:1`)
+
+```
+identifier:  "secondary-windows"
+description: "Narrow capability for passive secondary windows."
+windows:     ["tasks-float", "transcript-viewer", "transcription-preview"]
+permissions:
+  - core:event:default
+  - core:window:allow-start-dragging
+  - core:window:allow-close
+  - core:window:allow-hide
+  - core:window:allow-show
+  - core:window:allow-set-focus
+  - core:window:allow-set-always-on-top
+```
+
+Notes:
+
+- No `core:default`. Only `core:event:default`. Secondary windows can listen to events emitted by the backend or other windows but can't reach the broader core surface (e.g. shell, fs).
+- No plugin permissions at all. No `dialog`, no `opener`, no `global-shortcut`, no `autostart`, no `notification`, no `updater`. This is enforced as a regression test (see below).
+- The window-control set is the bare minimum to drag (titleless overlay), close, hide, show, focus, and pin always-on-top. No maximise, no minimise, no toggle-fullscreen.
+
+### Regression test
+
+`src-tauri/tests/config_hardening.rs::secondary_windows_do_not_get_high_risk_plugin_permissions` (`src-tauri/tests/config_hardening.rs:50`) walks every JSON file in `capabilities/`, finds the ones whose `windows` array contains any of the three secondary labels, and asserts none of their permissions start with `dialog:`, `autostart:`, `global-shortcut:`, `opener:`, or `updater:`. The test fails the moment someone adds, for example, `dialog:default` to the secondary-windows file.
+
+### `gen/schemas/`
+
+Auto-generated by `tauri-build` from the plugin set. Files:
+
+```
+acl-manifests.json
+capabilities.json
+desktop-schema.json
+linux-schema.json
+macOS-schema.json
+windows-schema.json
+plugin-global-scope-schema.json
+plugin-default-permissions.json
+```
+
+These are committed to source control so a fresh checkout has a working ACL even before the first build. Do not edit by hand. If you add a plugin, `cargo tauri build` regenerates them. If a capability file references a permission absent from these schemas, the IDE's JSON-schema validation will flag it before the build even runs.
+
+## Data flow
+
+The ACL is enforced in two places:
+
+1. **Webview IPC layer.** Every `invoke()` call from a window is checked against the capability bound to that window's label. A permission miss returns an IPC error before the Rust handler runs.
+2. **Tauri-side guards.** Several command handlers add their own `ensure_main_window` check on top of the ACL (see [Power assertions and security](commands/power-and-security.md)). This is defence in depth: even if the ACL ever drifted, a secondary window calling, say, `delete_implementation_rule` would still be rejected by the Rust guard.
+
+## Watch-outs
+
+- Adding a permission to either capability is a security decision. The "secondary windows" set in particular has been pruned deliberately — the in-repo tests and the brief item #B.2 review trace the path that closed each gap.
+- The Phase 9 LLM-content-tags command (`commands::llm::extract_content_tags_cmd`) does NOT check the capability; the History page lives in the main window so the main capability already gates it. If you ever expose this command to a secondary window, add an `ensure_main_window` guard and an explicit ACL allowlist entry.
+- `notification:allow-notify` is on the main capability. Secondary windows cannot fire notifications. The frontend's nudge bus already uses the main-window guard via `commands::nudges::deliver_nudge`, but if you ever invoke the plugin's JS-side `sendNotification` directly from a secondary window, it will fail with an ACL error.
+- The schema files in `gen/schemas/` are updated when the dependency graph changes. If you bump a plugin version, expect a diff there too. Commit them in the same PR as the dependency bump.
+
+## See also
+
+- [App lifecycle](app-lifecycle.md) — plugins are wired in `lib.rs::run`, gated by the same `cfg(not(target_os = "android"))` block that gates the desktop-only permissions.
+- [Cargo and features](cargo-and-features.md) — the dependency graph that `gen/schemas/` is generated from.
+- [Tauri config](tauri-config.md) — the CSP works alongside the ACL: CSP guards the webview, ACL guards the IPC.
+- [Tests](tests.md) — `secondary_windows_do_not_get_high_risk_plugin_permissions` is the regression net.
+- [Power assertions and security](commands/power-and-security.md) — `ensure_main_window` is the defence-in-depth pair.

docs/architecture-map/02-tauri-runtime/cargo-and-features.md

@@ -0,0 +1,152 @@
+---
+name: Cargo and features
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# Cargo and features
+
+> **Where you are:** [Architecture map](../README.md) → [Tauri runtime](README.md) → Cargo and features
+
+**Plain English summary.** This page walks the Tauri crate's `Cargo.toml`, its `build.rs`, and its `.cargo/config.toml`. The crate is the binary entry for the desktop app and the library entry for the Android target. The `whisper` cargo feature is the kill-switch for the whisper.cpp backend. Per-target dependency blocks gate macOS objc2 bindings, Linux GTK / WebKitGTK, and Windows base64 (used by the TTS PowerShell shim). `build.rs` enforces the CSP regression guard documented in `docs/whisper-ecosystem/brief.md` item #2.
+
+## At a glance
+
+- Path: `src-tauri/Cargo.toml` (108 LOC), `src-tauri/build.rs` (81 LOC), `src-tauri/.cargo/config.toml` (3 LOC).
+- Tauri commands exposed: none. Build-system files only.
+- Events emitted: none.
+- Depends on: every workspace crate (slices 03–05) plus the Tauri ecosystem.
+- Called from frontend at: nothing direct. The build outputs land in the dev / packaged binary.
+
+## What's in here
+
+### `Cargo.toml`
+
+Package metadata: `name = "lumotia"`, `version = "0.1.0"`, `description = "Lumotia — Think out loud"`, `authors = ["CORBEL Ltd"]`, `edition = "2021"`.
+
+Lib stanza (`src-tauri/Cargo.toml:8`):
+
+```
+name       = "lumotia_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+```
+
+`staticlib` and `cdylib` are needed for the Android target where Tauri builds an `.aar` from a `cdylib`. `rlib` makes it consumable from `main.rs`.
+
+#### `[features]`
+
+```
+default = ["whisper"]
+whisper = ["lumotia-transcription/whisper"]
+```
+
+The `whisper` feature transitively enables `lumotia-transcription/whisper`. The crate-level `default-features = false` on `lumotia-transcription` (`src-tauri/Cargo.toml:33`) means a `--no-default-features` workspace build drops `whisper-rs-sys` entirely; Parakeet still works. `commands::models::load_model_from_disk` returns a clear runtime error for `Engine::Whisper` when the feature is off.
+
+#### `[build-dependencies]`
+
+`tauri-build = "2"`, plus `serde_json = "1"` for the CSP regression guard in `build.rs`.
+
+#### `[dependencies]` — workspace crates
+
+```
+lumotia-core
+lumotia-audio
+lumotia-transcription   { default-features = false }
+lumotia-ai-formatting
+lumotia-storage
+lumotia-cloud-providers
+lumotia-hotkey
+lumotia-llm
+```
+
+The `cloud-providers` crate is referenced here even though no command file currently imports it. Likely reserved for the Phase-N upload flow that the diagnostic-report bundler hints at.
+
+#### `[dependencies]` — Tauri
+
+```
+tauri                       = { version = "2" }
+tauri-plugin-opener         = "2"
+tauri-plugin-dialog         = "2"
+tauri-plugin-notification   = "2"
+```
+
+These three plugins are unconditional. `notification` supports Android natively (Phase 6 nudges) so it stays out of the desktop-only block.
+
+#### `[dependencies]` — runtime
+
+```
+serde       = { version = "1", features = ["derive"] }
+serde_json  = "1"
+tokio       = { version = "1", features = ["rt", "sync"] }
+arboard     = "3.6.1"
+sqlx        = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite"] }
+uuid        = { version = "1", features = ["v4"] }
+```
+
+The `sqlx` block has `default-features = false` and only opts into `runtime-tokio` and `sqlite`. `lumotia-storage` already pulls the macros / migrate / any / json features via its own re-export, so duplicating them here would just bloat compile time. `sqlx` is named directly because `AppState` types it as `SqlitePool`; naming a transitive dep type still requires the dep be listed.
+
+#### `[dev-dependencies]`
+
+`tempfile = "3"` for the Phase 9 `commands::fs::write_text_file_cmd` tests.
+
+#### `[target.'cfg(not(target_os = "android"))'.dependencies]`
+
+```
+tauri                          = { version = "2", features = ["tray-icon"] }
+tauri-plugin-global-shortcut   = "2"
+tauri-plugin-window-state      = "2"
+tauri-plugin-autostart         = "2"
+```
+
+Each is justified inline in `src-tauri/Cargo.toml:74`. Tray icons, global shortcuts, multi-window state, and autostart all either fail to compile against the Android NDK or are structurally meaningless on a single-window mobile activity. The Cargo gate matches the `#[cfg(not(target_os = "android"))]` blocks in `lib.rs` and `commands/windows.rs`.
+
+#### Per-OS dependency blocks
+
+```
+linux:   webkit2gtk = "2.0", gtk = "0.18", gdk = "0.18"
+macos:   objc2 = "0.6.4", objc2-foundation = { ... features = ["std", "NSString", "NSProcessInfo"] }
+windows: base64 = "0.22"
+```
+
+- `webkit2gtk`/`gtk`/`gdk` are used in `lib.rs` (auto-grant audio capture) and `commands/windows.rs` (set GTK `WindowTypeHint::Utility` on the preview overlay). Versions track what `webkit2gtk` 2.0 transitively depends on.
+- `objc2` + `objc2-foundation` power the macOS App Nap power assertion (`commands/power.rs::objc_bridge`).
+- `base64` is the Windows TTS encoder. PowerShell `-EncodedCommand` requires UTF-16-LE base64.
+
+### `build.rs`
+
+Two responsibilities:
+
+1. **Linker workaround.** `--allow-multiple-definition` is passed to GNU ld / lld on Linux because `llama-cpp-sys-2` and `whisper-rs-sys` both statically link their own copy of `ggml`, leading to duplicate symbols (`src-tauri/build.rs:8`). Documented as INTERIM; the intended fix is system-ggml shared-lib linking. Only emitted on Linux.
+2. **CSP regression guard.** `assert_loopback_llm_csp` (`src-tauri/build.rs:30`) parses `tauri.conf.json` with `serde_json`, finds the `connect-src` directive (full-name match, not prefix), and asserts the four required tokens: `http://127.0.0.1:*` and `ws://127.0.0.1:*` must be present, `http://localhost:*` and `ws://localhost:*` must be absent. Fails compilation with a brief-item-#2 reference if any of those break. Re-runs when `tauri.conf.json` changes.
+
+`tauri_build::build()` is called last. Order matters: the CSP guard fails fast, before tauri-build does any of its own work.
+
+### `.cargo/config.toml`
+
+```
+[env]
+LIBCLANG_PATH = "C:\\Program Files\\LLVM\\bin"
+```
+
+Hard-coded Windows path so `bindgen` (used by Tauri 2's macros and a couple of dependencies) can find clang during a Windows build. Harmless on non-Windows hosts — the env var is just unused. Foot-gun: a Windows developer with Clang in a non-default path will have to override or remove this.
+
+## Data flow
+
+- `cargo build` reads `Cargo.toml`, runs `build.rs`, then compiles `src/lib.rs` and `src/main.rs`. The CSP regression guard fires before any source compiles.
+- The default features include `whisper`. A workspace-wide `cargo build --no-default-features` drops both whisper.cpp and the Tauri default features (which would also drop tray-icon, etc., so this is a niche build).
+- Plugin crates land in the dependency graph and contribute permission manifests that `gen/schemas/` is regenerated from at build time.
+
+## Watch-outs
+
+- Adding a workspace crate dependency here also requires that crate to be in the root `Cargo.toml`'s workspace members (or referenced by `path =` here, which is what is done now). All eight workspace crates appear in this `Cargo.toml`.
+- The `--allow-multiple-definition` link arg is the kind of thing that hides bugs. If both ggml copies ever drift, the binary picks "the first definition" and the second copy's slightly-different symbol is silently shadowed. Track the `whisper-rs-sys` and `llama-cpp-sys-2` ggml pins together.
+- Bumping any of `objc2`, `objc2-foundation`, `webkit2gtk`, `gtk`, `gdk` is an ABI move. Test on each platform.
+- The hard-coded `LIBCLANG_PATH` should ideally come from an environment variable or a build-script probe. Until then, document it in `docs/dev-setup.md` for Windows contributors.
+
+## See also
+
+- [App lifecycle](app-lifecycle.md) — `lib.rs::run` is what consumes everything declared here.
+- [Tauri config](tauri-config.md) — `build.rs` reads `tauri.conf.json` and pins the CSP shape.
+- [Tests](tests.md) — runtime regression for the same CSP property.
+- [Capabilities and ACL](capabilities-and-acl.md) — `gen/schemas/` files are regenerated when a plugin in this Cargo manifest changes.

docs/architecture-map/02-tauri-runtime/commands/README.md

@@ -0,0 +1,68 @@
+---
+name: Commands index
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# Commands index
+
+> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → Commands
+
+**Plain English summary.** This is the registry of every Tauri command file. Each `.rs` file under `src-tauri/src/commands/` either declares one or more `#[tauri::command]` functions invoked from the frontend, or is a utility (state, security, power) that the command files share. The full list of commands actually exposed to the frontend is registered via the `tauri::generate_handler!` macro in `src-tauri/src/lib.rs:321`.
+
+## At a glance
+
+- Path: `src-tauri/src/commands/`.
+- 22 command modules (declare `#[tauri::command]`s) plus 3 utility modules (`mod.rs`, `power.rs`, `security.rs`).
+- 71 `#[tauri::command]` functions registered in `lib.rs`. A handful of additional `#[tauri::command]` functions exist in source but are NOT registered (notably the small `clipboard::copy_to_clipboard` IS registered; nothing meaningful is unregistered as of last verification).
+- Total LOC across `commands/`: 6,939 (Rust source, excluding tests folder).
+
+## Module list
+
+| Module | LOC | Registered commands | One-liner |
+|---|---|---|---|
+| [audio](audio.md) | 540 | 4 | Native cpal mic capture, list devices, save WAV |
+| [clipboard](small-commands.md#clipboardrs) | 11 | 1 | Copy text to system clipboard via arboard |
+| [diagnostics](diagnostics.md) | 534 | 6 | Panic hook, frontend error log, crash files, diagnostic-report bundler, OS info |
+| [feedback](feedback.md) | 110 | 2 | HITL feedback capture and retrieval (Phase 2) |
+| [fs](small-commands.md#fsrs) | 44 | 1 | Write UTF-8 text to a user-chosen path (Phase 9) |
+| [hardware](small-commands.md#hardwarers) | 69 | 2 | Probe RAM/CPU/GPU, rank models for current hardware |
+| [hotkey](hotkey.md) | 105 | 5 | evdev hotkey listener bridge (Linux Wayland-compatible) |
+| [intentions](intentions.md) | 308 | 5 | Phase 7 implementation-intention rules CRUD |
+| [live](live.md) | 1,737 | 2 | Live transcription session orchestration (the big one) |
+| [llm](llm.md) | 423 | 10 | LLM model lifecycle, transcript cleanup, content tags |
+| [meeting](small-commands.md#meetingrs) | 50 | 1 | Process-list poll for known meeting apps (Phase 8) |
+| [models](models.md) | 691 | 13 | Whisper / Parakeet model registry, download, load, runtime capabilities |
+| [mod](mod.md) | 114 | n/a | `build_initial_prompt` helper + module re-exports |
+| [nudges](small-commands.md#nudgesrs) | 63 | 1 | Phase 6 nudge delivery via tauri-plugin-notification |
+| [paste](paste.md) | 790 | 3 | Auto-insert at cursor across Linux/macOS/Windows |
+| [power](power-and-security.md#powerrs) | 208 | 0 | macOS App Nap power assertion (no commands) |
+| [profiles](profiles.md) | 185 | 9 | Profile + profile-term CRUD, auto-learn from edits |
+| [rituals](small-commands.md#ritualsrs) | 43 | 2 | Morning triage last-shown sentinel (Phase 5) |
+| [security](power-and-security.md#securityrs) | 30 | 0 | `ensure_main_window` defence-in-depth helper |
+| [tasks](tasks.md) | 402 | 11 | Task CRUD, decompose-and-store, extract-from-transcript |
+| [transcription](transcription.md) | 413 | 3 | Transcribe PCM (Whisper / Parakeet), transcribe file |
+| [transcripts](transcripts.md) | 253 | 8 | Transcripts CRUD + FTS5 search + meta patches |
+| [tts](tts.md) | 444 | 3 | Read aloud via spd-say / say / PowerShell SAPI (Phase 4) |
+| [update](small-commands.md#updaters) | 16 | 2 | Updater placeholder (returns "disabled" until signing wired) |
+| [windows](windows.md) | 197 | 4 | Open / close the secondary windows (preview, viewer, task float) |
+
+## Per-command page assignments
+
+- Big files have their own page: [audio](audio.md), [live](live.md), [paste](paste.md), [models](models.md), [diagnostics](diagnostics.md), [llm](llm.md), [tts](tts.md), [transcription](transcription.md), [tasks](tasks.md), [transcripts](transcripts.md), [intentions](intentions.md), [profiles](profiles.md), [windows](windows.md), [hotkey](hotkey.md), [feedback](feedback.md).
+- Utilities collapsed into one page: [Power assertions and security](power-and-security.md) covers `power.rs` and `security.rs`.
+- Small modules grouped: [Small commands](small-commands.md) covers `clipboard.rs`, `fs.rs`, `hardware.rs`, `meeting.rs`, `nudges.rs`, `rituals.rs`, `update.rs`.
+- Module entry: [mod.md](mod.md) covers `mod.rs` (re-exports + `build_initial_prompt` helper).
+
+## How to navigate
+
+- Looking for a frontend `invoke('foo', ...)` call? Search for `pub async fn foo` or `pub fn foo` under `commands/`. The page for that file lists all its commands with arg + return signatures.
+- Looking for an event the frontend listens for? See the slice README's "events emitted" section, or grep for the event name across `commands/`.
+- Looking for ACL gotchas? Pages flag the commands that include an `ensure_main_window` guard.
+
+## See also
+
+- [Slice README](../README.md) — back to the top of slice 02.
+- [App lifecycle](../app-lifecycle.md) — `lib.rs::run` is what registers everything listed here.
+- [Capabilities and ACL](../capabilities-and-acl.md) — the permission set that gates every invocation.

docs/architecture-map/02-tauri-runtime/commands/audio.md

@@ -0,0 +1,103 @@
+---
+name: Audio capture commands
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# `commands::audio`
+
+> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Audio
+
+**Plain English summary.** Owns the native cpal microphone capture path used outside live transcription. Exposes "list input devices", "start native capture", "stop native capture", and "save audio to WAV". Streams 16 kHz mono PCM chunks to the frontend via the `native-pcm` event. Also owns the deterministic recording-filename generator and the helper that resolves a destination WAV path so the live-transcription module can share it.
+
+## At a glance
+
+- Path: `src-tauri/src/commands/audio.rs`.
+- LOC: 540.
+- Tauri commands exposed:
+  - `list_audio_devices(window: WebviewWindow) -> Result<Vec<DeviceInfo>, String>` — main-window only. Wraps `MicrophoneCapture::list_devices` in `spawn_blocking`.
+  - `start_native_capture(window, app, state, device_name: Option<String>) -> Result<(), String>` — main-window only. Starts a cpal stream, downsamples to 16 kHz mono, streams chunks via `native-pcm` events, also writes to a temp WAV.
+  - `stop_native_capture(window, state) -> Result<Vec<f32>, String>` — main-window only. Awaits the worker join barrier (RB-06) and returns the accumulated samples.
+  - `save_audio(window, app, samples, output_folder: Option<String>) -> Result<String, String>` — main-window only. Writes a fresh WAV to `app_local_data_dir/recordings/` (or a user-chosen folder) and returns its absolute path.
+- Events emitted: `native-pcm` (payload `{ samples: Vec<f32> }`, ~0.5 s of 16 kHz mono per emit) — `src-tauri/src/commands/audio.rs:249` and `:274`.
+- Depends on: `lumotia_audio::{DeviceInfo, MicrophoneCapture, WavWriter, write_wav}`, `lumotia_core::types::AudioSamples`, `lumotia_core::constants::WHISPER_SAMPLE_RATE`. Plus `tokio::{mpsc, Mutex, JoinHandle, spawn_blocking, sleep}` and `std::sync::{Arc, Mutex, atomic::AtomicBool}`.
+- Called from frontend at: dictation page (start / stop), Settings → Audio (device list), file-import flow (save_audio).
+
+## What's in here
+
+### Constants
+
+- `MAX_NATIVE_CAPTURE_RETURN_SAMPLES = WHISPER_SAMPLE_RATE * 60 * 10` (`src-tauri/src/commands/audio.rs:14`). 10 minutes of 16 kHz mono. Caps the in-memory return buffer; the temp WAV on disk stays authoritative beyond this.
+
+### `CaptureWorker` (`src-tauri/src/commands/audio.rs:34`)
+
+Internal struct holding `stop_tx: tokio_mpsc::Sender<()>` and `join: JoinHandle<()>`. `stop_worker(worker).await` (`src-tauri/src/commands/audio.rs:44`) sends the stop signal and awaits the join. Consumes the worker because `stop_tx` and `join` are single-use. Errors from the join are logged and swallowed.
+
+### `NativeCaptureState` (`src-tauri/src/commands/audio.rs:53`)
+
+Tauri-managed state. Fields:
+
+- `worker: AsyncMutex<Option<CaptureWorker>>` — `tokio::sync::Mutex` because `stop_worker` awaits while holding the lock.
+- `all_samples: Arc<Mutex<Vec<f32>>>` — capped compatibility buffer returned by `stop_native_capture`.
+- `wav_writer: Arc<Mutex<Option<WavWriter>>>` — temp WAV writer, finalised when the worker exits.
+- `temp_audio_path: Arc<Mutex<Option<PathBuf>>>` — destination for the temp WAV.
+- `capture_truncated: Arc<AtomicBool>` — set when `all_samples` was capped (the temp WAV still has the full capture).
+
+### `append_recorded_chunk` (`src-tauri/src/commands/audio.rs:79`)
+
+Helper that pushes a downsampled chunk into both the WAV writer and the in-memory buffer, respecting the buffer cap and flipping the `capture_truncated` flag when it bumps the ceiling.
+
+### `start_native_capture` (`src-tauri/src/commands/audio.rs:113`)
+
+Step-by-step:
+
+1. `ensure_main_window(&window)` — secondary windows can't start a capture.
+2. Stop any in-flight worker and `await` its termination (RB-06 — without the join, `all_samples.clear()` below would race a draining worker and a rapid start→stop→start could leak old-session samples into the new session).
+3. Call `MicrophoneCapture::start` (or `start_with_device(name)`) inside `spawn_blocking` — the underlying cpal probe spends up to `DEVICE_VALIDATION_MS * N` per pass and would block the async runtime otherwise (Codex review 2026/04/17 D2).
+4. Open a temp WAV via `WavWriter::create(&temp_path, WHISPER_SAMPLE_RATE, 1)`.
+5. Spawn the worker. The worker loop:
+   - Polls the stop channel non-blocking.
+   - Drains `cpal::AudioChunk`s from the capture mpsc, distinguishing `Empty` (try again) from `Disconnected` (stream is dead, exit) — Codex review 2026/04/17 M3.
+   - Downmixes to mono if the source is stereo (`chunk.samples.chunks(channels).map(|frame| sum / channels)`).
+   - Decimates to 16 kHz (simple ratio-based decimation, matches the frontend pcm-processor.js pattern).
+   - When the buffer ≥ 8000 samples (~0.5 s), drains, calls `append_recorded_chunk`, and emits `native-pcm`.
+   - On exit, flushes any remaining samples, drops the cpal capture, finalises the WAV.
+6. Stash the worker in `state.worker`.
+
+### `stop_native_capture` (`src-tauri/src/commands/audio.rs:306`)
+
+Takes the worker out of state, calls `stop_worker(worker).await`, then `mem::take`s `all_samples` and returns it. Logs a warning if the buffer was truncated.
+
+### `resolve_recording_path` (`src-tauri/src/commands/audio.rs:333`)
+
+Public helper used by `commands::live::start_live_transcription_session`. Resolves the recordings dir (user-supplied folder if non-empty, else `app_local_data_dir/recordings/`), creates it, and returns `dir.join(recording_filename())`.
+
+### `recording_filename` (`src-tauri/src/commands/audio.rs:365`)
+
+Deterministic filename: `lumotia-<unix_secs>-<nanos:09>-<counter:04>.wav`. The counter is a process-lifetime `AtomicU64` (`RECORDING_COUNTER`) bumped on each call. The combination defeats wall-clock collisions both across launches (secs change) and within the same nanosecond (counter changes).
+
+### `persist_audio_samples` and `save_audio` (`src-tauri/src/commands/audio.rs:512`, `:531`)
+
+`save_audio` is the public command. Calls `persist_audio_samples`, which resolves the recording path, then calls `lumotia_audio::write_wav` inside `spawn_blocking`. Returns the absolute path as a string.
+
+## Data flow
+
+- **Start path:** `start_native_capture(deviceName)` → cpal opens stream → worker downmixes/downsamples → emits `native-pcm` events at 0.5 s cadence → frontend dictation page accumulates samples or feeds them to a transcription command.
+- **Stop path:** frontend invokes `stop_native_capture` → worker stop channel signalled → join awaited → samples returned (capped at 10 minutes) → frontend can request `save_audio` to persist.
+- **Live transcription path:** `commands::live` does not use `start_native_capture` directly; it owns its own `MicrophoneCapture::start` invocation but reuses `resolve_recording_path` and `recording_filename` from this file.
+
+## Watch-outs
+
+- The in-memory buffer is capped at 10 minutes. Anything longer relies on the temp WAV; the frontend cannot just `stop_native_capture` and treat the returned vec as ground truth for long sessions. Today's UI assumes short captures, but the cap should be surfaced if you build a long-form recorder.
+- The downsampler is naive decimation. Acceptable for speech but not for music. If you ever extend Lumotia to general audio, swap in `lumotia_audio::StreamingResampler` (which is what `commands::live` uses).
+- `start_native_capture` does *not* engage `PowerAssertion` (App Nap pinning). `commands::live::run_live_session` does. If you build a long-form non-live recorder on top of this, add the assertion.
+- The worker emits `native-pcm` to the entire app handle (not a specific window). Every webview that listens will receive the chunks. If you ever route audio to a non-main window, double-check this is what you want.
+- `stop_worker_awaits_full_termination_no_writes_after_join` (`src-tauri/src/commands/audio.rs:454`) is the regression test for RB-06. Do not change `stop_worker` to a fire-and-forget pattern.
+
+## See also
+
+- [Live transcription](live.md) — uses `resolve_recording_path` and `recording_filename` from this file.
+- [Transcription](transcription.md) — receives `Vec<f32>` from `stop_native_capture` and runs Whisper / Parakeet on it.
+- [Models](models.md) — `ensure_model_loaded` is invoked by the transcription commands before they consume audio.
+- [Cargo and features](../cargo-and-features.md) — `arboard` and the audio crate dependency live there.

docs/architecture-map/02-tauri-runtime/commands/diagnostics.md

@@ -0,0 +1,111 @@
+---
+name: Diagnostics and reports
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# `commands::diagnostics`
+
+> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Diagnostics
+
+**Plain English summary.** The local-only diagnostic plumbing. Installs the Rust panic hook (writes per-panic dumps to `crashes_dir`). Captures frontend errors via a global `window.onerror` handler. Lists recent error-log rows and crash files. Bundles a markdown diagnostic report (settings, recent errors, active power assertions, crash dumps, log tail) so the user can paste it into an email or GitHub issue. Privacy posture: nothing is transmitted; the user reviews exactly what would be shared before sharing it.
+
+## At a glance
+
+- Path: `src-tauri/src/commands/diagnostics.rs`.
+- LOC: 534.
+- Tauri commands exposed (6 total):
+  - `log_frontend_error(state, context, message, stack: Option<String>) -> Result<(), String>`. No window guard — fires from any window's global error handler.
+  - `list_recent_errors_command(window, state, limit) -> Result<Vec<ErrorLogDto>, String>`. Main-window only.
+  - `list_crash_files(window) -> Result<Vec<CrashFile>, String>`. Main-window only.
+  - `generate_diagnostic_report(window, state, options: Option<ReportOptions>) -> Result<String, String>`. Main-window only.
+  - `save_diagnostic_report(window, app, state, options) -> Result<String, String>`. Main-window only. Returns the absolute file path it wrote.
+  - `get_os_info() -> OsInfo`.
+- Public Rust helper used by `lib.rs::run`: `install_panic_hook()`.
+- Events emitted: none.
+- Depends on: `lumotia_storage::{app_data_dir, crashes_dir, list_recent_errors, log_error, logs_dir, ErrorLogRow}`, `commands::power::active_assertions_snapshot`, `commands::security::ensure_main_window`. Plus `std::fs`, `std::panic`, `std::time`.
+- Called from frontend at: global `window.onerror` / `window.unhandledrejection` (`log_frontend_error`); Settings → About → Diagnostics (the bundle commands and `list_*` commands); top-of-app Cmd-vs-Ctrl labelling (`get_os_info`).
+
+## What's in here
+
+### Constants (`src-tauri/src/commands/diagnostics.rs:26`)
+
+- `DEFAULT_RECENT_ERRORS = 50`.
+- `MAGNOTIA_VERSION = env!("CARGO_PKG_VERSION")`.
+
+### `install_panic_hook` (`:34`)
+
+Creates `crashes_dir()` if missing. Replaces the default panic hook with one that writes a minimal text dump to `crashes_dir/<unix_secs>-<short_hash>.crash` and then chains to the original hook so the panic still hits stderr. Dump includes version, timestamp, thread name, panic message, OS, arch, RUST_BACKTRACE env. Backtraces require `RUST_BACKTRACE=1` and `std::backtrace` plumbing — neither set up today, so production crashes will lack stack traces.
+
+### `log_frontend_error` (`:86`)
+
+Truncates the stack to 2,000 chars and calls `lumotia_storage::log_error` with context `"frontend"` (or the caller-supplied context), error code `"FRONTEND_ERROR"`, the message, and the stack as metadata.
+
+### `ErrorLogDto` (`:114`) and `list_recent_errors_command` (`:138`)
+
+`ErrorLogDto` is a camelCase shape over `ErrorLogRow`. The list command clamps `limit` to `[1, 1000]` and defaults to 50.
+
+### `CrashFile` and `list_crash_files` (`:152`, `:162`)
+
+`CrashFile` exposes filename, mtime_secs, size_bytes, plus a 600-char preview. `list_crash_files_inner` reads the crashes directory, builds the structs, sorts by mtime descending.
+
+### Report options and assembler
+
+- `ReportOptions` has four boolean flags: `include_settings`, `include_recent_errors`, `include_crashes`, `include_log_tail` (each defaulting true).
+- `redact_home(input)` replaces `home_dir().display()` substrings with `~`.
+- `looks_sensitive_key(key)` flags keys containing `apikey` / `token` / `secret` / `password` / `bearer`.
+- `redact_json_value(value, key_hint)` recursively walks a JSON value redacting strings under sensitive keys.
+- `sanitise_preferences_json(raw)` parses, redacts, re-emits.
+- `redact_line(input)` does line-level redaction for the error-message field.
+
+### `generate_diagnostic_report_inner` (`:307`)
+
+Builds a markdown document with sections:
+
+1. Header (version, OS / arch, app data dir, generated timestamp, "local-only until you choose to share" notice).
+2. Settings (sanitised JSON via `sanitise_preferences_json`).
+3. Recent errors (50 rows, redacted).
+4. Power assertions (snapshots from `commands::power::active_assertions_snapshot`).
+5. Crash dumps (up to 5 most-recent, plus a count of older ones).
+6. Log tail (8 KB tail of `logs_dir/lumotia.log`, home-redacted).
+
+### `save_diagnostic_report` (`:513`)
+
+Generates the report, then writes it to `app_data_dir/diagnostic-reports/lumotia-diagnostic-<unix_secs>.md`. Returns the absolute path.
+
+### `OsInfo` and `get_os_info` (`:449`, `:474`)
+
+OS family label, arch, `uses_cmd` boolean (macOS only), `is_wayland` boolean (Linux only), `custom_hotkey_backend` (Linux only — true because evdev is the primary path on Linux), and `primary_modifier_label` (`"Cmd"` on macOS, `"Ctrl"` elsewhere). Frontend reads this once at boot to set the hotkey labels and "Open file location" terminology.
+
+## Data flow
+
+```
+panic occurs -> install_panic_hook writes crashes_dir/<ts>.crash
+window.onerror fires in JS -> invoke('log_frontend_error', context, message, stack)
+                            -> lumotia_storage::log_error
+                            -> error_log table
+
+Settings -> About -> Diagnostics
+  list_crash_files -> [CrashFile, ...]
+  list_recent_errors_command -> [ErrorLogDto, ...]
+  generate_diagnostic_report(opts) -> markdown string
+  user reviews, then optionally:
+    save_diagnostic_report(opts) -> absolute path
+```
+
+## Watch-outs
+
+- **No backtraces in production crashes.** `RUST_BACKTRACE` is not set in the packaged binary. Either set it in a launcher script or call `std::backtrace::Backtrace::capture()` inside the panic hook.
+- **`log_frontend_error` is unguarded by ACL or window-label check.** Any window can log a frontend error. That is fine, but the storage layer should enforce a row-rate limiter before this surface ever ships to users with adversarial workloads.
+- **Crash file prefixes are unix-seconds-and-a-16-bit-hash.** Two panics in the same second with the same low-16-bits of seconds will collide. Vanishingly unlikely in practice. If you want bulletproof, use the same counter pattern as `commands::audio::recording_filename`.
+- **Diagnostic report is markdown by design** so it can be pasted anywhere. If you ever want a structured upload format, keep this command and add a sibling that returns JSON.
+- **Sensitive-key redaction is a heuristic.** It catches the obvious names (`api_key`, `apiKey`, `token`, `Bearer`) but won't catch a user-named key like `mySecretToken: "abc"` if the key string is normalised to lowercase first. Fine for "user reviews before sharing"; not fine if you ever auto-upload.
+- **`ensure_main_window` is missing on `log_frontend_error` and `get_os_info`.** Intentional — both should be callable from any window. But document this so future tightening attempts know to leave them alone.
+
+## See also
+
+- [App lifecycle](../app-lifecycle.md) — `install_panic_hook` is called from setup.
+- [Power assertions and security](power-and-security.md) — `active_assertions_snapshot` feeds the report.
+- [Capabilities and ACL](../capabilities-and-acl.md) — the report is local until the user chooses to share.
+- [Tests](../tests.md) — no specific test for the report itself, but the redactor helpers could use unit coverage.

docs/architecture-map/02-tauri-runtime/commands/feedback.md

@@ -0,0 +1,78 @@
+---
+name: HITL feedback
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# `commands::feedback`
+
+> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Feedback
+
+**Plain English summary.** Phase 2: thumbs + correction capture on AI-generated output (microsteps from a task decomposition, task lines extracted from a transcript, or LLM cleanup). The captured rows feed a few-shot loop: subsequent prompts are conditioned on the user's preferred style by injecting the (input, preferred-output) pairs as exemplars.
+
+## At a glance
+
+- Path: `src-tauri/src/commands/feedback.rs`.
+- LOC: 110.
+- Tauri commands exposed:
+  - `record_feedback(state, input: RecordFeedbackInput) -> Result<i64, String>` — returns the new row id.
+  - `list_feedback_examples_cmd(state, target_type, limit, min_rating, profile_id) -> Result<Vec<FeedbackDto>, String>`.
+- Events emitted: none.
+- Depends on: `lumotia_storage::{record_feedback, list_feedback_examples, FeedbackRow, FeedbackTargetType, RecordFeedbackParams}`.
+- Called from frontend at: dictation result panel (thumb up/down + correction-text on cleanup); Tasks page (thumb on extracted tasks and decomposed microsteps).
+
+## What's in here
+
+### `RecordFeedbackInput` (`src-tauri/src/commands/feedback.rs:15`)
+
+Frontend-supplied shape:
+
+- `targetType`: `"microstep" | "task_extraction" | "cleanup"`. Parsed via `FeedbackTargetType::parse`.
+- `targetId`: optional surface-specific id (subtask id, task id, transcript id).
+- `rating`: `-1` (thumbs down), `0` (correction, neutral), `+1` (thumbs up).
+- `originalText`: the AI-generated text the user is rating.
+- `correctedText`: the user's preferred text (when they corrected it).
+- `contextJson`: freeform JSON used by the prompt builder later to reconstruct the (input, preferred-output) pair.
+- `profileId`: scopes the row.
+
+### `FeedbackDto` (`:38`)
+
+camelCase mirror of `FeedbackRow`. Note `rating` widens to `i64` in the DTO (storage uses `i64`).
+
+### `parse_target_type` (`:68`)
+
+Wraps `FeedbackTargetType::parse(raw)`, returning `"unknown feedback target_type: <raw>"` on miss.
+
+### `record_feedback` (`:73`)
+
+`parse_target_type` then `db_record_feedback`. Returns the row id.
+
+### `list_feedback_examples_cmd` (`:95`)
+
+Clamps `limit` to `[1, 64]`, defaults 8. Clamps `min_rating` to `[-1, 1]`, default 0. Calls `db_list_feedback_examples`. Returns `FeedbackDto`s. Used by the `commands::tasks` few-shot exemplar pull and would be used by the equivalent in `commands::llm` if/when cleanup gets its own exemplar path.
+
+## Data flow
+
+```
+dictation result thumbs-up -> invoke('record_feedback', { targetType: 'cleanup', rating: +1, originalText, correctedText, contextJson, profileId })
+                            -> lumotia_storage::record_feedback -> row id
+
+decomposition thumbs-down + correction -> record_feedback({ targetType: 'microstep', rating: 0, originalText, correctedText: "user's preferred wording", contextJson: {parent_text}, profileId })
+
+next decompose call -> list_feedback_examples_cmd('microstep', 5, 0, profile_id)
+                    -> [FeedbackDto, ...] -> few-shot exemplars
+```
+
+## Watch-outs
+
+- **No `ensure_main_window` guard.** Tasks float and History viewer secondary windows can also fire feedback. Intentional. If you ever want to lock down feedback writes, this is where to add the guard.
+- **`contextJson` is freeform.** Storage stores the raw string. `commands::tasks::to_llm_examples` parses it and skips rows that are malformed. Bad data therefore degrades gracefully but doesn't surface to the user. The `eprintln!` in `to_llm_examples` is the only visibility.
+- **`min_rating` clamp is `[-1, 1]`.** Pass `1` to get only thumbs-up examples, `0` for thumbs-up + corrections, `-1` for everything. The default of `0` is what `commands::tasks` picks.
+- **No deduplication.** A user thumbs-upping the same output twice creates two rows. The exemplar trim in `commands::tasks` does not dedupe by `originalText`. If two identical exemplars steal slots, that's just lost prompt budget.
+
+## See also
+
+- [Tasks](tasks.md) — the consumer of `list_feedback_examples_cmd`.
+- [LLM](llm.md) — the cleanup path that produces the text that thumbs-up/down feedback rates.
+- [Profiles](profiles.md) — `profileId` is the scoping key.

docs/architecture-map/02-tauri-runtime/commands/hotkey.md

@@ -0,0 +1,87 @@
+---
+name: Hotkey bridge
+type: architecture-map-page
+slice: 02-tauri-runtime
+last_verified: 2026/05/09
+---
+
+# `commands::hotkey`
+
+> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Hotkey bridge
+
+**Plain English summary.** The Linux Wayland-compatible global hotkey backend. Tauri's `tauri-plugin-global-shortcut` works on macOS / Windows and on X11 Linux but fails silently on Wayland (the protocol forbids unprivileged keystroke grabs). Lumotia's bespoke evdev backend reads `/dev/input/event*` directly, parses key combos, and emits `lumotia:hotkey-pressed` / `lumotia:hotkey-released` events. Settings on Linux uses these commands instead of the global-shortcut plugin; everywhere else the plugin path is canonical.
+
+## At a glance
+
+- Path: `src-tauri/src/commands/hotkey.rs`.
+- LOC: 105.
+- Tauri commands exposed (5 total):
+  - `is_wayland_session() -> bool`. Pure env probe.
+  - `check_hotkey_access() -> Result<(), String>`. Probes evdev access (user in `input` group, etc.).
+  - `start_evdev_hotkey(app, state, hotkey: String) -> Result<(), String>`. Parses the Tauri-style combo string, stops any existing listener, starts a new one, spawns a forwarder task that converts evdev events to Tauri events.
+  - `update_evdev_hotkey(state, hotkey: String) -> Result<(), String>`. Updates the combo on a running listener.
+  - `stop_evdev_hotkey(state) -> Result<(), String>`. Stops cleanly.
+- Events emitted: `lumotia:hotkey-pressed` (no payload), `lumotia:hotkey-released` (no payload). Fired from the forwarder task in `start_evdev_hotkey` (`src-tauri/src/commands/hotkey.rs:67`, `:70`).
+- Depends on: `lumotia_hotkey::{EvdevHotkeyListener, HotkeyCombo, HotkeyEvent, check_evdev_access}`. Plus `tokio::sync::{mpsc, Mutex}`.
+- Called from frontend at: Settings → Hotkey on Linux. Other platforms call the `tauri-plugin-global-shortcut` plugin's JS API directly.
+
+## What's in here
+
+### `HotkeyState` (`src-tauri/src/commands/hotkey.rs:9`)
+
+Tauri-managed: `listener: Arc<Mutex<Option<EvdevHotkeyListener>>>`. `tokio::sync::Mutex` because operations await across `.lock()`.
+
+### `is_wayland_session` (`:23`)
+
+Returns true if `WAYLAND_DISPLAY` is set or `XDG_SESSION_TYPE=wayland`. Used by Settings to decide whether to display the Linux-only hotkey UI.
+
+### `check_hotkey_access` (`:32`)
+
+Defers to `lumotia_hotkey::check_evdev_access` — that helper checks the user can read `/dev/input/event*` (typically requires being in the `input` group, or a udev rule). On failure, returns the actionable error string.
+
+### `start_evdev_hotkey` (`:41`)
+
+1. Parse the hotkey string (e.g. `"Shift+Cmd+Space"`) via `HotkeyCombo::from_tauri_str`. Errors become `"Cannot parse hotkey: ..."`.
+2. Lock the listener mutex; if a listener is already running, stop it and await termination.
+3. Build a 64-deep `tokio::sync::mpsc` channel for `HotkeyEvent`s.
+4. Call `EvdevHotkeyListener::start(combo, event_tx)`, stash the listener.
+5. Spawn a `tokio::spawn` forwarder that reads from the event_rx and emits `lumotia:hotkey-pressed` / `lumotia:hotkey-released` per event variant.
+
+### `update_evdev_hotkey` (`:81`)
+
+Re-parses the combo and calls `listener.set_hotkey(combo)` if a listener is running. Returns `"Hotkey listener not running"` otherwise. Avoids the cost of stopping and restarting the evdev thread.
+
+### `stop_evdev_hotkey` (`:99`)
+
+Take the listener out, call `listener.stop().await`. Idempotent — calling stop with no listener returns Ok silently.
+
+## Data flow
+
+```
+Settings -> is_wayland_session() -> bool
+Settings -> check_hotkey_access() -> Ok or "join the input group / install udev rule"
+Settings -> start_evdev_hotkey("Shift+Cmd+Space")
+  -> parse combo
+  -> stop any prior listener
+  -> EvdevHotkeyListener spawns its own thread reading /dev/input/event*
+  -> forwarder spawn: HotkeyEvent -> Tauri event
+frontend listens on 'lumotia:hotkey-pressed' / '...-released' and starts/stops dictation
+Settings -> update_evdev_hotkey("Ctrl+Alt+M") (when user changes binding)
+Settings -> stop_evdev_hotkey() (when user disables)
+```
+
+## Watch-outs
+
+- **No `ensure_main_window` guard.** Settings is in the main window. If you ever expose hotkey re-binding in a secondary window, add the guard.
+- **Linux only.** macOS and Windows code paths in the frontend talk to `tauri-plugin-global-shortcut` directly — no Rust commands needed because the plugin handles register / unregister via JS. This module compiles and runs on every desktop OS but only *works* on Linux because evdev is Linux-specific (the workspace crate `lumotia_hotkey` has the platform shim).
+- **`/dev/input/event*` access requires either:** (a) the user is in the `input` group, or (b) a udev rule grants Lumotia explicit access. The Settings UI walks the user through option (a) on first run; option (b) is documented in `docs/dev-setup.md` for power users.
+- **Channel size of 64** is enough for a key smash burst. If a worker stalls and the channel fills, evdev events would be dropped silently. Consider logging a warning when the channel is at capacity.
+- **The forwarder spawn is detached.** No way to stop the spawn task explicitly; it exits when `event_rx.recv().await` returns None (which happens when the listener is dropped). Acceptable.
+- **No power assertion.** The evdev listener thread is pinned by the kernel via the file handle; idle CPU is near zero.
+
+## See also
+
+- [App lifecycle](../app-lifecycle.md) — `HotkeyState::new()` is stashed in setup.
+- [Diagnostics](diagnostics.md) — `OsInfo.custom_hotkey_backend` flags Linux as the evdev path.
+- [Paste](paste.md) — the consumer of "user pressed dictation hotkey": holds focus on the target window for the eventual paste.
+- [Live transcription](live.md) — the dictation flow that the hotkey starts.