docs(sync): align google connect and auth hook docs

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

Author: cursoragent

docs/development/feature-file-map.md

@@ -16,8 +16,8 @@ Use this document to find the first files to inspect for common Compass changes.
 
 - Session initialization and SuperTokens wiring: `packages/web/src/auth/session/SessionProvider.tsx`
 - User profile bootstrap: `packages/web/src/auth/context/UserProvider.tsx`
-- Google OAuth app flow: `packages/web/src/auth/hooks/oauth/useGoogleAuth.ts`, `packages/web/src/auth/hooks/oauth/useGoogleAuthWithOverlay.ts`
-- Google OAuth provider wrapper: `packages/web/src/components/oauth/google/useGoogleLogin.ts`
+- Google OAuth app flow: `packages/web/src/auth/hooks/google/useGoogleAuth/useGoogleAuth.ts`, `packages/web/src/auth/hooks/google/useGoogleAuthWithOverlay/useGoogleAuthWithOverlay.ts`
+- Google OAuth provider wrapper: `packages/web/src/auth/hooks/google/useGoogleLogin/useGoogleLogin.ts`
 - Popup-cancel classification for Google OAuth: `packages/web/src/auth/google/google-oauth-error.util.ts`
 - Auth schemas: `packages/web/src/auth/schemas/auth.schemas.ts`
 - Backend auth routes: `packages/backend/src/auth/auth.routes.config.ts`
@@ -63,7 +63,7 @@ Use this document to find the first files to inspect for common Compass changes.
 - Sidebar shell and tab rendering: `packages/web/src/views/Calendar/components/Sidebar/Sidebar.tsx`
 - Footer icon row actions (tasks/month, command palette, sync/update): `packages/web/src/views/Calendar/components/Sidebar/SidebarIconRow/SidebarIconRow.tsx`
 - Sidebar layout constants and icon group styling: `packages/web/src/views/Calendar/components/Sidebar/styled.ts`
-- Google connection/status UI contract for sidebar + command palette: `packages/web/src/auth/hooks/oauth/useConnectGoogle.ts`
+- Google connection/status UI contract for sidebar + command palette: `packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts`
 - Sidebar icon row behavior tests: `packages/web/src/views/Calendar/components/Sidebar/SidebarIconRow/SidebarIconRow.test.tsx`
 
 ## Offline Storage

docs/development/troubleshoot.md

@@ -85,3 +85,26 @@ Operational notes:
 - UI should transition to reconnect-required behavior rather than repeatedly
   retrying repair
 - user action is to reconnect Google, then allow sync/import restart
+
+## Google Connect Aborts With Local Events Sync Error
+
+When a password-authenticated user connects Google from an existing session, the
+client now attempts to sync IndexedDB-only Compass events **before**
+`POST /api/auth/google/connect`.
+
+If that pre-connect local sync fails, connect is intentionally aborted and the
+user sees:
+
+- `We could not sync your local events. Your changes are still saved on this device.`
+
+What this means operationally:
+
+- this is a local-to-cloud event migration failure, not an OAuth popup failure
+- backend `connectGoogleToCurrentUser` is not called for that attempt
+- no Google import restart should be observed from that click
+
+Recommended triage:
+
+1. inspect browser console/network for the local event sync request failure
+2. resolve connectivity/auth issues to Compass APIs first
+3. retry Google connect after local sync succeeds

docs/features/google-sync-and-websocket-flow.md

@@ -25,7 +25,6 @@ Important server-to-client events:
 Source files:
 
 - `packages/core/src/types/websocket.types.ts`
-- `packages/backend/src/user/services/user.service.ts`
 - `packages/backend/src/sync/services/sync.service.ts`
 
 `IMPORT_GCAL_END` now carries an explicit `operation` so the client can distinguish
@@ -282,17 +281,23 @@ When a user authenticates with email/password first and connects Google later
 from an existing session:
 
 1. the web client completes the Google popup flow
-2. `useConnectGoogle()` sends the auth-code payload to
-   `POST /api/auth/google/connect`
-3. backend `connectGoogleToCurrentUser()` attaches Google credentials to the
+2. `useConnectGoogle()` first calls `syncPendingLocalEvents(dispatch)` so
+   IndexedDB-only Compass events are pushed before any Google refresh
+3. if local sync fails, connect is aborted and the user sees:
+   - `We could not sync your local events. Your changes are still saved on this device.`
+4. on successful local sync, `useConnectGoogle()` sends the auth-code payload
+   to `POST /api/auth/google/connect`
+5. backend `connectGoogleToCurrentUser()` attaches Google credentials to the
    existing Compass user
