Use plugin-helper profiles in builder skill

.agents/skills/beatsaber-plugin-builder/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: beatsaber-plugin-builder
-description: Build, test-compile, or package Beat Saber PC BSIPA plugin source on Linux from local checkouts, GitHub branches, or pull requests. Use when asked to build a Beat Saber plugin, compile a plugin PR, produce a DLL/zip artifact, configure BeatSaberDir/local refs for dotnet builds, or diagnose Linux build failures for net472 BSIPA projects.
+description: Build, test-compile, or package Beat Saber PC BSIPA plugin source on Linux from local checkouts, GitHub branches, or pull requests. Use when asked to build a Beat Saber plugin, compile a plugin PR, produce a DLL/zip artifact, configure BeatSaberDir/local refs for dotnet builds, or diagnose Linux build failures for .NET Framework BSIPA projects.
 ---
 
-# Build Beat Saber Plugin
+# Beat Saber Plugin Builder
 
 Use this skill to compile PC BSIPA plugin projects on this Linux host, especially from the `plugin-helper` repo. The workflow is adapted from the Setlist repo's Linux/Cursor build notes.
 
@@ -16,18 +16,25 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
    ```bash
    pwd
    git status --short
+   sed -n '1,220p' plugin-helper.local.toml
    ```
 
-   In `plugin-helper`, run commands from repo root and keep temporary source checkouts under `.state/build/<name>` unless the user asks for another location. Do not disturb unrelated dirty files.
+   In `plugin-helper`, run commands from repo root. Treat
+   `plugin-helper.local.toml` as the source of truth for profile
+   `instances_root` and `state_dir` values, and keep temporary source checkouts
+   under the chosen profile's `state_dir` such as
+   `<state_dir>/build/<name>`. Do not disturb unrelated dirty files.
 
 2. Resolve source.
 
-   For a GitHub PR, clone or reuse a checkout under `.state/build`, add/fetch the upstream remote if needed, and check out the PR head:
+   For a GitHub PR, clone or reuse a checkout under the selected profile's
+   `<state_dir>/build`, add/fetch the upstream remote if needed, and check out
+   the PR head:
 
    ```bash
-   git clone https://github.com/<owner>/<repo>.git .state/build/<name>
+   git clone https://github.com/<owner>/<repo>.git <state_dir>/build/<name>
-   git -C .state/build/<name> fetch origin pull/<pr>/head:pr-<pr>
+   git -C <state_dir>/build/<name> fetch origin pull/<pr>/head:pr-<pr>
-   git -C .state/build/<name> checkout pr-<pr>
+   git -C <state_dir>/build/<name> checkout pr-<pr>
    ```
 
    If the PR is from a fork and the repo already has a fork remote, preserve it. Never overwrite local source changes without explicit approval.
@@ -43,14 +50,19 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
 
 4. Choose Beat Saber references.
 
-   Prefer a BSManager instance matching the plugin or manifest `gameVersion`. Common local roots:
+   Prefer a BSManager instance matching the plugin or manifest `gameVersion`.
+   Read `plugin-helper.local.toml` and select the intended profile, then use
+   that profile's `instances_root` and matching `state_dir` instead of
+   searching default BSManager paths manually:
 
-   ```text
+   ```bash
-   /home/pleb/.local/share/BSManager/BSInstances/<version>
+   PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> instances
-   /home/pleb/Windows/Users/pleb/BSManager/BSInstances/<version>
    ```
 
-   Use a local `.csproj.user` or MSBuild properties rather than committing machine paths. For test builds, pass `-p:DisableCopyToPlugins=True` and, for BSMT projects that expose it, `-p:DisableCopyToGame=True` so compilation does not mutate the game install.
+   Use a local `.csproj.user` or MSBuild properties rather than committing
+   machine paths. For test builds, pass `-p:DisableCopyToPlugins=True` and, for
+   BSMT projects that expose it, `-p:DisableCopyToGame=True` so compilation
+   does not mutate the game install.
 
 5. Restore and build.
 
@@ -61,9 +73,25 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
    dotnet build <solution-or-project> -c Release -p:DisableCopyToPlugins=True -p:DisableCopyToGame=True
    ```
 
