Network: Lazy-start mDNS, add networking toggle

- Add `network.enabled` setting (top of `Settings > Network > SMB/Network shares`, default on). When off, the picker shows "Network (disabled)" and clicking it deep-links to the Settings section instead of navigating
- Defer mDNS browse and direct-smb2 mount upgrade until first user network action — fresh installs no longer trigger macOS's "Cmdr wants to find devices on local networks" prompt at app launch
- Hidden internal `network.firstTriggerDone` flag persists once we've fired the prompt, so returning users still get eager startup (no re-prompt regression)
- Lazy trigger fires from `NetworkBrowser` mount, `ConnectToServerDialog` open, and the picker's OS-mount → direct-SMB upgrade click. Single chokepoint in `lazy-trigger.ts`
- Add `NSLocalNetworkUsageDescription` to `Info.plist` so the system prompt has user-friendly copy
- Settings panel surfaces a "Local Network access" info card with a deep link to System Settings > Privacy & Security > Local Network
- Settings window gains an optional `section` deep-link (JSON-encoded URL param + cross-window event)
- Hidden settings flag (`hidden: true`) for internal-only state that needs the same persistence as user settings without showing in the UI
- Backend: new `ensure_network_discovery_started` and `set_network_enabled` Tauri commands. mDNS startup gate consolidated into a single `should_start_network_at_launch` boolean covering both daemon start and existing-mount upgrade
- E2E: new `network-toggle.spec.ts` covers the four toggle UX states end-to-end
- Project rule: don't bump `file-length-allowlist.json` as a side effect of unrelated changes

Author: vdavid

.claude/rules/file-length-allowlist.md

@@ -0,0 +1,5 @@
+❌ NEVER modify `scripts/check/checks/file-length-allowlist.json` unless the user explicitly asks for it. The
+file-length check is warn-only — it doesn't fail the suite. The allowlist exists to track current file sizes; bumping it
+as a side effect of a feature change hides growth that should be addressed by trimming the file or splitting it. If a
+file you're touching exceeds its allowlisted count and the warning is annoying, leave it as a warning and surface it to
+the user, don't silently raise the limit.

apps/desktop/knip.json

@@ -1,14 +1,13 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "ignoreBinaries": ["only-allow", "rustc"],
-  "ignore": ["src/lib/tauri-commands/**"],
+  "ignore": ["src/lib/tauri-commands/**", "src/unplugin-icons.d.ts"],
   "ignoreUnresolved": ["~icons/.+"],
   "ignoreDependencies": [
     "oxlint",
     "@tauri-apps/cli",
     "@testing-library/svelte",
     "prettier-plugin-svelte",
-    "axe-core",
     "@iconify-json/lucide"
   ],
   "ignoreExportsUsedInFile": true,

apps/desktop/src-tauri/Info.plist

@@ -20,5 +20,7 @@
     <string>Cmdr needs access to your Documents folder to browse and manage files there.</string>
     <key>NSDownloadsFolderUsageDescription</key>
     <string>Cmdr needs access to your Downloads folder to browse and manage files there.</string>
+    <key>NSLocalNetworkUsageDescription</key>
+    <string>Cmdr uses your local network to discover SMB file servers like NAS devices and connect to them for browsing and transferring files.</string>
 </dict>
 </plist>

apps/desktop/src-tauri/src/commands/CLAUDE.md

@@ -13,7 +13,7 @@ immediately to business-logic modules. No significant logic lives here.
 | `volumes.rs` | Volume management (macOS) | `list_volumes`, `get_default_volume_id`, `get_volume_space`, `resolve_path_volume` (statfs-based, no volume enumeration) |
 | `volumes_linux.rs` | Volume management (Linux) | Same interface as `volumes.rs`, delegates to `volumes_linux` module |
 | `mtp.rs` | MTP devices | Full MTP command surface (connect, disconnect, list, download, upload, delete, rename, move, scan) |
