docs: add agent and LLM contribution guidance

AGENTS.md

@@ -0,0 +1,87 @@
+# Pumptools contributor instructions
+
+These instructions apply throughout the repository. Read the relevant source,
+tests, and documentation before changing behavior. See `CONTRIBUTING.md`,
+`doc/development/development.md`, and `doc/development/architecture.md` for the
+broader contributor guidance.
+
+## Engineering principles
+
+- Follow the patterns in neighboring code for naming, ownership, lifecycle,
+  error handling, logging, documentation, and CMake organization.
+- Keep each responsibility in the narrowest existing module. Reusable
+  corrections belong in a suitable patch module; game hooks select and
+  initialize the modules required by that game.
+- Preserve API return values and `errno` behavior. Use module-scoped logging for
+  runtime failures and assertions for internal invariants.
+- Preserve pass-through behavior when a hook does not own or recognize a call.
+- Treat constructors, destructors, `__libc_start_main`, `dlopen`, `dlsym`,
+  `RTLD_NEXT`, signatures, calling conventions, hard-coded addresses,
+  initialization and shutdown order, recursion, and thread safety as
+  compatibility-sensitive boundaries.
+- Follow `.clang-format` for maintained C and header files. Inspect the focused
+  diff before running `make clang-format`, and do not format vendored code under
+  `src/imports/`. Follow the established local style for CMake, Make, shell, and
+  Markdown files.
+- Comments and documentation should explain non-obvious constraints, ABI or
+  lifecycle requirements, and reasons. Update user or development documentation
+  when configuration, public APIs, setup, or supported behavior changes.
+
+## Tests and hooked behavior
+
+- Add or update unit tests whenever changed behavior can be isolated with the
+  existing test framework. For a bug fix, add a regression case that
+  demonstrates the previous failure where practical.
+- Preserve coverage for existing behavior while testing the new expectation.
+  Include relevant success, failure, malformed-input, disabled, no-match, and
+  pass-through cases.
+- Check observable behavior as applicable: parameters, calls, buffers, return
+  values, `errno`, side effects, lifecycle, and ownership. Do not merely relax
+  an expectation to accommodate a changed implementation.
+- Put production behavior in the production module and exercise that same code
+  from tests. Do not create a test-only copy of parsing or decision logic.
+- For hook behavior, use the capnhook named-function-mock seam and CMocka when
+  the dependency can be isolated. Verify whether and how the original function
+  is called, then keep the real game-hook path responsible for initializing the
+  tested patch module.
+- `src/main/hook/propatch/usb-fix.c` and
+  `src/test/hook/propatch/usb-fix/main.c` provide the established pattern for a
+  production patch integrated with mocked detoured calls.
+- Register new tests in the corresponding `cmake/src/test/` hierarchy.
+
+## Verification
+
+Run the applicable checks from the repository root:
+
+```sh
+make build
+make test
+make build-docker
+```
+
+Compilation, unit tests, Docker compatibility builds, fixture or process tests,
+game-runtime tests, and cabinet or hardware tests are separate evidence levels.
+Do not claim game or hardware compatibility from compilation or unit tests.
+State what was actually tested and the relevant platform, game, and hardware
+details.
+
+## Maintainer interaction and LLM use
+
+Follow the LLM policy in `CONTRIBUTING.md`. Human contributors remain
+responsible for understanding, reviewing, testing, and validating submitted
+work.
+
+Do not autonomously publish issues, pull requests, reviews, comments, or
+replies. Prepare concise drafts for human review. Filter analysis and tool
+output to evidence relevant to the discussion rather than transferring raw or
+excessive output to maintainers. A human must choose what to communicate,
+provide its context, guide the discussion, and respond to maintainer feedback.
+
+Only describe work as an unvetted or deliberately rough prototype when the
+maintainers have agreed to receive it on that basis. Clearly state its scope,
+limitations, and verification status.
+
+## Sensitive material
+
+Do not read, reproduce, log, or commit credentials, game assets, dongle keys,
+raw security material, private identifiers, or unsanitized runtime evidence.

CONTRIBUTING.md

@@ -12,6 +12,28 @@ we have, the easier it might get to solve the issue.
 
 When creating new issues, use our template for reporting bugs. It tells you what kind of information we need.
 
+# Use of LLM tools
+
+Using large language models and other generative tools is allowed. The person using the tool remains responsible for
+the contribution and its communication.
+
+LLMs should assist with work that the contributor understands well enough to direct, review, and validate. They may
+perform implementation, research, analysis, documentation, or other leg work, but the contributor must check their
+output before submitting it to maintainers. The usual requirements for correctness, testing, documentation, security,
+and compatibility apply regardless of how the work was produced.
+
+An exception may be made when the maintainers have agreed in advance to receive an explicitly unvetted or deliberately
+rough prototype. Its purpose, limitations, and verification status must be clear.
+
+Interactions with maintainers in issues and pull requests must be actively driven by a human. Reviewed LLM-generated
+material may be included directly when it usefully communicates code analysis, technical explanations, test results,
+or similar evidence; rewriting it solely to conceal its origin is not required. However, a human must decide what is
+relevant, provide the surrounding context, initiate and guide the discussion, and respond to maintainer feedback.
+
+Do not use an LLM or automated agent to autonomously post comments, reviews, or replies, or to flood maintainers with
+unfiltered output. Contributions and discussions should present concise, relevant, human-reviewed information rather
+than transferring the burden of reviewing raw LLM output to the maintainers.
+
 # Pull requests: bugfixes, new features or other code contributions
 
 Pull requests are welcome! May it be a PR to an already known issue or a new feature that you consider as a valuable
@@ -32,4 +54,4 @@ changes, once approved, will be included in the next release.
 
 # Roadmap 
 
-No concrete roadmap or timeline exists. When the time is right, we continue adding support for newer games as well.
+No concrete roadmap or timeline exists. When the time is right, we continue adding support for newer games as well.