⚡ perf: stale-while-revalidate cache — always instant startup

Cache is now returned immediately on every run. When stale (age >
cache_ttl_hours), a detached background process rebuilds it
incrementally via --background-refresh, so blocking scans never
happen in the foreground after the first run.

cache_ttl_hours is now actually enforced (previously ignored).

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [0.9.2] - 2026-03-04
+
+### Changed
+- Cache now uses stale-while-revalidate: cached projects are returned immediately and a background process (`--background-refresh`) rebuilds the cache when it is stale, eliminating blocking scans on every invocation
+- `cache_ttl_hours` is now enforced: when the cache age exceeds the configured TTL, a background refresh is triggered automatically
+
+## [0.9.1] - 2026-03-01
+
+### Fixed
+- Shortcut and desktop integration wizards are now offered regardless of whether the user chose the interactive wizard or the default config on first run; previously they were only offered in the wizard path
+
+## [0.9.0] - 2026-03-01
+
+### Added
+- First-run setup choice prompt: when no configuration file exists, tmuxido now asks whether to run the interactive wizard or apply sensible defaults immediately
+- `SetupChoice` enum and `parse_setup_choice_input` in `ui` module (pure, fully tested)
+- `Config::write_default_config` helper for writing defaults without any prompts
+- `Config::run_wizard` extracted from `ensure_config_exists` for clarity and testability
+- `render_setup_choice_prompt` and `render_default_config_saved` render functions
+
 ## [0.8.3] - 2026-03-01
 
 ### Fixed

Cargo.lock

@@ -857,7 +857,7 @@ dependencies = [
 
 [[package]]
 name = "tmuxido"
-version = "0.8.3"
+version = "0.9.2"
 dependencies = [
  "anyhow",
  "clap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tmuxido"
-version = "0.8.3"
+version = "0.9.2"
 edition = "2024"
 
 [dev-dependencies]

src/config.rs

@@ -96,42 +96,22 @@ impl Config {
                 )
             })?;
 
-            // Run interactive configuration wizard
-            let paths = Self::prompt_for_paths()?;
-            let max_depth = Self::prompt_for_max_depth()?;
-            let cache_enabled = Self::prompt_for_cache_enabled()?;
-            let cache_ttl_hours = if cache_enabled {
-                Self::prompt_for_cache_ttl()?
-            } else {
-                24
-            };
-            let windows = Self::prompt_for_windows()?;
+            // Ask whether to run the interactive wizard or apply sensible defaults
+            let raw = ui::render_setup_choice_prompt()?;
+            match ui::parse_setup_choice_input(&raw) {
+                ui::SetupChoice::Default => {
+                    Self::write_default_config(&config_path)?;
+                    ui::render_default_config_saved(&config_path.display().to_string());
+                }
+                ui::SetupChoice::Wizard => {
+                    Self::run_wizard(&config_path)?;
+                }
+            }
 
-            // Render styled success message before moving windows
-            ui::render_config_created(&paths, max_depth, cache_enabled, cache_ttl_hours, &windows);
-
-            let config = Config {
-                paths: paths.clone(),
-                max_depth,
-                cache_enabled,
-                cache_ttl_hours,
-                update_check_interval_hours: default_update_check_interval_hours(),
-                default_session: SessionConfig { windows },
-            };
-
-            let toml_string =
-                toml::to_string_pretty(&config).context("Failed to serialize config")?;
-
-            fs::write(&config_path, toml_string).with_context(|| {
-                format!("Failed to write config file: {}", config_path.display())
-            })?;
-
-            // Offer to set up a keyboard shortcut (best-effort, non-fatal)
+            // Offer shortcut and desktop integration regardless of setup mode
             if let Err(e) = crate::shortcut::setup_shortcut_wizard() {
                 eprintln!("Warning: shortcut setup failed: {}", e);
             }
-
-            // Offer to install .desktop entry + icon (best-effort, non-fatal)
             if let Err(e) = crate::shortcut::setup_desktop_integration_wizard() {
                 eprintln!("Warning: desktop integration failed: {}", e);
             }
@@ -140,6 +120,44 @@ impl Config {
         Ok(config_path)
     }
 
