!fix: password reset flow (#1566)

* feat(delete): enhance deleteCompassDataForMatchingUsers to include Google Calendar access check

- Updated the deleteCompassDataForMatchingUsers function to accept a second parameter, gcalAccess, indicating whether the user has Google Calendar access.
- This change allows for more granular control over the deletion process based on the user's Google Calendar connection status.

* feat(auth): enhance AuthModal tests and URL handling for password reset flow

- Introduced a new `RouteLocationMirror` component to synchronize URL state with the AuthModal.
- Added `renderWithDayRedirectRoute` function to facilitate testing of the AuthModal with day-based routing.
- Updated tests to verify that the reset password flow correctly preserves authentication parameters in the URL during redirects.
- Implemented `updateCurrentUrlSearchParams` function to streamline URL parameter updates in the authentication flow.
- Enhanced existing tests to ensure robust coverage of the new functionality and maintainability of the AuthModal component.

* feat(auth): enhance AuthModal for password reset flow and status messaging

- Introduced a new status message in the LogInForm to inform users of successful password resets.
- Updated AuthModal logic to handle the new "loginAfterReset" view, improving user experience during the authentication process.
- Enhanced tests for LogInForm to verify the display of status messages, ensuring accurate feedback for users.
- Refactored related hooks and components to support the updated authentication flow and maintain clarity in the codebase.

* feat(auth): enhance AuthModal tests for sign-up flow after password reset

- Added a test to verify that clicking "Sign up" after a successful password reset correctly transitions the user to the sign-up view.
- Updated error handling in the useZodForm hook to log errors in development mode, improving debugging capabilities during form submissions.

* feat(env): rename LOCAL_WEB_URL to FRONTEND_URL across configuration and documentation

* feat(env): streamline environment variable handling by removing staging and production URLs

* refactor(email): extract new user tagging logic into EmailService.tagNewUserIfEnabled

* docs: add error handling guide and engineering principles documentation

* docs: reorganize documentation into categorical folders and add architecture, auth-sync, and recurring events guides

* docs: reorganize documentation into categorical folders and add architecture, auth-sync, and recurring events guides

* feat(docs): add coding conventions, deployment, and troubleshooting guides

* fix(cli.utils): update domain retrieval logic to return host instead of hostname for non-local environments

* Refactor recurring events documentation and sync process

- Added section on Google Series Splits to recurring events handling documentation to clarify handling of incremental sync payloads.
- Deleted outdated recurring events overview and sync documentation to streamline content and avoid redundancy.
- Updated frontend data flow documentation to consolidate information and clarify event flow.
- Revised principles documentation to align with repo guidance.

* fix: supertokens middleware handler

* refactor: optimize sync creation by removing Promise.all for sequential execution

* fix: core tests

Author: tyler-dane

.gitignore

@@ -19,8 +19,7 @@ packages/**/yarn.lock
 # DIRS #
 ########
 # root
-.claude/settings.local.json
-.claude/worktrees/
+.claude/
 .idea/
 .mcp.json
 .vscode/

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting a Vulnerability
 
-If you discover a security vulnerability in this project, please send an email to **tyler@switchback.tech** with the following details:
+If you discover a security vulnerability in this project, please send an email to <tyler@switchback.tech> with the following details:
 
 - A description of the vulnerability
 - Steps to reproduce (if applicable)

docs/README.md

@@ -0,0 +1,57 @@
+# Docs
+
+Internal documentation for engineers and agents working in the Compass repo.
+
+Start with [AGENTS.md](../AGENTS.md) for repo rules, commands, and conventions. Use the docs below for codebase shape and subsystem behavior.
+
+## Start Here
+
+- [Agent Onboarding](./development/agent-onboarding.md)
+- [Repo Architecture](./architecture/repo-architecture.md)
+- [Feature File Map](./development/feature-file-map.md)
+- [Common Change Recipes](./development/common-change-recipes.md)
+
+## Common Change Paths
+
+- Auth or session behavior:
+  [Frontend Runtime Flow](./frontend/frontend-runtime-flow.md),
+  [Password Auth Flow](./features/password-auth-flow.md),
+  [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+- Event shape or recurrence behavior:
+  [Event And Task Domain Model](./architecture/event-and-task-domain-model.md),
+  [Recurrence Handling](./features/recurring-events-handling.md)
+- Local-first or storage behavior:
+  [Offline Storage And Migrations](./features/offline-storage-and-migrations.md)
+- Backend routes and API behavior:
+  [Backend Request Flow](./backend/backend-request-flow.md),
+  [API Documentation](./backend/api-documentation.md),
+  [Backend Error Handling](./backend/backend-error-handling.md)
+
+## Runtime Flows
+
+- [Frontend Runtime Flow](./frontend/frontend-runtime-flow.md)
+- [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+- [Password Auth Flow](./features/password-auth-flow.md)
+
+## Architecture And Domain
+
+- [Repo Architecture](./architecture/repo-architecture.md)
+- [Event And Task Domain Model](./architecture/event-and-task-domain-model.md)
+- [Glossary](./architecture/glossary.md)
+- [Engineering Principles](./principles.md)
+
+## Development And Operations
+
+- [Env And Dev Modes](./development/env-and-dev-modes.md)
+- [Testing Playbook](./development/testing-playbook.md)
+- [Types And Validation](./development/types-and-validation.md)
+- [CLI And Maintenance Commands](./development/cli-and-maintenance-commands.md)
+- [Deploy](./development/deploy.md)
+- [Coding Conventions](./development/coding-conventions.md)
+
+## Feature Deep Dives
+
+- [Password Auth Flow](./features/password-auth-flow.md)
+- [Google Sync And Websocket Flow](./features/google-sync-and-websocket-flow.md)
+- [Recurrence Handling](./features/recurring-events-handling.md)
+- [Offline Storage And Migrations](./features/offline-storage-and-migrations.md)

docs/agent-onboarding.md

@@ -45,7 +45,7 @@ These are UI-facing categories, not storage categories.
 
 Many sync and parser decisions key off transitions between these states.
 
-For the full recurring-event lifecycle, see [recurrence-handling.md](./recurrence-handling.md).
+For the full recurring-event lifecycle, see [Recurrence Handling](../features/recurring-events-handling.md).
 
 ## Update Scopes
 

docs/event-and-task-domain-model.md …hitecture/event-and-task-domain-model.mddocs/event-and-task-domain-model.md renamed to docs/architecture/event-and-task-domain-model.md docs/event-and-task-domain-model.md renamed to docs/architecture/event-and-task-domain-model.md

@@ -0,0 +1,58 @@
+# Glossary
+
+Definition of terms used in the source code and documentation.
+
+## Events
+
+**Standalone Event**: An event that has a datetime and is NOT recurring. It represents a single occurrence.
+
+**Grid Event**: An event that is assigned to a specific time slot on the calendar in the grid view. These events have both a date and time.
+
+**Draft Event**: A calendar event that has pending changes that have not yet been persisted to the database. When a user makes changes to an event in the form, drags the event or resizes its times, the user is operating on a draft event. After the user clicks "Save", the draft event is persisted to the database, and the Draft Event goes away and is replaced with the Event.
+
+**Someday Event**: These have `startDate` and `endDate` like regular timed events, but they have not yet been assigned to a specific time slot on the calendar in the grid. Instead, they are stored in the sidebar (Someday/Maybe list). These may be recurring or standalone.
+
+**Base Event**: A _recurring_ event that defines the recurrence pattern. It has the series `RRULE` in the `recurrence` field and serves as a template for generating instances.
+
+**Instance Event**: A _recurring_ event that is an individual occurrence of a base event. Instances are generated based on the base event's recurrence rule.
+
+## Calendar Concepts
+
+**Calendar**: A calendar is a collection of events. It is the main object in the application. In Compass, each user has their primary calendar.
+
+**Calendar List**: Also known as sub-calendars. A calendar list is a collection of calendars. In Google Calendar, users can have multiple calendars (e.g., "Work", "Personal", "Holidays").
+
+**Calendar View**: A calendar view is a way to view a calendar. Compass currently centers on:
+
+- Day view
+- Week view
+- Now mode (focus on current task)
+- sidebar month widget / someday-month workflows
+
+**Primary Calendar**: The main calendar associated with a user's Google account. Compass currently syncs only the primary calendar.
+
+## Sync & Authentication
+
+**Sync**: The Compass feature that allows users to sync their calendar data with other calendars like Google Calendar. Sync can be bidirectional (changes in Compass update Google Calendar and vice versa).
+
+**Sync Channel**: A notification channel set up with Google Calendar that notifies Compass when events change. Managed via Google Calendar's watch API.
+
+**nextSyncToken**: A token provided by Google Calendar API that allows incremental syncing. It represents the state of the calendar at a point in time.
+
+**gAccessToken**: Google OAuth access token used to authenticate API requests to Google Calendar.
+
+**gRefreshToken**: Google OAuth refresh token used to obtain new access tokens when they expire. Stored securely in MongoDB.
+
+## Technical Terms
+
+**Redux Store**: The centralized state management store for the React frontend. Contains all application state including events, user data, and UI state.
+
+**Redux Saga**: Middleware for Redux that handles side effects (API calls, async operations) in a declarative way.
+
+**Duck Pattern**: A Redux pattern that co-locates actions, reducers, and selectors in a single file (or directory) for a feature domain.
+
+**WebSocket**: A communication protocol used for real-time bidirectional communication between the frontend and backend. Used to push updates when events change.
+
+**Supertokens**: The authentication library used by Compass to manage user sessions, access tokens, and refresh tokens.
+
+**MongoDB Collection**: A collection in MongoDB is similar to a table in a relational database. Compass uses collections for users, events, syncs, etc.

docs/architecture/glossary.md

@@ -123,7 +123,9 @@ Runtime constraints from recipe overrides:
 
 - successful password `signUpPOST` and `signInPOST` upsert the Compass user via `userService.upsertUserFromAuth(...)`
 - password `createNewRecipeUser` ensures SuperTokens external user-id mapping exists and points to a Mongo `ObjectId` string
-- password-reset emails are currently logged (dev/test) or logged as disabled (non-dev), not delivered by an external provider
+- password-reset links are rewritten to Compass app URLs before delivery
+- in `test`, reset links are logged instead of sent
+- outside `test`, delivery goes through SuperTokens email delivery
 
 ---
 

docs/repo-architecture.md docs/architecture/repo-architecture.mddocs/repo-architecture.md renamed to docs/architecture/repo-architecture.md

@@ -0,0 +1,50 @@
+# Backend Error Handling
+
+Compass uses typed operational errors plus a centralized Express error handler.
+
+## Source Files
+
+- `packages/backend/src/common/errors/handlers/error.handler.ts`
+- `packages/backend/src/common/errors/handlers/error.express.handler.ts`
+- feature error metadata files under `packages/backend/src/common/errors/**`
+- `packages/core/src/errors/errors.base.ts`
+
+## Main Pattern
+
+Preferred backend pattern:
+
+1. define reusable error metadata in the relevant feature file
+2. create a `BaseError` through `error(...)`
+3. let controller/service code throw that error
+4. let centralized Express handling turn it into the client payload
+
+Example:
+
+```ts
+import { AuthError } from "@backend/common/errors/auth/auth.errors";
+import { error } from "@backend/common/errors/handlers/error.handler";
+
+throw error(AuthError.MissingRefreshToken, "Google connection required");
+```
+
+## Client Payload Rules
+
+For `BaseError`, backend responses are intentionally small:
+
+- `result`: short result string
+- `message`: safe user-facing description
+
+Internal details such as stack traces and operational flags stay server-side.
+
+## Unexpected Error Rules
+
+- non-`BaseError` values are routed through `handleExpressError(...)`
+- Google API errors get special handling for revoked tokens, invalid values, and full-sync recovery
+- programmer errors can terminate the process after logging
+
+## Guidance
+
+- Keep `result` short and stable.
+- Put technical detail in logs, not in the client payload.
+- Prefer reusing existing feature error metadata before inventing new names.
+- If the error should trigger special auth/sync behavior, verify both API handling and websocket side effects.