-   If the project lacks .NET Framework reference assemblies on Linux, add or pass `Microsoft.NETFramework.ReferenceAssemblies.net472` as described in the reference file.
+   If the project lacks .NET Framework reference assemblies on Linux, add or
+   pass the package matching the project's target framework, usually
+   `Microsoft.NETFramework.ReferenceAssemblies.net48` for current BSIPA
+   projects, as described in the reference file.
 
-6. Collect artifacts.
+6. Verify Beat Saber API changes before patching gameplay code.
+
+   When a Beat Saber upgrade breaks a type/member reference, first determine
+   whether the API moved assemblies before substituting another type. Inspect
+   the target game DLLs and nearby mod sources:
+
+   ```bash
+   strings "<BeatSaberDir>/Beat Saber_Data/Managed/Main.dll" | rg 'TypeOrMemberName'
+   strings "<BeatSaberDir>/Beat Saber_Data/Managed/HMLib.dll" | rg 'TypeOrMemberName'
+   ilspycmd -t TypeName "<BeatSaberDir>/Beat Saber_Data/Managed/Main.dll" | sed -n '1,220p'
+   rg -n 'TypeOrMemberName|NearbyConcept' ~/src/<owner>/<repo> ~/src/Auros/SiraUtil ~/src/nike4613/BeatSaber-IPA-Reloaded
+   ```
+
+7. Collect artifacts.
 
    Find produced DLLs and release zips:
 
