diff --git a/templates/runner-config.yaml.tpl b/templates/runner-config.yaml.tpl
index 1d107bc..472898c 100644
--- a/templates/runner-config.yaml.tpl
+++ b/templates/runner-config.yaml.tpl
@@ -1,26 +1,29 @@
-# act_runner configuration — rendered from runner-config.yaml.tpl
+# act_runner configuration — rendered by manage_runner.sh
+# Variables: RUNNER_NAME, RUNNER_LABELS_YAML, RUNNER_CAPACITY
+# Deployed alongside docker-compose.yml (docker) or act_runner binary (native).
+
 log:
   level: info
 
 runner:
   name: ${RUNNER_NAME}
-  labels:
+  labels:                       # Label specs define what workflows this runner picks up.
 ${RUNNER_LABELS_YAML}
-  capacity: ${RUNNER_CAPACITY}
-  timeout: 3h
-  insecure: false
-  fetch_timeout: 5s
-  fetch_interval: 2s
+  capacity: ${RUNNER_CAPACITY}  # Max concurrent jobs. Constrained by host CPU/RAM.
+  timeout: 3h                   # Kill jobs that run longer than this.
+  insecure: false               # Require valid TLS when talking to Gitea.
+  fetch_timeout: 5s             # Timeout for fetching new jobs from Gitea.
+  fetch_interval: 2s            # How often to poll Gitea for pending jobs.
 
 cache:
   enabled: true
-  dir: ""
+  dir: ""                       # Empty = default cache directory inside /data.
 
 container:
-  network: ""
-  privileged: false
+  network: ""                   # Empty = use default Docker network.
+  privileged: false             # Never run job containers as privileged.
   options:
   workdir_parent:
 
 host:
-  workdir_parent:
+  workdir_parent:               # Only used by native runners (type=native).