Improve documentation for GraphQL-Features transport

Co-authored-by: SamMorrowDrums <[email protected]>

Author: Copilot

pkg/github/issues.go

@@ -1914,15 +1914,22 @@ func AssignCodingAgentPrompt(t translations.TranslationHelperFunc) inventory.Ser
 	)
 }
 
-// graphQLFeaturesKey is a context key for GraphQL feature flags
+// graphQLFeaturesKey is a context key for GraphQL feature flags.
+// These flags enable preview or experimental GitHub API features that are not yet GA.
 type graphQLFeaturesKey struct{}
 
-// withGraphQLFeatures adds GraphQL feature flags to the context
+// withGraphQLFeatures adds GraphQL feature flags to the context.
+// The flags are read by GraphQLFeaturesTransport and sent as the GraphQL-Features header.
+// This is used internally by tool handlers that require experimental GitHub API features.
 func withGraphQLFeatures(ctx context.Context, features ...string) context.Context {
 	return context.WithValue(ctx, graphQLFeaturesKey{}, features)
 }
 
-// GetGraphQLFeatures retrieves GraphQL feature flags from the context
+// GetGraphQLFeatures retrieves GraphQL feature flags from the context.
+// This function is exported to allow custom HTTP transports (e.g., in remote servers)
+// to read feature flags and add them as the "GraphQL-Features" header.
+//
+// For most use cases, use GraphQLFeaturesTransport instead of calling this directly.
 func GetGraphQLFeatures(ctx context.Context) []string {
 	if features, ok := ctx.Value(graphQLFeaturesKey{}).([]string); ok {
 		return features

pkg/github/transport.go

@@ -10,15 +10,32 @@ import (
 //
 // This transport should be used in the HTTP client chain for githubv4.Client
 // to ensure GraphQL feature flags are properly sent to the GitHub API.
+// Without this transport, certain GitHub API features (like Copilot assignment)
+// that require feature flags will fail with schema validation errors.
 //
-// Example usage:
+// Example usage for local server (layering with auth):
+//
+//	httpClient := &http.Client{
+//		Transport: &github.GraphQLFeaturesTransport{
+//			Transport: &authTransport{
+//				Transport: http.DefaultTransport,
+//				token:     "ghp_...",
+//			},
+//		},
+//	}
+//	gqlClient := githubv4.NewClient(httpClient)
+//
+// Example usage for remote server (simple case):
 //
 //	httpClient := &http.Client{
 //		Transport: &github.GraphQLFeaturesTransport{
 //			Transport: http.DefaultTransport,
 //		},
 //	}
 //	gqlClient := githubv4.NewClient(httpClient)
+//
+// The transport reads feature flags from request context using GetGraphQLFeatures.
+// Feature flags are added to context by the tool handler via withGraphQLFeatures.
 type GraphQLFeaturesTransport struct {
 	// Transport is the underlying http.RoundTripper. If nil, http.DefaultTransport is used.
 	Transport http.RoundTripper