@dennisrongo/skills 0.1.2 → 0.2.0

package/skills/tauri-2-app/references/templates/cargo-toml.md

@@ -0,0 +1,118 @@
+# `src-tauri/Cargo.toml`
+
+Pin **Rust edition** to `2021`. Resolve crate **versions** at scaffold time via crates.io / context7 — never hard-paste a version into a generated file. The version markers below are placeholders.
+
+```toml
+[package]
+name = "{{app_name}}"
+version = "0.1.0"
+description = "{{description}}"
+authors = ["{{author}}"]
+license = "MIT"
+edition = "2021"
+default-run = "{{app_name}}"
+
+[lib]
+# The `_lib` suffix avoids a Windows linker conflict between the bin and lib targets.
+# See https://github.com/rust-lang/cargo/issues/8519
+name = "{{app_name}}_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[[bin]]
+name = "{{app_name}}"
+path = "src/main.rs"
+
+[build-dependencies]
+tauri-build = { version = "<latest 2.x>", features = [] }
+
+[dependencies]
+# Tauri core (2.x). Add features as needed: "tray-icon", "macos-private-api"
+tauri = { version = "<latest 2.x>", features = [] }
+
+# Tauri plugins — only those actually wired in lib.rs
+tauri-plugin-opener = "<latest 2.x>"
+tauri-plugin-dialog = "<latest 2.x>"
+tauri-plugin-fs = "<latest 2.x>"
+tauri-plugin-notification = "<latest 2.x>"
+tauri-plugin-global-shortcut = "<latest 2.x>"
+tauri-plugin-single-instance = "<latest 2.x>"
+# tauri-plugin-updater = "<latest 2.x>"   # only if updater is wired
+# tauri-plugin-process = "<latest 2.x>"
+
+# Serialization
+serde = { version = "<latest 1.x>", features = ["derive"] }
+serde_json = "<latest 1.x>"
+
+# Errors
+thiserror = "<latest>"
+anyhow = "<latest>"
+
+# Async runtime
+tokio = { version = "<latest 1.x>", features = ["sync", "rt-multi-thread", "macros"] }
+
+# Logging
+tracing = "<latest>"
+tracing-subscriber = { version = "<latest>", features = ["env-filter"] }
+
+# Date/time — DO NOT hand-roll
+chrono = "<latest>"
+
+# Paths
+dirs = "<latest>"
+
+# Optional: encrypted secrets at rest
+aes-gcm = "<latest>"
+argon2 = "<latest>"
+base64 = "<latest>"
+rand = "<latest>"
+
+# macOS-specific
+[target.'cfg(target_os = "macos")'.dependencies]
+embed_plist = "<latest>"
+# Add when used:
+# security-framework = "<latest>"
+# cocoa = "<latest>"
+# objc = "<latest>"
+# core-graphics = "<latest>"
+
+# Windows-specific
+[target.'cfg(target_os = "windows")'.dependencies]
+# Add only the windows-sys features actually referenced in code:
+# windows-sys = { version = "<latest>", features = [
+#     "Win32_Foundation",
+#     "Win32_System_ProcessStatus",
+# ] }
+
+# Linux-specific
+[target.'cfg(target_os = "linux")'.dependencies]
+# machine-uid = "<latest>"   # only if encryption module needs a stable machine ID
+
+# Release profile — full LTO + smaller binary
+[profile.release]
+lto = "fat"
+codegen-units = 1
+opt-level = 3
+strip = true
+panic = "abort"
+
+# Dev profile — light optimization keeps debug builds bearable
+[profile.dev]
+opt-level = 1
+
+[dev-dependencies]
+tempfile = "<latest>"          # temporary fixtures
+assert_matches = "<latest>"
+pretty_assertions = "<latest>" # readable diffs in test failures
+tokio-test = "<latest>"        # async test helpers
+# mockall = "<latest>"         # only if trait-based mocking is set up
+# proptest = "<latest>"        # only if property tests are in scope
+```
+
+## Why
+
+- **`[lib].name = "{{app_name}}_lib"`** — Without the `_lib` suffix, Windows fails to link because the bin and lib targets generate conflicting symbols.
+- **`crate-type = ["staticlib", "cdylib", "rlib"]`** — `cdylib` is for mobile (Android/iOS) targets, `staticlib` for some embedded uses, `rlib` for integration tests. Tauri's mobile work needs all three.
+- **Target-specific `[target.'cfg(...)'.dependencies]`** — Platform-only crates (`cocoa`, `windows-sys`) only compile on the matching target. The `[target.cfg(...)]` syntax means a `cargo build` on a different OS skips them entirely.
+- **`tauri-plugin-single-instance` listed under regular deps** — It works cross-platform; the plugin internally handles per-OS specifics.
+- **Release profile** — `lto = "fat"` enables cross-crate inlining (faster, smaller). `codegen-units = 1` is required for full LTO. `strip = true` drops symbols (~30% binary size reduction). `panic = "abort"` skips unwinding tables.
+- **Dev profile `opt-level = 1`** — Cuts debug-build runtime by 2–3× vs. `opt-level = 0`, with only a minor compile-time hit. Especially noticeable for tests that exercise crypto or audio processing.

