version bump for sdk

version bump to 0.2.2
added settings + non blocking ui actions
2026-11-03 16:41:26 +01:00 · 2026-06-30 21:11:21 +02:00 · 2026-06-30 18:39:11 +02:00 · 2026-06-30 18:38:38 +02:00 · 2026-06-30 17:42:38 +02:00 · 2026-06-30 17:41:52 +02:00
25 changed files with 5504 additions and 677 deletions
@@ -107,71 +107,12 @@ jobs:
          # Build Debian package
          dpkg-deb --build deb proton-drive-linux_${{ env.VERSION }}_amd64.deb

-      - name: Package AppImage (.AppImage)
-        run: |
-          # 1. Set up AppDir structure
-          mkdir -p AppDir/usr/bin
-          mkdir -p AppDir/usr/share/applications
-          mkdir -p AppDir/usr/share/icons/hicolor/scalable/apps
-
-          # Copy binaries
-          cp target/release/pdfs AppDir/usr/bin/
-          cp target/release/pdfs-tray AppDir/usr/bin/
-          cp target/release/pdfs-app AppDir/usr/bin/
-
-          # Copy desktop integration files
-          cp packaging/io.narl.proton-drive-linux.desktop AppDir/usr/share/applications/
-          cp packaging/io.narl.proton-drive-linux.svg AppDir/usr/share/icons/hicolor/scalable/apps/
-
-          # Create required AppImage root symlinks
-          ln -s usr/share/applications/io.narl.proton-drive-linux.desktop AppDir/
-          ln -s usr/share/icons/hicolor/scalable/apps/io.narl.proton-drive-linux.svg AppDir/
-
-          # 2. Write custom AppRun to support multi-call execution
-          cat <<'EOF' > AppDir/AppRun
-          #!/bin/sh
-          HERE="$(dirname "$(readlink -f "${0}")")"
-          ARG0="$(basename "${0}")"
-          case "${ARG0}" in
-            pdfs)
-              exec "${HERE}/usr/bin/pdfs" "$@"
-              ;;
-            pdfs-tray)
-              exec "${HERE}/usr/bin/pdfs-tray" "$@"
-              ;;
-            pdfs-app)
-              exec "${HERE}/usr/bin/pdfs-app" "$@"
-              ;;
-            *)
-              # Support running a specific binary by passing its name as first arg
-              if [ "$1" = "pdfs" ] || [ "$1" = "pdfs-tray" ] || [ "$1" = "pdfs-app" ]; then
-                CMD="$1"
-                shift
-                exec "${HERE}/usr/bin/${CMD}" "$@"
-              else
-                # Default behavior: run GUI app
-                exec "${HERE}/usr/bin/pdfs-app" "$@"
-              fi
-              ;;
-          esac
-          EOF
-          chmod +x AppDir/AppRun
-
-          # 3. Download and extract appimagetool (avoids FUSE mount failures in CI)
-          curl -Lo appimagetool https://github.com/AppImage/AppImageKit/releases/download/13/appimagetool-x86_64.AppImage
-          chmod +x appimagetool
-          ./appimagetool --appimage-extract
-
-          # 4. Generate AppImage
-          ARCH=x86_64 ./squashfs-root/AppRun AppDir proton-drive-linux-${{ env.VERSION }}-x86_64.AppImage
-
      - name: Upload Workflow Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: proton-drive-linux-builds
          path: |
            *.deb
-            *.AppImage
            *.tar.gz
          if-no-files-found: error

@@ -181,7 +122,6 @@ jobs:
        with:
          files: |
            *.deb
-            *.AppImage
            *.tar.gz
          draft: false
          prerelease: false
@@ -53,6 +53,18 @@ dependencies = [
 "aes",
 ]

+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -1278,6 +1290,18 @@ dependencies = [
 "pin-project-lite",
 ]

+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
 [[package]]
 name = "fastrand"
 version = "2.4.1"
@@ -1793,12 +1817,30 @@ dependencies = [
 "system-deps",
 ]

+[[package]]
+name = "hashbrown"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+dependencies = [
+ "ahash",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"

+[[package]]
+name = "hashlink"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"
+dependencies = [
+ "hashbrown 0.14.5",
+]
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -2117,7 +2159,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
 "equivalent",
- "hashbrown",
+ "hashbrown 0.17.1",
 ]

 [[package]]
