diff --git a/cmd/review-bot/main.go b/cmd/review-bot/main.go
index 359d080..673b076 100644
--- a/cmd/review-bot/main.go
+++ b/cmd/review-bot/main.go
@@ -59,7 +59,7 @@ func main() {
 	provider := flag.String("provider", envOrDefault("VCS_PROVIDER", "gitea"), "VCS provider: gitea or github")
 	baseURL := flag.String("base-url", envOrDefault("VCS_BASE_URL", ""), "VCS API base URL (for github provider; defaults to https://api.github.com)")
 	vcsURL := flag.String("vcs-url", envOrDefault("VCS_URL", envOrDefault("GITEA_URL", envOrDefault("GITHUB_SERVER_URL", ""))), "VCS instance URL (Gitea) [deprecated alias: --gitea-url]")
-	// Keep --gitea-url as hidden alias (flag package doesn't support aliases natively, handle below)
+	// Keep --gitea-url as backward-compatible alias (flag package doesn't support aliases natively, handle below)
 	repo := flag.String("repo", envOrDefault("VCS_REPO", envOrDefault("GITEA_REPO", envOrDefault("GITHUB_REPOSITORY", ""))), "Repository (owner/name)")
 	prNum := flag.String("pr", envOrDefault("PR_NUMBER", ""), "Pull request number")
 	reviewerName := flag.String("reviewer-name", envOrDefault("REVIEWER_NAME", ""), "Reviewer display name")
@@ -84,7 +84,9 @@ func main() {
 	aicoreAPIURL := flag.String("aicore-api-url", envOrDefault("AICORE_API_URL", ""), "SAP AI Core API URL (for provider=aicore)")
 	aicoreResourceGroup := flag.String("aicore-resource-group", envOrDefault("AICORE_RESOURCE_GROUP", "default"), "SAP AI Core resource group (for provider=aicore)")
 
-	// Register --gitea-url as a deprecated alias for --vcs-url
+	// Register --gitea-url as a backward-compatible alias for --vcs-url.
+	// StringVar shares the *string pointer with vcsURL, so whichever flag is
+	// set last by flag.Parse wins — both point to the same underlying value.
 	flag.StringVar(vcsURL, "gitea-url", *vcsURL, "Deprecated: use --vcs-url instead")
 
 	flag.Parse()
@@ -535,7 +537,7 @@ func supersedeOldReviews(ctx context.Context, client vcs.Client, provider, vcsUR
 		}
 		return nil
 	case "gitea":
-		// Fall through to Gitea-specific logic below the switch.
+		// Continue to Gitea-specific logic below the switch.
 	default:
 		return fmt.Errorf("supersedeOldReviews: unsupported provider %q", provider)
 	}
diff --git a/github/reviews.go b/github/reviews.go
index 1d8066f..1f877e0 100644
--- a/github/reviews.go
+++ b/github/reviews.go
@@ -80,7 +80,8 @@ func (c *Client) PostReview(ctx context.Context, owner, repo string, number int,
 			Body:     comment.Body,
 		}
 		payload.Comments = append(payload.Comments, rc)
-		// Use CommitID from the first comment that has one
+		// Use CommitID from the first comment that has one.
+		// All comments in a single review are expected to reference the same commit.
 		if payload.CommitID == "" && comment.CommitID != "" {
 			payload.CommitID = comment.CommitID
 		}