deploy: sync backend to Space root (learn-lesson HF cache fix)

.env.example

@@ -1,4 +1,4 @@
-APP_NAME="AI Exam Success API"
+APP_NAME="AI Exam Success API"
 ENVIRONMENT="development"
 
 # PostgreSQL target for production/local DB work.
@@ -50,6 +50,16 @@ OPENROUTER_MODEL_LLAMA="qwen/qwen3-next-80b-a3b-instruct"
 AI_MAX_RETRIES="2"
 AI_TIMEOUT_SECONDS="120"
 
+# Learn Anything lesson authoring (OpenAI-compatible chat via Groq).
+# Server-side only — never put this in NEXT_PUBLIC_*.
+GROQ_API_KEY=""
+
+# Scale knobs for ~1k concurrent students (raise in production Postgres deploys).
+DATABASE_POOL_SIZE="10"
+DATABASE_MAX_OVERFLOW="20"
+RATE_LIMIT_ENABLED="true"
+RATE_LIMIT_AI_REQUESTS_PER_DAY="80"
+
 # TTS provider settings.
 # AI4Bharat Indic Parler is the local Indian-English + Malayalam teacher voice.
 # Accept its free Hugging Face access terms once, then set HUGGINGFACE_API_KEY.
@@ -115,6 +125,17 @@ ACCESS_TOKEN_EXPIRE_MINUTES="10080"
 SUPABASE_URL=""
 SUPABASE_JWT_SECRET=""
 SUPABASE_ANON_KEY=""
+# Backend only. Required to fully remove Supabase Auth identities when
+# AUTH_PROVIDER="supabase". Never copy this into a NEXT_PUBLIC_* variable.
+SUPABASE_SERVICE_ROLE_KEY=""
+
+# Transactional account email. Required for password recovery when
+# AUTH_PROVIDER="jwt" in production.
+EMAIL_PROVIDER="disabled" # disabled | resend
+RESEND_API_KEY=""
+EMAIL_FROM="DocDoe <support@docdoe.in>"
+PASSWORD_RESET_TOKEN_MINUTES="30"
+PASSWORD_RESET_REQUEST_COOLDOWN_SECONDS="60"
 
 # Optional Google sign-in.
 # Create OAuth credentials in Google Cloud and add this redirect URI:
@@ -136,28 +157,22 @@ BETA_INVITE_CODE=""
 RATE_LIMIT_ENABLED="false"
 RATE_LIMIT_AI_REQUESTS_PER_DAY="50"
 
-# --- Stripe Billing (tuition plans + exam packs + webhooks) ---
-# Use Stripe TEST keys for development (sk_test_... and whsec_...).
-# Create products + prices in Stripe Dashboard (test mode) for each paid plan.
-# Monthly plan keys use subscription checkout:
-#   subject_month_99, all_subjects_beta_149, parent_tuition_299
-# One-time exam pack keys use payment checkout:
-#   chapter_rescue_29, last_night_pack_49, derivation_pack_49,
-#   chemistry_numericals_pack_49, maths_proof_pack_49, kerala_physics_chapter_99
-# Legacy keys remain accepted for existing users:
-#   starter_199, popular_299, premium_599
+# --- Stripe Billing (Popular 299 + Premium 599 subscriptions) ---
+# Prefer a restricted TEST key (rk_test_...) with only the Checkout, Customers,
+# Subscriptions, and Billing Portal permissions this backend needs.
+# Create recurring test Prices for both active plans. Checkout stays disabled
+# until the key, webhook secret, and requested Price are all present.
 # Example:
-# STRIPE_PRICE_IDS=subject_month_99=price_sub_abc,parent_tuition_299=price_sub_def,chapter_rescue_29=price_pay_ghi
-# UPI/Razorpay checkout is not implemented yet; wire Razorpay orders for one-time packs before promising live UPI payment.
-# For webhook testing: use `stripe listen --forward-to http://127.0.0.1:8000/billing/webhook`
+# STRIPE_PRICE_IDS=popular_299=price_sub_abc,premium_599=price_sub_def
+# For webhook testing: `stripe listen --forward-to http://127.0.0.1:8000/billing/webhook`
 #   (this prints a local whsec_... you paste here; in prod use the dashboard endpoint secret).
 STRIPE_SECRET_KEY=""
 STRIPE_WEBHOOK_SECRET=""
 STRIPE_PRICE_IDS=""
 
-# ── Observability + scaling (optional; A+ when set) ───────────────────────────
+# ── Observability + scaling (optional; A+ when set) ───────────────────────────
 # Shared rate-limit + prompt cache across replicas (e.g. Upstash free tier):
 REDIS_URL=
-# Error tracking — paste a Sentry project DSN to capture backend + frontend errors:
+# Error tracking — paste a Sentry project DSN to capture backend + frontend errors:
 SENTRY_DSN=
 SENTRY_TRACES_SAMPLE_RATE=0.1

.env.production.example

@@ -1,4 +1,4 @@
-# DocDoe backend production template.
+# DocDoe backend production template.
 # Copy into your hosting provider's secret/env dashboard. Do not commit real values.
 # Closed beta must use PostgreSQL for DATABASE_URL. Do not use SQLite for real students.
 
@@ -6,7 +6,7 @@ ENVIRONMENT=production
 DATABASE_URL=
 CORS_ORIGINS=
 
-# ── Database backup and recovery ──────────────────────────────────
+# ── Database backup and recovery ──────────────────────────────────
 # Use "managed" when Supabase or another provider owns the schedule and
 # retention. Use "pg_dump" for backend/scripts/database_backup.py.
 DATABASE_BACKUP_STRATEGY=managed
@@ -16,7 +16,7 @@ DATABASE_RESTORE_TESTED_AT=
 # Required only for pg_dump strategy. This should be durable off-host storage.
 DATABASE_BACKUP_DIR=
 
-# ── Auth ──────────────────────────────────────────────────────────────────
+# ── Auth ──────────────────────────────────────────────────────────────────
 # AUTH_PROVIDER=supabase is the recommended production setup (managed auth + a
 # real Postgres for DATABASE_URL). AUTH_PROVIDER=jwt is the self-hosted option.
 # The tuition beta is login-less regardless (localStorage), so students still
@@ -26,18 +26,18 @@ AUTH_ENABLED=true
 AUTH_PROVIDER=supabase
 FRONTEND_BASE_URL=
 
-# Supabase (when AUTH_PROVIDER=supabase). Dashboard → Project Settings.
-#   SUPABASE_URL           → Settings → API → Project URL
-#   SUPABASE_ANON_KEY      → Settings → API → Project API keys → anon public
-#   SUPABASE_JWT_SECRET    → Settings → API → JWT Settings → JWT Secret
-#   DATABASE_URL (above)   → Settings → Database → Connection string (URI),
+# Supabase (when AUTH_PROVIDER=supabase). Dashboard → Project Settings.
+#   SUPABASE_URL           → Settings → API → Project URL
+#   SUPABASE_ANON_KEY      → Settings → API → Project API keys → anon public
+#   SUPABASE_JWT_SECRET    → Settings → API → JWT Settings → JWT Secret
+#   DATABASE_URL (above)   → Settings → Database → Connection string (URI),
 #                            use the pooled connstring for serverless hosts,
 #                            prefix with postgresql:// (not postgres://).
 SUPABASE_URL=
 SUPABASE_ANON_KEY=
 SUPABASE_JWT_SECRET=
 
-# JWT / Google OAuth (only when AUTH_PROVIDER=jwt) — leave blank for supabase.
+# JWT / Google OAuth (only when AUTH_PROVIDER=jwt) — leave blank for supabase.
 JWT_SECRET_KEY=
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
@@ -49,34 +49,41 @@ BETA_INVITE_CODE=
 RATE_LIMIT_ENABLED=true
 RATE_LIMIT_AI_REQUESTS_PER_DAY=50
 
-# ── Text AI provider (study-chat, notes, quizzes, video scripts) ─────────────
-# Your main app provider. Keep whatever you already use (e.g. sarvam) — the
+# ── Text AI provider (study-chat, notes, quizzes, video scripts) ─────────────
+# Your main app provider. Keep whatever you already use (e.g. sarvam) — the
 # tuition brain does NOT ride on this, it has its own provider below.
 AI_PROVIDER=sarvam
 AI_FALLBACK_TO_MOCK=false
 
-# ── Tuition brain provider (the real LLM that restates + plans today's class) ─
+# Learn Anything lesson authoring (Groq). Server-only.
+GROQ_API_KEY=
+
+# Postgres pool for ~1k concurrent students (tune against your plan limits).
+DATABASE_POOL_SIZE=15
+DATABASE_MAX_OVERFLOW=30
+
+# ── Tuition brain provider (the real LLM that restates + plans today's class) ─
 # Runs on its own cheap text adapter so it never forces the app off AI_PROVIDER.
 # Must be a text adapter: cloudflare_workers_ai | openrouter | nvidia_nim.
 # Defaults to cloudflare_workers_ai even if unset.
 TUITION_BRAIN_PROVIDER=cloudflare_workers_ai
 
 # Cloudflare Workers AI (when AI_PROVIDER=cloudflare_workers_ai).
-#   CLOUDFLARE_ACCOUNT_ID → dash.cloudflare.com → account id (right sidebar / URL)
-#   CLOUDFLARE_API_TOKEN  → My Profile → API Tokens → Create Token →
-#                           template "Workers AI" (permission: Account · Workers AI · Read/Run)
+#   CLOUDFLARE_ACCOUNT_ID → dash.cloudflare.com → account id (right sidebar / URL)
+#   CLOUDFLARE_API_TOKEN  → My Profile → API Tokens → Create Token →
+#                           template "Workers AI" (permission: Account · Workers AI · Read/Run)
 CLOUDFLARE_ACCOUNT_ID=
 CLOUDFLARE_API_TOKEN=
 # Optional model override (defaults to @cf/meta/llama-3.1-8b-instruct).
 CLOUDFLARE_WORKERS_AI_TEXT_MODEL=@cf/meta/llama-3.1-8b-instruct
 
-# Daily AI budget guard (USD). MUST be > 0 for the brain LLM to run — Cloudflare
+# Daily AI budget guard (USD). MUST be > 0 for the brain LLM to run — Cloudflare
 # Workers AI is near-free but its estimated cost is > 0, so a 0 budget denies it
 # and everything falls back to the deterministic brain. Start small.
 AI_ROUTER_DAILY_BUDGET_USD=5
 AI_ROUTER_ALLOW_FREE_PROVIDERS=true
 
-# Alternative paid provider (only when AI_PROVIDER=sarvam) — leave blank otherwise.
+# Alternative paid provider (only when AI_PROVIDER=sarvam) — leave blank otherwise.
 SARVAM_API_KEY=
 
 # Study-video voice defaults to local AI4Bharat Indic Parler for Indian English
@@ -100,19 +107,19 @@ VIDEO_BETA_MAX_DURATION_SECONDS=90
 VIDEO_SCENE_TEXT_MAX_CHARS=700
 VIDEO_MAX_CONCURRENT_RENDER_JOBS_PER_USER=1
 
-# ── Cloud storage (REQUIRED in production for video URLs to be playable) ─────
+# ── Cloud storage (REQUIRED in production for video URLs to be playable) ─────
 # Current production target: Cloudinary (free tier, generous transformations).
 # Alternatives: cloudflare R2, AWS S3 (see backend/STORAGE_SETUP.md).
 STORAGE_PROVIDER=cloudinary
 
 # Cloudinary credentials (when STORAGE_PROVIDER=cloudinary).
-# Find under: cloudinary.com Dashboard → Settings → API Keys.
+# Find under: cloudinary.com Dashboard → Settings → API Keys.
 # All three required.
 CLOUDINARY_CLOUD_NAME=
 CLOUDINARY_API_KEY=
 CLOUDINARY_API_SECRET=
 
-# R2 / S3 (when STORAGE_PROVIDER=r2 or s3) — leave blank if using Cloudinary.
+# R2 / S3 (when STORAGE_PROVIDER=r2 or s3) — leave blank if using Cloudinary.
 STORAGE_BUCKET=
 STORAGE_ENDPOINT_URL=
 STORAGE_ACCESS_KEY_ID=
@@ -124,17 +131,16 @@ STORAGE_REGION=
 # Values: huggingface | railway | flyio | docker | local
 DEPLOY_TARGET=huggingface
 
-# ── Stripe Billing (MANDATORY for paid plans in production) ───────────────────
-# Use LIVE keys (sk_live_... and whsec_... from Stripe dashboard).
-# Create one Price per paid tuition plan in LIVE mode.
-# Monthly keys use subscription checkout: subject_month_99, all_subjects_beta_149, parent_tuition_299.
-# One-time exam pack keys use payment checkout: chapter_rescue_29, last_night_pack_49,
-# derivation_pack_49, chemistry_numericals_pack_49, maths_proof_pack_49, kerala_physics_chapter_99.
-# Legacy keys starter_199, popular_299, premium_599 remain accepted for existing users/webhooks.
-# STRIPE_PRICE_IDS=subject_month_99=price_...,parent_tuition_299=price_...,chapter_rescue_29=price_...
-# UPI/Razorpay is the recommended next integration for India-friendly one-time packs; do not promise it live until wired.
+# ── Stripe Billing (MANDATORY for paid plans in production) ───────────────────
+# Prefer a restricted LIVE key (rk_live_...) scoped to Checkout, Customers,
+# Subscriptions, and Billing Portal. Store it only in the backend secret store.
+# Create recurring LIVE Prices for the two plans currently shown to students.
+# Checkout refuses to take payment unless the webhook secret and selected Price
+# are both configured.
+# STRIPE_PRICE_IDS=popular_299=price_...,premium_599=price_...
 # WEBHOOK: In Stripe dashboard create endpoint https://yourdomain.com/billing/webhook
-#   select events: checkout.session.completed , invoice.paid . Copy the signing secret here.
+#   select checkout.session.completed, customer.subscription.created/updated/deleted,
+#   invoice.paid, and invoice.payment_failed. Copy the signing secret here.
 # IMPORTANT: After setting, restart/redeploy backend so pydantic-settings picks up.
 # Never commit keys. Rotate secrets if leaked. See backend/app/routes/billing.py for impl.
 STRIPE_SECRET_KEY=

.gitignore

