docs(auth): add JSDoc comments to OAuth utilities

app/plugins/auth.client.ts

@@ -1,5 +1,23 @@
 import { useAuth } from '../composables/useAuth';
 
+/**
+ * Authentication plugin that initializes auth state on app mount (client-side only).
+ *
+ * This plugin automatically:
+ * - Restores the user session from Pocketbase's authStore on page load
+ * - Sets up cross-tab synchronization via Pocketbase's onChange listener
+ * - Enables session persistence across page refreshes
+ *
+ * **Lifecycle**: Runs once on app mount, before any pages are rendered.
+ *
+ * **Cross-Tab Sync**: When a user logs in or out in one browser tab, all other tabs
+ * automatically update their auth state within ~2 seconds (handled by Pocketbase SDK).
+ *
+ * **Session Restoration**: On page refresh, the plugin checks Pocketbase's authStore
+ * and restores the user object if a valid session exists.
+ *
+ * @see {@link useAuth} for the auth composable API
+ */
 export default defineNuxtPlugin(() => {
   const { initAuth } = useAuth();
   initAuth();