diff --git a/.env.example b/.env.example
index b4e9acd..c15dac7 100644
--- a/.env.example
+++ b/.env.example
@@ -5,6 +5,15 @@ GITEA_URL=https://git.example.com
 # Admin → Actions → Runners → Create Registration Token
 GITEA_REGISTRATION_TOKEN=your-registration-token
 
+# Gitea admin API token for post-install integration test (optional).
+# The runner registration token above is NOT sufficient for the
+# /api/v1/admin/runners endpoint; it is only valid for registration.
+# To verify the runner appears in Gitea after install, generate a
+# personal access token with at least the "admin" scope:
+#   Settings → Applications → Generate New Token → scope: admin
+# If left unset, the integration test is skipped gracefully.
+# GITEA_ADMIN_TOKEN=your-admin-api-token
+
 # Default SSH user for remote hosts (optional, overrides --user)
 # GITEA_RUNNER_USER=ubuntu