package/skills/tauri-2-app/references/templates/ci-workflow.md

@@ -0,0 +1,99 @@
+# `.github/workflows/unit-tests.yml`
+
+Cross-platform matrix that runs `cargo test` on every push and PR. Ubuntu needs GTK system deps for Tauri to link.
+
+```yaml
+name: Unit Tests
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [macos-latest, windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Cache cargo registry + build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src-tauri/target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('src-tauri/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - run: npm ci
+
+      - name: Install Ubuntu system deps
+        if: matrix.platform == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgtk-3-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev \
+            libwebkit2gtk-4.1-dev \
+            pkg-config
+
+      - name: Run Rust tests
+        run: cd src-tauri && cargo test --all-features
+
+      - name: TypeScript build
+        run: npm run build
+```
+
+## Why these choices
+
+- **`fail-fast: false`** — Without it, a failure on macOS cancels the Windows and Ubuntu jobs. You want to see all three results to know whether the bug is platform-specific.
+- **Three runners** — Tauri's behavior diverges per OS (file pickers, permissions, hotkeys). Green on one runner means little.
+- **Ubuntu system deps** — Tauri's webview integration on Linux needs GTK, AppIndicator, RSVG, WebKit2GTK. Without them, `cargo build` fails with cryptic linker errors.
+- **Cache key includes `Cargo.lock`** — Re-key the cache when dependencies change. Without the `restore-keys` fallback, a single dep bump invalidates the whole cache.
+- **`npm ci`** (not `npm install`) — Faster, deterministic, fails if `package-lock.json` is out of sync.
+- **`cargo test --all-features`** — If you have feature flags, run tests across them. Drop `--all-features` if you have features that intentionally conflict.
+
+## Optional: TypeScript-only quick check
+
+If the Rust matrix is slow and you want fast feedback on frontend changes, add a parallel job:
+
+```yaml
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx tsc --noEmit
+```
+
+Runs in seconds and catches the majority of frontend regressions without spinning up the Rust toolchain.
+
+## Optional: Tag-triggered release workflow
+
+Skipping the full template here because the publish pipeline depends heavily on the user's distribution choice (GitHub Releases, R2, S3, custom CDN, …) and their signing setup. Key points if you generate one:
+
+- **Never hardcode the CDN URL** or any signing identity in the workflow file — read them from `secrets.*`.
+- **Build matrix typically includes only signed targets** (Windows + macOS aarch64 / x86_64). Linux builds may not need signing depending on distribution.
+- **Updater manifest generation** assembles the JSON shape documented in `references/templates/tauri-conf.md` from each platform's `.sig` file outputs.
+- **Notarization on macOS** (`xcrun notarytool submit ... --wait`) is mandatory for unsigned-runtime users; budget 5–15 minutes per build.
+
+Ask the user for the distribution target (GitHub Releases, R2, S3, custom) before generating a release workflow. Don't assume.

package/skills/tauri-2-app/references/templates/encryption-mod.md

