new file mode 100644
@@ -0,0 +1,85 @@
+# AGENTS.md — pseudo
+
+Guidance for AI agents working in the `pseudo` repository.
+
+## Making changes
+
+- No web PR workflow. The project uses **patches on mailing lists**
+ (yocto-patches@lists.yoctoproject.org). Don't assume GitHub PR
+ conventions apply. Subject on the mailing list must include
+ '[pseudo]'.
+- One Git commit per logical change (e.g., one commit per fix, refactor or new test).
+- Split unrelated changes, even small ones found along the way: a bug
+ noticed during a refactor gets its own commit.
+- Keep every commit building cleanly, with tests passing, so the series
+ bisects. Put a new test after the fix it checks.
+- Commit message format:
+ - Summary line prefixed with the component or short file path,
+ e.g. `pseudo_util: Remove stale with_libpseudo() comment`.
+ Check `git log --oneline <path>` for the prefix convention already in use.
+ - Body explains what/why/how, and how it was tested.
+ - Prefer explaining *why* a change was made over restating what's
+ already visible in the diff, unless the diff is long/hard to follow
+ or the reason for the change isn't known — in those cases, summarize
+ what changed instead.
+ - Be succinct: use as few sentences and lines as possible while still
+ covering what/why/how. Cut restatements, filler, and any detail a
+ reviewer wouldn't need (e.g. exact test-run counts, step-by-step
+ narration). One short paragraph is usually enough; only add a second
+ if a distinct point (e.g. testing) needs it.
+ - The most relevant information about the change should be presented first.
+ - Reference bugs as `[YOCTO #1234]` when applicable.
+ - Use `Reported-by`, `Suggested-by`, `Tested-by`, `Reviewed-by`, `Cc` tags
+ where relevant.
+
+### AI-generated code
+
+- **Mandatory**: any AI-generated code/commit must add an `AI-Generated:`
+ tag line in the commit message, placed *before* `Signed-off-by` (if present),
+ naming the tool used, e.g.:
+
+ ```
+ component: Add the ability to ...
+
+ AI-Generated: Uses GitHub Copilot
+ ```
+
+- **Mandatory** Do not automatically add a `Signed-off-by`. This tag must
+ always be written by the human contributor, never by the AI tool — the
+ DCO/Developer's Statement of Origin still applies in full.
+- Contributor is responsible for confirming the AI tool's terms don't
+ conflict with the project's open source license/IP policy, and that
+ any third-party copyrighted material in the AI output is properly
+ licensed before contributing it. See the Linux Foundation generative AI
+ guidance: https://www.linuxfoundation.org/legal/generative-ai.
+- `Co-authored-by` should be omitted in favor of the `AI-Generated` tag.
+ Don't add other tool-specific trailers either (e.g. `Copilot-Session`).
+
+## Building and testing
+
+- Configure and build: `./configure --prefix=$(pwd)/test && make`
+- Full test suite: `make test-verbose` (or `make test`). Single tests:
+ `./run_tests.sh -v test-name`.
+- Tests are `test/test-*.sh`, with optional `test/test-*.c` programs that
+ the Makefile builds automatically. A script exits 0 to pass and 255 to
+ report a skip; C helpers conventionally exit 77 for "not supported"
+ (for example ENOSYS), which the script maps to 255. Create temporary
+ trees below $PWD so pseudo tracks them.
+- Changes to the server, locking or path handling: also run the
+ test-parallel-* tests several times, as they are timing dependent.
+
+## Code layout
+
+- Wrappers are generated by `makewrappers` from `ports/*/wrapfuncs.in`,
+ `templates/` and the guts in `ports/*/guts/`. Don't edit the generated
+ files (pseudo_wrapfuncs.*, pseudo_wrapper_table.c, pseudo_ports.h,
+ port_wrappers.c).
+- Linux is the only port. Put port-specific definitions in
+ `ports/<port>/portdefs.h`. Where shared code needs something only one
+ port provides, fail with `#error` for other ports rather than silently
+ falling back.
+- Keep pseudo.1 and README.security in step with behaviour changes:
+ options, environment variables, diagnostics, security model.
+
+When in doubt about a convention, grep `git log --oneline <path>` in the
+target repo for precedent before inventing a new style.