# plugin-helper State And Profiles

Use these rules when selecting BSManager instances, state directories, and source
checkout locations.

## Instance Selection

- Prefer the Beat Saber instance the user names.
- If the user omits an instance, use the latest available BSInstance unless the
  current task context or user notes clearly point at another instance.
- Discover available instances with the helper rather than assuming a hard-coded
  game version:

  ```bash
  PYTHONPATH=src .venv/bin/python -m plugin_helper instances
  ```

## State Directories

- Prefer repo-local `.state` for planned installs, update audits, downloaded
  artifacts, and generated plans unless the user explicitly targets live default
  state or another configured profile.
- For mounted Windows installs, prefer the shared Windows-partition state
  directory configured in `plugin-helper.local.toml` when both roots contain the
  same instance name.
- Keep target-specific managed state with the selected target root. Do not mix a
  Linux install's `installed.json` with a Windows install's state unless the user
  intentionally selected that shared state.

## Profiles

- Read `plugin-helper.local.toml` before choosing a configured profile:

  ```bash
  sed -n '1,220p' plugin-helper.local.toml
  PYTHONPATH=src .venv/bin/python -m plugin_helper --profile <profile-id> instances
  ```

- Treat the selected profile's `instances_root` and `state_dir` as a pair.
- When using `--profile`, prefer it over manually passing default BSManager paths.

## Source Checkouts

- Keep plugin source checkouts under `~/src/<owner>/<repo>` when a locked or
  registry plugin has a GitHub source repo.
- Prefer checking out upstream `owner/repo` first, with `origin` pointing at
  upstream.
- If a personal fork checkout already exists, preserve it as a remote named
  `github` and set or add `origin` to the upstream repo instead of replacing
  local work.
- For temporary PR/build work tied to a selected profile, use that profile's
  `<state_dir>/build/<name>` when the skill explicitly calls for disposable
  build checkouts.