deploy: backend from c237ff2

main.py

@@ -6774,6 +6774,7 @@ async def commit_student_account_import(
             }
             if not existing_profile_doc:
                 profile_payload["createdAt"] = FIRESTORE_SERVER_TIMESTAMP
+                profile_payload["guideOfferPending"] = True
 
             client.collection("users").document(target_uid).set(profile_payload, merge=True)
 
@@ -7691,6 +7692,7 @@ async def create_student_account_for_teacher(
             "atRiskSubjects": [],
             "hasTakenDiagnostic": False,
             "adviserTeacherId": adviser_teacher_id,
+            "guideOfferPending": True,
             "createdAt": FIRESTORE_SERVER_TIMESTAMP,
             "updatedAt": FIRESTORE_SERVER_TIMESTAMP,
         }
@@ -11757,16 +11759,17 @@ def _validate_quiz_questions(
 
         if options:
             options = [to_plain_text(o, single_line=True, strip_option_label=True) for o in options]
+        correct_answer = to_plain_text(q.get("correctAnswer", ""), single_line=True, strip_option_label=True)
         validated.append(QuizQuestion(
             questionType=question_type,
             question=clean_llm_text(q.get("question", "")),
-            correctAnswer=to_plain_text(q.get("correctAnswer", ""), single_line=True, strip_option_label=True),
+            correctAnswer=correct_answer,
             options=options,
             bloomLevel=bloom_level,
             difficulty=difficulty,
             topic=question_topic,
             points=q.get("points", points_map.get(difficulty, 3)),
-            explanation=clean_llm_text(q.get("explanation", "")) or "No explanation provided.",
+            explanation=clean_llm_text(q.get("explanation", "")) or f"Correct answer: {correct_answer}",
             provenance=question_provenance,
         ))
 

routes/practice.py

@@ -250,7 +250,7 @@ async def generate_practice(request: Request, body: PracticeGenerateRequest):
                 question=q.get("question", ""),
                 options=q.get("options", ["", "", "", ""]),
                 correct_index=correct_idx,
-                explanation=q.get("explanation", "No explanation available."),
+                explanation=q.get("explanation") or "",
                 competency=q.get("competency", body.competency),
                 difficulty=q.get("difficulty", body.difficulty),
                 bloomsLevel=q.get("bloomsLevel", "Apply"),

services/user_provisioning_service.py

@@ -269,6 +269,8 @@ class UserProvisioningService:
 
         profile_payload = self._build_profile_payload(user_input, role_lower, normalized_status)
         profile_payload["createdAt"] = self._firestore_server_timestamp
+        # New accounts are asked once whether to play the first-use guide; the app clears this flag.
+        profile_payload["guideOfferPending"] = True
 
         try:
             firestore_client.collection("users").document(uid).set(profile_payload, merge=True)

tests/test_api.py

@@ -2237,6 +2237,29 @@ class TestStudentAccountProvisioningImport:
         provisioned_profile = next(iter(users_store.values()))
         assert provisioned_profile.get("role") == "student"
         assert provisioned_profile.get("forcePasswordChange") is True
+        assert provisioned_profile.get("guideOfferPending") is True
+
+    def test_teacher_created_student_account_is_offered_the_first_use_guide(self):
+        firestore = _ProvisionFirestoreModule({"users": {}, "managedStudents": {}, "classSectionOwnership": {}, "accessAuditLogs": {}})
+
+        with patch.object(main_module, "firebase_firestore", firestore), patch.object(main_module, "_firebase_ready", True), patch.object(main_module.firebase_auth, "verify_id_token", return_value={
+            "uid": "teacher-uid",
+            "email": "teacher@example.com",
+            "role": "teacher",
+        }), patch.object(main_module.firebase_auth, "get_user_by_email", side_effect=Exception("user not found")), patch.object(main_module.firebase_auth, "create_user", return_value=type("AuthUser", (), {"uid": "auth-created-1"})()):
+            response = client.post(
+                "/api/teacher/create-student-account",
+                json={
+                    "name": "Ana Cruz",
+                    "email": "ana@student.com",
+                    "temporary_password": "Secure123!",
+                    "section": "STEM-A",
+                    "adviser_teacher_id": "teacher-uid",
+                },
+            )
+
+        assert response.status_code == 200
+        assert firestore.client().store["users"]["auth-created-1"]["guideOfferPending"] is True
 
     @staticmethod
     def _move_firestore() -> _ProvisionFirestoreModule:

tests/test_practice_router.py

@@ -97,6 +97,29 @@ class TestPracticeGenerate:
         assert "generated_at" in data
         assert data["questions"][0]["id"] == "q1"
 
+    @patch("routes.practice._get_firestore", return_value=None)
+    @patch("routes.practice._call_claude")
+    def test_missing_explanation_is_left_empty_instead_of_a_shared_sentence(self, mock_call, _mock_db):
+        """An omitted or null explanation must not become the same canned text on every question."""
+        options = ["3", "4", "5", "6"]
+        mock_call.return_value = json.dumps({
+            "questions": [
+                {"id": "q1", "question": "2+2?", "options": options, "correct_index": 1, "explanation": "Add 2 and 2."},
+                {"id": "q2", "question": "3+3?", "options": options, "correct_index": 3},
+                {"id": "q3", "question": "4+4?", "options": options, "correct_index": 3, "explanation": None},
+            ]
+        })
+
+        user_id = "test_user_123"
+        response = client.post(
+            "/api/practice/generate",
+            json={"userId": user_id, "subject": "Algebra", "competency": "Linear Equations", "difficulty": "Practice", "count": 3},
+            headers=_auth_header(user_id),
+        )
+
+        assert response.status_code == 200
+        assert [q["explanation"] for q in response.json()["questions"]] == ["Add 2 and 2.", "", ""]
+
     def test_generate_rejects_mismatched_user(self):
         """Request with mismatched auth userId should return 403."""
         response = client.post(

tests/test_quiz_generation_regression.py

@@ -4,7 +4,7 @@ import pytest
 from fastapi.testclient import TestClient
 from pydantic import ValidationError
 
-from main import app
+from main import _validate_quiz_questions, app
 from routes.quiz_generation_routes import QuizGenerationRequest, _build_quiz_generation_prompt
 
 pytestmark = pytest.mark.usefixtures("isolated_mock_student_auth")
@@ -49,3 +49,17 @@ def test_quiz_type_fallback_prompt_handles_empty_type_list():
         "Algebra", "Math", None, 1, [], "easy", "", grade_level="Grade 11"
     )
     assert "multiple_choice" in prompt
+
+
+def test_missing_quiz_explanation_falls_back_to_the_questions_own_answer():
+    questions = [
+        {"questionType": "identification", "question": "Define slope", "correctAnswer": "rise over run", "explanation": "Slope is rise over run."},
+        {"questionType": "identification", "question": "Define intercept", "correctAnswer": "where the line crosses an axis"},
+        {"questionType": "identification", "question": "Define vertex", "correctAnswer": "the turning point", "explanation": "  "},
+    ]
+    validated = _validate_quiz_questions(questions, [])
+    assert [q.explanation for q in validated] == [
+        "Slope is rise over run.",
+        "Correct answer: where the line crosses an axis",
+        "Correct answer: the turning point",
+    ]

tests/test_user_provisioning_service.py

@@ -1,3 +1,4 @@
+import pytest
 from services.user_provisioning_service import AdminCreateUserInput, UserProvisioningService
 from unittest.mock import MagicMock
 
@@ -28,3 +29,38 @@ def test_teacher_profile_does_not_require_or_assign_a_section():
     assert profile["role"] == "teacher"
     assert "section" not in profile
     assert "classSectionId" not in profile
+
+
+@pytest.mark.parametrize("role", ["Student", "Teacher", "Admin"])
+def test_created_accounts_are_offered_the_first_use_guide(role):
+    auth = MagicMock()
+    auth.get_user_by_email.side_effect = Exception("No user record found")
+    auth.create_user.return_value = MagicMock(uid="new-uid")
+    firestore_module = MagicMock()
+    users = firestore_module.client.return_value.collection.return_value
+    users.where.return_value.limit.return_value.stream.return_value = []
+    provisioning = UserProvisioningService(
+        firebase_auth_module=auth,
+        firestore_module=firestore_module,
+        firestore_server_timestamp="server-timestamp",
+        email_service=MagicMock(),
+    )
+
+    uid = provisioning.create_user(
+        AdminCreateUserInput(
+            name="New User",
+            email="new.user@example.com",
+            password="Secure123!",
+            confirm_password="Secure123!",
+            role=role,
+            status="Active",
+            grade="Grade 11",
+            section="Section A",
+            lrn="123456789012",
+        )
+    )
+
+    assert uid == "new-uid"
+    users.document.assert_called_with("new-uid")
+    (profile,) = users.document.return_value.set.call_args.args
+    assert profile["guideOfferPending"] is True