@@ -0,0 +1,228 @@
+# `src-tauri/src/encryption/mod.rs` (optional)
+
+Authenticated encryption for API keys / tokens / other secrets at rest. Pattern: AES-256-GCM ciphertext + Argon2id-derived key from a per-install salt + a hardware-bound machine ID for additional binding.
+
+Only generate this module if the user explicitly asked for it. Many apps don't need it (they store no secrets) or use OS-native keychains (`security-framework` on macOS, Windows DPAPI, Linux Secret Service) instead.
+
+```rust
+//! Encrypted secrets at rest. AES-256-GCM + Argon2id + hardware-bound salt.
+//!
+//! Threat model: protects against casual disk reads (backup syncs, malware
+//! grepping files, accidental leaks via shared screenshots). Does NOT protect
+//! against a privileged process on the same machine. For higher assurance,
+//! integrate the OS-native keychain.
+
+use aes_gcm::{
+    aead::{Aead, AeadCore, KeyInit, OsRng},
+    Aes256Gcm, Nonce,
+};
+use argon2::{Algorithm, Argon2, Params, Version};
+use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EncryptedApiKey {
+    pub ciphertext: String,  // base64
+    pub nonce: String,       // base64 (12 bytes)
+    pub salt: String,        // base64 (≥16 bytes)
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum EncryptionError {
+    #[error("key derivation failed: {0}")]
+    KeyDerivation(String),
+    #[error("encryption failed: {0}")]
+    Encrypt(String),
+    #[error("decryption failed: {0}")]
+    Decrypt(String),
+    #[error("invalid base64: {0}")]
+    Base64(#[from] base64::DecodeError),
+    #[error("invalid machine ID: {0}")]
+    MachineId(String),
+}
+
+/// Hardware-bound machine identifier. Combined with the per-install salt.
+fn get_machine_id() -> Result<String, EncryptionError> {
+    #[cfg(target_os = "macos")]
+    {
+        let out = std::process::Command::new("ioreg")
+            .args(["-rd1", "-c", "IOPlatformExpertDevice"])
+            .output()
+            .map_err(|e| EncryptionError::MachineId(e.to_string()))?;
+        let s = String::from_utf8_lossy(&out.stdout);
+        for line in s.lines() {
+            if line.contains("IOPlatformUUID") {
+                if let (Some(a), Some(b)) = (line.find('"'), line.rfind('"')) {
+                    if a != b { return Ok(line[a + 1..b].to_string()); }
+                }
+            }
+        }
+        Err(EncryptionError::MachineId("IOPlatformUUID not found".into()))
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        use std::os::windows::process::CommandExt;
+        const CREATE_NO_WINDOW: u32 = 0x08000000;
+        let out = std::process::Command::new("cmd")
+            .creation_flags(CREATE_NO_WINDOW)
+            .args(["/C", "wmic csproduct get uuid"])
+            .output()
+            .map_err(|e| EncryptionError::MachineId(e.to_string()))?;
+        let s = String::from_utf8_lossy(&out.stdout);
+        for line in s.lines().map(str::trim) {
+            if !line.is_empty() && !line.contains("UUID") {
+                return Ok(line.to_string());
+            }
+        }
+        Err(EncryptionError::MachineId("UUID not found".into()))
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        // /etc/machine-id is stable per install on most distros.
+        match std::fs::read_to_string("/etc/machine-id") {
+            Ok(s) => Ok(s.trim().to_string()),
+            Err(_) => Err(EncryptionError::MachineId("/etc/machine-id unavailable".into())),
+        }
+    }
+}
+
+fn derive_key(machine_id: &str, salt: &[u8]) -> Result<[u8; 32], EncryptionError> {
+    // Argon2id parameters tuned for ~300ms on a modern laptop. Tune as the
+    // user-facing latency budget allows.
+    let params = Params::new(64 * 1024, 3, 1, Some(32))
+        .map_err(|e| EncryptionError::KeyDerivation(e.to_string()))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+
+    let mut key = [0u8; 32];
+    argon2
+        .hash_password_into(machine_id.as_bytes(), salt, &mut key)
+        .map_err(|e| EncryptionError::KeyDerivation(e.to_string()))?;
+    Ok(key)
+}
+
+pub fn encrypt_api_key(plaintext: &str) -> Result<EncryptedApiKey, EncryptionError> {
+    let machine_id = get_machine_id()?;
+
+    // Per-encryption salt; never reuse.
+    let mut salt = [0u8; 16];
+    use rand::RngCore;
+    rand::rngs::OsRng.fill_bytes(&mut salt);
+
+    let key_bytes = derive_key(&machine_id, &salt)?;
+    let cipher = Aes256Gcm::new_from_slice(&key_bytes)
+        .map_err(|e| EncryptionError::Encrypt(e.to_string()))?;
+
+    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
+    let ciphertext = cipher
+        .encrypt(&nonce, plaintext.as_bytes())
+        .map_err(|e| EncryptionError::Encrypt(e.to_string()))?;
+
+    Ok(EncryptedApiKey {
+        ciphertext: BASE64.encode(&ciphertext),
+        nonce: BASE64.encode(nonce),
+        salt: BASE64.encode(salt),
+    })
+}
+
+pub fn decrypt_api_key(enc: &EncryptedApiKey) -> Result<String, EncryptionError> {
+    let machine_id = get_machine_id()?;
+    let salt = BASE64.decode(&enc.salt)?;
+    let nonce_bytes = BASE64.decode(&enc.nonce)?;
+    let ciphertext = BASE64.decode(&enc.ciphertext)?;
+
+    let key_bytes = derive_key(&machine_id, &salt)?;
+    let cipher = Aes256Gcm::new_from_slice(&key_bytes)
+        .map_err(|e| EncryptionError::Decrypt(e.to_string()))?;
+
+    let nonce = Nonce::from_slice(&nonce_bytes);
+    let plaintext = cipher
+        .decrypt(nonce, ciphertext.as_ref())
+        .map_err(|e| EncryptionError::Decrypt(e.to_string()))?;
+
+    String::from_utf8(plaintext).map_err(|e| EncryptionError::Decrypt(e.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn round_trip() {
+        let secret = "sk-test-1234567890";
+        let encrypted = encrypt_api_key(secret).expect("encrypt");
+        let decrypted = decrypt_api_key(&encrypted).expect("decrypt");
+        assert_eq!(decrypted, secret);
+    }
+
+    #[test]
+    fn different_ciphertext_each_time() {
+        // Different salts + nonces should produce different ciphertexts.
+        let a = encrypt_api_key("same secret").unwrap();
+        let b = encrypt_api_key("same secret").unwrap();
+        assert_ne!(a.ciphertext, b.ciphertext);
+    }
+}
+```
+
+## Dependencies needed in `Cargo.toml`
+
+```toml
+aes-gcm = "<latest>"
+argon2 = "<latest>"
+base64 = "<latest>"
+rand = "<latest>"
+thiserror = "<latest>"
+```
+
+## Auto-migrate plaintext on load
+
+When deserializing settings, detect legacy plaintext API keys and re-encrypt:
+
+```rust
+// In settings/storage.rs deserialize_settings(&Value):
+if let Some(v) = json.get("openaiApiKey") {
+    if let Some(obj) = v.as_object() {
+        if let (Some(ct), Some(n), Some(s)) = (
+            obj.get("ciphertext").and_then(|x| x.as_str()),
+            obj.get("nonce").and_then(|x| x.as_str()),
+            obj.get("salt").and_then(|x| x.as_str()),
+        ) {
+            settings.openai_api_key = Some(EncryptedApiKey {
+                ciphertext: ct.into(), nonce: n.into(), salt: s.into(),
+            });
+        }
+    } else if let Some(plaintext) = v.as_str() {
+        // Try parsing as already-encrypted JSON string first.
+        if let Ok(enc) = serde_json::from_str::<EncryptedApiKey>(plaintext) {
+            settings.openai_api_key = Some(enc);
+        } else if !plaintext.is_empty() {
+            // Legacy plaintext — auto-migrate.
+            tracing::warn!("Found plaintext API key — migrating to encrypted format");
+            if let Ok(enc) = crate::encryption::encrypt_api_key(plaintext) {
+                settings.openai_api_key = Some(enc);
+            }
+        }
+    }
+}
+```
+
+## Threat model — be honest
+
+This module protects against:
+- Disk reads by other users on a shared machine (when filesystem permissions are correct).
+- Stolen settings files / backup leaks.
+- Casual scanning by malware that doesn't escalate privileges.
+
+This module does **not** protect against:
+- A privileged process on the same user account (it can read `IOPlatformUUID` and reproduce the same key).
+- A debugger attached to the running app (memory has plaintext after decrypt).
+- Hardware-level attacks (cold boot, side channels).
+
+For higher assurance, integrate the OS keychain:
+- macOS: `security-framework` crate, `SecKeychainItem`.
+- Windows: `windows-sys` + DPAPI (`CryptProtectData`).
+- Linux: `libsecret` via the `secret-service` crate.
+
+Document the threat model in your project's `SECURITY.md` so users have realistic expectations.

