diff --git a/src/lib/services/document-folders.service.ts b/src/lib/services/document-folders.service.ts
index 46ca9541..abee0846 100644
--- a/src/lib/services/document-folders.service.ts
+++ b/src/lib/services/document-folders.service.ts
@@ -324,6 +324,12 @@ export async function ensureSystemRoots(portId: string, userId: string): Promise
     createdBy: userId,
   }));
 
+  // ON CONFLICT DO NOTHING with no target is safe here because root
+  // inserts can only collide on `uniq_document_folders_sibling_name`
+  // (entityId is null on roots, so the partial index
+  // `uniq_document_folders_entity` is excluded). Do not copy this
+  // pattern into helpers that insert per-entity subfolders — they
+  // need an explicit target to avoid masking real conflicts.
   await db.insert(documentFolders).values(values).onConflictDoNothing();
 
   const rows = await db
diff --git a/src/lib/services/ports.service.ts b/src/lib/services/ports.service.ts
index 9dc837ea..0bab8542 100644
--- a/src/lib/services/ports.service.ts
+++ b/src/lib/services/ports.service.ts
@@ -41,6 +41,8 @@ export async function createPort(data: CreatePortInput, meta: AuditMeta) {
     })
     .returning();
 
+  // Non-fatal if this throws: ensureSystemRoots is re-runnable, and
+  // scripts/backfill-document-folders.ts heals orphaned ports.
   await ensureSystemRoots(port!.id, meta.userId);
 
   void createAuditLog({