AGENTS.md

Guidance for coding agents working in this repo.

Project Shape

This repo manages Beat Saber plugins for BSManager instances.
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. 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.

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 .venv/bin/python -m plugin_helper --state-dir .state menu.
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.
After completing repo changes, suggest a concise commit message in the final response unless the user already asked you to commit.

Run PYTHONPATH=src .venv/bin/python -m unittest discover -s tests after code changes when .venv exists; otherwise use python.
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.

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.