driftwood/docs/USER-GUIDE.md

# Driftwood User Guide

## Getting started

### Installation

**From source:**
```sh
cargo build --release
sudo install -Dm755 target/release/driftwood /usr/local/bin/driftwood
```

**Arch Linux (AUR):**
```sh
yay -S driftwood
```

**Flatpak:**
```sh
flatpak install app.driftwood.Driftwood
```

### First launch

When you first open Driftwood, you'll see an empty state with two options:

- **Scan Now** - Immediately scan the default directories (`~/Applications` and
  `~/Downloads`) for AppImage files
- **Preferences** - Configure which directories to scan and other settings

Driftwood will discover all AppImage files (both Type 1 and Type 2) in your
configured directories and add them to its library.

## Library view

The main screen shows all your discovered AppImages in either grid or list mode.
Toggle between views with the button in the header bar.

### Status badges

Each AppImage card shows colored badges indicating:

- **Wayland status** - Green (native), yellow (XWayland), red (X11 only)
- **FUSE status** - Green (native FUSE), yellow (extract-and-run), red (cannot launch)
- **Update available** - Blue badge when a newer version is detected
- **Security** - Red badge if known vulnerabilities are found

### Searching

Use the search bar to filter AppImages by name or file path. The search is
debounced - it waits 150ms after you stop typing before filtering.

### Keyboard shortcuts

- **Ctrl+Q** - Quit
- **Ctrl+D** - Open dashboard
- **Ctrl+U** - Check for updates

## Detail view

Click any AppImage card to see its full detail page. The detail view has
these sections:

### Identity
App name, version, developer, description, and categories extracted from
the AppImage's embedded .desktop file.

### Desktop integration
Shows whether the AppImage is integrated into your desktop menu. You can
integrate or remove integration from here.

### Runtime compatibility
FUSE status (how the AppImage can be mounted) and Wayland compatibility
(whether the app supports Wayland natively or needs XWayland).

### Sandboxing
Toggle Firejail sandboxing for this AppImage. When enabled, the app
launches inside a Firejail container with `--appimage` flag. Requires
firejail to be installed.

### Updates
Shows the update type (GitHub Releases, GitLab, zsync), current and latest
versions, and lets you check for and apply updates.

### Usage
Launch count and last launched date.

### Security
Results of CVE scanning against bundled libraries. Shows counts by severity
(critical, high, medium, low).

### Disk footprint
Config, data, and cache directories associated with this AppImage. Shows
estimated size and discovery confidence.

### File details
File path, size, SHA256 hash, AppImage type, architecture, and timestamps.

## Scanning

### Automatic scanning
By default, Driftwood scans on startup. Disable this in Preferences under
Behavior > "Scan on startup".

### Manual scanning
Use the "Scan for AppImages" option in the hamburger menu or run:
```sh
driftwood scan
```

### Scan optimization
On subsequent scans, Driftwood skips files that haven't changed (same size
and modification time) and already have all analysis complete. This makes
re-scans much faster.

### Adding scan directories
Go to Preferences > General > Scan Locations to add or remove directories.
Subdirectories are not scanned recursively.

## Desktop integration

Driftwood creates standard .desktop files in `~/.local/share/applications/`
with the prefix `driftwood-`. Icons are installed to
`~/.local/share/icons/hicolor/`.

To integrate an AppImage:
1. Open its detail view
2. Click "Integrate" in the Desktop Integration section
3. Confirm in the integration dialog

To remove integration:
1. Open its detail view
2. Click "Remove Integration"

## Updates

### Checking for updates
- Single app: Open detail view and click "Check for Updates"
- All apps: Use the hamburger menu "Check for Updates" or `driftwood check-updates`

### Applying updates
When an update is available, click "Update Now" in the update dialog. Driftwood
downloads the new version and replaces the old file.

### Old version cleanup
After a successful update, Driftwood handles the old version based on your
preference (Preferences > Behavior > "After updating an AppImage"):

- **Ask each time** (default) - Shows a dialog asking whether to remove the backup
- **Remove old version** - Automatically deletes the backup
- **Keep backup** - Saves the old version with a `.old` extension

## Security scanning

Driftwood extracts the list of shared libraries (.so files) bundled inside each
AppImage and queries the OSV.dev vulnerability database for known CVEs.

### Running a scan
- Single app: Open detail view and click "Run Security Scan"
- All apps: `driftwood security`
- Single app CLI: `driftwood security ~/path/to/app.AppImage`

### Interpreting results
Results show CVE IDs grouped by severity. Each CVE includes:
- CVE identifier and severity level
- CVSS score (if available)
- Summary of the vulnerability
- Affected library and version
- Fixed version (if known)

### Limitations
- Not all bundled libraries can be identified
- Version detection uses heuristics and may be inaccurate
- Results should be treated as advisory, not definitive

## Duplicate detection

Driftwood detects:
- **Same app, different versions** - Multiple version files of the same application
- **Identical files** - Same SHA256 hash in different locations

Access via the hamburger menu "Find Duplicates" or `driftwood duplicates`.

## Disk cleanup

The cleanup wizard (hamburger menu > "Disk Cleanup") helps reclaim space by:
- Identifying orphaned desktop entries for deleted AppImages
- Finding associated config/data/cache directories
- Showing total reclaimable space

## Orphaned entries

When an AppImage is deleted outside of Driftwood, its .desktop file and icon
remain. Driftwood detects these orphans and offers to clean them up.

- Automatic detection on the dashboard
- Manual cleanup via hamburger menu or `driftwood clean-orphans`

## Dashboard

The dashboard (Ctrl+D or hamburger menu) shows system health:
- FUSE availability (fuse2, fuse3, or none)
- Wayland session information
- Total disk usage by AppImages
- Orphaned entry count
- Security alert summary

## CLI reference

```
driftwood                      # Launch the GUI
driftwood scan                 # Scan for AppImages
driftwood list                 # List all AppImages (table format)
driftwood list --format json   # List as JSON
driftwood inspect <path>       # Show AppImage metadata
driftwood integrate <path>     # Create .desktop file and icon
driftwood remove <path>        # Remove desktop integration
driftwood launch <path>        # Launch with tracking
driftwood launch --sandbox <path>  # Launch in Firejail
driftwood check-updates        # Check all for updates
driftwood duplicates           # Find duplicates
driftwood security             # Scan all for CVEs
driftwood security <path>      # Scan one for CVEs
driftwood footprint <path>     # Show disk footprint
driftwood status               # Show system status
driftwood clean-orphans        # Remove orphaned entries
```

## Preferences

Access via hamburger menu > Preferences.

### General
- **Color Scheme** - Follow system, light, or dark
- **Default View** - Grid or list
- **Scan Locations** - Directories to scan

### Behavior
- **Scan on startup** - Auto-scan when the app opens
- **Check for updates** - Periodically check for newer versions
- **Auto-integrate new AppImages** - Automatically create .desktop files
- **Confirm before delete** - Show confirmation dialogs
- **After updating** - Old version cleanup policy (ask/always/never)

### Security
- **Auto-scan new AppImages** - Run CVE scan on newly discovered AppImages