Document plugin helper agent workflow

2026-06-28 14:35:21 -07:00
parent f085bbb802
commit 17bd736e59
3 changed files with 270 additions and 6 deletions
@@ -0,0 +1,49 @@
+# 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 with `--state-dir .state` for planned installs unless
+  the task explicitly targets the user's live default state.
+
+## 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 rather than the Windows
+  mirror, pass `--instances-root /home/pleb/.local/share/BSManager/BSInstances`
+  or choose that path explicitly in the menu.
+- 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.
+
+## 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.