Add Beat Saber data backup command

README.md

@@ -1,6 +1,6 @@
 # plugin-helper
 
-`plugin-helper` is an early Python CLI for managing Beat Saber plugins in a mounted Windows BSManager install.
+`plugin-helper` is an early Python CLI for managing Beat Saber plugins in BSManager installs.
 
 The first implementation focuses on safe local workflows:
 
@@ -11,28 +11,97 @@ The first implementation focuses on safe local workflows:
 - apply exactly that plan and record install state
 - uninstall only files recorded in install state
 
-Default BSManager instance root:
+Default BSManager instance roots:
 
 ```text
 /home/pleb/Windows/Users/pleb/BSManager/BSInstances
+/home/pleb/.local/share/BSManager/BSInstances
 ```
 
-Override with `--instances-root` or `PLUGIN_HELPER_INSTANCES_ROOT`.
+Override with `--instances-root` or `PLUGIN_HELPER_INSTANCES_ROOT`. To search
+multiple explicit roots, separate them with `:`.
 
 ## Commands
 
-Run from the repo root with `PYTHONPATH=src` unless installed.
+For normal use, run the menu from the repo root. Use repo-local state so the
+menu sees the same plans, downloads, and install records used by the helper
+workflow:
 
 ```sh
-PYTHONPATH=src python -m plugin_helper instances
-PYTHONPATH=src python -m plugin_helper --state-dir .state installed --instance 1.40.8
-PYTHONPATH=src python -m plugin_helper updates --instance 1.40.8
-PYTHONPATH=src python -m plugin_helper scan --instance 1.40.8
-PYTHONPATH=src python -m plugin_helper --state-dir .state plan --instance 1.40.8
+PYTHONPATH=src python -m plugin_helper --state-dir .state menu
 ```
 
+The individual subcommands are mostly for automation and debugging. If you use
+them, pass `--state-dir .state` unless you intentionally want the default live
+state outside this repo.
+
 Install assets are currently expected to already exist locally, usually under:
 
 ```text
 .state/instances/<instance>/downloads/<plugin-id>/
 ```
+
+## Beat Saber Data Backups
+
+`backup-userdata` copies the mounted Windows `UserData` folder and Beat Saber
+Windows app data into this repo. With the Windows mount at `~/Windows`, the
+helper infers Beat Saber's Windows app data as:
+
+```text
+/home/pleb/Windows/Users/pleb/AppData/LocalLow/Hyperbolic Magnetism/Beat Saber
+```
+
+Example manual backup after mounting Windows:
+
+```sh
+PYTHONPATH=src python -m plugin_helper \
+  --instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances \
+  backup-userdata \
+  --instance 1.44.1
+```
+
+By default the repo receives plain copied files under `backups/beat-saber/UserData`
+and `backups/beat-saber/AppData`, plus `backups/beat-saber/backup-descriptor.json`
+describing the source paths from the latest backup run. Use
+`--appdata-path <path>` if the Windows profile path ever differs, `--no-appdata`
+for a `UserData`-only sync, or `--backup-root <path>` to choose a different
+repo-local destination.
+
+The backup intentionally omits bulky/generated data:
+
+- `UserData/BeatLeader/Replays`
+- `UserData/BeatLeader/ReplayerCache`
+- `UserData/BeatLeader/LeaderboardsCache`
+- `UserData/BeatLeader/ReplayHeadersCache`
+- `UserData/ScoreSaber/Replays`
+- `UserData/BeatSaberPlus/Cache`
+- `UserData/BeatSaverNotifier.json`
+- `UserData/Accsaber/PlayerScoreCache.json`
+- `UserData/NalulunaAvatars/cache`
+- `UserData/SongDetailsCache.proto`
+- `AppData/com.unity.addressables`
+- `*.log`
+
+Other large folders seen in the 1.44.1 `UserData` tree are
+`Custom Campaigns`, `SongCore`, `AssetBundleLoadingTools`, `NalulunaMenu`, and
+`NalulunaSkybox`. Those are not skipped by default because they can contain
+custom content or non-obvious user choices rather than pure cache data.
+
+## Operational notes
+
+- BSManager can inherit launch arguments configured in Steam for Beat Saber.
+  Check both places before debugging black screens or startup hangs. Duplicating
+  arguments such as `--no-yeet fpfc` can make the game fail command-line
+  parsing after BSIPA and plugins have already loaded.
+- BSIPA is managed as a first-class bootstrap phase. The `bootstrap` command
+  applies the locked `bsipa` root archive, runs `IPA.exe -n` through Proton, and
+  records every bootstrap-relevant file under root `IPA.exe*`, `winhttp.dll`,
+  `Libs/`, and `IPA/`, including backups created during patching.
+- If an instance lockfile includes `bsipa`, ordinary plugin plans require a
+  recorded bootstrap state plus a `Logs/_latest.log` that shows BSIPA startup.
+  Use `bootstrap-check` before planning a batch when you want a quick gate.
+- Use [`docs/SMOKETEST.md`](docs/SMOKETEST.md) after installing or removing a
+  plugin batch. It documents the short Proton/BSManager launch loop, IPA log
+  checks, and teardown commands.
+- The 1.44.1 migration tracker lives in
+  [`docs/notes/install-and-verify-plugins-1.44.1.md`](docs/notes/install-and-verify-plugins-1.44.1.md).