@@ -71,23 +99,27 @@ For detailed Linux/BSMT behavior, read [linux-bsipa-build.md](references/linux-b
    find <checkout> -path '*/bin/*' \( -name '*.dll' -o -name '*.zip' \) -print
    ```
 
-   Verify the DLL name, version, and manifest. If the result is meant for `plugin-helper`, place a copy under `.state/instances/<instance>/downloads/<plugin-id>/` and use the helper plan/apply workflow rather than hand-copying into a BSManager instance.
+   Verify the DLL name, version, and manifest. If the result is meant for
+   `plugin-helper`, place a copy under
+   `<state_dir>/instances/<instance>/downloads/<plugin-id>/` for the selected
+   profile and use the helper plan/apply workflow rather than hand-copying into
+   a BSManager instance.
 
-7. Validate.
+8. Validate.
 
    For skill edits inside this repo, run:
 
    ```bash
    python /home/pleb/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/beatsaber-plugin-builder
-   PYTHONPATH=src python -m compileall -q src tests
+   PYTHONPATH=src .venv/bin/python -m compileall -q src tests
-   PYTHONPATH=src python -m unittest discover -s tests
+   PYTHONPATH=src .venv/bin/python -m unittest discover -s tests
    ```
 
    For a plugin build, at minimum report the exact `dotnet build` result and artifact paths. For live game validation, use `docs/SMOKETEST.md` and tear down Beat Saber processes afterward.
 
 ## Failure Triage
 
-- Missing `Microsoft.NETFramework.ReferenceAssemblies`: add the net472 reference-assemblies package or pass an equivalent MSBuild/package restore fix.
+- Missing `Microsoft.NETFramework.ReferenceAssemblies`: add the package matching the target framework, usually `Microsoft.NETFramework.ReferenceAssemblies.net48` for current projects, or pass an equivalent MSBuild/package restore fix.
 - Missing `Main.dll`, `HMUI.dll`, `IPA.Loader.dll`, `BSML.dll`, `SongCore.dll`, or similar: `BeatSaberDir` points at the wrong/unmodded instance, or dependencies are absent from `Plugins/`/`Libs/`.
 - BSMT copies to `IPA/Pending` or `Plugins` during build: rebuild with `-p:DisableCopyToPlugins=True -p:DisableCopyToGame=True` unless the user explicitly wants deployment.
 - NuGet package restore fails because a source is missing: inspect `NuGet.config` and installed package sources; use repo-local configuration where possible.

.agents/skills/beatsaber-plugin-builder/references/linux-bsipa-build.md

@@ -6,7 +6,8 @@ This workflow comes from `/home/pleb/ops/beatsaber/setlist/docs/pc-modding.md` a
 
 ## Toolchain
 
-- PC BSIPA plugins are usually .NET Framework `net472` class libraries.
+- PC BSIPA plugins are .NET Framework class libraries; current projects
+  commonly target `net48`, while older projects may still target `net472`.
 - Linux `dotnet` SDK 6+ can build them because output DLLs are platform-agnostic CIL loaded by Beat Saber under Proton.
 - `BeatSaberModdingTools.Tasks` supplies the MSBuild targets normally driven by Visual Studio/Rider BSMT extensions.
 - On this host, `dotnet --list-sdks` should show a usable SDK. NuGet is available for package inspection.
@@ -24,16 +25,13 @@ Plugins/
 winhttp.dll
 ```
 
-Preferred local managed instance root:
+In `plugin-helper`, prefer the profile selected from
+`plugin-helper.local.toml` as the source of truth for the managed instance root
+and state directory:
 
-```text
+```bash
-/home/pleb/.local/share/BSManager/BSInstances/<version>
+sed -n '1,220p' plugin-helper.local.toml
-```
+PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> instances
-
-Windows mirror root:
-
-```text
-/home/pleb/Windows/Users/pleb/BSManager/BSInstances/<version>
 ```
 
 Use `BeatSaberVersion.txt` for the exact game version. The manifest `gameVersion` normally uses the `major.minor.patch` prefix, not the build suffix.
@@ -45,7 +43,7 @@ Prefer machine-local configuration in `<Project>.csproj.user`:
 ```xml
 <Project>
   <PropertyGroup>
-    <BeatSaberDir>/home/pleb/.local/share/BSManager/BSInstances/1.40.8</BeatSaberDir>
+    <BeatSaberDir>/path/from/selected/profile/instances_root/1.44.1</BeatSaberDir>
   </PropertyGroup>
 </Project>
 ```
@@ -60,7 +58,10 @@ For those, pass `-p:LocalRefsDir=/path/to/instance` or add a local `.csproj.user
 
 When changing a project file for Linux portability, prefer the smallest explicit fix:
 
-- Add `Microsoft.NETFramework.ReferenceAssemblies.net472` when MSBuild reports missing .NET Framework reference assemblies.
+- Add the `Microsoft.NETFramework.ReferenceAssemblies.*` package matching the
+  project target framework, usually `Microsoft.NETFramework.ReferenceAssemblies.net48`
+  for current projects, when MSBuild reports missing .NET Framework reference
+  assemblies.
 - Set or pass `DisableCopyToPlugins=True` for artifact-only builds.
 - Keep hint paths rooted at `$(BeatSaberDir)` where possible.
 - Do not add broad multi-version compatibility logic unless requested.
@@ -105,7 +106,9 @@ If the purpose is to install the built artifact, copy it into plugin-helper's st
 
 ## Common Reference Failures
 
-- `MSB3644` or missing `.NETFramework,Version=v4.7.2` reference assemblies: add `Microsoft.NETFramework.ReferenceAssemblies.net472`.
+- `MSB3644` or missing `.NETFramework,Version=v4.x` reference assemblies: add
+  the matching `Microsoft.NETFramework.ReferenceAssemblies.*` package, usually
+  `Microsoft.NETFramework.ReferenceAssemblies.net48` for current projects.
 - Missing game assemblies such as `Main.dll`, `HMUI.dll`, `UnityEngine.CoreModule.dll`: `BeatSaberDir` is wrong or incomplete.
 - Missing mod dependencies such as `BSML.dll`, `SongCore.dll`, `SiraUtil.dll`, `BeatSaberPlaylistsLib.dll`: install or point at an instance containing those plugins, or fetch the dependency DLL from its verified release only when appropriate.
 - `IPA.Loader.dll` missing: BSIPA is not bootstrapped in that instance.
@@ -115,17 +118,17 @@ If the purpose is to install the built artifact, copy it into plugin-helper's st
 For a built plugin DLL intended for a managed instance:
 
 ```bash
-mkdir -p .state/instances/<instance>/downloads/<plugin-id>
+mkdir -p <state_dir>/instances/<instance>/downloads/<plugin-id>
-cp <checkout>/<path>/bin/Release/<Plugin>.dll .state/instances/<instance>/downloads/<plugin-id>/<Plugin>.dll
+cp <checkout>/<path>/bin/Release/<Plugin>.dll <state_dir>/instances/<instance>/downloads/<plugin-id>/<Plugin>.dll
-sha256sum .state/instances/<instance>/downloads/<plugin-id>/<Plugin>.dll
+sha256sum <state_dir>/instances/<instance>/downloads/<plugin-id>/<Plugin>.dll
 ```
 
 Then update registry/lock data only if the user asked to manage/install the artifact, and use:
 
 ```bash
-PYTHONPATH=src python -m plugin_helper --state-dir .state check --instance <instance>
+PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> check --instance <instance>
-PYTHONPATH=src python -m plugin_helper --state-dir .state plan --instance <instance> --plugin <plugin-id>
+PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> plan --instance <instance> --plugin <plugin-id>
-PYTHONPATH=src python -m plugin_helper --state-dir .state apply <plan-path>
+PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> apply <plan-path>
 ```
 
 Inspect the generated plan before applying.

.agents/skills/beatsaber-plugin-manager/SKILL.md

@@ -3,7 +3,7 @@ name: beatsaber-plugin-manager
 description: Install or update a Beat Saber plugin in the plugin-helper repo by using the local helper workflow. Use when the user asks to add, install, update, bump, lock, bootstrap BSIPA, or manage a Beat Saber plugin release for a BSManager instance. Prefer upstream GitHub release artifacts for normal plugins; use BeatMods primarily as compatibility/dependency metadata, with CDN artifacts only for inaccessible upstream assets, BeatMods-only packages, or framework/library dependencies.
 ---
 
-# Install Beat Saber Plugin
+# Beat Saber Plugin Installer
 
 Use the repository's own `plugin-helper` commands to manage plugins for BSManager instances whenever the helper supports the operation.
 

AGENTS.md

@@ -26,8 +26,10 @@ Guidance for coding agents working in this repo.
 ## Workflow Rules
 
 - Run commands from the repo root with `PYTHONPATH=src`.
+- A repo-local Python virtualenv is normally available at `.venv`; prefer
+  `.venv/bin/python` for helper commands and tests when it exists.
 - For human-style inspection, prefer the menu with repo-local state:
-  `PYTHONPATH=src python -m plugin_helper --state-dir .state menu`.
+  `PYTHONPATH=src .venv/bin/python -m plugin_helper --state-dir .state menu`.
 - When targeting the local Linux BSManager install, pass
   `--instances-root ~/.local/share/BSManager/BSInstances` and normally
   `--state-dir .state`.
@@ -51,9 +53,10 @@ Guidance for coding agents working in this repo.
 
 ## Validation
 
-- Run `PYTHONPATH=src python -m unittest discover -s tests` after code changes.
+- Run `PYTHONPATH=src .venv/bin/python -m unittest discover -s tests` after
-- Run `PYTHONPATH=src python -m compileall -q src tests` for syntax/import
+  code changes when `.venv` exists; otherwise use `python`.
-  checks.
+- Run `PYTHONPATH=src .venv/bin/python -m compileall -q src tests` for
+  syntax/import checks when `.venv` exists; otherwise use `python`.
 - For live game validation, follow `docs/SMOKETEST.md` and tear down Beat Saber
   processes afterward.