diff --git a/.gitignore b/.gitignore
index 5dd507e..b574eaf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,4 @@
 /.vscode/
 /dist/
 /bin/
-/distro.zip
-/HANDOFF.md
\ No newline at end of file
+/distro.zip
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fce234a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,20 @@
+# AGENTS.md
+
+Guidance for agents working in this repo.
+
+## Structure
+- Parent repo integrates five submodules built and packaged for Debian 13: `libg15`, `libg15render`, `g15daemon`, `g15macro`, `g15stats`.
+- `packaging/` holds all build/CI logic; `.gitea/workflows/` and `.github/workflows/` both call into the same shared scripts rather than duplicating build logic.
+
+## Building
+- `bash packaging/local-build.sh` (also available as the default VS Code build task) builds all five Debian source+binary packages into gitignored `dist/`, and extracts plain executables/shared libraries into gitignored `bin/`.
+- `packaging/build.sh` requires every submodule to be clean (`git status --porcelain --untracked-files=all` empty) and checked out exactly at its parent's pinned gitlink commit — it refuses to build otherwise. Regenerable host build artifacts (autotools `Makefile`, `config.*`, `libtool`, `stamp-h1`, `.deps/`) left over from a manual `./configure && make` are untracked but still count as dirty; remove them (safe, regenerable) rather than committing them.
+- `packaging/run.sh` / `packaging/ci.sh` wrap `build.sh`+`test.sh` in disposable Docker containers for host/CI use; inside this devcontainer (already root, already `/.dockerenv`, already has all packaging tools installed) `build.sh`/`test.sh` can be run directly without nested Docker.
+- See `packaging/NOTES.md` for full packaging/versioning/CI policy details.
+
+## Submodule workflow
+- Commit and push submodule changes in the submodule's own repo first, then update and push the parent gitlink pointer — this keeps the parent's gitlink always fetchable.
+- Never blindly `git add -A` a submodule; stage real source/doc changes explicitly and exclude generated build state.
+
+## Known technical constraint
+- g15stats renders on a bitmap-only canvas allocation; do not switch it to the ABI-dependent (optionally TTF-enabled) `libg15render` canvas initializer — a smaller bitmap-only allocation plus a larger installed renderer ABI has previously corrupted the heap at startup (`malloc(): invalid size`).