Standards alignment: Document .js tools deviation, fix port 3030, enhance tool documentation

tools/user-alert/index.js

@@ -1,6 +1,18 @@
 /**
  * User Alert System
  * Monitors shared notes and alerts when someone shares a note with the current user
+ * 
+ * @module UserAlertSystem
+ * @description Standalone utility for monitoring PocketBase note collection changes.
+ *   Watches for notes shared with current user and triggers desktop notifications and
+ *   audio alerts. Exports UserAlertSystem class for instantiation with PocketBase instance.
+ * @usage Instantiate with PocketBase instance: new UserAlertSystem(pb, userEmail, userName).
+ *   Call watchForSharedNotes() to start monitoring.
+ * @dependencies PocketBase instance (passed in constructor). Browser APIs: Notifications,
+ *   Web Audio API, DOM manipulation.
+ * @integration Used in index.html to provide real-time alert functionality for shared notes
+ * @gotchas Requires user permission for desktop notifications. Audio context may be blocked
+ *   on some browsers until user gesture. Track alertedNotes Set to prevent duplicate alerts.
  */
 
 export class UserAlertSystem {