feat: Improve RIS deployment documentation and add real-time webhook support

.env.example

@@ -11,16 +11,84 @@ NEXTAUTH_URL=http://localhost:3000
 # Example: https://react.foundation
 NEXT_PUBLIC_SITE_URL=
 
-# GitHub Personal Access Token for maintainer progress API and RIS data collection
-# Provide a fine-grained or classic personal access token with read:user and public_repo scopes.
-# Used for: Maintainer progress tracking, RIS metrics collection
-# Get one at: https://github.com/settings/tokens/new
-GITHUB_TOKEN=
+# ===================================================================
+# RIS SYSTEM: QUICK START - CHOOSE YOUR DEPLOYMENT MODE
+# ===================================================================
+# See docs/RIS_DEPLOYMENT_MODES.md for detailed comparison
+# ===================================================================
+#
+# MODE 1: Simple (PAT-only)
+# ├─ Best for: Testing, MVP, < 50 libraries
+# ├─ Setup time: 1 minute
+# ├─ Rate limit: 5,000/hour (shared)
+# └─ Updates: Monthly
+#
+# MODE 2: Professional (GitHub App, no webhooks)
+# ├─ Best for: Production, any scale
+# ├─ Setup time: 15 minutes
+# ├─ Rate limit: 5,000/hour per installation
+# └─ Updates: Monthly
+#
+# MODE 3: Real-time (GitHub App + Webhooks)
+# ├─ Best for: Production with maintainer engagement
+# ├─ Setup time: 30 minutes
+# ├─ Rate limit: 5,000/hour per installation
+# └─ Updates: Real-time (< 2 minutes)
+#
+# ===================================================================
+
+# ===== MODE 1: Simple (PAT-only) =====
+# Uncomment this line to use Mode 1:
+# GITHUB_TOKEN=ghp_your_token_here
+#
+# Get token at: https://github.com/settings/tokens/new
+# Required scopes: read:user, public_repo
+#
+# That's it! Mode 1 is ready to use.
+
+# ===== MODE 2: Professional (GitHub App, no webhooks) =====
+# Uncomment these lines to use Mode 2:
+# GITHUB_APP_ID=123456
+# GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+# MIIEpAIBAAKCAQEA...
+# -----END RSA PRIVATE KEY-----"
+#
+# Setup guide: docs/GITHUB_APP_SETUP.md (skip Step 4)
+#
+# Optional: Keep PAT as fallback
+# GITHUB_TOKEN=ghp_your_token_here
+
+# ===== MODE 3: Real-time (GitHub App + Webhooks) =====
+# Uncomment these lines to use Mode 3:
+# GITHUB_APP_ID=123456
+# GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+# MIIEpAIBAAKCAQEA...
+# -----END RSA PRIVATE KEY-----"
+# GITHUB_WEBHOOK_SECRET=your_webhook_secret_here
+# CRON_SECRET=your_random_secret_here
+# NEXT_PUBLIC_GITHUB_APP_INSTALL_URL=https://github.com/apps/your-app/installations/new
+#
+# Setup guides:
+# 1. docs/GITHUB_APP_SETUP.md (all steps including Step 4)
+# 2. docs/RIS_WEBHOOK_IMPLEMENTATION.md
+#
+# Optional: Keep PAT as fallback
+# GITHUB_TOKEN=ghp_your_token_here
+#
+# Also required for Mode 3:
+# - Add webhook processing cron job to vercel.json
+# - Redis instance (see REDIS_URL below)
+
+# ===================================================================
+# ADVANCED: Hybrid Deployment (Recommended)
+# ===================================================================
+# Configure Mode 3 (all variables above) for full functionality:
+# - Repos with app installed → Real-time updates via webhooks
+# - Repos without app → Monthly updates via PAT fallback
+# - Best of both worlds: real-time for engaged maintainers, polling for others
+# ===================================================================
 
-# Optional: Multiple GitHub tokens for rate limit rotation (comma-separated)
-# Each token gets 5,000 requests/hour, so 3 tokens = 15,000 requests/hour
-# Format: token1,token2,token3
-GITHUB_TOKENS=
+GITHUB_TOKEN=
 
 # Shopify Storefront API (for fetching products/collections on the frontend)
 SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
@@ -92,6 +160,12 @@ CRAWLER_BYPASS_TOKEN=
 # Generate a secure random string for this value
 INGESTION_API_TOKEN=
 
+# Cron Job Secret
+# Secret token for webhook processing cron job
+# Prevents unauthorized triggering of background tasks
+# Generate a secure random string for this value
+CRON_SECRET=
+
 # Resend API Key for access request notifications
 # Get one at: https://resend.com/api-keys
 RESEND_API_KEY=