+    /// Write the built-in default config to `config_path` without any prompts.
+    fn write_default_config(config_path: &std::path::Path) -> Result<()> {
+        let config = Self::default_config();
+        let toml_string = toml::to_string_pretty(&config).context("Failed to serialize config")?;
+        fs::write(config_path, toml_string)
+            .with_context(|| format!("Failed to write config file: {}", config_path.display()))
+    }
+
+    /// Run the full interactive configuration wizard and offer shortcut / desktop setup at the end.
+    fn run_wizard(config_path: &std::path::Path) -> Result<()> {
+        let paths = Self::prompt_for_paths()?;
+        let max_depth = Self::prompt_for_max_depth()?;
+        let cache_enabled = Self::prompt_for_cache_enabled()?;
+        let cache_ttl_hours = if cache_enabled {
+            Self::prompt_for_cache_ttl()?
+        } else {
+            24
+        };
+        let windows = Self::prompt_for_windows()?;
+
+        // Render styled success message before moving windows
+        ui::render_config_created(&paths, max_depth, cache_enabled, cache_ttl_hours, &windows);
+
+        let config = Config {
+            paths,
+            max_depth,
+            cache_enabled,
+            cache_ttl_hours,
+            update_check_interval_hours: default_update_check_interval_hours(),
+            default_session: SessionConfig { windows },
+        };
+
+        let toml_string = toml::to_string_pretty(&config).context("Failed to serialize config")?;
+
+        fs::write(config_path, toml_string)
+            .with_context(|| format!("Failed to write config file: {}", config_path.display()))
+    }
+
     fn prompt_for_paths() -> Result<Vec<String>> {
         // Render styled welcome banner
         ui::render_welcome_banner();
@@ -377,6 +395,35 @@ mod tests {
         assert_eq!(ui::parse_layout_input("invalid"), None);
     }
 
+    #[test]
+    fn should_write_default_config_to_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let config_path = dir.path().join("tmuxido.toml");
+
+        Config::write_default_config(&config_path).unwrap();
+
+        assert!(config_path.exists());
+        let content = std::fs::read_to_string(&config_path).unwrap();
+        let loaded: Config = toml::from_str(&content).unwrap();
+        assert!(!loaded.paths.is_empty());
+        assert_eq!(loaded.max_depth, 5);
+        assert!(loaded.cache_enabled);
+        assert_eq!(loaded.cache_ttl_hours, 24);
+    }
+
+    #[test]
+    fn should_write_valid_toml_in_default_config() {
+        let dir = tempfile::tempdir().unwrap();
+        let config_path = dir.path().join("tmuxido.toml");
+
+        Config::write_default_config(&config_path).unwrap();
+
+        let content = std::fs::read_to_string(&config_path).unwrap();
+        // Must parse cleanly
+        let result: Result<Config, _> = toml::from_str(&content);
+        assert!(result.is_ok(), "Default config must be valid TOML");
+    }
+
     #[test]
     fn should_parse_config_with_windows_and_panes() {
         let toml_str = r#"

src/lib.rs

@@ -55,9 +55,47 @@ pub fn get_projects(config: &Config, force_refresh: bool) -> Result<Vec<PathBuf>
         &ProjectCache::load,
         &|cache| cache.save(),
         &scan_all_roots,
+        &spawn_background_refresh,
     )
 }
 