@@ -12,5 +12,6 @@ uploads/*
 !uploads/.gitkeep
 generated-video-jobs/
 generated-videos/
+generated/
 uvicorn_log.txt
 *.log

Dockerfile

@@ -5,7 +5,8 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     UPLOAD_DIR=/app/uploads \
     TTS_OUTPUT_DIR=/app/generated/audio \
     GENERATED_VIDEO_JOBS_DIR=/app/generated-video-jobs \
-    GENERATED_VIDEO_OUTPUT_DIR=/app/generated-videos
+    GENERATED_VIDEO_OUTPUT_DIR=/app/generated-videos \
+    LEARN_LESSON_CACHE_DIR=/app/generated/learn-anything
 
 WORKDIR /app
 

app/core/auth.py

@@ -128,6 +128,7 @@ def create_access_token(user: User) -> tuple[str, int]:
         "sub": user.id,
         "email": user.email,
         "role": user.role,
+        "ver": user.auth_version,
         "exp": expires_at,
         "iat": datetime.now(timezone.utc),
     }
@@ -135,6 +136,45 @@ def create_access_token(user: User) -> tuple[str, int]:
     return token, expires_in_seconds
 
 
+def get_verified_auth_subject(token: str) -> str:
+    """Return the verified identity-provider subject for an access token.
+
+    Most application routes only need the hydrated local ``User``. Destructive
+    identity operations also need the original provider subject so a legacy
+    email-matched local row cannot accidentally be used as a Supabase user ID.
+    """
+    settings = get_settings()
+    auth_provider = (settings.auth_provider or "jwt").strip().lower()
+    if auth_provider == "supabase":
+        if not settings.supabase_jwt_secret:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Supabase auth is enabled but SUPABASE_JWT_SECRET is not configured.",
+            )
+        secret = settings.supabase_jwt_secret
+        algorithms = ["HS256"]
+    elif auth_provider == "jwt":
+        secret = settings.jwt_secret_key
+        algorithms = [settings.jwt_algorithm]
+    else:
+        raise _auth_error()
+
+    try:
+        payload = jwt.decode(
+            token,
+            secret,
+            algorithms=algorithms,
+            options={"verify_aud": False},
+        )
+    except jwt.PyJWTError as exc:
+        raise _auth_error() from exc
+
+    subject = str(payload.get("sub") or "")
+    if not subject:
+        raise _auth_error()
+    return subject
+
+
 def _user_from_local_jwt(db: Session, token: str) -> User | None:
     settings = get_settings()
     try:
@@ -153,6 +193,12 @@ def _user_from_local_jwt(db: Session, token: str) -> User | None:
     user = db.get(User, user_id)
     if user is None:
         raise _auth_error()
+    try:
+        token_version = int(payload.get("ver", 1))
+    except (TypeError, ValueError) as exc:
+        raise _auth_error() from exc
+    if token_version != user.auth_version:
+        raise _auth_error()
     return user
 
 

app/core/config.py

@@ -14,10 +14,23 @@ class Settings(BaseSettings):
     app_version: str = "0.1.0"
     environment: str = "development"
     database_url: str = f"sqlite:///{BACKEND_DIR / 'exam_success_dev.db'}"
-    database_pool_size: int = 2
-    database_max_overflow: int = 3
-    database_pool_timeout_seconds: int = 10
-    database_pool_recycle_seconds: int = 1800
+    # Dev defaults stay small; production .env should raise these for 1k+ concurrent students.
+    database_pool_size: int = Field(
+        default=2,
+        validation_alias=AliasChoices("DATABASE_POOL_SIZE"),
+    )
+    database_max_overflow: int = Field(
+        default=3,
+        validation_alias=AliasChoices("DATABASE_MAX_OVERFLOW"),
+    )
+    database_pool_timeout_seconds: int = Field(
+        default=10,
+        validation_alias=AliasChoices("DATABASE_POOL_TIMEOUT_SECONDS"),
+    )
+    database_pool_recycle_seconds: int = Field(
+        default=1800,
+        validation_alias=AliasChoices("DATABASE_POOL_RECYCLE_SECONDS"),
+    )
     cors_origins: str = "http://localhost:3000,http://127.0.0.1:3000,http://localhost:3001,http://127.0.0.1:3001,http://localhost:3003,http://127.0.0.1:3003"
     upload_dir: str = "uploads"
     ai_provider: str = "openai"
@@ -159,6 +172,15 @@ class Settings(BaseSettings):
     redis_url: str | None = None
     sentry_dsn: str | None = None
     sentry_traces_sample_rate: float = 0.1
+    email_provider: str = "disabled"
+    resend_api_key: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("RESEND_API_KEY"),
+    )
+    resend_base_url: str = "https://api.resend.com"
+    email_from: str = "DocDoe <support@docdoe.in>"
+    password_reset_token_minutes: int = 30
+    password_reset_request_cooldown_seconds: int = 60
     generated_video_jobs_dir: str = "generated-video-jobs"
     generated_video_output_dir: str = "generated-videos"
     video_render_timeout_seconds: int = 3600
@@ -192,6 +214,13 @@ class Settings(BaseSettings):
     supabase_url: str | None = None
     supabase_jwt_secret: str | None = None
     supabase_anon_key: str | None = None
+    # Backend-only key used for destructive Supabase Auth administration, such
+    # as honoring an authenticated account-deletion request. Never expose this
+    # value through a NEXT_PUBLIC_* variable or a frontend response.
+    supabase_service_role_key: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("SUPABASE_SERVICE_ROLE_KEY"),
+    )
     jwt_secret_key: str = "change-this-local-dev-secret"
     jwt_algorithm: str = "HS256"
     access_token_expire_minutes: int = 10080  # 7 days — keeps users logged in across sessions
@@ -235,9 +264,13 @@ class Settings(BaseSettings):
     stripe_webhook_secret: str | None = Field(
         default=None, validation_alias=AliasChoices("STRIPE_WEBHOOK_SECRET")
     )
-    # Map internal plan keys to Stripe Price IDs (set in .env for prod).
-    # Monthly plans use subscription checkout; one-time exam packs use payment checkout.
-    stripe_price_ids: str = ""  # e.g. subject_month_99=price_xxx,parent_tuition_299=price_yyy,chapter_rescue_29=price_zzz
+    stripe_api_version: str = "2026-06-24.dahlia"
+    # Stable integration label registered for this checkout flow. The suffix
+    # was generated once (rather than per request) so Stripe idempotency keys
+    # always see identical request parameters.
+    stripe_checkout_integration_identifier: str = "docdoe_web_psuqtgkx"
+    # Map the two student-facing subscription keys to recurring Stripe Prices.
+    stripe_price_ids: str = ""  # e.g. popular_299=price_xxx,premium_599=price_yyy
 
     model_config = SettingsConfigDict(
         env_file=BACKEND_DIR / ".env",

app/core/database.py

@@ -107,6 +107,7 @@ def init_db() -> None:
         tuition_profile,
         class_session_progress,
         phase3_activity,
+        password_reset_token,
         learn_anything_roadmap,
         learning_state,
         support_submission,
@@ -135,13 +136,16 @@ def init_db() -> None:
     _ensure_document_chunk_columns()
     _ensure_previous_paper_columns()
     _ensure_ai_result_columns()
+    _ensure_chat_session_columns()
     _ensure_chat_message_columns()
     _ensure_video_render_job_columns()
     _ensure_generation_columns()
     _ensure_user_columns()
     _ensure_user_plan_columns()
+    _ensure_subscription_columns()
     _ensure_previous_question_t2_columns()
     _ensure_student_profile_exam_date_nullable()
+    _ensure_quiz_attempt_columns()
 
     with SessionLocal() as db:
         demo_user = db.get(User, "usr_demo_student")
@@ -284,6 +288,19 @@ def _ensure_ai_result_columns() -> None:
                 )
 
 
+def _ensure_chat_session_columns() -> None:
+    inspector = inspect(engine)
+    if "chat_sessions" not in inspector.get_table_names():
+        return
+
+    columns = {column["name"] for column in inspector.get_columns("chat_sessions")}
+    if "context_data" not in columns:
+        with engine.begin() as connection:
+            connection.execute(
+                text("ALTER TABLE chat_sessions ADD COLUMN context_data JSON NOT NULL DEFAULT '{}'")
+            )
+
+
 def _ensure_chat_message_columns() -> None:
     inspector = inspect(engine)
     if "chat_messages" not in inspector.get_table_names():
@@ -293,6 +310,21 @@ def _ensure_chat_message_columns() -> None:
     with engine.begin() as connection:
         if "evidence_label" not in columns:
             connection.execute(text("ALTER TABLE chat_messages ADD COLUMN evidence_label TEXT"))
+        if "web_sources" not in columns:
+            connection.execute(
+                text("ALTER TABLE chat_messages ADD COLUMN web_sources JSON NOT NULL DEFAULT '[]'"),
+            )
+        if "client_turn_id" not in columns:
+            connection.execute(
+                text("ALTER TABLE chat_messages ADD COLUMN client_turn_id TEXT"),
+            )
+        connection.execute(
+            text(
+                "CREATE UNIQUE INDEX IF NOT EXISTS uq_chat_messages_session_turn_role "
+                "ON chat_messages(session_id, client_turn_id, role) "
+                "WHERE client_turn_id IS NOT NULL",
+            ),
+        )
 
 
 def _ensure_previous_paper_columns() -> None:
@@ -439,6 +471,27 @@ def _ensure_student_profile_exam_date_nullable() -> None:
             pass
 
 
+def _ensure_quiz_attempt_columns() -> None:
+    """Backfill assessment idempotency on existing development databases."""
+
+    inspector = inspect(engine)
+    if "quiz_attempts" not in inspector.get_table_names():
+        return
+
+    columns = {column["name"] for column in inspector.get_columns("quiz_attempts")}
+    with engine.begin() as connection:
+        if "client_attempt_id" not in columns:
+            connection.execute(
+                text("ALTER TABLE quiz_attempts ADD COLUMN client_attempt_id VARCHAR(180)")
+            )
+        connection.execute(
+            text(
+                "CREATE UNIQUE INDEX IF NOT EXISTS uq_quiz_attempts_user_client "
+                "ON quiz_attempts (user_id, client_attempt_id)"
+            )
+        )
+
+
 def _ensure_user_columns() -> None:
     inspector = inspect(engine)
     if "users" not in inspector.get_table_names():
@@ -448,6 +501,10 @@ def _ensure_user_columns() -> None:
     with engine.begin() as connection:
         if "password_hash" not in columns:
             connection.execute(text("ALTER TABLE users ADD COLUMN password_hash TEXT"))
+        if "auth_version" not in columns:
+            connection.execute(
+                text("ALTER TABLE users ADD COLUMN auth_version INTEGER NOT NULL DEFAULT 1")
+            )
 
 
 def _ensure_document_chunk_columns() -> None:
@@ -475,6 +532,42 @@ def _ensure_user_plan_columns() -> None:
             )
 
 
+def _ensure_subscription_columns() -> None:
+    """Backfill Stripe lifecycle columns on existing local/hosted databases.
+
+    Explicit SQL migrations remain the production source of truth. This guard
+    keeps SQLite development databases usable when they predate that migration.
+    """
+
+    inspector = inspect(engine)
+    if "subscriptions" not in inspector.get_table_names():
+        return
+
+    columns = {column["name"] for column in inspector.get_columns("subscriptions")}
+    with engine.begin() as connection:
+        if "provider_price_id" not in columns:
+            connection.execute(text("ALTER TABLE subscriptions ADD COLUMN provider_price_id TEXT"))
+        if "cancel_at_period_end" not in columns:
+            connection.execute(
+                text(
+                    "ALTER TABLE subscriptions "
+                    "ADD COLUMN cancel_at_period_end BOOLEAN NOT NULL DEFAULT FALSE"
+                )
+            )
+        connection.execute(
+            text(
+                "CREATE UNIQUE INDEX IF NOT EXISTS ix_subscriptions_provider_customer "
+                "ON subscriptions (provider_customer_id)"
+            )
+        )
+        connection.execute(
+            text(
+                "CREATE UNIQUE INDEX IF NOT EXISTS ix_subscriptions_provider_subscription "
+                "ON subscriptions (provider_subscription_id)"
+            )
+        )
+
+
 def _ensure_generation_columns() -> None:
     inspector = inspect(engine)
     if "generations" not in inspector.get_table_names():

app/core/rate_limiter.py

@@ -56,7 +56,12 @@ def over_per_minute(key: str, now: float | None = None, path: str | None = None)
     the brute-force guard.
     """
     now = now or time.time()
-    is_auth = path == "/auth/login" or path == "/auth/signup"
+    is_auth = path in {
+        "/auth/login",
+        "/auth/signup",
+        "/auth/forgot-password",
+        "/auth/reset-password",
+    }
     is_support = path is not None and path.startswith("/support")
     if is_auth:
         limit = _PER_IP_AUTH_MINUTE_LIMIT

app/main.py

@@ -1,5 +1,6 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from pathlib import Path
 
 import logging
 import time
@@ -25,6 +26,7 @@ from app.routes import (
     billing,
     chat,
     chat_history,
+    chemistry_video,
     dashboard,
     dev,
     documents,
@@ -40,6 +42,7 @@ from app.routes import (
     pyq_discovery,
     physics_video,
     quizzes,
+    social_science_video,
     sources,
     study,
     study_path,
@@ -103,6 +106,8 @@ _RATE_LIMIT_PREFIXES = (
     "/ask",
     "/auth/login",
     "/auth/signup",
+    "/auth/forgot-password",
+    "/auth/reset-password",
     "/chat",
     "/generate/",
     "/intelligence/",
@@ -722,6 +727,16 @@ app.include_router(
     prefix="/video/physics-curriculum",
     tags=["Physics Video Curriculum"],
 )
+app.include_router(
+    chemistry_video.router,
+    prefix="/video/chemistry-curriculum",
+    tags=["Chemistry Video Curriculum"],
+)
+app.include_router(
+    social_science_video.router,
+    prefix="/video/social-science-curriculum",
+    tags=["Social Science Video Curriculum"],
+)
 app.include_router(study_profile.router, prefix="/study-profile", tags=["Study Profile"])
 app.include_router(learning_state.router, prefix="/learning-state", tags=["Learning State"])
 app.include_router(
@@ -764,3 +779,14 @@ app.mount(
     StaticFiles(directory=settings.resolved_generated_video_output_dir, check_dir=False),
     name="generated-videos",
 )
+# Learn Anything lesson cache (manifests + per-beat audio). Must live under a
+# writable path on Hugging Face (/app/generated/...), not monorepo public/.
+_learn_lesson_static = (
+    Path(__file__).resolve().parents[1] / "generated" / "learn-anything"
+)
+_learn_lesson_static.mkdir(parents=True, exist_ok=True)
+app.mount(
+    "/generated/learn-anything",
+    StaticFiles(directory=_learn_lesson_static, check_dir=False),
+    name="generated-learn-lessons",
+)

app/models/chat_session.py

@@ -1,7 +1,7 @@
 """Chat session and message persistence models."""
 from datetime import datetime
 
-from sqlalchemy import DateTime, ForeignKey, String, Text, func
+from sqlalchemy import JSON, DateTime, ForeignKey, Index, String, Text, UniqueConstraint, func
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.core.database import Base
@@ -10,6 +10,9 @@ from app.utils.ids import prefixed_id
 
 class ChatSession(Base):
     __tablename__ = "chat_sessions"
+    __table_args__ = (
+        Index("ix_chat_sessions_user_updated_at", "user_id", "updated_at"),
+    )
 
     id: Mapped[str] = mapped_column(
         String(40), primary_key=True, default=lambda: prefixed_id("csess"),
@@ -20,6 +23,12 @@ class ChatSession(Base):
     source_id: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)
     subject: Mapped[str] = mapped_column(String(120), nullable=False, default="")
     title: Mapped[str] = mapped_column(String(255), nullable=False, default="New chat")
+    # Structured academic origin (Tuition question, chapter/topic, uploaded
+    # source, and safe return route). This keeps continuity independent of the
+    # display title or free-form first message.
+    context_data: Mapped[dict[str, object]] = mapped_column(
+        JSON, nullable=False, default=dict,
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False,
     )
@@ -34,6 +43,14 @@ class ChatSession(Base):
 
 class ChatMessageRecord(Base):
     __tablename__ = "chat_messages"
+    __table_args__ = (
+        UniqueConstraint(
+            "session_id",
+            "client_turn_id",
+            "role",
+            name="uq_chat_messages_session_turn_role",
+        ),
+    )
 
     id: Mapped[str] = mapped_column(
         String(40), primary_key=True, default=lambda: prefixed_id("cmsg"),
@@ -45,6 +62,10 @@ class ChatMessageRecord(Base):
     content: Mapped[str] = mapped_column(Text, nullable=False)
     intent: Mapped[str | None] = mapped_column(String(40), nullable=True)
     evidence_label: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    client_turn_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    web_sources: Mapped[list[dict[str, object]]] = mapped_column(
+        JSON, nullable=False, default=list,
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False,
     )

app/models/learning_state.py

@@ -170,10 +170,18 @@ class LessonProgress(Base):
 
 class QuizAttempt(Base):
     __tablename__ = "quiz_attempts"
-    __table_args__ = (Index("ix_quiz_attempts_user_completed", "user_id", "completed_at"),)
+    __table_args__ = (
+        UniqueConstraint(
+            "user_id",
+            "client_attempt_id",
+            name="uq_quiz_attempts_user_client",
+        ),
+        Index("ix_quiz_attempts_user_completed", "user_id", "completed_at"),
+    )
 
     id: Mapped[str] = mapped_column(String(40), primary_key=True, default=lambda: prefixed_id("qat"))
     user_id: Mapped[str] = mapped_column(String(40), ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False)
+    client_attempt_id: Mapped[str | None] = mapped_column(String(180), nullable=True)
     quiz_id: Mapped[str | None] = mapped_column(String(40), nullable=True)
     daily_task_id: Mapped[str | None] = mapped_column(String(40), ForeignKey("daily_tasks.id", ondelete="SET NULL"), index=True, nullable=True)
     subject_id: Mapped[str | None] = mapped_column(String(40), ForeignKey("subjects.id", ondelete="SET NULL"), index=True, nullable=True)
@@ -298,6 +306,10 @@ class GeneratedResource(Base):
 
 class Subscription(Base):
     __tablename__ = "subscriptions"
+    __table_args__ = (
+        Index("ix_subscriptions_provider_customer", "provider_customer_id", unique=True),
+        Index("ix_subscriptions_provider_subscription", "provider_subscription_id", unique=True),
+    )
 
     id: Mapped[str] = mapped_column(String(40), primary_key=True, default=lambda: prefixed_id("subn"))
     user_id: Mapped[str] = mapped_column(String(40), ForeignKey("users.id", ondelete="CASCADE"), unique=True, index=True, nullable=False)
@@ -306,12 +318,33 @@ class Subscription(Base):
     usage_limits: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
     provider_customer_id: Mapped[str | None] = mapped_column(String(180), nullable=True)
     provider_subscription_id: Mapped[str | None] = mapped_column(String(180), nullable=True)
+    provider_price_id: Mapped[str | None] = mapped_column(String(180), nullable=True)
+    cancel_at_period_end: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     current_period_start: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     current_period_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
 
 
+class StripeWebhookEvent(Base):
+    """Minimal idempotency ledger for Stripe event delivery.
+
+    The raw webhook payload is deliberately not stored because it can contain
+    customer and payment data. The event ID is enough to prevent duplicate
+    entitlement changes while still allowing failed transactions to retry.
+    """
+
+    __tablename__ = "stripe_webhook_events"
+
+    event_id: Mapped[str] = mapped_column(String(180), primary_key=True)
+    event_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    processed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+
+
 class UsageEvent(Base):
     __tablename__ = "usage_events"
     __table_args__ = (Index("ix_usage_events_user_type_occurred", "user_id", "event_type", "occurred_at"),)

app/models/user.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from sqlalchemy import DateTime, String, func
+from sqlalchemy import DateTime, Integer, String, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.core.database import Base
@@ -18,6 +18,7 @@ class User(Base):
     name: Mapped[str] = mapped_column(String(120), nullable=False)
     email: Mapped[str] = mapped_column(String(255), unique=True, index=True, nullable=False)
     password_hash: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    auth_version: Mapped[int] = mapped_column(Integer, default=1, nullable=False)
     role: Mapped[str] = mapped_column(String(20), default="student", nullable=False)
     class_level: Mapped[str | None] = mapped_column(String(80), nullable=True)
     syllabus: Mapped[str | None] = mapped_column(String(120), nullable=True)

app/routes/ask.py

@@ -30,6 +30,7 @@ from app.services.source_guard import get_source_block_message
 from app.services.monthly_usage_service import increment_usage
 from app.services.usage_service import assert_generation_quota, record_generation
 from app.services.weak_topic_service import get_user_weak_topics, record_topic_attempt
+from app.services.workspace_context import workspace_context_directive
 
 # Better profiles for Ask DocDoe (re-uses spirit of context_builder RETRIEVAL_PROFILES)
 ASK_RETRIEVAL_PROFILES: dict[str, str] = {
@@ -327,6 +328,9 @@ def ask_docdoe(
     )
     response_evidence_label = evidence_ctx.evidence_label
     context = f"{context}\n\n{evidence_ctx.prompt_rules}" if context.strip() else evidence_ctx.prompt_rules
+    page_context = workspace_context_directive(payload.origin_page)
+    if page_context and context.strip():
+        context = f"{context}\n\n{page_context}"
 
     try:
         record_topic_attempt(
@@ -362,6 +366,7 @@ def ask_docdoe(
         "class_level": _grade,
         "subject": _subject,
         "exam": (_profile.exam if _profile else None),
+        "origin_page": payload.origin_page,
     }
 
     # enh5: pass weak topics to /ask generators too (so prompt_builder + _build use weak_topic directive)
@@ -395,6 +400,7 @@ def ask_docdoe(
                     "Do not refuse because a source is missing and do not make upload the main next step. "
                     "If the student sounds stressed, give one short reassuring line, then a practical plan. "
                     "Ask for an upload only when the user explicitly wants document-matched or PYQ evidence."
+                    + (f" {page_context}" if page_context else "")
                 ),
                 language=payload.language_preference or "English",
                 metadata=metadata,

app/routes/auth.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import json
+import hashlib
+import logging
+import secrets
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -9,21 +12,80 @@ from datetime import datetime, timedelta, timezone
 import jwt
 from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
 from fastapi.responses import RedirectResponse
-from sqlalchemy import select
+from sqlalchemy import delete, select, update
 from sqlalchemy.orm import Session
 
 from app.core.auth import create_access_token, hash_password, require_user, verify_password
 from app.core.config import get_settings
 from app.core.database import get_db
 from app.models.user import User
-from app.schemas.user import AuthLoginRequest, AuthSignupRequest, AuthTokenResponse, UserRead
+from app.models.password_reset_token import PasswordResetToken
+from app.schemas.user import (
+    AuthLoginRequest,
+    AuthSignupRequest,
+    AuthTokenResponse,
+    ForgotPasswordRequest,
+    ForgotPasswordResponse,
+    LoginOtpRequest,
+    LoginOtpRequestResponse,
+    LoginOtpVerifyRequest,
+    ResetPasswordRequest,
+    ResetPasswordResponse,
+    UserRead,
+)
+from app.services.email_service import (
+    password_email_delivery_configured,
+    send_login_otp_email,
+    send_password_reset_email,
+)
 
 
 router = APIRouter()
+logger = logging.getLogger(__name__)
 
 GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"
 GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
 GOOGLE_USERINFO_URL = "https://openidconnect.googleapis.com/v1/userinfo"
+PASSWORD_RESET_MESSAGE = (
+    "If a password account exists for that email, DocDoe will send a recovery link."
+)
+LOGIN_OTP_MESSAGE = (
+    "If an account exists for that email, DocDoe will send a 6-digit sign-in code."
+)
+LOGIN_OTP_TTL_MINUTES = 10
+
+
+def _validate_password(password: str) -> None:
+    if len(password) < 8 or len(password) > 128:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Use a password between 8 and 128 characters.",
+        )
+    if not any(character.isalpha() for character in password) or not any(
+        character.isdigit() for character in password
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Use at least one letter and one number in your password.",
+        )
+
+
+def _reset_token_hash(raw_token: str) -> str:
+    return hashlib.sha256(raw_token.encode("utf-8")).hexdigest()
+
+
+def _aware_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def _password_recovery_available() -> bool:
+    settings = get_settings()
+    return (
+        (settings.auth_provider or "jwt").strip().lower() == "jwt"
+        and password_email_delivery_configured()
+    )
 
 
 def _safe_next_path(next_path: str | None) -> str:
@@ -189,6 +251,7 @@ def signup(payload: AuthSignupRequest, db: Session = Depends(get_db)) -> AuthTok
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="A valid email is required.",
         )
+    _validate_password(payload.password)
 
     existing_user = db.scalar(select(User).where(User.email == normalized_email))
     if existing_user is not None:
@@ -239,6 +302,259 @@ def login(payload: AuthLoginRequest, db: Session = Depends(get_db)) -> AuthToken
     )
 
 
+def _otp_token_hash(user_id: str, code: str) -> str:
+    return _reset_token_hash(f"login-otp:{user_id}:{code.strip()}")
+
+
+@router.post(
+    "/login/otp/request",
+    response_model=LoginOtpRequestResponse,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+def request_login_otp(
+    payload: LoginOtpRequest,
+    db: Session = Depends(get_db),
+) -> LoginOtpRequestResponse:
+    if not _password_recovery_available():
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Email sign-in codes are temporarily unavailable.",
+        )
+
+    normalized_email = payload.email.strip().lower()
+    user = db.scalar(select(User).where(User.email == normalized_email))
+    if user is None or not user.password_hash:
+        return LoginOtpRequestResponse(message=LOGIN_OTP_MESSAGE)
+
+    settings = get_settings()
+    now = datetime.now(timezone.utc)
+    cooldown_start = now - timedelta(
+        seconds=max(settings.password_reset_request_cooldown_seconds, 1)
+    )
+    recent_token = db.scalar(
+        select(PasswordResetToken.id)
+        .where(
+            PasswordResetToken.user_id == user.id,
+            PasswordResetToken.created_at >= cooldown_start,
+            PasswordResetToken.used_at.is_(None),
+        )
+        .limit(1)
+    )
+    if recent_token is not None:
+        return LoginOtpRequestResponse(message=LOGIN_OTP_MESSAGE)
+
+    db.execute(
+        delete(PasswordResetToken).where(
+            PasswordResetToken.user_id == user.id,
+            PasswordResetToken.expires_at < now,
+        )
+    )
+
+    code = f"{secrets.randbelow(1_000_000):06d}"
+    otp_row = PasswordResetToken(
+        user_id=user.id,
+        token_hash=_otp_token_hash(user.id, code),
+        expires_at=now + timedelta(minutes=LOGIN_OTP_TTL_MINUTES),
+    )
+    db.add(otp_row)
+    db.commit()
+    db.refresh(otp_row)
+
+    delivered = send_login_otp_email(
+        recipient=user.email,
+        student_name=user.name,
+        code=code,
+        expires_minutes=LOGIN_OTP_TTL_MINUTES,
+        idempotency_key=f"docdoe-login-otp-{otp_row.id}",
+    )
+    if not delivered:
+        db.execute(delete(PasswordResetToken).where(PasswordResetToken.id == otp_row.id))
+        db.commit()
+        logger.warning("Login OTP email was not delivered")
+    return LoginOtpRequestResponse(message=LOGIN_OTP_MESSAGE)
+
+
+@router.post("/login/otp/verify", response_model=AuthTokenResponse)
+def verify_login_otp(
+    payload: LoginOtpVerifyRequest,
+    db: Session = Depends(get_db),
+) -> AuthTokenResponse:
+    if (get_settings().auth_provider or "jwt").strip().lower() != "jwt":
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Email sign-in codes are unavailable for this sign-in provider.",
+        )
+
+    normalized_email = payload.email.strip().lower()
+    code = payload.code.strip()
+    if not code.isdigit() or len(code) != 6:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired sign-in code.",
+        )
+
+    user = db.scalar(select(User).where(User.email == normalized_email))
+    if user is None or not user.password_hash:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired sign-in code.",
+        )
+
+    now = datetime.now(timezone.utc)
+    token_hash = _otp_token_hash(user.id, code)
+    otp_row = db.scalar(
+        select(PasswordResetToken)
+        .where(PasswordResetToken.token_hash == token_hash)
+        .with_for_update()
+    )
+    if (
+        otp_row is None
+        or otp_row.used_at is not None
+        or otp_row.user_id != user.id
+        or _aware_utc(otp_row.expires_at) <= now
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired sign-in code.",
+        )
+
+    otp_row.used_at = now
+    db.commit()
+
+    access_token, expires_in = create_access_token(user)
+    return AuthTokenResponse(
+        access_token=access_token,
+        expires_in=expires_in,
+        user=UserRead.model_validate(user),
+    )
+
+
+@router.post(
+    "/forgot-password",
+    response_model=ForgotPasswordResponse,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+def forgot_password(
+    payload: ForgotPasswordRequest,
+    db: Session = Depends(get_db),
+) -> ForgotPasswordResponse:
+    if not _password_recovery_available():
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Password recovery is temporarily unavailable. Try again shortly.",
+        )
+
+    normalized_email = payload.email.strip().lower()
+    user = db.scalar(select(User).where(User.email == normalized_email))
+    if user is None or not user.password_hash:
+        return ForgotPasswordResponse(message=PASSWORD_RESET_MESSAGE)
+
+    settings = get_settings()
+    now = datetime.now(timezone.utc)
+    cooldown_start = now - timedelta(
+        seconds=max(settings.password_reset_request_cooldown_seconds, 1)
+    )
+    recent_token = db.scalar(
+        select(PasswordResetToken.id)
+        .where(
+            PasswordResetToken.user_id == user.id,
+            PasswordResetToken.created_at >= cooldown_start,
+            PasswordResetToken.used_at.is_(None),
+        )
+        .limit(1)
+    )
+    if recent_token is not None:
+        return ForgotPasswordResponse(message=PASSWORD_RESET_MESSAGE)
+
+    db.execute(
+        delete(PasswordResetToken).where(
+            PasswordResetToken.user_id == user.id,
+            PasswordResetToken.expires_at < now,
+        )
+    )
+    raw_token = secrets.token_urlsafe(48)
+    reset_token = PasswordResetToken(
+        user_id=user.id,
+        token_hash=_reset_token_hash(raw_token),
+        expires_at=now
+        + timedelta(minutes=max(settings.password_reset_token_minutes, 5)),
+    )
+    db.add(reset_token)
+    db.commit()
+    db.refresh(reset_token)
+
+    query = urllib.parse.urlencode({"token": raw_token})
+    reset_url = f"{settings.frontend_base_url.rstrip('/')}/reset-password?{query}"
+    delivered = send_password_reset_email(
+        recipient=user.email,
+        student_name=user.name,
+        reset_url=reset_url,
+        idempotency_key=f"docdoe-password-reset-{reset_token.id}",
+    )
+    if not delivered:
+        db.execute(
+            delete(PasswordResetToken).where(PasswordResetToken.id == reset_token.id)
+        )
+        db.commit()
+        logger.warning("Password recovery email was not delivered")
+    return ForgotPasswordResponse(message=PASSWORD_RESET_MESSAGE)
+
+
+@router.post("/reset-password", response_model=ResetPasswordResponse)
+def reset_password(
+    payload: ResetPasswordRequest,
+    db: Session = Depends(get_db),
+) -> ResetPasswordResponse:
+    if (get_settings().auth_provider or "jwt").strip().lower() != "jwt":
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Password recovery is unavailable for this sign-in provider.",
+        )
+    _validate_password(payload.password)
+    now = datetime.now(timezone.utc)
+    token_hash = _reset_token_hash(payload.token)
+    reset_token = db.scalar(
+        select(PasswordResetToken)
+        .where(PasswordResetToken.token_hash == token_hash)
+        .with_for_update()
+    )
+    if (
+        reset_token is None
+        or reset_token.used_at is not None
+        or _aware_utc(reset_token.expires_at) <= now
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="This recovery link is invalid or expired. Request a new one.",
+        )
+
+    user = db.get(User, reset_token.user_id)
+    if user is None or not user.password_hash:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="This recovery link is invalid or expired. Request a new one.",
+        )
+    if verify_password(payload.password, user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Choose a password you have not already used for this account.",
+        )
+
+    user.password_hash = hash_password(payload.password)
+    user.auth_version += 1
+    db.add(user)
+    db.execute(
+        update(PasswordResetToken)
+        .where(
+            PasswordResetToken.user_id == user.id,
+            PasswordResetToken.used_at.is_(None),
+        )
+        .values(used_at=now)
+    )
+    db.commit()
+    return ResetPasswordResponse(reset=True)
+
+
 @router.get("/session", response_model=UserRead)
 def session(current_user: User = Depends(require_user)) -> User:
     return current_user

app/routes/billing.py

@@ -1,67 +1,64 @@
 from __future__ import annotations
 
-import json
+import hashlib
+import logging
+from collections.abc import Mapping
 from datetime import datetime, timedelta, timezone
+from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status
-from pydantic import BaseModel, ConfigDict
-from sqlalchemy import select
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy import or_, select
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.core.auth import require_user
 from app.core.config import get_settings
 from app.core.database import get_db
+from app.models.learning_state import StripeWebhookEvent, Subscription
 from app.models.user import User
 from app.models.user_plan import UserPlan
+from app.services.plan_catalog import (
+    get_billing_plan_defaults,
+    get_monthly_usage_limits,
+    get_plan_config,
+)
 
 try:
     import stripe  # type: ignore
-except Exception:  # pragma: no cover
+except Exception:  # pragma: no cover - optional dependency in minimal local installs
     stripe = None  # type: ignore[assignment]
 
-import logging
 
 logger = logging.getLogger(__name__)
-
 router = APIRouter()
 
-
-PLAN_DEFAULTS: dict[str, dict] = {
-    "free_trial": {
-        "monthly_video_limit": 2,
-        "monthly_generation_limit": 20,
-        "coming_soon": False,
-    },
-    "starter_199": {
-        "monthly_video_limit": 10,
-        "monthly_generation_limit": 100,
-        "coming_soon": False,
-    },
-    "popular_299": {
-        "monthly_video_limit": 20,
-        "monthly_generation_limit": 200,
-        "coming_soon": False,
-    },
-    "premium_599": {
-        "monthly_video_limit": 30,
-        "monthly_generation_limit": 300,
-        "coming_soon": False,
-    },
-    "advanced_1299": {
-        "monthly_video_limit": 50,
-        "monthly_generation_limit": 500,
-        "coming_soon": True,
-    },
-}
-
-# Plan used when a trial is started (equivalent to popular_299).
+PLAN_DEFAULTS = get_billing_plan_defaults()
 _TRIAL_PLAN_KEY = "popular_299"
-_ACTIVE_PAID_CHECKOUT_PLANS = {"popular_299", "premium_599"}
+_FREE_PLAN_KEY = "free_trial"
+_ACTIVE_PAID_CHECKOUT_PLANS = ("popular_299", "premium_599")
+_DIRECT_SELECT_PLAN_KEYS = {
+    "free_trial",
+    "starter_199",
+    "popular_299",
+    "premium_599",
+    "advanced_1299",
+}
+_ACTIVE_PROVIDER_STATUSES = {"active", "trialing", "past_due"}
+_ATTACHED_PROVIDER_STATUSES = _ACTIVE_PROVIDER_STATUSES | {"payment_pending"}
+_CONFIRMED_CHECKOUT_PAYMENT_STATUSES = {"paid", "no_payment_required"}
+_TRIAL_DAYS = 3
+_PLAN_DISPLAY_NAMES = {
+    "free_trial": "Free",
+    "popular_299": "Popular",
+    "premium_599": "Premium",
+}
 
 
 class UserPlanRead(BaseModel):
     user_id: str
     selected_plan: str
+    plan_name: str
     status: str
     trial_started_at: datetime | None
     trial_ends_at: datetime | None
@@ -70,10 +67,14 @@ class UserPlanRead(BaseModel):
     monthly_generation_limit: int
     monthly_generation_used: int
     coming_soon: bool = False
-    # Derived convenience fields for frontend
     remaining_generations: int = 0
     remaining_videos: int = 0
     usage_warning: str | None = None
+    checkout_plan_keys: list[str] = Field(default_factory=list)
+    portal_available: bool = False
+    current_period_end: datetime | None = None
+    cancel_at_period_end: bool = False
+    billing_message: str | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -82,263 +83,959 @@ class SelectPlanRequest(BaseModel):
     plan: str
 
 
+class CreateCheckoutRequest(BaseModel):
+    plan: str
+
+
+class CheckoutResponse(BaseModel):
+    url: str
+    session_id: str
+
+
+class PortalResponse(BaseModel):
+    url: str
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _plan_config(plan_key: str):
+    config = get_plan_config(plan_key)
+    if config is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unknown plan '{plan_key}'.",
+        )
+    return config
+
+
 def _get_or_create_plan(db: Session, user_id: str) -> UserPlan:
     plan = db.scalar(select(UserPlan).where(UserPlan.user_id == user_id))
     if plan is not None:
         return plan
-    defaults = PLAN_DEFAULTS["free_trial"]
+
+    config = _plan_config(_FREE_PLAN_KEY)
     plan = UserPlan(
         user_id=user_id,
-        selected_plan="free_trial",
+        selected_plan=_FREE_PLAN_KEY,
         status="active",
-        monthly_video_limit=defaults["monthly_video_limit"],
-        monthly_generation_limit=defaults["monthly_generation_limit"],
+        period_start=_utc_now(),
+        monthly_video_limit=config.monthly_video_limit,
+        monthly_generation_limit=config.monthly_generation_limit,
     )
     db.add(plan)
-    db.commit()
-    db.refresh(plan)
+    db.flush()
     return plan
 
 
-def _plan_read(plan: UserPlan) -> UserPlanRead:
-    coming_soon = PLAN_DEFAULTS.get(plan.selected_plan, {}).get("coming_soon", False)
-    data = UserPlanRead.model_validate(plan)
-    data.coming_soon = coming_soon
-    data.remaining_generations = max(0, plan.monthly_generation_limit - plan.monthly_generation_used)
-    data.remaining_videos = max(0, plan.monthly_video_limit - plan.monthly_video_used)
-    gen_pct = (plan.monthly_generation_used / max(1, plan.monthly_generation_limit)) * 100
-    vid_pct = (plan.monthly_video_used / max(1, plan.monthly_video_limit)) * 100
-    if gen_pct >= 100 or vid_pct >= 100:
-        data.usage_warning = "You have reached your monthly limit. Upgrade to continue."
-    elif gen_pct >= 80 or vid_pct >= 80:
+def _get_or_create_subscription(
+    db: Session,
+    user_id: str,
+    *,
+    plan_key: str = _FREE_PLAN_KEY,
+) -> Subscription:
+    subscription = db.scalar(
+        select(Subscription).where(Subscription.user_id == user_id)
+    )
+    if subscription is not None:
+        return subscription
+
+    subscription = Subscription(
+        user_id=user_id,
+        plan_key=plan_key,
+        status="active",
+        usage_limits=get_monthly_usage_limits(plan_key),
+    )
+    db.add(subscription)
+    db.flush()
+    return subscription
+
+
+def _configured_checkout_plan_keys() -> list[str]:
+    settings = get_settings()
+    if (
+        stripe is None
+        or not settings.stripe_secret_key
+        or not settings.stripe_webhook_secret
+    ):
+        return []
+    return [
+        plan_key
+        for plan_key in _ACTIVE_PAID_CHECKOUT_PLANS
+        if settings.get_stripe_price_id(plan_key)
+    ]
+
+
+def _plan_read(plan: UserPlan, subscription: Subscription | None) -> UserPlanRead:
+    config = get_plan_config(plan.selected_plan) or _plan_config(_FREE_PLAN_KEY)
+    effective_status = subscription.status if subscription is not None else plan.status
+    data = UserPlanRead(
+        user_id=plan.user_id,
+        selected_plan=plan.selected_plan,
+        plan_name=(
+            "Free Trial"
+            if effective_status == "trialing"
+            and not subscription.provider_subscription_id
+            else _PLAN_DISPLAY_NAMES.get(
+                plan.selected_plan,
+                config.display_name.replace(" (Legacy)", ""),
+            )
+        ),
+        status=effective_status,
+        trial_started_at=plan.trial_started_at,
+        trial_ends_at=plan.trial_ends_at,
+        monthly_video_limit=plan.monthly_video_limit,
+        monthly_video_used=plan.monthly_video_used,
+        monthly_generation_limit=plan.monthly_generation_limit,
+        monthly_generation_used=plan.monthly_generation_used,
+        coming_soon=config.coming_soon,
+        remaining_generations=max(
+            0, plan.monthly_generation_limit - plan.monthly_generation_used
+        ),
+        remaining_videos=max(0, plan.monthly_video_limit - plan.monthly_video_used),
+        checkout_plan_keys=_configured_checkout_plan_keys(),
+        portal_available=bool(
+            subscription
+            and subscription.provider_customer_id
+            and subscription.provider_subscription_id
+            and subscription.status in _ATTACHED_PROVIDER_STATUSES
+            and stripe is not None
+            and get_settings().stripe_secret_key
+        ),
+        current_period_end=subscription.current_period_end if subscription else None,
+        cancel_at_period_end=subscription.cancel_at_period_end
+        if subscription
+        else False,
+    )
+
+    generation_pct = (
+        plan.monthly_generation_used / max(1, plan.monthly_generation_limit)
+    ) * 100
+    video_pct = (plan.monthly_video_used / max(1, plan.monthly_video_limit)) * 100
+    if generation_pct >= 100 or video_pct >= 100:
+        data.usage_warning = "You have reached your current plan limit."
+    elif generation_pct >= 80 or video_pct >= 80:
         data.usage_warning = (
-            f"You are using {max(gen_pct, vid_pct):.0f}% of your monthly limit."
+            f"You have used {max(generation_pct, video_pct):.0f}% of your current plan."
         )
+
+    if subscription and subscription.status == "payment_pending":
+        data.billing_message = "Stripe has not confirmed this payment yet. Your current access is unchanged."
+    elif subscription and subscription.status == "past_due":
+        data.billing_message = "Your latest payment needs attention. Open billing to update the payment method."
+    elif subscription and subscription.cancel_at_period_end:
+        data.billing_message = (
+            "Your paid access remains active until the end of this period."
+        )
+    elif not data.checkout_plan_keys:
+        data.billing_message = "Paid upgrades are not accepting payments yet. Your current plan is unchanged."
     return data
 
 
-@router.get("/me", response_model=UserPlanRead,
-            summary="Get my billing plan",
-            description="Returns current plan, usage counts, remaining limits, and trial status.")
+def _apply_plan_limits(
+    plan: UserPlan,
+    plan_key: str,
+    *,
+    status_value: str,
+    reset_usage: bool,
+    period_start: datetime | None = None,
+) -> None:
+    config = _plan_config(plan_key)
+    plan.selected_plan = plan_key
+    plan.status = status_value
+    plan.monthly_video_limit = config.monthly_video_limit
+    plan.monthly_generation_limit = config.monthly_generation_limit
+    if reset_usage:
+        plan.monthly_video_used = 0
+        plan.monthly_generation_used = 0
+    if period_start is not None:
+        plan.period_start = period_start
+
+
+def _expire_trial_if_needed(plan: UserPlan, subscription: Subscription) -> None:
+    if plan.status != "trialing" or plan.trial_ends_at is None:
+        return
+    trial_end = plan.trial_ends_at
+    if trial_end.tzinfo is None:
+        trial_end = trial_end.replace(tzinfo=timezone.utc)
+    if _utc_now() <= trial_end:
+        return
+    _apply_plan_limits(
+        plan,
+        _FREE_PLAN_KEY,
+        status_value="trial_expired",
+        reset_usage=False,
+        period_start=plan.period_start,
+    )
+    subscription.status = "expired"
+    subscription.current_period_end = trial_end
+
+
+def _sync_subscription_projection(
+    subscription: Subscription,
+    *,
+    plan_key: str,
+    status_value: str,
+    provider_customer_id: str | None = None,
+    provider_subscription_id: str | None = None,
+    provider_price_id: str | None = None,
+    current_period_start: datetime | None = None,
+    current_period_end: datetime | None = None,
+    cancel_at_period_end: bool | None = None,
+) -> None:
+    subscription.plan_key = plan_key
+    subscription.status = status_value
+    subscription.usage_limits = get_monthly_usage_limits(plan_key)
+    if provider_customer_id:
+        subscription.provider_customer_id = provider_customer_id
+    if provider_subscription_id:
+        subscription.provider_subscription_id = provider_subscription_id
+    if provider_price_id:
+        subscription.provider_price_id = provider_price_id
+    if current_period_start is not None:
+        subscription.current_period_start = current_period_start
+    if current_period_end is not None:
+        subscription.current_period_end = current_period_end
+    if cancel_at_period_end is not None:
+        subscription.cancel_at_period_end = cancel_at_period_end
+
+
+@router.get(
+    "/me",
+    response_model=UserPlanRead,
+    summary="Get my billing plan",
+    description="Returns the authenticated student's persisted plan, usage, and Stripe lifecycle state.",
+)
 def get_my_plan(
     db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> UserPlanRead:
-    return _plan_read(_get_or_create_plan(db, current_user.id))
+    plan = _get_or_create_plan(db, current_user.id)
+    subscription = _get_or_create_subscription(
+        db, current_user.id, plan_key=plan.selected_plan
+    )
+    _expire_trial_if_needed(plan, subscription)
+    db.commit()
+    db.refresh(plan)
+    db.refresh(subscription)
+    return _plan_read(plan, subscription)
 
 
-@router.post("/select-plan", response_model=UserPlanRead,
-             summary="Select a billing plan",
-             description="Select a billing plan. Active paid plans are popular_299 and premium_599; legacy keys remain accepted outside production for compatibility.")
+@router.post(
+    "/select-plan",
+    response_model=UserPlanRead,
+    summary="Select a development/free plan",
+    description="Paid activation is always routed through Stripe Checkout in production.",
+)
 def select_plan(
     payload: SelectPlanRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> UserPlanRead:
     plan_key = payload.plan.strip().lower()
-    if plan_key not in PLAN_DEFAULTS:
+    if plan_key not in _DIRECT_SELECT_PLAN_KEYS:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Unknown plan '{payload.plan}'. Valid plans: {', '.join(PLAN_DEFAULTS)}.",
+            detail=f"Unknown plan '{payload.plan}'.",
         )
-    if get_settings().environment == "production" and plan_key != "free_trial":
+    if get_settings().environment == "production" and plan_key != _FREE_PLAN_KEY:
         raise HTTPException(
             status_code=status.HTTP_402_PAYMENT_REQUIRED,
-            detail=(
-                "Paid plan activation requires checkout. Direct selection disabled in production. "
-                "Use POST /billing/create-checkout-session with the desired plan instead."
-            ),
+            detail="Paid plan activation requires secure checkout.",
         )
+
+    config = _plan_config(plan_key)
     plan = _get_or_create_plan(db, current_user.id)
-    plan.selected_plan = plan_key
-    defaults = PLAN_DEFAULTS[plan_key]
-    plan.monthly_video_limit = defaults["monthly_video_limit"]
-    plan.monthly_generation_limit = defaults["monthly_generation_limit"]
-    plan.status = "active"
-    db.add(plan)
+    subscription = _get_or_create_subscription(db, current_user.id)
+    _apply_plan_limits(
+        plan,
+        plan_key,
+        status_value="active",
+        reset_usage=False,
+        period_start=plan.period_start or _utc_now(),
+    )
+    _sync_subscription_projection(
+        subscription,
+        plan_key=plan_key,
+        status_value="active",
+    )
     db.commit()
     db.refresh(plan)
-    return _plan_read(plan)
+    db.refresh(subscription)
+    result = _plan_read(plan, subscription)
+    result.coming_soon = config.coming_soon
+    return result
 
 
-@router.post("/start-trial", response_model=UserPlanRead,
-             summary="Start free trial",
-             description="Start a 7-day free trial with Popular plan limits. Can only be started once per user.")
+@router.post(
+    "/start-trial",
+    response_model=UserPlanRead,
+    summary="Start the one-time free trial",
+    description="Starts the persisted three-day trial once per authenticated student.",
+)
 def start_trial(
     db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> UserPlanRead:
     plan = _get_or_create_plan(db, current_user.id)
+    subscription = _get_or_create_subscription(db, current_user.id)
     if plan.trial_started_at is not None:
-        return _plan_read(plan)
-    now = datetime.now(timezone.utc)
-    plan.trial_started_at = now
-    plan.trial_ends_at = now + timedelta(days=7)
+        db.commit()
+        return _plan_read(plan, subscription)
+    if (
+        subscription.provider_subscription_id
+        and subscription.status in _ACTIVE_PROVIDER_STATUSES
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="A paid membership is already attached to this account.",
+        )
+
+    now = _utc_now()
+    trial_config = _plan_config(_TRIAL_PLAN_KEY)
+    # Persist the entitlement tier itself so every usage service sees the same
+    # Popular limits. The trialing status and dates identify that it is unpaid.
+    plan.selected_plan = _TRIAL_PLAN_KEY
     plan.status = "trialing"
-    defaults = PLAN_DEFAULTS[_TRIAL_PLAN_KEY]
-    plan.monthly_video_limit = defaults["monthly_video_limit"]
-    plan.monthly_generation_limit = defaults["monthly_generation_limit"]
-    db.add(plan)
+    plan.trial_started_at = now
+    plan.trial_ends_at = now + timedelta(days=_TRIAL_DAYS)
+    plan.period_start = now
+    plan.monthly_video_limit = trial_config.monthly_video_limit
+    plan.monthly_generation_limit = trial_config.monthly_generation_limit
+    plan.monthly_video_used = 0
+    plan.monthly_generation_used = 0
+    _sync_subscription_projection(
+        subscription,
+        plan_key=_TRIAL_PLAN_KEY,
+        status_value="trialing",
+        current_period_start=now,
+        current_period_end=plan.trial_ends_at,
+        cancel_at_period_end=False,
+    )
     db.commit()
     db.refresh(plan)
-    return _plan_read(plan)
+    db.refresh(subscription)
+    return _plan_read(plan, subscription)
 
 
-# ===================== REAL STRIPE BILLING (10kx SaaS) =====================
+def _stripe_client_or_503(*, require_webhook: bool) -> Any:
+    settings = get_settings()
+    if stripe is None or not settings.stripe_secret_key:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Secure billing is not available yet. No payment was started.",
+        )
+    if require_webhook and not settings.stripe_webhook_secret:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Secure billing is not ready to activate memberships. No payment was started.",
+        )
+    stripe.api_key = settings.stripe_secret_key
+    stripe.api_version = settings.stripe_api_version
+    return stripe
 
-class CreateCheckoutRequest(BaseModel):
-    plan: str
 
+def _object_value(value: Any, key: str, default: Any = None) -> Any:
+    if isinstance(value, Mapping):
+        return value.get(key, default)
+    getter = getattr(value, "get", None)
+    if callable(getter):
+        return getter(key, default)
+    return getattr(value, key, default)
 
-class CheckoutResponse(BaseModel):
-    # Primary fields per production contract: {url, session_id}. checkout_url kept for frontend compat during transition.
-    url: str | None = None
-    session_id: str | None = None
-    mode: str = "live"  # or "demo" when no Stripe key
-    message: str | None = None
-    checkout_url: str | None = None  # deprecated alias; prefer url
 
+def _stripe_id(value: Any) -> str | None:
+    if isinstance(value, str):
+        return value or None
+    object_id = _object_value(value, "id")
+    return object_id if isinstance(object_id, str) and object_id else None
 
-def _get_stripe_client():
-    settings = get_settings()
-    if not settings.stripe_enabled or stripe is None:
-        return None
-    stripe.api_key = settings.stripe_secret_key
-    return stripe
 
+def _checkout_idempotency_key(user_id: str, plan_key: str) -> str:
+    five_minute_window = int(_utc_now().timestamp()) // 300
+    digest = hashlib.sha256(
+        f"{user_id}:{plan_key}:{five_minute_window}".encode()
+    ).hexdigest()[:32]
+    return f"docdoe_checkout_{digest}"
 
-@router.post("/create-checkout-session", response_model=CheckoutResponse,
-             summary="Create Stripe Checkout for paid plan",
-             description="Returns a Stripe-hosted checkout URL. In production requires valid STRIPE_SECRET_KEY + price IDs.")
+
+@router.post(
+    "/create-checkout-session",
+    response_model=CheckoutResponse,
+    summary="Create secure Stripe Checkout",
+    description="Creates a Stripe-hosted subscription Checkout only when webhook activation is configured.",
+)
 def create_checkout_session(
     payload: CreateCheckoutRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> CheckoutResponse:
     plan_key = payload.plan.strip().lower()
-    if plan_key not in PLAN_DEFAULTS:
-        raise HTTPException(status_code=400, detail=f"Unknown plan: {plan_key}")
-
-    if plan_key == "free_trial":
-        raise HTTPException(
-            status_code=400,
-            detail="Free trial does not require Stripe checkout. Use POST /billing/start-trial (or /select-plan for free).",
-        )
-
-    defaults = PLAN_DEFAULTS[plan_key]
     if plan_key not in _ACTIVE_PAID_CHECKOUT_PLANS:
         raise HTTPException(
-            status_code=402,
+            status_code=status.HTTP_402_PAYMENT_REQUIRED,
             detail="This plan is not available for checkout. Choose the 299 or 599 plan.",
         )
-    if defaults.get("coming_soon"):
-        raise HTTPException(status_code=402, detail="This plan is coming soon.")
 
     settings = get_settings()
-    client = _get_stripe_client()
-
-    if not client:
-        # Demo / no-key mode: return a placeholder that frontend can handle
-        demo_url = f"/pricing?demo_upgrade={plan_key}"
-        return CheckoutResponse(
-            url=demo_url,
-            checkout_url=demo_url,
-            mode="demo",
-            message="Stripe not configured (dev/demo). In production this would redirect to real Stripe Checkout.",
-        )
-
+    client = _stripe_client_or_503(require_webhook=True)
     price_id = settings.get_stripe_price_id(plan_key)
     if not price_id:
-        # Fallback to a safe message — real deploys must set price IDs
-        return CheckoutResponse(
-            url=None,
-            checkout_url=None,
-            mode="live",
-            message="Stripe price ID not configured for this plan. Set STRIPE_PRICE_IDS in backend env.",
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="This membership is not accepting payments yet. No payment was started.",
+        )
+
+    subscription = _get_or_create_subscription(db, current_user.id)
+    if (
+        subscription.provider_subscription_id
+        and subscription.status in _ATTACHED_PROVIDER_STATUSES
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="This account already has a Stripe membership. Use Manage billing to change it.",
         )
 
+    metadata = {
+        "app": "docdoe",
+        "user_id": current_user.id,
+        "plan_key": plan_key,
+    }
     try:
-        # Use Stripe Checkout hosted (recommended). Omit payment_method_types to let Stripe use dynamic payment methods
-        # per best practices (dashboard settings control wallets etc automatically).
+        if not subscription.provider_customer_id:
+            customer = client.Customer.create(
+                email=current_user.email,
+                name=current_user.name,
+                metadata={"app": "docdoe", "user_id": current_user.id},
+                idempotency_key=f"docdoe_customer_{current_user.id}",
+            )
+            customer_id = _stripe_id(customer)
+            if not customer_id:
+                raise RuntimeError("Stripe did not return a customer ID")
+            subscription.provider_customer_id = customer_id
+            db.commit()
+            db.refresh(subscription)
+
         session = client.checkout.Session.create(
             line_items=[{"price": price_id, "quantity": 1}],
             mode="subscription",
-            success_url=f"{settings.frontend_base_url}/pricing?success=1&session_id={{CHECKOUT_SESSION_ID}}",
+            customer=subscription.provider_customer_id,
+            success_url=(
+                f"{settings.frontend_base_url}/pricing"
+                f"?success=1&session_id={{CHECKOUT_SESSION_ID}}"
+            ),
             cancel_url=f"{settings.frontend_base_url}/pricing?canceled=1",
             client_reference_id=current_user.id,
-            metadata={"plan_key": plan_key, "user_id": current_user.id},
+            metadata=metadata,
+            subscription_data={"metadata": metadata},
+            integration_identifier=settings.stripe_checkout_integration_identifier,
+            idempotency_key=_checkout_idempotency_key(current_user.id, plan_key),
         )
-        return CheckoutResponse(url=session.url, session_id=session.id, checkout_url=session.url, mode="live")
-    except Exception as exc:  # pragma: no cover
-        raise HTTPException(status_code=502, detail=f"Stripe session creation failed: {str(exc)[:200]}") from exc
+    except HTTPException:
+        raise
+    except Exception as exc:
+        db.rollback()
+        logger.exception(
+            "Stripe Checkout creation failed for user_id=%s plan=%s",
+            current_user.id,
+            plan_key,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="Secure checkout could not be started. No payment was completed.",
+        ) from exc
+
+    session_id = _stripe_id(session)
+    session_url = _object_value(session, "url")
+    if not session_id or not isinstance(session_url, str) or not session_url:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="Stripe did not return a usable checkout session. No payment was completed.",
+        )
+    return CheckoutResponse(url=session_url, session_id=session_id)
+
+
+@router.post(
+    "/create-portal-session",
+    response_model=PortalResponse,
+    summary="Open Stripe Billing Portal",
+    description="Creates a customer-scoped Stripe Billing Portal session for the authenticated student.",
+)
+def create_portal_session(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(require_user),
+) -> PortalResponse:
+    client = _stripe_client_or_503(require_webhook=False)
+    subscription = db.scalar(
+        select(Subscription).where(Subscription.user_id == current_user.id)
+    )
+    if (
+        subscription is None
+        or not subscription.provider_customer_id
+        or not subscription.provider_subscription_id
+    ):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="No Stripe membership is attached to this account.",
+        )
+
+    try:
+        portal = client.billing_portal.Session.create(
+            customer=subscription.provider_customer_id,
+            return_url=f"{get_settings().frontend_base_url}/settings",
+        )
+    except Exception as exc:
+        logger.exception(
+            "Stripe Billing Portal creation failed for user_id=%s", current_user.id
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="Billing management could not be opened. Try again shortly.",
+        ) from exc
+
+    portal_url = _object_value(portal, "url")
+    if not isinstance(portal_url, str) or not portal_url:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail="Stripe did not return a billing portal URL.",
+        )
+    return PortalResponse(url=portal_url)
+
+
+def _timestamp(value: Any) -> datetime | None:
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value, tz=timezone.utc)
+    return None
+
+
+def _metadata(data: Any) -> Mapping[str, Any]:
+    value = _object_value(data, "metadata", {})
+    return value if isinstance(value, Mapping) else {}
+
+
+def _subscription_id_from_invoice(data: Any) -> str | None:
+    direct = _stripe_id(_object_value(data, "subscription"))
+    if direct:
+        return direct
+    parent = _object_value(data, "parent", {})
+    details = _object_value(parent, "subscription_details", {})
+    return _stripe_id(_object_value(details, "subscription"))
+
+
+def _invoice_period(data: Any) -> tuple[datetime | None, datetime | None]:
+    period_start = _timestamp(_object_value(data, "period_start"))
+    period_end = _timestamp(_object_value(data, "period_end"))
+    if period_start or period_end:
+        return period_start, period_end
+
+    lines = _object_value(data, "lines", {})
+    line_items = _object_value(lines, "data", [])
+    if isinstance(line_items, list) and line_items:
+        period = _object_value(line_items[0], "period", {})
+        return (
+            _timestamp(_object_value(period, "start")),
+            _timestamp(_object_value(period, "end")),
+        )
+    return None, None
+
+
+def _find_subscription_for_provider_event(
+    db: Session,
+    data: Any,
+) -> Subscription | None:
+    subscription_id = _stripe_id(_object_value(data, "id"))
+    object_name = _object_value(data, "object")
+    if object_name == "invoice":
+        subscription_id = _subscription_id_from_invoice(data)
+    customer_id = _stripe_id(_object_value(data, "customer"))
+    conditions = []
+    if subscription_id:
+        conditions.append(Subscription.provider_subscription_id == subscription_id)
+    if customer_id:
+        conditions.append(Subscription.provider_customer_id == customer_id)
+    if not conditions:
+        return None
+    return db.scalar(select(Subscription).where(or_(*conditions)))
+
+
+def _plan_key_from_price_id(price_id: str | None) -> str | None:
+    if not price_id:
+        return None
+    settings = get_settings()
+    for plan_key in _ACTIVE_PAID_CHECKOUT_PLANS:
+        if settings.get_stripe_price_id(plan_key) == price_id:
+            return plan_key
+    return None
+
+
+def _price_id_from_subscription(data: Any) -> str | None:
+    items = _object_value(data, "items", {})
+    item_data = _object_value(items, "data", [])
+    if not isinstance(item_data, list) or not item_data:
+        return None
+    price = _object_value(item_data[0], "price")
+    return _stripe_id(price)
+
+
+def _provider_status(value: Any) -> str:
+    raw = str(value or "").lower()
+    if raw == "canceled":
+        return "cancelled"
+    if raw in {"active", "trialing", "past_due"}:
+        return raw
+    if raw in {"unpaid", "paused", "incomplete_expired"}:
+        return "expired"
+    if raw == "incomplete":
+        return "past_due"
+    return "active"
+
+
+def _assert_provider_ownership(
+    subscription: Subscription,
+    *,
+    customer_id: str | None,
+    provider_subscription_id: str | None,
+) -> None:
+    """Reject provider identifiers already bound to a different local record."""
+
+    if (
+        customer_id
+        and subscription.provider_customer_id
+        and subscription.provider_customer_id != customer_id
+    ):
+        raise RuntimeError("Stripe customer does not match the account billing record")
+    if (
+        provider_subscription_id
+        and subscription.provider_subscription_id
+        and subscription.provider_subscription_id != provider_subscription_id
+        and subscription.status not in {"cancelled", "expired"}
+    ):
+        raise RuntimeError(
+            "Stripe subscription does not match the account billing record"
+        )
+
+
+def _bind_pending_checkout(
+    subscription: Subscription,
+    *,
+    plan_key: str,
+    customer_id: str,
+    provider_subscription_id: str,
+) -> None:
+    _assert_provider_ownership(
+        subscription,
+        customer_id=customer_id,
+        provider_subscription_id=provider_subscription_id,
+    )
+    _sync_subscription_projection(
+        subscription,
+        plan_key=plan_key,
+        status_value="payment_pending",
+        provider_customer_id=customer_id,
+        provider_subscription_id=provider_subscription_id,
+        provider_price_id=get_settings().get_stripe_price_id(plan_key),
+        cancel_at_period_end=False,
+    )
+
+
+def _downgrade_to_free(
+    plan: UserPlan,
+    subscription: Subscription,
+    *,
+    status_value: str,
+) -> None:
+    now = _utc_now()
+    _apply_plan_limits(
+        plan,
+        _FREE_PLAN_KEY,
+        status_value=status_value,
+        reset_usage=True,
+        period_start=now,
+    )
+    subscription.status = status_value
+    subscription.cancel_at_period_end = False
+    subscription.current_period_end = now
+
+
+def _process_checkout_completed(db: Session, data: Any) -> None:
+    metadata = _metadata(data)
+    if metadata.get("app") != "docdoe":
+        return
+    user_id = _object_value(data, "client_reference_id") or metadata.get("user_id")
+    plan_key = metadata.get("plan_key")
+    if not isinstance(user_id, str) or plan_key not in _ACTIVE_PAID_CHECKOUT_PLANS:
+        raise RuntimeError("DocDoe Checkout event is missing valid ownership metadata")
+
+    customer_id = _stripe_id(_object_value(data, "customer"))
+    provider_subscription_id = _stripe_id(_object_value(data, "subscription"))
+    if not customer_id or not provider_subscription_id:
+        raise RuntimeError("DocDoe Checkout event is missing provider identifiers")
+
+    now = _utc_now()
+    plan = _get_or_create_plan(db, user_id)
+    subscription = _get_or_create_subscription(db, user_id)
+    _assert_provider_ownership(
+        subscription,
+        customer_id=customer_id,
+        provider_subscription_id=provider_subscription_id,
+    )
+    payment_status = str(_object_value(data, "payment_status", "")).lower()
+    if payment_status not in _CONFIRMED_CHECKOUT_PAYMENT_STATUSES:
+        _bind_pending_checkout(
+            subscription,
+            plan_key=plan_key,
+            customer_id=customer_id,
+            provider_subscription_id=provider_subscription_id,
+        )
+        return
+
+    _apply_plan_limits(
+        plan,
+        plan_key,
+        status_value="active",
+        reset_usage=True,
+        period_start=now,
+    )
+    plan.trial_ends_at = None
+    _sync_subscription_projection(
+        subscription,
+        plan_key=plan_key,
+        status_value="active",
+        provider_customer_id=customer_id,
+        provider_subscription_id=provider_subscription_id,
+        provider_price_id=get_settings().get_stripe_price_id(plan_key),
+        current_period_start=now,
+        cancel_at_period_end=False,
+    )
+
+
+def _process_subscription_change(
+    db: Session,
+    data: Any,
+    *,
+    deleted: bool,
+) -> None:
+    metadata = _metadata(data)
+    subscription = _find_subscription_for_provider_event(db, data)
+    if subscription is None:
+        if metadata.get("app") != "docdoe":
+            return
+        user_id = metadata.get("user_id")
+        if not isinstance(user_id, str):
+            raise RuntimeError(
+                "DocDoe subscription event is missing ownership metadata"
+            )
+        subscription = _get_or_create_subscription(db, user_id)
+
+    provider_subscription_id = _stripe_id(_object_value(data, "id"))
+    customer_id = _stripe_id(_object_value(data, "customer"))
+    _assert_provider_ownership(
+        subscription,
+        customer_id=customer_id,
+        provider_subscription_id=provider_subscription_id,
+    )
+    price_id = _price_id_from_subscription(data)
+    plan_key = (
+        metadata.get("plan_key")
+        or _plan_key_from_price_id(price_id)
+        or subscription.plan_key
+    )
+    if plan_key not in _ACTIVE_PAID_CHECKOUT_PLANS:
+        if metadata.get("app") == "docdoe":
+            raise RuntimeError("DocDoe subscription event has an unknown price/plan")
+        return
+
+    status_value = (
+        "cancelled" if deleted else _provider_status(_object_value(data, "status"))
+    )
+    period_start = _timestamp(_object_value(data, "current_period_start"))
+    period_end = _timestamp(_object_value(data, "current_period_end"))
+    cancel_at_period_end = bool(_object_value(data, "cancel_at_period_end", False))
+    plan = _get_or_create_plan(db, subscription.user_id)
+
+    if status_value in {"cancelled", "expired"}:
+        _downgrade_to_free(plan, subscription, status_value=status_value)
+    else:
+        entitlement_already_active = (
+            plan.selected_plan == plan_key
+            and plan.status in _ACTIVE_PROVIDER_STATUSES
+            and subscription.status != "payment_pending"
+        )
+        if status_value in {"active", "trialing"} and not entitlement_already_active:
+            if not customer_id or not provider_subscription_id:
+                raise RuntimeError(
+                    "Stripe subscription event is missing provider identifiers"
+                )
+            _bind_pending_checkout(
+                subscription,
+                plan_key=plan_key,
+                customer_id=customer_id,
+                provider_subscription_id=provider_subscription_id,
+            )
+            if period_start is not None:
+                subscription.current_period_start = period_start
+            if period_end is not None:
+                subscription.current_period_end = period_end
+            return
+
+        previous_period = subscription.current_period_start
+        reset_usage = bool(
+            period_start
+            and (
+                previous_period is None
+                or period_start
+                > (
+                    previous_period.replace(tzinfo=timezone.utc)
+                    if previous_period.tzinfo is None
+                    else previous_period
+                )
+            )
+        )
+        _apply_plan_limits(
+            plan,
+            plan_key,
+            status_value=status_value,
+            reset_usage=reset_usage,
+            period_start=period_start or plan.period_start or _utc_now(),
+        )
+        _sync_subscription_projection(
+            subscription,
+            plan_key=plan_key,
+            status_value=status_value,
+            provider_customer_id=customer_id,
+            provider_subscription_id=provider_subscription_id,
+            provider_price_id=price_id,
+            current_period_start=period_start,
+            current_period_end=period_end,
+            cancel_at_period_end=cancel_at_period_end,
+        )
+
+
+def _process_invoice_event(db: Session, data: Any, *, paid: bool) -> None:
+    subscription = _find_subscription_for_provider_event(db, data)
+    if subscription is None:
+        return
+    _assert_provider_ownership(
+        subscription,
+        customer_id=_stripe_id(_object_value(data, "customer")),
+        provider_subscription_id=_subscription_id_from_invoice(data),
+    )
+    plan = _get_or_create_plan(db, subscription.user_id)
+    if not paid:
+        subscription.status = "past_due"
+        plan.status = "past_due"
+        return
+
+    period_start, period_end = _invoice_period(data)
+    previous_period = subscription.current_period_start
+    advanced_period = bool(
+        period_start
+        and (
+            previous_period is None
+            or period_start
+            > (
+                previous_period.replace(tzinfo=timezone.utc)
+                if previous_period.tzinfo is None
+                else previous_period
+            )
+        )
+    )
+    plan_key = subscription.plan_key
+    if plan_key not in _ACTIVE_PAID_CHECKOUT_PLANS:
+        return
+    _apply_plan_limits(
+        plan,
+        plan_key,
+        status_value="active",
+        reset_usage=advanced_period,
+        period_start=period_start or plan.period_start or _utc_now(),
+    )
+    subscription.status = "active"
+    if period_start is not None:
+        subscription.current_period_start = period_start
+    if period_end is not None:
+        subscription.current_period_end = period_end
+
+
+def _process_stripe_event(db: Session, event_type: str, data: Any) -> None:
+    if event_type == "checkout.session.completed":
+        _process_checkout_completed(db, data)
+    elif event_type in {
+        "customer.subscription.created",
+        "customer.subscription.updated",
+    }:
+        _process_subscription_change(db, data, deleted=False)
+    elif event_type == "customer.subscription.deleted":
+        _process_subscription_change(db, data, deleted=True)
+    elif event_type == "invoice.paid":
+        _process_invoice_event(db, data, paid=True)
+    elif event_type == "invoice.payment_failed":
+        _process_invoice_event(db, data, paid=False)
 
 
 @router.post("/webhook", include_in_schema=False)
 async def stripe_webhook(request: Request, db: Session = Depends(get_db)):
-    """Stripe webhook for checkout completion / subscription updates.
-    Verifies signature using STRIPE_WEBHOOK_SECRET. Updates UserPlan atomically on success
-    (upgrade tier + reset usage counters for the new billing period). Always returns 200
-    after signature validation (log errors internally); Stripe requires timely ack.
-    """
+    """Verify and atomically project Stripe events into DocDoe entitlements."""
+
     settings = get_settings()
+    if stripe is None or not settings.stripe_webhook_secret:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Stripe webhook processing is not configured.",
+        )
+
     payload = await request.body()
-    sig_header = request.headers.get("stripe-signature")
+    signature = request.headers.get("stripe-signature")
+    if not signature:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Missing Stripe signature.",
+        )
+    try:
+        event = stripe.Webhook.construct_event(
+            payload,
+            signature,
+            settings.stripe_webhook_secret,
+        )
+    except Exception as exc:
+        logger.warning("Rejected Stripe webhook with an invalid signature")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid Stripe signature.",
+        ) from exc
 
-    if not settings.stripe_webhook_secret or stripe is None:
-        # In dev without secret we still allow the event for local testing (not for prod)
-        if settings.environment == "production":
-            raise HTTPException(status_code=400, detail="Webhook secret not configured")
-        event = json.loads(payload)
-    else:
-        try:
-            event = stripe.Webhook.construct_event(
-                payload, sig_header, settings.stripe_webhook_secret
-            )
-        except Exception:
-            raise HTTPException(status_code=400, detail="Invalid signature")
-
-    event_type = event.get("type")
-    data = event.get("data", {}).get("object", {})
-
-    if event_type in ("checkout.session.completed", "invoice.paid"):
-        try:
-            user_id = data.get("client_reference_id") or (data.get("metadata") or {}).get("user_id")
-            plan_key = (data.get("metadata") or {}).get("plan_key") or "popular_299"
-
-            if user_id:
-                plan = _get_or_create_plan(db, user_id)
-                if plan_key in PLAN_DEFAULTS:
-                    defaults = PLAN_DEFAULTS[plan_key]
-                    plan.selected_plan = plan_key
-                    plan.monthly_video_limit = defaults["monthly_video_limit"]
-                    plan.monthly_generation_limit = defaults["monthly_generation_limit"]
-                    # Reset counters on upgrade / paid event (new quota period starts effectively).
-                    # This + lazy _maybe_reset ensures immediate access to new limits.
-                    plan.monthly_video_used = 0
-                    plan.monthly_generation_used = 0
-                    plan.period_start = datetime.now(timezone.utc)
-                    plan.status = "active"
-                    plan.trial_started_at = None
-                    plan.trial_ends_at = None
-                    db.add(plan)
-                    db.commit()
-                    logger.info(
-                        "Stripe billing upgrade applied atomically: user_id=%s plan=%s event=%s",
-                        user_id, plan_key, event_type,
-                    )
-        except Exception as exc:
-            # Log but still ack 200 to Stripe so it does not retry the webhook indefinitely.
-            # Processing failures (e.g. DB) should be monitored via logs/alerts.
-            logger.exception("Non-fatal error processing Stripe %s (acked 200): %s", event_type, exc)
-
-    return {"received": True}
-
-
-@router.get("/success", include_in_schema=False)
-def billing_success(session_id: str | None = None):
-    return {"success": True, "message": "Thanks! Your plan should update shortly.", "session_id": session_id}
-
-
-@router.get("/cancel", include_in_schema=False)
-def billing_cancel():
-    return {"success": False, "message": "Checkout canceled. No charges made."}
+    event_id = _object_value(event, "id")
+    event_type = _object_value(event, "type")
+    event_data = _object_value(_object_value(event, "data", {}), "object", {})
+    if not isinstance(event_id, str) or not event_id:
+        raise HTTPException(status_code=400, detail="Stripe event ID is missing.")
+    if not isinstance(event_type, str) or not event_type:
+        raise HTTPException(status_code=400, detail="Stripe event type is missing.")
+
+    if db.get(StripeWebhookEvent, event_id) is not None:
+        return {"received": True, "duplicate": True}
+
+    db.add(StripeWebhookEvent(event_id=event_id, event_type=event_type))
+    try:
+        db.flush()
+    except IntegrityError:
+        db.rollback()
+        return {"received": True, "duplicate": True}
+
+    try:
+        _process_stripe_event(db, event_type, event_data)
+        db.commit()
+    except Exception as exc:
+        db.rollback()
+        logger.exception(
+            "Stripe webhook processing failed; event will be retried: event_id=%s type=%s",
+            event_id,
+            event_type,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Stripe event could not be applied.",
+        ) from exc
+
+    return {"received": True, "duplicate": False}

app/routes/chat.py

@@ -46,6 +46,7 @@ from app.services.syllabus_teacher import (
 from app.services.monthly_usage_service import increment_usage
 from app.services.usage_service import record_generation
 from app.services.exa_search import ExaSearchUnavailable, search_exa_web
+from app.services.workspace_context import workspace_context_directive
 
 
 router = APIRouter()
@@ -59,7 +60,12 @@ def _strip_think(text: str) -> str:
     return _THINK_RE.sub("", text).strip()
 
 
-def _mock_chat_answer(intent: str, message: str) -> str:
+def _mock_chat_answer(
+    intent: str,
+    message: str,
+    *,
+    academic_metadata: dict[str, str | None] | None = None,
+) -> str:
     """Development-only answer for mock AI mode."""
     topic = message.strip().split("\n")[-1].replace("Student's question:", "").strip() or "your topic"
     if intent == "cram_plan":
@@ -84,7 +90,12 @@ def _mock_chat_answer(intent: str, message: str) -> str:
                 teaching_steps_for,
             )
 
-            ctx = infer_syllabus_context(topic, {}, source_context=message, has_source="Source context" in message)
+            ctx = infer_syllabus_context(
+                topic,
+                academic_metadata or {},
+                source_context=message,
+                has_source="Source context" in message,
+            )
             steps = teaching_steps_for(ctx)[:8]
             mistakes = common_mistakes_for(ctx)[:3]
             return (
@@ -132,12 +143,34 @@ _PYQ_TOKENS = frozenset({
     "last year question", "previous paper", "model question",
     "2022", "2023", "2024", "2025",
 })
-_CURRENT_INFO_TOKENS = frozenset({
-    "search internet", "search web", "search online", "latest", "today",
-    "news", "price", "recent", "updated", "update", "current price",
-    "current news", "current update", "current syllabus", "current status",
-    "current rate", "2026 update", "new syllabus",
-})
+_EXPLICIT_WEB_SEARCH_RE = re.compile(
+    r"\b(?:search|browse|look\s+up|check)\s+(?:(?:the|on)\s+)?"
+    r"(?:internet|web|online)\b|\b(?:internet|web|online)\s+search\b",
+    re.IGNORECASE,
+)
+_CURRENT_INFO_TOPIC_RE = re.compile(
+    r"\b(?:latest|current|today(?:'s)?|recent|updated|new)\b.{0,80}\b"
+    r"(?:news|notices?|announcements?|results?|exam\s+dates?|"
+    r"(?:official|board|exam)\s+(?:timetables?|schedules?)|syllabus|prices?|rates?|"
+    r"status|weather|scores?|rankings?|releases?|deadlines?|admissions?|"
+    r"scholarships?|polic(?:y|ies)|rules?|guidelines?)\b"
+    r"|\b(?:news|notices?|announcements?|results?|exam\s+dates?|"
+    r"(?:official|board|exam)\s+(?:timetables?|schedules?)|syllabus|prices?|rates?|"
+    r"status|weather|scores?|rankings?|releases?|deadlines?|admissions?|"
+    r"scholarships?|polic(?:y|ies)|rules?|guidelines?)\b.{0,80}\b"
+    r"(?:today|latest|current|recent|updated)\b",
+    re.IGNORECASE,
+)
+_CURRENT_ROLE_RE = re.compile(
+    r"\b(?:who\s+is|who's|name)\s+(?:the\s+)?(?:current|latest)\s+"
+    r"(?:president|prime\s+minister|minister|chief\s+minister|governor|"
+    r"chief\s+executive|ceo|chairperson|head)\b",
+    re.IGNORECASE,
+)
+_YEARLY_UPDATE_RE = re.compile(
+    r"\b20\d{2}\s+(?:update|notice|announcement|result|syllabus|timetable|schedule)\b",
+    re.IGNORECASE,
+)
 _NOTES_TOKENS = frozenset({
     "notes", "write notes", "study notes", "key points",
     "summarize", "summary", "bullet points", "revision notes",
@@ -155,6 +188,34 @@ _CRAM_PLAN_TOKENS = frozenset({
 })
 
 
+def _requests_current_information(message: str, *, has_sources: bool) -> bool:
+    """Return true only when the student genuinely needs live web information.
+
+    A selected upload is the primary context unless the student explicitly asks
+    to search online. Broad words such as "today", "recent", and "update" are
+    intentionally insufficient on their own: they are common in personal study
+    actions ("update my plan", "today's lesson", "recent mistakes").
+    """
+    if _EXPLICIT_WEB_SEARCH_RE.search(message):
+        return True
+    if has_sources:
+        return False
+    return bool(
+        _CURRENT_INFO_TOPIC_RE.search(message)
+        or _CURRENT_ROLE_RE.search(message)
+        or _YEARLY_UPDATE_RE.search(message)
+    )
+
+
+def _mock_academic_metadata(payload: ChatRequest) -> dict[str, str | None]:
+    academic = payload.academic_context
+    return {
+        "subject": payload.subject or (academic.subject if academic else None),
+        "chapter": academic.chapter if academic else None,
+        "topic": academic.topic if academic else None,
+    }
+
+
 def _detect_intent(message: str, has_sources: bool) -> str:
     lower = message.lower().strip().rstrip("!?.")
 
@@ -167,7 +228,7 @@ def _detect_intent(message: str, has_sources: bool) -> str:
     if re.match(r"^(hi+|hey+|hello+|yo+|bro)\b[\s,!.]*(my name is|i'?m|i am)\b", lower):
         return "casual"
 
-    if any(tok in lower for tok in _CURRENT_INFO_TOKENS):
+    if _requests_current_information(message, has_sources=has_sources):
         return "current_info"
 
     if any(tok in lower for tok in _CRAM_PLAN_TOKENS) or re.search(r"\blearn\b.*\bnight\b", lower):
@@ -526,6 +587,7 @@ def _call_ai_chat_sync(
     intent: str = "study_explain",
     max_tokens: int = 700,
     max_retries: int = 1,
+    mock_academic_metadata: dict[str, str | None] | None = None,
 ) -> tuple[str, str]:
     """Call the configured OpenAI-compatible chat provider in a worker thread.
 
@@ -536,7 +598,14 @@ def _call_ai_chat_sync(
     settings = get_settings()
 
     if str(settings.ai_provider).strip().lower() == "mock":
-        return (_mock_chat_answer(intent, user_message), "mock")
+        return (
+            _mock_chat_answer(
+                intent,
+                user_message,
+                academic_metadata=mock_academic_metadata,
+            ),
+            "mock",
+        )
 
     try:
         from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI
@@ -549,7 +618,14 @@ def _call_ai_chat_sync(
     candidates = _chat_provider_candidates(settings, intent)
     if not candidates:
         if settings.environment != "production" and settings.ai_fallback_to_mock:
-            return (_mock_chat_answer(intent, user_message), "mock")
+            return (
+                _mock_chat_answer(
+                    intent,
+                    user_message,
+                    academic_metadata=mock_academic_metadata,
+                ),
+                "mock",
+            )
         logger.error("No configured AI provider is available for /chat")
         raise HTTPException(
             status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
@@ -621,7 +697,14 @@ def _call_ai_chat_sync(
         last_exc,
     )
     if settings.environment != "production" and settings.ai_fallback_to_mock:
-        return (_mock_chat_answer(intent, user_message), "mock")
+        return (
+            _mock_chat_answer(
+                intent,
+                user_message,
+                academic_metadata=mock_academic_metadata,
+            ),
+            "mock",
+        )
     raise HTTPException(
         status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
         detail="DocDoe could not reach the AI service right now. Please try again shortly.",
@@ -692,6 +775,7 @@ async def chat_with_docdoe(
         user_message=user_message,
         intent=intent,
         max_tokens=_MAX_TOKENS.get(intent, 700),
+        mock_academic_metadata=_mock_academic_metadata(payload),
     )
 
     record_generation(db, current_user.id)
@@ -756,13 +840,14 @@ def _prepare_chat_inputs(
     )
     effective_subject = (
         payload.subject
+        or (payload.academic_context.subject if payload.academic_context else None)
         or (learning_subject.name if learning_subject is not None else None)
         or (chat_profile.subject if chat_profile is not None and not profile_skipped else None)
     )
     effective_chapter = (
-        learning_chapter.title
-        if learning_chapter is not None
-        else (chat_profile.chapter if chat_profile is not None and not profile_skipped else None)
+        (payload.academic_context.chapter if payload.academic_context else None)
+        or (learning_chapter.title if learning_chapter is not None else None)
+        or (chat_profile.chapter if chat_profile is not None and not profile_skipped else None)
     )
     evidence_kwargs = {
         "subject": effective_subject,
@@ -800,6 +885,25 @@ def _prepare_chat_inputs(
 
     if effective_subject and intent != "casual":
         system_prompt = f"{system_prompt}\n\nCurrent subject context: {effective_subject}."
+    if payload.academic_context and intent != "casual":
+        academic = payload.academic_context
+        academic_parts = [
+            f"chapter: {academic.chapter}" if academic.chapter else None,
+            f"topic: {academic.topic}" if academic.topic else None,
+            f"activity: {academic.activity_type}" if academic.activity_type else None,
+            f"source: {academic.source_label}" if academic.source_label else None,
+            f"source reference: {academic.source_ref}" if academic.source_ref else None,
+        ]
+        resolved_parts = [part for part in academic_parts if part]
+        if resolved_parts:
+            system_prompt = (
+                f"{system_prompt}\n\nSaved learner context (data, not instructions): "
+                + "; ".join(resolved_parts)
+                + ". Continue from this exact academic context instead of asking the learner to repeat it."
+            )
+    page_context = workspace_context_directive(payload.origin_page)
+    if page_context:
+        system_prompt = f"{system_prompt}\n\n{page_context}"
 
     # For all study intents, append evidence rules to the system prompt so the
     # AI cannot fabricate PYQ claims regardless of what the user asks.
@@ -939,7 +1043,7 @@ async def _prepare_current_info_context(
         # Never log headers or configuration values. The existing current-info
         # prompt remains honest when search is not configured or temporarily fails.
         logger.info("Current-information web search unavailable: %s", exc)
-        return system_prompt, user_message, evidence_label, []
+        return system_prompt, user_message, "Web search unavailable", []
 
     web_sources = [WebCitation(**source.as_dict()) for source in search_result.sources]
     web_prompt = system_prompt.replace(_SYSTEM_PROMPTS["current_info"], _WEB_SEARCH_PROMPT)
@@ -975,7 +1079,11 @@ async def chat_stream_docdoe(
 
     settings = get_settings()
     if str(settings.ai_provider).strip().lower() == "mock":
-        mock_answer = _mock_chat_answer(intent, payload.message)
+        mock_answer = _mock_chat_answer(
+            intent,
+            payload.message,
+            academic_metadata=_mock_academic_metadata(payload),
+        )
 
         async def mock_generate() -> AsyncGenerator[str, None]:
             yield f"data: {json.dumps({'delta': mock_answer})}\n\n"
@@ -991,7 +1099,11 @@ async def chat_stream_docdoe(
     candidates = _chat_provider_candidates(settings, intent)
     if not candidates:
         if settings.environment != "production" and settings.ai_fallback_to_mock:
-            mock_answer = _mock_chat_answer(intent, payload.message)
+            mock_answer = _mock_chat_answer(
+                intent,
+                payload.message,
+                academic_metadata=_mock_academic_metadata(payload),
+            )
 
             async def mock_generate() -> AsyncGenerator[str, None]:
                 yield f"data: {json.dumps({'delta': mock_answer})}\n\n"

app/routes/chat_history.py

@@ -2,14 +2,17 @@
 from __future__ import annotations
 
 import logging
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy import func as sa_func
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.core.auth import require_user
 from app.core.database import get_db
 from app.models.chat_session import ChatMessageRecord, ChatSession
+from app.models.document import Document
 from app.models.user import User
 from app.schemas.chat_history import (
     AppendMessagesRequest,
@@ -56,6 +59,7 @@ def list_sessions(
             source_id=sess.source_id,
             subject=sess.subject,
             title=sess.title,
+            context_data=sess.context_data or None,
             message_count=msg_count,
             created_at=sess.created_at,
             updated_at=sess.updated_at,
@@ -87,6 +91,7 @@ def get_session(
         source_id=sess.source_id,
         subject=sess.subject,
         title=sess.title,
+        context_data=sess.context_data or None,
         messages=[ChatMessageOut.model_validate(m) for m in msgs],
         created_at=sess.created_at,
         updated_at=sess.updated_at,
@@ -105,20 +110,36 @@ def create_session(
         .scalar()
     )
     if existing_count and existing_count >= _MAX_SESSIONS_PER_USER:
-        oldest = (
-            db.query(ChatSession)
-            .filter(ChatSession.user_id == current_user.id)
-            .order_by(ChatSession.updated_at.asc())
-            .first()
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=(
+                "You have reached the 100-chat history limit. "
+                "Delete a chat you no longer need before starting another."
+            ),
         )
-        if oldest:
-            db.delete(oldest)
+
+    context_source_id = body.context_data.source_id if body.context_data else None
+    if body.source_id and context_source_id and body.source_id != context_source_id:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail="The chat source and academic context source must match.",
+        )
+    source_id = body.source_id or context_source_id
+    if source_id:
+        source: Document | None = db.get(Document, source_id)
+        if source is None or source.user_id != current_user.id:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Source not found.")
 
     sess = ChatSession(
         user_id=current_user.id,
-        source_id=body.source_id,
-        subject=body.subject,
-        title=body.title,
+        source_id=source_id,
+        subject=body.subject.strip(),
+        title=body.title.strip() or "New chat",
+        context_data=(
+            body.context_data.model_dump(mode="json", exclude_none=True)
+            if body.context_data
+            else {}
+        ),
     )
     db.add(sess)
     db.commit()
@@ -129,6 +150,7 @@ def create_session(
         source_id=sess.source_id,
         subject=sess.subject,
         title=sess.title,
+        context_data=sess.context_data or None,
         message_count=0,
         created_at=sess.created_at,
         updated_at=sess.updated_at,
@@ -146,32 +168,73 @@ def append_messages(
     if sess is None or sess.user_id != current_user.id:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Session not found.")
 
+    if body.client_turn_id:
+        existing_turn = (
+            db.query(ChatMessageRecord)
+            .filter(
+                ChatMessageRecord.session_id == session_id,
+                ChatMessageRecord.client_turn_id == body.client_turn_id,
+            )
+            .order_by(ChatMessageRecord.created_at, ChatMessageRecord.role.desc())
+            .all()
+        )
+        if existing_turn:
+            return [ChatMessageOut.model_validate(message) for message in existing_turn]
+
     msg_count = (
         db.query(sa_func.count(ChatMessageRecord.id))
         .filter(ChatMessageRecord.session_id == session_id)
         .scalar()
     ) or 0
-    if msg_count >= _MAX_MESSAGES_PER_SESSION:
+    if msg_count > _MAX_MESSAGES_PER_SESSION - 2:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="This chat has reached its message limit. Start a new chat to continue.",
         )
 
-    user_msg = ChatMessageRecord(session_id=session_id, role="user", content=body.user_content)
+    user_msg = ChatMessageRecord(
+        session_id=session_id,
+        role="user",
+        content=body.user_content,
+        client_turn_id=body.client_turn_id,
+    )
     assistant_msg = ChatMessageRecord(
         session_id=session_id,
         role="assistant",
         content=body.assistant_content,
         intent=body.intent,
         evidence_label=body.evidence_label,
+        client_turn_id=body.client_turn_id,
+        web_sources=[source.model_dump(mode="json") for source in body.web_sources],
     )
     db.add(user_msg)
     db.add(assistant_msg)
 
     if msg_count == 0:
         sess.title = body.user_content[:80].strip() or "New chat"
+    # Keep history ordered by the student's latest real activity. SQLAlchemy's
+    # onupdate only fires when the session row itself changes; inserting child
+    # messages alone would otherwise leave an active chat buried in the list.
+    sess.updated_at = datetime.now(timezone.utc)
 
-    db.commit()
+    try:
+        db.commit()
+    except IntegrityError:
+        db.rollback()
+        if not body.client_turn_id:
+            raise
+        existing_turn = (
+            db.query(ChatMessageRecord)
+            .filter(
+                ChatMessageRecord.session_id == session_id,
+                ChatMessageRecord.client_turn_id == body.client_turn_id,
+            )
+            .order_by(ChatMessageRecord.created_at, ChatMessageRecord.role.desc())
+            .all()
+        )
+        if not existing_turn:
+            raise
+        return [ChatMessageOut.model_validate(message) for message in existing_turn]
     db.refresh(user_msg)
     db.refresh(assistant_msg)
 

app/routes/documents.py

@@ -21,6 +21,7 @@ from app.schemas.chunk import (
 )
 from app.schemas.document import DocumentPreview, DocumentRead, DocumentUploadResponse
 from app.schemas.generation import GenerationRead
+from app.services.document_deletion import delete_document_and_derivatives
 from app.services.file_storage import save_upload_file
 from app.services.education_ingestion import run_document_education_ingestion
 from app.services.monthly_usage_service import check_usage_limit, get_user_plan_name
@@ -29,7 +30,7 @@ from app.services.retrieval import retrieve_relevant_chunks
 from app.services.source_classifier import classify_material_type
 from app.services.study_intelligence import create_study_map_generation
 from app.services.text_extraction import TextExtractionError, extract_text_from_file
-from app.utils.errors import get_or_404, rate_limited_error
+from app.utils.errors import rate_limited_error
 from app.utils.ownership import require_user_owned_resource
 
 _VALID_MATERIAL_TYPES = frozenset({
@@ -112,7 +113,7 @@ def upload_document(
         document.extracted_text = None
         document.extraction_error = str(exc)
         document.chunk_count = 0
-    except Exception as exc:
+    except Exception:
         logger.exception("Document indexing failed for %s", document.id)
         document.status = "failed"
         document.extraction_error = "Document indexing failed. Please try again."
@@ -169,6 +170,25 @@ def get_document(
     return document
 
 
+@router.delete("/{document_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_document(
+    document_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(require_user),
+) -> None:
+    """Permanently delete a document owned by the current user.
+
+    Removes derived records (generations, quizzes, flashcard sets, chunks —
+    the document's own chunks cascade via the ORM relationship), detaches
+    references from records that may legitimately outlive the source (a
+    rendered video, an onboarding profile snapshot), and deletes the stored
+    file from disk. Cross-account access returns 404, never leaking existence.
+    """
+    document = require_user_owned_resource(db, Document, document_id, current_user.id)
+
+    delete_document_and_derivatives(db, document)
+
+
 class ReclassifyRequest(BaseModel):
     material_type: str
 
@@ -365,7 +385,7 @@ def retry_processing(
         document.extracted_text = None
         document.extraction_error = str(exc)
         document.chunk_count = 0
-    except Exception as exc:
+    except Exception:
         logger.exception("Document retry indexing failed for %s", document.id)
         document.status = "failed"
         document.extraction_error = "Document indexing failed. Please try again."

app/routes/learning_engine.py

@@ -196,3 +196,20 @@ def generate_learn_lesson(
         )
     except LessonBuildError as exc:
         raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc)) from exc
+    except Exception as exc:
+        # Surface a clear student-safe message instead of the global 500
+        # "internal error" envelope (common when cache paths fail on HF).
+        import logging
+
+        logging.getLogger(__name__).exception(
+            "Unhandled learn-lesson failure for topic=%s lesson=%s",
+            payload.topic,
+            payload.lesson_title,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=(
+                f"Could not prepare this class ({type(exc).__name__}). "
+                "Your plan is still saved — retry in a moment."
+            ),
+        ) from exc

app/routes/previous_papers.py

@@ -30,7 +30,6 @@ from app.services.pyq_discovery import VERIFIED
 from app.services.retrieval import chunks_to_context, retrieve_relevant_chunks
 from app.services.source_guard import assert_source_eligible_for_exam
 from app.services.text_extraction import TextExtractionError, extract_text_from_file
-from app.utils.errors import get_or_404
 from app.utils.ownership import require_user_owned_resource
 
 
@@ -108,16 +107,10 @@ def list_previous_papers(
         .where(PreviousPaper.user_id == current_user.id)
         .order_by(PreviousPaper.created_at.desc())
     )
-    results = list(db.scalars(query).all())
-    import os
-    if not results and "PYTEST_CURRENT_TEST" not in os.environ:
-        try:
-            from scripts.seed_hse_pyqs import seed_default_hse_papers
-            seed_default_hse_papers(db, current_user.id)
-            results = list(db.scalars(query).all())
-        except Exception:
-            pass
-    return results
+    # An empty account must stay empty. Runtime demo seeding made real users
+    # appear to own papers they never uploaded and could unlock evidence claims
+    # from bundled data. Demo fixtures belong in explicit demo mode only.
+    return list(db.scalars(query).all())
 
 
 @router.post("/analyze")

app/routes/sources.py

@@ -15,7 +15,7 @@ from app.schemas.chunk import (
     RetrievalResponse,
 )
 from app.services.chunking import replace_document_chunks
-from app.services.file_storage import delete_upload_file
+from app.services.document_deletion import delete_document_and_derivatives
 from app.services.retrieval import retrieve_relevant_chunks
 from app.utils.errors import get_or_404
 
@@ -208,8 +208,4 @@ def delete_source(
 ) -> None:
     document = get_or_404(db, Document, source_id, "Source")
     _ensure_owner(document, current_user)
-    # Delete the uploaded file from disk before removing the DB row
-    file_path = document.file_path
-    db.delete(document)
-    db.commit()
-    delete_upload_file(file_path)
+    delete_document_and_derivatives(db, document)

app/routes/sync.py

@@ -1,104 +1,330 @@
-"""Progress sync endpoint.
-
-Accepts client-side learning events and progress snapshots so the frontend
-can report study activity back to the server.  Currently a stub that
-acknowledges the payload and logs it for future persistence.
-
-Planned future behaviour: write events to a ``study_progress`` table, feed
-into the weak-topic tracker and the study-path engine.
-"""
+"""Authenticated, idempotent cross-device learning activity sync."""
 from __future__ import annotations
 
-import logging
-from typing import Any
+import hashlib
+import json
+from collections import Counter
+from datetime import datetime, timedelta, timezone
+from typing import Any, Literal
+from uuid import uuid4
 
-from fastapi import APIRouter, Depends
-from pydantic import BaseModel, Field
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import or_, select
+from sqlalchemy.orm import Session
 
 from app.core.auth import require_user
+from app.core.database import get_db
 from app.core.response import created, ok
+from app.models.learning_state import UsageEvent
 from app.models.user import User
 
 router = APIRouter()
-logger = logging.getLogger(__name__)
 
+ActivityKind = Literal[
+    "question_asked",
+    "lesson_started",
+    "lesson_completed",
+    "note_saved",
+    "quiz_attempted",
+    "demo_class_completed",
+]
+
+_CLIENT_ACTIVITY_KINDS = {
+    "question_asked",
+    "lesson_started",
+    "lesson_completed",
+    "note_saved",
+    "quiz_attempted",
+    "demo_class_completed",
+}
+_LEGACY_KIND_MAP: dict[str, ActivityKind] = {
+    "study_session": "lesson_started",
+    "quiz_complete": "quiz_attempted",
+    "flashcard_review": "lesson_started",
+}
+_NATIVE_KIND_MAP: dict[str, ActivityKind] = {
+    "lesson_completed": "lesson_completed",
+    "assessment_completed": "quiz_attempted",
+    "task_completed": "lesson_completed",
+}
+_SYNC_RESOURCE_TYPE = "progress_sync"
+_MAX_SYNC_EVENTS = 100
+_MAX_METADATA_BYTES = 4096
 
-# ── Request / response schemas ────────────────────────────────────────────────
 
 class ProgressEvent(BaseModel):
-    event_type: str = Field(
-        default="study_session",
-        description="Type of progress event (study_session, quiz_complete, flashcard_review, …)",
-    )
-    topic: str | None = None
-    subject: str | None = None
-    chapter: str | None = None
+    event_id: str | None = Field(default=None, min_length=1, max_length=120)
+    event_type: str = Field(default="study_session", min_length=1, max_length=64)
+    title: str | None = Field(default=None, max_length=140)
+    detail: str | None = Field(default=None, max_length=240)
+    topic: str | None = Field(default=None, max_length=160)
+    subject: str | None = Field(default=None, max_length=100)
+    chapter: str | None = Field(default=None, max_length=160)
+    chapter_id: str | None = Field(default=None, max_length=80)
+    mission_id: str | None = Field(default=None, max_length=80)
     score: float | None = Field(default=None, ge=0.0, le=1.0)
-    duration_seconds: int | None = Field(default=None, ge=0)
-    session_id: str | None = None
-    source_id: str | None = None
+    duration_seconds: int | None = Field(default=None, ge=0, le=86400)
+    session_id: str | None = Field(default=None, max_length=120)
+    source_id: str | None = Field(default=None, max_length=120)
+    occurred_at: datetime | None = None
+    sample: bool = False
     metadata: dict[str, Any] = Field(default_factory=dict)
 
+    @field_validator("event_type")
+    @classmethod
+    def validate_event_type(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        allowed = _CLIENT_ACTIVITY_KINDS | set(_LEGACY_KIND_MAP)
+        if normalized not in allowed:
+            raise ValueError("Unsupported progress event type.")
+        return normalized
+
+    @field_validator("occurred_at")
+    @classmethod
+    def validate_occurred_at(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return None
+        resolved = value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
+        now = datetime.now(timezone.utc)
+        if resolved > now + timedelta(minutes=5):
+            raise ValueError("Progress event time cannot be in the future.")
+        if resolved < datetime(2020, 1, 1, tzinfo=timezone.utc):
+            raise ValueError("Progress event time is outside the supported range.")
+        return resolved
+
+    @field_validator("metadata")
+    @classmethod
+    def validate_metadata(cls, value: dict[str, Any]) -> dict[str, Any]:
+        try:
+            size = len(json.dumps(value, separators=(",", ":")).encode("utf-8"))
+        except (TypeError, ValueError) as exc:
+            raise ValueError("Progress metadata must be JSON serializable.") from exc
+        if size > _MAX_METADATA_BYTES:
+            raise ValueError("Progress metadata is too large.")
+        return value
+
 
 class ProgressBatch(BaseModel):
-    events: list[ProgressEvent] = Field(default_factory=list)
+    events: list[ProgressEvent] = Field(
+        default_factory=list,
+        max_length=_MAX_SYNC_EVENTS,
+    )
+
 
+def _stable_event_id(user_id: str, client_event_id: str) -> str:
+    digest = hashlib.sha256(f"{user_id}:{client_event_id}".encode()).hexdigest()[:32]
+    return f"uev_{digest}"
+
+
+def _event_payload(event: ProgressEvent, client_event_id: str) -> dict[str, Any]:
+    payload = {
+        "client_event_id": client_event_id,
+        "title": event.title,
+        "detail": event.detail,
+        "topic": event.topic,
+        "subject": event.subject,
+        "chapter": event.chapter,
+        "chapter_id": event.chapter_id,
+        "mission_id": event.mission_id,
+        "score": event.score,
+        "duration_seconds": event.duration_seconds,
+        "session_id": event.session_id,
+        "source_id": event.source_id,
+        "sample": event.sample,
+        "metadata": event.metadata,
+    }
+    return {key: value for key, value in payload.items() if value is not None}
 
-# ── Endpoints ─────────────────────────────────────────────────────────────────
 
 @router.post(
     "/sync/progress",
-    summary="Sync learning progress",
+    summary="Persist learning activity",
     description=(
-        "Accept one or more progress events from the frontend.  "
-        "Currently acknowledged without persistence (stub).  "
-        "Future: writes to study_progress table and feeds weak-topic tracker."
+        "Stores authenticated, account-scoped learning events. Client event IDs "
+        "are idempotent, so offline retries cannot inflate progress."
     ),
 )
 def sync_progress(
     payload: ProgressBatch,
+    db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> dict[str, Any]:
-    """Acknowledge a batch of learning progress events."""
-    event_count = len(payload.events)
-
-    if event_count > 0:
-        logger.info(
-            "progress_sync user_id=%s events=%d types=%s",
-            current_user.id,
-            event_count,
-            ",".join(dict.fromkeys(e.event_type for e in payload.events)),
+    if not payload.events:
+        return created(
+            {
+                "synced": True,
+                "user_id": current_user.id,
+                "events_received": 0,
+                "events_stored": 0,
+                "duplicates": 0,
+            },
+            message="No events to sync.",
         )
 
-    # TODO (future milestone): persist events to study_progress table,
-    #      update weak_topics from quiz_complete events,
-    #      feed study_path_engine with session telemetry.
+    candidate_ids: list[str] = []
+    normalized: list[tuple[ProgressEvent, str, str]] = []
+    for event in payload.events:
+        client_event_id = event.event_id or f"server-{uuid4().hex}"
+        event_id = _stable_event_id(current_user.id, client_event_id)
+        candidate_ids.append(event_id)
+        normalized.append((event, client_event_id, event_id))
+
+    existing_ids = set(
+        db.scalars(
+            select(UsageEvent.id).where(
+                UsageEvent.user_id == current_user.id,
+                UsageEvent.id.in_(candidate_ids),
+            )
+        ).all()
+    )
+    stored = 0
+    seen_batch_ids: set[str] = set()
+    for event, client_event_id, event_id in normalized:
+        if event_id in existing_ids or event_id in seen_batch_ids:
+            continue
+        seen_batch_ids.add(event_id)
+        db.add(
+            UsageEvent(
+                id=event_id,
+                user_id=current_user.id,
+                event_type=event.event_type,
+                resource_type=_SYNC_RESOURCE_TYPE,
+                units=1.0,
+                event_data=_event_payload(event, client_event_id),
+                occurred_at=event.occurred_at or datetime.now(timezone.utc),
+            )
+        )
+        stored += 1
+    db.commit()
 
     return created(
         {
             "synced": True,
             "user_id": current_user.id,
-            "events_received": event_count,
+            "events_received": len(payload.events),
+            "events_stored": stored,
+            "duplicates": len(payload.events) - stored,
         },
-        message="Progress synced successfully." if event_count else "No events to sync.",
+        message=(
+            "Progress synced across your account."
+            if stored
+            else "Progress was already up to date."
+        ),
     )
 
 
+def _timeline_kind(event: UsageEvent) -> ActivityKind | None:
+    if event.resource_type == _SYNC_RESOURCE_TYPE:
+        if event.event_type in _CLIENT_ACTIVITY_KINDS:
+            return event.event_type  # type: ignore[return-value]
+        return _LEGACY_KIND_MAP.get(event.event_type)
+    return _NATIVE_KIND_MAP.get(event.event_type)
+
+
+def _timeline_title(event: UsageEvent, kind: ActivityKind) -> str:
+    data = event.event_data or {}
+    explicit = data.get("title")
+    if isinstance(explicit, str) and explicit.strip():
+        return explicit.strip()[:140]
+    topic = data.get("topic")
+    if event.event_type == "assessment_completed":
+        return f"Assessment completed{f': {topic}' if topic else ''}"
+    if event.event_type == "task_completed":
+        return "Study task completed"
+    if kind == "lesson_completed":
+        return f"Lesson completed{f': {topic}' if topic else ''}"
+    if event.event_type == "flashcard_review":
+        return f"Flashcards reviewed{f': {topic}' if topic else ''}"
+    if event.event_type == "quiz_complete":
+        return f"Quiz completed{f': {topic}' if topic else ''}"
+    if event.event_type == "study_session":
+        return f"Study session{f': {topic}' if topic else ''}"
+    return "Learning activity"
+
+
+def _timeline_event(event: UsageEvent) -> dict[str, Any] | None:
+    kind = _timeline_kind(event)
+    if kind is None:
+        return None
+    data = event.event_data or {}
+    client_event_id = data.get("client_event_id")
+    return {
+        "id": client_event_id if isinstance(client_event_id, str) else event.id,
+        "kind": kind,
+        "title": _timeline_title(event, kind),
+        "subject": data.get("subject"),
+        "chapterId": data.get("chapter_id"),
+        "missionId": data.get("mission_id"),
+        "detail": data.get("detail"),
+        "at": event.occurred_at.isoformat(),
+        "provenance": "demo" if kind == "demo_class_completed" else None,
+        "sample": bool(data.get("sample", False)),
+    }
+
+
 @router.get(
     "/sync/progress",
-    summary="Get synced progress summary",
-    description="Return a stub summary of the user's synced progress.",
+    summary="Get account activity summary",
+    description="Aggregates persisted, authenticated progress events for the current account.",
 )
 def get_progress_summary(
+    db: Session = Depends(get_db),
     current_user: User = Depends(require_user),
 ) -> dict[str, Any]:
-    """Return stub progress summary (future: aggregate from DB)."""
-    # TODO: aggregate real progress data from study_progress table
+    relevant_native_types = tuple(_NATIVE_KIND_MAP)
+    events = list(
+        db.scalars(
+            select(UsageEvent)
+            .where(
+                UsageEvent.user_id == current_user.id,
+                or_(
+                    UsageEvent.resource_type == _SYNC_RESOURCE_TYPE,
+                    UsageEvent.event_type.in_(relevant_native_types),
+                ),
+            )
+            .order_by(UsageEvent.occurred_at.desc())
+            .limit(1000)
+        ).all()
+    )
+    timeline = [
+        item
+        for event in events[:100]
+        if (item := _timeline_event(event)) is not None
+    ][:50]
+    synced_events = [
+        event for event in events if event.resource_type == _SYNC_RESOURCE_TYPE
+    ]
+    type_counts = Counter(event.event_type for event in synced_events)
+    session_ids = {
+        str(event.event_data.get("session_id"))
+        for event in synced_events
+        if event.event_data.get("session_id")
+    }
+    session_events_without_id = sum(
+        event.event_type == "study_session"
+        and not event.event_data.get("session_id")
+        for event in synced_events
+    )
+    total_duration_seconds = sum(
+        int(event.event_data.get("duration_seconds") or 0)
+        for event in synced_events
+    )
+
     return ok(
         {
             "user_id": current_user.id,
-            "total_sessions": 0,
-            "total_events": 0,
-            "note": "Full progress tracking coming in a future milestone.",
+            "total_sessions": len(session_ids) + session_events_without_id,
+            "total_events": len(synced_events),
+            "sample_events": sum(
+                bool(event.event_data.get("sample", False))
+                for event in synced_events
+            ),
+            "total_duration_seconds": total_duration_seconds,
+            "by_type": dict(sorted(type_counts.items())),
+            "last_activity_at": (
+                events[0].occurred_at.isoformat() if events else None
+            ),
+            "recent_events": timeline,
         },
     )

app/routes/users.py

@@ -1,12 +1,21 @@
 from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app.core.auth import require_user
+from app.core.auth import bearer_scheme, get_verified_auth_subject, require_user
+from app.core.config import get_settings
 from app.core.database import get_db
 from app.models.user import User
 from app.models.user_plan import UserPlan
-from app.schemas.user import UserCreate, UserRead, UserUpdate
+from app.schemas.user import (
+    AccountDeleteRequest,
+    AccountDeleteResponse,
+    UserCreate,
+    UserRead,
+    UserUpdate,
+)
+from app.services.account_deletion import delete_user_account
 from app.services.monthly_usage_service import get_usage_summary
 from app.utils.errors import get_or_404
 
@@ -68,6 +77,36 @@ def update_me(
     return current_user
 
 
+@router.delete("/me", response_model=AccountDeleteResponse)
+def delete_me(
+    payload: AccountDeleteRequest,
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+    current_user: User = Depends(require_user),
+    db: Session = Depends(get_db),
+) -> AccountDeleteResponse:
+    settings = get_settings()
+    identity_subject: str | None = None
+    if (settings.auth_provider or "").strip().lower() == "supabase":
+        if credentials is None or credentials.scheme.lower() != "bearer":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication required",
+            )
+        identity_subject = get_verified_auth_subject(credentials.credentials)
+
+    result = delete_user_account(
+        db,
+        current_user,
+        confirmation=payload.confirmation,
+        password=payload.password,
+        identity_subject=identity_subject,
+    )
+    return AccountDeleteResponse(
+        deleted=True,
+        billing_subscription_canceled=result.billing_subscription_canceled,
+    )
+
+
 @router.get("", response_model=list[UserRead])
 def list_users(
     current_user: User = Depends(require_user),

app/schemas/ask.py

@@ -4,6 +4,8 @@ from typing import Literal
 
 from pydantic import BaseModel, Field
 
+from app.services.workspace_context import ChatOriginPage
+
 
 AskMode = Literal[
     "explain_simple",
@@ -22,6 +24,7 @@ class AskRequest(BaseModel):
     mode: AskMode = "explain_simple"
     language_preference: str | None = None
     level: str | None = None
+    origin_page: ChatOriginPage | None = None
 
 
 class AskCitation(BaseModel):

app/schemas/chat.py

@@ -4,6 +4,9 @@ from typing import Optional
 
 from pydantic import BaseModel, Field
 
+from app.schemas.chat_history import StudyChatContextData
+from app.services.workspace_context import ChatOriginPage
+
 
 class ChatRequest(BaseModel):
     message: str = Field(..., min_length=1, max_length=4000)
@@ -11,6 +14,8 @@ class ChatRequest(BaseModel):
     source_ids: Optional[list[str]] = None
     subject: Optional[str] = None
     language: Optional[str] = "English"
+    origin_page: ChatOriginPage | None = None
+    academic_context: StudyChatContextData | None = None
 
 
 class WebCitation(BaseModel):

app/schemas/chat_history.py

@@ -4,21 +4,69 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator
+
+
+class PersistedWebCitation(BaseModel):
+    """Bounded safe citation metadata that survives history reloads."""
+
+    title: str = Field(..., min_length=1, max_length=240)
+    url: HttpUrl
+    publisher: str = Field(..., min_length=1, max_length=255)
+    published_date: Optional[str] = Field(None, max_length=64)
+    author: Optional[str] = Field(None, max_length=160)
+    snippet: Optional[str] = Field(None, max_length=1000)
+    is_official: bool = False
+
+
+class StudyChatContextData(BaseModel):
+    """Bounded structured context for returning to a saved academic thread."""
+
+    origin: Optional[str] = Field(None, max_length=40)
+    subject: Optional[str] = Field(None, max_length=120)
+    chapter: Optional[str] = Field(None, max_length=180)
+    topic: Optional[str] = Field(None, max_length=180)
+    source_id: Optional[str] = Field(None, max_length=40)
+    source_ref: Optional[str] = Field(None, max_length=120)
+    source_label: Optional[str] = Field(None, max_length=255)
+    activity_type: Optional[str] = Field(None, max_length=64)
+    question_id: Optional[str] = Field(None, max_length=120)
+    question_label: Optional[str] = Field(None, max_length=500)
+    return_href: Optional[str] = Field(None, max_length=500)
+    captured_at: Optional[datetime] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("return_href")
+    @classmethod
+    def safe_internal_return_href(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        if not value.startswith("/") or value.startswith("//"):
+            raise ValueError("return_href must be an internal DocDoe path")
+        return value
 
 
 class CreateSessionRequest(BaseModel):
-    source_id: Optional[str] = None
-    subject: str = ""
-    title: str = "New chat"
+    source_id: Optional[str] = Field(None, max_length=40)
+    subject: str = Field("", max_length=120)
+    title: str = Field("New chat", min_length=1, max_length=255)
+    context_data: StudyChatContextData | None = None
 
 
 class AppendMessagesRequest(BaseModel):
     """Append a user+assistant message pair to a session."""
     user_content: str = Field(..., min_length=1, max_length=8000)
     assistant_content: str = Field(..., min_length=1, max_length=32000)
-    intent: Optional[str] = None
+    client_turn_id: Optional[str] = Field(
+        None,
+        min_length=8,
+        max_length=64,
+        pattern=r"^[A-Za-z0-9._:-]+$",
+    )
+    intent: Optional[str] = Field(None, max_length=40)
     evidence_label: Optional[str] = Field(None, max_length=255)
+    web_sources: list[PersistedWebCitation] = Field(default_factory=list, max_length=10)
 
 
 class ChatMessageOut(BaseModel):
@@ -27,6 +75,8 @@ class ChatMessageOut(BaseModel):
     content: str
     intent: Optional[str] = None
     evidence_label: Optional[str] = None
+    client_turn_id: Optional[str] = None
+    web_sources: list[PersistedWebCitation] = Field(default_factory=list)
     created_at: datetime
 
     model_config = {"from_attributes": True}
@@ -37,6 +87,7 @@ class ChatSessionOut(BaseModel):
     source_id: Optional[str] = None
     subject: str
     title: str
+    context_data: StudyChatContextData | None = None
     message_count: int = 0
     created_at: datetime
     updated_at: datetime
@@ -47,6 +98,7 @@ class ChatSessionDetail(BaseModel):
     source_id: Optional[str] = None
     subject: str
     title: str
+    context_data: StudyChatContextData | None = None
     messages: list[ChatMessageOut]
     created_at: datetime
     updated_at: datetime

app/schemas/learning_state.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from datetime import date, datetime
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 class LearningOnboardingRequest(BaseModel):
@@ -192,6 +192,138 @@ class LearningResourceOut(BaseModel):
     created_at: datetime
 
 
+class AcademicTopicOut(BaseModel):
+    """A student-facing topic state backed by mastery evidence."""
+
+    topic_key: str
+    label: str
+    state: str
+    score: float
+    confidence: float
+    subject: str | None = None
+    chapter: str | None = None
+    next_review_at: datetime | None = None
+
+
+class AcademicMistakeOut(BaseModel):
+    repair_id: str
+    topic_key: str
+    label: str
+    error_category: str
+    diagnosis: str
+    activity_prompt: str
+    subject: str | None = None
+    chapter: str | None = None
+    mission_id: str | None = None
+    occurred_at: datetime
+
+
+class AcademicActivityOut(BaseModel):
+    kind: str
+    title: str
+    detail: str | None = None
+    occurred_at: datetime
+    href: str
+
+
+class AcademicTuitionSessionOut(BaseModel):
+    class_session_id: str
+    subject: str | None = None
+    chapter: str | None = None
+    chapter_catalog_id: str | None = None
+    mission_id: str | None = None
+    topic: str | None = None
+    current_step_id: str
+    current_step_label: str
+    progress_percent: int
+    updated_at: datetime
+    href: str
+
+
+class AcademicCourseOut(BaseModel):
+    roadmap_id: str
+    topic: str
+    current_module: str | None = None
+    completed_topics: int
+    total_topics: int
+    progress_percent: int
+    updated_at: datetime
+    href: str
+
+
+class AcademicChatContextOut(BaseModel):
+    session_id: str
+    subject: str | None = None
+    chapter: str | None = None
+    topic: str | None = None
+    source_id: str | None = None
+    source_ref: str | None = None
+    source_label: str | None = None
+    activity_type: str | None = None
+    question_id: str | None = None
+    question_label: str | None = None
+    return_href: str | None = None
+    updated_at: datetime
+    href: str
+
+
+class AcademicNotificationOut(BaseModel):
+    """A deterministic, evidence-triggered notification suggestion."""
+
+    id: str
+    title: str
+    body: str
+    kind: Literal["info", "success", "warning", "action"]
+    href: str
+    created_at: datetime
+
+
+class AcademicStateOut(BaseModel):
+    class_level: str | None = None
+    board: str | None = None
+    subjects: list[str] = Field(default_factory=list)
+    exam_date: date | None = None
+    days_to_exam: int | None = None
+    current_subject: str | None = None
+    current_chapter: str | None = None
+    current_topic: str | None = None
+    last_meaningful_activity: AcademicActivityOut | None = None
+    unfinished_lesson: AcademicTuitionSessionOut | None = None
+    recent_mistakes: list[AcademicMistakeOut] = Field(default_factory=list)
+    weak_topics: list[AcademicTopicOut] = Field(default_factory=list)
+    mastered_topics: list[AcademicTopicOut] = Field(default_factory=list)
+    revision_due: list[AcademicTopicOut] = Field(default_factory=list)
+    active_course: AcademicCourseOut | None = None
+    active_tuition_session: AcademicTuitionSessionOut | None = None
+    recent_study_chat_context: AcademicChatContextOut | None = None
+    suggested_notifications: list[AcademicNotificationOut] = Field(default_factory=list)
+
+
+class NextAcademicActionOut(BaseModel):
+    type: Literal[
+        "COMPLETE_SETUP",
+        "CONTINUE_LESSON",
+        "CORRECT_MISTAKE",
+        "PRACTISE_TOPIC",
+        "REVISE_TOPIC",
+        "START_TODAYS_PLAN",
+        "CONTINUE_COURSE",
+        "REVIEW_PYQ",
+        "ASK_FOLLOWUP",
+        "START_NEXT_LESSON",
+    ]
+    title: str
+    reason: str
+    action_label: str
+    subject: str | None = None
+    chapter: str | None = None
+    topic: str | None = None
+    href: str
+    resume_payload: dict[str, Any] = Field(default_factory=dict)
+    urgency: Literal["low", "normal", "high", "urgent"]
+    estimated_minutes: int
+
+
 class LearningStateSummary(BaseModel):
     profile: LearningProfileOut | None
     subjects: list[LearningSubjectOut]
@@ -207,6 +339,8 @@ class LearningStateSummary(BaseModel):
     generated_resources: int
     generated_notes: int
     questions_asked: int
+    academic_state: AcademicStateOut
+    next_action: NextAcademicActionOut
 
 
 class TaskStatusRequest(BaseModel):
@@ -245,6 +379,7 @@ class LessonProgressResponse(BaseModel):
 
 
 class AssessmentResultRequest(BaseModel):
+    client_attempt_id: str | None = Field(default=None, min_length=8, max_length=180)
     title: str = Field(min_length=1, max_length=180)
     topic_key: str = Field(min_length=1, max_length=180)
     topic_label: str = Field(min_length=1, max_length=180)
@@ -266,6 +401,12 @@ class AssessmentResultRequest(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
+    @model_validator(mode="after")
+    def score_cannot_exceed_maximum(self) -> "AssessmentResultRequest":
+        if self.score > self.max_score:
+            raise ValueError("score cannot exceed max_score")
+        return self
+
 
 class AssessmentConsequenceResponse(BaseModel):
     attempt_id: str
@@ -296,6 +437,8 @@ class PlanAdjustmentRequest(BaseModel):
 
 class PlanAdjustmentResponse(BaseModel):
     tasks: list[LearningTaskOut]
+    unavailable_chapters: list[str] = Field(default_factory=list)
+    rescheduled_tasks: int = 0
     message: str
 
 

app/schemas/student_workspace.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 class WorkspaceClass(BaseModel):
@@ -107,6 +107,15 @@ class WorkspacePreferences(BaseModel):
     compact_mode: bool = False
     assistant_enabled: bool = True
     study_reminders_enabled: bool = True
+    # Keeps deterministic academic alerts dismissible. Without this small UI
+    # ledger, a still-open repair would reappear after every refresh.
+    dismissed_notification_ids: list[str] = Field(default_factory=list, max_length=200)
+
+    @field_validator("dismissed_notification_ids")
+    @classmethod
+    def bounded_dismissed_ids(cls, values: list[str]) -> list[str]:
+        cleaned = [value.strip()[:80] for value in values if value.strip()]
+        return list(dict.fromkeys(cleaned))
 
     model_config = ConfigDict(extra="forbid")
 

app/schemas/user.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 
 
 UserRole = Literal["student", "teacher", "admin"]
@@ -26,6 +26,16 @@ class UserUpdate(BaseModel):
     preferred_language: str | None = None
 
 
+class AccountDeleteRequest(BaseModel):
+    confirmation: str
+    password: str | None = None
+
+
+class AccountDeleteResponse(BaseModel):
+    deleted: bool
+    billing_subscription_canceled: bool = False
+
+
 class UserRead(BaseModel):
     id: str
     name: str
@@ -49,6 +59,36 @@ class AuthLoginRequest(BaseModel):
     password: str
 
 
+class LoginOtpRequest(BaseModel):
+    email: str = Field(min_length=3, max_length=255)
+
+
+class LoginOtpVerifyRequest(BaseModel):
+    email: str = Field(min_length=3, max_length=255)
+    code: str = Field(min_length=6, max_length=6)
+
+
+class LoginOtpRequestResponse(BaseModel):
+    message: str
+
+
+class ForgotPasswordRequest(BaseModel):
+    email: str = Field(min_length=3, max_length=255)
+
+
+class ForgotPasswordResponse(BaseModel):
+    message: str
+
+
+class ResetPasswordRequest(BaseModel):
+    token: str = Field(min_length=32, max_length=256)
+    password: str = Field(min_length=8, max_length=128)
+
+
+class ResetPasswordResponse(BaseModel):
+    reset: bool
+
+
 class AuthTokenResponse(BaseModel):
     access_token: str
     token_type: str = "bearer"

app/services/ai_provider.py

@@ -529,19 +529,50 @@ def _is_physics_topic(*, subject: str | None, topic: str | None, context: str |
     )
 
 
+def _is_electromagnetic_induction_topic(
+    *, topic: str | None, context: str | None
+) -> bool:
+    haystack = " ".join([topic or "", context or ""]).lower()
+    return any(
+        token in haystack
+        for token in (
+            "electromagnetic induction",
+            "faraday",
+            "lenz",
+            "magnetic flux",
+            "induced emf",
+        )
+    )
+
+
 def _long_answer_item(topic: str, snippet: str, keywords: list[str]) -> dict[str, Any]:
-    formula = "epsilon = -N(dPhi/dt) [SI unit: Volt (V)]"
-    if not _is_physics_topic(subject="Physics", topic=topic, context=snippet):
-        formula = "Use the main formula or labelled process from the chapter, with SI units where applicable."
+    is_electromagnetic_induction = _is_electromagnetic_induction_topic(
+        topic=topic,
+        context=snippet,
+    )
+    formula = (
+        "epsilon = -N(dPhi/dt) [SI unit: Volt (V)]"
+        if is_electromagnetic_induction
+        else "Use the governing formula or labelled process for this topic, with SI units where applicable."
+    )
+    diagram_guidance = (
+        "Diagram guidance: label the magnet, coil, galvanometer, field lines, motion arrow, and induced current."
+        if is_electromagnetic_induction
+        else f"Diagram guidance: use a labelled {topic} diagram only when the question requires one."
+    )
+    application_guidance = (
+        "Application: mention one use such as a generator or transformer."
+        if is_electromagnetic_induction
+        else "Application: connect the idea to one relevant chapter example."
+    )
     return {
         "question": f"Write a 5/6-mark long answer on {topic}.",
         "answer": (
             f"Introduction: {topic} is a board-level scoring concept. "
             f"Law/principle: state the central principle clearly. Formula: {formula}. "
             "Explanation: define each symbol, show how the change/process produces the result, "
-            "and connect it to the exam keyword. Diagram guidance: draw the required labelled "
-            "setup if the question is visual. Application: mention one use such as generator, "
-            "transformer, or a real chapter example. Conclusion: end with the key principle."
+            f"and connect it to the exam keyword. {diagram_guidance} "
+            f"{application_guidance} Conclusion: end with the key principle."
         ),
         "intro": f"{topic} is an important concept for long-answer board questions.",
         "main_points": [
@@ -549,11 +580,11 @@ def _long_answer_item(topic: str, snippet: str, keywords: list[str]) -> dict[str
             "Law/principle stated exactly",
             f"Formula with units: {formula}",
             "Explanation of each symbol and physical meaning",
-            "Diagram guidance: labelled magnet, coil, galvanometer, field lines, and current arrow when relevant",
-            "Application and conclusion",
+            diagram_guidance,
+            f"{application_guidance} Add a conclusion.",
         ],
         "conclusion": f"Underline: {', '.join(keywords[:5])}. Avoid missing the sign/unit/diagram labels.",
-        "diagram_needed": _is_physics_topic(subject="Physics", topic=topic, context=snippet),
+        "diagram_needed": is_electromagnetic_induction,
     }
 
 
@@ -698,11 +729,14 @@ def _ensure_quiz_quality(
         )
         if not any(token in joined for token in ("numerical", "calculate", "diagram", "process", "draw")):
             questions[-1] = {
-                "question": "Draw or explain the labelled magnet-coil-galvanometer setup for electromagnetic induction.",
-                "type": "diagram/process",
+                "question": f"Draw or describe one labelled representation that helps explain {topic}.",
+                "type": "application/process",
                 "options": [],
-                "answer": "Label bar magnet, coil, galvanometer, field lines, motion arrow, and induced current arrow.",
-                "explanation": "This checks the visual process behind Faraday's law and Lenz's law.",
+                "answer": (
+                    f"Use only labels that belong to {topic}, and show the relevant direction, change, or relationship. "
+                    "If the topic has no useful diagram, describe one observable application instead."
+                ),
+                "explanation": "The representation must stay scoped to the requested topic.",
                 "difficulty": difficulty,
                 "skill": "diagram/process",
                 "topic": topic,
@@ -748,8 +782,16 @@ def _ensure_exam_long_answer(
             combined = " ".join(str(value) for value in item.values()).lower()
             answer = str(item.get("answer") or "")
             additions: list[str] = []
+            is_electromagnetic_induction = _is_electromagnetic_induction_topic(
+                topic=topic,
+                context=context,
+            )
             if "formula" not in combined:
-                additions.append("Formula: epsilon = -N(dPhi/dt) [Volt].")
+                additions.append(
+                    "Formula: epsilon = -N(dPhi/dt) [Volt]."
+                    if is_electromagnetic_induction
+                    else "Formula: state the governing relationship for this topic and give SI units where applicable."
+                )
             if "keyword" not in combined:
                 additions.append(f"Keywords to underline: {', '.join(keywords[:5])}.")
             if "diagram" not in combined and _is_physics_topic(
@@ -759,6 +801,8 @@ def _ensure_exam_long_answer(
             ):
                 additions.append(
                     "Diagram guidance: draw and label magnet, coil, galvanometer, field lines, motion arrow, and induced current."
+                    if is_electromagnetic_induction
+                    else f"Diagram guidance: include a topic-relevant labelled diagram for {topic} only when it helps answer the question."
                 )
                 item.setdefault("diagram_needed", True)
             if additions:
@@ -1016,68 +1060,96 @@ class MockAIProvider(BaseAIProvider):
         question_count: int,
         metadata: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        snippet = _study_snippet(context)
-        keywords = _keyword_candidates(context)
+        metadata = metadata or {}
         topic = _topic_from_metadata_or_text(metadata, context)
-        subject = str((metadata or {}).get("subject") or "")
+        has_source = bool(metadata.get("source_title"))
+        quiz_context = context if has_source else topic
+        snippet = _study_snippet(quiz_context)
+        keywords = _keyword_candidates(quiz_context)
+        subject = str(metadata.get("subject") or "")
         is_physics = _is_physics_topic(subject=subject, topic=topic, context=context)
+        scope_label = "selected material" if has_source else "requested topic"
         questions = [
             {
-                "question": f"Which keyword best matches this material: {snippet[:90]}?",
+                "question": f"Which keyword best matches this {scope_label}: {snippet[:90]}?",
                 "type": "mcq",
                 "options": [keywords[0], keywords[1], keywords[2], keywords[3]],
                 "answer": keywords[0],
-                "explanation": "This keyword appears as a central exam term in the source.",
+                "explanation": f"This keyword anchors the {scope_label}.",
                 "difficulty": difficulty,
                 "skill": "recall",
                 "topic": keywords[0],
             },
             {
-                "question": "Write one exam keyword from the uploaded material.",
+                "question": f"Write one exam keyword for {topic}.",
                 "type": "short",
                 "options": [],
                 "answer": keywords[1],
-                "explanation": "Short answers should use exact source keywords.",
+                "explanation": "Short answers should use exact topic keywords.",
                 "difficulty": difficulty,
                 "skill": "understanding",
                 "topic": keywords[1],
             },
             {
-                "question": f"True or false: The material mentions {keywords[2]}.",
+                "question": f"True or false: {keywords[2]} is included in this {scope_label}.",
                 "type": "true_false",
                 "options": ["True", "False"],
                 "answer": "True",
-                "explanation": "This is checked from the retrieved document chunk.",
+                "explanation": f"This is checked against the {scope_label}.",
                 "difficulty": difficulty,
                 "skill": "tricky mistake",
                 "topic": keywords[2],
             },
         ]
-        physics_questions = [
-            {
-                "question": (
-                    "A coil has 50 turns and magnetic flux changes from 0.04 Wb "
-                    "to 0 Wb in 0.2 s. Calculate the induced EMF."
-                ),
-                "type": "numerical",
-                "options": [],
-                "answer": "10 V using epsilon = -N(delta phi / delta t) [SI unit: Volt].",
-                "explanation": "Use Faraday's law: epsilon = -50 x (0 - 0.04) / 0.2 = 10 V.",
-                "difficulty": difficulty,
-                "skill": "numerical/application",
-                "topic": topic,
-            },
-            {
-                "question": "Draw the labelled magnet-coil-galvanometer setup for electromagnetic induction.",
-                "type": "diagram/process",
-                "options": [],
-                "answer": "Show bar magnet, coil, galvanometer, field lines, motion arrow, and induced current arrow.",
-                "explanation": "Kerala +2 Physics answers often score extra clarity from a neat labelled setup diagram.",
-                "difficulty": difficulty,
-                "skill": "diagram/process",
-                "topic": topic,
-            },
-        ]
+        if _is_electromagnetic_induction_topic(topic=topic, context=quiz_context):
+            physics_questions = [
+                {
+                    "question": (
+                        "A coil has 50 turns and magnetic flux changes from 0.04 Wb "
+                        "to 0 Wb in 0.2 s. Calculate the induced EMF."
+                    ),
+                    "type": "numerical",
+                    "options": [],
+                    "answer": "10 V using epsilon = -N(delta phi / delta t) [SI unit: Volt].",
+                    "explanation": "Use Faraday's law: epsilon = -50 x (0 - 0.04) / 0.2 = 10 V.",
+                    "difficulty": difficulty,
+                    "skill": "numerical/application",
+                    "topic": topic,
+                },
+                {
+                    "question": "Draw the labelled magnet-coil-galvanometer setup for electromagnetic induction.",
+                    "type": "diagram/process",
+                    "options": [],
+                    "answer": "Show bar magnet, coil, galvanometer, field lines, motion arrow, and induced current arrow.",
+                    "explanation": "The labels show how changing magnetic flux produces an induced current.",
+                    "difficulty": difficulty,
+                    "skill": "diagram/process",
+                    "topic": topic,
+                },
+            ]
+        else:
+            physics_questions = [
+                {
+                    "question": f"Set up one numerical or quantitative application of {topic}. What must be written before substitution?",
+                    "type": "numerical method",
+                    "options": [],
+                    "answer": "Write the given values, the required quantity, the topic-specific formula or relationship, and convert every value to SI units before substituting.",
+                    "explanation": f"This checks a safe solving method without importing a formula from an unrelated Physics chapter into {topic}.",
+                    "difficulty": difficulty,
+                    "skill": "numerical/application",
+                    "topic": topic,
+                },
+                {
+                    "question": f"Draw or describe one labelled representation that helps explain {topic}.",
+                    "type": "application/process",
+                    "options": [],
+                    "answer": f"Use only quantities, directions, or parts that belong to {topic}; if no diagram is useful, describe one observable application instead.",
+                    "explanation": "Every label and step must stay relevant to the requested topic.",
+                    "difficulty": difficulty,
+                    "skill": "application/process",
+                    "topic": topic,
+                },
+            ]
         if is_physics:
             if question_count <= 3:
                 questions = [questions[0], *physics_questions]
@@ -1090,8 +1162,8 @@ class MockAIProvider(BaseAIProvider):
                     "question": f"Why is {keyword} important for exam answers?",
                     "type": "short",
                     "options": [],
-                    "answer": f"{keyword} is an important source keyword.",
-                    "explanation": "Use the exact term to score keyword marks.",
+                    "answer": f"{keyword} is an important keyword for {topic}.",
+                    "explanation": "Use the exact topic term in the answer.",
                     "difficulty": difficulty,
                     "skill": "exam",
                     "topic": keyword,

app/services/file_storage.py

@@ -15,11 +15,6 @@ _MAX_UPLOAD_BYTES = 20 * 1024 * 1024
 _ALLOWED_MIME_TYPES: frozenset[str] = frozenset(
     {
         "application/pdf",
-        "image/jpeg",
-        "image/jpg",
-        "image/png",
-        "image/webp",
-        "image/gif",
         "text/plain",
     }
 )
@@ -48,7 +43,8 @@ def save_upload_file(upload_file: UploadFile, upload_dir: Path) -> StoredFile:
             status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
             detail=(
                 f"File type '{content_type}' is not supported. "
-                "Please upload a PDF, image (JPEG/PNG/WebP), or plain text file."
+                "Please upload a selectable-text PDF or plain text file. "
+                "Image OCR and Word document extraction are not available yet."
             ),
         )
 
@@ -82,7 +78,7 @@ def save_upload_file(upload_file: UploadFile, upload_dir: Path) -> StoredFile:
     if too_large:
         destination.unlink(missing_ok=True)
         raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
             detail=(
                 f"File exceeds the 20 MB limit "
                 f"({total_bytes / (1024 * 1024):.1f} MB uploaded so far). "

app/services/learn_lesson_builder.py

@@ -25,18 +25,23 @@ import logging
 import os
 import re
 import subprocess
+import threading
 import urllib.error
 import urllib.request
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-from app.core.config import PROJECT_ROOT, get_settings
+from app.core.config import BACKEND_DIR, PROJECT_ROOT, get_settings
 
 logger = logging.getLogger(__name__)
 
-# Served to the browser under /generated/learn-anything/<hash>/...
-PUBLIC_ROOT = PROJECT_ROOT / "public" / "generated" / "learn-anything"
+# Writable cache for lesson manifests + audio.
+# NEVER use PROJECT_ROOT/"public" — on HF Docker WORKDIR=/app, that resolves to
+# /public which is not creatable (Permission denied → 500).
+# Prefer: LEARN_LESSON_CACHE_DIR → /app/generated/... → backend/generated/...
+# Tests may monkeypatch PUBLIC_ROOT.
+PUBLIC_ROOT = BACKEND_DIR / "generated" / "learn-anything"
 
 GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
 # llama-4-scout was retired from Groq; 3.3-70b is the strongest current chat model.
@@ -49,6 +54,11 @@ TARGET_BEATS = 16
 MIN_BEATS = 12
 MAX_BEATS = 20
 
+# Prevent stampede: many students opening the same uncached lesson at once
+# should share one authoring job, not N parallel LLM bills.
+_lesson_build_locks: dict[str, threading.Lock] = {}
+_lesson_build_locks_guard = threading.Lock()
+
 
 class LessonBuildError(RuntimeError):
     pass
@@ -78,13 +88,19 @@ def _env(name: str) -> str:
         path = PROJECT_ROOT / filename
         if not path.exists():
             continue
-        for line in path.read_text(encoding="utf-8").splitlines():
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            raw = path.read_text(encoding="utf-8", errors="replace")
+        for line in raw.splitlines():
             if line.startswith(f"{name}="):
                 return _clean_env_value(line.split("=", 1)[1])
     return ""
 
 
-def lesson_hash(topic: str, lesson_title: str, level: str, medium: str, voice: str) -> str:
+def lesson_hash(
+    topic: str, lesson_title: str, level: str, medium: str, voice: str
+) -> str:
     payload = json.dumps(
         {
             "topic": topic.strip().lower(),
@@ -99,75 +115,149 @@ def lesson_hash(topic: str, lesson_title: str, level: str, medium: str, voice: s
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:20]
 
 
-def _call_groq(prompt: str, api_key: str, max_tokens: int = 8000) -> dict[str, Any]:
+def _call_openai_compatible_json(
+    *,
+    url: str,
+    api_key: str,
+    model: str,
+    prompt: str,
+    max_tokens: int = 8000,
+    provider_label: str,
+) -> dict[str, Any]:
+    """OpenAI-shaped chat completions that return a JSON object body."""
     payload = {
-        "model": GROQ_MODEL,
+        "model": model,
         "messages": [{"role": "user", "content": prompt}],
         "temperature": 0.35,
         "max_tokens": max_tokens,
         "response_format": {"type": "json_object"},
     }
     request = urllib.request.Request(
-        GROQ_URL,
+        url,
         data=json.dumps(payload).encode("utf-8"),
         headers={
             "Content-Type": "application/json",
             "Authorization": f"Bearer {api_key}",
-            # Groq's Cloudflare front-end 403s urllib's default UA.
-            "User-Agent": "python-requests/2.31.0",
+            # Some CDN edges 403 urllib's default UA.
+            "User-Agent": "DocDoe-LearnLesson/1.0",
         },
         method="POST",
     )
-    with urllib.request.urlopen(request, timeout=180) as response:
-        result = json.loads(response.read().decode("utf-8"))
-    return json.loads(result["choices"][0]["message"]["content"])
+    try:
+        with urllib.request.urlopen(request, timeout=180) as response:
+            result = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = ""
+        try:
+            body = exc.read().decode("utf-8", errors="replace")[:400]
+        except Exception:
+            body = ""
+        raise LessonBuildError(
+            f"{provider_label} HTTP {exc.code}: {body or exc.reason}"
+        ) from exc
+    content = result["choices"][0]["message"]["content"]
+    if isinstance(content, list):
+        # Some providers return content parts; join text pieces.
+        content = "".join(
+            part.get("text", "") if isinstance(part, dict) else str(part)
+            for part in content
+        )
+    return json.loads(content)
+
+
+def _call_groq(prompt: str, api_key: str, max_tokens: int = 8000) -> dict[str, Any]:
+    return _call_openai_compatible_json(
+        url=GROQ_URL,
+        api_key=api_key,
+        model=GROQ_MODEL,
+        prompt=prompt,
+        max_tokens=max_tokens,
+        provider_label="Groq",
+    )
 
 
-def _lesson_prompt(topic: str, lesson_title: str, level: str, medium: str, context: str) -> str:
+def _script_llm_providers() -> list[dict[str, Any]]:
+    """Lesson-script providers: Groq OpenAI-compatible chat."""
+    providers: list[dict[str, Any]] = []
+    groq = _env("GROQ_API_KEY")
+    if groq.startswith(("gsk-", "gsk_")) and len(groq) >= 20:
+        providers.append(
+            {
+                "name": "groq",
+                "key": groq,
+                "call": lambda prompt, key=groq: _call_groq(prompt, key),
+            }
+        )
+    return providers
+
+
+def _lesson_prompt(
+    topic: str, lesson_title: str, level: str, medium: str, context: str
+) -> str:
     medium_rule = (
         "Write the spoken narration in natural spoken Malayalam mixed with English technical terms "
         "(the way a Kerala tuition teacher actually talks: Malayalam sentences, English kept for "
-        "technical vocabulary). Keep board_heading and board_lines in English."
+        "technical vocabulary). Keep board_heading, board_lines, objectives, notes and flashcards in English."
         if medium.strip().lower() in {"malayalam", "manglish", "ml"}
         else "Write the spoken narration in clear, simple spoken Indian English."
     )
-    return f"""You are an outstanding tutor making ONE ~10-minute lesson that a student watches as a continuous class (not slides).
+    return f"""You are one of the best teachers in the world making ONE ~10-minute lesson that a student experiences as a continuous, spoken class (not slides). Your goal: the student truly UNDERSTANDS, not just hears facts.
 
 Lesson: "{lesson_title}"
 Part of learning: "{topic}"
 Learner level: {level or "beginner"}
 {medium_rule}
 
+HOW A GREAT LESSON IS BUILT (follow this arc across the beats)
+1. HOOK — open with a real question, surprising fact, or everyday situation that makes the student curious about THIS lesson. No throat-clearing.
+2. GROUND IT — connect to something the student already knows before introducing anything new.
+3. EXPLAIN — teach the core idea. ALWAYS give the reason BEFORE the rule ("here's why, so the rule makes sense"). Build up, never dump.
+4. WORKED EXAMPLE — walk through ONE concrete, specific example with real numbers/specifics, step by step, thinking out loud. This is the heart of the lesson — make it vivid and complete.
+5. ANALOGY — at most one, and only if it genuinely makes the idea click.
+6. MISCONCEPTION — name the exact mistake students usually make here and correct it directly ("A lot of students think X — but actually Y, because...").
+7. CHECKPOINT — ask the student a question and give them a beat to think, then reveal and explain the answer. Make them do the thinking.
+8. RECAP — warm, tight summary of what they can now do, and how it connects to the next thing.
+
 TEACHING RULES
-- One continuous class that flows: hook the curiosity, explain simply with a reason before any rule, give a concrete example, use one analogy only if it truly clarifies, check understanding, then recap.
-- Talk TO the student ("you"), warm and clear. Use short spoken sentences, but keep teaching — expand every idea with the "why", a concrete example, and what it means for the student.
-- CRITICAL LENGTH RULE: each beat's narration MUST be 90-130 words of what the teacher actually SAYS. Do not write one- or two-sentence beats. A real teacher talks for 40-60 seconds per beat.
-- The board is what appears on screen while they speak — a short heading and 2-5 tight bullet lines (not full sentences). Never read the board out loud word-for-word; the narration teaches, the board reinforces.
-- Total narration across all beats MUST be about 1200-1500 words — this is a full ~10 minute class, not a summary.
+- Talk TO the student ("you"), warm, human, and encouraging. Sound like a person who loves this subject, not a textbook.
+- Reason before rule, concrete before abstract, one idea per beat fully developed.
+- CRITICAL LENGTH RULE: each beat's narration MUST be 90-140 words of what the teacher actually SAYS. Never write one- or two-sentence beats. A real teacher talks for 40-60 seconds per beat.
+- The board is what appears on screen WHILE they speak — a short heading and 2-5 tight bullet fragments (not full sentences, not read aloud verbatim). The narration teaches; the board reinforces the keywords, the formula, or the example's steps.
+- Total narration across all beats MUST be about 1300-1600 words — a full ~10 minute class, not a summary.
+- Be accurate. If the lesson has a formula, definition, or process, state it precisely and correctly.
+
+QUALITY OF SUPPORTING MATERIAL
+- objectives: 3-5 crisp "By the end you can…" statements — the concrete skills this lesson delivers.
+- notes: 6-10 revision notes a student writes in their notebook — self-contained, exam-ready, each a complete useful fact (include the key formula/definition/steps, not vague reminders).
+- flashcards: 6-10 real question→answer pairs that test the hardest/most testable points (definitions, why-questions, one small applied problem). Answers must be correct and specific.
 
 Return ONE JSON object, no markdown:
 {{
   "lesson_title": "{lesson_title}",
+  "summary": "one warm sentence describing what this class teaches",
+  "objectives": ["By the end you can …", "By the end you can ��"],
   "beats": [
-    {{"kind": "hook|explain|example|analogy|checkpoint|recap", "narration": "what the teacher says", "board_heading": "short title", "board_lines": ["tight point", "tight point"], "visual_hint": "optional: a simple diagram/idea to draw, or empty string"}}
+    {{"kind": "hook|explain|example|analogy|checkpoint|recap", "narration": "what the teacher says (90-140 words)", "board_heading": "short title", "board_lines": ["tight fragment", "tight fragment"], "visual_hint": "optional: a simple diagram/idea to draw, or empty string"}}
   ],
-  "notes": ["6-10 concise revision notes a student writes down"],
-  "flashcards": [{{"front": "question", "back": "answer"}}]
+  "notes": ["exam-ready revision note", "..."],
+  "flashcards": [{{"front": "question", "back": "correct, specific answer"}}]
 }}
 
-Make {MIN_BEATS}-{MAX_BEATS} beats (aim for {TARGET_BEATS}) and 6-10 flashcards.
-{f'Use this source material where relevant:{chr(10)}{context[:4000]}' if context.strip() else ''}
+Make {MIN_BEATS}-{MAX_BEATS} beats (aim for {TARGET_BEATS}), 3-5 objectives, 6-10 notes and 6-10 flashcards.
+{f"Use this source material where relevant (stay faithful to it):{chr(10)}{context[:4000]}" if context.strip() else ""}
 """
 
 
-def _continue_prompt(topic: str, lesson_title: str, level: str, medium: str, taught_headings: list[str]) -> str:
+def _continue_prompt(
+    topic: str, lesson_title: str, level: str, medium: str, taught_headings: list[str]
+) -> str:
     medium_rule = (
         "Continue in natural spoken Malayalam mixed with English technical terms; keep board text in English."
         if medium.strip().lower() in {"malayalam", "manglish", "ml"}
         else "Continue in clear, simple spoken Indian English."
     )
     already = "; ".join(taught_headings)
-    return f"""You are continuing a live ~10-minute class on "{lesson_title}" (part of "{topic}", learner level {level or 'beginner'}).
+    return f"""You are continuing a live ~10-minute class on "{lesson_title}" (part of "{topic}", learner level {level or "beginner"}).
 {medium_rule}
 
 So far you have already taught these beats: {already}.
@@ -188,14 +278,266 @@ Write 6-9 more beats and 6-10 flashcards.
 """
 
 
-def _generate_with_retries(prompt: str, api_key: str, label: str) -> dict[str, Any]:
+def _starter_reading_script(
+    *, topic: str, lesson_title: str, level: str
+) -> dict[str, Any]:
+    """Return an honest, deterministic lesson for local/mock development.
+
+    The direct Groq/Deepgram authoring pipeline must not run when the configured
+    AI provider is ``mock``. This starter is deliberately labelled as reading
+    mode by ``build_lesson``; it keeps roadmap study and resume flows usable
+    without presenting generated audio as real.
+    """
+    normalized = " ".join([topic, lesson_title]).lower()
+    if "python" in normalized:
+        return {
+            "lesson_title": lesson_title,
+            "summary": "A beginner reading class on how Python instructions, values, decisions, repetition, and functions fit together.",
+            "objectives": [
+                "Explain what a Python program does",
+                "Use variables and basic value types",
+                "Recognise decisions, loops, and functions",
+                "Trace a short program before running it",
+            ],
+            "beats": [
+                {
+                    "kind": "hook",
+                    "narration": "A computer does not guess what you mean. It follows instructions in order. Python gives you a readable way to write those instructions. In this class, treat every line as a small command: store a value, make a decision, repeat an action, or reuse a group of instructions. That simple model is enough to begin reading real Python without memorising a long list of rules.",
+                    "board_heading": "Code is a sequence of instructions",
+                    "board_lines": [
+                        "Read top to bottom",
+                        "One clear action per line",
+                        "Predict before you run",
+                    ],
+                    "visual_hint": "Draw three boxes labelled input, process, output.",
+                },
+                {
+                    "kind": "explain",
+                    "narration": "A variable is a name that refers to a value. For example, score = 5 gives the name score the integer value 5, while name = 'Asha' gives name a text value. Common beginner types are int for whole numbers, float for decimal numbers, str for text, and bool for True or False. The equals sign assigns a value here; it does not ask whether two values are equal.",
+                    "board_heading": "Names and values",
+                    "board_lines": [
+                        "score = 5",
+                        "name = 'Asha'",
+                        "int, float, str, bool",
+                    ],
+                    "visual_hint": "Connect each variable name to its current value.",
+                },
+                {
+                    "kind": "example",
+                    "narration": "Trace this example: name = 'Asha', marks = 8, then print(name, marks). The first line stores text, the second stores a whole number, and print sends both values to the output. Change marks to 9 and only the printed number changes. This is a useful study habit: say what each line changes before you press Run. Tracing catches many mistakes faster than rereading the whole program.",
+                    "board_heading": "Worked example",
+                    "board_lines": [
+                        "name = 'Asha'",
+                        "marks = 8",
+                        "print(name, marks)",
+                        "Output: Asha 8",
+                    ],
+                    "visual_hint": "Use a two-column trace table: variable and value.",
+                },
+                {
+                    "kind": "explain",
+                    "narration": "Programs become useful when they can choose and repeat. An if statement runs a block only when its condition is True. A for loop repeats a block for each item in a sequence. Python uses indentation to show which lines belong inside that block, so spacing changes meaning. Read the condition first, then follow only the indented lines that should run.",
+                    "board_heading": "Decide and repeat",
+                    "board_lines": [
+                        "if condition:",
+                        "    run this block",
+                        "for item in sequence:",
+                        "    repeat this block",
+                    ],
+                    "visual_hint": "Draw a decision diamond leading to an indented block.",
+                },
+                {
+                    "kind": "explain",
+                    "narration": "A function gives a reusable name to a group of instructions. You define it with def, pass information through parameters, and use return when the function must send a result back. For example, def double(number): return number * 2 describes one job clearly. Calling double(4) produces 8. Functions reduce repetition and make each part of a program easier to test.",
+                    "board_heading": "Reuse with functions",
+                    "board_lines": [
+                        "def double(number):",
+                        "    return number * 2",
+                        "double(4) -> 8",
+                    ],
+                    "visual_hint": "Show input 4 entering a function box and output 8 leaving it.",
+                },
+                {
+                    "kind": "checkpoint",
+                    "narration": "Pause and predict this without running it: total = 2, then for number in [1, 2, 3], total = total + number. The loop adds 1, then 2, then 3 to the starting value 2, so total becomes 8. If your answer differed, write the value after every pass. A trace table is the correction tool: it makes the changing state visible instead of asking you to hold every step in memory.",
+                    "board_heading": "Checkpoint",
+                    "board_lines": [
+                        "Start: total = 2",
+                        "+1 -> 3",
+                        "+2 -> 5",
+                        "+3 -> 8",
+                    ],
+                    "visual_hint": "Make one row for each loop pass.",
+                },
+                {
+                    "kind": "recap",
+                    "narration": "You now have a map for beginner Python. Values are stored behind variable names. If chooses a path, for repeats a block, and def creates a reusable function. Your next move is small: type the worked example, change one value, and predict the new output before running it. Learning programming comes from this short loop of predict, run, compare, and correct.",
+                    "board_heading": "Your Python map",
+                    "board_lines": [
+                        "Variables store values",
+                        "if chooses",
+                        "for repeats",
+                        "def reuses",
+                        "Predict -> run -> correct",
+                    ],
+                    "visual_hint": "Keep this map beside your first practice program.",
+                },
+            ],
+            "notes": [
+                "Python executes instructions in a defined order.",
+                "A variable name refers to a value; assignment uses =.",
+                "Basic beginner types include int, float, str, and bool.",
+                "An if statement runs its indented block when the condition is True.",
+                "A for loop repeats its indented block for items in a sequence.",
+                "A function is defined with def and can return a result.",
+                "Trace changing variable values to debug a short program.",
+            ],
+            "flashcards": [
+                {
+                    "front": "What does = do in score = 5?",
+                    "back": "It assigns the integer value 5 to the name score.",
+                },
+                {"front": "Which type stores text?", "back": "str"},
+                {"front": "What controls a Python code block?", "back": "Indentation."},
+                {
+                    "front": "What does an if statement do?",
+                    "back": "It runs a block when its condition is True.",
+                },
+                {
+                    "front": "What does a for loop do?",
+                    "back": "It repeats a block for each item in a sequence.",
+                },
+                {
+                    "front": "Why use a function?",
+                    "back": "To name and reuse a focused group of instructions.",
+                },
+            ],
+        }
+
+    clean_title = lesson_title.strip() or topic.strip() or "this topic"
+    clean_level = level.strip() or "beginner"
+    return {
+        "lesson_title": clean_title,
+        "summary": f"A {clean_level} starter reading class that turns {clean_title} into a definition, example, check, and next practice move.",
+        "objectives": [
+            f"State what {clean_title} means",
+            "Identify the central terms",
+            "Work through one concrete example",
+            "Check your understanding without notes",
+        ],
+        "beats": [
+            {
+                "kind": "hook",
+                "narration": f"Before collecting facts about {clean_title}, write one question you want this lesson to answer. That question gives the topic a purpose and makes it easier to notice which ideas matter.",
+                "board_heading": "Start with one question",
+                "board_lines": [
+                    f"Topic: {clean_title}",
+                    "What must I understand?",
+                    "What can I explain after this?",
+                ],
+                "visual_hint": "Write your question at the top of the page.",
+            },
+            {
+                "kind": "explain",
+                "narration": f"Build a precise definition of {clean_title}: name the larger idea it belongs to, the feature that makes it distinct, and one boundary or condition. Keep this as a working definition and verify subject-specific facts against a trusted lesson or source.",
+                "board_heading": "Build the definition",
+                "board_lines": [
+                    "Category",
+                    "Distinct feature",
+                    "Boundary or condition",
+                ],
+                "visual_hint": "Use a three-part definition box.",
+            },
+            {
+                "kind": "example",
+                "narration": f"Choose one concrete example of {clean_title}. Label which part of the definition appears in the example and which details are only background. A useful example should let you explain why it belongs, not merely name it.",
+                "board_heading": "Test with an example",
+                "board_lines": [
+                    "Name the example",
+                    "Match it to the definition",
+                    "Explain why it fits",
+                ],
+                "visual_hint": "Draw arrows from example details to definition terms.",
+            },
+            {
+                "kind": "checkpoint",
+                "narration": f"Close your notes and explain {clean_title} in two sentences: one definition and one example with a reason. If you cannot connect the example to the definition, mark that exact missing link for revision instead of restarting the whole topic.",
+                "board_heading": "Quick check",
+                "board_lines": [
+                    "Sentence 1: definition",
+                    "Sentence 2: example + why",
+                    "Mark the missing link",
+                ],
+                "visual_hint": "Answer aloud before reopening your notes.",
+            },
+            {
+                "kind": "recap",
+                "narration": f"Your next move for {clean_title} is now specific: verify the working definition, add one subject-correct example, then retry the two-sentence explanation tomorrow. That short retrieval step creates evidence of learning and gives the roadmap a real place to resume.",
+                "board_heading": "Next move",
+                "board_lines": ["Verify", "Add one example", "Recall tomorrow"],
+                "visual_hint": "Schedule the two-sentence recall for tomorrow.",
+            },
+        ],
+        "notes": [
+            f"Working topic: {clean_title}.",
+            "A strong definition gives category, distinct feature, and boundary.",
+            "An example is useful only when you can explain why it fits.",
+            "Mark the exact missing link instead of restarting everything.",
+            "Retry the definition and example from memory the next day.",
+        ],
+        "flashcards": [
+            {
+                "front": f"What is your working definition of {clean_title}?",
+                "back": "Give category, distinct feature, and boundary; verify subject facts against a trusted source.",
+            },
+            {
+                "front": "What makes an example useful?",
+                "back": "You can connect its details to the definition and explain why it fits.",
+            },
+            {
+                "front": "What should you revise after a failed recall?",
+                "back": "The exact missing link, not the entire topic.",
+            },
+        ],
+    }
+
+
+def _generate_with_retries(
+    prompt: str,
+    label: str,
+    providers: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
     last_error: Exception | None = None
-    for attempt in range(1, 4):
-        try:
-            return _call_groq(prompt, api_key)
-        except (urllib.error.URLError, TimeoutError, KeyError, json.JSONDecodeError) as exc:
-            last_error = exc
-            logger.warning("Lesson %s attempt %s failed: %s", label, attempt, type(exc).__name__)
+    chain = providers if providers is not None else _script_llm_providers()
+    if not chain:
+        raise LessonBuildError(
+            "No lesson LLM key configured. Set GROQ_API_KEY for Learn Anything authoring."
+        )
+    for provider in chain:
+        name = str(provider.get("name") or "llm")
+        call = provider["call"]
+        for attempt in range(1, 3):
+            try:
+                data = call(prompt)
+                logger.info("Lesson %s authored via %s (attempt %s)", label, name, attempt)
+                return data
+            except (
+                urllib.error.URLError,
+                TimeoutError,
+                KeyError,
+                json.JSONDecodeError,
+                LessonBuildError,
+                ValueError,
+                TypeError,
+            ) as exc:
+                last_error = exc
+                logger.warning(
+                    "Lesson %s via %s attempt %s failed: %s",
+                    label,
+                    name,
+                    attempt,
+                    type(exc).__name__,
+                )
     raise LessonBuildError(f"Lesson {label} generation failed: {last_error}")
 
 
@@ -211,23 +553,47 @@ def generate_lesson_script(
     medium: str = "english",
     context: str = "",
 ) -> dict[str, Any]:
-    api_key = _env("GROQ_API_KEY")
-    if not (api_key.startswith("gsk_") and len(api_key) >= 20):
-        raise LessonBuildError("GROQ_API_KEY missing or invalid; cannot author lesson script.")
+    providers = _script_llm_providers()
+    if not providers:
+        logger.warning(
+            "GROQ_API_KEY missing/invalid; serving starter reading class."
+        )
+        return _starter_reading_script(
+            topic=topic, lesson_title=lesson_title, level=level
+        )
+
+    try:
+        data = _generate_with_retries(
+            _lesson_prompt(topic, lesson_title, level, medium, context),
+            "script",
+            providers,
+        )
+    except LessonBuildError as exc:
+        # Never leave 1000 students on a hard error when providers are out of quota:
+        # fall back to a complete starter reading class and keep the product usable.
+        logger.warning("Lesson script providers failed (%s); using starter class.", exc)
+        return _starter_reading_script(
+            topic=topic, lesson_title=lesson_title, level=level
+        )
 
-    data = _generate_with_retries(_lesson_prompt(topic, lesson_title, level, medium, context), api_key, "script")
     beats = list(data.get("beats") or [])
     if not beats:
-        raise LessonBuildError("Model returned no lesson beats.")
+        return _starter_reading_script(
+            topic=topic, lesson_title=lesson_title, level=level
+        )
 
     # The model reliably writes ~4-5 minutes in one call, then stops. To reach a
     # real ~10-minute class, ask it to continue from what it already taught.
     # One continuation is enough; this stays a cheap 2-call generation.
     if _narration_words(beats) < 950:
         try:
-            taught = [str(beat.get("board_heading") or beat.get("kind")) for beat in beats]
+            taught = [
+                str(beat.get("board_heading") or beat.get("kind")) for beat in beats
+            ]
             more = _generate_with_retries(
-                _continue_prompt(topic, lesson_title, level, medium, taught), api_key, "continuation"
+                _continue_prompt(topic, lesson_title, level, medium, taught),
+                "continuation",
+                providers,
             )
             beats.extend(more.get("beats") or [])
             # Prefer the fuller notes/flashcards from whichever pass gave more.
@@ -246,7 +612,10 @@ def _deepgram_synthesize(text: str, out_path: Path, api_key: str, model: str) ->
     request = urllib.request.Request(
         url,
         data=json.dumps({"text": text}).encode("utf-8"),
-        headers={"Authorization": f"Token {api_key}", "Content-Type": "application/json"},
+        headers={
+            "Authorization": f"Token {api_key}",
+            "Content-Type": "application/json",
+        },
         method="POST",
     )
     with urllib.request.urlopen(request, timeout=120) as response:
@@ -257,7 +626,19 @@ def _deepgram_synthesize(text: str, out_path: Path, api_key: str, model: str) ->
     pcm_path = out_path.with_suffix(".pcm")
     pcm_path.write_bytes(audio)
     subprocess.run(
-        ["ffmpeg", "-y", "-f", "s16le", "-ar", "24000", "-ac", "1", "-i", str(pcm_path), str(out_path)],
+        [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "s16le",
+            "-ar",
+            "24000",
+            "-ac",
+            "1",
+            "-i",
+            str(pcm_path),
+            str(out_path),
+        ],
         check=True,
         capture_output=True,
     )
@@ -266,7 +647,16 @@ def _deepgram_synthesize(text: str, out_path: Path, api_key: str, model: str) ->
 
 def _probe_duration(path: Path) -> float:
     completed = subprocess.run(
-        ["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", str(path)],
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration",
+            "-of",
+            "default=nw=1:nk=1",
+            str(path),
+        ],
         capture_output=True,
         check=True,
         text=True,
@@ -274,9 +664,10 @@ def _probe_duration(path: Path) -> float:
     return round(float(completed.stdout.strip()), 3)
 
 
-def synthesize_beats(beats: list[dict[str, Any]], out_dir: Path, medium: str) -> list[LessonBeat]:
+def synthesize_beats(
+    beats: list[dict[str, Any]], out_dir: Path, medium: str
+) -> list[LessonBeat]:
     """Voice each beat. Deepgram for English; AI4Bharat for Malayalam medium."""
-    settings = get_settings()
     use_malayalam = medium.strip().lower() in {"malayalam", "ml"}
     result: list[LessonBeat] = []
     cursor = 0.0
@@ -291,7 +682,9 @@ def synthesize_beats(beats: list[dict[str, Any]], out_dir: Path, medium: str) ->
         api_key = _env("DOCDOE_TTS_API_KEY")
         model = _env("DOCDOE_TTS_MODEL") or "aura-luna-en"
         if not api_key:
-            raise LessonBuildError("DOCDOE_TTS_API_KEY (Deepgram) missing; cannot voice English lesson.")
+            raise LessonBuildError(
+                "DOCDOE_TTS_API_KEY (Deepgram) missing; cannot voice English lesson."
+            )
 
     for index, beat in enumerate(beats, start=1):
         narration = str(beat.get("narration", "")).strip()
@@ -300,9 +693,18 @@ def synthesize_beats(beats: list[dict[str, Any]], out_dir: Path, medium: str) ->
         audio_path = out_dir / f"beat-{index:02d}.wav"
         if use_malayalam:
             provider, scene_cls = ai4bharat_provider
-            scene = scene_cls(scene_id=index, type="concept", duration_seconds=20, voice_text=narration)
+            scene = scene_cls(
+                scene_id=index,
+                type="concept",
+                duration_seconds=20,
+                voice_text=narration,
+            )
             synth = provider.generate_scene_audio(
-                scene=scene, output_file=audio_path, voice_mode="malayalam_soft", voice="Anjali", language="ml"
+                scene=scene,
+                output_file=audio_path,
+                voice_mode="malayalam_soft",
+                voice="Anjali",
+                language="ml",
             )
             if synth.file_path != audio_path:
                 Path(synth.file_path).replace(audio_path)
@@ -325,6 +727,97 @@ def synthesize_beats(beats: list[dict[str, Any]], out_dir: Path, medium: str) ->
     return result
 
 
+def _reading_beats(beats: list[dict[str, Any]]) -> list[LessonBeat]:
+    """Turn authored beats into a fully navigable reading class."""
+    result: list[LessonBeat] = []
+    cursor = 0.0
+    for beat in beats:
+        narration = str(beat.get("narration", "")).strip()
+        if not narration:
+            continue
+        duration = round(max(20.0, len(narration.split()) / 180 * 60), 3)
+        result.append(
+            LessonBeat(
+                kind=str(beat.get("kind", "explain")),
+                narration=narration,
+                board_heading=str(beat.get("board_heading", "")),
+                board_lines=[str(line) for line in (beat.get("board_lines") or [])],
+                visual_hint=str(beat.get("visual_hint", "")),
+                audio_src="",
+                start_second=round(cursor, 3),
+                duration_seconds=duration,
+            )
+        )
+        cursor += duration
+    return result
+
+
+def _lesson_lock_for(key: str) -> threading.Lock:
+    with _lesson_build_locks_guard:
+        lock = _lesson_build_locks.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _lesson_build_locks[key] = lock
+        return lock
+
+
+def _is_forbidden_cache_path(path: Path) -> bool:
+    """Block the HF /public tree that resolves outside the writable container."""
+    normalized = path.as_posix().replace("\\", "/")
+    # Unix absolute
+    if normalized == "/public" or normalized.startswith("/public/"):
+        return True
+    # Windows oddities if someone sets PUBLIC_ROOT = Path("/public/...")
+    if normalized.lower().endswith(":/public") or "/public/generated" in normalized and normalized.startswith("/"):
+        return True
+    return False
+
+
+def ensure_public_root() -> Path:
+    """Ensure the lesson cache directory exists and is writable on HF + local."""
+    candidates: list[Path] = []
+    env = _env("LEARN_LESSON_CACHE_DIR")
+    if env:
+        candidates.append(Path(env))
+    # Tests monkeypatch PUBLIC_ROOT to a temp path — prefer that when safe.
+    if not _is_forbidden_cache_path(PUBLIC_ROOT):
+        candidates.append(PUBLIC_ROOT)
+    # HF Docker WORKDIR is /app (backend tree).
+    candidates.append(Path("/app/generated/learn-anything"))
+    # Monorepo / local backend package root.
+    candidates.append(BACKEND_DIR / "generated" / "learn-anything")
+    # Last-resort temp (always writable for reading-mode fallbacks).
+    candidates.append(
+        Path(os.getenv("TMPDIR") or os.getenv("TEMP") or "/tmp")
+        / "docdoe-learn-lessons"
+    )
+
+    errors: list[str] = []
+    seen: set[str] = set()
+    for root in candidates:
+        key = root.as_posix()
+        if key in seen:
+            continue
+        seen.add(key)
+        if _is_forbidden_cache_path(root):
+            errors.append(f"skip forbidden path {root}")
+            continue
+        try:
+            root.mkdir(parents=True, exist_ok=True)
+            probe = root / ".write_probe"
+            probe.write_text("ok", encoding="utf-8")
+            probe.unlink(missing_ok=True)
+            logger.info("Lesson cache using %s", root)
+            return root
+        except OSError as exc:
+            errors.append(f"{root}: {exc}")
+            continue
+
+    raise LessonBuildError(
+        "Lesson cache directory is not writable. Tried: " + "; ".join(errors)
+    )
+
+
 def build_lesson(
     *,
     topic: str,
@@ -334,42 +827,127 @@ def build_lesson(
     context: str = "",
     force: bool = False,
 ) -> dict[str, Any]:
-    """Full pipeline: script -> audio -> playable manifest, cached by content hash."""
-    voice = "ai4bharat-anjali" if medium.strip().lower() in {"malayalam", "ml"} else (_env("DOCDOE_TTS_MODEL") or "aura-luna-en")
+    """Full pipeline: script -> audio -> playable manifest, cached by content hash.
+
+    Cache is shared across all students: the first open pays for authoring;
+    the next 999+ hits serve the same lesson.json + audio instantly.
+    Concurrent first opens for the same hash serialize on a per-hash lock so
+    we do not fan out N identical LLM bills under load.
+    """
+    settings = get_settings()
+    mock_mode = str(settings.ai_provider).strip().lower() == "mock"
+    voice = (
+        "reading-preview"
+        if mock_mode
+        else "ai4bharat-anjali"
+        if medium.strip().lower() in {"malayalam", "ml"}
+        else (_env("DOCDOE_TTS_MODEL") or "aura-luna-en")
+    )
     key = lesson_hash(topic, lesson_title, level, medium, voice)
-    out_dir = PUBLIC_ROOT / key
+    cache_root = ensure_public_root()
+    out_dir = cache_root / key
     manifest_path = out_dir / "lesson.json"
 
     if manifest_path.exists() and not force:
         return json.loads(manifest_path.read_text(encoding="utf-8"))
 
-    script = generate_lesson_script(topic=topic, lesson_title=lesson_title, level=level, medium=medium, context=context)
-    out_dir.mkdir(parents=True, exist_ok=True)
-    beats = synthesize_beats(script["beats"], out_dir, medium)
-    if not beats:
-        raise LessonBuildError("No audible beats were produced for the lesson.")
-
-    total_seconds = round(beats[-1].start_second + beats[-1].duration_seconds, 3)
-    manifest = {
-        "schema": "learn-lesson-v1",
-        "lessonHash": key,
-        "topic": topic,
-        "lessonTitle": script.get("lesson_title", lesson_title),
-        "level": level,
-        "medium": medium,
-        "voice": voice,
-        "totalSeconds": total_seconds,
-        "totalMinutes": round(total_seconds / 60, 2),
-        "beats": [beat.__dict__ for beat in beats],
-        "notes": [str(note) for note in (script.get("notes") or [])],
-        "flashcards": [
-            {"front": str(card.get("front", "")), "back": str(card.get("back", ""))}
-            for card in (script.get("flashcards") or [])
-            if card.get("front") and card.get("back")
-        ],
-    }
-    manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    return manifest
+    lock = _lesson_lock_for(key)
+    with lock:
+        # Re-check inside the lock: another student may have finished while we waited.
+        if manifest_path.exists() and not force:
+            return json.loads(manifest_path.read_text(encoding="utf-8"))
+
+        script = (
+            _starter_reading_script(topic=topic, lesson_title=lesson_title, level=level)
+            if mock_mode
+            else generate_lesson_script(
+                topic=topic,
+                lesson_title=lesson_title,
+                level=level,
+                medium=medium,
+                context=context,
+            )
+        )
+        try:
+            out_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            # Hard fallback: rebuild under /tmp so students still get a class.
+            emergency = (
+                Path(os.getenv("TMPDIR") or os.getenv("TEMP") or "/tmp")
+                / "docdoe-learn-lessons"
+                / key
+            )
+            try:
+                emergency.mkdir(parents=True, exist_ok=True)
+                out_dir = emergency
+                manifest_path = out_dir / "lesson.json"
+                logger.warning(
+                    "Lesson cache mkdir failed (%s); using emergency path %s",
+                    exc,
+                    out_dir,
+                )
+            except OSError as exc2:
+                raise LessonBuildError(
+                    f"Could not create lesson cache folder ({out_dir}): {exc}; "
+                    f"emergency also failed: {exc2}"
+                ) from exc2
+        delivery_mode = "reading" if mock_mode else "audio"
+        delivery_notice = (
+            "Local preview: this complete starter class is available in reading mode; no generated voice is being presented as real audio."
+            if mock_mode
+            else ""
+        )
+        if mock_mode:
+            beats = _reading_beats(script["beats"])
+        else:
+            try:
+                beats = synthesize_beats(script["beats"], out_dir, medium)
+            except Exception as exc:
+                logger.exception(
+                    "Lesson voice generation failed; serving the authored reading class: %s",
+                    type(exc).__name__,
+                )
+                beats = _reading_beats(script["beats"])
+                delivery_mode = "reading"
+                delivery_notice = "Audio is temporarily unavailable. The complete authored class is ready in reading mode, and your lesson position still saves."
+        if not beats:
+            raise LessonBuildError("No audible beats were produced for the lesson.")
+
+        total_seconds = round(beats[-1].start_second + beats[-1].duration_seconds, 3)
+        manifest = {
+            "schema": "learn-lesson-v1",
+            "lessonHash": key,
+            "topic": topic,
+            "lessonTitle": script.get("lesson_title", lesson_title),
+            "level": level,
+            "medium": medium,
+            "voice": voice,
+            "deliveryMode": delivery_mode,
+            "deliveryNotice": delivery_notice,
+            "isFallback": delivery_mode == "reading",
+            "totalSeconds": total_seconds,
+            "totalMinutes": round(total_seconds / 60, 2),
+            "summary": str(script.get("summary", "")).strip(),
+            "objectives": [
+                str(item).strip()
+                for item in (script.get("objectives") or [])
+                if str(item).strip()
+            ],
+            "beats": [beat.__dict__ for beat in beats],
+            "notes": [str(note) for note in (script.get("notes") or [])],
+            "flashcards": [
+                {"front": str(card.get("front", "")), "back": str(card.get("back", ""))}
+                for card in (script.get("flashcards") or [])
+                if card.get("front") and card.get("back")
+            ],
+        }
+        # Atomic-ish write: write temp then replace so readers never see half JSON.
+        tmp_path = manifest_path.with_suffix(".json.tmp")
+        tmp_path.write_text(
+            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        tmp_path.replace(manifest_path)
+        return manifest
 
 
 def _slugify(value: str) -> str:
@@ -379,7 +957,9 @@ def _slugify(value: str) -> str:
 if __name__ == "__main__":
     import argparse
 
-    parser = argparse.ArgumentParser(description="Build one Learn Anything lesson end-to-end.")
+    parser = argparse.ArgumentParser(
+        description="Build one Learn Anything lesson end-to-end."
+    )
     parser.add_argument("--topic", required=True)
     parser.add_argument("--lesson", required=True)
     parser.add_argument("--level", default="beginner")

app/services/learning_state_service.py

@@ -5,9 +5,12 @@ from typing import Iterable
 
 from fastapi import HTTPException, status
 from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.models.chat_session import ChatMessageRecord, ChatSession
+from app.models.class_session_progress import ClassSessionProgress
+from app.models.learn_anything_roadmap import LearnAnythingRoadmap
 from app.models.learning_state import (
     Chapter,
     DailyTask,
@@ -22,7 +25,9 @@ from app.models.learning_state import (
     TopicMastery,
     UsageEvent,
 )
+from app.models.study_profile import StudyProfile
 from app.services.adaptive_engine import repair_item_out
+from app.services.academic_state import build_academic_projection, current_mastery_state
 from app.schemas.learning_state import (
     AssessmentConsequenceResponse,
     AssessmentResultRequest,
@@ -102,7 +107,7 @@ def _task_maps(db: Session, user_id: str) -> tuple[dict[str, str], dict[str, str
     return subjects, chapters
 
 
-def _mastery_out(item: TopicMastery) -> TopicMasteryOut:
+def _mastery_out(item: TopicMastery, *, resolved_state: str | None = None) -> TopicMasteryOut:
     """Expose the mastery engine's evidence-derived fields alongside the row."""
     evidence = item.evidence or {}
     last_correct = evidence.get("last_correct_at")
@@ -127,7 +132,7 @@ def _mastery_out(item: TopicMastery) -> TopicMasteryOut:
         attempts_count=item.attempts_count,
         last_result=item.last_result,
         next_review_at=item.next_review_at,
-        state=item.last_result or "not_started",
+        state=resolved_state or item.last_result or "not_started",
         consecutive_success=int(evidence.get("consecutive_success", 0) or 0),
         error_categories={
             str(key): int(value)
@@ -138,6 +143,74 @@ def _mastery_out(item: TopicMastery) -> TopicMasteryOut:
     )
 
 
+def _mirror_onboarding_study_profile(
+    db: Session,
+    *,
+    user_id: str,
+    payload: LearningOnboardingRequest,
+    available_days: int,
+) -> StudyProfile:
+    """Keep the legacy tutor context in the onboarding transaction.
+
+    StudyChat, source routing and the onboarding gate still read
+    ``study_profiles`` while the adaptive planner owns ``student_profiles``.
+    Writing both rows before the same commit prevents a completed profile from
+    existing without the plan and first task that completion promises.
+    """
+
+    profile = db.scalar(
+        select(StudyProfile)
+        .where(StudyProfile.user_id == user_id)
+        .with_for_update()
+    )
+    if profile is None:
+        profile = StudyProfile(user_id=user_id)
+
+    preferences = dict(payload.preferences or {})
+    language = preferences.get("language")
+    learning_style = preferences.get("learning_style")
+    focus_areas = preferences.get("focus_areas")
+    daily_time = preferences.get("daily_time")
+    preferred_time = preferences.get("preferred_time")
+    if not isinstance(daily_time, str) or not daily_time.strip():
+        daily_time = (
+            f"{payload.daily_minutes // 60} hours"
+            if payload.daily_minutes >= 120 and payload.daily_minutes % 60 == 0
+            else f"{payload.daily_minutes} minutes"
+        )
+    if not isinstance(preferred_time, str) or not preferred_time.strip():
+        preferred_time = payload.preferred_time
+
+    extra = dict(profile.extra or {})
+    extra.update(
+        {
+            "schema_version": 2,
+            "subjects": list(payload.subjects),
+            "daily_time": daily_time,
+            "daily_minutes": payload.daily_minutes,
+            "preferred_time": preferred_time,
+            "focus_areas": focus_areas if isinstance(focus_areas, list) else [],
+            "language_preference": language if isinstance(language, str) else None,
+            "learning_style": learning_style if isinstance(learning_style, str) else None,
+            "available_study_days": available_days,
+            "first_plan_days": min(7, available_days),
+            "setup_completed_at": datetime.now(timezone.utc).isoformat(),
+        }
+    )
+
+    profile.board = payload.board
+    profile.grade = payload.class_level
+    profile.subject = payload.subjects[0]
+    profile.goal = payload.goal
+    profile.time_left = payload.exam_date.isoformat() if payload.exam_date else None
+    profile.language_preference = language if isinstance(language, str) else None
+    profile.source_mode = "onboarding"
+    profile.onboarding_completed = 1
+    profile.extra = extra
+    db.add(profile)
+    return profile
+
+
 def create_onboarding_plan(
     db: Session,
     *,
@@ -154,7 +227,7 @@ def create_onboarding_plan(
         available_days = (payload.exam_date - today).days
         if available_days <= 0:
             raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 detail={"code": "EXAM_DATE_NOT_FUTURE", "message": "Choose an exam date after today."},
             )
 
@@ -314,6 +387,12 @@ def create_onboarding_plan(
     profile.current_subject_id = first_task.subject_id
     profile.current_chapter_id = first_task.chapter_id
     profile.current_mission_id = first_task.mission_id
+    _mirror_onboarding_study_profile(
+        db,
+        user_id=user_id,
+        payload=payload,
+        available_days=available_days,
+    )
     db.add(
         UsageEvent(
             user_id=user_id,
@@ -376,6 +455,24 @@ def read_learning_state(db: Session, *, user_id: str) -> LearningStateSummary:
         .where(GeneratedResource.user_id == user_id)
         .order_by(GeneratedResource.created_at.desc())
     ).all()
+    class_sessions = db.scalars(
+        select(ClassSessionProgress)
+        .where(ClassSessionProgress.user_id == user_id)
+        .order_by(ClassSessionProgress.updated_at.desc())
+        .limit(50)
+    ).all()
+    roadmaps = db.scalars(
+        select(LearnAnythingRoadmap)
+        .where(LearnAnythingRoadmap.user_id == user_id)
+        .order_by(LearnAnythingRoadmap.updated_at.desc())
+        .limit(50)
+    ).all()
+    chat_sessions = db.scalars(
+        select(ChatSession)
+        .where(ChatSession.user_id == user_id)
+        .order_by(ChatSession.updated_at.desc())
+        .limit(50)
+    ).all()
     questions_asked = (
         db.scalar(
             select(func.count(ChatMessageRecord.id))
@@ -390,6 +487,31 @@ def read_learning_state(db: Session, *, user_id: str) -> LearningStateSummary:
     subject_map = {item.id: item.name for item in subjects}
     chapter_map = {item.id: item.title for item in chapters}
     chapter_by_id = {item.id: item for item in chapters}
+    resolved_now = datetime.now(timezone.utc)
+    academic_state, next_action = build_academic_projection(
+        profile=profile,
+        subjects=list(subjects),
+        chapters=list(chapters),
+        tasks=list(tasks),
+        lesson_progress=list(lesson_progress),
+        mastery=list(mastery),
+        repairs=list(repair_items),
+        attempts=list(attempts),
+        class_sessions=list(class_sessions),
+        roadmaps=list(roadmaps),
+        chat_sessions=list(chat_sessions),
+        now=resolved_now,
+    )
+    open_repair_keys = {item.concept_key for item in repair_items if item.status == "open"}
+    mastery_states = {
+        item.topic_key: current_mastery_state(
+            item,
+            now=resolved_now,
+            exam_date=profile.exam_date if profile else None,
+            has_open_repair=item.topic_key in open_repair_keys,
+        )
+        for item in mastery
+    }
     return LearningStateSummary(
         profile=LearningProfileOut.model_validate(profile, from_attributes=True) if profile else None,
         subjects=[LearningSubjectOut.model_validate(item, from_attributes=True) for item in subjects],
@@ -412,7 +534,10 @@ def read_learning_state(db: Session, *, user_id: str) -> LearningStateSummary:
             for item in lesson_progress
             if (chapter := chapter_by_id.get(item.chapter_id)) is not None
         ],
-        mastery=[_mastery_out(item) for item in mastery],
+        mastery=[
+            _mastery_out(item, resolved_state=mastery_states.get(item.topic_key))
+            for item in mastery
+        ],
         repair_items=[repair_item_out(item) for item in repair_items],
         quiz_attempts=[
             LearningQuizAttemptOut(
@@ -456,6 +581,8 @@ def read_learning_state(db: Session, *, user_id: str) -> LearningStateSummary:
         generated_resources=len(resources),
         generated_notes=sum(item.resource_type == "notes" for item in resources),
         questions_asked=int(questions_asked),
+        academic_state=academic_state,
+        next_action=next_action,
     )
 
 
@@ -582,7 +709,7 @@ def record_lesson_progress(
     )
     if chapter is None:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": "CHAPTER_NOT_IN_STUDY_PLAN",
                 "message": "This chapter is not in the student's saved study plan.",
@@ -601,7 +728,7 @@ def record_lesson_progress(
             raise HTTPException(status_code=404, detail="Study task not found.")
         if task.chapter_id and task.chapter_id != chapter.id:
             raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
                 detail={
                     "code": "TASK_CHAPTER_MISMATCH",
                     "message": "This task belongs to a different chapter.",
@@ -718,6 +845,57 @@ def record_lesson_progress(
     )
 
 
+def _replayed_assessment_response(
+    db: Session,
+    *,
+    user_id: str,
+    payload: AssessmentResultRequest,
+    attempt: QuizAttempt,
+) -> AssessmentConsequenceResponse:
+    mastery = db.scalar(
+        select(TopicMastery).where(
+            TopicMastery.user_id == user_id,
+            TopicMastery.topic_key == payload.topic_key,
+        )
+    )
+    score = mastery.score if mastery is not None else 0.0
+    tasks = db.scalars(
+        select(DailyTask).where(DailyTask.user_id == user_id)
+    ).all()
+    revision_task = next(
+        (
+            task
+            for task in tasks
+            if (task.task_metadata or {}).get("assessment_attempt_id") == attempt.id
+        ),
+        None,
+    )
+    next_task = revision_task or next(
+        (
+            task
+            for task in sorted(
+                tasks,
+                key=lambda item: (-item.priority, item.scheduled_for),
+            )
+            if task.status == "pending"
+        ),
+        None,
+    )
+    subject_map, chapter_map = _task_maps(db, user_id)
+    return AssessmentConsequenceResponse(
+        attempt_id=attempt.id,
+        mastery_before=round(score, 2),
+        mastery_after=round(score, 2),
+        revision_task=(
+            _task_out(revision_task, subject_map, chapter_map)
+            if revision_task
+            else None
+        ),
+        next_recommended_task_id=next_task.id if next_task else None,
+        message="This assessment was already saved. No duplicate mastery or revision change was created.",
+    )
+
+
 def record_assessment(
     db: Session,
     *,
@@ -726,6 +904,21 @@ def record_assessment(
 ) -> AssessmentConsequenceResponse:
     from app.services.mastery_engine import EvidenceEvent, MasterySnapshot, apply_evidence
 
+    if payload.client_attempt_id:
+        existing_attempt = db.scalar(
+            select(QuizAttempt).where(
+                QuizAttempt.user_id == user_id,
+                QuizAttempt.client_attempt_id == payload.client_attempt_id,
+            )
+        )
+        if existing_attempt is not None:
+            return _replayed_assessment_response(
+                db,
+                user_id=user_id,
+                payload=payload,
+                attempt=existing_attempt,
+            )
+
     observed = max(0.0, min(100.0, payload.score / payload.max_score * 100.0))
     now = datetime.now(timezone.utc)
     profile = db.scalar(select(StudentProfileState).where(StudentProfileState.user_id == user_id))
@@ -792,6 +985,7 @@ def record_assessment(
 
     attempt = QuizAttempt(
         user_id=user_id,
+        client_attempt_id=payload.client_attempt_id,
         quiz_id=payload.quiz_id,
         daily_task_id=payload.daily_task_id,
         subject_id=payload.subject_id,
@@ -805,7 +999,25 @@ def record_assessment(
         completed_at=now,
     )
     db.add(attempt)
-    db.flush()
+    try:
+        db.flush()
+    except IntegrityError:
+        db.rollback()
+        if payload.client_attempt_id:
+            existing_attempt = db.scalar(
+                select(QuizAttempt).where(
+                    QuizAttempt.user_id == user_id,
+                    QuizAttempt.client_attempt_id == payload.client_attempt_id,
+                )
+            )
+            if existing_attempt is not None:
+                return _replayed_assessment_response(
+                    db,
+                    user_id=user_id,
+                    payload=payload,
+                    attempt=existing_attempt,
+                )
+        raise
 
     if payload.daily_task_id:
         assessed_task = db.scalar(
@@ -910,13 +1122,45 @@ def adjust_plan_from_assistant(
     )
     if target is None:
         raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
             detail={
                 "code": "SUBJECT_NOT_SELECTED",
                 "message": f"{payload.target_subject} is not in your selected subjects.",
             },
         )
 
+    chapters = db.scalars(
+        select(Chapter).where(
+            Chapter.user_id == user_id,
+            Chapter.subject_id == target.id,
+            Chapter.curated.is_(True),
+            Chapter.status == "available",
+        )
+    ).all()
+    by_order = {str(item.order_index): item for item in chapters}
+    by_title = {item.title.casefold(): item for item in chapters}
+    resolved_chapters: list[tuple[str, Chapter]] = []
+    unavailable_chapters: list[str] = []
+    for label in payload.chapters:
+        known = by_order.get(label.strip()) or by_title.get(label.casefold())
+        if known is None:
+            unavailable_chapters.append(label)
+        else:
+            resolved_chapters.append((label, known))
+
+    if not resolved_chapters:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail={
+                "code": "CHAPTER_NOT_AVAILABLE",
+                "message": (
+                    f"DocDoe does not have a verified {target.name} class or source "
+                    f"for {', '.join(unavailable_chapters)} yet. Your existing plan is unchanged."
+                ),
+                "unavailable_chapters": unavailable_chapters,
+            },
+        )
+
     replaced = next(
         (
             item
@@ -926,30 +1170,10 @@ def adjust_plan_from_assistant(
         ),
         None,
     )
-    if replaced is not None:
-        replaced_tasks = db.scalars(
-            select(DailyTask).where(
-                DailyTask.user_id == user_id,
-                DailyTask.study_plan_id == active_plan.id,
-                DailyTask.subject_id == replaced.id,
-                DailyTask.status == "pending",
-                DailyTask.scheduled_for <= datetime.now(timezone.utc) + timedelta(days=2),
-            )
-        ).all()
-        for task in replaced_tasks:
-            task.status = "skipped"
-            task.task_metadata = {
-                **(task.task_metadata or {}),
-                "replaced_by_assistant": True,
-                "reason": payload.reason,
-            }
-
-    chapters = db.scalars(
-        select(Chapter).where(Chapter.user_id == user_id, Chapter.subject_id == target.id)
-    ).all()
-    by_order = {str(item.order_index): item for item in chapters}
-    by_title = {item.title.casefold(): item for item in chapters}
-    duration = min(60, max(20, active_plan.daily_minutes // max(1, len(payload.chapters))))
+    duration = min(
+        60,
+        max(20, active_plan.daily_minutes // max(1, len(resolved_chapters))),
+    )
     start = datetime.now(timezone.utc)
     existing_revisions = db.scalars(
         select(DailyTask).where(
@@ -961,23 +1185,14 @@ def adjust_plan_from_assistant(
         )
     ).all()
     created: list[DailyTask] = []
-    for index, label in enumerate(payload.chapters):
-        known = by_order.get(label.strip()) or by_title.get(label.casefold())
-        display = known.title if known else f"Chapter {label}"
+    for index, (label, known) in enumerate(resolved_chapters):
+        display = known.title
         # Sound Waves is the one fully curated beta chapter. A student asking
         # DocDoe for a chapter revision should therefore reopen its complete
         # chapter-test/revision mission in Tuition, not merely create a card
         # that the Tuition planner cannot resolve to a real lesson.
-        curated_mission_id = (
-            "M9"
-            if known and known.curated and known.catalog_id == "phy-p1-c1"
-            else None
-        )
-        href = (
-            "/tuition"
-            if known and known.curated
-            else f"/study-chat?prompt=Help%20me%20revise%20{payload.target_subject.replace(' ', '%20')}%20{display.replace(' ', '%20')}%20from%20my%20material"
-        )
+        curated_mission_id = "M9" if known.catalog_id == "phy-p1-c1" else None
+        href = "/tuition"
         existing = next(
             (
                 task
@@ -988,7 +1203,7 @@ def adjust_plan_from_assistant(
             None,
         )
         if existing is not None:
-            existing.chapter_id = known.id if known else None
+            existing.chapter_id = known.id
             existing.title = f"{payload.target_subject} revision: {display}"
             existing.scheduled_for = start + timedelta(minutes=index * duration)
             existing.duration_minutes = duration
@@ -1000,8 +1215,8 @@ def adjust_plan_from_assistant(
                 "assistant_requested": True,
                 "reason": payload.reason,
                 "student_chapter_label": label,
-                "verified_chapter": bool(known),
-                "chapter_catalog_id": known.catalog_id if known else None,
+                "verified_chapter": True,
+                "chapter_catalog_id": known.catalog_id,
             }
             created.append(existing)
             continue
@@ -1009,7 +1224,7 @@ def adjust_plan_from_assistant(
             user_id=user_id,
             study_plan_id=active_plan.id,
             subject_id=target.id,
-            chapter_id=known.id if known else None,
+            chapter_id=known.id,
             task_type="revision",
             title=f"{payload.target_subject} revision: {display}",
             status="pending",
@@ -1022,14 +1237,43 @@ def adjust_plan_from_assistant(
                 "assistant_requested": True,
                 "reason": payload.reason,
                 "student_chapter_label": label,
-                "verified_chapter": bool(known),
-                "chapter_catalog_id": known.catalog_id if known else None,
+                "verified_chapter": True,
+                "chapter_catalog_id": known.catalog_id,
             },
         )
         db.add(task)
         created.append(task)
     db.flush()
 
+    rescheduled_tasks = 0
+    if replaced is not None:
+        replaced_tasks = db.scalars(
+            select(DailyTask).where(
+                DailyTask.user_id == user_id,
+                DailyTask.study_plan_id == active_plan.id,
+                DailyTask.subject_id == replaced.id,
+                DailyTask.status == "pending",
+                DailyTask.scheduled_for <= start + timedelta(days=2),
+            ).order_by(DailyTask.scheduled_for, DailyTask.created_at)
+        ).all()
+        next_slot = created[-1].scheduled_for + timedelta(
+            minutes=created[-1].duration_minutes
+        )
+        for task in replaced_tasks:
+            metadata = task.task_metadata or {}
+            task.task_metadata = {
+                **metadata,
+                "rescheduled_by_assistant": True,
+                "assistant_original_scheduled_for": metadata.get(
+                    "assistant_original_scheduled_for",
+                    task.scheduled_for.isoformat(),
+                ),
+                "reason": payload.reason,
+            }
+            task.scheduled_for = next_slot
+            next_slot += timedelta(minutes=max(5, task.duration_minutes))
+            rescheduled_tasks += 1
+
     profile.current_subject_id = target.id
     profile.current_chapter_id = created[0].chapter_id
     profile.current_mission_id = created[0].mission_id
@@ -1048,7 +1292,23 @@ def adjust_plan_from_assistant(
     )
     db.commit()
     subject_map, chapter_map = _task_maps(db, user_id)
+    message = (
+        f"Plan updated. {target.name} now comes first with {len(created)} verified "
+        f"revision task{'s' if len(created) != 1 else ''}."
+    )
+    if rescheduled_tasks and replaced is not None:
+        message += (
+            f" {rescheduled_tasks} upcoming {replaced.name} "
+            f"task{'s were' if rescheduled_tasks != 1 else ' was'} rescheduled, not removed."
+        )
+    if unavailable_chapters:
+        message += (
+            f" I did not add {', '.join(unavailable_chapters)} because DocDoe has "
+            "no verified class or source for them yet."
+        )
     return PlanAdjustmentResponse(
         tasks=[_task_out(task, subject_map, chapter_map) for task in created],
-        message=f"Plan updated. {target.name} now comes first with {len(created)} revision task{'s' if len(created) != 1 else ''}.",
+        unavailable_chapters=unavailable_chapters,
+        rescheduled_tasks=rescheduled_tasks,
+        message=message,
     )

app/services/physics_curriculum_repository.py

@@ -12,7 +12,9 @@ from app.core.config import PROJECT_ROOT
 CURRICULUM_ROOT = PROJECT_ROOT / "data" / "curriculum" / "kerala-sslc" / "physics"
 MANIFEST_PATH = CURRICULUM_ROOT / "chapter-manifest.json"
 GENERATED_ROOT = CURRICULUM_ROOT / "generated"
-PRODUCTION_ROOT = PROJECT_ROOT / "outputs" / "video" / "physics"
+# The V2 Remotion renderer (scripts/video-engine/render-physics-v2-chapter.ts)
+# writes one render-manifest.json per chapter ID (not slug) under this root.
+PRODUCTION_ROOT = PROJECT_ROOT / "outputs" / "video" / "physics-course-2025-v2" / "renders"
 CHAPTER_VIDEO_SLUGS = {
     "phy-p1-c1": "sound-waves",
     "phy-p1-c2": "lenses",
@@ -103,63 +105,66 @@ def get_lesson_artifact(lesson_id: str, artifact: str) -> Any:
     return _read_json(path)
 
 
+def _v2_manifest_path(chapter_id: str) -> Path:
+    return PRODUCTION_ROOT / chapter_id / "final" / "render-manifest.json"
+
+
+def _v2_mp4_output(manifest: dict[str, Any]) -> Path | None:
+    """The V2 manifest lists deliverables (HLS master + compat MP4); pick the
+    flat MP4 for direct <video> playback, matching how HLS assets sit alongside it."""
+    outputs = (manifest.get("deliverables") or {}).get("outputs") or []
+    mp4s = [o for o in outputs if str(o).endswith(".mp4")]
+    if not mp4s:
+        return None
+    path = Path(str(mp4s[0]))
+    return path if path.is_absolute() else PROJECT_ROOT / path
+
+
 def get_chapter_video_status(chapter_id: str) -> dict[str, Any]:
     chapter = get_chapter(chapter_id)
-    slug = CHAPTER_VIDEO_SLUGS.get(chapter_id)
-    if slug is None:
+    if chapter_id not in CHAPTER_VIDEO_SLUGS:
         raise PhysicsCurriculumNotFound(f"No production-video mapping exists for chapter {chapter_id}")
-    manifest_path = PRODUCTION_ROOT / slug / "final" / "render-manifest.json"
+    manifest_path = _v2_manifest_path(chapter_id)
     if not manifest_path.is_file():
-        package_path = PRODUCTION_ROOT / slug / "full-chapter" / "render-manifest.json"
-        package = _read_json(package_path) if package_path.is_file() else None
         return {
             "chapterId": chapter_id,
             "title": chapter.get("title"),
-            "status": "package_ready" if package else "not_generated",
+            "status": "not_generated",
             "ready": False,
             "qaPassed": False,
-            "audioPresent": bool(package and package.get("audioPresent")),
-            "resolution": package.get("resolution") if package else None,
-            "durationSeconds": package.get("durationSeconds") if package else None,
+            "audioPresent": False,
+            "resolution": None,
+            "durationSeconds": None,
             "downloadUrl": None,
         }
     manifest = _read_json(manifest_path)
-    output_path = Path(str(manifest.get("outputFile") or ""))
-    if not output_path.is_absolute():
-        output_path = PROJECT_ROOT / output_path
-    ready = bool(manifest.get("qaPassed")) and manifest.get("status") == "ready" and output_path.is_file()
+    output_path = _v2_mp4_output(manifest)
+    qa_passed = bool(manifest.get("passed")) and not (manifest.get("blackFrames") or [])
+    ready = qa_passed and output_path is not None and output_path.is_file()
     return {
         "chapterId": chapter_id,
         "title": chapter.get("title"),
         "status": "ready" if ready else "qa_failed",
         "ready": ready,
-        "qaPassed": bool(manifest.get("qaPassed")),
-        "audioPresent": bool(manifest.get("audioPresent")),
-        "resolution": manifest.get("resolution"),
-        "durationSeconds": manifest.get("durationSeconds"),
+        "qaPassed": qa_passed,
+        "audioPresent": ready,  # V2 full-chapter MP4 always muxes English narration.
+        "resolution": "1920x1080" if ready else None,
+        "durationSeconds": manifest.get("visualDurationSeconds"),
         "downloadUrl": (
-            manifest.get("publicUrl")
-            or (
-                f"/video/physics-curriculum/chapters/{chapter_id}/video/file"
-                if ready and chapter_id == "phy-p1-c1"
-                else None
-            )
+            f"/video/physics-curriculum/chapters/{chapter_id}/video/file" if ready else None
         ),
     }
 
 
 def get_chapter_video_file(chapter_id: str) -> Path:
-    """Return the QA-passed free sample file without exposing arbitrary paths."""
+    """Return the QA-passed chapter video file without exposing arbitrary paths."""
     status_payload = get_chapter_video_status(chapter_id)
     if not status_payload.get("ready"):
         raise PhysicsCurriculumNotFound(f"Production video is unavailable for chapter {chapter_id}")
-    slug = CHAPTER_VIDEO_SLUGS.get(chapter_id)
-    if slug is None:
-        raise PhysicsCurriculumNotFound(f"No production-video mapping exists for chapter {chapter_id}")
-    manifest = _read_json(PRODUCTION_ROOT / slug / "final" / "render-manifest.json")
-    output_path = Path(str(manifest.get("outputFile") or ""))
-    if not output_path.is_absolute():
-        output_path = PROJECT_ROOT / output_path
+    manifest = _read_json(_v2_manifest_path(chapter_id))
+    output_path = _v2_mp4_output(manifest)
+    if output_path is None:
+        raise PhysicsCurriculumNotFound(f"Production video file is unavailable for chapter {chapter_id}")
     resolved = output_path.resolve()
     production_root = PRODUCTION_ROOT.resolve()
     if production_root not in resolved.parents or not resolved.is_file():

app/services/tts_provider.py

@@ -371,7 +371,7 @@ class AI4BharatIndicParlerTTSProvider(BaseTTSProvider):
                         prompt_attention_mask=prompt_inputs.attention_mask,
                         **generation_options,
                     )
-                    candidate = generation.detach().to("cpu", dtype=torch.float32).numpy().squeeze()
+                    candidate = generation.detach().to("cpu", dtype=torch.float32).numpy().reshape(-1)
                     with tempfile.NamedTemporaryFile(
                         suffix=".wav",
                         delete=False,

backend/.dockerignore

@@ -1,16 +0,0 @@
-.env
-.env.local
-.env.production
-.env.huggingface
-.venv
-__pycache__
-*.pyc
-.pytest_cache
-.ruff_cache
-*.db
-uploads/*
-!uploads/.gitkeep
-generated-video-jobs
-generated-videos
-uvicorn_log.txt
-*.log

backend/.env.example

@@ -1,178 +0,0 @@
-APP_NAME="AI Exam Success API"
-ENVIRONMENT="development"
-
-# PostgreSQL target for production/local DB work.
-# If DATABASE_URL is not set, the app falls back to a local SQLite file so the
-# mock backend can run immediately during early development.
-DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/exam_success"
-
-# Production recovery controls. Development does not require these.
-DATABASE_BACKUP_STRATEGY=""
-DATABASE_BACKUP_RETENTION_DAYS="14"
-DATABASE_RESTORE_TESTED_AT=""
-DATABASE_BACKUP_DIR=""
-
-CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:3000,http://localhost:3003,http://127.0.0.1:3003"
-UPLOAD_DIR="uploads"
-
-# AI provider settings.
-# Use AI_PROVIDER="mock" for local free development without an API key.
-# Use AI_PROVIDER="sarvam" with SARVAM_API_KEY for real AI outputs (recommended).
-# Use AI_PROVIDER="openrouter" with OPENROUTER_API_KEY for OpenRouter models.
-AI_PROVIDER="sarvam"
-SARVAM_API_KEY=""
-SARVAM_BASE_URL="https://api.sarvam.ai/v1"
-SARVAM_MODEL_MAIN="sarvam-30b"
-SARVAM_MODEL_HEAVY="sarvam-105b"
-SARVAM_MODEL_NOTES="sarvam-30b"
-SARVAM_MODEL_QUIZ="sarvam-30b"
-SARVAM_MODEL_FLASHCARDS="sarvam-30b"
-SARVAM_MODEL_EXAM_MODE="sarvam-105b"
-SARVAM_MODEL_PYQ_ANALYSIS="sarvam-105b"
-SARVAM_MODEL_VIDEO_SCRIPT="sarvam-105b"
-SARVAM_TIMEOUT_SECONDS="90"
-SARVAM_MAX_RETRIES="2"
-AI_FALLBACK_TO_MOCK="true"
-MOCK_AI_MODEL_NAME="mock-exam-tutor-v1"
-
-# Exa is used only when the student explicitly asks to search the web or asks
-# for current/latest information. Keep this backend-only; never use NEXT_PUBLIC_.
-EXA_API_KEY=""
-EXA_BASE_URL="https://api.exa.ai"
-EXA_SEARCH_TIMEOUT_SECONDS="15"
-EXA_SEARCH_MAX_RESULTS="6"
-
-# Legacy OpenRouter settings (set AI_PROVIDER="openrouter" to use)
-OPENROUTER_API_KEY=""
-OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
-OPENROUTER_MODEL_MAIN="deepseek/deepseek-v4-flash"
-OPENROUTER_MODEL_LLAMA="qwen/qwen3-next-80b-a3b-instruct"
-AI_MAX_RETRIES="2"
-AI_TIMEOUT_SECONDS="120"
-
-# Learn Anything lesson authoring (OpenAI-compatible chat via Groq).
-# Server-side only — never put this in NEXT_PUBLIC_*.
-GROQ_API_KEY=""
-
-# Scale knobs for ~1k concurrent students (raise in production Postgres deploys).
-DATABASE_POOL_SIZE="10"
-DATABASE_MAX_OVERFLOW="20"
-RATE_LIMIT_ENABLED="true"
-RATE_LIMIT_AI_REQUESTS_PER_DAY="80"
-
-# TTS provider settings.
-# AI4Bharat Indic Parler is the local Indian-English + Malayalam teacher voice.
-# Accept its free Hugging Face access terms once, then set HUGGINGFACE_API_KEY.
-# Use TTS_PROVIDER="mock" only for silent timing tests.
-TTS_PROVIDER="ai4bharat"
-TTS_DEFAULT_PROVIDER="ai4bharat"
-VIDEO_TTS_PROVIDER="ai4bharat"
-TTS_DEFAULT_VOICE="nila"
-TTS_OUTPUT_DIR="public/generated/audio"
-AI4BHARAT_TTS_MODEL="ai4bharat/indic-parler-tts"
-AI4BHARAT_TTS_SPEAKER="Anjali"
-AI4BHARAT_TTS_ENGLISH_SPEAKER="Mary"
-AI4BHARAT_TTS_DEVICE="auto"
-AI4BHARAT_TTS_PRECISION="float32"
-AUDIO_SCENE_TIMEOUT_SECONDS="45"
-AUDIO_TOTAL_TIMEOUT_SECONDS="300"
-AUDIO_MAX_RETRIES="2"
-AUDIO_MAX_CONCURRENCY="3"
-KOKORO_VOICE="af_heart"
-KOKORO_SPEED="0.95"
-INDIC_TTS_MODEL=""
-INDIC_TTS_LANGUAGE="ml"
-EDGE_TTS_VOICE_EN="en-US-JennyNeural"
-EDGE_TTS_VOICE_ML="ml-IN-SobhanaNeural"
-EDGE_TTS_RATE="+15%"
-ELEVENLABS_API_KEY=""
-ELEVENLABS_VOICE_ID=""
-AUDIO_NORMALIZE="true"
-
-# Local Remotion final render settings.
-GENERATED_VIDEO_JOBS_DIR="generated-video-jobs"
-GENERATED_VIDEO_OUTPUT_DIR="generated-videos"
-VIDEO_RENDER_TIMEOUT_SECONDS="420"
-VIDEO_MIN_OUTPUT_BYTES="4096"
-VIDEO_BETA_MAX_SCENES="5"
-VIDEO_BETA_MAX_DURATION_SECONDS="90"
-VIDEO_SCENE_TEXT_MAX_CHARS="700"
-VIDEO_MAX_CONCURRENT_RENDER_JOBS_PER_USER="1"
-VIDEO_ENFORCE_BETA_LIMITS_IN_DEVELOPMENT="false"
-
-# Storage provider settings.
-# Local is default and keeps current /generated/audio and /generated/videos URLs.
-# Use STORAGE_PROVIDER="r2" or "s3" with an S3-compatible bucket for cloud media.
-STORAGE_PROVIDER="local"
-STORAGE_BUCKET=""
-STORAGE_REGION=""
-STORAGE_ENDPOINT_URL=""
-STORAGE_ACCESS_KEY_ID=""
-STORAGE_SECRET_ACCESS_KEY=""
-STORAGE_PUBLIC_BASE_URL=""
-STORAGE_UPLOAD_PREFIX="uploads"
-STORAGE_AUDIO_PREFIX="generated-audio"
-STORAGE_VIDEO_PREFIX="generated-videos"
-
-# Auth settings.
-# Local dev defaults keep all current flows working as the demo student.
-AUTH_ENABLED="false"
-AUTH_PROVIDER="dev"
-FRONTEND_BASE_URL="http://127.0.0.1:3000"
-JWT_SECRET_KEY="change-this-before-real-users"
-JWT_ALGORITHM="HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES="10080"
-SUPABASE_URL=""
-SUPABASE_JWT_SECRET=""
-SUPABASE_ANON_KEY=""
-# Backend only. Required to fully remove Supabase Auth identities when
-# AUTH_PROVIDER="supabase". Never copy this into a NEXT_PUBLIC_* variable.
-SUPABASE_SERVICE_ROLE_KEY=""
-
-# Transactional account email. Required for password recovery when
-# AUTH_PROVIDER="jwt" in production.
-EMAIL_PROVIDER="disabled" # disabled | resend
-RESEND_API_KEY=""
-EMAIL_FROM="DocDoe <support@docdoe.in>"
-PASSWORD_RESET_TOKEN_MINUTES="30"
-PASSWORD_RESET_REQUEST_COOLDOWN_SECONDS="60"
-
-# Optional Google sign-in.
-# Create OAuth credentials in Google Cloud and add this redirect URI:
-# http://127.0.0.1:8000/auth/google/callback
-GOOGLE_CLIENT_ID=""
-GOOGLE_CLIENT_SECRET=""
-GOOGLE_OAUTH_REDIRECT_URI="http://127.0.0.1:8000/auth/google/callback"
-
-# Beta invite gate.
-# Set BETA_ACCESS_ENABLED=true and a strong BETA_INVITE_CODE to require an invite
-# code at signup. Leave BETA_ACCESS_ENABLED=false for open signup (dev/demo).
-BETA_ACCESS_ENABLED="false"
-BETA_INVITE_CODE=""
-
-# Per-user AI rate limiting.
-# Set RATE_LIMIT_ENABLED=true for beta to prevent a single user from exhausting
-# Sarvam credits. RATE_LIMIT_AI_REQUESTS_PER_DAY applies per user (JWT sub) or
-# per IP when no token is present. Resets every 24 hours from first request.
-RATE_LIMIT_ENABLED="false"
-RATE_LIMIT_AI_REQUESTS_PER_DAY="50"
-
-# --- Stripe Billing (Popular 299 + Premium 599 subscriptions) ---
-# Prefer a restricted TEST key (rk_test_...) with only the Checkout, Customers,
-# Subscriptions, and Billing Portal permissions this backend needs.
-# Create recurring test Prices for both active plans. Checkout stays disabled
-# until the key, webhook secret, and requested Price are all present.
-# Example:
-# STRIPE_PRICE_IDS=popular_299=price_sub_abc,premium_599=price_sub_def
-# For webhook testing: `stripe listen --forward-to http://127.0.0.1:8000/billing/webhook`
-#   (this prints a local whsec_... you paste here; in prod use the dashboard endpoint secret).
-STRIPE_SECRET_KEY=""
-STRIPE_WEBHOOK_SECRET=""
-STRIPE_PRICE_IDS=""
-
-# ── Observability + scaling (optional; A+ when set) ───────────────────────────
-# Shared rate-limit + prompt cache across replicas (e.g. Upstash free tier):
-REDIS_URL=
-# Error tracking — paste a Sentry project DSN to capture backend + frontend errors:
-SENTRY_DSN=
-SENTRY_TRACES_SAMPLE_RATE=0.1

backend/.env.huggingface.example

@@ -1,39 +0,0 @@
-ENVIRONMENT=production
-DATABASE_URL=
-CORS_ORIGINS=
-
-AUTH_ENABLED=true
-AUTH_PROVIDER=jwt
-JWT_SECRET_KEY=
-FRONTEND_BASE_URL=
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-GOOGLE_OAUTH_REDIRECT_URI=
-
-BETA_ACCESS_ENABLED=true
-BETA_INVITE_CODE=
-
-RATE_LIMIT_ENABLED=true
-RATE_LIMIT_AI_REQUESTS_PER_DAY=50
-
-AI_PROVIDER=sarvam
-SARVAM_API_KEY=
-AI_FALLBACK_TO_MOCK=false
-
-SARVAM_BASE_URL=https://api.sarvam.ai/v1
-SARVAM_MODEL_MAIN=sarvam-30b
-SARVAM_MODEL_HEAVY=sarvam-105b
-SARVAM_MODEL_NOTES=sarvam-30b
-SARVAM_MODEL_QUIZ=sarvam-30b
-SARVAM_MODEL_FLASHCARDS=sarvam-30b
-SARVAM_MODEL_EXAM_MODE=sarvam-105b
-SARVAM_MODEL_PYQ_ANALYSIS=sarvam-105b
-SARVAM_MODEL_VIDEO_SCRIPT=sarvam-105b
-SARVAM_TIMEOUT_SECONDS=90
-SARVAM_MAX_RETRIES=2
-
-STORAGE_PROVIDER=local
-UPLOAD_DIR=/app/uploads
-TTS_OUTPUT_DIR=/app/generated/audio
-GENERATED_VIDEO_JOBS_DIR=/app/generated-video-jobs
-GENERATED_VIDEO_OUTPUT_DIR=/app/generated-videos

backend/.env.production.example

@@ -1,148 +0,0 @@
-# DocDoe backend production template.
-# Copy into your hosting provider's secret/env dashboard. Do not commit real values.
-# Closed beta must use PostgreSQL for DATABASE_URL. Do not use SQLite for real students.
-
-ENVIRONMENT=production
-DATABASE_URL=
-CORS_ORIGINS=
-
-# ── Database backup and recovery ──────────────────────────────────
-# Use "managed" when Supabase or another provider owns the schedule and
-# retention. Use "pg_dump" for backend/scripts/database_backup.py.
-DATABASE_BACKUP_STRATEGY=managed
-DATABASE_BACKUP_RETENTION_DAYS=14
-# Set only after successfully restoring the latest backup into an isolated DB.
-DATABASE_RESTORE_TESTED_AT=
-# Required only for pg_dump strategy. This should be durable off-host storage.
-DATABASE_BACKUP_DIR=
-
-# ── Auth ──────────────────────────────────────────────────────────────────
-# AUTH_PROVIDER=supabase is the recommended production setup (managed auth + a
-# real Postgres for DATABASE_URL). AUTH_PROVIDER=jwt is the self-hosted option.
-# The tuition beta is login-less regardless (localStorage), so students still
-# work without an account; auth only gates the non-beta app + unlocks the real
-# LLM tuition brain for signed-in users.
-AUTH_ENABLED=true
-AUTH_PROVIDER=supabase
-FRONTEND_BASE_URL=
-
-# Supabase (when AUTH_PROVIDER=supabase). Dashboard → Project Settings.
-#   SUPABASE_URL           → Settings → API → Project URL
-#   SUPABASE_ANON_KEY      → Settings → API → Project API keys → anon public
-#   SUPABASE_JWT_SECRET    → Settings → API → JWT Settings → JWT Secret
-#   DATABASE_URL (above)   → Settings → Database → Connection string (URI),
-#                            use the pooled connstring for serverless hosts,
-#                            prefix with postgresql:// (not postgres://).
-SUPABASE_URL=
-SUPABASE_ANON_KEY=
-SUPABASE_JWT_SECRET=
-
-# JWT / Google OAuth (only when AUTH_PROVIDER=jwt) — leave blank for supabase.
-JWT_SECRET_KEY=
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-GOOGLE_OAUTH_REDIRECT_URI=
-
-BETA_ACCESS_ENABLED=true
-BETA_INVITE_CODE=
-
-RATE_LIMIT_ENABLED=true
-RATE_LIMIT_AI_REQUESTS_PER_DAY=50
-
-# ── Text AI provider (study-chat, notes, quizzes, video scripts) ─────────────
-# Your main app provider. Keep whatever you already use (e.g. sarvam) — the
-# tuition brain does NOT ride on this, it has its own provider below.
-AI_PROVIDER=sarvam
-AI_FALLBACK_TO_MOCK=false
-
-# Learn Anything lesson authoring (Groq). Server-only.
-GROQ_API_KEY=
-
-# Postgres pool for ~1k concurrent students (tune against your plan limits).
-DATABASE_POOL_SIZE=15
-DATABASE_MAX_OVERFLOW=30
-
-# ── Tuition brain provider (the real LLM that restates + plans today's class) ─
-# Runs on its own cheap text adapter so it never forces the app off AI_PROVIDER.
-# Must be a text adapter: cloudflare_workers_ai | openrouter | nvidia_nim.
-# Defaults to cloudflare_workers_ai even if unset.
-TUITION_BRAIN_PROVIDER=cloudflare_workers_ai
-
-# Cloudflare Workers AI (when AI_PROVIDER=cloudflare_workers_ai).
-#   CLOUDFLARE_ACCOUNT_ID → dash.cloudflare.com → account id (right sidebar / URL)
-#   CLOUDFLARE_API_TOKEN  → My Profile → API Tokens → Create Token →
-#                           template "Workers AI" (permission: Account · Workers AI · Read/Run)
-CLOUDFLARE_ACCOUNT_ID=
-CLOUDFLARE_API_TOKEN=
-# Optional model override (defaults to @cf/meta/llama-3.1-8b-instruct).
-CLOUDFLARE_WORKERS_AI_TEXT_MODEL=@cf/meta/llama-3.1-8b-instruct
-
-# Daily AI budget guard (USD). MUST be > 0 for the brain LLM to run — Cloudflare
-# Workers AI is near-free but its estimated cost is > 0, so a 0 budget denies it
-# and everything falls back to the deterministic brain. Start small.
-AI_ROUTER_DAILY_BUDGET_USD=5
-AI_ROUTER_ALLOW_FREE_PROVIDERS=true
-
-# Alternative paid provider (only when AI_PROVIDER=sarvam) — leave blank otherwise.
-SARVAM_API_KEY=
-
-# Study-video voice defaults to local AI4Bharat Indic Parler for Indian English
-# and Malayalam support without per-minute TTS costs.
-TTS_PROVIDER=ai4bharat
-TTS_DEFAULT_PROVIDER=ai4bharat
-VIDEO_TTS_PROVIDER=ai4bharat
-AI4BHARAT_TTS_MODEL=ai4bharat/indic-parler-tts
-AI4BHARAT_TTS_SPEAKER=Anjali
-AI4BHARAT_TTS_ENGLISH_SPEAKER=Mary
-AI4BHARAT_TTS_DEVICE=auto
-AI4BHARAT_TTS_PRECISION=float32
-AUDIO_SCENE_TIMEOUT_SECONDS=45
-AUDIO_TOTAL_TIMEOUT_SECONDS=300
-AUDIO_MAX_RETRIES=2
-AUDIO_MAX_CONCURRENCY=3
-VIDEO_RENDER_TIMEOUT_SECONDS=420
-VIDEO_MIN_OUTPUT_BYTES=4096
-VIDEO_BETA_MAX_SCENES=5
-VIDEO_BETA_MAX_DURATION_SECONDS=90
-VIDEO_SCENE_TEXT_MAX_CHARS=700
-VIDEO_MAX_CONCURRENT_RENDER_JOBS_PER_USER=1
-
-# ── Cloud storage (REQUIRED in production for video URLs to be playable) ─────
-# Current production target: Cloudinary (free tier, generous transformations).
-# Alternatives: cloudflare R2, AWS S3 (see backend/STORAGE_SETUP.md).
-STORAGE_PROVIDER=cloudinary
-
-# Cloudinary credentials (when STORAGE_PROVIDER=cloudinary).
-# Find under: cloudinary.com Dashboard → Settings → API Keys.
-# All three required.
-CLOUDINARY_CLOUD_NAME=
-CLOUDINARY_API_KEY=
-CLOUDINARY_API_SECRET=
-
-# R2 / S3 (when STORAGE_PROVIDER=r2 or s3) — leave blank if using Cloudinary.
-STORAGE_BUCKET=
-STORAGE_ENDPOINT_URL=
-STORAGE_ACCESS_KEY_ID=
-STORAGE_SECRET_ACCESS_KEY=
-STORAGE_PUBLIC_BASE_URL=
-STORAGE_REGION=
-
-# Deployment target tag (used by preflight to relax assumptions).
-# Values: huggingface | railway | flyio | docker | local
-DEPLOY_TARGET=huggingface
-
-# ── Stripe Billing (MANDATORY for paid plans in production) ───────────────────
-# Prefer a restricted LIVE key (rk_live_...) scoped to Checkout, Customers,
-# Subscriptions, and Billing Portal. Store it only in the backend secret store.
-# Create recurring LIVE Prices for the two plans currently shown to students.
-# Checkout refuses to take payment unless the webhook secret and selected Price
-# are both configured.
-# STRIPE_PRICE_IDS=popular_299=price_...,premium_599=price_...
-# WEBHOOK: In Stripe dashboard create endpoint https://yourdomain.com/billing/webhook
-#   select checkout.session.completed, customer.subscription.created/updated/deleted,
-#   invoice.paid, and invoice.payment_failed. Copy the signing secret here.
-# IMPORTANT: After setting, restart/redeploy backend so pydantic-settings picks up.
-# Never commit keys. Rotate secrets if leaked. See backend/app/routes/billing.py for impl.
-STRIPE_SECRET_KEY=
-STRIPE_WEBHOOK_SECRET=
-STRIPE_PRICE_IDS=

backend/.gitignore

@@ -1,17 +0,0 @@
-.env
-.env.local
-.env.production
-.env.huggingface
-.venv/
-__pycache__/
-*.py[cod]
-.pytest_cache/
-.ruff_cache/
-*.db
-uploads/*
-!uploads/.gitkeep
-generated-video-jobs/
-generated-videos/
-generated/
-uvicorn_log.txt
-*.log