Simplify plugin-helper state configuration

README.md

@@ -11,55 +11,67 @@ 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 roots:
+Default BSManager instance root:
 
 ```text
-/home/pleb/Windows/Users/pleb/BSManager/BSInstances
 /home/pleb/.local/share/BSManager/BSInstances
 ```
 
-Override with `--instances-root` or `PLUGIN_HELPER_INSTANCES_ROOT`. To search
+Default plugin-helper state directory:
+
+```text
+$XDG_STATE_HOME/plugin-helper
+```
+
+If `XDG_STATE_HOME` is not set, the state directory defaults to:
+
+```text
+~/.local/state/plugin-helper
+```
+
+Override the instance root with `--instances-root`,
+`PLUGIN_HELPER_INSTANCES_ROOT`, or `plugin-helper.local.toml`. To search
 multiple explicit roots, separate them with `:`.
 
-## Managing Multiple Installs
+Override the state directory with `--state-dir`, `PLUGIN_HELPER_STATE_DIR`, or
+`plugin-helper.local.toml`.
 
-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`, give each install profile its own
-state directory.
+## Local Configuration
+
+This checkout is intended to manage the local Linux BSManager install. If you
+also manage a Windows install, use a separate clone on that partition and point
+both clones at the same state directory only when you intentionally want one
+shared source of truth.
+
+Copy the example config and adjust paths if needed:
 
-Copy the example profile config and adjust paths if needed:
 
 ```sh
 cp plugin-helper.toml.example plugin-helper.local.toml
 ```
 
-`plugin-helper.local.toml` is ignored by git. The default example uses this
-repo-local convention:
+`plugin-helper.local.toml` is ignored by git and uses top-level fields:
 
-```text
-.state/          local Linux BSManager state
-.state-windows/  mounted Windows BSManager state
+```toml
+instances_root = "~/.local/share/BSManager/BSInstances"
+state_dir = "~/.local/state/plugin-helper"
 ```
 
-Examples:
+For repo-local state, set:
 
-```sh
-PYTHONPATH=src python -m plugin_helper \
-  --profile linux \
-  installed --instance 1.44.1
-
-PYTHONPATH=src python -m plugin_helper \
-  --profile windows \
-  installed --instance 1.44.1
+```toml
+state_dir = ".state"
 ```
 
-Explicit `--instances-root` and `--state-dir` still work and override profile
-values. 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.
+For a shared Windows-partition state directory, set the same `state_dir` in both
+clones, for example:
+
+```toml
+state_dir = "~/Windows/Users/pleb/ops/plugin-helper/.state"
+```
+
+CLI flags override environment variables, environment variables override local
+config, and local config overrides built-in defaults.
 
 ## Commands
 
@@ -79,21 +91,13 @@ disable all currently enabled managed plugins and `e` to enable all currently
 disabled managed plugins.
 
 The individual subcommands are mostly for automation and debugging. If you use
-them, prefer `--profile linux` or `--profile windows`. Pass `--state-dir`
-directly only when you intentionally want to override profile state or use the
-default live state outside this repo.
+them, pass `--state-dir` directly only when you intentionally want to override
+the configured state directory for one command.
 
 Install assets are currently expected to already exist locally, usually under:
 
 ```text
-.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>/
+<state-dir>/instances/<instance>/downloads/<plugin-id>/
 ```
 
 ## Beat Saber Data Backups