# AGENTS.md

Guidance for coding agents working in this repo.

## Project Shape

- This repo manages Beat Saber plugins for BSManager instances.
- Default instance roots are:
  - `/home/pleb/Windows/Users/pleb/BSManager/BSInstances`
  - `/home/pleb/.local/share/BSManager/BSInstances`
- A local BSManager source checkout may be available at
  `/home/pleb/src/Zagrios/bs-manager`. Use it as a read-only reference when
  investigating launch behavior, inherited Steam arguments, instance layout, or
  Proton environment details unless the user explicitly asks for BSManager code
  changes.
- Prefer repo-local state for planned installs unless the task explicitly
  targets the user's live default state. Use `--state-dir .state` for the local
  Linux install and `--state-dir .state-windows` for the mounted Windows install
  when both roots contain the same instance name.

## Workflow Rules

- Run commands from the repo root with `PYTHONPATH=src`.
- For human-style inspection, prefer the menu with repo-local state:
  `PYTHONPATH=src python -m plugin_helper --state-dir .state menu`.
- When targeting the local Linux BSManager install, pass
  `--instances-root /home/pleb/.local/share/BSManager/BSInstances` and normally
  `--state-dir .state`.
- When targeting the mounted Windows BSManager install, pass
  `--instances-root /home/pleb/Windows/Users/pleb/BSManager/BSInstances` and
  normally `--state-dir .state-windows`.
- Use the helper commands instead of manually copying plugin files into an
  instance.
- Treat BSIPA as a bootstrap phase:
  - `bootstrap` installs the locked BSIPA archive and records generated files.
  - ordinary plugin plans should depend on healthy bootstrap state.
- Be careful with duplicate instance names across Windows and local roots. Use
  the menu or pass `--instances-root` explicitly when targeting one install, and
  keep install/bootstrap state separate per target root.

## Validation

- Run `PYTHONPATH=src python -m unittest discover -s tests` after code changes.
- Run `PYTHONPATH=src python -m compileall -q src tests` for syntax/import
  checks.
- For live game validation, follow `docs/SMOKETEST.md` and tear down Beat Saber
  processes afterward.

## Launch Notes

- BSManager may inherit Beat Saber launch arguments configured in Steam.
- Do not assume a black screen is a plugin failure until checking
  `Logs/_latest.log`, Unity `Player.log`, and the live process command line.
- Duplicate launch args such as `--no-yeet fpfc --no-yeet fpfc` can trigger a
  fatal command-line parse error after BSIPA/plugin loading succeeds.