docs: Update documentation and organize project structure

- Update CLAUDE.md with comprehensive onboarding system documentation
- Add detailed applicant workflow (applying → testing → onboarding → waitlist → accepted)
- Document new database schema additions for quiz, commitment, and mobile capability
- Update video URLs to use Supabase Storage (codebility/onboarding-videos/)

Database & Types:
- Create TypeScript types for applicant and onboarding tables (types/database/applicant.ts)
- Add project category many-to-many migration
- Create migrations README with naming conventions and categories
- Document all onboarding-related database fields

Documentation:
- Add comprehensive VIDEO_UPLOAD_GUIDE.md for Supabase Storage
- Include upload instructions via dashboard and CLI
- Document video optimization and troubleshooting tips
- Add storage policies and CORS configuration

Organization:
- Move project-category migration to proper location (supabase/migrations/)
- Add DEPRECATION_NOTICE.md for old migration-scripts folder
- Clarify that migration-scripts/ is deprecated for historical reference only
- Establish proper migration workflow in apps/codebility/supabase/migrations/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Zeff01

CLAUDE.md

@@ -69,8 +69,9 @@ This is a Turborepo monorepo with pnpm workspaces containing multiple Next.js ap
 **Authentication Flow:**
 - Middleware-based route protection in `middleware.ts`
 - Role-based access control with `roles` table
-- Application status workflow: `applying` → `pending` → `passed`/`failed`
+- Application status workflow: `applying` → `testing` → `onboarding` → `waitlist` → `accepted`/`denied`
 - Email verification requirements
+- Comprehensive onboarding system with video watching, quizzes, and digital commitment signing
 
 **State Management Pattern:**
 - Zustand stores in `store/` directories for global state
