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:
- ~/Windows/Users/pleb/BSManager/BSInstances
- ~/.local/share/BSManager/BSInstances
A local BSManager source checkout may be available at ~/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.
Keep plugin source checkouts under ~/src/<owner>/<repo> when a locked or registry plugin has a GitHub source repo. Prefer checking out the upstream author/repo first, with origin pointing at upstream. If the user has an existing personal fork checkout, preserve it as a remote named github and set/add origin to the upstream repo instead of replacing local work.
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 ~/.local/share/BSManager/BSInstances and normally --state-dir .state.
When targeting the mounted Windows BSManager install, pass --instances-root ~/Windows/Users/pleb/BSManager/BSInstances and normally --state-dir .state-windows.
Use the helper commands instead of manually copying plugin files into an instance.
When adding, updating, building, or investigating a GitHub-hosted plugin, check for ~/src/<owner>/<repo> and clone the upstream repo there if it is missing. Do not substitute forks or similar repos without explicit user direction.
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.

When the user asks for a PR against an upstream plugin, compose and submit a polite pull request using the user's existing gh session.
Keep upstream PRs small, focused, and easy for the maintainer to verify. Favor narrow compatibility fixes, clear commit messages, and minimal formatting or project-file churn.
Work from the upstream checkout under ~/src/<owner>/<repo> when available. If the upstream remote is not writable, create or reuse the user's fork with gh repo fork, push a topic branch there, and open the PR against upstream.
Include concise verification notes in the PR body, especially the exact build or smoke-test command and any generated artifact name. Mention local-only build configuration separately if it was needed, and do not commit machine paths or helper state unless the user explicitly asks for it.

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.