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.

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.

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.

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.