-4. backend marks sync metadata as `"RESTART"`
-5. background import/watch sync is restarted
+6. backend marks sync metadata as `"RESTART"`
+7. background import/watch sync is restarted
 
 Operational constraints:
 
 - this path no longer depends on SuperTokens `AccountLinking`
 - Google-account ownership is checked server-side by `google.googleId`
+- connect is intentionally blocked when local event sync fails; this prevents
+  local-only Compass events from disappearing during Google-triggered refresh
 - restart still follows the same metadata/socket lifecycle
   (`IMPORT_GCAL_START`, metadata transitions, `IMPORT_GCAL_END`)
 
@@ -302,7 +307,8 @@ Primary files:
 - `packages/backend/src/auth/services/google/google.auth.service.ts`
 - `packages/backend/src/auth/controllers/auth.controller.ts`
 - `packages/web/src/auth/google/google.auth.state.ts`
-- `packages/web/src/auth/hooks/oauth/useConnectGoogle.ts`
+- `packages/web/src/auth/google/google.auth.util.ts`
+- `packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts`
 - `packages/web/src/common/repositories/event/event.repository.util.ts`
 
 ### Connect-Later Ownership Conflict Triage
@@ -390,7 +396,7 @@ Google import progress is also realtime:
 Source files:
 
 - `packages/web/src/socket/hooks/useGcalSync.ts`
-- `packages/web/src/auth/hooks/oauth/useConnectGoogle.ts`
+- `packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts`
 - `packages/web/src/ducks/events/slices/sync.slice.ts`
 
 `IMPORT_GCAL_END` handling is operation-aware:

docs/frontend/frontend-runtime-flow.md

@@ -77,8 +77,8 @@ When a user re-authenticates with Google, auth-state utilities also clear any in
 
 Files:
 
-- `packages/web/src/auth/hooks/oauth/useGoogleAuth.ts`
-- `packages/web/src/components/oauth/google/useGoogleLogin.ts`
+- `packages/web/src/auth/hooks/google/useGoogleAuth/useGoogleAuth.ts`
+- `packages/web/src/auth/hooks/google/useGoogleLogin/useGoogleLogin.ts`
 - `packages/web/src/auth/google/google-oauth-error.util.ts`
 
 The web auth flow intentionally treats popup-close outcomes as cancellation, not authentication failure.
@@ -134,7 +134,7 @@ Files:
 - `packages/web/src/views/Calendar/components/Sidebar/Sidebar.tsx`
 - `packages/web/src/views/Calendar/components/Sidebar/SidebarIconRow/SidebarIconRow.tsx`
 - `packages/web/src/views/Calendar/components/Sidebar/styled.ts`
-- `packages/web/src/auth/hooks/oauth/useConnectGoogle.ts`
+- `packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts`
 
 Layout contract:
 
@@ -330,7 +330,8 @@ Runtime nuances:
 
 Files:
 
-- `packages/web/src/auth/hooks/oauth/useConnectGoogle.ts`
+- `packages/web/src/auth/hooks/google/useConnectGoogle/useConnectGoogle.ts`
+- `packages/web/src/auth/google/google.auth.util.ts`
 - `packages/web/src/views/Calendar/components/Sidebar/SidebarIconRow/SidebarIconRow.tsx`
 
 UI state comes from a single server-enriched metadata field (`google.connectionState`) plus one client-only loading state:
@@ -346,6 +347,15 @@ Important constraint:
 
 - `connectionState` values are uppercase string literals shared with backend/core (`NOT_CONNECTED`, `RECONNECT_REQUIRED`, `IMPORTING`, `HEALTHY`, `ATTENTION`); lowercase variants will not match UI state guards.
 
+Connect-later guardrail:
+
+- In the password-session "connect Google" flow, `useConnectGoogle` calls
+  `syncPendingLocalEvents(dispatch)` before `AuthApi.connectGoogle(...)`.
+- If local sync fails, connect is aborted and a toast is shown:
+  `"We could not sync your local events. Your changes are still saved on this device."`
+- This prevents IndexedDB-only Compass events from disappearing during the
+  Google-triggered metadata/import refresh.
+
 ## What To Read Before Editing
 
 - Auth/session issue: read session provider, user provider, router loaders.