diff --git a/server/src/services/onboarding-seed.ts b/server/src/services/onboarding-seed.ts
index b8650d11515..9e3b5ee958c 100644
--- a/server/src/services/onboarding-seed.ts
+++ b/server/src/services/onboarding-seed.ts
@@ -233,6 +233,11 @@ export function onboardingSeedService(db: Db) {
         });
       } else {
         const projectId = await resolveOnboardingProjectId(companyId, goalId);
+        // The idempotency key is what protects two pushes that arrive at once
+        // — Cloud's reconcile runs off portfolio fetches, which can overlap.
+        // It is deliberately not revision-scoped: if the recorded issue is
+        // lost, a later revision should still dedupe against whatever the
+        // first push created.
         const created = await issueSvc.create(companyId, {
           title: firstTaskTitle,
           ...(firstTaskDetails ? { description: firstTaskDetails } : {}),