-| `network.rs` | SMB/network shares | Discovery, share listing, keychain, mounting, direct-connection upgrade, in-place reconnect (`reconnect_smb_volume` — backend single-flighted via `Volume::attempt_reconnect`), per-volume disconnect (`disconnect_smb_volume` — macOS shells out to `diskutil unmount`, Linux drops the smb2 session). Upgrade business logic (address resolution, credential lookup, smb2 connection) lives in `network::smb_upgrade`; commands here are thin wrappers. |
+| `network.rs` | SMB/network shares | Discovery, share listing, keychain, mounting, direct-connection upgrade, in-place reconnect (`reconnect_smb_volume` — backend single-flighted via `Volume::attempt_reconnect`), per-volume disconnect (`disconnect_smb_volume` — macOS shells out to `diskutil unmount`, Linux drops the smb2 session). Lazy-startup hooks: `ensure_network_discovery_started` (idempotent — kicks off mDNS + manual-server load + smb-mount upgrade on first user network action) and `set_network_enabled` (live-applies the `network.enabled` toggle: stops mDNS and clears discovered hosts when off). Upgrade business logic (address resolution, credential lookup, smb2 connection) lives in `network::smb_upgrade`; commands here are thin wrappers. |
 | `font_metrics.rs` | Font metrics cache | `store_font_metrics`, `has_font_metrics` |
 | `icons.rs` | File icons | `get_icons`, `refresh_directory_icons`, cache clear |
 | `rename.rs` | Rename / trash | `move_to_trash` (delegates to `write_operations::trash::move_to_trash_sync`), `check_rename_permission`, `check_rename_validity`, `rename_file`. `rename_file` calls `notify_mutation` after success to update the listing cache (both local and volume-aware paths). |

apps/desktop/src-tauri/src/commands/network.rs

@@ -639,3 +639,37 @@ pub async fn connect_to_server(address: String, app_handle: tauri::AppHandle) ->
 pub fn remove_manual_server(server_id: String, app_handle: tauri::AppHandle) -> Result<(), String> {
     manual_servers::remove_manual_server(&server_id, &app_handle)
 }
+
+/// Idempotently starts mDNS discovery if it isn't running. Triggered by the frontend the first
+/// time the user takes a network action (clicks "Network", opens "Connect to server…", or
+/// upgrades a mounted share to direct smb2). The first call here is what triggers macOS's
+/// "Cmdr wants to find devices on local networks" prompt — we defer to the latest reasonable
+/// moment so fresh installs don't see the prompt at launch.
+///
+/// Also kicks off the existing-SMB-mount upgrade pass: if macOS auto-remounted SMB shares
+/// at login, this is the first moment we can open direct smb2 connections to them (TCP to a
+/// private IP also gates on the Local Network permission).
+///
+/// Reloads manually-added servers in case discovery was previously stopped (toggle-off path)
+/// and `DISCOVERY_STATE` got cleared.
+#[tauri::command]
+pub fn ensure_network_discovery_started(app_handle: tauri::AppHandle) {
+    crate::network::start_discovery(app_handle.clone());
+    manual_servers::load_manual_servers(&app_handle);
+    crate::file_system::upgrade_existing_smb_mounts();
+
+    #[cfg(feature = "smb-e2e")]
+    crate::network::virtual_smb_hosts::setup_virtual_smb_hosts(&app_handle);
+}
+
+/// Live-apply the `network.enabled` toggle. When `false`, stops mDNS and clears the discovered
+/// host list (frontend store empties via emitted `network-host-lost` events). When `true`, this
+/// is a no-op — the frontend triggers `ensure_network_discovery_started` separately when the
+/// user takes a network action.
+#[tauri::command]
+pub fn set_network_enabled(enabled: bool, app_handle: tauri::AppHandle) {
+    if !enabled {
+        crate::network::mdns_discovery::stop_discovery();
+        crate::network::clear_discovered_hosts(&app_handle);
+    }
+}

apps/desktop/src-tauri/src/lib.rs