@@ -119,9 +120,83 @@ All shared packages must be prefixed with `@codevs/` (e.g., `@codevs/ui`, `@code
 ### Database Schema
 The project uses Supabase (PostgreSQL) with the following key tables:
 - **Core**: `codev` (users), `roles` (permissions), `project`, `project_members`
-- **Job System**: `job_listings`, `job_applications` 
+- **Applicant System**: `applicant` (test results, onboarding progress, quiz scores, commitments)
+- **Onboarding**: `onboarding_video_progress` (video completion tracking)
+- **Job System**: `job_listings`, `job_applications`
 - **Attendance**: `attendance`, `attendance_summary`
 - **Gamification**: `skill_categories`, `codev_points`
 - **Kanban**: `kanban_board`, `kanban_column`, `kanban_sprint`, `task`
-
-For detailed schema information, relationships, and SQL examples, see `database-schema.md` in the root directory.
+- **Communication**: `notifications`, `news_banners`, `surveys`
+
+For detailed schema information, relationships, and SQL examples, see `database-schema.md` in the root directory.
+
+### Applicant Onboarding System
+
+**Overview:**
+A comprehensive 4-step onboarding system that guides applicants from initial application through to acceptance:
+
+1. **Applying** - Submit application
+2. **Testing** - Complete coding assessment
+3. **Onboarding** - Watch 4 videos, pass quiz (70%), sign commitment
+4. **Waitlist** - Await admin review and acceptance
+
+**Key Features:**
+- **Video System**: 4 onboarding videos with 90% watch completion validation
+- **Sequential Unlocking**: Videos unlock only after completing previous ones
+- **Quiz System**: 6 questions focusing on understanding that Codebility is:
+  - FREE (no payment required)
+  - For portfolio building and upskilling
+  - NOT for quick employment
+  - Requires 3-6 months commitment
+  - Requires twice-weekly mandatory meetings
+- **Digital Commitment**: Canvas-based signature capture
+- **Mobile Capability**: Tracks if applicant can do React Native development
+- **Progress Persistence**: State saved across page refreshes
+- **Email Notifications**: Automated emails at each stage transition
+- **Admin Dashboard**: View quiz scores, mobile capability, commitment status
+
+**File Locations:**
+- Onboarding UI: `apps/codebility/app/applicant/onboarding/`
+- Waitlist UI: `apps/codebility/app/applicant/waiting/`
+- Admin View: `apps/codebility/app/home/applicants/`
+- Migrations: `apps/codebility/supabase/migrations/`
+- Videos: Stored in Supabase Storage at `public/onboarding-videos/`
+
+**Database Fields Added:**
+- `applicant.quiz_score` - Score achieved on quiz
+- `applicant.quiz_total` - Total quiz questions
+- `applicant.quiz_passed` - Boolean pass/fail status
+- `applicant.quiz_completed_at` - Completion timestamp
+- `applicant.can_do_mobile` - Mobile development capability
+- `applicant.commitment_signed_at` - Digital signature timestamp
+- `applicant.signature_data` - Base64 signature image
+
+**Admin Actions:**
+- **Accept**: Sends acceptance email with /home access instructions
+- **Deny**: Sends denial email with reapplication information
+- **View Progress**: See quiz scores, mobile capability, and commitment status
+
+### File Storage
+
+**Supabase Storage Buckets:**
+- `public/onboarding-videos/` - Onboarding video files (part1.mp4 - part4.mp4)
+- Upload via Supabase Dashboard → Storage → Select bucket → Upload files
+- Videos are referenced by path in video player component
+- Total size: ~5.8GB (too large for git, excluded via .gitignore)
+
+### Database Migrations
+
+All database migrations are located in `apps/codebility/supabase/migrations/`
+
+**Migration Naming Convention:** `YYYYMMDD_description.sql`
+
+**Key Migrations:**
+- `add_quiz_and_commitment_fields.sql` - Onboarding system fields
+- `create_onboarding_videos_table.sql` - Video progress tracking
+- `create_notification_system.sql` - Notification infrastructure
+- `create_attendance_tables.sql` - Attendance tracking
+- `20251127_project_category_many_to_many.sql` - Project categories
+
+**Legacy Migrations:**
+The `migration-scripts/` folder in the root contains deprecated migration tools and scripts.
+Do not add new migrations there. See `migration-scripts/DEPRECATION_NOTICE.md` for details.

apps/codebility/app/applicant/onboarding/_components/OnboardingClient.tsx

@@ -17,10 +17,10 @@ interface OnboardingClientProps {
 }
 
 const VIDEO_URLS = {
-  1: "/assets/onboardingvideos/part1.mp4", // Introduction - About Codebility
-  2: "/assets/onboardingvideos/part2.mp4", // Benefits, Culture & Expectations
-  3: "/assets/onboardingvideos/part3.mp4", // Roadmaps, Milestones & Tech Stack
-  4: "/assets/onboardingvideos/part4.mp4", // Portal Tour - Gamification & Workflow (to be added)
+  1: "https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part1.mp4", // Introduction - About Codebility
+  2: "https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part2.mp4", // Benefits, Culture & Expectations
+  3: "https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part3.mp4", // Roadmaps, Milestones & Tech Stack
+  4: "https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part4.mp4", // Portal Tour - Gamification & Workflow
 };
 
 const VIDEO_TITLES = {

apps/codebility/docs/VIDEO_UPLOAD_GUIDE.md

@@ -0,0 +1,219 @@
+# Onboarding Video Upload Guide
+
+This guide explains how to upload and manage onboarding videos in Supabase Storage.
+
+## Current Video Configuration
+
+The onboarding videos are stored in Supabase Storage and accessed via public URLs:
+
+- **Bucket**: `codebility`
+- **Path**: `onboarding-videos/`
+- **Files**: `part1.mp4`, `part2.mp4`, `part3.mp4`, `part4.mp4`
+
+### Current Video URLs
+
+```
+https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part1.mp4
+https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part2.mp4
+https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part3.mp4
+https://hibnlysaokybrsufrdwp.supabase.co/storage/v1/object/public/codebility/onboarding-videos/part4.mp4
+```
+
+## Uploading Videos via Supabase Dashboard
+
+### Step 1: Access Supabase Storage
+
+1. Go to your Supabase Dashboard: https://app.supabase.com
+2. Select your project
+3. Navigate to **Storage** in the left sidebar
+4. Select the `codebility` bucket (or create it if it doesn't exist)
+
+### Step 2: Create Folder (if needed)
+
+1. Click **Create folder**
+2. Name it `onboarding-videos`
+3. Click **Create**
+
+### Step 3: Upload Videos
+
+1. Navigate into the `onboarding-videos` folder
+2. Click **Upload file**
+3. Select your video files:
+   - `part1.mp4` - Introduction - About Codebility
+   - `part2.mp4` - Benefits, Culture & Expectations
+   - `part3.mp4` - Roadmaps, Milestones & Tech Stack
+   - `part4.mp4` - Portal Tour - Gamification & Workflow
+4. Click **Upload**
+
+### Step 4: Make Files Public
+
+1. For each uploaded file, click the **⋮** menu
+2. Select **Get URL**
+3. Toggle **Public** to ON
+4. Copy the public URL
+
+### Step 5: Update Video URLs (if needed)
+
+If you upload to a different bucket or path, update the URLs in:
+
+`apps/codebility/app/applicant/onboarding/_components/OnboardingClient.tsx`
+
+```typescript
+const VIDEO_URLS = {
+  1: "https://YOUR_PROJECT.supabase.co/storage/v1/object/public/YOUR_BUCKET/YOUR_PATH/part1.mp4",
+  2: "https://YOUR_PROJECT.supabase.co/storage/v1/object/public/YOUR_BUCKET/YOUR_PATH/part2.mp4",
+  3: "https://YOUR_PROJECT.supabase.co/storage/v1/object/public/YOUR_BUCKET/YOUR_PATH/part3.mp4",
+  4: "https://YOUR_PROJECT.supabase.co/storage/v1/object/public/YOUR_BUCKET/YOUR_PATH/part4.mp4",
+};
+```
+
+## Uploading Videos via Supabase CLI
+
+### Prerequisites
+
+```bash
+# Install Supabase CLI
+npm install -g supabase
+
+# Login to Supabase
+supabase login
+```
+
+### Upload Command
+
+```bash
+# Navigate to your project
+cd apps/codebility
+
+# Upload a single video
+supabase storage upload codebility/onboarding-videos/part1.mp4 path/to/your/part1.mp4 --project-ref YOUR_PROJECT_REF
+
+# Upload all videos
+supabase storage upload codebility/onboarding-videos path/to/your/videos/*.mp4 --project-ref YOUR_PROJECT_REF
+```
+
+### Make Files Public via CLI
+
+```bash
+# Create a public bucket policy
+supabase storage update codebility --public true --project-ref YOUR_PROJECT_REF
+```
+
+## Video File Specifications
+
+### Recommended Settings
+
+- **Format**: MP4 (H.264 codec)
+- **Resolution**: 1080p (1920x1080) or 720p (1280x720)
+- **Bitrate**: 2-5 Mbps for good quality
+- **Audio**: AAC codec, 128-192 kbps
+- **Frame Rate**: 30fps
+
+### Current File Sizes
+
+- part1.mp4: ~716 MB
+- part2.mp4: ~2.4 GB
+- part3.mp4: ~1.4 GB
+- part4.mp4: ~1.3 GB
+- **Total**: ~5.8 GB
+
+### Size Optimization Tips
+
+If you need to reduce file sizes:
+
+1. **Use HandBrake or FFmpeg**:
+   ```bash
+   # Example with FFmpeg to reduce size while maintaining quality
+   ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k output.mp4
+   ```
+
+2. **Recommended CRF values**:
+   - 18-22: High quality (larger files)
+   - 23-28: Good quality (balanced)
+   - 28+: Lower quality (smaller files)
+
+3. **Consider streaming optimization**:
+   ```bash
+   # Add web optimization flag
+   ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k -movflags +faststart output.mp4
+   ```
+
+## Bucket Configuration
+
+### Storage Policies
+
+Ensure your Supabase Storage bucket has the correct RLS policies:
+
+```sql
+-- Allow public access to onboarding videos
+CREATE POLICY "Public Access for Onboarding Videos"
+ON storage.objects FOR SELECT
+TO public
+USING (bucket_id = 'codebility' AND (storage.foldername(name))[1] = 'onboarding-videos');
+```
+
+### CORS Configuration
+
+If videos don't play due to CORS issues:
+
+1. Go to **Settings** → **API** in Supabase Dashboard
+2. Add your application domain to **CORS allowed origins**
+3. Include both development and production URLs:
+   - `http://localhost:3000`
+   - `https://www.codebility.tech`
+
+## Troubleshooting
+
+### Videos Not Playing
+
+1. **Check public access**: Ensure files are set to public in Supabase Storage
+2. **Verify URLs**: Make sure URLs in code match actual storage paths
+3. **Browser console**: Check for CORS errors or 404s
+4. **File format**: Ensure videos are in MP4 format with H.264 codec
+
+### Slow Loading
+
+1. **Enable CDN**: Supabase uses CloudFlare CDN automatically for public storage
+2. **Optimize video files**: Use the compression tips above
+3. **Consider adaptive streaming**: For very large files, consider HLS or DASH streaming
+
+### Upload Failures
+
+1. **File size limits**: Check your Supabase plan's storage limits
+2. **Timeout issues**: For large files, use the CLI instead of dashboard
+3. **Network stability**: Ensure stable internet connection during upload
+
+## Updating Videos
+
+When you need to replace a video:
+
+1. Upload the new video with the same filename
+2. Supabase will automatically overwrite the old version
+3. No code changes needed if filename stays the same
+4. Old URLs will automatically serve the new video
+
+## Best Practices
+
+1. **Name consistently**: Use descriptive, sequential names (part1, part2, etc.)
+2. **Optimize before upload**: Compress videos before uploading to save storage space
+3. **Test after upload**: Always verify videos play correctly after uploading
+4. **Backup originals**: Keep original high-quality versions as backups
+5. **Version control**: If you need to keep multiple versions, use folders like `v1/`, `v2/`
+
+## Cost Considerations
+
+Supabase Storage pricing (as of 2024):
+- **Free tier**: 1 GB storage
+- **Pro tier**: 100 GB storage included
+- **Additional**: $0.021 per GB/month
+
+Current videos (~5.8 GB) will use:
+- Pro tier: Covered under 100 GB limit
+- Additional cost: ~$0.12/month if over free tier
+
+## Security Notes
+
+- Videos are public and can be accessed by anyone with the URL
+- Do not include sensitive information in videos
+- Consider watermarking videos if needed
+- Monitor storage bucket for unauthorized uploads