@@ -2345,6 +2387,17 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "libsqlite3-sys"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -2772,7 +2825,7 @@ dependencies = [

 [[package]]
 name = "pdfs-cli"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
 "anyhow",
 "clap 4.6.1",
@@ -2787,12 +2840,13 @@ dependencies = [

 [[package]]
 name = "pdfs-core"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
 "directories",
 "keyring",
 "proton-drive-rs",
 "proton-sdk",
+ "rusqlite",
 "serde",
 "serde_json",
 "sha2 0.10.9",
@@ -2803,7 +2857,7 @@ dependencies = [

 [[package]]
 name = "pdfs-fuse"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
 "fuser",
 "libc",
@@ -2816,7 +2870,7 @@ dependencies = [

 [[package]]
 name = "pdfs-gui"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -3406,6 +3460,20 @@ dependencies = [
 "windows-sys 0.59.0",
 ]

+[[package]]
+name = "rusqlite"
+version = "0.32.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"
+dependencies = [
+ "bitflags 2.13.0",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -4347,6 +4415,12 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"

+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
 [[package]]
 name = "vec_map"
 version = "0.8.2"
@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/pdfs-core", "crates/pdfs-fuse", "crates/pdfs-cli", "crates/pdfs-gui"]

 [workspace.package]
-version = "0.1.0"
+version = "0.2.2"
 edition = "2024"
 license = "MIT"
 authors = ["Nils Pukropp <contact@narl.io>"]
@@ -11,8 +11,8 @@ rust-version = "1.96"

 [workspace.dependencies]
 # Local Proton SDK crates (path deps until published; switch to versioned later).
-proton-sdk = "0.1"
-proton-drive-rs = "0.1"
+proton-sdk = "0.1.2"
+proton-drive-rs = "0.1.2"

 # Internal crates.
 pdfs-core = { path = "crates/pdfs-core" }
@@ -27,6 +27,7 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 directories = "5"
 sha2 = "0.10"
+rusqlite = { version = "0.32", features = ["bundled"] }
 keyring = { version = "3", features = ["sync-secret-service", "crypto-rust"] }
 clap = { version = "4", features = ["derive"] }
 rpassword = "7"
@@ -1,14 +1,37 @@
 # Proton Drive client for Linux (unofficial)

-A fast, unofficial Proton Drive client for Linux. This client provides a FUSE files-on-demand virtual mount, a command-line interface (CLI), and a GTK4 desktop application with system tray integration.
+A fast, unofficial Proton Drive client for Linux. This client features an advanced files-on-demand FUSE virtual mount with block-level caching, a command-line interface (CLI), and a fully non-blocking GTK4 desktop application with system tray integration.

 ## Features

- **Files-on-demand (FUSE)**: Mount your Proton Drive as a virtual filesystem where files are downloaded only when opened.
+- **Files-on-Demand (FUSE)**: Mount your Proton Drive as a virtual filesystem where files are downloaded only when opened, utilizing smart block-level caching and disk-backed writes.
 - **Command-Line Interface (CLI)**: Manage your drive, authenticate, and monitor sync status directly from the terminal.
- **GTK4 Desktop App**: Log in, browse files, and configure sync options through a modern, native Linux GUI.
+- **Non-Blocking GTK4 Desktop App**: Browse files, manage pins, and configure options through a modern, native GUI with a fully non-blocking asynchronous main loop.
 - **System Tray Integration**: Background indicator for status monitoring, quick actions, and fast sync controls.
- **Secure Credential Storage**: Integrates with the system Secret Service (GNOME Keyring, KWallet, etc.) for safe token storage.
+- **Secure Credential Storage**: Integrates with the system Secret Service (GNOME Keyring, KWallet, etc.) with smart in-memory credential caching to avoid UI thread blockages.
+- **Proton Photos Support**: Access your Proton Photos timeline, view thumbnails, and download backed-up media natively (available in the GUI as a navigation tab and via the CLI).
+
+## Performance & Caching
+
+The client includes several optimizations designed for high efficiency, a low memory footprint, and a responsive user experience:
+
+- **On-Demand Block Cache**: Files are read in fixed 4 MiB blocks. For unpinned files, the client fetches and caches only the blocks containing the requested byte ranges. This enables fast sequential and sparse reads (e.g. media streaming or metadata scanning) without downloading entire files.
+- **Disk-Backed Writes**: Large file writes are staged on disk in temporary scratch files (rather than fully buffered in RAM) and track modified byte intervals. Only the unedited remote segments are fetched at commit time, keeping memory usage minimal.
+- **Non-Blocking GTK4 Loop**: To prevent UI freezes, all synchronous D-Bus credential checks, control socket requests, and cache usage calculations are offloaded to background worker threads or fetched asynchronously.
+- **Flicker-Free UI Rendering**: The GTK4 application performs differential rendering of the pins list, only modifying list rows when the list content changes, preserving the user's scroll position and widget focus.
+
+
+## Screenshots
+
+### GUI Application
+
+| Login Screen | Account Overview |
+| :---: | :---: |
+| ![Login Screen](images/login.png) | ![Account Overview](images/account.png) |
+
+| Files (Grid View) | Files (List View) |
+| :---: | :---: |
+| ![Files Grid](images/files_grid.png) | ![Files List](images/files_list.png) |

 ---

@@ -64,24 +87,7 @@ Install the debian package via `dpkg` or `apt`:
 sudo apt install ./proton-drive-linux_*.deb
 ```

-### 2. AppImage (.AppImage)
-The AppImage is a portable build that packages all binaries. Make it executable and run it:
-```bash
-chmod +x proton-drive-linux-*.AppImage
-./proton-drive-linux-*.AppImage
-```
-
-> [!TIP]
-> The AppImage is a multi-call binary. By default, running it launches the GUI. You can run the CLI or the Tray app by passing their name as the first argument, or by renaming/symlinking the AppImage file:
-> ```bash
-> # Run CLI
-> ./proton-drive-linux-*.AppImage pdfs --help
-> 
-> # Run Tray
-> ./proton-drive-linux-*.AppImage pdfs-tray
-> ```
-
-### 3. Arch Linux
+### 2. Arch Linux
 A local `PKGBUILD` is available under the `packaging/` directory. You can build and install it using:
 ```bash
 cd packaging && makepkg -fi
@@ -104,9 +110,8 @@ This project has a GitHub Actions CI workflow configured under `.github/workflow
 3. **Artifact Packaging**:
   - Generates a `.tar.gz` containing the raw binaries (`pdfs`, `pdfs-app`, `pdfs-tray`).
   - Packs them into a Debian package (`.deb`).
-   - Builds a portable AppImage using `appimagetool` without requiring FUSE inside CI.
 4. **Publishing**:
-   - Creates a GitHub Release matching the pushed tag and uploads the `.deb`, `.AppImage`, and `.tar.gz` packages as release assets.
+   - Creates a GitHub Release matching the pushed tag and uploads the `.deb` and `.tar.gz` packages as release assets.
   - For manual runs, compiles and exposes the packages as workflow run artifacts for testing.

 ---
@@ -2,6 +2,7 @@

 use std::io::Write;
 use std::path::{Path, PathBuf};
+use std::sync::Arc;

 use anyhow::{Context, Result, anyhow, bail};
 use clap::{Parser, Subcommand};
@@ -9,9 +10,14 @@ use pdfs_core::auth;
 use pdfs_core::cache::ContentCache;
 use pdfs_core::config::AppDirs;
 use pdfs_core::control::{Request as CtlRequest, Response as CtlResponse};
+use pdfs_core::db::Db;

 #[derive(Parser)]
-#[command(name = "pdfs", version, about = "Proton Drive for Linux (Files On-Demand)")]
+#[command(
+    name = "pdfs",
+    version,
+    about = "Proton Drive for Linux (Files On-Demand)"
+)]
 struct Cli {
    #[command(subcommand)]
    command: Command,
@@ -34,6 +40,13 @@ enum Command {
        /// Mountpoint; defaults to ~/ProtonDrive.
        mountpoint: Option<PathBuf>,
    },
+    /// Run the auto-mount daemon: wait for login, mount, and keep it mounted
+    /// until stopped. This is what the systemd user service runs; you normally
+    /// don't invoke it by hand.
+    Daemon {
+        /// Mountpoint; defaults to ~/ProtonDrive.
+        mountpoint: Option<PathBuf>,
+    },
    /// Keep a file on this device (download + cache it). Needs a running mount.
    Pin {
        /// File path, inside the mountpoint or relative to it.
@@ -65,6 +78,47 @@ enum Command {
        /// Photo node uid in `volume~link` form (from `pdfs photos`).
        uid: String,
    },
+    /// Search file/folder names via the running daemon's local index.
+    Search {
+        /// Query string (substring match).
+        query: String,
+        /// Max hits to return.
+        #[arg(long, default_value_t = 50)]
+        limit: usize,
+    },
+    /// Rename a file or folder via the running daemon.
+    Rename {
+        /// File/folder path, inside the mountpoint or relative to it.
+        path: PathBuf,
+        /// New name (a single path component).
+        new_name: String,
+    },
+    /// Move a file or folder into another folder via the running daemon.
+    Move {
+        /// File/folder path, inside the mountpoint or relative to it.
+        path: PathBuf,
+        /// Destination folder path, inside the mountpoint or relative to it.
+        new_parent: PathBuf,
+    },
+    /// Trash a file or folder via the running daemon.
+    Rm {
+        /// File/folder path, inside the mountpoint or relative to it.
+        path: PathBuf,
+    },
+    /// Create a folder via the running daemon.
+    Mkdir {
+        /// Parent folder path, inside the mountpoint or relative to it.
+        parent: PathBuf,
+        /// New folder name (a single path component).
+        name: String,
+    },
+    /// Upload a local file into a Drive folder via the running daemon.
+    Upload {
+        /// Local file to upload.
+        file: PathBuf,
+        /// Destination folder path, inside the mountpoint or relative to it.
+        parent: PathBuf,
+    },
 }

 fn main() -> Result<()> {
@@ -84,12 +138,19 @@ fn main() -> Result<()> {
        Command::Logout => cmd_logout(),
        Command::Status => cmd_status(),
        Command::Mount { mountpoint } => cmd_mount(mountpoint),
+        Command::Daemon { mountpoint } => cmd_daemon(mountpoint),
        Command::Pin { path } => cmd_pin(path),
        Command::Unpin { path } => cmd_unpin(path),
        Command::Pins => cmd_pins(),
        Command::Ls { path } => cmd_ls(path),
        Command::Photos { limit, offset } => cmd_photos(limit, offset),
        Command::OpenPhoto { uid } => cmd_open_photo(uid),
+        Command::Search { query, limit } => cmd_search(query, limit),
+        Command::Rename { path, new_name } => cmd_rename(path, new_name),
+        Command::Move { path, new_parent } => cmd_move(path, new_parent),
+        Command::Rm { path } => cmd_rm(path),
+        Command::Mkdir { parent, name } => cmd_mkdir(parent, name),
+        Command::Upload { file, parent } => cmd_upload(file, parent),
    }
 }

@@ -111,8 +172,7 @@ fn cmd_login(username: Option<String>) -> Result<()> {

    // The 2FA prompt fires lazily — only if the account actually requires it.
    let get_totp = || -> pdfs_core::Result<String> {
-        prompt_line("2FA code")
-            .map_err(|e| pdfs_core::Error::Other(format!("read 2FA code: {e}")))
+        prompt_line("2FA code").map_err(|e| pdfs_core::Error::Other(format!("read 2FA code: {e}")))
    };

    let rt = tokio::runtime::Runtime::new()?;
@@ -143,7 +203,9 @@ fn cmd_status() -> Result<()> {
    }
    // If a mount daemon is running, report live status from its control socket.
    match control_request(CtlRequest::Status) {
-        Ok(CtlResponse::Status { mountpoint, pinned, .. }) => {
+        Ok(CtlResponse::Status {
+            mountpoint, pinned, ..
+        }) => {
            println!("Mounted at {mountpoint} ({pinned} pinned)");
        }
        Ok(other) => println!("Mount: unexpected response {other:?}"),
@@ -153,17 +215,69 @@ fn cmd_status() -> Result<()> {
 }

 fn cmd_mount(mountpoint: Option<PathBuf>) -> Result<()> {
+    mount_once(mountpoint)?;
+    Ok(())
+}
+
+/// Run the auto-mount daemon loop. Waits for a stored login, mounts, and keeps
+/// the mount alive: a clean stop (SIGTERM via `systemctl --user stop`) exits 0;
+/// an external unmount triggers a remount; errors back off and retry. This is
+/// the entry point for the systemd user service.
+fn cmd_daemon(mountpoint: Option<PathBuf>) -> Result<()> {
+    loop {
+        // Wait until a session is stored. The GUI enables this service on login,
+        // but the service may also start at boot before the user has logged in.
+        loop {
+            match auth::load() {
+                Ok(_) => break,
+                Err(pdfs_core::Error::NotLoggedIn) => {
+                    tracing::info!("not logged in; waiting…");
+                    std::thread::sleep(std::time::Duration::from_secs(3));
+                }
+                Err(e) => return Err(e.into()),
+            }
+        }
+
+        match mount_once(mountpoint.clone()) {
+            Ok(pdfs_fuse::MountOutcome::Shutdown) => {
+                tracing::info!("daemon stopping");
+                return Ok(());
+            }
+            Ok(pdfs_fuse::MountOutcome::Unmounted) => {
+                tracing::warn!("mount ended externally; remounting in 2s");
+                std::thread::sleep(std::time::Duration::from_secs(2));
+            }
+            Err(e) => {
+                tracing::error!(error = %e, "mount failed; retrying in 5s");
+                std::thread::sleep(std::time::Duration::from_secs(5));
+            }
+        }
+    }
+}
+
+/// One mount run: resume the session, mount, and block until the mount ends
+/// (clean shutdown or external unmount). Returns the [`MountOutcome`] so the
+/// daemon loop can decide whether to exit or remount.
+fn mount_once(mountpoint: Option<PathBuf>) -> Result<pdfs_fuse::MountOutcome> {
    let dirs = AppDirs::new()?;
    dirs.ensure()?;
-    let mountpoint = mountpoint.unwrap_or_else(|| dirs.default_mountpoint());
+    let config = dirs.load_config();
+    // An explicit `--mountpoint` wins; otherwise honor the Settings-page choice
+    // (config), falling back to the default location.
+    let mountpoint = mountpoint.unwrap_or_else(|| dirs.resolved_mountpoint(&config));
    std::fs::create_dir_all(&mountpoint)
        .with_context(|| format!("create mountpoint {}", mountpoint.display()))?;

    let username = auth::load().map(|s| s.username).unwrap_or_default();
+    // The daemon owns the unified DB (single writer). Open it here so the content
+    // cache and the mount share one handle: the cache uses its `cache_entries`
+    // table as the LRU index, the mount uses it for nodes/search/event cursor.
+    let db = Arc::new(Db::open(&dirs.db_path()).context("open cache db")?);
    let cache = ContentCache::open(
        dirs.content_cache_dir(),
        dirs.pins_path(),
-        pdfs_core::config::DEFAULT_CACHE_BUDGET_BYTES,
+        config.resolved_cache_budget(),
+        db.clone(),
    )
    .context("open content cache")?;
    let control_socket = dirs.control_socket();
@@ -209,8 +323,15 @@ fn cmd_mount(mountpoint: Option<PathBuf>) -> Result<()> {
    });

    let handle = rt.handle().clone();
-    let result =
-        pdfs_fuse::mount(client, handle, &mountpoint, cache, &control_socket, username);
+    let result = pdfs_fuse::mount(
+        client,
+        handle,
+        &mountpoint,
+        cache,
+        &control_socket,
+        db,
+        username,
+    );

    // Clean unmount: flush whatever tokens the store holds now so the keyring
    // always ends a session with the live refresh token, not a stale one. Runs
@@ -219,12 +340,14 @@ fn cmd_mount(mountpoint: Option<PathBuf>) -> Result<()> {
        tracing::warn!(error = %e, "failed to persist tokens on shutdown");
    }

-    result.context("mount failed")?;
-    Ok(())
+    let outcome = result.context("mount failed")?;
+    Ok(outcome)
 }

 fn cmd_pin(path: PathBuf) -> Result<()> {
-    match control_request(CtlRequest::Pin { path: path_arg(&path)? })? {
+    match control_request(CtlRequest::Pin {
+        path: path_arg(&path)?,
+    })? {
        CtlResponse::Ok { message } => println!("{message}"),
        CtlResponse::Error { message } => bail!("{message}"),
        other => bail!("unexpected response: {other:?}"),
@@ -233,7 +356,9 @@ fn cmd_pin(path: PathBuf) -> Result<()> {
 }

 fn cmd_unpin(path: PathBuf) -> Result<()> {
-    match control_request(CtlRequest::Unpin { path: path_arg(&path)? })? {
+    match control_request(CtlRequest::Unpin {
+        path: path_arg(&path)?,
+    })? {
        CtlResponse::Ok { message } => println!("{message}"),
        CtlResponse::Error { message } => bail!("{message}"),
        other => bail!("unexpected response: {other:?}"),
@@ -277,7 +402,9 @@ fn cmd_ls(path: Option<PathBuf>) -> Result<()> {

 fn cmd_photos(limit: usize, offset: usize) -> Result<()> {
    match control_request(CtlRequest::PhotosTimeline { offset, limit })? {
-        CtlResponse::Photos { available: false, .. } => {
+        CtlResponse::Photos {
+            available: false, ..
+        } => {
            println!("This account has no photos volume.")
        }
        CtlResponse::Photos { items, .. } if items.is_empty() => println!("No photos."),
@@ -302,13 +429,94 @@ fn cmd_open_photo(uid: String) -> Result<()> {
    Ok(())
 }

+fn cmd_search(query: String, limit: usize) -> Result<()> {
+    match control_request(CtlRequest::Search { query, limit })? {
+        CtlResponse::SearchResults { hits } if hits.is_empty() => println!("(no matches)"),
+        CtlResponse::SearchResults { hits } => {
+            for h in hits {
+                let kind = if h.is_dir { "d" } else { "-" };
+                let pin = if h.pinned { "*" } else { " " };
+                println!("{kind}{pin} {:>12}  {}", h.size, h.path);
+            }
+        }
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
+fn cmd_rename(path: PathBuf, new_name: String) -> Result<()> {
+    match control_request(CtlRequest::Rename {
+        path: path_arg(&path)?,
+        new_name,
+    })? {
+        CtlResponse::Ok { message } => println!("{message}"),
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
+fn cmd_move(path: PathBuf, new_parent: PathBuf) -> Result<()> {
+    match control_request(CtlRequest::Move {
+        path: path_arg(&path)?,
+        new_parent: path_arg(&new_parent)?,
+    })? {
+        CtlResponse::Ok { message } => println!("{message}"),
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
+fn cmd_rm(path: PathBuf) -> Result<()> {
+    match control_request(CtlRequest::Delete {
+        path: path_arg(&path)?,
+    })? {
+        CtlResponse::Ok { message } => println!("{message}"),
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
+fn cmd_mkdir(parent: PathBuf, name: String) -> Result<()> {
+    match control_request(CtlRequest::CreateFolder {
+        parent: path_arg(&parent)?,
+        name,
+    })? {
+        CtlResponse::Ok { message } => println!("{message}"),
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
+fn cmd_upload(file: PathBuf, parent: PathBuf) -> Result<()> {
+    let bytes = std::fs::read(&file).with_context(|| format!("read {}", file.display()))?;
+    let name = file
+        .file_name()
+        .and_then(|n| n.to_str())
+        .ok_or_else(|| anyhow!("source file has no valid name"))?
+        .to_owned();
+    match control_request(CtlRequest::UploadFile {
+        parent: path_arg(&parent)?,
+        name,
+        bytes,
+    })? {
+        CtlResponse::Ok { message } => println!("{message}"),
+        CtlResponse::Error { message } => bail!("{message}"),
+        other => bail!("unexpected response: {other:?}"),
+    }
+    Ok(())
+}
+
 /// Normalize a user-supplied path argument for sending to the daemon. Absolute
 /// paths are canonicalized (so the daemon can strip its mountpoint prefix);
 /// relative paths are passed through and resolved against the mount root.
 fn path_arg(path: &Path) -> Result<String> {
    let p = if path.is_absolute() {
-        std::fs::canonicalize(path)
-            .with_context(|| format!("resolve {}", path.display()))?
+        std::fs::canonicalize(path).with_context(|| format!("resolve {}", path.display()))?
    } else {
        path.to_path_buf()
    };
@@ -17,4 +17,5 @@ thiserror.workspace = true
 tracing.workspace = true
 directories.workspace = true
 sha2.workspace = true
+rusqlite.workspace = true
 keyring.workspace = true
@@ -12,7 +12,7 @@ use proton_sdk::config::ProtonClientConfiguration;
 use proton_sdk::session::{PasswordMode, ProtonApiSession, ResumeParameters};
 use serde::{Deserialize, Serialize};

-use crate::config::{APP_VERSION, KEYRING_SERVICE, USER_AGENT};
+use crate::config::{APP_VERSION, AppDirs, KEYRING_SERVICE, USER_AGENT};
 use crate::error::{Error, Result};

 /// Fixed keyring account name for the single stored session blob.
@@ -53,7 +53,14 @@ impl StoredSession {
 }

 fn client_config() -> ProtonClientConfiguration {
-    ProtonClientConfiguration::new(APP_VERSION).with_user_agent(USER_AGENT)
+    let (app_version, user_agent) = match AppDirs::new() {
+        Ok(dirs) => {
+            let config = dirs.load_config();
+            (config.app_version, config.user_agent)
+        }
+        Err(_) => (APP_VERSION.to_string(), USER_AGENT.to_string()),
+    };
+    ProtonClientConfiguration::new(app_version).with_user_agent(user_agent)
 }

 fn keyring_entry() -> Result<Entry> {
@@ -19,14 +19,38 @@
 use std::collections::{BTreeMap, HashSet};
 use std::io::{Read, Seek, SeekFrom};
 use std::path::{Path, PathBuf};
-use std::time::SystemTime;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};

 use proton_drive_rs::proton_sdk::ids::NodeUid;
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};

+use crate::db::Db;
 use crate::error::Result;

+/// `cache_entries.kind` tag for whole-file content blobs.
+const KIND_BLOB: &str = "blob";
+/// `cache_entries.kind` tag for on-demand block-cache chunks.
+const KIND_BLOCK: &str = "block";
+
+/// Current wall-clock time in unix *milliseconds*, for the LRU `last_accessed`
+/// column. Milliseconds (not seconds) so two cache events in the same second
+/// still order correctly — a coarse second-granularity clock would make LRU
+/// eviction order indeterminate under bursty access.
+fn now_millis() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+/// Block size for the on-demand block cache. Matches the SDK content block size
+/// (`DEFAULT_BLOCK_SIZE`, 4 MiB) so each cached block maps to exactly one
+/// `download_range` fetch with no straddling.
+pub const BLOCK_SIZE: u64 = 1 << 22;
+
 /// Validity tag stored alongside a cached blob. A blob is fresh only if both
 /// fields still match the node's current metadata.
 #[derive(Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
@@ -37,18 +61,22 @@ struct Meta {
    size: u64,
 }

-/// One pinned file, as persisted to the pin registry.
+/// One pin, as carried over the control socket and listed in `status`.
 #[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct Pin {
    /// Node uid in `volume~link` display form.
    pub uid: String,
-    /// Last path the file was pinned under, for display in `status`. Advisory
+    /// Last path the node was pinned under, for display in `status`. Advisory
    /// only — the uid is the identity.
    pub path: String,
+    /// A folder pin whose whole subtree is kept on disk. `false` for a single
+    /// file. Defaulted so a legacy `pins.json` (file pins only) still parses.
+    #[serde(default)]
+    pub recursive: bool,
 }

-/// The pin registry, persisted as JSON. Keyed by uid display string so a pin
-/// survives renames/moves of the node.
+/// The legacy JSON pin registry, kept only to import a pre-P5 `pins.json` into
+/// the DB once on open. Live pins are owned by the `pins` table.
 #[derive(Serialize, Deserialize, Default)]
 struct PinFile {
    pins: BTreeMap<String, Pin>,
@@ -61,27 +89,118 @@ pub struct ContentCache {
    /// Subdirectory holding cached thumbnails (`<key>.t<n>` + `.meta`). Kept out
    /// of `content_dir` so the budget scan never sees thumbnail files.
    thumb_dir: PathBuf,
+    /// Subdirectory holding on-demand block-cache files (`<key>.b<idx>` +
+    /// `.meta`). Kept out of `content_dir` so the whole-file budget scan never
+    /// sees them; blocks carry their own LRU budget.
+    block_dir: PathBuf,
+    /// Subdirectory for write-handle scratch files (disk-backed write buffers).
+    /// Emptied on open so a crashed run leaves no orphans.
+    scratch_dir: PathBuf,
    /// JSON pin registry path.
    pins_path: PathBuf,
    /// Soft cap on total blob bytes. Exceeded only transiently: a `store`
    /// evicts least-recently-used *unpinned* blobs back under the cap. `0`
    /// disables the cap. Pinned blobs are never evicted, so pins alone may push
-    /// the cache over budget.
-    max_bytes: u64,
+    /// the cache over budget. Atomic so the daemon can retune it at runtime
+    /// (a Settings-page change) via [`set_budget`](Self::set_budget) without
+    /// taking a lock on every cache read.
+    max_bytes: AtomicU64,
+    /// Unified metadata DB. Its `cache_entries` table is the LRU index: every
+    /// store/read/evict updates it, and the budget enforcers query it instead of
+    /// scanning the cache directories (plan.md P4).
+    db: Arc<Db>,
 }

 impl ContentCache {
    /// Open (and create) a cache under `content_dir`, with the pin registry at
    /// `pins_path` and a `max_bytes` size cap (`0` = unlimited). Both parent
-    /// directories are created if missing.
-    pub fn open(content_dir: PathBuf, pins_path: PathBuf, max_bytes: u64) -> Result<Self> {
+    /// directories are created if missing. `db` is the shared metadata database
+    /// whose `cache_entries` table backs LRU eviction; the on-disk cache is
+    /// reconciled into it on open.
+    pub fn open(
+        content_dir: PathBuf,
+        pins_path: PathBuf,
+        max_bytes: u64,
+        db: Arc<Db>,
+    ) -> Result<Self> {
        std::fs::create_dir_all(&content_dir)?;
        let thumb_dir = content_dir.join("thumbs");
        std::fs::create_dir_all(&thumb_dir)?;
+        let block_dir = content_dir.join("blocks");
+        std::fs::create_dir_all(&block_dir)?;
+        // Scratch holds disk-backed write buffers; a previous run's leftovers are
+        // worthless, so start clean.
+        let scratch_dir = content_dir.join("scratch");
+        let _ = std::fs::remove_dir_all(&scratch_dir);
+        std::fs::create_dir_all(&scratch_dir)?;
        if let Some(parent) = pins_path.parent() {
            std::fs::create_dir_all(parent)?;
        }
-        Ok(Self { content_dir, thumb_dir, pins_path, max_bytes })
+        let cache = Self {
+            content_dir,
+            thumb_dir,
+            block_dir,
+            scratch_dir,
+            pins_path,
+            max_bytes: AtomicU64::new(max_bytes),
+            db,
+        };
+        cache.reconcile()?;
+        cache.import_legacy_pins()?;
+        Ok(cache)
+    }
+
+    /// One-time migration of a pre-P5 `pins.json` into the DB `pins` table, then
+    /// delete the file so it never re-imports. Legacy pins were all whole-file
+    /// (non-recursive). Absent file → nothing to do.
+    fn import_legacy_pins(&self) -> Result<()> {
+        let Ok(bytes) = std::fs::read(&self.pins_path) else {
+            return Ok(());
+        };
+        if let Ok(file) = serde_json::from_slice::<PinFile>(&bytes) {
+            for (uid, pin) in file.pins {
+                self.db.pin_add(&uid, &pin.path, false)?;
+            }
+        }
+        let _ = std::fs::remove_file(&self.pins_path);
+        Ok(())
+    }
+
+    /// Rebuild the `cache_entries` LRU index from the on-disk cache. Called once
+    /// on open: the index is cleared, then every blob (`content_dir`) and block
+    /// (`block_dir`) file is re-registered with its on-disk size and last-modified
+    /// time as the initial LRU key. This makes the DB authoritative even after a
+    /// crash or an external file deletion, and picks up caches written by builds
+    /// predating the index. In-run accesses then refine the ordering.
+    fn reconcile(&self) -> Result<()> {
+        self.db.cache_clear()?;
+        for (dir, kind) in [
+            (&self.content_dir, KIND_BLOB),
+            (&self.block_dir, KIND_BLOCK),
+        ] {
+            let Ok(rd) = std::fs::read_dir(dir) else {
+                continue;
+            };
+            for entry in rd.flatten() {
+                let name = entry.file_name();
+                let Some(name) = name.to_str() else { continue };
+                if name.ends_with(".meta") || name.ends_with(".tmp") {
+                    continue;
+                }
+                let Ok(meta) = entry.metadata() else { continue };
+                if !meta.is_file() {
+                    continue;
+                }
+                let at = meta
+                    .modified()
+                    .ok()
+                    .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
+                    .map(|d| d.as_millis() as i64)
+                    .unwrap_or(0);
+                self.db.cache_touch(name, kind, meta.len(), at)?;
+            }
+        }
+        Ok(())
    }

    /// Filesystem-safe, fixed-length cache key for a uid display string: the
@@ -145,10 +264,10 @@ impl ContentCache {
        len: u64,
    ) -> Option<Vec<u8>> {
        let blob = self.valid_blob(uid, mtime, size)?;
-        // Record the access for LRU: bump the blob's mtime to now. Best effort —
-        // a failed touch only makes eviction order slightly less accurate.
+        // Record the access for LRU in the cache index. Best effort — a failed
+        // update only makes eviction order slightly less accurate.
+        let _ = self.db.cache_accessed(&Self::key(uid), now_millis());
        let mut f = std::fs::File::open(&blob).ok()?;
-        let _ = f.set_times(std::fs::FileTimes::new().set_modified(SystemTime::now()));
        if offset >= size {
            return Some(Vec::new());
        }
@@ -171,10 +290,130 @@ impl ContentCache {
        std::fs::rename(&tmp, &blob)?;
        let meta = serde_json::to_vec(&Meta { mtime, size })?;
        std::fs::write(self.meta_path(uid), meta)?;
+        // Register the blob in the LRU index before enforcing the budget so the
+        // newest entry is weighed (and ordered most-recent) like any other.
+        self.db
+            .cache_touch(&Self::key(uid), KIND_BLOB, bytes.len() as u64, now_millis())?;
        self.enforce_budget();
        Ok(())
    }

+    /// Cache-index key for block `idx` of `uid` — the block file's name, which
+    /// is also its `cache_entries.cache_key`.
+    fn block_key(&self, uid: &NodeUid, idx: u64) -> String {
+        format!("{}.b{idx}", Self::key(uid))
+    }
+
+    fn block_blob(&self, uid: &NodeUid, idx: u64) -> PathBuf {
+        self.block_dir.join(self.block_key(uid, idx))
+    }
+
+    fn block_meta(&self, uid: &NodeUid, idx: u64) -> PathBuf {
+        self.block_dir
+            .join(format!("{}.b{idx}.meta", Self::key(uid)))
+    }
+
+    /// Serve cached block `idx` (a [`BLOCK_SIZE`]-aligned chunk) of `uid`, or
+    /// `None` on miss/stale. Validated against `(mtime, size)` like a whole-file
+    /// blob, so a new revision (which bumps the mtime) is detected. Bumps the
+    /// block's mtime for LRU, best effort.
+    pub fn cached_block(&self, uid: &NodeUid, mtime: i64, size: u64, idx: u64) -> Option<Vec<u8>> {
+        let want = Meta { mtime, size };
+        let meta: Meta =
+            serde_json::from_slice(&std::fs::read(self.block_meta(uid, idx)).ok()?).ok()?;
+        if meta != want {
+            return None;
+        }
+        let mut f = std::fs::File::open(self.block_blob(uid, idx)).ok()?;
+        // LRU touch in the cache index (best effort).
+        let _ = self
+            .db
+            .cache_accessed(&self.block_key(uid, idx), now_millis());
+        let mut buf = Vec::new();
+        f.read_to_end(&mut buf).ok()?;
+        Some(buf)
+    }
+
+    /// Store `bytes` as cached block `idx` of `uid`, tagged `(mtime, size)`.
+    /// Temp-file-then-rename like [`store`](Self::store); meta written last so a
+    /// crash mid-store fails validation. Enforces the block-cache LRU budget.
+    pub fn store_block(
+        &self,
+        uid: &NodeUid,
+        mtime: i64,
+        size: u64,
+        idx: u64,
+        bytes: &[u8],
+    ) -> Result<()> {
+        let blob = self.block_blob(uid, idx);
+        let tmp = self
+            .block_dir
+            .join(format!("{}.b{idx}.tmp", Self::key(uid)));
+        std::fs::write(&tmp, bytes)?;
+        std::fs::rename(&tmp, &blob)?;
+        std::fs::write(
+            self.block_meta(uid, idx),
+            serde_json::to_vec(&Meta { mtime, size })?,
+        )?;
+        self.db.cache_touch(
+            &self.block_key(uid, idx),
+            KIND_BLOCK,
+            bytes.len() as u64,
+            now_millis(),
+        )?;
+        self.enforce_block_budget();
+        Ok(())
+    }
+
+    /// Evict least-recently-used block-cache files until the block dir fits
+    /// `max_bytes`. No-op when the cap is disabled (`0`). All blocks are
+    /// evictable — pinned files are served from whole-file blobs, never blocks.
+    fn enforce_block_budget(&self) {
+        let cap = self.cap();
+        if cap == 0 {
+            return;
+        }
+        // LRU-ordered (oldest first) block entries straight from the index — no
+        // directory scan. All blocks are evictable; pinned files are served from
+        // whole-file blobs, never blocks.
+        let Ok(entries) = self.db.cache_entries_by_kind(KIND_BLOCK) else {
+            return;
+        };
+        let mut total: u64 = entries.iter().map(|(_, size)| *size).sum();
+        if total <= cap {
+            return;
+        }
+        for (key, size) in entries {
+            if total <= cap {
+                break;
+            }
+            // `key` is the block file's name (and its `.meta` sibling's stem).
+            let _ = std::fs::remove_file(self.block_dir.join(&key));
+            let _ = std::fs::remove_file(self.block_dir.join(format!("{key}.meta")));
+            let _ = self.db.cache_remove(&key);
+            total = total.saturating_sub(size);
+        }
+    }
+
+    /// Create a fresh, empty read-write scratch file for a disk-backed write
+    /// handle. Returns the open file and its path (for cleanup on release).
+    pub fn create_scratch(&self) -> Result<(std::fs::File, PathBuf)> {
+        use std::sync::atomic::{AtomicU64, Ordering};
+        static N: AtomicU64 = AtomicU64::new(0);
+        let path = self.scratch_dir.join(format!(
+            "w-{}-{}",
+            std::process::id(),
+            N.fetch_add(1, Ordering::Relaxed)
+        ));
+        let file = std::fs::OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .read(true)
+            .write(true)
+            .open(&path)?;
+        Ok((file, path))
+    }
+
    /// Remove any cached blob + meta for `uid`, including its thumbnails (best
    /// effort; absence is fine). Thumbnails are tied to the revision, so a
    /// content eviction must drop them too.
@@ -185,6 +424,24 @@ impl ContentCache {
            let _ = std::fs::remove_file(self.thumb_blob(uid, ttype));
            let _ = std::fs::remove_file(self.thumb_meta(uid, ttype));
        }
+        // Drop every cached block (and its meta/tmp) for this uid. The block
+        // dir is still scanned here because eviction targets one uid's files by
+        // name prefix, not by LRU order; the index rows are removed in one shot
+        // by `cache_remove_all` below.
+        let prefix = format!("{}.b", Self::key(uid));
+        if let Ok(rd) = std::fs::read_dir(&self.block_dir) {
+            for entry in rd.flatten() {
+                if entry
+                    .file_name()
+                    .to_str()
+                    .is_some_and(|n| n.starts_with(&prefix))
+                {
+                    let _ = std::fs::remove_file(entry.path());
+                }
+            }
+        }
+        // Forget the blob and all of this uid's block rows in the LRU index.
+        let _ = self.db.cache_remove_all(&Self::key(uid));
    }

    fn thumb_blob(&self, uid: &NodeUid, ttype: i32) -> PathBuf {
@@ -192,7 +449,8 @@ impl ContentCache {
    }

    fn thumb_meta(&self, uid: &NodeUid, ttype: i32) -> PathBuf {
-        self.thumb_dir.join(format!("{}.t{ttype}.meta", Self::key(uid)))
+        self.thumb_dir
+            .join(format!("{}.t{ttype}.meta", Self::key(uid)))
    }

    /// Serve a cached thumbnail of `ttype` for `uid`, or `None` on miss/stale.
@@ -263,97 +521,84 @@ impl ContentCache {
    /// cache already fits. Pinned blobs are skipped, so a cache held entirely by
    /// pins can legitimately stay over budget.
    fn enforce_budget(&self) {
-        if self.max_bytes == 0 {
+        let cap = self.cap();
+        if cap == 0 {
            return;
        }
-        // Pinned blobs (by cache key) are exempt from eviction.
-        let pinned: HashSet<String> =
-            self.load_pins().pins.keys().map(|uid| Self::key_str(uid)).collect();
+        // Pinned blobs (by cache key) are exempt from eviction. Resolves direct
+        // pins plus every descendant of a recursively-pinned folder, hashed into
+        // cache keys to match on-disk filenames.
+        let pinned: HashSet<String> = self
+            .db
+            .pinned_uids()
+            .unwrap_or_default()
+            .iter()
+            .map(|uid| Self::key_str(uid))
+            .collect();

-        // Scan blobs (the `<key>` files; skip `.meta`/`.tmp` siblings), record
-        // size + last-access (mtime) for each.
-        let mut total: u64 = 0;
-        let mut blobs: Vec<(PathBuf, u64, SystemTime)> = Vec::new();
-        let Ok(rd) = std::fs::read_dir(&self.content_dir) else {
+        // LRU-ordered (oldest first) blob entries from the index — no directory
+        // scan. Pinned blobs still count toward the total (so pins alone can hold
+        // the cache over budget) but are never chosen as victims.
+        let Ok(entries) = self.db.cache_entries_by_kind(KIND_BLOB) else {
            return;
        };
-        for entry in rd.flatten() {
-            let path = entry.path();
-            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
-                continue;
-            };
-            if name.ends_with(".meta") || name.ends_with(".tmp") {
-                continue;
-            }
-            let Ok(meta) = entry.metadata() else { continue };
-            if !meta.is_file() {
-                continue;
-            }
-            total += meta.len();
-            if pinned.contains(name) {
-                continue; // counts toward total but is never a victim
-            }
-            let atime = meta.modified().unwrap_or(SystemTime::UNIX_EPOCH);
-            blobs.push((path, meta.len(), atime));
-        }
-        if total <= self.max_bytes {
+        let mut total: u64 = entries.iter().map(|(_, size)| *size).sum();
+        if total <= cap {
            return;
        }
-        // Oldest access first.
-        blobs.sort_by_key(|(_, _, atime)| *atime);
-        for (path, len, _) in blobs {
-            if total <= self.max_bytes {
+        for (key, size) in entries {
+            if total <= cap {
                break;
            }
-            let _ = std::fs::remove_file(&path);
-            let _ = std::fs::remove_file(path.with_extension("meta"));
-            total = total.saturating_sub(len);
+            if pinned.contains(&key) {
+                continue; // counts toward total but is never a victim
+            }
+            // `key` is the blob file's name (and its `.meta` sibling's stem).
+            let _ = std::fs::remove_file(self.content_dir.join(&key));
+            let _ = std::fs::remove_file(self.content_dir.join(format!("{key}.meta")));
+            let _ = self.db.cache_remove(&key);
+            total = total.saturating_sub(size);
        }
    }

-    fn load_pins(&self) -> PinFile {
-        std::fs::read(&self.pins_path)
-            .ok()
-            .and_then(|b| serde_json::from_slice(&b).ok())
-            .unwrap_or_default()
-    }
-
-    fn save_pins(&self, pins: &PinFile) -> Result<()> {
-        std::fs::write(&self.pins_path, serde_json::to_vec_pretty(pins)?)?;
-        Ok(())
-    }
-
-    /// Whether `uid` is pinned (independent of whether its blob is currently
-    /// cached).
+    /// Whether `uid` is pinned — directly, or because an ancestor folder is
+    /// pinned recursively (resolved in the DB against the node tree). Independent
+    /// of whether its blob is currently cached. Best effort: a DB error reads as
+    /// "not pinned" rather than failing the calling FUSE op.
    pub fn is_pinned(&self, uid: &NodeUid) -> bool {
-        self.load_pins().pins.contains_key(&uid.to_string())
+        self.db.is_pinned(&uid.to_string()).unwrap_or(false)
    }

-    /// Record `uid` as pinned under `path`. The caller is responsible for having
-    /// already cached the content via [`store`](Self::store).
-    pub fn add_pin(&self, uid: &NodeUid, path: &Path) -> Result<()> {
-        let mut file = self.load_pins();
-        let key = uid.to_string();
-        file.pins.insert(
-            key.clone(),
-            Pin { uid: key, path: path.display().to_string() },
-        );
-        self.save_pins(&file)
+    /// Record `uid` as pinned under `path`. `recursive` marks a folder pin whose
+    /// whole subtree is kept. The caller is responsible for having cached the
+    /// content (a file via [`store`](Self::store); a folder's descendants by the
+    /// daemon walking the subtree).
+    pub fn add_pin(&self, uid: &NodeUid, path: &Path, recursive: bool) -> Result<()> {
+        self.db
+            .pin_add(&uid.to_string(), &path.display().to_string(), recursive)
    }

    /// Drop `uid` from the pin registry and evict its blob. No-op if not pinned.
+    /// A recursively-pinned folder's descendants are evicted by the daemon
+    /// (`Core::unpin`), which knows the node tree.
    pub fn remove_pin(&self, uid: &NodeUid) -> Result<()> {
-        let mut file = self.load_pins();
-        if file.pins.remove(&uid.to_string()).is_some() {
-            self.save_pins(&file)?;
-        }
+        self.db.pin_remove(&uid.to_string())?;
        self.evict(uid);
        Ok(())
    }

-    /// All pinned files, ordered by uid.
+    /// All pins (files and recursive folders), ordered by uid.
    pub fn list_pins(&self) -> Vec<Pin> {
-        self.load_pins().pins.into_values().collect()
+        self.db
+            .pin_list()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|(uid, path, recursive)| Pin {
+                uid,
+                path,
+                recursive,
+            })
+            .collect()
    }

    /// Total bytes of cached content blobs (pinned + unpinned), matching what
@@ -384,7 +629,61 @@ impl ContentCache {
    /// Configured soft byte cap (`0` = unlimited), for display alongside
    /// [`usage`](Self::usage).
    pub fn budget(&self) -> u64 {
-        self.max_bytes
+        self.cap()
+    }
+
+    /// The current soft byte cap. A plain atomic load; the value can change
+    /// under [`set_budget`](Self::set_budget) while the daemon runs.
+    fn cap(&self) -> u64 {
+        self.max_bytes.load(Ordering::Relaxed)
+    }
+
+    /// Retune the soft byte cap (`0` = unlimited) at runtime and immediately
+    /// enforce it: blobs and blocks are LRU-evicted back under the new cap (a
+    /// lower cap frees space now; a higher one is a no-op until the next store).
+    /// Called by the daemon when the Settings page changes the cache budget.
+    pub fn set_budget(&self, bytes: u64) {
+        self.max_bytes.store(bytes, Ordering::Relaxed);
+        self.enforce_budget();
+        self.enforce_block_budget();
+    }
+
+    /// Delete every *unpinned* cached blob plus all on-demand block chunks,
+    /// keeping pinned files intact. Pinned files keep their whole-file blobs
+    /// (and are never served from blocks), so dropping all blocks is safe.
+    /// Returns the number of bytes freed, for a user-facing confirmation.
+    pub fn clear_unpinned(&self) -> u64 {
+        // Pinned blobs are exempt; resolve them to cache keys to match filenames.
+        let pinned: HashSet<String> = self
+            .db
+            .pinned_uids()
+            .unwrap_or_default()
+            .iter()
+            .map(|uid| Self::key_str(uid))
+            .collect();
+        let mut freed = 0u64;
+        // Unpinned whole-file blobs.
+        if let Ok(entries) = self.db.cache_entries_by_kind(KIND_BLOB) {
+            for (key, size) in entries {
+                if pinned.contains(&key) {
+                    continue;
+                }
+                let _ = std::fs::remove_file(self.content_dir.join(&key));
+                let _ = std::fs::remove_file(self.content_dir.join(format!("{key}.meta")));
+                let _ = self.db.cache_remove(&key);
+                freed = freed.saturating_add(size);
+            }
+        }
+        // Every on-demand block (transient partial reads, re-fetched on demand).
+        if let Ok(entries) = self.db.cache_entries_by_kind(KIND_BLOCK) {
+            for (key, size) in entries {
+                let _ = std::fs::remove_file(self.block_dir.join(&key));
+                let _ = std::fs::remove_file(self.block_dir.join(format!("{key}.meta")));
+                let _ = self.db.cache_remove(&key);
+                freed = freed.saturating_add(size);
+            }
+        }
+        freed
    }
 }

@@ -427,10 +726,12 @@ mod tests {

    fn cache_capped(max_bytes: u64) -> (ContentCache, TempDir) {
        let dir = TempDir::new();
+        let db = Arc::new(Db::open_in_memory().unwrap());
        let c = ContentCache::open(
            dir.path().join("content"),
            dir.path().join("pins.json"),
            max_bytes,
+            db,
        )
        .unwrap();
        (c, dir)
@@ -454,6 +755,40 @@ mod tests {
        );
    }

+    #[test]
+    fn reconcile_rebuilds_index_from_disk() {
+        let dir = TempDir::new();
+        let content = dir.path().join("content");
+        let pins = dir.path().join("pins.json");
+
+        // First session: unlimited cap, store three blobs onto disk.
+        let db1 = Arc::new(Db::open_in_memory().unwrap());
+        {
+            let c = ContentCache::open(content.clone(), pins.clone(), 0, db1).unwrap();
+            c.store(&uid("a"), 1, 4, b"aaaa").unwrap();
+            c.store(&uid("b"), 1, 4, b"bbbb").unwrap();
+            c.store(&uid("c"), 1, 4, b"cccc").unwrap();
+        }
+
+        // Second session with a *fresh* index (as if predating P4, or after a
+        // crash) but the same on-disk cache: reconcile repopulates from disk.
+        let db2 = Arc::new(Db::open_in_memory().unwrap());
+        assert!(db2.cache_entries_by_kind("blob").unwrap().is_empty());
+        let c = ContentCache::open(content, pins, 8, db2.clone()).unwrap();
+        assert_eq!(db2.cache_entries_by_kind("blob").unwrap().len(), 3);
+
+        // With the index rebuilt, a further store enforces the budget against the
+        // reconciled entries instead of leaking them.
+        c.store(&uid("d"), 1, 4, b"dddd").unwrap();
+        let total: u64 = db2
+            .cache_entries_by_kind("blob")
+            .unwrap()
+            .iter()
+            .map(|(_, s)| s)
+            .sum();
+        assert!(total <= 8, "budget enforced after reconcile, total={total}");
+    }
+
    #[test]
    fn stale_metadata_is_a_miss() {
        let (c, _d) = cache();
@@ -466,12 +801,36 @@ mod tests {
        assert!(c.read_range(&u, 100, 4, 0, 3).is_none());
    }

+    #[test]
+    fn legacy_pins_json_imported_then_removed() {
+        let dir = TempDir::new();
+        let pins = dir.path().join("pins.json");
+        // Hand-write a pre-P5 pins.json (file pins only, no `recursive` field).
+        std::fs::write(
+            &pins,
+            r#"{"pins":{"vol~a":{"uid":"vol~a","path":"docs/a.txt"}}}"#,
+        )
+        .unwrap();
+
+        let db = Arc::new(Db::open_in_memory().unwrap());
+        let c = ContentCache::open(dir.path().join("content"), pins.clone(), 0, db).unwrap();
+
+        // Imported into the DB as a non-recursive pin...
+        assert!(c.is_pinned(&uid("a")));
+        let listed = c.list_pins();
+        assert_eq!(listed.len(), 1);
+        assert_eq!(listed[0].path, "docs/a.txt");
+        assert!(!listed[0].recursive);
+        // ...and the legacy file is gone so it never re-imports.
+        assert!(!pins.exists());
+    }
+
    #[test]
    fn pin_lifecycle_evicts_on_unpin() {
        let (c, _d) = cache();
        let u = uid("a");
        c.store(&u, 100, 3, b"abc").unwrap();
-        c.add_pin(&u, Path::new("docs/a.txt")).unwrap();
+        c.add_pin(&u, Path::new("docs/a.txt"), false).unwrap();
        assert!(c.is_pinned(&u));
        assert_eq!(c.list_pins().len(), 1);
        assert_eq!(c.list_pins()[0].path, "docs/a.txt");
@@ -511,7 +870,7 @@ mod tests {
        let (a, b, d) = (uid("a"), uid("b"), uid("d"));

        c.store(&a, 1, 4, b"aaaa").unwrap();
-        c.add_pin(&a, Path::new("a")).unwrap();
+        c.add_pin(&a, Path::new("a"), false).unwrap();
        std::thread::sleep(std::time::Duration::from_millis(10));
        c.store(&b, 1, 4, b"bbbb").unwrap();
        // Over budget: `a` is pinned (oldest) so `b` must be the victim.
@@ -522,6 +881,43 @@ mod tests {
        assert!(c.is_cached(&d, 1, 4));
    }

+    #[test]
+    fn clear_unpinned_keeps_pinned() {
+        let (c, _d) = cache();
+        let (a, b) = (uid("a"), uid("b"));
+        c.store(&a, 1, 4, b"aaaa").unwrap();
+        c.add_pin(&a, Path::new("a"), false).unwrap();
+        c.store(&b, 1, 4, b"bbbb").unwrap();
+        // A stray on-demand block of the unpinned file is purged too.
+        c.store_block(&b, 1, 8, 0, b"bbbb").unwrap();
+
+        let freed = c.clear_unpinned();
+        assert_eq!(freed, 8, "one 4-byte blob + one 4-byte block freed");
+        assert!(c.is_cached(&a, 1, 4), "pinned blob survives purge");
+        assert!(!c.is_cached(&b, 1, 4), "unpinned blob purged");
+        assert!(c.cached_block(&b, 1, 8, 0).is_none(), "block purged");
+    }
+
+    #[test]
+    fn set_budget_evicts_immediately() {
+        // Start unlimited so three blobs all fit, then tighten the cap.
+        let (c, _d) = cache();
+        let (a, b, d) = (uid("a"), uid("b"), uid("d"));
+        c.store(&a, 1, 4, b"aaaa").unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&b, 1, 4, b"bbbb").unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store(&d, 1, 4, b"dddd").unwrap();
+
+        // Tightening to 8 bytes evicts the LRU unpinned blob(s) now, not on the
+        // next store.
+        c.set_budget(8);
+        assert!(!c.is_cached(&a, 1, 4), "oldest blob evicted on tighten");
+        assert!(c.is_cached(&b, 1, 4));
+        assert!(c.is_cached(&d, 1, 4));
+        assert_eq!(c.budget(), 8);
+    }
+
    #[test]
    fn thumbnail_store_read_and_evict() {
        let (c, _d) = cache();
@@ -546,4 +942,63 @@ mod tests {
        c.evict(&u);
        assert!(!c.is_cached(&u, 1, 3));
    }
+
+    #[test]
+    fn block_store_then_read() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store_block(&u, 100, 4096, 0, b"block-zero").unwrap();
+        assert_eq!(c.cached_block(&u, 100, 4096, 0).unwrap(), b"block-zero");
+        // A different index is a separate cache entry, absent here.
+        assert!(c.cached_block(&u, 100, 4096, 1).is_none());
+        // A new revision (mtime/size bump) invalidates the block.
+        assert!(c.cached_block(&u, 101, 4096, 0).is_none());
+        assert!(c.cached_block(&u, 100, 5000, 0).is_none());
+    }
+
+    #[test]
+    fn evict_drops_blocks() {
+        let (c, _d) = cache();
+        let u = uid("a");
+        c.store_block(&u, 1, 8, 0, b"aaaa").unwrap();
+        c.store_block(&u, 1, 8, 1, b"bbbb").unwrap();
+        c.evict(&u);
+        assert!(c.cached_block(&u, 1, 8, 0).is_none());
+        assert!(c.cached_block(&u, 1, 8, 1).is_none());
+    }
+
+    #[test]
+    fn block_budget_evicts_lru() {
+        // Cap fits two 4-byte blocks but not three.
+        let (c, _d) = cache_capped(8);
+        let u = uid("a");
+        c.store_block(&u, 1, 12, 0, b"aaaa").unwrap();
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store_block(&u, 1, 12, 1, b"bbbb").unwrap();
+        // Touch block 0 so block 1 is the least-recently-used.
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        assert!(c.cached_block(&u, 1, 12, 0).is_some());
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        c.store_block(&u, 1, 12, 2, b"cccc").unwrap();
+        assert!(
+            c.cached_block(&u, 1, 12, 0).is_some(),
+            "recently-read survives"
+        );
+        assert!(c.cached_block(&u, 1, 12, 1).is_none(), "LRU block evicted");
+        assert!(c.cached_block(&u, 1, 12, 2).is_some(), "newest survives");
+    }
+
+    #[test]
+    fn scratch_file_is_writable_and_isolated() {
+        use std::io::{Read as _, Seek as _, SeekFrom, Write as _};
+        let (c, _d) = cache();
+        let (mut f1, p1) = c.create_scratch().unwrap();
+        let (_f2, p2) = c.create_scratch().unwrap();
+        assert_ne!(p1, p2, "each scratch file is unique");
+        f1.write_all(b"scratch").unwrap();
+        f1.seek(SeekFrom::Start(0)).unwrap();
+        let mut s = String::new();
+        f1.read_to_string(&mut s).unwrap();
+        assert_eq!(s, "scratch");
+    }
 }
@@ -3,6 +3,7 @@
 use std::path::PathBuf;

 use directories::ProjectDirs;
+use serde::{Deserialize, Serialize};

 use crate::error::{Error, Result};

@@ -18,6 +19,42 @@ pub const KEYRING_SERVICE: &str = "proton-drive-linux";
 /// blobs back under this; pinned files are exempt. See [`crate::cache`].
 pub const DEFAULT_CACHE_BUDGET_BYTES: u64 = 5 * 1024 * 1024 * 1024;

+/// Configuration structure allowing the user to customize client identification headers.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct AppConfig {
+    pub app_version: String,
+    pub user_agent: String,
+    /// Soft cap on the on-disk content cache, in bytes (`0` = unlimited).
+    /// `None` means "use [`DEFAULT_CACHE_BUDGET_BYTES`]"; the Settings page
+    /// writes an explicit value here. Defaulted for configs predating the field.
+    #[serde(default)]
+    pub cache_budget: Option<u64>,
+    /// Mountpoint the daemon mounts at. `None` means
+    /// [`AppDirs::default_mountpoint`]; the Settings page writes an explicit
+    /// path here. Defaulted for configs predating the field.
+    #[serde(default)]
+    pub mountpoint: Option<String>,
+}
+
+impl Default for AppConfig {
+    fn default() -> Self {
+        Self {
+            app_version: APP_VERSION.to_string(),
+            user_agent: USER_AGENT.to_string(),
+            cache_budget: None,
+            mountpoint: None,
+        }
+    }
+}
+
+impl AppConfig {
+    /// The effective cache budget in bytes: the user's explicit choice, or
+    /// [`DEFAULT_CACHE_BUDGET_BYTES`] when unset.
+    pub fn resolved_cache_budget(&self) -> u64 {
+        self.cache_budget.unwrap_or(DEFAULT_CACHE_BUDGET_BYTES)
+    }
+}
+
 /// Resolved XDG locations for state, cache, and the default mountpoint.
 pub struct AppDirs {
    dirs: ProjectDirs,
@@ -30,6 +67,41 @@ impl AppDirs {
        Ok(Self { dirs })
    }

+    /// Configuration file path (e.g. ~/.config/proton-drive-linux/config.json).
+    pub fn config_path(&self) -> PathBuf {
+        self.dirs.config_dir().join("config.json")
+    }
+
+    /// Load config from disk, creating default if missing.
+    pub fn load_config(&self) -> AppConfig {
+        let path = self.config_path();
+        if path.exists()
+            && let Ok(content) = std::fs::read_to_string(&path)
+            && let Ok(config) = serde_json::from_str::<AppConfig>(&content)
+        {
+            return config;
+        }
+
+        let default_config = AppConfig::default();
+        if let Ok(content) = serde_json::to_string_pretty(&default_config) {
+            let _ = std::fs::create_dir_all(self.dirs.config_dir());
+            let _ = std::fs::write(&path, content);
+        }
+        default_config
+    }
+
+    /// Persist `config` to [`config_path`](Self::config_path), creating the
+    /// config dir if missing. The Settings page calls this after editing the
+    /// cache budget or mountpoint; the daemon re-reads the file on its next mount.
+    pub fn save_config(&self, config: &AppConfig) -> Result<()> {
+        let path = self.config_path();
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::write(&path, serde_json::to_string_pretty(config)?)?;
+        Ok(())
+    }
+
    /// Persistent state: inode map / cache index DB lives here.
    pub fn state_dir(&self) -> PathBuf {
        // `state_dir` is Linux-only in `directories`; fall back to data dir.
@@ -54,11 +126,22 @@ impl AppDirs {
        self.state_dir().join("pins.json")
    }

+    /// Unified SQLite metadata cache (inodes, FTS, cache LRU, pins). Lives in
+    /// persistent state next to `control.sock`; only the daemon writes it.
+    pub fn db_path(&self) -> PathBuf {
+        self.state_dir().join("cache.db")
+    }
+
    /// Unix domain socket the mount daemon listens on for CLI control commands.
    pub fn control_socket(&self) -> PathBuf {
        self.state_dir().join("control.sock")
    }

+    /// Unix domain socket the tray uses to ensure single instance.
+    pub fn tray_socket(&self) -> PathBuf {
+        self.state_dir().join("tray.sock")
+    }
+
    /// Default mountpoint when the user does not pass one explicitly.
    pub fn default_mountpoint(&self) -> PathBuf {
        directories::UserDirs::new()
@@ -66,10 +149,47 @@ impl AppDirs {
            .unwrap_or_else(|| PathBuf::from("/tmp/ProtonDrive"))
    }

+    /// The effective mountpoint: the config's explicit path, or
+    /// [`default_mountpoint`](Self::default_mountpoint) when unset.
+    pub fn resolved_mountpoint(&self, config: &AppConfig) -> PathBuf {
+        config
+            .mountpoint
+            .as_ref()
+            .map(PathBuf::from)
+            .unwrap_or_else(|| self.default_mountpoint())
+    }
+
    /// Create state + cache dirs if missing.
    pub fn ensure(&self) -> Result<()> {
        std::fs::create_dir_all(self.state_dir())?;
        std::fs::create_dir_all(self.cache_dir())?;
+        let _ = std::fs::create_dir_all(self.dirs.config_dir());
        Ok(())
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_app_config_serialization() {
+        let config = AppConfig {
+            app_version: "external-drive-test-client@1.0.0".to_string(),
+            user_agent: "test-agent/1.0".to_string(),
+            cache_budget: Some(1234),
+            mountpoint: Some("/tmp/x".to_string()),
+        };
+        let json = serde_json::to_string(&config).unwrap();
+        let decoded: AppConfig = serde_json::from_str(&json).unwrap();
+        assert_eq!(decoded.app_version, "external-drive-test-client@1.0.0");
+        assert_eq!(decoded.user_agent, "test-agent/1.0");
+    }
+
+    #[test]
+    fn test_default_app_config() {
+        let default_config = AppConfig::default();
+        assert_eq!(default_config.app_version, APP_VERSION);
+        assert_eq!(default_config.user_agent, USER_AGENT);
+    }
+}
@@ -49,10 +49,46 @@ pub enum Request {
    PhotosTimeline { offset: usize, limit: usize },
    /// Download a photo's full content into the cache; replies with its path.
    OpenPhoto { uid: String },
+    /// Upload a photo with the given name, media type, and content bytes.
+    UploadPhoto {
+        name: String,
+        media_type: String,
+        bytes: Vec<u8>,
+        capture_time: Option<i64>,
+    },
    /// Download a Drive file's full content into the cache; replies with the
    /// on-disk path so the front-end can open it with the default app. `path`
    /// is mountpoint-relative.
    OpenFile { path: String },
+    /// Full-text search node names against the daemon's local metadata index.
+    /// `limit` caps the number of hits returned. Replies with [`Response::SearchResults`].
+    Search { query: String, limit: usize },
+    /// Rename a file or folder. `path` is mountpoint-relative; `new_name` is a
+    /// single path component (no separators). Replies with [`Response::Ok`].
+    Rename { path: String, new_name: String },
+    /// Move a file or folder into a new parent folder. Both `path` and
+    /// `new_parent` are mountpoint-relative. Replies with [`Response::Ok`].
+    Move { path: String, new_parent: String },
+    /// Trash a file or folder. `path` is mountpoint-relative. Replies with
+    /// [`Response::Ok`].
+    Delete { path: String },
+    /// Create a new folder named `name` under the mountpoint-relative `parent`.
+    /// Replies with [`Response::Ok`].
+    CreateFolder { parent: String, name: String },
+    /// Upload a file named `name` with content `bytes` into the
+    /// mountpoint-relative `parent` folder. Replies with [`Response::Ok`].
+    UploadFile {
+        parent: String,
+        name: String,
+        bytes: Vec<u8>,
+    },
+    /// Delete all unpinned cached blobs and on-demand blocks, keeping pinned
+    /// files intact. Replies with [`Response::Ok`] reporting the bytes freed.
+    PurgeCache,
+    /// Retune the on-disk cache's soft byte cap at runtime (`0` = unlimited) and
+    /// persist it to config so the next mount keeps it. Replies with
+    /// [`Response::Ok`].
+    SetCacheBudget { bytes: u64 },
 }

 /// One entry in a [`Request::ListDir`] listing.
@@ -67,8 +103,35 @@ pub struct DirEntry {
    pub modified: i64,
    /// Whether the file is pinned to this device.
    pub pinned: bool,
+    /// Whether the file's full content is present in the local cache (a current,
+    /// non-stale blob). Always false for folders. Defaulted for wire-compat with
+    /// clients/daemons predating the field.
+    #[serde(default)]
+    pub cached: bool,
    /// Node uid in `volume~link` form, for follow-up requests.
    pub uid: String,
+    /// Full mountpoint-relative path. Empty for a [`Request::ListDir`] listing
+    /// (the entry lives in the requested directory, so the caller derives the
+    /// path by joining its name); populated when an entry can live anywhere in
+    /// the tree, as for search hits rendered through the browser.
+    #[serde(default)]
+    pub path: String,
+}
+
+/// One hit in a [`Request::Search`] result. Like [`DirEntry`] but carries the
+/// full mountpoint-relative `path` (a hit can live anywhere in the tree), so the
+/// front-end can navigate to or open it directly.
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct SearchHit {
+    pub name: String,
+    /// Mountpoint-relative path (`/`-joined, no leading slash).
+    pub path: String,
+    pub is_dir: bool,
+    pub size: u64,
+    pub modified: i64,
+    pub pinned: bool,
+    /// Node uid in `volume~link` form.
+    pub uid: String,
 }

 /// One photo in a [`Request::PhotosTimeline`] page.
@@ -85,11 +148,19 @@ pub struct PhotoItem {
 /// The daemon's reply to a [`Request`].
 #[derive(Serialize, Deserialize, Debug)]
 pub enum Response {
-    /// Current mount status.
+    /// Current mount status. Carries the cache stats the daemon already holds
+    /// (`used`/`budget` bytes and the pin list) so a front-end never has to open
+    /// the on-disk cache itself on its UI thread.
    Status {
        username: String,
        mountpoint: String,
        pinned: usize,
+        /// Bytes of cached content blobs (see [`crate::cache::ContentCache::usage`]).
+        used: u64,
+        /// Configured soft byte cap (`0` = unlimited).
+        budget: u64,
+        /// The pin registry.
+        pins: Vec<Pin>,
    },
    /// A human-readable success message.
    Ok { message: String },
@@ -99,9 +170,14 @@ pub enum Response {
    Entries { entries: Vec<DirEntry> },
    /// A page of the photos timeline. `available` is false when the account
    /// has no photos volume.
-    Photos { available: bool, items: Vec<PhotoItem> },
+    Photos {
+        available: bool,
+        items: Vec<PhotoItem>,
+    },
    /// An on-disk path the front-end can open (e.g. a downloaded photo).
    FilePath { path: String },
+    /// Full-text search results (reply to [`Request::Search`]).
+    SearchResults { hits: Vec<SearchHit> },
    /// The request failed.
    Error { message: String },
 }
@@ -123,3 +199,43 @@ pub fn send(socket: &Path, req: &Request) -> Result<Response> {
    reader.read_line(&mut resp)?;
    Ok(serde_json::from_str(resp.trim())?)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The mutation requests must survive a line-delimited JSON round-trip, since
+    /// that is exactly how they cross the control socket.
+    #[test]
+    fn mutation_requests_roundtrip() {
+        let reqs = [
+            Request::Rename {
+                path: "a/b.txt".into(),
+                new_name: "c.txt".into(),
+            },
+            Request::Move {
+                path: "a/b.txt".into(),
+                new_parent: "d".into(),
+            },
+            Request::Delete {
+                path: "a/b.txt".into(),
+            },
+            Request::CreateFolder {
+                parent: "a".into(),
+                name: "new".into(),
+            },
+            Request::UploadFile {
+                parent: "a".into(),
+                name: "f.bin".into(),
+                bytes: vec![0, 1, 2, 255],
+            },
+        ];
+        for req in reqs {
+            let line = serde_json::to_string(&req).unwrap();
+            assert!(!line.contains('\n'), "wire form must be a single line");
+            let back: Request = serde_json::from_str(&line).unwrap();
+            // Round-trip is lossless: re-serializing yields the same bytes.
+            assert_eq!(line, serde_json::to_string(&back).unwrap());
+        }
+    }
+}
@@ -16,6 +16,9 @@ pub enum Error {
    #[error("io: {0}")]
    Io(#[from] std::io::Error),

+    #[error("database: {0}")]
+    Db(#[from] rusqlite::Error),
+
    /// No persisted session found — caller must run an interactive login.
    #[error("not logged in (no saved session)")]
    NotLoggedIn,
@@ -6,7 +6,9 @@ pub mod auth;
 pub mod cache;
 pub mod config;
 pub mod control;
+pub mod db;
 pub mod error;
+pub mod service;

 pub use error::{Error, Result};

@@ -0,0 +1,106 @@
+//! Thin wrappers over `systemctl --user` for the auto-mount daemon.
+//!
+//! The mount is owned by a systemd *user* service (`proton-drive.service`, see
+//! `packaging/`). Front-ends never spawn `pdfs mount` directly anymore: logging
+//! in enables+starts the unit, logging out disables+stops it, and the tray's
+//! "Disconnect" just stops it. systemd then handles restart-on-failure and a
+//! clean SIGTERM stop (which the daemon turns into a lazy unmount).
+//!
+//! Every call is best-effort: a failure is logged but not fatal, since the user
+//! can always drive `systemctl --user` by hand.
+
+use std::process::{Command, Stdio};
+
+/// The systemd user unit that runs `pdfs daemon`.
+pub const SERVICE: &str = "proton-drive.service";
+
+/// Run one `systemctl --user <args> proton-drive.service`, returning whether it
+/// succeeded. Output is suppressed; failures are logged.
+fn systemctl(args: &[&str]) -> bool {
+    let ok = Command::new("systemctl")
+        .arg("--user")
+        .args(args)
+        .arg(SERVICE)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false);
+    if !ok {
+        tracing::warn!(args = ?args, "systemctl --user {SERVICE} failed");
+    }
+    ok
+}
+
+/// Like [`systemctl`] but treats a non-zero exit as a plain `false` answer
+/// rather than a failure to log. For query verbs (`is-active`, `is-failed`)
+/// where "no" is the normal, expected result.
+fn systemctl_query(args: &[&str]) -> bool {
+    Command::new("systemctl")
+        .arg("--user")
+        .args(args)
+        .arg(SERVICE)
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+/// Enable the service so it survives reboots/logins and start it now. Called on
+/// successful login.
+pub fn enable_start() -> bool {
+    systemctl(&["enable", "--now"])
+}
+
+/// Stop the running mount without disabling it. Called by the tray's
+/// "Disconnect": the next login (or reboot) brings it back.
+pub fn stop() -> bool {
+    systemctl(&["stop"])
+}
+
+/// Restart the unit now. Used by a front-end "Retry" action when the mount has
+/// failed and the user wants to bring it back without re-logging-in.
+pub fn restart() -> bool {
+    systemctl(&["restart"])
+}
+
+/// Whether the unit currently reports `active` (running, or starting up).
+/// `systemctl is-active` exits 0 only while the unit is active, so a front-end
+/// can use this to tell "service still coming up" from "service is down".
+pub fn is_active() -> bool {
+    systemctl_query(&["is-active"])
+}
+
+/// Whether the unit is in the `failed` state. `systemctl is-failed` exits 0
+/// only when the unit has failed, letting a front-end show an actionable error
+/// (with Retry) rather than an indefinite "connecting…" spinner.
+pub fn is_failed() -> bool {
+    systemctl_query(&["is-failed"])
+}
+
+/// Whether the unit is enabled to start on login/boot. `systemctl is-enabled`
+/// exits 0 only for an enabled unit, so the Settings page can render the
+/// "Start on login" switch in its true state.
+pub fn is_enabled() -> bool {
+    systemctl_query(&["is-enabled"])
+}
+
+/// Enable the service so it auto-starts on future logins, without necessarily
+/// starting it now beyond what `enable` does. Used by the Settings "Start on
+/// login" switch; pairs with [`disable`](disable).
+pub fn enable() -> bool {
+    systemctl(&["enable"])
+}
+
+/// Disable auto-start without stopping the running mount. Used by the Settings
+/// "Start on login" switch turning off; the current session stays mounted.
+pub fn disable() -> bool {
+    systemctl(&["disable"])
+}
+
+/// Disable the service so it no longer auto-starts, and stop it now. Called on
+/// logout.
+pub fn disable_stop() -> bool {
+    systemctl(&["disable", "--now"])
+}
@@ -19,6 +19,7 @@ use ksni::{MenuItem, Tray, TrayService};
 use pdfs_core::auth;
 use pdfs_core::config::AppDirs;
 use pdfs_core::control::{Request, Response, send};
+use pdfs_core::service;

 /// How often the tray re-polls the daemon to refresh its menu.
 const POLL_INTERVAL: Duration = Duration::from_secs(3);
@@ -42,7 +43,9 @@ struct DriveTray {
 /// menu can still say "Logged in …" / "Not logged in" when no mount is running.
 fn poll_state(socket: &Path, default_mountpoint: &Path) -> DriveState {
    match send(socket, &Request::Status) {
-        Ok(Response::Status { mountpoint, pinned, .. }) => DriveState {
+        Ok(Response::Status {
+            mountpoint, pinned, ..
+        }) => DriveState {
            line: format!("Mounted at {mountpoint} ({pinned} pinned)"),
            mounted: true,
            mountpoint: PathBuf::from(mountpoint),
@@ -69,32 +72,26 @@ fn poll_state(socket: &Path, default_mountpoint: &Path) -> DriveState {
    }
 }

-/// Launch `pdfs mount` detached so the tray keeps running independently.
-fn spawn_mount() {
-    match Command::new("pdfs").arg("mount").spawn() {
-        Ok(_) => tracing::info!("spawned `pdfs mount`"),
-        Err(e) => tracing::error!("failed to spawn `pdfs mount`: {e}"),
-    }
-}
-
-/// Unmount the FUSE filesystem. `fusermount3 -u` is the FUSE-native teardown;
-/// fall back to `fusermount` on older systems.
-fn unmount(mountpoint: &Path) {
-    let try_unmount = |bin: &str| Command::new(bin).arg("-u").arg(mountpoint).status();
-    let result = try_unmount("fusermount3").or_else(|_| try_unmount("fusermount"));
-    match result {
-        Ok(s) if s.success() => tracing::info!("unmounted {}", mountpoint.display()),
-        Ok(s) => tracing::error!("unmount exited with {s}"),
-        Err(e) => tracing::error!("failed to run fusermount: {e}"),
-    }
-}
-
 fn open_folder(mountpoint: &Path) {
    if let Err(e) = Command::new("xdg-open").arg(mountpoint).spawn() {
        tracing::error!("failed to xdg-open {}: {e}", mountpoint.display());
    }
 }

+/// Launch (or, since it's `SingleMainWindow`, raise) the settings/management
+/// window. The app binary lives next to the tray binary; fall back to the bare
+/// name so a PATH install still works.
+fn open_manager() {
+    let exe = std::env::current_exe()
+        .ok()
+        .and_then(|p| p.parent().map(|d| d.join("pdfs-app")))
+        .filter(|p| p.exists())
+        .unwrap_or_else(|| PathBuf::from("pdfs-app"));
+    if let Err(e) = Command::new(&exe).spawn() {
+        tracing::error!("failed to launch {}: {e}", exe.display());
+    }
+}
+
 impl Tray for DriveTray {
    fn id(&self) -> String {
        "io.narl.proton-drive-linux".into()
@@ -109,9 +106,8 @@ impl Tray for DriveTray {
    }

    fn menu(&self) -> Vec<MenuItem<Self>> {
-        // Values captured into the action closures (which only get `&mut Self`).
-        let mountpoint = self.state.mountpoint.clone();
-        let open_mp = mountpoint.clone();
+        // Value captured into the action closure (which only gets `&mut Self`).
+        let open_mp = self.state.mountpoint.clone();

        let mut items: Vec<MenuItem<Self>> = vec![
            StandardItem {
@@ -121,6 +117,12 @@ impl Tray for DriveTray {
            }
            .into(),
            MenuItem::Separator,
+            StandardItem {
+                label: "Open Manager".into(),
+                activate: Box::new(|_: &mut Self| open_manager()),
+                ..Default::default()
+            }
+            .into(),
        ];

        if self.state.mounted {
@@ -132,25 +134,28 @@ impl Tray for DriveTray {
                }
                .into(),
            );
+            // Stop the systemd service (clean SIGTERM → lazy unmount). The next
+            // login or reboot brings it back; this is a deliberate disconnect.
            items.push(
                StandardItem {
-                    label: "Unmount".into(),
+                    label: "Disconnect".into(),
                    activate: Box::new(move |this: &mut Self| {
-                        unmount(&mountpoint);
+                        service::stop();
                        this.state.mounted = false;
-                        this.state.line = "Unmounting…".into();
+                        this.state.line = "Disconnecting…".into();
                    }),
                    ..Default::default()
                }
                .into(),
            );
        } else {
+            // Enable+start the service so it mounts now and on future logins.
            items.push(
                StandardItem {
-                    label: "Mount".into(),
+                    label: "Connect".into(),
                    activate: Box::new(|this: &mut Self| {
-                        spawn_mount();
-                        this.state.line = "Mounting…".into();
+                        service::enable_start();
+                        this.state.line = "Connecting…".into();
                    }),
                    ..Default::default()
                }
@@ -174,12 +179,22 @@ impl Tray for DriveTray {
 fn main() -> Result<()> {
    tracing_subscriber::fmt()
        .with_env_filter(
-            tracing_subscriber::EnvFilter::try_from_default_env()
-                .unwrap_or_else(|_| "info".into()),
+            tracing_subscriber::EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()),
        )
        .init();

    let dirs = AppDirs::new().context("resolve app dirs")?;
+
+    // Ensure only one instance of the tray runs.
+    let tray_sock = dirs.tray_socket();
+    if std::os::unix::net::UnixStream::connect(&tray_sock).is_ok() {
+        tracing::info!("Another instance of pdfs-tray is already running; exiting.");
+        return Ok(());
+    }
+    let _ = std::fs::remove_file(&tray_sock);
+    let _lock_socket = std::os::unix::net::UnixListener::bind(&tray_sock)
+        .context("failed to bind tray single-instance socket")?;
+
    let socket = dirs.control_socket();
    let default_mountpoint = dirs.default_mountpoint();

@@ -8,7 +8,7 @@
 # Build + install:   cd packaging && makepkg -fi

 pkgname=proton-drive-linux
-pkgver=0.1.0
+pkgver=0.2.1
 pkgrel=1
 pkgdesc="Proton Drive client for Linux: FUSE files-on-demand mount, CLI, GTK4 app + tray"
 arch=('x86_64')
@@ -20,7 +20,7 @@ provides=('pdfs')
 # Files-on-demand mount + keyring need these at runtime.
 optdepends=('gnome-keyring: credential storage via Secret Service'
            'xdg-utils: "Open folder" action from the tray')
-options=('!lto')
+options=('!lto' '!debug')

 # Built in place from the checkout; nothing to fetch or checksum.
 source=()
@@ -56,8 +56,15 @@ package() {

  install -Dm644 "packaging/io.narl.proton-drive-linux.desktop" \
    "$pkgdir/usr/share/applications/io.narl.proton-drive-linux.desktop"
+  install -Dm644 "packaging/io.narl.proton-drive-linux-tray.desktop" \
+    "$pkgdir/etc/xdg/autostart/io.narl.proton-drive-linux-tray.desktop"
  install -Dm644 "packaging/io.narl.proton-drive-linux.svg" \
    "$pkgdir/usr/share/icons/hicolor/scalable/apps/io.narl.proton-drive-linux.svg"

+  # systemd user service that runs the auto-mount daemon. Enabled per-user by
+  # the GUI on login (`systemctl --user enable --now proton-drive.service`).
+  install -Dm644 "packaging/proton-drive.service" \
+    "$pkgdir/usr/lib/systemd/user/proton-drive.service"
+
  install -Dm644 "LICENSE" "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
 }
@@ -0,0 +1,11 @@
+[Desktop Entry]
+Type=Application
+Name=Proton Drive (Tray)
+GenericName=Cloud Drive Tray
+Comment=Proton Drive system tray icon
+Exec=pdfs-tray
+Icon=io.narl.proton-drive-linux
+Terminal=false
+Categories=Network;FileTransfer;GTK;
+Keywords=proton;drive;cloud;sync;storage;
+NoDisplay=true
@@ -10,5 +10,5 @@
  <!-- cloud -->
  <path fill="#ffffff" d="M44 84c-11 0-20-9-20-20 0-10 7-18 17-20 3-11 13-19 25-19 13 0 24 10 26 23 9 1 16 9 16 18 0 10-8 18-18 18z"/>
  <!-- down arrow (on-demand pull) -->
-  <path fill="#6d4aff" d="M64 50v22m0 0l-9-9m9 9l9-9" stroke="#6d4aff" stroke-width="7" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  <path d="M64 50v22m0 0l-9-9m9 9l9-9" stroke="#6d4aff" stroke-width="7" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
 </svg>
@@ -0,0 +1,19 @@
+[Unit]
+Description=Proton Drive Files-On-Demand mount
+Documentation=https://github.com/narl/proton-drive-linux
+# Tie the mount to the desktop session: start after it is up and stop with it.
+After=graphical-session.target
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+# The daemon waits for a stored login, mounts ~/ProtonDrive, and keeps it
+# mounted. SIGTERM (from `systemctl --user stop`) triggers a clean lazy unmount.
+ExecStart=/usr/bin/pdfs daemon
+Restart=on-failure
+RestartSec=3
+# Give the lazy unmount time to finish before SIGKILL.
+TimeoutStopSec=15
+
+[Install]
+WantedBy=default.target
Author	SHA1	Message	Date
nvrl	d77d7ed817	version bump for sdk	2026-06-30 21:11:21 +02:00
nvrl	56f2b35aca	version bump to 0.2.2	2026-06-30 18:39:11 +02:00
nvrl	56abe3fe14	added settings + non blocking ui actions	2026-06-30 18:38:38 +02:00
nvrl	5e71148fec	version bump 0.2.1	2026-06-30 17:42:38 +02:00
nvrl	2812e0c893	clippy + pkgbuild	2026-06-30 17:41:52 +02:00
nvrl	03dd8d8496	implemented database for search	2026-06-30 17:35:18 +02:00
nvrl	5e151bbfc5	updated readme	2026-06-30 06:31:51 +02:00
nvrl	172ec4b0b7	version 0.2.0	2026-06-30 06:23:36 +02:00
nvrl	ec4f5ea32f	fmt	2026-06-30 06:23:00 +02:00
nvrl	81a0ecce54	added block cache	2026-06-30 06:22:40 +02:00
nvrl	cc2f370670	lazy 2fa	2026-06-30 06:01:36 +02:00
nvrl	b3e8e8ab96	performance fixes	2026-06-30 05:56:21 +02:00
nvrl	8e8d42ad3b	updated ux	2026-06-30 05:50:20 +02:00
nvrl	99e80a7206	implemented robust fuse mount	2026-06-30 05:43:14 +02:00
nvrl	ca30dceae7	version bump to 0.1.2	2026-06-30 05:00:51 +02:00
nvrl	13d45ce6f5	clippy	2026-06-30 04:59:15 +02:00
nvrl	f31633cb3a	fmt	2026-06-30 04:58:40 +02:00
nvrl	86fa8aef03	updated app name + fixed missing icon in pkgbuild	2026-06-30 04:58:03 +02:00
nvrl	aa70077ad0	added images	2026-06-30 04:07:19 +02:00
nvrl	11af393633	removed .AppImage	2026-06-30 03:52:06 +02:00