Initial attempt at porting over fenrir's hardware synth support. Probably buggy.

AGENTS.md

@@ -24,6 +24,45 @@ This repository is a screen reader. Prioritize accessibility, correctness, and s
 - If repo and installed behavior differ, prefer rebuilding with `./build-local.sh` over patching the installed package directly.
 - Treat direct edits under `~/.local/.../cthulhu/` as an exception path that requires explicit user approval.
 
+## Contribution workflow (including generated patches)
+- Assume contributors may use code-generation tools without understanding every changed line. Review the resulting code, not the contributor's confidence in it.
+- Start from a reproducible user-visible problem. Capture the exact application, desktop/session type, steps, expected behavior, actual behavior, and relevant logs before changing code.
+- Investigate the full confirmed behavior class before implementing a fix. For example, a stale-focus bug seen in one browser may also affect other applications or empty workspaces.
+- Prefer the smallest root-cause fix that covers the full confirmed behavior class. Do not add app-specific exceptions, desktop-specific branches, compatibility fallbacks, or broad refactors unless the evidence requires them.
+- Add or update automated regression tests for the general behavior and the originally reported workflow whenever practical.
+- Read every generated diff before committing. Remove unrelated rewrites, speculative cleanup, dead code, debug leftovers, and generated files that are not required by the fix.
+- Never commit a change solely because it compiles or because an automated tool says it works. Verify the real user-facing workflow after rebuilding the installed copy.
+
+## Verification checklist before commit
+Run the narrowest relevant checks first, then broaden testing based on the affected behavior:
+
+1. Inspect the diff:
+   - `git diff --check`
+   - `git status --short`
+   - `git diff --stat`
+   - `git diff -- <changed files>`
+2. Run syntax checks for each changed Python file:
+   - `python -m py_compile <changed .py files>`
+3. Run focused automated regression tests:
+   - `python -m unittest <relevant test modules>`
+   - For shared input, focus, script lifecycle, settings, plugin loading, or installation changes, run `./test-local.sh` after the focused tests pass.
+4. Rebuild the local installed copy:
+   - `./build-local.sh`
+5. Confirm the runtime import resolves to the refreshed local install:
+   - `python - <<'PY'`
+   - `import importlib.util`
+   - `print(importlib.util.find_spec("cthulhu").origin)`
+   - `PY`
+6. Reproduce the original user-visible workflow against the rebuilt copy.
+7. Check closely related regressions. For focus, keyboard, or window-tracking changes, manually test:
+   - Xorg and the user's active window manager or desktop.
+   - Switching among browser content, terminal windows, GTK applications, dialogs, and empty workspaces.
+   - Returning to the original application after each switch.
+   - Cthulhu shortcuts, structural navigation, flat review, and any delegated key handling such as Fenrir in XTerm.
+   - Both key press and key release behavior for modifiers, NumLock, and keypad keys when relevant.
+   - Clean shutdown without crashing the browser or leaving grabs behind.
+8. Record what was tested, what could not be tested locally, and any remaining uncertainty in the commit message or review notes.
+
 ## Platform support stance
 - **critical** Robust Xorg support is required and is a merge gate for Cthulhu.
 - Wayland support is desirable, but it is secondary to keeping Xorg stable and usable.