diff --git a/src/resources/extensions/sf/notification-overlay.ts b/src/resources/extensions/sf/notification-overlay.ts
index 1103f5fcf..c0bb3fdb6 100644
--- a/src/resources/extensions/sf/notification-overlay.ts
+++ b/src/resources/extensions/sf/notification-overlay.ts
@@ -90,6 +90,10 @@ function formatTimestamp(ts: string): string {
 	}
 }
 
+/**
+ * Compute a string signature of notification entries for change detection.
+ * Used to detect mutations across processes without re-reading entire file.
+ */
 function notificationSignature(entries: readonly NotificationEntry[]): string {
 	return entries
 		.map(
diff --git a/src/resources/extensions/sf/self-feedback.ts b/src/resources/extensions/sf/self-feedback.ts
index 65e8b6c87..8ba6f160e 100644
--- a/src/resources/extensions/sf/self-feedback.ts
+++ b/src/resources/extensions/sf/self-feedback.ts
@@ -250,8 +250,8 @@ function readActiveUnit(basePath: string): SelfFeedbackOccurredIn | undefined {
 // ─── Public API ────────────────────────────────────────────────────────────
 
 /**
- * Record a self-feedback entry. Non-fatal — write errors are swallowed and
- * a null result is returned so callers can branch on success without try/catch.
+ * Record a self-feedback entry to the appropriate channel (project or upstream).
+ * Non-fatal — write errors are swallowed and null is returned on failure.
  */
 export function recordSelfFeedback(
 	entry: SelfFeedbackEntry,