diff --git a/templates/docker-compose-runner.yml.tpl b/templates/docker-compose-runner.yml.tpl
index 8bdd9f0..115d6a3 100644
--- a/templates/docker-compose-runner.yml.tpl
+++ b/templates/docker-compose-runner.yml.tpl
@@ -1,3 +1,9 @@
+# Gitea Actions runner Docker Compose — rendered by manage_runner.sh (add_docker_runner)
+# Variables: ACT_RUNNER_VERSION, RUNNER_NAME, GITEA_INTERNAL_URL,
+#            RUNNER_REG_TOKEN, RUNNER_LABELS_CSV, RUNNER_DATA_PATH,
+#            RUNNER_DEPLOY_RESOURCES
+# Deployed to ${RUNNER_DATA_PATH}/docker-compose.yml on the target host.
+
 version: "3"
 
 services:
@@ -6,11 +12,11 @@ services:
     container_name: gitea-runner-${RUNNER_NAME}
     restart: unless-stopped
     environment:
-      - GITEA_INSTANCE_URL=${GITEA_INTERNAL_URL}
-      - GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_REG_TOKEN}
-      - GITEA_RUNNER_NAME=${RUNNER_NAME}
-      - GITEA_RUNNER_LABELS=${RUNNER_LABELS_CSV}
+      - GITEA_INSTANCE_URL=${GITEA_INTERNAL_URL}               # Gitea API base URL
+      - GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_REG_TOKEN}     # One-time registration token
+      - GITEA_RUNNER_NAME=${RUNNER_NAME}                        # Display name in Gitea admin
+      - GITEA_RUNNER_LABELS=${RUNNER_LABELS_CSV}                # Label specs (e.g. linux:docker://image)
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-      - ${RUNNER_DATA_PATH}:/data
+      - /var/run/docker.sock:/var/run/docker.sock   # Required: runner spawns job containers via host Docker
+      - ${RUNNER_DATA_PATH}:/data                   # Runner state, cache, and config
 ${RUNNER_DEPLOY_RESOURCES}