package/skills/tauri-2-app/references/templates/error-mod.md

@@ -0,0 +1,126 @@
+# `src-tauri/src/error/mod.rs`
+
+The shared error-conversion utilities for Tauri commands. Internal APIs use `thiserror` enums; commands convert at the IPC boundary with `into_string_err!` or `ResultExt`.
+
+```rust
+//! Error handling utilities — keeps command boilerplate tight.
+
+/// Convert any error to a String at the call site.
+///
+/// ```ignore
+/// let r = into_string_err!(some_fallible());                 // "<err>"
+/// let r = into_string_err!(some_fallible(), "Failed to X");  // "Failed to X: <err>"
+/// let r = into_string_err!(some_fallible(), "Loading {}", path);
+/// ```
+#[macro_export]
+macro_rules! into_string_err {
+    ($expr:expr) => { $expr.map_err(|e| e.to_string()) };
+    ($expr:expr, $msg:expr) => { $expr.map_err(|e| format!("{}: {}", $msg, e)) };
+    ($expr:expr, $fmt:expr, $($arg:tt)*) => {
+        $expr.map_err(|e| format!("{}: {}", format!($fmt, $($arg)*), e))
+    };
+}
+
+/// `?`-propagating variant.
+///
+/// ```ignore
+/// fn cmd() -> Result<T, String> {
+///     let x = try_into_string_err!(some_fallible());
+///     Ok(x)
+/// }
+/// ```
+#[macro_export]
+macro_rules! try_into_string_err {
+    ($expr:expr) => { $expr.map_err(|e| e.to_string())? };
+    ($expr:expr, $msg:expr) => { $expr.map_err(|e| format!("{}: {}", $msg, e))? };
+}
+
+/// Extension trait so you can write `result.into_string()` / `.into_string_msg("...")`.
+pub trait ResultExt<T, E>: Sized {
+    fn into_string(self) -> Result<T, String>;
+    fn into_string_msg(self, msg: &str) -> Result<T, String>;
+}
+
+impl<T, E: std::fmt::Display> ResultExt<T, E> for Result<T, E> {
+    fn into_string(self) -> Result<T, String> {
+        self.map_err(|e| e.to_string())
+    }
+    fn into_string_msg(self, msg: &str) -> Result<T, String> {
+        self.map_err(|e| format!("{}: {}", msg, e))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn macro_no_context() {
+        fn f() -> Result<(), &'static str> { Err("boom") }
+        let r: Result<(), String> = into_string_err!(f());
+        assert_eq!(r.unwrap_err(), "boom");
+    }
+
+    #[test]
+    fn macro_with_context() {
+        fn f() -> Result<(), &'static str> { Err("boom") }
+        let r: Result<(), String> = into_string_err!(f(), "Failed");
+        assert_eq!(r.unwrap_err(), "Failed: boom");
+    }
+
+    #[test]
+    fn ext_trait() {
+        fn f() -> Result<(), &'static str> { Err("boom") }
+        let r = f().into_string_msg("Context");
+        assert_eq!(r.unwrap_err(), "Context: boom");
+    }
+}
+```
+
+## How to use it
+
+Define rich internal error types with `thiserror`:
+
+```rust
+// src-tauri/src/settings/mod.rs
+#[derive(Debug, thiserror::Error)]
+pub enum SettingsError {
+    #[error("settings file not found: {0}")]
+    NotFound(std::path::PathBuf),
+    #[error("invalid JSON: {0}")]
+    InvalidJson(#[from] serde_json::Error),
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+pub fn load(app: &AppHandle) -> Result<Settings, SettingsError> { /* ... */ }
+```
+
+Then convert at the command boundary:
+
+```rust
+// src-tauri/src/commands/settings.rs
+use crate::error::ResultExt;
+
+#[tauri::command]
+pub fn get_settings(app: tauri::AppHandle) -> Result<Settings, String> {
+    crate::settings::load(&app).into_string_msg("Failed to load settings")
+}
+```
+
+## Why two flavors
+
+- `into_string_err!` is a macro because some `?`-heavy command bodies are cleaner with the macro form.
+- `ResultExt` is a trait because it composes — `something.into_string().map(|v| ...)` flows naturally in chains.
+
+Pick the one that reads better at the call site. Don't bikeshed; consistency within a single module matters more than which form you chose globally.
+
+## Why convert at the boundary, not throughout
+
+If every internal function returned `Result<T, String>`:
+- Type information is lost (was it I/O? parsing? permissions?).
+- Adding `#[from]` conversions becomes impossible.
+- Tests that assert on error variants can't.
+- Callers can't decide to handle some errors and propagate others — every string looks the same.
+
+Keep `thiserror` types as long as possible, convert only when crossing into a `#[tauri::command]`.

package/skills/tauri-2-app/references/templates/lib-rs.md

@@ -0,0 +1,98 @@
+# `src-tauri/src/lib.rs`
+
+The single source of truth for module wiring, plugin registration, and command handler registration. Keep `run()` lean — defer initialization work to background threads.
+
+```rust
+// Module declarations
+pub mod commands;
+mod error;
+mod platform;
+mod settings;
+mod state;
+mod storage;
+// add per-feature modules here: mod audio; mod history; ...
+
+// Re-exports for integration tests
+pub use settings::Settings;
+pub use state::AppState;
+pub use storage::{generate_id, get_app_data_dir, get_storage_path, load_json, save_json};
+pub use error::ResultExt;
+
+use tauri::Manager;
+use tracing::info;
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    // Initialize tracing FIRST so plugin init logs are captured
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::from_default_env()
+                .add_directive(tracing::Level::INFO.into()),
+        )
+        .init();
+
+    tauri::Builder::default()
+        // Single-instance MUST register first so a second launch is intercepted
+        // before any other plugin initializes resources.
+        .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| {
+            if let Some(window) = app.get_webview_window("main") {
+                let _ = window.show();
+                let _ = window.set_focus();
+                let _ = window.unminimize();
+            }
+        }))
+        .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_dialog::init())
+        .plugin(tauri_plugin_fs::init())
+        .plugin(tauri_plugin_notification::init())
+        .plugin(tauri_plugin_global_shortcut::Builder::new().build())
+        .plugin(tauri_plugin_process::init())
+        // .plugin(tauri_plugin_updater::Builder::new().build())  // enable if updater is wired
+        .setup(|app| {
+            info!("App setup starting");
+
+            // Manage shared state
+            let state = std::sync::Mutex::new(state::AppState::new());
+            app.manage(state);
+
+            // Load settings synchronously (small file, fast)
+            let app_handle = app.handle().clone();
+            let settings = settings::load_settings(&app_handle);
+            if let Ok(mut s) = app.state::<std::sync::Mutex<state::AppState>>().lock() {
+                s.app_handle = Some(app_handle.clone());
+                s.settings = Some(settings);
+            }
+
+            // Heavy initialization on a background thread — keep .setup() fast
+            // so the window appears immediately.
+            std::thread::spawn(move || {
+                // model load, audio device enumeration, etc.
+                // emit progress back: let _ = app_handle.emit("init-progress", ...);
+            });
+
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![
+            // System commands
+            commands::write_file,
+            commands::save_file_dialog,
+            commands::open_file_dialog,
+            // Settings commands
+            settings::get_settings,
+            settings::save_settings_command,
+            settings::reset_settings_command,
+            // Add per-domain commands here
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+## Why
+
+- **Tracing initialized first** — Plugins log during their `init()` call. If `tracing_subscriber` registers later, those logs are silently dropped.
+- **`tauri_plugin_single_instance::init` registers first** — The plugin's IPC hook needs to fire before any other plugin claims a resource (lock file, IPC socket, audio device). Registering it last is a known footgun.
+- **`.setup()` is fast** — The window appears as soon as `.setup()` returns. Anything synchronous in there delays first paint. Synchronous settings load is OK (small JSON file); model loading / network calls are not.
+- **`pub mod commands; mod error;` pattern** — `commands` is `pub` so integration tests can call individual commands directly. Domain modules (`error`, `state`) stay private with selective re-exports.
+- **Re-exports for tests** — Integration tests in `src-tauri/tests/` import via `use {{app_name}}_lib::{Settings, AppState};`. Re-exporting at the crate root means tests don't need to know the internal module path.
+- **`tauri::generate_handler!` is one list** — Tauri verifies the macro expansion at compile time. Splitting it across files isn't supported; keep all commands in one `generate_handler![...]` block.