Document Forgejo API administration pattern

AGENTS.md

@@ -91,6 +91,37 @@ ssh -L 29316:localhost:29316 root@ops-jrz1
 ssh -L 8008:localhost:8008 root@ops-jrz1
 ```
 
+### Forgejo Administration
+```bash
+# Find the correct gitea binary (Forgejo uses gitea internally)
+# Use the version matching your deployed Forgejo - check with: systemctl status forgejo
+GITEA_BIN=$(find /nix/store -name "gitea" -path "*forgejo-7*" -type f -executable | head -1)
+
+# Generate a scoped API token (runs as forgejo user)
+ssh root@ops-jrz1 "sudo -u forgejo $GITEA_BIN admin user generate-access-token \\
+  --username dan \\
+  --token-name 'temp-task-name' \\
+  --scopes 'write:repository,read:repository' \\
+  --config /var/lib/forgejo/custom/conf/app.ini"
+
+# Common scopes:
+#   write:admin,read:admin,write:user  - User provisioning (dev-add.sh)
+#   write:repository,read:repository   - Repo settings (default branch, etc.)
+
+# Update repo settings (e.g., default branch)
+ssh root@ops-jrz1 'curl -s -X PATCH "http://localhost:3000/api/v1/repos/OWNER/REPO" \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{\"default_branch\": \"main\"}"'
+
+# After using temp token, delete via: https://git.clarun.xyz/user/settings/applications
+```
+
+**Gotchas:**
+- Token at `/run/secrets/forgejo-api-token` has admin scope only (for dev-add.sh)
+- Binary version must match DB schema - newer binaries fail with column errors
+- Forgejo API docs: https://git.clarun.xyz/api/swagger
+
 ## Coding Conventions
 
 - Two-space indentation in Nix files