GRM-32: fix: security, dead code, idempotence, and documentation cleanup

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md — Project Conventions for GRM
+
+## Build & Test Commands
+
+```bash
+make setup          # Create venv, install deps, set up hooks
+make lint-all       # ruff + pyright + bandit + ansible-lint + checkmake
+make pytest-cov     # Unit tests with 100% coverage enforcement
+make test-unit      # Unit tests without coverage
+make molecule       # All 6 scenarios on Ubuntu 22.04
+make molecule-all   # All 6 scenarios on all 4 supported OSes
+make test-all       # pytest-cov + molecule
+```
+
+## Architecture
+
+- **Python CLI** (`src/gitea_runner_manager/`) — Click-based CLI that delegates to Ansible
+- **Ansible Role** (`ansible/roles/gitea-runner/`) — Idempotent role for rootless Docker runner setup
+- **CI Scripts** (`scripts/`) — Automation for auto-merge, post-merge, publishing, molecule distribution
+
+## Key Conventions
+
+- Python 3.12+ required (ruff/pyright target `py312`)
+- 100% test coverage required (`--cov-fail-under=100`)
+- Conventional commits on feature branches (no `GRM-N:` prefix)
+- `GRM-N:` prefix on master branch (added by auto-merge)
+- Branch names must include `GRM-N` task ID
+- Line length: 120 chars
+- Secrets are passed via temp JSON files, never on the command line (CWE-214)
+
+## Ansible Role Structure
+
+```
+main.yml → systemd_check → user_setup → rootless_docker → install_runner → prune → integration_test
+```
+
+- `install_runner.yml` handles: download, config, validate, register, service
+- `main.yml` handles: prune, integration_test (NOT install_runner — avoids duplicates)
+- All `systemctl --user` tasks must be guarded by `docker_rootless_setup`
+- All template creation tasks must be guarded by `docker_rootless_setup`
+
+## Molecule Scenarios
+
+6 scenarios: `default`, `multi-instance`, `lifecycle`, `template-content`, `deregister`, `update`
+4 platforms: `ubuntu-2204`, `ubuntu-2404`, `debian-12`, `archlinux`
+Platform list is defined in `scripts/distribute_molecule.py` (single source of truth)
+
+## Known Issues
+
+- `ansible-lint` may warn about `command-instead-of-module` for `systemctl --user` calls — this is expected (systemd module doesn't support user services) and skipped in `.ansible-lint`
+- Molecule Docker driver may print "Event loop is closed" warnings on interrupt — harmless