diff --git a/.env.example b/.env.example
index b238ebf..249cfb4 100644
--- a/.env.example
+++ b/.env.example
@@ -4,24 +4,27 @@
 # NEVER commit .env.local to version control.
 # ============================================================
 
-# ── Supabase (PostgreSQL) ────────────────────────────────────
+# ── Supabase ─────────────────────────────────────────────────
 # Supabase Dashboard -> Project Settings -> Database -> Connection string
-# Use the POOLED connection string for DATABASE_URL (port 6543, ?pgbouncer=true)
-# Use the DIRECT connection string for DIRECT_URL (port 5432)
+#   DATABASE_URL: POOLED connection (port 6543, pgbouncer) — used by Prisma at runtime
+#   DIRECT_URL:   DIRECT connection (port 5432)            — used by Prisma for migrations
 DATABASE_URL="postgresql://postgres.xxxxxxxxxxxx:password@aws-0-eu-central-1.pooler.supabase.com:6543/postgres?pgbouncer=true"
 DIRECT_URL="postgresql://postgres.xxxxxxxxxxxx:password@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"
 
+# Supabase Dashboard -> Project Settings -> API
+#   NEXT_PUBLIC_SUPABASE_URL: Project URL (e.g. https://xxxx.supabase.co)
+#     !! This is NOT the database URL — it is the Supabase REST/Storage base URL !!
+#     Used for: avatar CDN links, signed upload URLs, Storage client.
+#     Baked into the client bundle at build time (NEXT_PUBLIC_ prefix).
+#   SUPABASE_SERVICE_ROLE_KEY: service_role key (secret! — server-only, never expose to client)
+NEXT_PUBLIC_SUPABASE_URL="https://xxxxxxxxxxxxxxxxxxxx.supabase.co"
+SUPABASE_SERVICE_ROLE_KEY="eyJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
 # ── Clerk (Authentication) ───────────────────────────────────
 # Clerk Dashboard -> API Keys
 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_xxxxxxxxxxxxxxxxxxxx"
 CLERK_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxx"
 
-# ── Supabase Storage (Media) ─────────────────────────────────
-# Supabase Dashboard -> Project Settings -> API -> Project URL
-NEXT_PUBLIC_SUPABASE_URL="https://xxxxxxxxxxxxxxxxxxxx.supabase.co"
-# Supabase Dashboard -> Project Settings -> API -> service_role (secret!)
-SUPABASE_SERVICE_ROLE_KEY="eyJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-
 # ── Admin Panel ───────────────────────────────────────────────
 # NEVER use NEXT_PUBLIC_ prefix — these MUST stay server-only!
 # ADMIN_SECRET: random UUID path segment (/p/[secret]/) — generate with: