diff --git a/go/agentfield-package.yaml b/go/agentfield-package.yaml
index 5e2d7b3..8bd7cfa 100644
--- a/go/agentfield-package.yaml
+++ b/go/agentfield-package.yaml
@@ -28,11 +28,16 @@ user_environment:
       description: LLM provider key (OpenRouter)
       type: secret
       scope: global
+  optional:
+    # Optional, not required: every use is lazy and degrades cleanly without it
+    # (github.NewClient falls back to unauthenticated API calls, clones only
+    # inject the token when set) — public repos review fine anonymously. The
+    # token is needed for private repos, posting reviews back to GitHub, and
+    # unthrottled API rate limits.
     - name: GH_TOKEN
-      description: GitHub token (repo scope)
+      description: GitHub token (repo scope) — needed only for private repos and posting reviews
       type: secret
       scope: global
-  optional:
     - name: AGENTFIELD_SERVER
       description: Control-plane URL
       default: http://localhost:8080
diff --git a/go/cmd/pr-af/main.go b/go/cmd/pr-af/main.go
index 2474060..b2905c1 100644
--- a/go/cmd/pr-af/main.go
+++ b/go/cmd/pr-af/main.go
@@ -18,7 +18,9 @@
 //	PR_AF_HARNESS_BIN   optional executable override for every harness provider
 //	OPENROUTER_API_KEY  LLM key — required for the .ai() gates; AIConfig is only
 //	                    attached when set (SDK rejects an empty key)
-//	GH_TOKEN            GitHub token for FetchPR/clone/PostReview
+//	GH_TOKEN            GitHub token for FetchPR/clone/PostReview (optional —
+//	                    public repos review anonymously; needed for private
+//	                    repos and posting reviews)
 //	GITHUB_WEBHOOK_SECRET  HMAC secret for /webhook/github (skip verify if unset)
 //	PR_AF_BOT_MENTION   webhook trigger mention (default @pr-af)
 package main