@@ -322,13 +322,14 @@ pub fn run() {
             #[cfg(any(target_os = "macos", target_os = "linux"))]
             file_system::volume::smb::set_app_handle(app.handle().clone());
 
-            // Start network host discovery (mDNS)
-            #[cfg(any(target_os = "macos", target_os = "linux"))]
-            network::start_discovery(app.handle().clone());
-
-            // Register virtual SMB hosts for E2E testing (after discovery start so they appear alongside real hosts)
-            #[cfg(feature = "smb-e2e")]
-            network::virtual_smb_hosts::setup_virtual_smb_hosts(app.handle());
+            // Network discovery (mDNS) startup is deferred — see the post-`load_settings`
+            // block below. Starting mDNS here would trigger macOS's "Cmdr wants to find devices
+            // on local networks" prompt at app launch even on first install before the user has
+            // shown any interest in networking. We only start at launch for returning users (who
+            // already answered the OS prompt at least once, tracked via `network.firstTriggerDone`).
+            //
+            // For E2E builds, virtual SMB hosts also live alongside discovery — they're only
+            // injected once discovery is up.
 
             // Initialize volume broadcast (must be before watchers so they can emit)
             volume_broadcast::init(app.handle());
@@ -390,6 +391,23 @@ pub fn run() {
             // Initialize font metrics for default font (system font at 12px)
             font_metrics::init_font_metrics(app.handle(), "system-400-12");
 
+            // Start mDNS network discovery only for returning users who've already answered the
+            // OS Local Network prompt at least once. Fresh installs stay quiet at launch — the
+            // frontend calls `ensure_network_discovery_started` lazily on first user network
+            // action (clicks "Network", opens "Connect to server…", upgrades a mounted share).
+            // E2E builds always start so virtual hosts are populated before tests run.
+            #[cfg(any(target_os = "macos", target_os = "linux"))]
+            let should_start_network_at_launch = saved_settings.network_enabled.unwrap_or(true)
+                && (saved_settings.network_first_trigger_done.unwrap_or(false) || cfg!(feature = "smb-e2e"));
+
+            #[cfg(any(target_os = "macos", target_os = "linux"))]
+            if should_start_network_at_launch {
+                network::start_discovery(app.handle().clone());
+
+                #[cfg(feature = "smb-e2e")]
+                network::virtual_smb_hosts::setup_virtual_smb_hosts(app.handle());
+            }
+
             // Apply direct SMB connection setting (default: true)
             file_system::set_direct_smb_enabled(saved_settings.direct_smb_connection.unwrap_or(true));
             file_system::git::set_virtual_portal_enabled(saved_settings.show_virtual_git_portal.unwrap_or(true));
@@ -401,9 +419,16 @@ pub fn run() {
             space_poller::set_threshold_mb(saved_settings.disk_space_change_threshold_mb.unwrap_or(1));
             space_poller::start();
 
-            // Upgrade existing SMB mounts to direct smb2 connections (background, non-blocking)
+            // Upgrade existing SMB mounts to direct smb2 connections (background, non-blocking).
+            // Gated on the same lazy-startup conditions as mDNS above — opening a TCP socket to
+            // a private-IP SMB server triggers macOS's Local Network prompt independently, so
+            // we must not run this on fresh installs either. Returning users already answered
+            // the prompt; lazy users wait until they click Network or use the picker's "Connect
+            // directly" indicator.
             #[cfg(any(target_os = "macos", target_os = "linux"))]
-            file_system::upgrade_existing_smb_mounts();
+            if should_start_network_at_launch {
+                file_system::upgrade_existing_smb_mounts();
+            }
 
             // Check if there's an existing license (for menu text)
             let has_existing_license = licensing::get_license_info(app.handle()).is_some();
@@ -994,6 +1019,14 @@ pub fn run() {
             commands::network::remove_manual_server,
             #[cfg(any(target_os = "macos", target_os = "linux"))]
             commands::network::disconnect_network_host,
+            #[cfg(any(target_os = "macos", target_os = "linux"))]
+            commands::network::ensure_network_discovery_started,
+            #[cfg(any(target_os = "macos", target_os = "linux"))]
+            commands::network::set_network_enabled,
+            #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+            stubs::network::ensure_network_discovery_started,
+            #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+            stubs::network::set_network_enabled,
             #[cfg(not(any(target_os = "macos", target_os = "linux")))]
             stubs::network::list_network_hosts,
             #[cfg(not(any(target_os = "macos", target_os = "linux")))]

apps/desktop/src-tauri/src/network/CLAUDE.md

@@ -36,6 +36,31 @@ Discover, browse, and mount SMB network shares. Works on macOS and Linux.
 
 ## Key decisions
 
+### Lazy mDNS startup gated on user toggle and first-trigger flag
+
+`network::start_discovery()` no longer fires unconditionally in `lib.rs::setup`. Instead, two settings drive the
+lifecycle:
+
+- **`network.enabled`** (boolean, default `true`) — top-level user toggle in `Settings > Network > SMB/Network shares`.
+  When `false`, the picker shows "Network (disabled)", no mDNS daemon runs, and no proactive smb2 upgrades happen.
+- **`network.firstTriggerDone`** (boolean, default `false`, hidden) — tracks whether we've already performed a gated
+  network action. Persisted across launches.
+
+At startup, mDNS starts only if `network.enabled && (firstTriggerDone || smb-e2e feature)`. On a fresh install,
+`firstTriggerDone == false` so we stay quiet and the macOS "Cmdr wants to find devices on local networks" prompt
+doesn't fire at app launch.
+
+The frontend calls `ensure_network_discovery_started` (idempotent) when the user takes a network action — clicking
+"Network" in the picker, opening "Connect to server…", or hitting the OS-mount → direct-smb2 upgrade indicator. That
+first call is what triggers the OS prompt. We also flip `firstTriggerDone = true` so subsequent launches start mDNS
+eagerly without surprising the user.
+
+`set_network_enabled(false)` stops the daemon and clears `DISCOVERY_STATE.hosts`, emitting `network-host-lost` events
+so the frontend store empties. `set_network_enabled(true)` is a no-op — the user must take a network action to
+re-trigger discovery.
+
+The E2E build feature (`smb-e2e`) bypasses both gates so virtual SMB hosts are populated before tests run.
+
 ### `NetFSMountURLAsync` for SMB mounting (not `mount_smbfs` CLI)
 
 Non-blocking (UI stays responsive), credentials passed via secure API (not exposed in process list), native Keychain

apps/desktop/src-tauri/src/network/mod.rs

@@ -123,6 +123,26 @@ pub fn get_discovery_state_value() -> DiscoveryState {
     state.state
 }
 
+/// Clears all discovered hosts and resets discovery state to `Idle`.
+/// Called when networking is disabled via the user toggle so the frontend store empties
+/// without waiting for `network-host-lost` events from a stopped daemon.
+pub fn clear_discovered_hosts<R: tauri::Runtime>(app_handle: &impl Emitter<R>) {
+    let removed_ids: Vec<String> = {
+        let mut state = get_discovery_state().lock_ignore_poison();
+        let ids: Vec<String> = state.hosts.keys().cloned().collect();
+        state.hosts.clear();
+        state.state = DiscoveryState::Idle;
+        ids
+    };
+    for id in removed_ids {
+        let _ = app_handle.emit("network-host-lost", serde_json::json!({ "id": id }));
+    }
+    let _ = app_handle.emit(
+        "network-discovery-state-changed",
+        serde_json::json!({ "state": DiscoveryState::Idle }),
+    );
+}
+
 /// Called by the mDNS discovery module when a host is discovered.
 pub(crate) fn on_host_found<R: tauri::Runtime>(host: NetworkHost, app_handle: &impl Emitter<R>) {
     let mut state = get_discovery_state().lock_ignore_poison();

apps/desktop/src-tauri/src/settings/CLAUDE.md

@@ -30,6 +30,8 @@ Settings {
     disk_space_change_threshold_mb: Option<u64>, // from "advanced.diskSpaceChangeThreshold"
     max_log_storage_mb: Option<u64>,               // from "advanced.maxLogStorageMb"
     error_reports_enabled: Option<bool>,           // from "updates.errorReports" (Flow B opt-in, default off)
+    network_enabled: Option<bool>,                 // from "network.enabled" (default on; off renders picker as "Network (disabled)")
+    network_first_trigger_done: Option<bool>,      // from "network.firstTriggerDone" (hidden internal flag — true if we've ever triggered the macOS Local Network prompt)
 }
 ```
 

apps/desktop/src-tauri/src/settings/loader.rs

@@ -68,6 +68,10 @@ pub struct Settings {
     pub error_reports_enabled: Option<bool>,
     #[serde(alias = "fileExplorer.git.showVirtualGitPortal", default)]
     pub show_virtual_git_portal: Option<bool>,
+    #[serde(alias = "network.enabled", default)]
+    pub network_enabled: Option<bool>,
+    #[serde(alias = "network.firstTriggerDone", default)]
+    pub network_first_trigger_done: Option<bool>,
 }
 
 fn default_show_hidden() -> bool {
@@ -93,6 +97,8 @@ impl Default for Settings {
             max_log_storage_mb: None,
             error_reports_enabled: None,
             show_virtual_git_portal: None,
+            network_enabled: None,
+            network_first_trigger_done: None,
         }
     }
 }
@@ -152,6 +158,8 @@ fn parse_settings(contents: &str) -> Result<Settings, serde_json::Error> {
     let show_virtual_git_portal = json
         .get("fileExplorer.git.showVirtualGitPortal")
         .and_then(|v| v.as_bool());
+    let network_enabled = json.get("network.enabled").and_then(|v| v.as_bool());
+    let network_first_trigger_done = json.get("network.firstTriggerDone").and_then(|v| v.as_bool());
 
     Ok(Settings {
         show_hidden_files,
@@ -170,6 +178,8 @@ fn parse_settings(contents: &str) -> Result<Settings, serde_json::Error> {
         max_log_storage_mb,
         error_reports_enabled,
         show_virtual_git_portal,
+        network_enabled,
+        network_first_trigger_done,
     })
 }