Update Tauri migration documentation and scaffold

AGENTS.md

@@ -17,6 +17,10 @@ A future migration to Tauri is planned, but do not begin that migration unless t
 - `electron/` - Electron desktop shell.
   - `electron/main.cjs` creates windows, stores settings, handles updates, and implements IPC handlers.
   - `electron/preload.cjs` exposes the Electron IPC surface as `window.electronAPI`.
+- `src-tauri/` - isolated Tauri migration scaffold.
+  - `src-tauri/src/main.rs` owns Tauri commands for the renderer `desktopApi` surface.
+  - `src-tauri/tauri.conf.json` points Tauri at the existing Vite renderer.
+  - `src-tauri/capabilities/` contains Tauri permission grants for enabled plugins.
 - `backend/` - FastAPI backend and local processing.
   - `backend/main.py` defines chat, session, model, audio, Ollama, and web search routes.
   - `backend/local_rag.py` defines library, file registration, job, and local context routes.
@@ -36,6 +40,7 @@ A future migration to Tauri is planned, but do not begin that migration unless t
 - `npm run dev:backend` - start FastAPI on `127.0.0.1:8000` with reload. Requires `backend/.venv`.
 - `npm run dev:renderer` - start Vite on `127.0.0.1:5173`.
 - `npm run dev:electron` - wait for Vite and backend health, then start Electron.
+- `npm run dev:tauri` - start the Tauri shell against the Vite renderer. The FastAPI backend is still external during migration work.
 - `npm run build` - build the renderer into `dist/`.
 - `npm start` - start Electron against the current app files.
 
@@ -47,6 +52,7 @@ There are currently no npm `test` or `lint` scripts in `package.json`.
 - `src/desktop/desktopApi.js` is the renderer's platform abstraction. Add desktop capabilities there first, then back them with Electron IPC. This keeps the future Tauri migration bounded.
 - `electron/preload.cjs` is the only file that should expose raw Electron IPC to the renderer.
 - `electron/main.cjs` owns desktop concerns: windows, dialogs, shell opening, settings persistence, update checks, and IPC implementations.
+- `src-tauri/src/main.rs` owns the Tauri implementation of the same renderer `desktopApi` surface during migration. Keep it additive and do not remove Electron behavior until Tauri reaches parity.
 - Backend code owns chat/session persistence, Ollama integration, Whisper transcription, web search enrichment, and RAG library processing.
 - Backend API contracts should stay stable unless intentionally coordinated with renderer changes. If a response/request shape changes in `backend/schemas.py` or route handlers, update the renderer callers in the same change.
 - Keep local RAG job orchestration and generated library state in the backend. Renderer code should use backend endpoints rather than reading library files directly.
@@ -62,6 +68,7 @@ Do not edit or commit generated/runtime data unless the task explicitly requires
 - `dist/` - Vite build output.
 - `__pycache__/`, `*.pyc`, `.DS_Store`, and similar machine-generated files.
 - Local app settings files under the Electron user data directory or `HEIMGEIST_SETTINGS_FILE`.
+- Tauri-generated `src-tauri/target/`, `src-tauri/gen/`, and local `src-tauri/Cargo.lock` if generated by local verification.
 
 Avoid broad file operations that traverse these directories. Use ignore patterns with search tools when inspecting the repo.
 
@@ -70,6 +77,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
 - Frontend changes: run `npm run build` at minimum. For UI or interaction changes, also run the dev stack and exercise the affected flow in Electron.
 - Backend changes: run a targeted syntax/import check such as `backend/.venv/bin/python -m py_compile backend/main.py backend/local_rag.py` for touched modules, then start `npm run dev:backend` or the full dev stack and check `GET /health`.
 - Desktop bridge/Electron changes: run the full dev stack with `npm run dev` and verify Electron launches, settings load/save, dialogs or shell actions work, and no renderer code bypasses `src/desktop/desktopApi.js`.
+- Tauri desktop bridge changes: run `cargo check --manifest-path src-tauri/Cargo.toml` with a temp `CARGO_TARGET_DIR` when useful, run `npm run build`, and if practical run `npm run dev:tauri` with a temporary `HEIMGEIST_SETTINGS_FILE` so local user settings are not modified during verification.
 - API contract changes: verify both sides together. Update backend schemas/routes and renderer callers in the same change, then exercise the affected request path.
 - RAG, Whisper, Ollama, or SearXNG changes: note any external services or local models required for verification, and test graceful failure paths when those services are unavailable.
 
@@ -77,6 +85,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
 
 - Do not start a Tauri migration opportunistically.
 - Keep new renderer desktop calls behind `src/desktop/desktopApi.js`; do not spread Electron-specific assumptions through React components.
+- Keep Tauri renderer calls behind `src/desktop/desktopApi.js`; do not import Tauri APIs directly in React components.
 - When adding desktop capabilities, prefer method names and payloads that could map cleanly to either Electron IPC or Tauri commands.
 - Maintain Electron behavior while any Tauri work is incomplete. Electron remains the supported desktop shell until Tauri reaches feature parity for settings, file picking/opening, external links, update flow, window events, backend startup expectations, and packaging.
 - Avoid refactors that mix migration prep with unrelated feature work. Migration work should be explicit and reviewable.

docs/tauri-migration.md

@@ -7,6 +7,8 @@ References checked during the spike:
 - Tauri Vite setup: https://v2.tauri.app/start/frontend/vite/
 - Tauri JavaScript API: https://v2.tauri.app/reference/javascript/api/
 - Tauri CLI: https://v2.tauri.app/reference/cli/
