Add BeatMods parsing and userdata restore

docs/DESIGN.md

@@ -1,16 +1,23 @@
 # plugin-helper Design
 
-`plugin-helper` is a Python CLI for managing Beat Saber plugins in a mounted Windows BSManager install. It installs from individual GitHub releases, keeps per-game-version plugin selections pinned, records exact filesystem changes, and leaves compatibility judgment visible enough for an agent to help when upstream packaging is inconsistent.
+`plugin-helper` is a Python CLI for managing Beat Saber plugins in BSManager
+installs. It installs from pinned release artifacts, keeps per-game-version
+plugin selections locked, records exact filesystem changes, and leaves
+compatibility judgment visible enough for an agent to help when upstream
+packaging is inconsistent.
 
-The initial target is the Linux side of `incineroar`, after the Windows partition has been mounted manually. The current Beat Saber instances live under:
+The current targets are the local Linux BSManager install and the mounted
+Windows BSManager install:
 
 ```text
 /home/pleb/Windows/Users/pleb/BSManager/BSInstances
+/home/pleb/.local/share/BSManager/BSInstances
 ```
 
 ## Goals
 
-- Manage plugins for one BSManager Beat Saber instance at a time, such as `1.40.8`.
+- Manage plugins for one BSManager Beat Saber instance at a time, such as
+  `1.44.1`, while supporting the same instance name under multiple roots.
 - Pull plugin releases directly from configured GitHub repositories.
 - Determine candidate updates while respecting the pinned Beat Saber version.
 - Support selective updates and explicit pins.
@@ -25,8 +32,10 @@ The initial target is the Linux side of `incineroar`, after the Windows partitio
 - Replacing BSManager as a GUI or Beat Saber instance manager.
 - Downloading or downgrading Beat Saber versions.
 - Running `nixos-rebuild switch`.
-- Mutating the Windows partition unless the user has mounted it and explicitly runs an apply command.
-- Treating Nix as the plugin installer. Nix should package `plugin-helper`; the CLI should manage the mutable mounted game tree.
+- Mutating the Windows partition unless the user has mounted it and explicitly
+  runs an apply command targeting that root.
+- Treating Nix as the plugin installer. Nix should package `plugin-helper`; the
+  CLI should manage mutable game trees.
 
 ## Core Model
 
@@ -82,6 +91,21 @@ Runtime state should not need to live inside the repository. By default, keep mu
 
 For early development, a `--state-dir` option is useful so plans and manifests can be kept in the repo while the format settles.
 
+When managing both local Linux and mounted Windows installs, install state must
+be separated by target root as well as by instance name. The current state
+layout is keyed by instance name, so two `1.44.1` installs should not share one
+state directory. A practical repo-local convention is:
+
+```text
+.state/          local Linux BSManager state
+.state-windows/  mounted Windows BSManager state
+```
+
+The registry and lockfile remain shared for a Beat Saber version. Downloads may
+be copied or re-fetched into each target-specific state directory, but generated
+plans, bootstrap records, backups, and `installed.json` belong to one target
+game tree.
+
 ## Registry
 
 The registry describes plugin sources and install behavior. It should be human-editable because many Beat Saber plugins have small packaging differences.

docs/ROADMAP.md

@@ -15,7 +15,13 @@ The initial tool should stay conservative:
 - Mutating operations apply an explicit plan and record exact file hashes.
 - Nix packages `plugin-helper`, but does not directly manage the mutable Beat Saber tree.
 
-This works well while Beat Saber is still launched from a Windows install or a mounted Windows filesystem.
+This works well while Beat Saber is launched from either the local Linux
+BSManager install or a mounted Windows BSManager filesystem.
+
+For the near term, the Python state model should treat target roots as distinct
+installations even when they share an instance name. Lockfiles can stay keyed by
+Beat Saber version, but bootstrap state, generated plans, backups, and
+`installed.json` need to stay target-specific.
 
 ## Future: Nix-Orchestrated Plugin Sets
 

docs/SMOKETEST.md

@@ -3,10 +3,10 @@
 Use this workflow after installing or removing a plugin batch. It is adapted
 from the Setlist repo's working Proton/BSManager smoketest notes.
 
-The routine smoketest should be short: about 10 seconds wall time for launch and
-log check, followed by immediate teardown. If expected plugin log lines do not
-appear inside that window, treat that as a failure to investigate instead of
-stretching the timeout.
+The routine smoketest should be short: about 20 seconds wall time for launch,
+menu/UI initialization, and log check, followed by immediate teardown. If
+expected plugin log lines do not appear inside that window, treat that as a
+failure to investigate instead of repeatedly stretching the timeout.
 
 ## Preconditions
 
@@ -47,7 +47,7 @@ export SteamEnv=1
 export OXR_PARALLEL_VIEWS=1
 
 (
-  sleep 10
+  sleep 20
   pkill -TERM -f "[B]eat Saber.exe" || pkill -TERM -f "[B]eat Saber" || true
   sleep 2
   pkill -KILL -f "[B]eat Saber.exe" || pkill -KILL -f "[B]eat Saber" || true