Add reset scripts and setup docs

Author: RadNotRed

README.md

@@ -17,6 +17,7 @@ USB Mirror Sync is a cross-platform tray app for keeping selected folders from a
 - GitHub Pages docs: `https://radnotred.github.io/USBFileSync/`
 - Local docs source: [`docs/`](docs/)
 - Example config: [`config.example.json`](config.example.json)
+- Reset and cleanup tools: [`tools/reset/`](tools/reset/)
 - Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
 
 ## Install
@@ -36,19 +37,27 @@ Release artifacts are produced automatically from the version in `Cargo.toml` fo
 
 Windows keeps the installer with optional desktop shortcut creation and optional run-at-startup registration. Startup is off by default. macOS now ships a drag-to-Applications `.dmg` plus a raw archive fallback. Linux ships per-architecture archives.
 
-## Runtime Files
+## First Launch
 
-On first launch the app creates:
+Use the native `Setup Wizard` from the tray menu for guided setup, or edit `config.json` directly.
 
-- `%LOCALAPPDATA%\UsbMirrorSync\config.json`
-- `%LOCALAPPDATA%\UsbMirrorSync\manifest.json`
-- `%LOCALAPPDATA%\UsbMirrorSync\shadow\`
-- `%LOCALAPPDATA%\UsbMirrorSync\sync.log`
+Basic setup:
 
-Use the tray menu `Setup Wizard` action for guided configuration, or edit `config.json` directly.
+- Windows: install or unzip the release, launch the app, then set `drive.letter`
+- macOS: open the `.dmg`, drag the app to `Applications`, launch it, then set `drive.path`
+- Linux: extract the archive, launch the binary, then set `drive.path`
 
 On Windows, set `drive.letter`. On macOS and Linux, set `drive.path` to the mounted USB root.
 
+The app creates a per-user data directory containing:
+
+- `config.json`
+- `manifest.json`
+- `shadow/`
+- `sync.log`
+
+Use the tray actions to open the config, log, app-data folder, mounted drive, or shadow cache.
+
 ## Development
 
 ```powershell

docs/contributing.md

@@ -1,10 +1,10 @@
 # Contributing
 
-USB Mirror Sync is a Windows-first utility with file movement, caching, packaging, and tray UX all tied together. Keep changes scoped and document behavior changes in the same patch.
+USB Mirror Sync is a cross-platform utility with file movement, caching, packaging, and tray UX all tied together. Keep changes scoped and document behavior changes in the same patch.
 
 ## Quick Checklist
 
-- Keep Windows behavior explicit
+- Keep platform-specific behavior explicit
 - Preserve the documented sync model unless you are intentionally changing it
 - Add or update tests when sync logic changes
 - Update the docs when config fields, workflows, packaging, or tray behavior change
@@ -22,5 +22,6 @@ python -m mkdocs build --strict
 
 - `src/sync_engine.rs`: sync direction, delete semantics, manifest handling
 - `src/app.rs`: tray behavior, status, startup flow, config recovery
-- `assets/setup_wizard.ps1`: user-facing setup experience
+- `src/wizard.rs`: cross-platform setup experience
 - `.github/workflows/`: release and documentation automation
+- `tools/reset/`: local cleanup and reset behavior

docs/getting-started.md

@@ -2,21 +2,30 @@
 
 ## Choose a Release
 
-USB Mirror Sync ships in two Windows-friendly forms:
+USB Mirror Sync ships in platform-specific forms:
 
-- Portable zip: unzip and run `usb_mirror_sync.exe`
-- Installer: installs the app, Start Menu entry, optional desktop shortcut, and optional startup registration
+- Windows: portable zip or installer
+- macOS: `.dmg` plus a `.tar.gz` fallback
+- Linux: per-architecture `.tar.gz`
 
-Startup is disabled by default in the installer.
+Startup is disabled by default in the Windows installer.
 
 ## First Launch
 
-On first launch the app creates:
+1. Launch the app.
+2. Open `Setup Wizard` from the tray/menu bar icon.
+3. Point the app at the USB source:
+   - Windows: set `drive.letter`
+   - macOS/Linux: set `drive.path`
+4. Add at least one job mapping a USB-relative `source` to an absolute local `target`.
+5. Save the config and leave the app running in the tray.
 