+/// Rebuilds the project cache incrementally. Intended to be called from a
+/// background process spawned by `get_projects` via stale-while-revalidate.
+pub fn refresh_cache(config: &Config) -> Result<()> {
+    match ProjectCache::load()? {
+        None => {
+            let (projects, fingerprints) = scan_all_roots(config)?;
+            ProjectCache::new(projects, fingerprints).save()?;
+        }
+        Some(mut cache) => {
+            if cache.dir_mtimes.is_empty() {
+                // Old cache format — full rescan
+                let (projects, fingerprints) = scan_all_roots(config)?;
+                ProjectCache::new(projects, fingerprints).save()?;
+            } else {
+                // Incremental rescan based on directory mtimes
+                let changed = cache.validate_and_update(&|root| scan_from_root(root, config))?;
+                if changed {
+                    cache.save()?;
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+fn spawn_background_refresh() {
+    if let Ok(exe) = std::env::current_exe() {
+        std::process::Command::new(exe)
+            .arg("--background-refresh")
+            .stdin(std::process::Stdio::null())
+            .stdout(std::process::Stdio::null())
+            .stderr(std::process::Stdio::null())
+            .spawn()
+            .ok();
+    }
+}
+
 #[allow(clippy::type_complexity)]
 fn get_projects_internal(
     config: &Config,
@@ -65,45 +103,31 @@ fn get_projects_internal(
     cache_loader: &dyn Fn() -> Result<Option<ProjectCache>>,
     cache_saver: &dyn Fn(&ProjectCache) -> Result<()>,
     scanner: &dyn Fn(&Config) -> Result<(Vec<PathBuf>, HashMap<PathBuf, u64>)>,
+    refresh_spawner: &dyn Fn(),
 ) -> Result<Vec<PathBuf>> {
     if !config.cache_enabled || force_refresh {
         let (projects, fingerprints) = scanner(config)?;
         let cache = ProjectCache::new(projects.clone(), fingerprints);
         cache_saver(&cache)?;
-        eprintln!("Cache updated with {} projects", projects.len());
         return Ok(projects);
     }
 
-    if let Some(mut cache) = cache_loader()? {
-        // Cache no formato antigo (sem dir_mtimes) → atualizar com rescan completo
-        if cache.dir_mtimes.is_empty() {
-            eprintln!("Upgrading cache, scanning for projects...");
-            let (projects, fingerprints) = scanner(config)?;
-            let new_cache = ProjectCache::new(projects.clone(), fingerprints);
-            cache_saver(&new_cache)?;
-            eprintln!("Cache updated with {} projects", projects.len());
-            return Ok(projects);
-        }
-
-        let changed = cache.validate_and_update(&|root| scan_from_root(root, config))?;
-        if changed {
-            cache_saver(&cache)?;
-            eprintln!(
-                "Cache updated incrementally ({} projects)",
-                cache.projects.len()
-            );
-        } else {
-            eprintln!("Using cached projects ({} projects)", cache.projects.len());
+    if let Some(cache) = cache_loader()? {
+        // Cache exists — return immediately (stale-while-revalidate).
+        // Spawn a background refresh if the cache is stale or in old format.
+        let is_stale =
+            cache.dir_mtimes.is_empty() || cache.age_in_seconds() > config.cache_ttl_hours * 3600;
+        if is_stale {
+            refresh_spawner();
         }
         return Ok(cache.projects);
     }
 
-    // Sem cache ainda — scan completo inicial
+    // No cache yet — first run, blocking scan is unavoidable.
     eprintln!("No cache found, scanning for projects...");
     let (projects, fingerprints) = scanner(config)?;
     let cache = ProjectCache::new(projects.clone(), fingerprints);
     cache_saver(&cache)?;
-    eprintln!("Cache updated with {} projects", projects.len());
     Ok(projects)
 }
 
@@ -196,242 +220,208 @@ mod tests {
     use super::*;
     use std::cell::RefCell;
 
-    fn create_test_config(cache_enabled: bool) -> Config {
+    fn make_config(cache_enabled: bool, cache_ttl_hours: u64) -> Config {
         Config {
             paths: vec!["/tmp/test".to_string()],
             max_depth: 3,
             cache_enabled,
-            cache_ttl_hours: 24,
+            cache_ttl_hours,
             update_check_interval_hours: 24,
             default_session: session::SessionConfig { windows: vec![] },
         }
     }
 
+    fn fresh_cache(projects: Vec<PathBuf>) -> ProjectCache {
+        let fingerprints = HashMap::from([(PathBuf::from("/tracked"), 1u64)]);
+        ProjectCache::new(projects, fingerprints)
+        // last_updated = now_secs() — within any reasonable TTL
+    }
+
+    fn stale_cache(projects: Vec<PathBuf>) -> ProjectCache {
+        let fingerprints = HashMap::from([(PathBuf::from("/tracked"), 1u64)]);
+        let mut c = ProjectCache::new(projects, fingerprints);
+        c.last_updated = 0; // epoch — always older than TTL
+        c
+    }
+
+    fn call_internal(
+        config: &Config,
+        force_refresh: bool,
+        cache_loader: &dyn Fn() -> Result<Option<ProjectCache>>,
+        cache_saver: &dyn Fn(&ProjectCache) -> Result<()>,
+        scanner: &dyn Fn(&Config) -> Result<(Vec<PathBuf>, HashMap<PathBuf, u64>)>,
+        refresh_spawner: &dyn Fn(),
+    ) -> Result<Vec<PathBuf>> {
+        get_projects_internal(
+            config,
+            force_refresh,
+            cache_loader,
+            cache_saver,
+            scanner,
+            refresh_spawner,
+        )
+    }
+
     #[test]
     fn should_scan_when_cache_disabled() {
-        let config = create_test_config(false);
-        let projects = vec![PathBuf::from("/tmp/test/project1")];
-        let fingerprints = HashMap::new();
-        let expected_projects = projects.clone();
-
+        let config = make_config(false, 24);
+        let expected = vec![PathBuf::from("/p1")];
         let scanner_called = RefCell::new(false);
         let saver_called = RefCell::new(false);
+        let spawner_called = RefCell::new(false);
 
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             false,
-            &|| panic!("should not load cache when disabled"),
+            &|| panic!("loader must not be called when cache disabled"),
             &|_| {
                 *saver_called.borrow_mut() = true;
                 Ok(())
             },
             &|_| {
                 *scanner_called.borrow_mut() = true;
-                Ok((expected_projects.clone(), fingerprints.clone()))
+                Ok((expected.clone(), HashMap::new()))
             },
+            &|| *spawner_called.borrow_mut() = true,
         );
 
         assert!(result.is_ok());
         assert!(scanner_called.into_inner());
         assert!(saver_called.into_inner());
-        assert_eq!(result.unwrap(), projects);
+        assert!(!spawner_called.into_inner());
+        assert_eq!(result.unwrap(), expected);
     }
 
     #[test]
     fn should_scan_when_force_refresh() {
-        let config = create_test_config(true);
-        let projects = vec![PathBuf::from("/tmp/test/project1")];
-        let fingerprints = HashMap::new();
-        let expected_projects = projects.clone();
-
+        let config = make_config(true, 24);
+        let expected = vec![PathBuf::from("/p1")];
         let scanner_called = RefCell::new(false);
         let saver_called = RefCell::new(false);
+        let spawner_called = RefCell::new(false);
 
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             true,
-            &|| panic!("should not load cache when force refresh"),
+            &|| panic!("loader must not be called on force refresh"),
             &|_| {
                 *saver_called.borrow_mut() = true;
                 Ok(())
             },
             &|_| {
                 *scanner_called.borrow_mut() = true;
-                Ok((expected_projects.clone(), fingerprints.clone()))
+                Ok((expected.clone(), HashMap::new()))
             },
+            &|| *spawner_called.borrow_mut() = true,
         );
 
         assert!(result.is_ok());
         assert!(scanner_called.into_inner());
         assert!(saver_called.into_inner());
-        assert_eq!(result.unwrap(), projects);
+        assert!(!spawner_called.into_inner());
+        assert_eq!(result.unwrap(), expected);
     }
 
     #[test]
-    fn should_do_initial_scan_when_no_cache_exists() {
-        let config = create_test_config(true);
-        let projects = vec![PathBuf::from("/tmp/test/project1")];
-        let fingerprints = HashMap::new();
-        let expected_projects = projects.clone();
-
-        let loader_called = RefCell::new(false);
+    fn should_do_blocking_scan_when_no_cache_exists() {
+        let config = make_config(true, 24);
+        let expected = vec![PathBuf::from("/p1")];
         let scanner_called = RefCell::new(false);
         let saver_called = RefCell::new(false);
+        let spawner_called = RefCell::new(false);
 
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             false,
-            &|| {
-                *loader_called.borrow_mut() = true;
-                Ok(None)
-            },
+            &|| Ok(None),
             &|_| {
                 *saver_called.borrow_mut() = true;
                 Ok(())
             },
             &|_| {
                 *scanner_called.borrow_mut() = true;
-                Ok((expected_projects.clone(), fingerprints.clone()))
+                Ok((expected.clone(), HashMap::new()))
             },
+            &|| *spawner_called.borrow_mut() = true,
         );
 
         assert!(result.is_ok());
-        assert!(loader_called.into_inner());
         assert!(scanner_called.into_inner());
         assert!(saver_called.into_inner());
-        assert_eq!(result.unwrap(), projects);
+        assert!(!spawner_called.into_inner());
+        assert_eq!(result.unwrap(), expected);
     }
 
     #[test]
-    fn should_upgrade_old_cache_format() {
-        let config = create_test_config(true);
-        let old_projects = vec![PathBuf::from("/old/project")];
-        let new_projects = vec![
-            PathBuf::from("/new/project1"),
-            PathBuf::from("/new/project2"),
-        ];
-        let new_fingerprints = HashMap::from([(PathBuf::from("/new"), 12345u64)]);
+    fn should_return_cached_projects_immediately_when_cache_is_fresh() {
+        let config = make_config(true, 24);
+        let cached = vec![PathBuf::from("/cached/project")];
+        let cache = RefCell::new(Some(fresh_cache(cached.clone())));
+        let spawner_called = RefCell::new(false);
 
-        // Use RefCell<Option<>> to allow moving into closure multiple times
-        let old_cache = RefCell::new(Some(ProjectCache::new(old_projects, HashMap::new())));
-
-        let loader_called = RefCell::new(false);
-        let scanner_called = RefCell::new(false);
-        let saver_count = RefCell::new(0);
-
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             false,
-            &|| {
-                *loader_called.borrow_mut() = true;
-                // Take the cache out of the RefCell
-                Ok(old_cache.borrow_mut().take())
-            },
-            &|_| {
-                *saver_count.borrow_mut() += 1;
-                Ok(())
-            },
-            &|_| {
-                *scanner_called.borrow_mut() = true;
-                Ok((new_projects.clone(), new_fingerprints.clone()))
-            },
+            &|| Ok(cache.borrow_mut().take()),
+            &|_| panic!("saver must not be called in foreground"),
+            &|_| panic!("scanner must not be called when cache is fresh"),
+            &|| *spawner_called.borrow_mut() = true,
         );
 
         assert!(result.is_ok());
-        assert!(loader_called.into_inner());
-        assert!(scanner_called.into_inner());
-        assert_eq!(*saver_count.borrow(), 1);
-        assert_eq!(result.unwrap(), new_projects);
+        assert_eq!(result.unwrap(), cached);
+        assert!(
+            !spawner_called.into_inner(),
+            "fresh cache should not trigger background refresh"
+        );
     }
 
     #[test]
-    fn should_use_cached_projects_when_nothing_changed() {
-        let config = create_test_config(true);
-        let cached_projects = vec![
-            PathBuf::from("/nonexistent/project1"),
-            PathBuf::from("/nonexistent/project2"),
-        ];
-        // Use a path that doesn't exist - validate_and_update will skip rescan
-        // because it can't check mtime of non-existent directory
-        let cached_fingerprints =
-            HashMap::from([(PathBuf::from("/definitely_nonexistent_path_xyz"), 12345u64)]);
+    fn should_return_stale_cache_immediately_and_spawn_background_refresh() {
+        let config = make_config(true, 24);
+        let cached = vec![PathBuf::from("/cached/project")];
+        let cache = RefCell::new(Some(stale_cache(cached.clone())));
+        let spawner_called = RefCell::new(false);
 
-        // Use RefCell<Option<>> to allow moving into closure multiple times
-        let cache = RefCell::new(Some(ProjectCache::new(
-            cached_projects.clone(),
-            cached_fingerprints,
-        )));
-
-        let loader_called = RefCell::new(false);
-        let scanner_called = RefCell::new(false);
-        let saver_count = RefCell::new(0);
-
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             false,
-            &|| {
-                *loader_called.borrow_mut() = true;
-                // Take the cache out of the RefCell
-                Ok(cache.borrow_mut().take())
-            },
-            &|_| {
-                *saver_count.borrow_mut() += 1;
-                Ok(())
-            },
-            &|_| {
-                *scanner_called.borrow_mut() = true;
-                panic!("should not do full scan when cache is valid")
-            },
+            &|| Ok(cache.borrow_mut().take()),
+            &|_| panic!("saver must not be called in foreground"),
+            &|_| panic!("scanner must not be called in foreground"),
+            &|| *spawner_called.borrow_mut() = true,
         );
 
         assert!(result.is_ok());
-        assert!(loader_called.into_inner());
-        // Note: When the directory in dir_mtimes doesn't exist, validate_and_update
-        // treats it as "changed" and removes projects under that path.
-        // This test verifies the flow completes - the specific behavior of
-        // validate_and_update is tested separately in cache.rs
-        let result_projects = result.unwrap();
-        // Projects were removed because the tracked directory doesn't exist
-        assert!(result_projects.is_empty());
+        assert_eq!(result.unwrap(), cached);
+        assert!(
+            spawner_called.into_inner(),
+            "stale cache must trigger background refresh"
+        );
     }
 
     #[test]
-    fn should_update_incrementally_when_cache_changed() {
-        let config = create_test_config(true);
-        let initial_projects = vec![PathBuf::from("/nonexistent/project1")];
-        // Use a path that doesn't exist - validate_and_update will treat missing
-        // directory as a change (unwrap_or(true) in the mtime check)
-        let mut dir_mtimes = HashMap::new();
-        dir_mtimes.insert(PathBuf::from("/definitely_nonexistent_path_abc"), 0u64);
+    fn should_spawn_background_refresh_when_cache_has_no_fingerprints() {
+        let config = make_config(true, 24);
+        let cached = vec![PathBuf::from("/old/project")];
+        // Old cache format: no dir_mtimes
+        let old_cache = RefCell::new(Some(ProjectCache::new(cached.clone(), HashMap::new())));
+        let spawner_called = RefCell::new(false);
 
-        // Use RefCell<Option<>> to allow moving into closure multiple times
-        let cache = RefCell::new(Some(ProjectCache::new(initial_projects, dir_mtimes)));
-
-        let loader_called = RefCell::new(false);
-        let saver_called = RefCell::new(false);
-
-        let result = get_projects_internal(
+        let result = call_internal(
             &config,
             false,
-            &|| {
-                *loader_called.borrow_mut() = true;
-                // Take the cache out of the RefCell
-                Ok(cache.borrow_mut().take())
-            },
-            &|_| {
-                *saver_called.borrow_mut() = true;
-                Ok(())
-            },
-            &|_| panic!("full scan should not happen with incremental update"),
+            &|| Ok(old_cache.borrow_mut().take()),
+            &|_| panic!("saver must not be called in foreground"),
+            &|_| panic!("scanner must not be called in foreground"),
+            &|| *spawner_called.borrow_mut() = true,
         );
 
-        // validate_and_update is called internally. Since the directory doesn't exist,
-        // it treats it as "changed" and will try to rescan using scan_from_root.
-        // We verify the flow completes without panicking.
-
         assert!(result.is_ok());
-        assert!(loader_called.into_inner());
-        // Note: The saver may or may not be called depending on whether
-        // validate_and_update detects changes (missing dir = change)
+        assert_eq!(result.unwrap(), cached);
+        assert!(
+            spawner_called.into_inner(),
+            "old cache format must trigger background refresh"
+        );
     }
 }

src/main.rs

@@ -8,8 +8,8 @@ use tmuxido::deps::ensure_dependencies;
 use tmuxido::self_update;
 use tmuxido::update_check;
 use tmuxido::{
-    get_projects, launch_tmux_session, setup_desktop_integration_wizard, setup_shortcut_wizard,
-    show_cache_status,
+    get_projects, launch_tmux_session, refresh_cache, setup_desktop_integration_wizard,
+    setup_shortcut_wizard, show_cache_status,
 };
 
 #[derive(Parser, Debug)]
@@ -41,6 +41,10 @@ struct Args {
     /// Install the .desktop entry and icon for app launcher integration
     #[arg(long)]
     setup_desktop_shortcut: bool,
+
+    /// Internal: rebuild cache in background (used by stale-while-revalidate)
+    #[arg(long, hide = true)]
+    background_refresh: bool,
 }
 
 fn main() -> Result<()> {
@@ -51,6 +55,13 @@ fn main() -> Result<()> {
         return self_update::self_update();
     }
 
+    // Handle background cache refresh (spawned internally by stale-while-revalidate).
+    // Runs early to avoid unnecessary dependency checks and config prompts.
+    if args.background_refresh {
+        let config = Config::load()?;
+        return refresh_cache(&config);
+    }
+
     // Handle standalone shortcut setup
     if args.setup_shortcut {
         return setup_shortcut_wizard();

src/ui.rs

@@ -613,6 +613,91 @@ pub fn render_desktop_integration_success(result: &crate::shortcut::DesktopInsta
 
 // ============================================================================
 
+/// Choices offered when no configuration file is found on first run
+#[derive(Debug, PartialEq)]
+pub enum SetupChoice {
+    Wizard,
+    Default,
+}
+
+/// Parse the first-run setup choice input.
+///
+/// Accepts:
+/// - `""`, `" "`, `"1"`, `"w"`, `"wizard"` → `Wizard` (default)
+/// - `"2"`, `"d"`, `"default"` → `Default`
+/// - anything else falls back to `Wizard`
+pub fn parse_setup_choice_input(input: &str) -> SetupChoice {
+    match input.trim().to_lowercase().as_str() {
+        "2" | "d" | "default" => SetupChoice::Default,
+        _ => SetupChoice::Wizard,
+    }
+}
+
+/// Renders the first-run prompt asking whether to run the wizard or use defaults.
+/// Returns the raw user input.
+pub fn render_setup_choice_prompt() -> Result<String> {
+    let prompt_style = Style::new().bold(true).foreground(color_green());
+    let hint_style = Style::new().italic(true).foreground(color_dark_gray());
+    let title_style = Style::new().bold(true).foreground(color_blue());
+    let option_style = Style::new().foreground(color_purple());
+
+    println!();
+    println!("{}", title_style.render("  🚀 Welcome to tmuxido!"));
+    println!();
+    println!(
+        "{}",
+        hint_style.render("  No configuration found. How would you like to get started?")
+    );
+    println!();
+    println!(
+        "  {}",
+        option_style
+            .render("1. Run setup wizard   — configure paths, cache, and windows interactively")
+    );
+    println!(
+        "  {}",
+        option_style.render("2. Use default config — start immediately with sensible defaults")
+    );
+    println!();
+    print!("  {} ", prompt_style.render("❯ Choose (1/2):"));
+    io::stdout().flush().context("Failed to flush stdout")?;
+
+    let mut input = String::new();
+    io::stdin()
+        .read_line(&mut input)
+        .context("Failed to read input")?;
+
+    Ok(input.trim().to_string())
+}
+
+/// Renders a confirmation message after the default config is written.
+pub fn render_default_config_saved(config_path: &str) {
+    let success_style = Style::new().bold(true).foreground(color_green());
+    let info_style = Style::new().foreground(color_dark_gray());
+    let path_style = Style::new().bold(true).foreground(color_blue());
+
+    println!();
+    println!(
+        "{}",
+        success_style.render("  ✅ Default configuration saved!")
+    );
+    println!(
+        "    {} {}",
+        info_style.render("Config:"),
+        path_style.render(config_path)
+    );
+    println!();
+    println!(
+        "{}",
+        info_style.render(
+            "  ⚙️  Edit it anytime to customise your setup, or run 'tmuxido --setup-shortcut'."
+        )
+    );
+    println!();
+}
+
+// ============================================================================
+
 /// Parse comma-separated list into Vec<String>, filtering empty items
 pub fn parse_comma_separated_list(input: &str) -> Vec<String> {
     input
@@ -882,4 +967,50 @@ mod tests {
         };
         render_desktop_integration_success(&result);
     }
+
+    // ---- SetupChoice / parse_setup_choice_input ----
+
+    #[test]
+    fn should_return_wizard_for_empty_input() {
+        assert_eq!(parse_setup_choice_input(""), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("   "), SetupChoice::Wizard);
+    }
+
+    #[test]
+    fn should_return_wizard_for_option_1() {
+        assert_eq!(parse_setup_choice_input("1"), SetupChoice::Wizard);
+    }
+
+    #[test]
+    fn should_return_wizard_for_w_aliases() {
+        assert_eq!(parse_setup_choice_input("w"), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("wizard"), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("W"), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("WIZARD"), SetupChoice::Wizard);
+    }
+
+    #[test]
+    fn should_return_default_for_option_2() {
+        assert_eq!(parse_setup_choice_input("2"), SetupChoice::Default);
+    }
+
+    #[test]
+    fn should_return_default_for_d_aliases() {
+        assert_eq!(parse_setup_choice_input("d"), SetupChoice::Default);
+        assert_eq!(parse_setup_choice_input("default"), SetupChoice::Default);
+        assert_eq!(parse_setup_choice_input("D"), SetupChoice::Default);
+        assert_eq!(parse_setup_choice_input("DEFAULT"), SetupChoice::Default);
+    }
+
+    #[test]
+    fn should_return_wizard_for_unknown_input() {
+        assert_eq!(parse_setup_choice_input("banana"), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("3"), SetupChoice::Wizard);
+        assert_eq!(parse_setup_choice_input("yes"), SetupChoice::Wizard);
+    }
+
+    #[test]
+    fn render_default_config_saved_should_not_panic() {
+        render_default_config_saved("/home/user/.config/tmuxido/tmuxido.toml");
+    }
 }