Document native Windows setup and update compatibility tracker.

Add PowerShell examples, profile usage notes, and record completed Windows
compatibility work in the tracker.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -31,7 +31,8 @@ If `XDG_STATE_HOME` is not set, the state directory defaults to:
 
 Override the instance root with `--instances-root`,
 `PLUGIN_HELPER_INSTANCES_ROOT`, or `plugin-helper.local.toml`. To search
-multiple explicit roots, separate them with `:`.
+multiple explicit roots, separate them with `:` on Linux/macOS or `;` on
+Windows.
 
 Override the state directory with `--state-dir`, `PLUGIN_HELPER_STATE_DIR`, or
 `plugin-helper.local.toml`.
@@ -73,6 +74,45 @@ 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.
 
+## Native Windows
+
+For a separate checkout on a Windows partition, copy the Windows example config
+and adjust paths if needed:
+
+```powershell
+Copy-Item plugin-helper.windows.toml.example plugin-helper.windows.toml
+```
+
+`plugin-helper.windows.toml` is ignored by git. It uses profile entries:
+
+```toml
+[[profiles]]
+id = "windows"
+label = "Native Windows BSManager"
+instances_root = "~/BSManager/BSInstances"
+state_dir = ".state"
+```
+
+Run commands with `--config` and `--profile` so native Windows state stays in
+that checkout's `.state/` directory. If `plugin-helper.windows.toml` has only
+one `[[profiles]]` entry, that profile is selected automatically when
+`--profile` is omitted:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+py -m pip install -e .
+py -m plugin_helper menu
+py -m plugin_helper --config plugin-helper.windows.toml --profile windows installed --instance 1.44.1
+```
+
+On native Windows, `bootstrap` runs `IPA.exe -n` directly instead of through
+Proton. `bootstrap-check` accepts a recorded native bootstrap without requiring
+`Logs/_latest.log` when `IPA.exe -n` completed successfully.
+
+When no config file is present on Windows, defaults are
+`~/BSManager/BSInstances` and `%LOCALAPPDATA%/plugin-helper`.
+
 ## Commands
 
 For normal use, run the Textual menu from the repo root:
@@ -170,9 +210,10 @@ custom content or non-obvious user choices rather than pure cache data.
   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
+  applies the locked `bsipa` root archive, runs `IPA.exe -n` (natively on
-  records every bootstrap-relevant file under root `IPA.exe*`, `winhttp.dll`,
+  Windows or through Proton on Linux), and records every bootstrap-relevant
-  `Libs/`, and `IPA/`, including backups created during patching.
+  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.

docs/notes/windows-compatibility.md

@@ -15,6 +15,12 @@ Windows instances.
   ```
 
 - Use a separate checkout or working copy on the Windows partition.
+- Copy and adjust the Windows config template:
+
+  ```powershell
+  Copy-Item plugin-helper.windows.toml.example plugin-helper.windows.toml
+  ```
+
 - Use a Windows-specific config file:
 
   ```powershell
@@ -30,38 +36,48 @@ Windows instances.
 - Core scan, plan, apply, uninstall, disable, and enable flows are mostly
   platform-neutral. They use `pathlib`, `zipfile`, `shutil`, JSON/TOML, and
   local file hashes.
-- Native Windows defaults should not reuse Linux-mounted paths such as
+- Native Windows defaults do not reuse Linux-mounted paths such as
   `/home/pleb/Windows/...`. A Windows-specific TOML file handles this for normal
   use.
 - Multiple `--instances-root` values use `os.pathsep`; that means `;` on
-  Windows and `:` on Linux. Documentation should make this platform-specific.
+  Windows and `:` on Linux. README documents this platform-specific separator.
 - The Textual TUI dependency supports Windows and Python 3.13, but the best
   terminal target is Windows Terminal or a modern PowerShell host.
 
 ## Work Items
 
+### Done
+
 - Add native Windows bootstrap support.
-  - Current bootstrap assumes Proton.
+  - `bootstrap` auto-detects Windows and runs `IPA.exe -n` directly.
-  - Native Windows should run `IPA.exe -n` directly from the Beat Saber instance.
+  - `--native` forces native mode; `--proton` remains for Linux/Proton installs.
-  - Timeout cleanup needs Windows-compatible process handling instead of
+  - Timeout cleanup uses `process.terminate()` / `process.kill()` on Windows
-    POSIX process groups.
+    instead of POSIX process groups.
-- Decide whether `bootstrap-check` should accept a recorded native Windows
+  - Bootstrap state records `bootstrapMode: "native"` or `"proton"`.
-  bootstrap state without a Proton launch history.
+- `bootstrap-check` accepts recorded native Windows bootstrap state without
-- Add Windows-aware default paths or keep requiring `--config
+  `Logs/_latest.log` when `IPA.exe -n` completed successfully
-  plugin-helper.windows.toml` for native use.
+  (`ipaExitCode == 0`, not timed out).
-- Update README examples for PowerShell:
+- Add Windows-aware default paths when no config is present:
-  - editable install
+  `~/BSManager/BSInstances` and `%LOCALAPPDATA%/plugin-helper`.
-  - `--config plugin-helper.windows.toml`
+  Normal native use still prefers `--config plugin-helper.windows.toml`.
-  - Windows path-list separator `;`
+- Add `--config` and `--profile` CLI flags with `[[profiles]]` TOML support.
-- Add or adjust tests for Windows behavior.
+- Add `plugin-helper.windows.toml.example` as the committed template.
-  - Skip or rewrite the POSIX-only `_run_ipa` timeout test on Windows.
+- Update README examples for PowerShell, profiles, and the `;` path separator.
-  - Add tests for native Windows config path resolution.
+- Add tests for profile config resolution, native bootstrap command
-  - Add tests for native bootstrap command construction.
+  construction, native bootstrap health checks, and platform-gated IPA timeout
+  behavior.
 - Review backup and restore helpers on native Windows.
-  - `sync_windows_data_repo` and `restore_windows_data_repo` should work with
+  - `sync_windows_data_repo` and `restore_windows_data_repo` work with ordinary
-    ordinary Windows paths.
+    Windows paths; `infer_windows_appdata_path` now keys off `BSManager` rather
-  - The older tar-based `backup_userdata` helper uses `NamedTemporaryFile` in a
+    than the first `Users` path segment.
-    way that may not be Windows-friendly if it becomes part of the CLI later.
+  - `backup_userdata` no longer uses `NamedTemporaryFile` while the tar archive
+    is open, which fixes Windows permission errors.
+
+### Remaining
+
+- Run the first manual smoke on a native Windows checkout (see below).
+- Consider whether the menu TUI needs Windows-specific setup hints when
+  `plugin-helper.windows.toml` is present but `--profile` was omitted.
 
 ## First Manual Smoke
 
@@ -75,3 +91,14 @@ py -3.13 -m plugin_helper --config plugin-helper.windows.toml --profile windows
 
 If instance discovery fails, verify the BSManager instance root in
 `plugin-helper.windows.toml`.
+
+## Implementation Map
+
+| Area | Files |
+| --- | --- |
+| Config profiles and Windows defaults | `src/plugin_helper/config.py` |
+| Native bootstrap and process handling | `src/plugin_helper/bootstrap.py` |
+| Native bootstrap health gate | `src/plugin_helper/bsipa.py` |
+| CLI flags | `src/plugin_helper/cli.py` |
+| Windows config template | `plugin-helper.windows.toml.example` |
+| Tests | `tests/test_plugin_helper.py` |