diff --git a/jam-ui/src/helpers/chatStorage.js b/jam-ui/src/helpers/chatStorage.js
index 286196e2d..541375a98 100644
--- a/jam-ui/src/helpers/chatStorage.js
+++ b/jam-ui/src/helpers/chatStorage.js
@@ -3,6 +3,20 @@
  *
  * Stores lastReadAt timestamps for each chat channel to track unread status
  * across browser sessions. Data is stored as JSON object keyed by channel ID.
+ *
+ * Storage format:
+ * ```json
+ * {
+ *   "session-abc": "2026-01-26T12:00:00Z",
+ *   "global": "2026-01-26T13:00:00Z",
+ *   "lesson-123": "2026-01-26T14:00:00Z"
+ * }
+ * ```
+ *
+ * Error handling:
+ * - All functions catch and log errors without throwing
+ * - Quota exceeded errors are handled gracefully (data won't be saved but app continues)
+ * - JSON parse errors return empty object to allow graceful degradation
  */
 
 const STORAGE_KEY = 'jk_chat_lastReadAt';