docs: update plugin helper agent workflow

AGENTS.md

@@ -6,13 +6,18 @@ Guidance for coding agents working in this repo.
 
 - 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`
+  - `~/Windows/Users/pleb/BSManager/BSInstances`
+  - `~/.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
+  `~/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
@@ -24,13 +29,17 @@ Guidance for coding agents working in this repo.
 - 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
+  `--instances-root ~/.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
+  `--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.
@@ -46,6 +55,21 @@ Guidance for coding agents working in this repo.
 - 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.