-- `%LOCALAPPDATA%\UsbMirrorSync\config.json`
-- `%LOCALAPPDATA%\UsbMirrorSync\manifest.json`
-- `%LOCALAPPDATA%\UsbMirrorSync\shadow\`
-- `%LOCALAPPDATA%\UsbMirrorSync\sync.log`
+On first launch the app creates a per-user data directory with:
+
+- `config.json`
+- `manifest.json`
+- `shadow/`
+- `sync.log`
 
 If the config is missing or invalid, the app can open the Setup Wizard automatically and recover to a safe default config.
 
@@ -69,8 +78,20 @@ Tray actions include:
 - `Sync to USB now`
 - `Eject drive`
 - `Setup Wizard`
+- `Open mounted drive`
+- `Open shadow cache`
 - `Open raw config`
 - `Open log`
 - `Open app folder`
 
 If a second copy of the app is launched, the single-instance guard shows a warning and lets you cancel or retry startup.
+
+## Clean Reset
+
+If you want to wipe local app state and start fresh, use the scripts in `tools/reset/`:
+
+- `tools/reset/reset-windows.bat`
+- `tools/reset/reset-macos.sh`
+- `tools/reset/reset-linux.sh`
+
+These are intended to remove the app's per-user config, manifest, logs, and shadow cache. They are for local state cleanup, not for uninstalling release artifacts.

docs/index.md

@@ -1,6 +1,6 @@
 # USB Mirror Sync
 
-USB Mirror Sync is a Windows tray app built for one job: keep selected folders from a removable USB drive mirrored onto a PC without forcing a full copy every time the drive is plugged in.
+USB Mirror Sync is a cross-platform tray app built for one job: keep selected folders from a removable USB drive mirrored onto a PC without forcing a full copy every time the drive is plugged in.
 
 <div class="grid cards" markdown>
 
@@ -20,12 +20,15 @@ USB Mirror Sync is a Windows tray app built for one job: keep selected folders f
 
     Sync, open logs, edit config, launch the setup wizard, and eject the drive directly from the taskbar icon.
 
+-   ### Reset When Needed
+
+    Platform-specific cleanup scripts in `tools/reset/` can wipe app data and cached state when you need a clean start.
+
 </div>
 
 ## Core Ideas
 
-- The app is Windows-only.
-- Jobs are tied to a configured USB drive letter.
+- Windows can use a USB drive letter; macOS and Linux use a mounted drive path.
 - `source` paths are relative to the USB root.
 - `target` paths are absolute folders on the PC.
 - `shadow` is a staging cache, not the live destination folder.
@@ -35,4 +38,5 @@ USB Mirror Sync is a Windows tray app built for one job: keep selected folders f
 - New user: [Getting Started](getting-started.md)
 - Need to hand-edit JSON: [Configuration](configuration.md)
 - Want to understand cache behavior and delete rules: [How Sync Works](sync-model.md)
+- Need to wipe config/cache state: [Reset and Cleanup](reset-and-cleanup.md)
 - Working on the repo: [Contributing](contributing.md)

docs/reset-and-cleanup.md

@@ -0,0 +1,51 @@
+# Reset and Cleanup
+
+USB Mirror Sync stores local state so it can stay incremental between runs. Sometimes that is exactly what you want to remove: a broken config, stale manifest, or shadow cache you no longer trust.
+
+## Reset Scripts
+
+The repo provides platform-specific cleanup scripts under `tools/reset/`:
+
+- `tools/reset/reset-windows.bat`
+- `tools/reset/reset-macos.sh`
+- `tools/reset/reset-linux.sh`
+
+These scripts are intended to remove the app's per-user state, including:
+
+- `config.json`
+- `manifest.json`
+- `sync.log`
+- `shadow/`
+
+They are for local cleanup. They are not meant to uninstall packaged binaries or remove release artifacts from system install locations.
+
+## When to Use Them
+
+Use a reset script when:
+
+- the config was badly broken and you want to start fresh
+- you want to discard the cached manifest and shadow copy
+- you are testing a first-run experience
+- you want to verify behavior without any retained local state
+
+## Safer First Steps
+
+Before wiping everything:
+
+- use the tray action `Open raw config`
+- use the tray action `Open log`
+- use the tray action `Open app folder`
+- back up `config.json` if you care about your current job setup
+
+## After a Reset
+
+After local state is removed:
+
+1. Launch the app again.
+2. Open `Setup Wizard`.
+3. Recreate the drive setting:
+   - Windows: `drive.letter`
+   - macOS/Linux: `drive.path`
+4. Recreate your jobs and save.
+
+The app will then build fresh local state on the next sync.

docs/tray-app.md

@@ -2,14 +2,16 @@
 
 ## Tray Menu
 
-The app lives in the Windows notification area and exposes the main workflow through the tray menu.
+The app lives in the system tray or menu bar area and exposes the main workflow through the tray menu.
 
 Typical actions:
 
 - `Sync from USB now`
 - `Sync to USB now`
 - `Eject drive`
 - `Setup Wizard`
+- `Open mounted drive`
+- `Open shadow cache`
 - `Open raw config`
 - `Open log`
 - `Open app folder`
@@ -30,16 +32,15 @@ This keeps the tray UI compact without losing visibility into what is happening.
 
 ## Setup Wizard
 
-The setup wizard is a Windows PowerShell + WinForms UI that helps edit `config.json` without hand-editing JSON.
+The setup wizard is a Rust desktop UI that helps edit `config.json` without hand-editing JSON.
 
 It includes:
 
-- Overview, Jobs, and Advanced tabs
-- job grid editing
+- cross-platform drive and mount-path setup
+- job list editing
 - path browse actions
-- workflow explanations
-- hover tooltips
 - config recovery context when a broken config is repaired
+- save and save-and-close flows
 
 ## Single-Instance Protection
 

docs/troubleshooting.md

@@ -27,6 +27,10 @@ Only one instance is allowed. Starting a second copy shows an `Already running`
 
 ## Where to Look for Logs
 
-Use the tray action `Open log`, or inspect:
+Use the tray action `Open log` or `Open app folder` first. If you want a full clean slate, use the reset scripts in `tools/reset/`.
 
-`%LOCALAPPDATA%\UsbMirrorSync\sync.log`
+The reset tools are:
+
+- `tools/reset/reset-windows.bat`
+- `tools/reset/reset-macos.sh`
+- `tools/reset/reset-linux.sh`

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: USB Mirror Sync
-site_description: Windows tray app for mirroring USB folders onto a PC with a shadow cache, tray controls, and installer or portable releases.
+site_description: Cross-platform tray app for mirroring USB folders onto a PC with a shadow cache, tray controls, reset tools, and packaged releases.
 site_url: https://radnotred.github.io/USBFileSync/
 repo_url: https://github.com/RadNotRed/USBFileSync
 repo_name: RadNotRed/USBFileSync
@@ -41,6 +41,7 @@ nav:
   - Configuration: configuration.md
   - How Sync Works: sync-model.md
   - Tray App: tray-app.md
+  - Reset and Cleanup: reset-and-cleanup.md
   - Installer and Releases: installer-and-releases.md
   - Release Artifacts: releases.md
   - Troubleshooting: troubleshooting.md

tools/reset/README.md

@@ -0,0 +1,32 @@
+# Reset Tools
+
+These scripts remove USB Mirror Sync's local app state from the current user account.
+
+They are intended for:
+
+- clearing broken config or cache state
+- removing tray auto-start shortcuts
+- resetting the app to a first-run state
+
+They do not remove:
+
+- your synced target folders
+- files on the USB drive
+- the installed application binaries themselves
+
+Scripts:
+
+- `reset-windows.bat`
+- `reset-macos.sh`
+- `reset-linux.sh`
+
+Each script removes local app data such as:
+
+- `config.json`
+- `manifest.json`
+- `sync.log`
+- `shadow/`
+- single-instance lock files
+- startup shortcuts or launch entries created for the current user
+
+Run them only when USB Mirror Sync is closed.

tools/reset/reset-linux.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env sh
+set -eu
+
+echo "USB Mirror Sync reset for Linux"
+echo
+echo "This removes local app state for the current user:"
+echo "  - config, manifest, log, shadow cache"
+echo "  - autostart desktop entries if present"
+echo "It does NOT remove synced folders or files on your USB drive."
+echo
+printf "Type RESET to continue: "
+read -r confirm
+if [ "$confirm" != "RESET" ]; then
+  echo "Cancelled."
+  exit 0
+fi
+
+remove_path() {
+  if [ -e "$1" ]; then
+    echo "Removing $1"
+    rm -rf "$1"
+  fi
+}
+
+data_home="${XDG_DATA_HOME:-$HOME/.local/share}"
+config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+
+remove_path "$data_home/rad/UsbMirrorSync"
+remove_path "$config_home/UsbMirrorSync"
+remove_path "$HOME/.config/autostart/usb-mirror-sync.desktop"
+remove_path "$HOME/.config/autostart/USB Mirror Sync.desktop"
+
+echo
+echo "Reset complete."