Add BeatMods parsing and userdata restore

README.md

@@ -21,6 +21,40 @@ Default BSManager instance roots:
 Override with `--instances-root` or `PLUGIN_HELPER_INSTANCES_ROOT`. To search
 multiple explicit roots, separate them with `:`.
 
+## Managing Multiple Installs
+
+The helper is intended to manage both the local Linux BSManager install and the
+mounted Windows install. Lockfiles and registry entries are shared by Beat Saber
+version, but install state is target-specific. When the same instance name
+exists under both roots, such as `1.44.1`, use an explicit `--instances-root`
+and a separate state directory for each target.
+
+Suggested repo-local convention:
+
+```text
+.state/          local Linux BSManager state
+.state-windows/  mounted Windows BSManager state
+```
+
+Examples:
+
+```sh
+PYTHONPATH=src python -m plugin_helper \
+  --instances-root /home/pleb/.local/share/BSManager/BSInstances \
+  --state-dir .state \
+  installed --instance 1.44.1
+
+PYTHONPATH=src python -m plugin_helper \
+  --instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances \
+  --state-dir .state-windows \
+  installed --instance 1.44.1
+```
+
+Do not reuse the same state directory for both targets when their instance names
+match. The current state layout is keyed by instance name, so sharing one state
+directory would mix bootstrap records, generated plans, backups, and installed
+file records for different game trees.
+
 ## Commands
 
 For normal use, run the menu from the repo root. Use repo-local state so the
@@ -33,7 +67,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.
+state outside this repo or are intentionally targeting the Windows install with
+`.state-windows`.
 
 Install assets are currently expected to already exist locally, usually under:
 
@@ -41,6 +76,13 @@ Install assets are currently expected to already exist locally, usually under:
 .state/instances/<instance>/downloads/<plugin-id>/
 ```
 
+For a second target-specific state directory, copy or re-download the same
+locked assets under that state root before planning. For example:
+
+```text
+.state-windows/instances/<instance>/downloads/<plugin-id>/
+```
+
 ## Beat Saber Data Backups
 
 `backup-userdata` copies the mounted Windows `UserData` folder and Beat Saber
@@ -68,6 +110,22 @@ the latest backup run. Use
 for a `UserData`-only sync, or `--backup-root <path>` to choose a different
 destination.
 
+`restore-userdata` copies those backup trees back into a target instance. It
+moves the current `UserData` and AppData trees aside first as
+`<name>.pre-restore-<timestamp>` snapshots. On Linux BSManager installs,
+AppData is restored into the BSManager SharedContent Proton prefix unless
+`--appdata-path` is provided. If `backup-descriptor.json` is present, its
+`instance` field must match `--instance`.
+
+Example restore into the local Linux instance:
+
+```sh
+PYTHONPATH=src python -m plugin_helper \
+  --instances-root /home/pleb/.local/share/BSManager/BSInstances \
+  restore-userdata \
+  --instance 1.44.1
+```
+
 The backup intentionally omits bulky/generated data:
 
 - `UserData/BeatLeader/Replays`