+- Tauri dialog plugin: https://v2.tauri.app/plugin/dialog/
+- Tauri opener plugin: https://v2.tauri.app/plugin/opener/
 
 ## Current Electron Responsibilities
 
@@ -14,12 +16,12 @@ References checked during the spike:
 | --- | --- | --- |
 | Main app window | `BrowserWindow` in `electron/main.cjs`, loading Vite in dev and `dist/index.html` in production | `src-tauri/tauri.conf.json` window loading the same Vite dev URL or `../dist` |
 | Settings window | Separate modal `BrowserWindow` routed to `#/settings` | Later phase: either a second Tauri webview window or in-app settings route |
-| Settings persistence | JSON file under Electron `app.getPath('userData')`, with migrations and normalization | Later phase: Tauri command backed by app config/data dir with the same setting keys and migrations |
-| Renderer bridge | `electron/preload.cjs` exposes `window.electronAPI`; renderer uses `src/desktop/desktopApi.js` | `desktopApi` can call Tauri commands through `window.__TAURI__.core.invoke` when running in Tauri |
-| File picker | `dialog.showOpenDialog` via `pick-paths` IPC | Later phase: official Tauri dialog plugin with scoped permissions |
-| Open file/path | `shell.openPath` via `open-path` IPC | Later phase: official Tauri opener plugin or a scoped Rust command |
-| External links | `shell.openExternal` and `setWindowOpenHandler` | Later phase: official Tauri opener plugin and window navigation policy |
-| Window focus events | Electron `focus` event forwarded to renderer | Later phase: Tauri window event listener or emitted command event |
+| Settings persistence | JSON file under Electron `app.getPath('userData')`, with migrations and normalization | Implemented for Tauri with `HEIMGEIST_SETTINGS_FILE` override or app config `settings.json`; keys and normalizers mirror Electron closely |
+| Renderer bridge | `electron/preload.cjs` exposes `window.electronAPI`; renderer uses `src/desktop/desktopApi.js` | Implemented: `desktopApi` still prefers Electron and falls back to Tauri commands/listeners |
+| File picker | `dialog.showOpenDialog` via `pick-paths` IPC | Implemented for Tauri through the official dialog plugin; supports existing `title` and `filters` options |
+| Open file/path | `shell.openPath` via `open-path` IPC | Implemented for Tauri through the official opener plugin |
+| External links | `shell.openExternal` and `setWindowOpenHandler` | Implemented for Tauri through the official opener plugin for `http`, `https`, `mailto`, and `tel` URLs |
+| Window focus events | Electron `focus` event forwarded to renderer | Implemented for Tauri by emitting `window-focused` and listening from `desktopApi` |
 | App menu | Electron `Menu.buildFromTemplate` | Later phase: Tauri menu API |
 | UI scale | Electron `webContents.setZoomFactor` | Later phase: Tauri/webview equivalent or renderer CSS scale strategy |
 | DevTools preference | Electron opens/closes DevTools in dev | Later phase: Tauri devtools behavior and persisted preference |
@@ -30,8 +32,8 @@ References checked during the spike:
 ## Scaffold Added
 
 - `src-tauri/tauri.conf.json` points Tauri at the existing Vite renderer on `http://127.0.0.1:5173` and the existing `dist` build output.
-- `src-tauri/src/main.rs` registers placeholder Tauri commands that match the current `desktopApi` surface.
-- `src-tauri/capabilities/default.json` grants the main window the default core capability for this spike.
+- `src-tauri/src/main.rs` registers Tauri commands for settings, file picking, path opening, external link opening, focus events, and update placeholders.
+- `src-tauri/capabilities/default.json` grants the main window core, dialog, and opener permissions used by this spike.
 - `src-tauri/icons/icon.png` is a placeholder icon required by Tauri context generation.
 - `src/desktop/desktopApi.js` still prefers Electron. When Electron is absent and Tauri is present, it invokes matching Tauri commands. Without either desktop bridge, it falls back to safe defaults so the renderer can mount.
 
@@ -46,15 +48,14 @@ References checked during the spike:
 
 - No Electron files, scripts, or IPC behavior were removed.
 - No Python backend sidecar, packaging, or lifecycle work was added.
-- No Tauri updater, opener, dialog, menu, or settings persistence parity was implemented.
-- The Tauri settings command is in-memory only and exists to let the renderer hydrate during the spike.
+- No Tauri updater, app menu, second settings window, UI zoom side effects, DevTools preference side effects, or packaging parity was implemented.
+- No Python backend sidecar or packaging work was added.
 
 ## Remaining Parity Gaps
 
-- Settings: persistent storage, migrations, normalization, UI scale side effects, DevTools preference side effects.
-- File picker: native picker and path filters.
-- Open path and external links: scoped native opener behavior.
-- Window focus events: renderer notification equivalent.
+- Settings: UI scale side effects and DevTools preference side effects are not wired in Tauri yet.
+- Settings window: Electron still has a separate modal settings window; Tauri currently uses the existing renderer route only.
+- App menu: Electron menu roles are not recreated in Tauri.
 - Update flow: startup/manual checks, changelog, restart, and signed release strategy.
 - Backend lifecycle: FastAPI startup, health gating, ffmpeg/ffprobe environment, shutdown, and sidecar packaging.
 - Packaging: bundle metadata, icons, signing/notarization, auto-update channel, and platform install behavior.