diff --git a/internal/featuredetection/feature_detection.go b/internal/featuredetection/feature_detection.go
index f0759bd3e..d4ef62070 100644
--- a/internal/featuredetection/feature_detection.go
+++ b/internal/featuredetection/feature_detection.go
@@ -24,11 +24,29 @@ type Detector interface {
 
 type IssueFeatures struct {
 	// TODO ApiActorsSupported
-	// ApiActorsSupported indicates the host supports actor-based APIs
-	// (replaceActorsForAssignable, requestReviewsByLogin, suggestedAssignableActors, etc.).
-	// True for github.com and ghe.com. False for GHES.
-	// Remove this flag once GHES supports these mutations, then collapse all
-	// // TODO ApiActorsSupported sites to the actor-only path.
+	// ApiActorsSupported indicates the host supports actor-based APIs. True for
+	// github.com and ghe.com, false for GHES.
+	//
+	// The GitHub API has two generations of assignee/reviewer types:
+	//
+	// Legacy (GHES): Uses AssignableUser (users only) and node-ID-based mutations.
+	//   - assignableUsers query returns []AssignableUser
+	//   - Mutations take node IDs (assigneeIds, userReviewerIds, teamReviewerIds)
+	//
+	// Actor-based (github.com): Uses AssignableActor (User + Bot union) and
+	// login-based mutations, enabling assignment of non-user actors like Copilot.
+	//   - suggestedActors query returns []AssignableActor (User | Bot)
+	//   - suggestedReviewerActors returns []ReviewerCandidate (User | Bot | Team)
+	//   - Mutations take logins (replaceActorsForAssignable, requestReviewsByLogin)
+	//
+	// When GHES adds support for the actor-based types and mutations, this flag
+	// can be removed and all // TODO ApiActorsSupported sites collapsed to the
+	// actor-only path. To verify GHES support, check whether the GHES GraphQL
+	// schema includes:
+	//   - The suggestedActors field on Repository (assignee search)
+	//   - The suggestedReviewerActors field on PullRequest (reviewer search)
+	//   - The replaceActorsForAssignable mutation
+	//   - The requestReviewsByLogin mutation
 	ApiActorsSupported bool
 }