Known Issues and Their Fixes

This document lists known issues in the codebase that have been fixed multiple times and should not be broken again.

1. Authentication Flow

Status: ✅ Migrated to WorkOS AuthKit (December 2025)

Current Implementation

The application uses WorkOS AuthKit for authentication, which provides:

• Hosted authentication UI (no custom sign-in forms to maintain)
• Built-in email verification
• OAuth provider support (Google)
• Session management via middleware

DO NOT:

• ❌ Add complex auth state management in sign-in pages
• ❌ Create custom OTP/email verification flows
• ❌ Bypass WorkOS AuthKit for authentication

DO:

• ✅ Use WorkOS middleware for protected routes
• ✅ Use withAuth() for server-side auth checks
• ✅ Use useAuth() hook from @/hooks/useAuth for client-side auth

---

Adding New Known Issues

When documenting a new recurring issue:

1. Create a detailed fix document in the relevant app's docs folder
2. Add a summary here with a link to the full documentation
3. Update CLAUDE.md to reference the issue
4. Include clear DO and DON'T sections