Add Supabase setup documentation

SUPABASE_SETUP.md

@@ -0,0 +1,136 @@
+# Supabase Database Setup
+
+This document explains how to set up the Supabase tables for user authentication and analytics.
+
+## Tables Created
+
+### 1. user_profiles
+Stores user onboarding data from the multi-step signup form.
+
+**Columns:**
+- `id` (UUID) - Primary key
+- `user_id` (UUID) - References auth.users(id), unique
+- `name` (TEXT) - Full name
+- `email` (TEXT) - Email address
+- `primary_goal` (TEXT) - User's primary goal
+- `target_outcome` (TEXT) - What they want to achieve
+- `data_types` (TEXT[]) - Array of data types they work with
+- `profession` (TEXT) - Job title/role
+- `experience` (TEXT) - Experience level
+- `industry` (TEXT) - Industry they work in
+- `onboarding_completed` (BOOLEAN) - Whether they finished onboarding
+- `created_at` (TIMESTAMP) - Created timestamp
+- `updated_at` (TIMESTAMP) - Last updated timestamp
+
+### 2. usage_analytics
+Tracks each query/interaction with the agent.
+
+**Columns:**
+- `id` (UUID) - Primary key
+- `user_id` (TEXT) - User identifier
+- `user_email` (TEXT) - User email
+- `session_id` (TEXT) - Session UUID
+- `query` (TEXT) - The user's query
+- `agent_used` (TEXT) - Which specialist agent handled it
+- `tools_executed` (TEXT[]) - Array of tools used
+- `tokens_used` (INTEGER) - Tokens consumed
+- `duration_ms` (INTEGER) - Time taken
+- `success` (BOOLEAN) - Whether it succeeded
+- `error_message` (TEXT) - Error details if failed
+- `created_at` (TIMESTAMP) - When the query was made
+
+### 3. user_sessions
+Tracks user sessions for analytics.
+
+**Columns:**
+- `id` (UUID) - Primary key
+- `user_id` (TEXT) - User identifier
+- `user_email` (TEXT) - User email
+- `started_at` (TIMESTAMP) - Session start time
+- `ended_at` (TIMESTAMP) - Session end time
+- `queries_count` (INTEGER) - Number of queries in session
+- `browser_info` (TEXT) - User agent string
+- `created_at` (TIMESTAMP) - Created timestamp
+
+## Setup Instructions
+
+### Step 1: Create Tables
+
+1. Go to your Supabase project: https://supabase.com/dashboard
+2. Click on **SQL Editor** in the left sidebar
+3. Click **New Query**
+4. Copy the entire contents of `supabase_schema.sql`
+5. Paste into the query editor
+6. Click **Run** to execute
+
+### Step 2: Verify Tables
+
+1. Click on **Table Editor** in the left sidebar
+2. You should see:
+   - `user_profiles`
+   - `usage_analytics`
+   - `user_sessions`
+
+### Step 3: Test Authentication
+
+1. Sign up via the app (email/password or OAuth)
+2. Complete the multi-step onboarding form
+3. Check the `user_profiles` table - you should see your data
+4. Make a query to the agent
+5. Check `usage_analytics` and `user_sessions` tables for tracking data
+
+## Row Level Security (RLS)
+
+The tables have RLS enabled with policies:
+- **user_profiles**: Users can only read/insert/update their own profile
+- **usage_analytics** and **user_sessions**: No RLS (for admin analytics)
+
+## Querying Analytics
+
+### Get total users
+```sql
+SELECT COUNT(DISTINCT user_id) FROM user_profiles;
+```
+
+### Get queries in last 7 days
+```sql
+SELECT COUNT(*) 
+FROM usage_analytics 
+WHERE created_at >= NOW() - INTERVAL '7 days';
+```
+
+### Get most active users
+```sql
+SELECT user_email, COUNT(*) as query_count
+FROM usage_analytics
+WHERE created_at >= NOW() - INTERVAL '30 days'
+GROUP BY user_email
+ORDER BY query_count DESC
+LIMIT 10;
+```
+
+### Get success rate
+```sql
+SELECT 
+  COUNT(*) as total_queries,
+  SUM(CASE WHEN success THEN 1 ELSE 0 END) as successful,
+  ROUND(100.0 * SUM(CASE WHEN success THEN 1 ELSE 0 END) / COUNT(*), 2) as success_rate
+FROM usage_analytics;
+```
+
+## Troubleshooting
+
+### User profile not saving
+- Check that Supabase URL and Anon Key are set as HuggingFace Secrets
+- Check browser console for errors
+- Verify the `user_profiles` table exists and RLS policies are correct
+
+### OAuth users not showing onboarding form
+- This is expected! OAuth users are prompted to complete the form after signing in
+- The form auto-fills their email and name from OAuth data
+- They only fill in: goals, profession, industry, experience
+
+### Analytics not tracking
+- Check that `usage_analytics` and `user_sessions` tables exist
+- Verify no RLS blocking inserts (they should have no RLS for admin use)
+- Check network tab for failed API calls to Supabase