From 5feb3ac81ed88822c8156fd4ce88142cdb2793d1 Mon Sep 17 00:00:00 2001
From: TheGeneralist <180094941+thegeneralist01@users.noreply.github.com>
Date: Sat, 24 Jan 2026 17:26:20 +0100
Subject: [PATCH] docs: add forgejo runner state dir notes

---
 AGENTS.md | 5 +++++
 1 file changed, 5 insertions(+)

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.