Updated AGENTS.md

AGENTS.md

@@ -45,6 +45,30 @@ when making cross platform changes.
 New unit tests are added by listing them in availableTests in unittest.cpp. If they are large, put them in
 separate files in the unittest subdirectory. Remember to update both CMakeLists.txt and the visual studio project.
 
+## Adding HLE modules
+
+HLE module implementations live in `Core/HLE/sce<ModuleName>.cpp` / `.h` (e.g. `sceOpenPSID.cpp`, `scePauth.cpp` are good
+small examples to copy from). A module is a `const HLEFunction <name>[]` table of
+`{nid, &WrapX_YYY<func>, "funcName", retChar, argString}` entries, registered via
+`RegisterHLEModule("<name>", ARRAY_SIZE(table), table)` inside a `Register_<name>()` function declared in the header.
+
+- `FunctionWrappers.h` has generic `WrapX_YYY<func>` templates for common signatures (return type X, args YYY) - check
+  there before writing a manual wrapper.
+- Format string legend for the `retmask`/argmask chars: `x` = u32 (shown as hex), `i` = int/s32, `f` = float, `X` = u64,
+  `I` = s64, `v` = void.
+- For functions of genuinely unknown purpose (only known by NID), name them `<moduleName>_<NID>` and stub them with
+  `return hleLogError(Log::HLE, 0, "UNIMPL");` - an established pattern (see `scePauth.cpp`, `sceOpenPSID.cpp`).
+- **New modules must be registered at the very end** of the registration function in `Core/HLE/HLETables.cpp` (look for
+  the `// add new modules here.` comment near the end of that function) - not inserted alphabetically/logically among
+  the existing `Register_*()` calls. Module registration order affects numeric IDs used in savestates, so inserting a
+  new module earlier in that list would break save-state compatibility for saves made with older builds.
+- Remember to add any new `.cpp`/`.c` file to **five** places: `Core/CMakeLists.txt`, `Core/Core.vcxproj`,
+  `Core/Core.vcxproj.filters`, `android/jni/Android.mk`, and `libretro/Makefile.common`. New `.h` files only need the
+  first three (`Android.mk`/`Makefile.common` are plain compiled-source lists, not project generators, so headers
+  don't go in them). Only the CMakeLists.txt change can be verified from a Linux/Mac build - the rest can't be
+  build-tested here, so double check them by hand against how an existing neighboring file (e.g. `sceVaudio.cpp`) is
+  listed in each.
+
 ## Quick rebuild on Linux
 
 You don't need to do ./b.sh --debug to verify every single little change, instead use this shortcut: