docs: add operational notes to AGENTS.md

Author: xnoto

AGENTS.md

@@ -21,9 +21,32 @@ make test
 
 This automatically fetches the canonical config if not present.
 
-## Special Configuration
+## CI/CD
 
-This repo uses `arc-dind` runner with an internal OpenShift registry image (`tfroot-runner`) because it requires SSH access to libvirt hosts.
+This repo uses the shared `opentofu.yml` workflow from `shared-workflows`, but with **custom configuration**:
+
+- **Runner:** `arc-dind` (self-hosted, not `ubuntu-latest`)
+- **Container:** `image-registry.openshift-image-registry.svc:5000/public-registry/tfroot-runner:latest` (internal OpenShift registry, not GHCR)
+
+This is required because the workflow needs SSH access to libvirt hosts, which is only available from the self-hosted runner network.
+
+### Failure Modes
+
+**"name unknown" or image pull failures:** The `tfroot-runner` image doesn't exist in the OpenShift internal registry. This happens when:
+
+1. The `images` repo Build workflow failed (check for transient network errors, re-run if needed)
+2. The `images` repo Pull workflow failed to import (the `|| true` masks failures - check logs for "Unable to connect" errors)
+
+**To fix:** Re-run the Pull workflow in the `images` repo, or manually import:
+```bash
+oc import-image tfroot-runner:latest \
+  --from=ghcr.io/makeitworkcloud/tfroot-runner:latest \
+  -n public-registry \
+  --confirm \
+  --reference-policy=local
+```
+
+**Pre-commit failures:** If hooks fail unexpectedly, the canonical config may have changed. Delete `.pre-commit-config.yaml` locally and re-run `make test` to fetch the latest.
 
 ## Related Repositories