# 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.

## Workflow Rules

- 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.

## Validation

- 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.

## Pull Requests

- 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.

## 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.