docs: add username fix documentation

server/USERNAME_FIX.md

@@ -0,0 +1,61 @@
+# Username Display Fix
+
+## Issue
+Users were seeing duplicate prefixes in their usernames (e.g., `@user_user_35ZFZ...`) on their profile pages.
+
+## Root Cause
+When auto-creating users from Clerk authentication, the code was generating usernames using the pattern:
+```typescript
+username: clerkUser.username || `user_${clerkId}`
+```
+
+Since Clerk IDs already start with `user_`, this resulted in usernames like `user_user_35ZFZ...`.
+
+## Solution
+
+### 1. Updated User Creation Logic
+Modified the username generation in both `userService.ts` and `reportController.ts`:
+
+```typescript
+// Generate a clean username from Clerk ID (remove 'user_' prefix if present)
+const cleanClerkId = clerkId.startsWith('user_') ? clerkId.substring(5) : clerkId;
+const defaultUsername = clerkUser.username || `user${cleanClerkId.substring(0, 8)}`;
+```
+
+Now generates usernames like `user35ZFZ...` instead of `user_user_35ZFZ...`.
+
+### 2. Migration Script
+Created `fixDuplicateUsernames.ts` to update existing users with duplicate prefixes:
+
+```bash
+npx ts-node src/scripts/fixDuplicateUsernames.ts
+```
+
+This script:
+- Finds all users with usernames starting with `user_user_`
+- Updates them to remove the duplicate prefix
+- Example: `user_user_35Z` → `user35Z`
+
+### 3. Profile Display
+Also removed email display from the user profile page for privacy.
+
+## Result
+- New users will have clean usernames: `user35ZFZ...`
+- Existing users have been migrated to the new format
+- Profile pages now show `@user35ZFZ...` instead of `@user_user_35ZFZ...`
+- Email addresses are no longer displayed on profile pages
+
+## Files Modified
+- `server/src/services/userService.ts` - Updated user creation logic
+- `server/src/controllers/reportController.ts` - Updated user creation logic
+- `server/src/scripts/fixDuplicateUsernames.ts` - Migration script (new)
+- `src/pages/UserProfilePage.tsx` - Removed email display
+
+## Testing
+Run the migration script to fix any existing users:
+```bash
+cd server
+npx ts-node src/scripts/fixDuplicateUsernames.ts
+```
+
+The script is idempotent and safe to run multiple times.