diff --git a/AGENTS.md b/AGENTS.md
index deafdf2..17b608a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -155,6 +155,11 @@ lib: inputs: self: lib.mkSystem "<os>" ./configuration.nix
 2. Check file extension is `.nix`
 3. Ensure valid Nix syntax
 
+### Forgejo Actions Runner (NixOS)
+1. `DynamicUser` conflicts require `lib.mkForce` if overriding module defaults.
+2. Runner state dir should be `/var/lib/gitea-runner/<instance>`; set `StateDirectory = "gitea-runner"` and let the instance name append.
+3. If the register script fails with `permission denied`, ensure `/var/lib/gitea-runner` exists and is owned by `gitea-runner`.
+
 ### Nushell Warnings
 1. Deprecated `get -i` warning from direnv integration is a short-term workaround in `modules/common/shell/direnv.nix` (custom Nushell hook with `get -o` and HM integration disabled) until upstream home-manager updates.