diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f52227f
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,17 @@
+# חובה - הטוקן מ-@BotFather בטלגרם
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF_your_token_here
+
+# אופציונלי - מפעיל את /ask (שאלות חופשיות) ובדיקת תרגילים חכמה
+ANTHROPIC_API_KEY=sk-ant-...
+CLAUDE_MODEL=claude-opus-5
+
+# אופציונלי - ברנדר מוגדר אוטומטית מ-RENDER_EXTERNAL_URL
+# WEBHOOK_URL=https://my-bot.onrender.com
+WEBHOOK_SECRET=change-me-to-a-random-string
+PORT=10000
+
+# היכן נשמר מסד הנתונים (ברנדר: /var/data אם חיברת Disk)
+DATA_DIR=./data
+
+# הרצת קוד של משתמשים (/run) - כבוי כברירת מחדל, ראה README
+ENABLE_CODE_RUNNER=false
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..20a02cc
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.db
+data/
+.pytest_cache/
+.DS_Store
diff --git a/Procfile b/Procfile
new file mode 100644
index 0000000..629b83a
--- /dev/null
+++ b/Procfile
@@ -0,0 +1 @@
+web: python main.py
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c820d5b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,126 @@
+# 🐍 בוט טלגרם שמלמד Python
+
+בוט טלגרם בעברית שמלמד Python מאפס: 12 שיעורים קצרים, ובכל אחד הסבר, דוגמת קוד,
+תרגיל מעשי וחידון. הבוט זוכר את ההתקדמות של כל תלמיד, ומוכן לפריסה ב-Render.
+
+## מה יש בבוט
+
+| יכולת | תיאור |
+|---|---|
+| 📚 12 שיעורים | מ-`print` ועד פונקציות וטיפול בשגיאות, עם ניווט בכפתורים |
+| ✏️ תרגילים | התלמיד שולח קוד בהודעה, והבוט בודק ומחזיר משוב ממוקד |
+| 🧠 חידונים | שאלות רב-ברירה עם הסבר לכל תשובה, גם כשטועים |
+| 📊 מעקב התקדמות | שיעורים שהושלמו, אחוזי הצלחה בחידונים ורצף למידה יומי |
+| 🤖 מורה חכם (אופציונלי) | `/ask` לשאלות חופשיות ובדיקת תרגילים חכמה, מבוסס Claude |
+| ▶️ הרצת קוד (אופציונלי) | הרצת קוד התלמיד בתת-תהליך מוגבל והשוואת הפלט |
+
+הבוט עובד במלואו גם בלי מפתח Claude - כל החומר, התרגילים והחידונים מקומיים.
+המפתח רק מוסיף את היכולת לענות על שאלות חופשיות.
+
+## הפקודות
+
+```
+/start      התחלה ותפריט ראשי
+/lessons    תפריט כל השיעורים
+/lesson 5   מעבר ישיר לשיעור מספר 5
+/next       השיעור הבא שטרם הושלם
+/practice   התרגיל של השיעור הנוכחי
+/quiz       החידון של השיעור הנוכחי
+/ask ...    שאלה חופשית על Python
+/run ...    הרצת קוד (אם הופעלה)
+/progress   ההתקדמות שלי
+/cancel     ביטול תרגיל פתוח
+/reset      איפוס ההתקדמות
+```
+
+## פריסה ב-Render
+
+### 1. יוצרים בוט בטלגרם
+
+פותחים צ'אט עם [@BotFather](https://t.me/BotFather), שולחים `/newbot`, בוחרים שם
+ושם משתמש, ומעתיקים את הטוקן שמתקבל.
+
+### 2. פורסים את הקוד
+
+הדרך הקצרה - **Blueprint**: ב-Render בוחרים `New` → `Blueprint`, מצביעים על
+הריפו הזה, ו-`render.yaml` מגדיר את השירות אוטומטית. נותר רק למלא את
+`TELEGRAM_BOT_TOKEN`.
+
+הדרך הידנית - **Web Service**:
+
+| הגדרה | ערך |
+|---|---|
+| Environment | Python 3 |
+| Build Command | `pip install -r requirements.txt` |
+| Start Command | `python main.py` |
+
+### 3. מגדירים משתני סביבה
+
+| משתנה | חובה | תיאור |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | ✅ | הטוקן מ-BotFather |
+| `ANTHROPIC_API_KEY` | ❌ | מפעיל את `/ask` ובדיקת תרגילים חכמה |
+| `CLAUDE_MODEL` | ❌ | ברירת מחדל: `claude-opus-5` |
+| `WEBHOOK_SECRET` | ❌ | מחרוזת אקראית שמאמתת שהעדכון הגיע מטלגרם |
+| `DATA_DIR` | ❌ | תיקיית מסד הנתונים, ברירת מחדל `./data` |
+| `ENABLE_CODE_RUNNER` | ❌ | `true` מפעיל את `/run` ובדיקת פלט |
+| `WEBHOOK_URL` | ❌ | רק אם אתם לא ב-Render; שם זה נגזר מ-`RENDER_EXTERNAL_URL` |
+
+אין צורך לרשום את ה-webhook ידנית: הבוט מזהה את כתובת השירות שרנדר מזריקה
+ב-`RENDER_EXTERNAL_URL`, נרשם מול טלגרם בעלייה ומאזין על `PORT`. בלי
+`WEBHOOK_URL` הוא עובר אוטומטית ל-polling, מה שנוח לפיתוח מקומי.
+
+### שתי מגבלות של התוכנית החינמית
+
+1. **השירות נרדם** אחרי כ-15 דקות חוסר פעילות. ההודעה הראשונה אחרי שינה
+   תתקבל באיחור של עשרות שניות, כי היא זו שמעירה את השירות.
+2. **אין דיסק קבוע**, ולכן מסד הנתונים נמחק בכל דיפלוי. לשמירת התקדמות לאורך זמן:
+   מוסיפים Disk בתוכנית בתשלום, ממפים אותו ל-`/var/data` ומגדירים
+   `DATA_DIR=/var/data`.
+
+## הרצה מקומית
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+cp .env.example .env     # ואז ממלאים את TELEGRAM_BOT_TOKEN
+python main.py           # עולה במצב polling
+```
+
+## בדיקות
+
+```bash
+pip install pytest pytest-asyncio
+python -m pytest
+```
+
+הבדיקות מאמתות שכל דוגמאות הקוד והפתרונות מתקמפלים, שהפתרונות מייצרים את הפלט
+המצופה, שכל הודעה שהבוט שולח היא HTML תקין שטלגרם מקבל, ושכל כפתור מוביל לפעולה
+קיימת.
+
+## מבנה הפרויקט
+
+```
+main.py               נקודת כניסה: בונה את האפליקציה ובוחר webhook או polling
+app/config.py         קריאת משתני סביבה
+app/content/lessons.py תוכנית הלימודים: שיעורים, תרגילים וחידונים
+app/handlers.py       פקודות, כפתורים וזרימת השיחה
+app/keyboards.py      מקלדות inline
+app/storage.py        התקדמות בשמירת SQLite
+app/ai.py             מורה חכם מבוסס Claude (אופציונלי)
+app/runner.py         הרצת קוד בתת-תהליך מוגבל (אופציונלי)
+render.yaml           Blueprint לפריסה ברנדר
+```
+
+## להוסיף שיעור משלכם
+
+מוסיפים `Lesson` לרשימת `LESSONS` בקובץ `app/content/lessons.py`. התפריט, הניווט,
+החידון ומעקב ההתקדמות מתעדכנים מעצמם. `python -m pytest` יאמת שהשיעור החדש תקין.
+
+## הערה על `/run`
+
+הפעלת `ENABLE_CODE_RUNNER=true` מריצה קוד שנשלח מטלגרם על השרת שלכם. הבוט מגביל
+זמן CPU, זיכרון, גודל פלט וכתיבה לקבצים, וחוסם ייבוא מודולים רגישים - אבל אלו
+שכבות הגנה, לא בידוד מלא. להפעלה בסביבה ציבורית מומלץ להריץ בקונטיינר ייעודי
+ללא גישת רשת. כשהתכונה כבויה, תרגילים נבדקים בלי להריץ קוד כלל.
diff --git a/app/__init__.py b/app/__init__.py
new file mode 100644
index 0000000..78c08ba
--- /dev/null
+++ b/app/__init__.py
@@ -0,0 +1,3 @@
+"""בוט טלגרם שמלמד Python."""
+
+__all__ = ["config", "storage", "ai", "handlers", "keyboards", "runner"]
diff --git a/app/ai.py b/app/ai.py
new file mode 100644
index 0000000..5a8dcd7
--- /dev/null
+++ b/app/ai.py
@@ -0,0 +1,189 @@
+"""שכבת AI אופציונלית מעל Claude.
+
+אם ANTHROPIC_API_KEY מוגדר, הבוט יודע לענות על שאלות חופשיות (/ask)
+ולבדוק תרגילים חופשיים. בלי מפתח הבוט ממשיך לעבוד עם בדיקות היוריסטיות.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+TUTOR_SYSTEM = (
+    "אתה מורה סבלני ל-Python שמלמד מתחילים גמורים דרך בוט טלגרם. "
+    "ענה תמיד בעברית, בגובה העיניים, בלי ז'רגון מיותר.\n"
+    "כללים:\n"
+    "- תשובה קצרה: עד 120 מילים, ואם צריך דוגמה - עד 12 שורות קוד.\n"
+    "- קוד תמיד בתוך בלוק ```python ... ``` ובלי הסברים בתוך הקוד.\n"
+    "- אם השאלה אינה קשורה לתכנות, לפייתון או ללמידה שלהם, אמור זאת "
+    "במשפט אחד והצע לשאול שאלה על Python.\n"
+    "- אל תיתן קוד מסוכן (מחיקת קבצים, גישה לרשת, סיסמאות) גם אם מבקשים.\n"
+    "- עדיף להסביר את העיקרון מאשר לפתור עבור התלמיד את כל שיעורי הבית."
+)
+
+GRADER_SYSTEM = (
+    "אתה בודק תרגילי Python של מתחילים. אתה מקבל את משימת התרגיל, פתרון "
+    "לדוגמה ואת הקוד של התלמיד.\n"
+    "החזר אך ורק JSON תקין במבנה:\n"
+    '{"passed": true/false, "feedback": "משפט או שניים בעברית"}\n'
+    "כללי שיפוט:\n"
+    "- קבל כל פתרון נכון, גם אם הוא שונה מהפתרון לדוגמה.\n"
+    "- אל תוריד נקודות על שמות משתנים, רווחים או סדר שורות שאינו משנה.\n"
+    "- אם יש שגיאה - הסבר במשפט אחד מה חסר, בלי לתת את הפתרון המלא.\n"
+    "- אם הקוד אינו קשור למשימה, passed=false."
+)
+
+_CODE_FENCE = re.compile(r"```[a-zA-Z]*\n?(.*?)```", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class Grade:
+    passed: bool
+    feedback: str
+
+
+class AIUnavailable(RuntimeError):
+    """נזרק כשאין מפתח API או כשהספרייה לא מותקנת."""
+
+
+class Tutor:
+    """עטיפה דקה מעל Anthropic SDK, עם ניוון עדין כשאין מפתח."""
+
+    def __init__(self, api_key: str | None, model: str = "claude-opus-5") -> None:
+        self._model = model
+        self._client = None
+        # נסיגה חד-פעמית: אם החשבון לא תומך ב-beta fallbacks, עוברים לנתיב הרגיל
+        self._server_fallbacks = True
+
+        if not api_key:
+            return
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError:  # pragma: no cover
+            logger.warning("חבילת anthropic אינה מותקנת - תכונות ה-AI כבויות")
+            return
+        self._client = AsyncAnthropic(api_key=api_key, max_retries=2, timeout=60.0)
+
+    @property
+    def enabled(self) -> bool:
+        return self._client is not None
+
+    # ------------------------------------------------------------------ core
+    async def _create(
+        self, *, system: str, user_content: str, max_tokens: int, effort: str
+    ):
+        if self._client is None:
+            raise AIUnavailable("תכונות ה-AI אינן פעילות")
+
+        messages = [{"role": "user", "content": user_content}]
+
+        if self._server_fallbacks:
+            try:
+                return await self._client.beta.messages.create(
+                    model=self._model,
+                    max_tokens=max_tokens,
+                    system=system,
+                    messages=messages,
+                    output_config={"effort": effort},
+                    betas=["server-side-fallback-2026-07-01"],
+                    fallbacks="default",
+                )
+            except Exception as exc:  # noqa: BLE001 - נסיגה מכוונת
+                if not _is_unsupported_parameter(exc):
+                    raise
+                logger.info("server-side fallbacks לא זמינים, עובר לנתיב הרגיל: %s", exc)
+                self._server_fallbacks = False
+
+        return await self._client.messages.create(
+            model=self._model,
+            max_tokens=max_tokens,
+            system=system,
+            messages=messages,
+            output_config={"effort": effort},
+        )
+
+    @staticmethod
+    def _text_of(response) -> str:
+        parts = [
+            block.text
+            for block in response.content
+            if getattr(block, "type", None) == "text"
+        ]
+        return "\n".join(part for part in parts if part).strip()
+
+    # ------------------------------------------------------------------- ask
+    async def answer(self, question: str, lesson_title: str | None = None) -> str:
+        """עונה על שאלה חופשית של תלמיד."""
+        context = f"התלמיד נמצא כרגע בשיעור: {lesson_title}\n\n" if lesson_title else ""
+        response = await self._create(
+            system=TUTOR_SYSTEM,
+            user_content=f"{context}שאלת התלמיד:\n{question}",
+            max_tokens=1500,
+            effort="low",
+        )
+
+        if response.stop_reason == "refusal":
+            return "לא אוכל לענות על השאלה הזו. אפשר לשאול אותי משהו על Python 🙂"
+
+        text = self._text_of(response)
+        return text or "לא הצלחתי לנסח תשובה. נסו לשאול בניסוח אחר."
+
+    # ----------------------------------------------------------------- grade
+    async def grade(self, task: str, solution: str, submission: str) -> Grade:
+        """בודק פתרון של תלמיד מול משימת התרגיל."""
+        user_content = (
+            f"<task>\n{task}\n</task>\n\n"
+            f"<reference_solution>\n{solution}\n</reference_solution>\n\n"
+            f"<student_code>\n{submission}\n</student_code>"
+        )
+        response = await self._create(
+            system=GRADER_SYSTEM,
+            user_content=user_content,
+            max_tokens=800,
+            effort="low",
+        )
+
+        if response.stop_reason == "refusal":
+            raise AIUnavailable("הבקשה נדחתה")
+
+        return _parse_grade(self._text_of(response))
+
+
+def _is_unsupported_parameter(exc: Exception) -> bool:
+    """מזהה שגיאות 'הפרמטר לא נתמך' כדי לנסות שוב בלי beta."""
+    if isinstance(exc, TypeError):
+        return True
+    status = getattr(exc, "status_code", None)
+    if status != 400:
+        return False
+    message = str(exc).lower()
+    return any(
+        token in message
+        for token in ("fallback", "beta", "unexpected", "not supported", "unknown")
+    )
+
+
+def _parse_grade(text: str) -> Grade:
+    """מחלץ JSON מתשובת המודל, גם אם הוא עטוף בבלוק קוד."""
+    candidate = text.strip()
+    fence = _CODE_FENCE.search(candidate)
+    if fence:
+        candidate = fence.group(1).strip()
+    else:
+        start, end = candidate.find("{"), candidate.rfind("}")
+        if start != -1 and end > start:
+            candidate = candidate[start : end + 1]
+
+    try:
+        data = json.loads(candidate)
+        return Grade(
+            passed=bool(data["passed"]),
+            feedback=str(data.get("feedback", "")).strip() or "נבדק.",
+        )
+    except (json.JSONDecodeError, KeyError, TypeError) as exc:
+        logger.warning("תשובת בדיקה לא תקינה: %s", exc)
+        raise AIUnavailable("תשובת הבדיקה לא הייתה בפורמט צפוי") from exc
diff --git a/app/config.py b/app/config.py
new file mode 100644
index 0000000..7eb5c8d
--- /dev/null
+++ b/app/config.py
@@ -0,0 +1,72 @@
+"""טעינת הגדרות מסביבת ההרצה (משתני סביבה / קובץ .env)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+try:  # python-dotenv הוא נוחות לפיתוח מקומי בלבד
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:  # pragma: no cover - בסביבת הרצה אמיתית המשתנים כבר מוגדרים
+    pass
+
+
+def _as_bool(value: str | None, default: bool = False) -> bool:
+    if value is None or value == "":
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+@dataclass(frozen=True)
+class Config:
+    telegram_token: str
+    anthropic_api_key: str | None
+    claude_model: str
+    webhook_url: str | None
+    webhook_secret: str | None
+    port: int
+    data_dir: Path
+    enable_code_runner: bool
+
+    @property
+    def db_path(self) -> Path:
+        return self.data_dir / "pythonbot.sqlite3"
+
+    @property
+    def use_webhook(self) -> bool:
+        """ברנדר מריצים webhook; מקומית בלי WEBHOOK_URL עוברים ל-polling."""
+        return bool(self.webhook_url)
+
+    @property
+    def ai_enabled(self) -> bool:
+        return bool(self.anthropic_api_key)
+
+
+def load_config() -> Config:
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "").strip()
+    if not token:
+        raise RuntimeError(
+            "חסר TELEGRAM_BOT_TOKEN. צרו בוט אצל @BotFather והגדירו את הטוקן "
+            "כמשתנה סביבה (ראו .env.example)."
+        )
+
+    # ברנדר מזריק את RENDER_EXTERNAL_URL אוטומטית לשירותי Web.
+    webhook_url = (
+        os.environ.get("WEBHOOK_URL") or os.environ.get("RENDER_EXTERNAL_URL") or ""
+    ).strip().rstrip("/")
+
+    data_dir = Path(os.environ.get("DATA_DIR", "./data")).expanduser()
+
+    return Config(
+        telegram_token=token,
+        anthropic_api_key=(os.environ.get("ANTHROPIC_API_KEY") or "").strip() or None,
+        claude_model=os.environ.get("CLAUDE_MODEL", "claude-opus-5").strip(),
+        webhook_url=webhook_url or None,
+        webhook_secret=(os.environ.get("WEBHOOK_SECRET") or "").strip() or None,
+        port=int(os.environ.get("PORT", "10000")),
+        data_dir=data_dir,
+        enable_code_runner=_as_bool(os.environ.get("ENABLE_CODE_RUNNER"), False),
+    )
diff --git a/app/content/__init__.py b/app/content/__init__.py
new file mode 100644
index 0000000..31e085c
--- /dev/null
+++ b/app/content/__init__.py
@@ -0,0 +1,23 @@
+"""תוכן הקורס: שיעורים, תרגילים וחידונים."""
+
+from app.content.lessons import (
+    Exercise,
+    Lesson,
+    Quiz,
+    LESSONS,
+    LESSONS_BY_ID,
+    find_lesson,
+    lesson_index,
+    next_lesson,
+)
+
+__all__ = [
+    "Exercise",
+    "Lesson",
+    "Quiz",
+    "LESSONS",
+    "LESSONS_BY_ID",
+    "find_lesson",
+    "lesson_index",
+    "next_lesson",
+]
diff --git a/app/content/lessons.py b/app/content/lessons.py
new file mode 100644
index 0000000..7e0c497
--- /dev/null
+++ b/app/content/lessons.py
@@ -0,0 +1,857 @@
+"""תוכנית הלימודים של הבוט.
+
+כל שיעור מורכב מהסבר, דוגמת קוד, תרגיל אחד וכמה שאלות חידון.
+הטקסט מיועד ל-Telegram במצב parse_mode=HTML, ולכן מותר בו רק
+<b>, <i>, <u>, <code>, <pre>, <a>.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Quiz:
+    question: str
+    options: tuple[str, ...]
+    answer: int  # אינדקס התשובה הנכונה בתוך options
+    explanation: str
+
+
+@dataclass(frozen=True)
+class Exercise:
+    prompt: str
+    hint: str
+    solution: str
+    #  מילות מפתח שחייבות להופיע בפתרון כשאין בדיקה חכמה זמינה
+    required: tuple[str, ...] = ()
+    #  הפלט המדויק שהקוד אמור להדפיס, אם יש כזה (משמש את /run)
+    expected_output: str | None = None
+
+
+@dataclass(frozen=True)
+class Lesson:
+    id: str
+    title: str
+    emoji: str
+    goal: str
+    body: str
+    example: str
+    exercise: Exercise
+    quizzes: tuple[Quiz, ...] = field(default_factory=tuple)
+
+    @property
+    def display_title(self) -> str:
+        return f"{self.emoji} {self.title}"
+
+
+LESSONS: tuple[Lesson, ...] = (
+    Lesson(
+        id="01-hello",
+        title="שלום Python",
+        emoji="👋",
+        goal="להריץ את שורת הקוד הראשונה ולהדפיס טקסט למסך.",
+        body=(
+            "Python היא שפת תכנות שנקראת כמעט כמו אנגלית. כל תוכנית היא רשימת "
+            "הוראות שהמחשב מבצע לפי הסדר, שורה אחרי שורה.\n\n"
+            "הפקודה הראשונה שכדאי להכיר היא <code>print()</code> - היא מדפיסה "
+            "למסך כל מה שנכתוב בתוך הסוגריים.\n\n"
+            "טקסט בפייתון נקרא <b>מחרוזת</b> (string) ועוטפים אותו במרכאות, "
+            "בודדות או כפולות - שתי הצורות זהות.\n\n"
+            "שורה שמתחילה ב-<code>#</code> היא <b>הערה</b>: פייתון מתעלמת ממנה "
+            "לגמרי, והיא נועדה להסביר את הקוד לבני אדם."
+        ),
+        example=(
+            '# התוכנית הראשונה שלי\n'
+            'print("שלום עולם!")\n'
+            'print("אני לומד Python")\n'
+            '\n'
+            '# אפשר גם לחשב בתוך print\n'
+            'print(7 * 6)\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "כתבו תוכנית שמדפיסה בדיוק שתי שורות:\n"
+                "בשורה הראשונה את השם שלכם, ובשנייה את המספר 2026."
+            ),
+            hint="צריך שתי פקודות print נפרדות. מספרים נכתבים בלי מרכאות.",
+            solution='print("דנה")\nprint(2026)\n',
+            required=("print",),
+        ),
+        quizzes=(
+            Quiz(
+                question="מה תדפיס השורה <code>print(\"3 + 4\")</code>?",
+                options=("7", "3 + 4", "שגיאה", '"3 + 4"'),
+                answer=1,
+                explanation=(
+                    "מה שבתוך המרכאות הוא טקסט, ולכן הוא מודפס כמו שהוא. "
+                    "בלי המרכאות - <code>print(3 + 4)</code> - היה מודפס 7."
+                ),
+            ),
+            Quiz(
+                question="איזו שורה היא הערה שפייתון מתעלמת ממנה?",
+                options=("// הערה", "# הערה", "<!-- הערה -->", "-- הערה"),
+                answer=1,
+                explanation="בפייתון הערה בשורה אחת מתחילה בסולמית <code>#</code>.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="02-variables",
+        title="משתנים",
+        emoji="📦",
+        goal="לשמור ערכים בזיכרון ולהשתמש בהם שוב.",
+        body=(
+            "<b>משתנה</b> הוא שם שמצביע על ערך. יוצרים אותו עם סימן שווה אחד:\n"
+            "<code>age = 25</code> קורא לערך 25 בשם <code>age</code>.\n\n"
+            "סימן <code>=</code> בפייתון אינו 'שווה' מתמטי אלא <b>השמה</b>: קח את "
+            "הערך מימין ושמור אותו בשם שמשמאל.\n\n"
+            "כללים לשמות משתנים:\n"
+            "• אותיות, ספרות וקו תחתון בלבד, ולא מתחילים בספרה\n"
+            "• יש הבדל בין אותיות גדולות לקטנות: <code>name</code> ו-<code>Name</code> "
+            "הם שני משתנים שונים\n"
+            "• בחרו שם שמסביר את התוכן: <code>price</code> עדיף על <code>p</code>\n\n"
+            "ערך של משתנה אפשר לשנות בכל רגע - הערך החדש פשוט מחליף את הישן."
+        ),
+        example=(
+            'name = "דנה"\n'
+            'age = 25\n'
+            'height = 1.68\n'
+            '\n'
+            'print(name, age, height)\n'
+            '\n'
+            '# שינוי ערך קיים\n'
+            'age = age + 1\n'
+            'print("בשנה הבאה:", age)\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "צרו משתנה <code>price</code> עם הערך 100 ומשתנה "
+                "<code>discount</code> עם הערך 25.\n"
+                "חשבו את המחיר אחרי ההנחה לתוך משתנה <code>final</code> והדפיסו אותו."
+            ),
+            hint="המחיר הסופי הוא price פחות discount. השתמשו ב-print(final).",
+            solution="price = 100\ndiscount = 25\nfinal = price - discount\nprint(final)\n",
+            required=("price", "discount", "final", "print"),
+            expected_output="75",
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה יודפס?\n<pre>x = 5\nx = 8\nprint(x)</pre>"
+                ),
+                options=("5", "8", "13", "שגיאה"),
+                answer=1,
+                explanation="ההשמה השנייה דורסת את הראשונה, ולכן נשאר הערך 8.",
+            ),
+            Quiz(
+                question="איזה שם משתנה אינו חוקי בפייתון?",
+                options=("total_price", "price2", "2price", "_price"),
+                answer=2,
+                explanation="שם משתנה לא יכול להתחיל בספרה.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="03-types",
+        title="טיפוסי נתונים",
+        emoji="🔢",
+        goal="להכיר מספרים, טקסט ובוליאנים - ולדעת להמיר ביניהם.",
+        body=(
+            "לכל ערך בפייתון יש <b>טיפוס</b>. ארבעת הבסיסיים:\n"
+            "• <code>int</code> - מספר שלם, למשל 42\n"
+            "• <code>float</code> - מספר עשרוני, למשל 3.14\n"
+            "• <code>str</code> - מחרוזת טקסט, למשל \"שלום\"\n"
+            "• <code>bool</code> - אמת או שקר: <code>True</code> / <code>False</code>\n\n"
+            "הפונקציה <code>type(x)</code> מגלה את הטיפוס של כל ערך.\n\n"
+            "הטיפוס קובע מה מותר לעשות: <code>2 + 3</code> נותן 5, אבל "
+            "<code>\"2\" + \"3\"</code> נותן <code>\"23\"</code> כי חיבור מחרוזות "
+            "מדביק אותן. <code>\"2\" + 3</code> פשוט יזרוק שגיאה.\n\n"
+            "לכן ממירים בין טיפוסים: <code>int(\"5\")</code>, "
+            "<code>float(\"2.5\")</code>, <code>str(10)</code>."
+        ),
+        example=(
+            'count = 10\n'
+            'price = 19.90\n'
+            'name = "ספר"\n'
+            'in_stock = True\n'
+            '\n'
+            'print(type(count), type(price), type(name), type(in_stock))\n'
+            '\n'
+            '# חיבור מחרוזות מול חיבור מספרים\n'
+            'print("2" + "3")\n'
+            'print(2 + 3)\n'
+            '\n'
+            '# המרה\n'
+            'print(int("2") + 3)\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "נתונה המחרוזת <code>year = \"1991\"</code>.\n"
+                "המירו אותה למספר שלם, הוסיפו 30 והדפיסו את התוצאה."
+            ),
+            hint="השתמשו ב-int(year) כדי לקבל מספר.",
+            solution='year = "1991"\nresult = int(year) + 30\nprint(result)\n',
+            required=("int(", "print"),
+            expected_output="2021",
+        ),
+        quizzes=(
+            Quiz(
+                question="מה הטיפוס של הערך <code>3.0</code>?",
+                options=("int", "float", "str", "bool"),
+                answer=1,
+                explanation="נקודה עשרונית הופכת את המספר ל-float, גם כשהשארית אפס.",
+            ),
+            Quiz(
+                question="מה התוצאה של <code>\"5\" * 3</code>?",
+                options=("15", "555", "שגיאה", "53"),
+                answer=1,
+                explanation=(
+                    "כפל מחרוזת במספר שלם משכפל אותה, ולכן מתקבל "
+                    "<code>\"555\"</code>."
+                ),
+            ),
+        ),
+    ),
+    Lesson(
+        id="04-input",
+        title="קלט מהמשתמש",
+        emoji="⌨️",
+        goal="לקרוא נתונים מהמשתמש ולהמיר אותם לטיפוס הנכון.",
+        body=(
+            "הפונקציה <code>input()</code> עוצרת את התוכנית, מחכה שהמשתמש יקליד "
+            "שורה, ומחזירה אותה.\n\n"
+            "נקודה קריטית: <code>input()</code> מחזירה <b>תמיד מחרוזת</b>, גם כשהמשתמש "
+            "הקליד מספר. אם צריך לחשב - חייבים להמיר:\n"
+            "<code>age = int(input(\"גיל: \"))</code>\n\n"
+            "אפשר לשלב ערכים בתוך טקסט בעזרת <b>f-string</b>: מוסיפים "
+            "<code>f</code> לפני המרכאות וכותבים שמות משתנים בתוך סוגריים מסולסלים.\n"
+            "<code>print(f\"שלום {name}, אתה בן {age}\")</code>"
+        ),
+        example=(
+            'name = input("איך קוראים לך? ")\n'
+            'age = int(input("בן כמה אתה? "))\n'
+            '\n'
+            'print(f"נעים להכיר, {name}!")\n'
+            'print(f"בעוד 10 שנים תהיה בן {age + 10}")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "קראו מהמשתמש שני מספרים שלמים והדפיסו את הסכום שלהם "
+                "במשפט מלא, למשל: <code>הסכום הוא 12</code>."
+            ),
+            hint="שני input נפרדים, כל אחד עטוף ב-int(), ואז f-string.",
+            solution=(
+                'a = int(input("מספר ראשון: "))\n'
+                'b = int(input("מספר שני: "))\n'
+                'print(f"הסכום הוא {a + b}")\n'
+            ),
+            required=("input", "int(", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "המשתמש הקליד 5. מה יקרה?\n"
+                    "<pre>x = input()\nprint(x + 1)</pre>"
+                ),
+                options=("יודפס 6", "יודפס 51", "תיזרק שגיאה", "יודפס 5"),
+                answer=2,
+                explanation=(
+                    "input מחזירה מחרוזת, וחיבור של מחרוזת עם מספר זורק "
+                    "<code>TypeError</code>. הפתרון: <code>int(x) + 1</code>."
+                ),
+            ),
+            Quiz(
+                question="מה מדפיס <code>print(f\"{2 + 2}\")</code>?",
+                options=("2 + 2", "4", "{2 + 2}", "שגיאה"),
+                answer=1,
+                explanation="בתוך f-string הביטוי בסוגריים המסולסלים מחושב לפני ההדפסה.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="05-conditions",
+        title="תנאים",
+        emoji="🔀",
+        goal="לגרום לתוכנית להחליט בין מסלולים שונים.",
+        body=(
+            "<code>if</code> מריץ בלוק קוד רק כשהתנאי נכון. אם לא - אפשר לתת חלופה "
+            "עם <code>elif</code> (תנאי נוסף) ו-<code>else</code> (כל השאר).\n\n"
+            "אופרטורים להשוואה: <code>==</code> שווה, <code>!=</code> שונה, "
+            "<code>&gt;</code>, <code>&lt;</code>, <code>&gt;=</code>, <code>&lt;=</code>.\n"
+            "שימו לב: <code>=</code> זו השמה, <code>==</code> זו השוואה.\n\n"
+            "מחברים תנאים עם <code>and</code>, <code>or</code> ו-<code>not</code>.\n\n"
+            "<b>הזחה קובעת מבנה</b>: בפייתון אין סוגריים מסולסלים. מה ששייך ל-if "
+            "מוזח פנימה בארבעה רווחים, ומי שלא מוזח כבר לא חלק מהתנאי."
+        ),
+        example=(
+            'grade = 85\n'
+            '\n'
+            'if grade >= 90:\n'
+            '    print("מצוין")\n'
+            'elif grade >= 70:\n'
+            '    print("טוב")\n'
+            'else:\n'
+            '    print("צריך לתרגל")\n'
+            '\n'
+            '# שילוב תנאים\n'
+            'age = 20\n'
+            'has_ticket = True\n'
+            'if age >= 18 and has_ticket:\n'
+            '    print("אפשר להיכנס")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "כתבו תוכנית שמקבלת מספר לתוך משתנה <code>n</code> ומדפיסה "
+                "<code>חיובי</code>, <code>שלילי</code> או <code>אפס</code> בהתאם לערכו."
+            ),
+            hint="שלושה מקרים: if n > 0, elif n < 0, else.",
+            solution=(
+                'n = 5\n'
+                'if n > 0:\n'
+                '    print("חיובי")\n'
+                'elif n < 0:\n'
+                '    print("שלילי")\n'
+                'else:\n'
+                '    print("אפס")\n'
+            ),
+            required=("if", "elif", "else", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה יודפס?\n"
+                    "<pre>x = 10\nif x > 5:\n    print(\"א\")\nelif x > 8:\n"
+                    "    print(\"ב\")</pre>"
+                ),
+                options=("א", "ב", "א ואז ב", "כלום"),
+                answer=0,
+                explanation=(
+                    "ברגע שתנאי אחד מתקיים, הפייתון מדלגת על כל ה-elif שאחריו - "
+                    "גם אם גם הם נכונים."
+                ),
+            ),
+            Quiz(
+                question="מה בודקים עם <code>==</code>?",
+                options=(
+                    "מכניסים ערך למשתנה",
+                    "בודקים אם שני ערכים שווים",
+                    "בודקים אם ערכים שונים",
+                    "מחברים מספרים",
+                ),
+                answer=1,
+                explanation="<code>=</code> משים ערך, <code>==</code> משווה בין ערכים.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="06-loops-while",
+        title="לולאת while",
+        emoji="🔄",
+        goal="לחזור על פעולה כל עוד תנאי מתקיים.",
+        body=(
+            "<code>while</code> מריצה בלוק שוב ושוב כל עוד התנאי נכון. היא מתאימה "
+            "כשלא יודעים מראש כמה חזרות יידרשו.\n\n"
+            "שלושת החלקים שחייבים להיות:\n"
+            "1. אתחול משתנה לפני הלולאה\n"
+            "2. תנאי עצירה\n"
+            "3. עדכון המשתנה בתוך הלולאה - בלעדיו נקבל <b>לולאה אינסופית</b>\n\n"
+            "שתי פקודות שימושיות בתוך לולאה:\n"
+            "• <code>break</code> - יציאה מיידית מהלולאה\n"
+            "• <code>continue</code> - דילוג לסיבוב הבא"
+        ),
+        example=(
+            'count = 1\n'
+            'while count <= 5:\n'
+            '    print(count)\n'
+            '    count = count + 1\n'
+            '\n'
+            'print("סיימתי")\n'
+            '\n'
+            '# עצירה מוקדמת\n'
+            'n = 0\n'
+            'while True:\n'
+            '    n += 1\n'
+            '    if n == 3:\n'
+            '        break\n'
+            'print(n)\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "השתמשו בלולאת <code>while</code> כדי לחשב את סכום המספרים "
+                "מ-1 עד 10 ולהדפיס אותו."
+            ),
+            hint="התחילו עם total = 0 ו-i = 1, והעלו את i בכל סיבוב עד שהוא עובר 10.",
+            solution=(
+                'total = 0\n'
+                'i = 1\n'
+                'while i <= 10:\n'
+                '    total += i\n'
+                '    i += 1\n'
+                'print(total)\n'
+            ),
+            required=("while", "print"),
+            expected_output="55",
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה הבעיה בקוד?\n<pre>i = 0\nwhile i < 3:\n    print(i)</pre>"
+                ),
+                options=(
+                    "שגיאת תחביר",
+                    "לולאה אינסופית - i לא מתעדכן",
+                    "הלולאה לא תרוץ בכלל",
+                    "אין בעיה",
+                ),
+                answer=1,
+                explanation="בלי <code>i += 1</code> התנאי נשאר נכון לנצח.",
+            ),
+            Quiz(
+                question="מה עושה <code>continue</code> בתוך לולאה?",
+                options=(
+                    "עוצרת את הלולאה",
+                    "מדלגת לסיבוב הבא",
+                    "מאתחלת את הלולאה מחדש",
+                    "מסיימת את התוכנית",
+                ),
+                answer=1,
+                explanation=(
+                    "<code>continue</code> מדלגת על שארית הסיבוב הנוכחי וממשיכה "
+                    "לסיבוב הבא, בניגוד ל-<code>break</code> שיוצאת מהלולאה."
+                ),
+            ),
+        ),
+    ),
+    Lesson(
+        id="07-loops-for",
+        title="לולאת for ו-range",
+        emoji="🎯",
+        goal="לעבור על רצף ערכים בצורה קצרה וברורה.",
+        body=(
+            "<code>for</code> עוברת על כל פריט באוסף, אחד אחרי השני, בלי לנהל "
+            "מונה ידנית.\n\n"
+            "<code>range()</code> מייצרת רצף מספרים:\n"
+            "• <code>range(5)</code> - 0,1,2,3,4\n"
+            "• <code>range(2, 6)</code> - 2,3,4,5\n"
+            "• <code>range(0, 10, 2)</code> - 0,2,4,6,8\n\n"
+            "הערך העליון תמיד <b>לא כלול</b> - זו טעות נפוצה למתחילים.\n\n"
+            "אפשר לעבור גם על מחרוזת (אות אחר אות) ועל רשימה (איבר אחר איבר)."
+        ),
+        example=(
+            'for i in range(5):\n'
+            '    print(i)\n'
+            '\n'
+            'for letter in "פייתון":\n'
+            '    print(letter)\n'
+            '\n'
+            '# לוח הכפל של 7\n'
+            'for i in range(1, 11):\n'
+            '    print(f"7 x {i} = {7 * i}")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "הדפיסו בעזרת <code>for</code> את כל המספרים הזוגיים בין 1 ל-20 "
+                "(כולל 20), כל אחד בשורה נפרדת."
+            ),
+            hint="range(2, 21, 2) מייצר בדיוק את המספרים הזוגיים.",
+            solution="for i in range(2, 21, 2):\n    print(i)\n",
+            required=("for", "range", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question="כמה פעמים ירוץ הבלוק של <code>for i in range(3, 8):</code>?",
+                options=("3", "5", "8", "4"),
+                answer=1,
+                explanation="הרצף הוא 3,4,5,6,7 - חמישה ערכים; 8 אינו כלול.",
+            ),
+            Quiz(
+                question="מה מדפיס <code>print(list(range(0, 10, 3)))</code>?",
+                options=(
+                    "[0, 3, 6, 9]",
+                    "[0, 3, 6, 9, 12]",
+                    "[3, 6, 9]",
+                    "[0, 1, 2, ..., 9]",
+                ),
+                answer=0,
+                explanation="הקפיצה היא 3, והרצף נעצר לפני 10.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="08-lists",
+        title="רשימות",
+        emoji="📋",
+        goal="לאחסן אוסף ערכים במשתנה אחד ולעבד אותו.",
+        body=(
+            "<b>רשימה</b> (list) מחזיקה כמה ערכים בסדר קבוע, בתוך סוגריים מרובעים:\n"
+            "<code>fruits = [\"תפוח\", \"בננה\", \"תמר\"]</code>\n\n"
+            "ניגשים לאיבר לפי <b>אינדקס</b>, שמתחיל מ-0:\n"
+            "<code>fruits[0]</code> הוא הראשון, <code>fruits[-1]</code> הוא האחרון.\n\n"
+            "פעולות שימושיות:\n"
+            "• <code>len(fruits)</code> - כמה איברים יש\n"
+            "• <code>fruits.append(\"ענב\")</code> - הוספה בסוף\n"
+            "• <code>fruits.remove(\"בננה\")</code> - הסרה לפי ערך\n"
+            "• <code>fruits.sort()</code> - מיון\n"
+            "• <code>\"תמר\" in fruits</code> - בדיקת הימצאות\n\n"
+            "פרוסות (slicing) מחזירות חלק מהרשימה: <code>fruits[1:3]</code>."
+        ),
+        example=(
+            'grades = [90, 75, 88, 100, 62]\n'
+            '\n'
+            'print(grades[0], grades[-1])\n'
+            'print(len(grades))\n'
+            'print(sum(grades) / len(grades))\n'
+            '\n'
+            'grades.append(95)\n'
+            'grades.sort()\n'
+            'print(grades)\n'
+            '\n'
+            'for g in grades:\n'
+            '    if g >= 90:\n'
+            '        print(f"ציון גבוה: {g}")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "נתונה הרשימה <code>nums = [4, 17, 8, 23, 42, 15]</code>.\n"
+                "הדפיסו את הגדול ביותר ואת הממוצע."
+            ),
+            hint="max(nums) מחזיר את הגדול, ו-sum(nums) / len(nums) את הממוצע.",
+            solution=(
+                'nums = [4, 17, 8, 23, 42, 15]\n'
+                'print(max(nums))\n'
+                'print(sum(nums) / len(nums))\n'
+            ),
+            required=("nums", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה יודפס?\n<pre>items = [10, 20, 30]\nprint(items[1])</pre>"
+                ),
+                options=("10", "20", "30", "שגיאה"),
+                answer=1,
+                explanation="אינדקס 0 הוא 10, אינדקס 1 הוא 20 - הספירה מתחילה מאפס.",
+            ),
+            Quiz(
+                question="איזו פעולה מוסיפה איבר לסוף רשימה?",
+                options=("add()", "append()", "insert_end()", "push()"),
+                answer=1,
+                explanation="<code>append()</code> מוסיפה איבר יחיד בסוף הרשימה.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="09-strings",
+        title="עבודה עם מחרוזות",
+        emoji="✂️",
+        goal="לחתוך, לחפש ולעצב טקסט.",
+        body=(
+            "מחרוזת היא רצף תווים, ואפשר לגשת אליה כמו לרשימה: "
+            "<code>text[0]</code>, <code>text[-1]</code>, <code>text[2:5]</code>.\n\n"
+            "מתודות נפוצות:\n"
+            "• <code>.upper()</code> / <code>.lower()</code> - שינוי רישיות\n"
+            "• <code>.strip()</code> - מסיר רווחים מההתחלה ומהסוף\n"
+            "• <code>.split(\",\")</code> - מפצל לרשימה\n"
+            "• <code>.replace(\"א\", \"ב\")</code> - החלפה\n"
+            "• <code>.startswith()</code> / <code>.endswith()</code>\n"
+            "• <code>\",\".join(items)</code> - מחבר רשימה למחרוזת\n\n"
+            "מחרוזות הן <b>בלתי ניתנות לשינוי</b>: כל מתודה מחזירה מחרוזת חדשה "
+            "ולא משנה את המקורית. צריך לשמור את התוצאה במשתנה."
+        ),
+        example=(
+            'text = "  Hello Python World  "\n'
+            '\n'
+            'clean = text.strip()\n'
+            'print(clean)\n'
+            'print(clean.upper())\n'
+            'print(clean.split(" "))\n'
+            'print(len(clean))\n'
+            '\n'
+            'email = "dana@example.com"\n'
+            'user = email.split("@")[0]\n'
+            'print(user)\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "נתונה המחרוזת <code>s = \"python is fun\"</code>.\n"
+                "הדפיסו אותה באותיות גדולות, ואז הדפיסו כמה מילים יש בה."
+            ),
+            hint="upper() לאותיות גדולות, ו-len(s.split()) לספירת המילים.",
+            solution=(
+                's = "python is fun"\n'
+                'print(s.upper())\n'
+                'print(len(s.split()))\n'
+            ),
+            required=("upper", "split", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה יודפס?\n<pre>s = \"abc\"\ns.upper()\nprint(s)</pre>"
+                ),
+                options=("ABC", "abc", "שגיאה", "None"),
+                answer=1,
+                explanation=(
+                    "מחרוזות אינן ניתנות לשינוי. <code>upper()</code> מחזירה מחרוזת "
+                    "חדשה, ובלי השמה התוצאה נזרקת."
+                ),
+            ),
+            Quiz(
+                question="מה מחזיר <code>\"a,b,c\".split(\",\")</code>?",
+                options=(
+                    '"abc"',
+                    "['a', 'b', 'c']",
+                    "['a,b,c']",
+                    "שגיאה",
+                ),
+                answer=1,
+                explanation="<code>split</code> מפצל לפי התו שנתנו ומחזיר רשימה.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="10-dicts",
+        title="מילונים",
+        emoji="🗂",
+        goal="לשמור נתונים לפי מפתח במקום לפי מיקום.",
+        body=(
+            "<b>מילון</b> (dict) שומר זוגות של מפתח וערך בתוך סוגריים מסולסלים:\n"
+            "<code>person = {\"name\": \"דנה\", \"age\": 25}</code>\n\n"
+            "ניגשים לפי מפתח ולא לפי אינדקס: <code>person[\"name\"]</code>.\n"
+            "גישה למפתח שלא קיים זורקת <code>KeyError</code>, ולכן בטוח יותר "
+            "להשתמש ב-<code>person.get(\"city\", \"לא ידוע\")</code> שמחזיר "
+            "ברירת מחדל.\n\n"
+            "פעולות נפוצות:\n"
+            "• <code>person[\"city\"] = \"חיפה\"</code> - הוספה או עדכון\n"
+            "• <code>del person[\"age\"]</code> - מחיקה\n"
+            "• <code>\"name\" in person</code> - בדיקת קיום מפתח\n"
+            "• <code>person.keys()</code>, <code>.values()</code>, <code>.items()</code>"
+        ),
+        example=(
+            'student = {"name": "יוסי", "grade": 88, "city": "תל אביב"}\n'
+            '\n'
+            'print(student["name"])\n'
+            'print(student.get("phone", "אין טלפון"))\n'
+            '\n'
+            'student["grade"] = 92\n'
+            'student["age"] = 17\n'
+            '\n'
+            'for key, value in student.items():\n'
+            '    print(f"{key}: {value}")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "צרו מילון <code>prices</code> עם שלושה מוצרים ומחיריהם, "
+                "והדפיסו את סכום כל המחירים."
+            ),
+            hint="sum(prices.values()) מחשב את סכום הערכים.",
+            solution=(
+                'prices = {"לחם": 8, "חלב": 6, "גבינה": 14}\n'
+                'print(sum(prices.values()))\n'
+            ),
+            required=("prices", "print"),
+        ),
+        quizzes=(
+            Quiz(
+                question="מה קורה בגישה למפתח שלא קיים, כמו <code>d[\"x\"]</code>?",
+                options=(
+                    "מוחזר None",
+                    "נזרקת שגיאת KeyError",
+                    "המפתח נוצר אוטומטית",
+                    "מוחזרת מחרוזת ריקה",
+                ),
+                answer=1,
+                explanation=(
+                    "לגישה בטוחה השתמשו ב-<code>.get()</code> שמחזיר ברירת מחדל "
+                    "במקום לזרוק שגיאה."
+                ),
+            ),
+            Quiz(
+                question="מה מחזיר <code>.items()</code> של מילון?",
+                options=(
+                    "רק את המפתחות",
+                    "רק את הערכים",
+                    "זוגות של מפתח וערך",
+                    "את מספר האיברים",
+                ),
+                answer=2,
+                explanation="<code>.items()</code> מתאים ללולאת for עם שני משתנים.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="11-functions",
+        title="פונקציות",
+        emoji="⚙️",
+        goal="לארוז קוד חוזר בשם אחד ולהשתמש בו שוב ושוב.",
+        body=(
+            "<b>פונקציה</b> היא קטע קוד עם שם, שמקבל קלט ומחזיר פלט. מגדירים "
+            "אותה עם <code>def</code>:\n"
+            "<pre>def greet(name):\n    return f\"שלום {name}\"</pre>\n"
+            "ההגדרה לבדה לא מריצה כלום - צריך <b>לקרוא</b> לפונקציה: "
+            "<code>greet(\"דנה\")</code>.\n\n"
+            "<code>return</code> מחזיר ערך ומסיים את הפונקציה מיד. פונקציה בלי "
+            "<code>return</code> מחזירה <code>None</code>.\n\n"
+            "אפשר לתת לפרמטר <b>ערך ברירת מחדל</b>: "
+            "<code>def greet(name, greeting=\"שלום\")</code>.\n\n"
+            "משתנה שנוצר בתוך פונקציה הוא <b>מקומי</b> וקיים רק בזמן הריצה שלה."
+        ),
+        example=(
+            'def add(a, b):\n'
+            '    return a + b\n'
+            '\n'
+            '\n'
+            'def greet(name, greeting="שלום"):\n'
+            '    return f"{greeting} {name}!"\n'
+            '\n'
+            '\n'
+            'print(add(3, 4))\n'
+            'print(greet("דנה"))\n'
+            'print(greet("יוסי", "בוקר טוב"))\n'
+            '\n'
+            '\n'
+            'def is_even(n):\n'
+            '    return n % 2 == 0\n'
+            '\n'
+            '\n'
+            'print(is_even(10))\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "כתבו פונקציה <code>area(width, height)</code> שמחזירה את שטח "
+                "המלבן, וקראו לה עם 5 ו-3 בתוך <code>print</code>."
+            ),
+            hint="def area(width, height): ואז return width * height.",
+            solution=(
+                'def area(width, height):\n'
+                '    return width * height\n'
+                '\n'
+                '\n'
+                'print(area(5, 3))\n'
+            ),
+            required=("def", "return", "print"),
+            expected_output="15",
+        ),
+        quizzes=(
+            Quiz(
+                question=(
+                    "מה יודפס?\n<pre>def f(x):\n    x * 2\n\nprint(f(5))</pre>"
+                ),
+                options=("10", "5", "None", "שגיאה"),
+                answer=2,
+                explanation=(
+                    "חסר <code>return</code>, ולכן הפונקציה מחזירה "
+                    "<code>None</code> למרות שהחישוב בוצע."
+                ),
+            ),
+            Quiz(
+                question="מה קורה לקוד שכתוב אחרי <code>return</code> בתוך פונקציה?",
+                options=(
+                    "הוא רץ כרגיל",
+                    "הוא לא רץ - return מסיים את הפונקציה",
+                    "נזרקת שגיאה",
+                    "הוא רץ רק בתנאי",
+                ),
+                answer=1,
+                explanation="<code>return</code> מחזיר ערך ויוצא מהפונקציה מיד.",
+            ),
+        ),
+    ),
+    Lesson(
+        id="12-errors",
+        title="שגיאות וטיפול בהן",
+        emoji="🛡",
+        goal="להבין הודעות שגיאה ולמנוע קריסה של התוכנית.",
+        body=(
+            "שגיאות הן חלק מהעבודה. שלוש נפוצות:\n"
+            "• <code>SyntaxError</code> - טעות כתיב, למשל נקודתיים חסרות\n"
+            "• <code>NameError</code> - שימוש במשתנה שלא הוגדר\n"
+            "• <code>TypeError</code> - פעולה על טיפוס לא מתאים, כמו "
+            "<code>\"5\" + 1</code>\n"
+            "• <code>ValueError</code> - טיפוס נכון אבל ערך לא חוקי, כמו "
+            "<code>int(\"abc\")</code>\n\n"
+            "קראו את הודעת השגיאה <b>מלמטה למעלה</b>: השורה האחרונה אומרת מה קרה, "
+            "והשורה שמעליה מראה איפה.\n\n"
+            "כדי שהתוכנית לא תקרוס עוטפים קוד מסוכן ב-<code>try</code> / "
+            "<code>except</code> - ותופסים שגיאה ספציפית, לא כל שגיאה שהיא."
+        ),
+        example=(
+            'text = input("הכניסו מספר: ")\n'
+            '\n'
+            'try:\n'
+            '    number = int(text)\n'
+            '    print(f"הכפלה: {number * 2}")\n'
+            'except ValueError:\n'
+            '    print("זה לא מספר תקין")\n'
+            '\n'
+            '\n'
+            '# חלוקה באפס\n'
+            'try:\n'
+            '    print(10 / 0)\n'
+            'except ZeroDivisionError:\n'
+            '    print("אי אפשר לחלק באפס")\n'
+            'finally:\n'
+            '    print("הבלוק הזה תמיד רץ")\n'
+        ),
+        exercise=Exercise(
+            prompt=(
+                "כתבו קוד שמנסה להמיר את המחרוזת <code>\"12a\"</code> למספר שלם, "
+                "ואם זה נכשל מדפיס <code>קלט לא תקין</code> במקום לקרוס."
+            ),
+            hint="try: int(\"12a\") ואז except ValueError:",
+            solution=(
+                'try:\n'
+                '    number = int("12a")\n'
+                '    print(number)\n'
+                'except ValueError:\n'
+                '    print("קלט לא תקין")\n'
+            ),
+            required=("try", "except", "print"),
+            expected_output="קלט לא תקין",
+        ),
+        quizzes=(
+            Quiz(
+                question="איזו שגיאה תיזרק מ-<code>int(\"hello\")</code>?",
+                options=("TypeError", "ValueError", "NameError", "SyntaxError"),
+                answer=1,
+                explanation=(
+                    "הטיפוס נכון (מחרוזת), אבל הערך לא ניתן להמרה - ולכן "
+                    "<code>ValueError</code>."
+                ),
+            ),
+            Quiz(
+                question="מתי רץ הבלוק של <code>finally</code>?",
+                options=(
+                    "רק כשיש שגיאה",
+                    "רק כשאין שגיאה",
+                    "תמיד, עם שגיאה או בלעדיה",
+                    "אף פעם",
+                ),
+                answer=2,
+                explanation="<code>finally</code> מתאים לניקוי משאבים, למשל סגירת קובץ.",
+            ),
+        ),
+    ),
+)
+
+LESSONS_BY_ID: dict[str, Lesson] = {lesson.id: lesson for lesson in LESSONS}
+
+
+def find_lesson(lesson_id: str) -> Lesson | None:
+    return LESSONS_BY_ID.get(lesson_id)
+
+
+def lesson_index(lesson_id: str) -> int:
+    """מיקום השיעור ברשימה, או -1 אם אינו קיים."""
+    for index, lesson in enumerate(LESSONS):
+        if lesson.id == lesson_id:
+            return index
+    return -1
+
+
+def next_lesson(lesson_id: str) -> Lesson | None:
+    index = lesson_index(lesson_id)
+    if index == -1 or index + 1 >= len(LESSONS):
+        return None
+    return LESSONS[index + 1]
diff --git a/app/handlers.py b/app/handlers.py
new file mode 100644
index 0000000..42093c6
--- /dev/null
+++ b/app/handlers.py
@@ -0,0 +1,731 @@
+"""הפקודות, הכפתורים וזרימת השיחה של הבוט."""
+
+from __future__ import annotations
+
+import html
+import logging
+import re
+
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.constants import ChatAction, ParseMode
+from telegram.error import BadRequest
+from telegram.ext import (
+    Application,
+    CallbackQueryHandler,
+    CommandHandler,
+    ContextTypes,
+    MessageHandler,
+    filters,
+)
+
+from app import keyboards as kb
+from app.ai import AIUnavailable, Grade, Tutor
+from app.content import LESSONS, Lesson, find_lesson, lesson_index, next_lesson
+from app.runner import run_code
+from app.storage import Storage
+
+logger = logging.getLogger(__name__)
+
+TELEGRAM_LIMIT = 3900  # מתחת למגבלת 4096 של טלגרם, עם מרווח ביטחון
+AWAITING_KEY = "awaiting_exercise"
+CURRENT_KEY = "current_lesson"
+
+
+# --------------------------------------------------------------------- utils
+def _storage(context: ContextTypes.DEFAULT_TYPE) -> Storage:
+    return context.application.bot_data["storage"]
+
+
+def _tutor(context: ContextTypes.DEFAULT_TYPE) -> Tutor:
+    return context.application.bot_data["tutor"]
+
+
+def _code_runner_enabled(context: ContextTypes.DEFAULT_TYPE) -> bool:
+    return bool(context.application.bot_data.get("enable_code_runner"))
+
+
+def _code_block(code: str) -> str:
+    return f"<pre><code>{html.escape(code)}</code></pre>"
+
+
+def _chunks(text: str, limit: int = TELEGRAM_LIMIT) -> list[str]:
+    """מפצל טקסט ארוך להודעות, עדיף בגבול שורה."""
+    if len(text) <= limit:
+        return [text]
+    parts: list[str] = []
+    remaining = text
+    while len(remaining) > limit:
+        cut = remaining.rfind("\n", 0, limit)
+        if cut <= 0:
+            cut = limit
+        parts.append(remaining[:cut])
+        remaining = remaining[cut:].lstrip("\n")
+    if remaining:
+        parts.append(remaining)
+    return parts
+
+
+async def _reply(update: Update, text: str, **kwargs) -> None:
+    """שולח הודעה, ומפצל אותה אם היא ארוכה מדי."""
+    message = update.effective_message
+    if message is None:
+        return
+    parts = _chunks(text)
+    for index, part in enumerate(parts):
+        is_last = index == len(parts) - 1
+        await message.reply_html(part, **(kwargs if is_last else {}))
+
+
+async def _edit_or_send(update: Update, text: str, **kwargs) -> None:
+    """מעדכן את ההודעה של הכפתור, ואם אי אפשר - שולח חדשה."""
+    query = update.callback_query
+    parts = _chunks(text)
+    if query is not None and len(parts) == 1:
+        try:
+            await query.edit_message_text(
+                text, parse_mode=ParseMode.HTML, **kwargs
+            )
+            return
+        except BadRequest as exc:
+            if "not modified" in str(exc).lower():
+                return
+            logger.debug("עריכת ההודעה נכשלה, שולח חדשה: %s", exc)
+    await _reply(update, text, **kwargs)
+
+
+async def _track(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
+    user = update.effective_user
+    if user is None:
+        return 0
+    return await _storage(context).touch_user(user.id, user.first_name, user.username)
+
+
+# ------------------------------------------------------------------ rendering
+def _lesson_text(lesson: Lesson) -> str:
+    position = lesson_index(lesson.id) + 1
+    return (
+        f"<b>{lesson.display_title}</b>  <i>({position}/{len(LESSONS)})</i>\n"
+        f"🎯 {lesson.goal}\n\n"
+        f"{lesson.body}"
+    )
+
+
+def _example_text(lesson: Lesson) -> str:
+    return (
+        f"<b>💡 דוגמה - {lesson.title}</b>\n\n"
+        f"{_code_block(lesson.example)}\n"
+        "נסו להעתיק את הקוד ולשנות אותו. ככה לומדים הכי מהר."
+    )
+
+
+def _exercise_text(lesson: Lesson, can_run: bool) -> str:
+    tail = (
+        "שלחו לי את הקוד שלכם בהודעה רגילה ואבדוק אותו."
+        if not can_run
+        else "שלחו לי את הקוד שלכם בהודעה רגילה - אריץ אותו ואבדוק את התוצאה."
+    )
+    return (
+        f"<b>✏️ תרגיל - {lesson.title}</b>\n\n"
+        f"{lesson.exercise.prompt}\n\n"
+        f"{tail}"
+    )
+
+
+def _quiz_text(lesson: Lesson, quiz_index: int) -> str:
+    quiz = lesson.quizzes[quiz_index]
+    return (
+        f"<b>🧠 חידון - {lesson.title}</b>\n"
+        f"<i>שאלה {quiz_index + 1} מתוך {len(lesson.quizzes)}</i>\n\n"
+        f"{quiz.question}"
+    )
+
+
+# ------------------------------------------------------------------- commands
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    streak = await _track(update, context)
+    user = update.effective_user
+    name = html.escape(user.first_name or "חבר") if user else "חבר"
+    completed = await _storage(context).completed_lessons(user.id) if user else set()
+
+    text = (
+        f"שלום {name}! 🐍\n\n"
+        "אני בוט שמלמד <b>Python מאפס</b>. יש כאן "
+        f"{len(LESSONS)} שיעורים קצרים, ובכל אחד הסבר, דוגמת קוד, תרגיל וחידון.\n\n"
+        "<b>איך מתחילים:</b>\n"
+        "• /lessons - תפריט כל השיעורים\n"
+        "• /next - להמשיך מאיפה שהפסקתם\n"
+        "• /ask שאלה - לשאול אותי כל דבר על Python\n"
+        "• /progress - לראות את ההתקדמות\n"
+        "• /help - כל הפקודות\n\n"
+        f"🔥 רצף למידה: {streak} ימים"
+    )
+    await _reply(update, text, reply_markup=kb.menu_keyboard(completed))
+
+
+async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    ai_line = (
+        "• /ask &lt;שאלה&gt; - שאלה חופשית על Python\n"
+        if _tutor(context).enabled
+        else "• /ask - כבוי כרגע (דורש מפתח ANTHROPIC_API_KEY)\n"
+    )
+    run_line = (
+        "• /run &lt;קוד&gt; - הרצת קוד ובדיקת הפלט\n"
+        if _code_runner_enabled(context)
+        else ""
+    )
+    await _reply(
+        update,
+        "<b>הפקודות שלי</b>\n\n"
+        "• /lessons - תפריט השיעורים\n"
+        "• /lesson &lt;מספר&gt; - מעבר ישיר לשיעור, למשל <code>/lesson 5</code>\n"
+        "• /next - השיעור הבא שלא השלמתם\n"
+        "• /quiz - חידון על השיעור הנוכחי\n"
+        "• /practice - התרגיל של השיעור הנוכחי\n"
+        f"{ai_line}"
+        f"{run_line}"
+        "• /progress - סטטיסטיקות והתקדמות\n"
+        "• /cancel - ביטול תרגיל פתוח\n"
+        "• /reset - איפוס כל ההתקדמות\n\n"
+        "טיפ: אפשר פשוט לשלוח לי שאלה בהודעה רגילה.",
+    )
+
+
+async def lessons_menu(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    user = update.effective_user
+    completed = await _storage(context).completed_lessons(user.id) if user else set()
+    await _reply(
+        update,
+        f"<b>📚 תוכנית הלימודים</b>\n\nהושלמו {len(completed)} מתוך {len(LESSONS)} שיעורים.\nבחרו שיעור:",
+        reply_markup=kb.menu_keyboard(completed),
+    )
+
+
+async def lesson_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    if not context.args:
+        await lessons_menu(update, context)
+        return
+
+    raw = context.args[0].strip()
+    if not raw.isdigit():
+        await _reply(update, "צריך מספר שיעור, למשל <code>/lesson 3</code>.")
+        return
+
+    number = int(raw)
+    if not 1 <= number <= len(LESSONS):
+        await _reply(update, f"יש שיעורים מ-1 עד {len(LESSONS)}.")
+        return
+
+    await _show_lesson(update, context, LESSONS[number - 1])
+
+
+async def next_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    user = update.effective_user
+    completed = await _storage(context).completed_lessons(user.id) if user else set()
+
+    target = next((lesson for lesson in LESSONS if lesson.id not in completed), None)
+    if target is None:
+        await _reply(
+            update,
+            "🎉 סיימתם את כל השיעורים! אפשר לחזור על שיעור מ-/lessons "
+            "או לשאול אותי שאלות עם /ask.",
+        )
+        return
+    await _show_lesson(update, context, target)
+
+
+async def quiz_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    lesson = _current_lesson(context)
+    if lesson is None:
+        await _reply(update, "קודם בחרו שיעור דרך /lessons.")
+        return
+    await _show_quiz(update, context, lesson, 0)
+
+
+async def practice_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    lesson = _current_lesson(context)
+    if lesson is None:
+        await _reply(update, "קודם בחרו שיעור דרך /lessons.")
+        return
+    await _show_exercise(update, context, lesson)
+
+
+async def progress_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    user = update.effective_user
+    if user is None:
+        return
+
+    storage = _storage(context)
+    stats = await storage.stats(user.id)
+    completed = await storage.completed_lessons(user.id)
+
+    done = len(completed)
+    total = len(LESSONS)
+    filled = round(10 * done / total) if total else 0
+    bar = "▓" * filled + "░" * (10 - filled)
+
+    lines = [
+        "<b>📊 ההתקדמות שלך</b>\n",
+        f"{bar}  {done}/{total} שיעורים",
+        f"🧠 חידונים: {stats.quiz_correct}/{stats.quiz_total} נכון ({stats.quiz_accuracy}%)",
+        f"✏️ תרגילים שנפתרו: {stats.exercises_passed}",
+        f"🔥 רצף: {stats.streak} ימים",
+    ]
+
+    upcoming = next((lesson for lesson in LESSONS if lesson.id not in completed), None)
+    if upcoming:
+        lines.append(f"\nהבא בתור: {upcoming.display_title} (/next)")
+    else:
+        lines.append("\nסיימתם את כל התוכנית! 🎉")
+
+    await _reply(update, "\n".join(lines))
+
+
+async def ask_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    question = " ".join(context.args).strip() if context.args else ""
+    if not question:
+        await _reply(
+            update,
+            "כתבו את השאלה אחרי הפקודה, למשל:\n"
+            "<code>/ask מה ההבדל בין רשימה למילון?</code>",
+        )
+        return
+    await _answer_question(update, context, question)
+
+
+async def run_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    if not _code_runner_enabled(context):
+        await _reply(
+            update,
+            "הרצת קוד כבויה בשרת הזה. אפשר להפעיל אותה עם "
+            "<code>ENABLE_CODE_RUNNER=true</code> (ראו README).",
+        )
+        return
+
+    code = update.effective_message.text.partition(" ")[2].strip()
+    code = _strip_fences(code)
+    if not code:
+        await _reply(
+            update,
+            "שלחו קוד אחרי הפקודה, למשל:\n<code>/run print(2 + 2)</code>",
+        )
+        return
+    await _run_and_report(update, code)
+
+
+async def cancel_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    if context.user_data.pop(AWAITING_KEY, None):
+        await _reply(update, "ביטלתי את התרגיל. אפשר להמשיך עם /next או /lessons.")
+    else:
+        await _reply(update, "אין תרגיל פתוח כרגע.")
+
+
+async def reset_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    await _track(update, context)
+    keyboard = InlineKeyboardMarkup(
+        [
+            [
+                InlineKeyboardButton("כן, אפס הכול", callback_data="reset:yes"),
+                InlineKeyboardButton("לא, בטל", callback_data="reset:no"),
+            ]
+        ]
+    )
+    await _reply(
+        update,
+        "לאפס את כל ההתקדמות, הציונים והרצף? אי אפשר לבטל את הפעולה.",
+        reply_markup=keyboard,
+    )
+
+
+# -------------------------------------------------------------------- display
+def _current_lesson(context: ContextTypes.DEFAULT_TYPE) -> Lesson | None:
+    lesson_id = context.user_data.get(CURRENT_KEY)
+    return find_lesson(lesson_id) if lesson_id else None
+
+
+async def _show_lesson(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, lesson: Lesson
+) -> None:
+    context.user_data[CURRENT_KEY] = lesson.id
+    context.user_data.pop(AWAITING_KEY, None)
+    await _edit_or_send(
+        update, _lesson_text(lesson), reply_markup=kb.lesson_keyboard(lesson)
+    )
+
+
+async def _show_example(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, lesson: Lesson
+) -> None:
+    context.user_data[CURRENT_KEY] = lesson.id
+    await _edit_or_send(
+        update, _example_text(lesson), reply_markup=kb.example_keyboard(lesson)
+    )
+
+
+async def _show_exercise(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, lesson: Lesson
+) -> None:
+    context.user_data[CURRENT_KEY] = lesson.id
+    context.user_data[AWAITING_KEY] = lesson.id
+    await _edit_or_send(
+        update,
+        _exercise_text(lesson, _code_runner_enabled(context)),
+        reply_markup=kb.exercise_keyboard(lesson),
+    )
+
+
+async def _show_quiz(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, lesson: Lesson, index: int
+) -> None:
+    context.user_data[CURRENT_KEY] = lesson.id
+    context.user_data.pop(AWAITING_KEY, None)
+    if not lesson.quizzes:
+        await _edit_or_send(update, "אין חידון לשיעור הזה.")
+        return
+    index = max(0, min(index, len(lesson.quizzes) - 1))
+    await _edit_or_send(
+        update, _quiz_text(lesson, index), reply_markup=kb.quiz_keyboard(lesson, index)
+    )
+
+
+# ------------------------------------------------------------------- callbacks
+async def on_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    query = update.callback_query
+    if query is None or not query.data:
+        return
+    await query.answer()
+    await _track(update, context)
+
+    action, _, rest = query.data.partition(":")
+    parts = rest.split(":") if rest else []
+    lesson_id = parts[0] if parts else ""
+    lesson = find_lesson(lesson_id)
+
+    if action == kb.CB_MENU:
+        user = update.effective_user
+        completed = (
+            await _storage(context).completed_lessons(user.id) if user else set()
+        )
+        await _edit_or_send(
+            update,
+            f"<b>📚 תוכנית הלימודים</b>\n\nהושלמו {len(completed)} מתוך "
+            f"{len(LESSONS)} שיעורים.\nבחרו שיעור:",
+            reply_markup=kb.menu_keyboard(completed),
+        )
+        return
+
+    if action == "reset":
+        user = update.effective_user
+        if lesson_id == "yes" and user:
+            await _storage(context).reset(user.id)
+            context.user_data.clear()
+            await _edit_or_send(update, "ההתקדמות אופסה. אפשר להתחיל מחדש עם /next 🙂")
+        else:
+            await _edit_or_send(update, "ביטלתי - ההתקדמות נשמרה.")
+        return
+
+    if lesson is None:
+        await _edit_or_send(update, "לא מצאתי את השיעור הזה. נסו /lessons.")
+        return
+
+    if action == kb.CB_LESSON:
+        await _show_lesson(update, context, lesson)
+    elif action == kb.CB_EXAMPLE:
+        await _show_example(update, context, lesson)
+    elif action == kb.CB_EXERCISE:
+        await _show_exercise(update, context, lesson)
+    elif action == kb.CB_HINT:
+        await _reply(update, f"🔦 <b>רמז:</b> {lesson.exercise.hint}")
+    elif action == kb.CB_SOLUTION:
+        await _reply(
+            update,
+            f"🔑 <b>פתרון אפשרי</b>\n\n{_code_block(lesson.exercise.solution)}\n"
+            "יש עוד דרכים נכונות - העיקר שהתוצאה נכונה.",
+        )
+    elif action == kb.CB_QUIZ:
+        index = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else 0
+        await _show_quiz(update, context, lesson, index)
+    elif action == kb.CB_ANSWER:
+        await _handle_quiz_answer(update, context, lesson, parts)
+    elif action == kb.CB_NEXT:
+        upcoming = next_lesson(lesson.id)
+        if upcoming is None:
+            await _edit_or_send(update, "זה היה השיעור האחרון 🎉 כל הכבוד!")
+        else:
+            await _show_lesson(update, context, upcoming)
+
+
+async def _handle_quiz_answer(
+    update: Update,
+    context: ContextTypes.DEFAULT_TYPE,
+    lesson: Lesson,
+    parts: list[str],
+) -> None:
+    if len(parts) < 3 or not parts[1].isdigit() or not parts[2].isdigit():
+        return
+    quiz_index, chosen = int(parts[1]), int(parts[2])
+    if quiz_index >= len(lesson.quizzes):
+        return
+
+    quiz = lesson.quizzes[quiz_index]
+    correct = chosen == quiz.answer
+    user = update.effective_user
+    if user:
+        await _storage(context).record_quiz_answer(
+            user.id, lesson.id, quiz_index, correct
+        )
+
+    head = "✅ <b>נכון!</b>" if correct else "❌ <b>לא מדויק</b>"
+    body = (
+        f"{head}\n\n{quiz.question}\n\n"
+        f"התשובה הנכונה: <b>{quiz.options[quiz.answer]}</b>\n\n"
+        f"{quiz.explanation}"
+    )
+
+    is_last = quiz_index + 1 >= len(lesson.quizzes)
+    if is_last and user:
+        await _storage(context).complete_lesson(user.id, lesson.id)
+        body += "\n\n🎉 סיימתם את השיעור! הוא סומן כהושלם."
+
+    await _edit_or_send(
+        update, body, reply_markup=kb.after_quiz_keyboard(lesson, quiz_index)
+    )
+
+
+# ---------------------------------------------------------------- free messages
+async def on_text(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """הודעה חופשית: פתרון תרגיל אם יש תרגיל פתוח, אחרת שאלה למורה."""
+    await _track(update, context)
+    message = update.effective_message
+    if message is None or not message.text:
+        return
+    text = message.text.strip()
+
+    lesson_id = context.user_data.get(AWAITING_KEY)
+    lesson = find_lesson(lesson_id) if lesson_id else None
+    if lesson is not None:
+        await _check_submission(update, context, lesson, _strip_fences(text))
+        return
+
+    if _looks_like_code(text):
+        await _reply(
+            update,
+            "נראה שזה קוד 🙂 כדי שאבדוק אותו פתחו קודם תרגיל עם /practice, "
+            "או שאלו אותי שאלה במילים.",
+        )
+        return
+
+    await _answer_question(update, context, text)
+
+
+async def _answer_question(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, question: str
+) -> None:
+    tutor = _tutor(context)
+    if not tutor.enabled:
+        await _reply(
+            update,
+            "שאלות חופשיות דורשות מפתח <code>ANTHROPIC_API_KEY</code> בשרת. "
+            "בינתיים אפשר ללמוד דרך /lessons - כל החומר שם זמין.",
+        )
+        return
+
+    chat = update.effective_chat
+    if chat:
+        await context.bot.send_chat_action(chat.id, ChatAction.TYPING)
+
+    lesson = _current_lesson(context)
+    try:
+        answer = await tutor.answer(question, lesson.title if lesson else None)
+    except AIUnavailable:
+        await _reply(update, "התכונה הזו אינה זמינה כרגע.")
+        return
+    except Exception:  # noqa: BLE001 - לא מפילים את הבוט בגלל שגיאת רשת
+        logger.exception("קריאה למודל נכשלה")
+        await _reply(update, "לא הצלחתי להגיע למורה החכם כרגע. נסו שוב בעוד רגע.")
+        return
+
+    await _reply(update, _markdown_code_to_html(answer))
+
+
+async def _check_submission(
+    update: Update, context: ContextTypes.DEFAULT_TYPE, lesson: Lesson, code: str
+) -> None:
+    chat = update.effective_chat
+    if chat:
+        await context.bot.send_chat_action(chat.id, ChatAction.TYPING)
+
+    run_note = ""
+    if _code_runner_enabled(context):
+        result = await run_code(code)
+        if not result.ok:
+            await _reply(
+                update,
+                f"❌ הקוד לא רץ בהצלחה:\n{_code_block(result.combined)}\n"
+                "תקנו ושלחו שוב, או בקשו 🔦 רמז.",
+            )
+            return
+        run_note = f"\n\n<b>הפלט שקיבלתי:</b>\n{_code_block(result.output or '(ריק)')}"
+        expected = lesson.exercise.expected_output
+        if expected is not None and result.output.strip() != expected.strip():
+            if update.effective_user:
+                await _storage(context).record_exercise(
+                    update.effective_user.id, lesson.id, False
+                )
+            await _reply(
+                update,
+                f"כמעט! ציפיתי לפלט <code>{html.escape(expected)}</code>."
+                f"{run_note}\n\nנסו שוב 💪",
+            )
+            return
+
+    grade = await _grade(context, lesson, code)
+    user = update.effective_user
+    if user:
+        await _storage(context).record_exercise(user.id, lesson.id, grade.passed)
+
+    if grade.passed:
+        context.user_data.pop(AWAITING_KEY, None)
+        await _reply(
+            update,
+            f"✅ <b>יפה מאוד!</b> {grade.feedback}{run_note}",
+            reply_markup=kb.exercise_keyboard(lesson),
+        )
+    else:
+        await _reply(
+            update,
+            f"🔍 {grade.feedback}{run_note}\n\nנסו שוב, או לחצו 🔦 רמז.",
+            reply_markup=kb.exercise_keyboard(lesson),
+        )
+
+
+async def _grade(
+    context: ContextTypes.DEFAULT_TYPE, lesson: Lesson, code: str
+) -> Grade:
+    """בדיקה חכמה עם Claude, ואם אינה זמינה - בדיקה היוריסטית."""
+    tutor = _tutor(context)
+    if tutor.enabled:
+        try:
+            return await tutor.grade(
+                lesson.exercise.prompt, lesson.exercise.solution, code
+            )
+        except AIUnavailable:
+            pass
+        except Exception:  # noqa: BLE001
+            logger.exception("בדיקת תרגיל נכשלה, עובר לבדיקה היוריסטית")
+    return heuristic_grade(lesson, code)
+
+
+def heuristic_grade(lesson: Lesson, code: str) -> Grade:
+    """בדיקה פשוטה: תחביר תקין ומילות המפתח הנדרשות."""
+    if not code.strip():
+        return Grade(False, "לא קיבלתי קוד.")
+    try:
+        compile(code, "<exercise>", "exec")
+    except SyntaxError as exc:
+        return Grade(False, f"יש שגיאת תחביר בשורה {exc.lineno}: {exc.msg}")
+
+    normalized = code.replace(" ", "")
+    missing = [
+        token
+        for token in lesson.exercise.required
+        if token.replace(" ", "") not in normalized
+    ]
+    if missing:
+        return Grade(False, f"חסר בקוד: {', '.join(missing)}")
+    return Grade(True, "הקוד נראה נכון.")
+
+
+async def _run_and_report(update: Update, code: str) -> None:
+    result = await run_code(code)
+    if result.ok:
+        await _reply(
+            update, f"▶️ <b>פלט:</b>\n{_code_block(result.output or '(אין פלט)')}"
+        )
+    else:
+        await _reply(update, f"❌ <b>שגיאה:</b>\n{_code_block(result.combined)}")
+
+
+# ------------------------------------------------------------------- helpers
+def _strip_fences(text: str) -> str:
+    """מסיר עטיפת ```python``` שמשתמשים נוטים להדביק."""
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return stripped
+    lines = stripped.splitlines()
+    if lines and lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].strip() == "```":
+        lines = lines[:-1]
+    return "\n".join(lines).strip()
+
+
+def _looks_like_code(text: str) -> bool:
+    markers = ("print(", "def ", "import ", "for ", "while ", "if ", "=")
+    return text.startswith("```") or (
+        "\n" in text and any(marker in text for marker in markers)
+    )
+
+
+def _markdown_code_to_html(text: str) -> str:
+    """ממיר תשובת מודל (markdown) ל-HTML שטלגרם מקבל."""
+    out: list[str] = []
+    in_code = False
+    for line in text.splitlines():
+        if line.strip().startswith("```"):
+            out.append("<pre><code>" if not in_code else "</code></pre>")
+            in_code = not in_code
+            continue
+        out.append(html.escape(line) if in_code else _inline_markdown(line))
+    if in_code:
+        out.append("</code></pre>")
+    return "\n".join(out)
+
+
+def _inline_markdown(line: str) -> str:
+    """בורח מ-HTML ומתרגם `code`, **bold** ו-*italic*."""
+    escaped = html.escape(line)
+    escaped = re.sub(r"`([^`]+)`", r"<code>\1</code>", escaped)
+    escaped = re.sub(r"\*\*([^*]+)\*\*", r"<b>\1</b>", escaped)
+    escaped = re.sub(r"(?<!\*)\*([^*\n]+)\*(?!\*)", r"<i>\1</i>", escaped)
+    return escaped
+
+
+async def on_error(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
+    logger.exception("שגיאה בטיפול בעדכון", exc_info=context.error)
+    if isinstance(update, Update) and update.effective_message:
+        try:
+            await update.effective_message.reply_text(
+                "משהו השתבש אצלי 😕 נסו שוב, או /start כדי להתחיל מחדש."
+            )
+        except Exception:  # noqa: BLE001
+            logger.debug("לא הצלחתי לשלוח הודעת שגיאה למשתמש")
+
+
+def register(application: Application) -> None:
+    """רושם את כל ההנדלרים על האפליקציה."""
+    application.add_handler(CommandHandler("start", start))
+    application.add_handler(CommandHandler("help", help_command))
+    application.add_handler(CommandHandler(["lessons", "menu"], lessons_menu))
+    application.add_handler(CommandHandler("lesson", lesson_command))
+    application.add_handler(CommandHandler("next", next_command))
+    application.add_handler(CommandHandler("quiz", quiz_command))
+    application.add_handler(CommandHandler(["practice", "exercise"], practice_command))
+    application.add_handler(CommandHandler("progress", progress_command))
+    application.add_handler(CommandHandler("ask", ask_command))
+    application.add_handler(CommandHandler("run", run_command))
+    application.add_handler(CommandHandler("cancel", cancel_command))
+    application.add_handler(CommandHandler("reset", reset_command))
+    application.add_handler(CallbackQueryHandler(on_callback))
+    application.add_handler(
+        MessageHandler(filters.TEXT & ~filters.COMMAND, on_text)
+    )
+    application.add_error_handler(on_error)
diff --git a/app/keyboards.py b/app/keyboards.py
new file mode 100644
index 0000000..29a51f3
--- /dev/null
+++ b/app/keyboards.py
@@ -0,0 +1,130 @@
+"""מקלדות inline של הבוט.
+
+מבנה ה-callback_data: "<פעולה>:<מזהה שיעור>[:פרמטר]".
+"""
+
+from __future__ import annotations
+
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+
+from app.content import LESSONS, Lesson, lesson_index
+
+CB_LESSON = "lesson"
+CB_EXAMPLE = "example"
+CB_EXERCISE = "exercise"
+CB_SOLUTION = "solution"
+CB_HINT = "hint"
+CB_QUIZ = "quiz"
+CB_ANSWER = "answer"
+CB_NEXT = "next"
+CB_MENU = "menu"
+CB_NOOP = "noop"
+
+
+def menu_keyboard(completed: set[str]) -> InlineKeyboardMarkup:
+    """תפריט כל השיעורים, עם וי ליד מה שהושלם."""
+    rows = []
+    for index, lesson in enumerate(LESSONS, start=1):
+        mark = "✅" if lesson.id in completed else "▫️"
+        rows.append(
+            [
+                InlineKeyboardButton(
+                    f"{mark} {index}. {lesson.display_title}",
+                    callback_data=f"{CB_LESSON}:{lesson.id}",
+                )
+            ]
+        )
+    return InlineKeyboardMarkup(rows)
+
+
+def lesson_keyboard(lesson: Lesson) -> InlineKeyboardMarkup:
+    rows = [
+        [
+            InlineKeyboardButton(
+                "💡 דוגמת קוד", callback_data=f"{CB_EXAMPLE}:{lesson.id}"
+            ),
+            InlineKeyboardButton(
+                "✏️ תרגיל", callback_data=f"{CB_EXERCISE}:{lesson.id}"
+            ),
+        ],
+        [
+            InlineKeyboardButton("🧠 חידון", callback_data=f"{CB_QUIZ}:{lesson.id}:0"),
+        ],
+    ]
+    rows.append(_nav_row(lesson))
+    return InlineKeyboardMarkup(rows)
+
+
+def example_keyboard(lesson: Lesson) -> InlineKeyboardMarkup:
+    return InlineKeyboardMarkup(
+        [
+            [
+                InlineKeyboardButton(
+                    "✏️ לתרגיל", callback_data=f"{CB_EXERCISE}:{lesson.id}"
+                ),
+                InlineKeyboardButton(
+                    "📖 חזרה לשיעור", callback_data=f"{CB_LESSON}:{lesson.id}"
+                ),
+            ],
+            _nav_row(lesson),
+        ]
+    )
+
+
+def exercise_keyboard(lesson: Lesson) -> InlineKeyboardMarkup:
+    return InlineKeyboardMarkup(
+        [
+            [
+                InlineKeyboardButton("🔦 רמז", callback_data=f"{CB_HINT}:{lesson.id}"),
+                InlineKeyboardButton(
+                    "🔑 פתרון", callback_data=f"{CB_SOLUTION}:{lesson.id}"
+                ),
+            ],
+            [
+                InlineKeyboardButton(
+                    "🧠 לחידון", callback_data=f"{CB_QUIZ}:{lesson.id}:0"
+                ),
+                InlineKeyboardButton(
+                    "📖 חזרה לשיעור", callback_data=f"{CB_LESSON}:{lesson.id}"
+                ),
+            ],
+        ]
+    )
+
+
+def quiz_keyboard(lesson: Lesson, quiz_index: int) -> InlineKeyboardMarkup:
+    quiz = lesson.quizzes[quiz_index]
+    rows = [
+        [
+            InlineKeyboardButton(
+                f"{chr(ord('א') + option_index)}. {option}",
+                callback_data=f"{CB_ANSWER}:{lesson.id}:{quiz_index}:{option_index}",
+            )
+        ]
+        for option_index, option in enumerate(quiz.options)
+    ]
+    return InlineKeyboardMarkup(rows)
+
+
+def after_quiz_keyboard(lesson: Lesson, quiz_index: int) -> InlineKeyboardMarkup:
+    rows = []
+    if quiz_index + 1 < len(lesson.quizzes):
+        rows.append(
+            [
+                InlineKeyboardButton(
+                    "➡️ שאלה הבאה",
+                    callback_data=f"{CB_QUIZ}:{lesson.id}:{quiz_index + 1}",
+                )
+            ]
+        )
+    rows.append(_nav_row(lesson))
+    return InlineKeyboardMarkup(rows)
+
+
+def _nav_row(lesson: Lesson) -> list[InlineKeyboardButton]:
+    row = [InlineKeyboardButton("📚 כל השיעורים", callback_data=f"{CB_MENU}:-")]
+    if lesson_index(lesson.id) + 1 < len(LESSONS):
+        row.append(
+            InlineKeyboardButton("⏭ השיעור הבא", callback_data=f"{CB_NEXT}:{lesson.id}")
+        )
+    return row
diff --git a/app/runner.py b/app/runner.py
new file mode 100644
index 0000000..b9cc307
--- /dev/null
+++ b/app/runner.py
@@ -0,0 +1,135 @@
+"""הרצת קוד תרגילים בתת-תהליך מוגבל.
+
+התכונה כבויה כברירת מחדל (ENABLE_CODE_RUNNER=false). הפעלה מריצה קוד שנשלח
+מטלגרם על השרת שלכם, ולכן הגבלנו זמן CPU, זיכרון, גודל פלט וייבוא מודולים
+רגישים. זו הגנה בשכבות, לא בידוד מלא - ראו את הפרק המתאים ב-README.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+CPU_SECONDS = 2
+MEMORY_BYTES = 128 * 1024 * 1024
+WALL_TIMEOUT = 6.0
+MAX_OUTPUT_CHARS = 2000
+MAX_CODE_CHARS = 4000
+
+BLOCKED_MODULES = {
+    "os", "sys", "subprocess", "shutil", "socket", "http", "urllib", "requests",
+    "pathlib", "ctypes", "multiprocessing", "threading", "importlib", "pickle",
+    "signal", "resource", "glob", "tempfile", "webbrowser", "ftplib", "smtplib",
+}
+BLOCKED_CALLS = {"open", "eval", "exec", "compile", "__import__", "input", "breakpoint"}
+
+_IMPORT_RE = re.compile(r"^\s*(?:import|from)\s+([A-Za-z_][\w.]*)", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class RunResult:
+    ok: bool
+    output: str
+    error: str = ""
+
+    @property
+    def combined(self) -> str:
+        return "\n".join(part for part in (self.output, self.error) if part).strip()
+
+
+def check_code(code: str) -> str | None:
+    """בדיקה סטטית מהירה. מחזיר הודעת שגיאה בעברית, או None אם הקוד עבר."""
+    if not code.strip():
+        return "לא קיבלתי קוד להרצה."
+    if len(code) > MAX_CODE_CHARS:
+        return f"הקוד ארוך מדי (מעל {MAX_CODE_CHARS} תווים)."
+
+    for match in _IMPORT_RE.finditer(code):
+        root = match.group(1).split(".")[0]
+        if root in BLOCKED_MODULES:
+            return f"ייבוא המודול <code>{root}</code> חסום בסביבת התרגול."
+
+    for name in BLOCKED_CALLS:
+        if re.search(rf"\b{re.escape(name)}\s*\(", code):
+            return f"השימוש ב-<code>{name}()</code> חסום בסביבת התרגול."
+
+    try:
+        compile(code, "<exercise>", "exec")
+    except SyntaxError as exc:
+        return f"שגיאת תחביר בשורה {exc.lineno}: {exc.msg}"
+    return None
+
+
+def _apply_limits() -> None:  # pragma: no cover - רץ רק בתת-תהליך
+    import resource
+
+    resource.setrlimit(resource.RLIMIT_CPU, (CPU_SECONDS, CPU_SECONDS))
+    resource.setrlimit(resource.RLIMIT_AS, (MEMORY_BYTES, MEMORY_BYTES))
+    resource.setrlimit(resource.RLIMIT_NPROC, (64, 64))
+    resource.setrlimit(resource.RLIMIT_FSIZE, (0, 0))
+    os.setsid()
+
+
+def _run_sync(code: str) -> RunResult:
+    env = {
+        "PATH": "/usr/bin:/bin",
+        "HOME": "/tmp",
+        "PYTHONIOENCODING": "utf-8",
+        "PYTHONDONTWRITEBYTECODE": "1",
+        "LANG": "C.UTF-8",
+    }
+    with tempfile.TemporaryDirectory(prefix="pythonbot-") as workdir:
+        try:
+            completed = subprocess.run(
+                [sys.executable, "-I", "-B", "-c", code],
+                capture_output=True,
+                text=True,
+                timeout=WALL_TIMEOUT,
+                cwd=workdir,
+                env=env,
+                stdin=subprocess.DEVNULL,
+                preexec_fn=_apply_limits if hasattr(os, "setsid") else None,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return RunResult(False, "", "הקוד רץ יותר מדי זמן - אולי יש לולאה אינסופית?")
+        except OSError as exc:  # pragma: no cover
+            logger.exception("הרצת הקוד נכשלה")
+            return RunResult(False, "", f"לא הצלחתי להריץ את הקוד: {exc}")
+
+    stdout = completed.stdout[:MAX_OUTPUT_CHARS]
+    stderr = completed.stderr[-MAX_OUTPUT_CHARS:]
+    if completed.returncode < 0:
+        # התהליך נהרג על ידי סיגנל - בדרך כלל חריגה ממגבלת CPU או זיכרון
+        return RunResult(
+            False,
+            stdout.strip(),
+            "הקוד חרג ממגבלות הזמן או הזיכרון. בדקו אם יש לולאה שלא נגמרת.",
+        )
+    if completed.returncode != 0:
+        return RunResult(False, stdout.strip(), _short_error(stderr))
+    return RunResult(True, stdout.strip())
+
+
+def _short_error(stderr: str) -> str:
+    """מציג לתלמיד את שורת השגיאה המשמעותית בלבד."""
+    lines = [line for line in stderr.strip().splitlines() if line.strip()]
+    if not lines:
+        return "הקוד נעצר עם שגיאה."
+    return lines[-1].strip()
+
+
+async def run_code(code: str) -> RunResult:
+    """מריץ קוד ומחזיר את הפלט. אינו חוסם את לולאת האירועים."""
+    problem = check_code(code)
+    if problem:
+        return RunResult(False, "", problem)
+    return await asyncio.to_thread(_run_sync, code)
diff --git a/app/storage.py b/app/storage.py
new file mode 100644
index 0000000..f31e87c
--- /dev/null
+++ b/app/storage.py
@@ -0,0 +1,251 @@
+"""שמירת התקדמות משתמשים ב-SQLite.
+
+כל הגישות ל-DB רצות ב-thread נפרד (``asyncio.to_thread``) כדי לא לחסום את
+לולאת האירועים של הבוט.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS users (
+    user_id     INTEGER PRIMARY KEY,
+    first_name  TEXT,
+    username    TEXT,
+    created_at  TEXT NOT NULL,
+    last_seen   TEXT NOT NULL,
+    streak      INTEGER NOT NULL DEFAULT 0,
+    last_active_day TEXT
+);
+
+CREATE TABLE IF NOT EXISTS lesson_progress (
+    user_id      INTEGER NOT NULL,
+    lesson_id    TEXT NOT NULL,
+    completed_at TEXT NOT NULL,
+    PRIMARY KEY (user_id, lesson_id)
+);
+
+CREATE TABLE IF NOT EXISTS quiz_answers (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id    INTEGER NOT NULL,
+    lesson_id  TEXT NOT NULL,
+    quiz_index INTEGER NOT NULL,
+    correct    INTEGER NOT NULL,
+    answered_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_quiz_answers_user ON quiz_answers(user_id);
+
+CREATE TABLE IF NOT EXISTS exercise_results (
+    user_id     INTEGER NOT NULL,
+    lesson_id   TEXT NOT NULL,
+    passed      INTEGER NOT NULL,
+    attempts    INTEGER NOT NULL DEFAULT 1,
+    updated_at  TEXT NOT NULL,
+    PRIMARY KEY (user_id, lesson_id)
+);
+"""
+
+
+@dataclass(frozen=True)
+class Stats:
+    lessons_done: int
+    quiz_total: int
+    quiz_correct: int
+    exercises_passed: int
+    streak: int
+
+    @property
+    def quiz_accuracy(self) -> int:
+        if self.quiz_total == 0:
+            return 0
+        return round(100 * self.quiz_correct / self.quiz_total)
+
+
+def _utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+class Storage:
+    """עטיפה דקה מעל SQLite עם API אסינכרוני."""
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = db_path
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------ setup
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, timeout=10)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA foreign_keys=ON")
+        return conn
+
+    def _init_sync(self) -> None:
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.executescript(_SCHEMA)
+
+    async def init(self) -> None:
+        await asyncio.to_thread(self._init_sync)
+
+    # ------------------------------------------------------------------ users
+    def _touch_user_sync(
+        self, user_id: int, first_name: str | None, username: str | None
+    ) -> int:
+        now = _utcnow()
+        today = date.today().isoformat()
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT streak, last_active_day FROM users WHERE user_id = ?",
+                (user_id,),
+            ).fetchone()
+
+            if row is None:
+                conn.execute(
+                    "INSERT INTO users (user_id, first_name, username, created_at,"
+                    " last_seen, streak, last_active_day) VALUES (?,?,?,?,?,?,?)",
+                    (user_id, first_name, username, now, now, 1, today),
+                )
+                return 1
+
+            streak = int(row["streak"] or 0)
+            last_day = row["last_active_day"]
+            if last_day != today:
+                if last_day:
+                    gap = (date.today() - date.fromisoformat(last_day)).days
+                    streak = streak + 1 if gap == 1 else 1
+                else:
+                    streak = 1
+            streak = max(streak, 1)
+
+            conn.execute(
+                "UPDATE users SET first_name = ?, username = ?, last_seen = ?,"
+                " streak = ?, last_active_day = ? WHERE user_id = ?",
+                (first_name, username, now, streak, today, user_id),
+            )
+            return streak
+
+    async def touch_user(
+        self, user_id: int, first_name: str | None = None, username: str | None = None
+    ) -> int:
+        """מעדכן פעילות אחרונה ומחזיר את אורך הרצף היומי."""
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._touch_user_sync, user_id, first_name, username
+            )
+
+    # --------------------------------------------------------------- progress
+    def _complete_lesson_sync(self, user_id: int, lesson_id: str) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT OR IGNORE INTO lesson_progress (user_id, lesson_id,"
+                " completed_at) VALUES (?,?,?)",
+                (user_id, lesson_id, _utcnow()),
+            )
+
+    async def complete_lesson(self, user_id: int, lesson_id: str) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._complete_lesson_sync, user_id, lesson_id)
+
+    def _completed_lessons_sync(self, user_id: int) -> set[str]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT lesson_id FROM lesson_progress WHERE user_id = ?", (user_id,)
+            ).fetchall()
+        return {row["lesson_id"] for row in rows}
+
+    async def completed_lessons(self, user_id: int) -> set[str]:
+        async with self._lock:
+            return await asyncio.to_thread(self._completed_lessons_sync, user_id)
+
+    # ------------------------------------------------------------------- quiz
+    def _record_quiz_sync(
+        self, user_id: int, lesson_id: str, quiz_index: int, correct: bool
+    ) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO quiz_answers (user_id, lesson_id, quiz_index, correct,"
+                " answered_at) VALUES (?,?,?,?,?)",
+                (user_id, lesson_id, quiz_index, int(correct), _utcnow()),
+            )
+
+    async def record_quiz_answer(
+        self, user_id: int, lesson_id: str, quiz_index: int, correct: bool
+    ) -> None:
+        async with self._lock:
+            await asyncio.to_thread(
+                self._record_quiz_sync, user_id, lesson_id, quiz_index, correct
+            )
+
+    # --------------------------------------------------------------- exercise
+    def _record_exercise_sync(self, user_id: int, lesson_id: str, passed: bool) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO exercise_results (user_id, lesson_id, passed, attempts,"
+                " updated_at) VALUES (?,?,?,1,?)"
+                " ON CONFLICT(user_id, lesson_id) DO UPDATE SET"
+                " passed = MAX(passed, excluded.passed),"
+                " attempts = attempts + 1,"
+                " updated_at = excluded.updated_at",
+                (user_id, lesson_id, int(passed), _utcnow()),
+            )
+
+    async def record_exercise(self, user_id: int, lesson_id: str, passed: bool) -> None:
+        async with self._lock:
+            await asyncio.to_thread(
+                self._record_exercise_sync, user_id, lesson_id, passed
+            )
+
+    # ------------------------------------------------------------------ stats
+    def _stats_sync(self, user_id: int) -> Stats:
+        with self._connect() as conn:
+            lessons = conn.execute(
+                "SELECT COUNT(*) AS c FROM lesson_progress WHERE user_id = ?",
+                (user_id,),
+            ).fetchone()["c"]
+            quiz = conn.execute(
+                "SELECT COUNT(*) AS total, COALESCE(SUM(correct), 0) AS correct"
+                " FROM quiz_answers WHERE user_id = ?",
+                (user_id,),
+            ).fetchone()
+            exercises = conn.execute(
+                "SELECT COUNT(*) AS c FROM exercise_results"
+                " WHERE user_id = ? AND passed = 1",
+                (user_id,),
+            ).fetchone()["c"]
+            user = conn.execute(
+                "SELECT streak FROM users WHERE user_id = ?", (user_id,)
+            ).fetchone()
+
+        return Stats(
+            lessons_done=int(lessons),
+            quiz_total=int(quiz["total"]),
+            quiz_correct=int(quiz["correct"]),
+            exercises_passed=int(exercises),
+            streak=int(user["streak"]) if user else 0,
+        )
+
+    async def stats(self, user_id: int) -> Stats:
+        async with self._lock:
+            return await asyncio.to_thread(self._stats_sync, user_id)
+
+    # ------------------------------------------------------------------ reset
+    def _reset_sync(self, user_id: int) -> None:
+        with self._connect() as conn:
+            conn.execute("DELETE FROM lesson_progress WHERE user_id = ?", (user_id,))
+            conn.execute("DELETE FROM quiz_answers WHERE user_id = ?", (user_id,))
+            conn.execute("DELETE FROM exercise_results WHERE user_id = ?", (user_id,))
+            conn.execute(
+                "UPDATE users SET streak = 1, last_active_day = ? WHERE user_id = ?",
+                (date.today().isoformat(), user_id),
+            )
+
+    async def reset(self, user_id: int) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._reset_sync, user_id)
diff --git a/main.py b/main.py
new file mode 100644
index 0000000..5ace948
--- /dev/null
+++ b/main.py
@@ -0,0 +1,100 @@
+"""נקודת הכניסה של הבוט.
+
+ברנדר (Web Service) מוגדר RENDER_EXTERNAL_URL, ולכן הבוט עולה במצב webhook
+ומאזין על PORT. מקומית, בלי WEBHOOK_URL, הוא עובר אוטומטית ל-polling.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from telegram import BotCommand
+from telegram.ext import Application, ApplicationBuilder
+
+from app import handlers
+from app.ai import Tutor
+from app.config import Config, load_config
+from app.storage import Storage
+
+logging.basicConfig(
+    format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+    level=logging.INFO,
+)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logger = logging.getLogger("pythonbot")
+
+COMMANDS = [
+    BotCommand("start", "התחלה"),
+    BotCommand("lessons", "תפריט השיעורים"),
+    BotCommand("next", "השיעור הבא"),
+    BotCommand("practice", "תרגיל"),
+    BotCommand("quiz", "חידון"),
+    BotCommand("ask", "שאלה חופשית על Python"),
+    BotCommand("progress", "ההתקדמות שלי"),
+    BotCommand("help", "עזרה"),
+]
+
+WEBHOOK_PATH = "telegram"
+
+
+def build_application(config: Config) -> Application:
+    storage = Storage(config.db_path)
+    tutor = Tutor(config.anthropic_api_key, config.claude_model)
+
+    async def on_startup(app: Application) -> None:
+        await storage.init()
+        await app.bot.set_my_commands(COMMANDS)
+        logger.info(
+            "הבוט מוכן | AI: %s | הרצת קוד: %s | מצב: %s",
+            "פעיל" if tutor.enabled else "כבוי",
+            "פעילה" if config.enable_code_runner else "כבויה",
+            "webhook" if config.use_webhook else "polling",
+        )
+
+    application = (
+        ApplicationBuilder()
+        .token(config.telegram_token)
+        .post_init(on_startup)
+        .build()
+    )
+    application.bot_data["storage"] = storage
+    application.bot_data["tutor"] = tutor
+    application.bot_data["enable_code_runner"] = config.enable_code_runner
+
+    handlers.register(application)
+    return application
+
+
+def main() -> int:
+    try:
+        config = load_config()
+    except RuntimeError as exc:
+        logger.error("%s", exc)
+        return 1
+
+    application = build_application(config)
+
+    if config.use_webhook:
+        url = f"{config.webhook_url}/{WEBHOOK_PATH}"
+        logger.info("מאזין ב-webhook על פורט %s", config.port)
+        application.run_webhook(
+            listen="0.0.0.0",
+            port=config.port,
+            url_path=WEBHOOK_PATH,
+            webhook_url=url,
+            secret_token=config.webhook_secret,
+            drop_pending_updates=True,
+            allowed_updates=["message", "callback_query"],
+        )
+    else:
+        logger.info("מצב polling (פיתוח מקומי)")
+        application.run_polling(
+            drop_pending_updates=True,
+            allowed_updates=["message", "callback_query"],
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000..4dc8d52
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,5 @@
+[pytest]
+testpaths = tests
+asyncio_mode = auto
+filterwarnings =
+    ignore::DeprecationWarning
diff --git a/render.yaml b/render.yaml
new file mode 100644
index 0000000..6d6fab3
--- /dev/null
+++ b/render.yaml
@@ -0,0 +1,30 @@
+# Render Blueprint - פריסה בלחיצה אחת.
+# ב-Render: New > Blueprint, בוחרים את הריפו הזה, ומגדירים את TELEGRAM_BOT_TOKEN.
+services:
+  - type: web
+    name: python-teacher-bot
+    runtime: python
+    plan: free
+    region: frankfurt
+    buildCommand: pip install -r requirements.txt
+    startCommand: python main.py
+    envVars:
+      - key: PYTHON_VERSION
+        value: "3.11.9"
+      # הטוקן מ-@BotFather. sync: false = מזינים אותו ידנית בדשבורד.
+      - key: TELEGRAM_BOT_TOKEN
+        sync: false
+      # אופציונלי: מפעיל /ask ובדיקת תרגילים חכמה.
+      - key: ANTHROPIC_API_KEY
+        sync: false
+      - key: CLAUDE_MODEL
+        value: claude-opus-5
+      # נוצר אוטומטית - מאמת שהעדכונים באמת הגיעו מטלגרם.
+      - key: WEBHOOK_SECRET
+        generateValue: true
+      - key: ENABLE_CODE_RUNNER
+        value: "false"
+      # בתוכנית החינמית אין דיסק קבוע; הנתונים נמחקים בכל דיפלוי.
+      # להתקדמות מתמשכת: שדרגו תוכנית, הוסיפו Disk ב-/var/data והציבו DATA_DIR=/var/data
+      - key: DATA_DIR
+        value: /tmp/pythonbot-data
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..1e44371
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+python-telegram-bot[webhooks]==22.8
+anthropic==1.7.0
+python-dotenv==1.1.1
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_content.py b/tests/test_content.py
new file mode 100644
index 0000000..6730358
--- /dev/null
+++ b/tests/test_content.py
@@ -0,0 +1,83 @@
+"""בדיקות תקינות לתוכן הקורס."""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from app.content import LESSONS, LESSONS_BY_ID, find_lesson, lesson_index, next_lesson
+
+ALLOWED_TAGS = {"b", "i", "u", "s", "code", "pre", "a"}
+TAG_RE = re.compile(r"</?([a-zA-Z0-9]+)")
+
+
+def _tags(text: str) -> set[str]:
+    return {match.lower() for match in TAG_RE.findall(text)}
+
+
+def test_lessons_exist_and_ids_are_unique():
+    assert len(LESSONS) >= 10
+    ids = [lesson.id for lesson in LESSONS]
+    assert len(ids) == len(set(ids))
+    assert len(LESSONS_BY_ID) == len(LESSONS)
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_lesson_fields_are_filled(lesson):
+    assert lesson.title and lesson.goal and lesson.body
+    assert lesson.example.strip()
+    assert lesson.exercise.prompt.strip()
+    assert lesson.exercise.hint.strip()
+    assert lesson.exercise.solution.strip()
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_only_telegram_safe_html(lesson):
+    """טלגרם תומך בתת-קבוצה קטנה של תגיות HTML בלבד."""
+    for field in (lesson.body, lesson.goal, lesson.exercise.prompt):
+        assert _tags(field) <= ALLOWED_TAGS, field
+    for quiz in lesson.quizzes:
+        assert _tags(quiz.question) <= ALLOWED_TAGS
+        assert _tags(quiz.explanation) <= ALLOWED_TAGS
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_examples_and_solutions_compile(lesson):
+    compile(lesson.example, f"{lesson.id}-example", "exec")
+    compile(lesson.exercise.solution, f"{lesson.id}-solution", "exec")
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_quizzes_are_valid(lesson):
+    assert lesson.quizzes, "לכל שיעור חייב להיות לפחות חידון אחד"
+    for quiz in lesson.quizzes:
+        assert len(quiz.options) >= 2
+        assert 0 <= quiz.answer < len(quiz.options)
+        assert quiz.explanation.strip()
+        assert len(set(quiz.options)) == len(quiz.options)
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_required_tokens_appear_in_reference_solution(lesson):
+    normalized = lesson.exercise.solution.replace(" ", "")
+    for token in lesson.exercise.required:
+        assert token.replace(" ", "") in normalized, (lesson.id, token)
+
+
+@pytest.mark.parametrize("lesson", LESSONS, ids=lambda lesson: lesson.id)
+def test_callback_data_fits_telegram_limit(lesson):
+    """callback_data מוגבל ל-64 בתים."""
+    for quiz_index, quiz in enumerate(lesson.quizzes):
+        for option_index in range(len(quiz.options)):
+            data = f"answer:{lesson.id}:{quiz_index}:{option_index}"
+            assert len(data.encode("utf-8")) <= 64, data
+
+
+def test_navigation_helpers():
+    assert lesson_index(LESSONS[0].id) == 0
+    assert lesson_index("nope") == -1
+    assert next_lesson(LESSONS[0].id) is LESSONS[1]
+    assert next_lesson(LESSONS[-1].id) is None
+    assert find_lesson(LESSONS[3].id) is LESSONS[3]
+    assert find_lesson("nope") is None
diff --git a/tests/test_flow.py b/tests/test_flow.py
new file mode 100644
index 0000000..f49c19b
--- /dev/null
+++ b/tests/test_flow.py
@@ -0,0 +1,274 @@
+"""בדיקות זרימה: מריצות את ההנדלרים האמיתיים מול טלגרם מדומה."""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from app import handlers
+from app.ai import Tutor
+from app.content import LESSONS
+from app.storage import Storage
+
+ALLOWED_TAGS = {"b", "i", "u", "s", "code", "pre", "a", "tg-spoiler", "blockquote"}
+USER_ID = 42
+
+
+class _TelegramHTMLValidator(HTMLParser):
+    """מוודא שהתגיות מאוזנות ושכולן נתמכות בטלגרם."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.stack: list[str] = []
+        self.problems: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag not in ALLOWED_TAGS:
+            self.problems.append(f"תגית לא נתמכת: {tag}")
+        self.stack.append(tag)
+
+    def handle_endtag(self, tag):
+        if not self.stack or self.stack.pop() != tag:
+            self.problems.append(f"סגירה לא תואמת: {tag}")
+
+
+def assert_valid_telegram_html(text: str) -> None:
+    validator = _TelegramHTMLValidator()
+    validator.feed(text)
+    assert not validator.problems, (validator.problems, text[:200])
+    assert not validator.stack, (validator.stack, text[:200])
+    assert len(text) <= handlers.TELEGRAM_LIMIT
+
+
+class FakeBot:
+    def __init__(self) -> None:
+        self.send_chat_action = AsyncMock()
+
+
+class Recorder:
+    """אוסף כל טקסט שהבוט שלח או ערך, ומאמת אותו."""
+
+    def __init__(self) -> None:
+        self.sent: list[str] = []
+
+    async def reply_html(self, text, **kwargs):
+        assert_valid_telegram_html(text)
+        self.sent.append(text)
+
+    async def edit_message_text(self, text, **kwargs):
+        assert_valid_telegram_html(text)
+        self.sent.append(text)
+
+    @property
+    def last(self) -> str:
+        assert self.sent, "הבוט לא שלח שום הודעה"
+        return self.sent[-1]
+
+
+def make_update(recorder: Recorder, *, text: str = "", callback: str | None = None):
+    message = SimpleNamespace(text=text, reply_html=recorder.reply_html)
+    message.reply_text = AsyncMock()
+    query = None
+    if callback is not None:
+        query = SimpleNamespace(
+            data=callback,
+            answer=AsyncMock(),
+            edit_message_text=recorder.edit_message_text,
+        )
+    return SimpleNamespace(
+        effective_message=message,
+        effective_user=SimpleNamespace(id=USER_ID, first_name="דנה", username="dana"),
+        effective_chat=SimpleNamespace(id=USER_ID),
+        callback_query=query,
+    )
+
+
+@pytest.fixture
+async def context(tmp_path):
+    storage = Storage(tmp_path / "flow.sqlite3")
+    await storage.init()
+    application = SimpleNamespace(
+        bot_data={
+            "storage": storage,
+            "tutor": Tutor(None),  # בלי מפתח - נתיב הבדיקה ההיוריסטית
+            "enable_code_runner": True,
+        }
+    )
+    return SimpleNamespace(
+        application=application,
+        bot_data=application.bot_data,
+        user_data={},
+        bot=FakeBot(),
+        args=[],
+    )
+
+
+async def test_start_greets_and_lists_lessons(context):
+    recorder = Recorder()
+    await handlers.start(make_update(recorder), context)
+    assert "דנה" in recorder.last
+    assert "רצף למידה" in recorder.last
+
+
+async def test_lesson_command_opens_the_requested_lesson(context):
+    recorder = Recorder()
+    context.args = ["3"]
+    await handlers.lesson_command(make_update(recorder), context)
+    assert LESSONS[2].title in recorder.last
+    assert context.user_data[handlers.CURRENT_KEY] == LESSONS[2].id
+
+
+async def test_lesson_command_rejects_out_of_range(context):
+    recorder = Recorder()
+    context.args = ["99"]
+    await handlers.lesson_command(make_update(recorder), context)
+    assert "יש שיעורים" in recorder.last
+
+
+async def test_every_lesson_renders_through_the_callback_router(context):
+    """המסלול המלא של כל שיעור: הסבר, דוגמה, תרגיל, רמז, פתרון וחידון."""
+    recorder = Recorder()
+    for lesson in LESSONS:
+        for action in ("lesson", "example", "exercise", "hint", "solution"):
+            await handlers.on_callback(
+                make_update(recorder, callback=f"{action}:{lesson.id}"), context
+            )
+        for index in range(len(lesson.quizzes)):
+            await handlers.on_callback(
+                make_update(recorder, callback=f"quiz:{lesson.id}:{index}"), context
+            )
+    assert len(recorder.sent) > len(LESSONS) * 5
+
+
+async def test_correct_quiz_answers_complete_the_lesson(context):
+    recorder = Recorder()
+    lesson = LESSONS[0]
+    for index, quiz in enumerate(lesson.quizzes):
+        await handlers.on_callback(
+            make_update(recorder, callback=f"answer:{lesson.id}:{index}:{quiz.answer}"),
+            context,
+        )
+    assert "נכון" in recorder.last
+    storage = context.bot_data["storage"]
+    assert lesson.id in await storage.completed_lessons(USER_ID)
+    assert (await storage.stats(USER_ID)).quiz_correct == len(lesson.quizzes)
+
+
+async def test_wrong_quiz_answer_explains_without_completing(context):
+    recorder = Recorder()
+    lesson = LESSONS[1]
+    quiz = lesson.quizzes[0]
+    wrong = (quiz.answer + 1) % len(quiz.options)
+    await handlers.on_callback(
+        make_update(recorder, callback=f"answer:{lesson.id}:0:{wrong}"), context
+    )
+    assert "לא מדויק" in recorder.last
+    assert quiz.explanation.split("<")[0][:20] in recorder.last
+    assert lesson.id not in await context.bot_data["storage"].completed_lessons(USER_ID)
+
+
+async def test_exercise_submission_runs_and_passes(context):
+    recorder = Recorder()
+    lesson = next(l for l in LESSONS if l.exercise.expected_output == "75")
+    await handlers.on_callback(
+        make_update(recorder, callback=f"exercise:{lesson.id}"), context
+    )
+    assert context.user_data[handlers.AWAITING_KEY] == lesson.id
+
+    await handlers.on_text(
+        make_update(recorder, text=lesson.exercise.solution), context
+    )
+    assert "יפה מאוד" in recorder.last
+    assert handlers.AWAITING_KEY not in context.user_data
+    assert (await context.bot_data["storage"].stats(USER_ID)).exercises_passed == 1
+
+
+async def test_wrong_output_keeps_the_exercise_open(context):
+    recorder = Recorder()
+    lesson = next(l for l in LESSONS if l.exercise.expected_output == "75")
+    context.user_data[handlers.AWAITING_KEY] = lesson.id
+
+    await handlers.on_text(make_update(recorder, text="print(1)"), context)
+    assert "ציפיתי לפלט" in recorder.last
+    assert context.user_data[handlers.AWAITING_KEY] == lesson.id
+
+
+async def test_broken_code_is_reported_not_crashed(context):
+    recorder = Recorder()
+    lesson = LESSONS[1]
+    context.user_data[handlers.AWAITING_KEY] = lesson.id
+
+    await handlers.on_text(make_update(recorder, text="print(1/0)"), context)
+    assert "לא רץ בהצלחה" in recorder.last
+    assert "ZeroDivisionError" in recorder.last
+
+
+async def test_markdown_fences_in_submissions_are_stripped(context):
+    recorder = Recorder()
+    lesson = next(l for l in LESSONS if l.exercise.expected_output == "75")
+    context.user_data[handlers.AWAITING_KEY] = lesson.id
+
+    fenced = f"```python\n{lesson.exercise.solution}```"
+    await handlers.on_text(make_update(recorder, text=fenced), context)
+    assert "יפה מאוד" in recorder.last
+
+
+async def test_question_without_ai_explains_the_limitation(context):
+    recorder = Recorder()
+    await handlers.on_text(make_update(recorder, text="מה זה לולאה?"), context)
+    assert "ANTHROPIC_API_KEY" in recorder.last
+
+
+async def test_progress_reports_real_numbers(context):
+    recorder = Recorder()
+    storage = context.bot_data["storage"]
+    await storage.touch_user(USER_ID)
+    await storage.complete_lesson(USER_ID, LESSONS[0].id)
+    await storage.record_quiz_answer(USER_ID, LESSONS[0].id, 0, True)
+
+    await handlers.progress_command(make_update(recorder), context)
+    assert f"1/{len(LESSONS)}" in recorder.last
+    assert "1/1 נכון (100%)" in recorder.last
+
+
+async def test_next_command_skips_completed_lessons(context):
+    recorder = Recorder()
+    await context.bot_data["storage"].complete_lesson(USER_ID, LESSONS[0].id)
+    await handlers.next_command(make_update(recorder), context)
+    assert LESSONS[1].title in recorder.last
+
+
+async def test_reset_flow_clears_progress(context):
+    recorder = Recorder()
+    storage = context.bot_data["storage"]
+    await storage.complete_lesson(USER_ID, LESSONS[0].id)
+
+    await handlers.reset_command(make_update(recorder), context)
+    assert "לאפס" in recorder.last
+
+    await handlers.on_callback(make_update(recorder, callback="reset:yes"), context)
+    assert "אופסה" in recorder.last
+    assert await storage.completed_lessons(USER_ID) == set()
+
+
+async def test_unknown_lesson_in_callback_is_handled(context):
+    recorder = Recorder()
+    await handlers.on_callback(make_update(recorder, callback="lesson:nope"), context)
+    assert "לא מצאתי" in recorder.last
+
+
+async def test_run_command_reports_output(context):
+    recorder = Recorder()
+    update = make_update(recorder, text="/run print(6 * 7)")
+    await handlers.run_command(update, context)
+    assert "42" in recorder.last
+
+
+async def test_run_command_blocks_dangerous_code(context):
+    recorder = Recorder()
+    update = make_update(recorder, text="/run import os\nos.listdir('/')")
+    await handlers.run_command(update, context)
+    assert "חסום" in recorder.last
diff --git a/tests/test_helpers.py b/tests/test_helpers.py
new file mode 100644
index 0000000..dfdb090
--- /dev/null
+++ b/tests/test_helpers.py
@@ -0,0 +1,102 @@
+"""בדיקות לעיבוד טקסט, לבדיקה ההיוריסטית ולפענוח תשובות המודל."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.ai import AIUnavailable, _parse_grade
+from app.content import LESSONS_BY_ID
+from app.handlers import (
+    TELEGRAM_LIMIT,
+    _chunks,
+    _looks_like_code,
+    _markdown_code_to_html,
+    _strip_fences,
+    heuristic_grade,
+)
+
+
+def test_short_text_is_not_split():
+    assert _chunks("שלום") == ["שלום"]
+
+
+def test_long_text_is_split_under_the_limit():
+    text = "\n".join(f"שורה מספר {i}" for i in range(2000))
+    parts = _chunks(text)
+    assert len(parts) > 1
+    assert all(len(part) <= TELEGRAM_LIMIT for part in parts)
+    assert "".join(part.replace("\n", "") for part in parts) == text.replace("\n", "")
+
+
+def test_text_without_newlines_is_still_split():
+    parts = _chunks("א" * (TELEGRAM_LIMIT * 2 + 5))
+    assert len(parts) == 3
+    assert all(len(part) <= TELEGRAM_LIMIT for part in parts)
+
+
+def test_strip_fences_removes_markdown_wrapper():
+    assert _strip_fences("```python\nprint(1)\n```") == "print(1)"
+    assert _strip_fences("```\nprint(1)\n```") == "print(1)"
+    assert _strip_fences("print(1)") == "print(1)"
+
+
+def test_looks_like_code_detects_multiline_snippets():
+    assert _looks_like_code("for i in range(3):\n    print(i)")
+    assert _looks_like_code("```print(1)```")
+    assert not _looks_like_code("מה זה לולאה?")
+    assert not _looks_like_code("איך עושים if בפייתון")
+
+
+def test_markdown_is_converted_to_telegram_html():
+    converted = _markdown_code_to_html(
+        "הנה **דוגמה**:\n```python\nif 1 < 2:\n    print('כן')\n```\nוזה `int`"
+    )
+    assert "<b>דוגמה</b>" in converted
+    assert "<pre><code>" in converted and "</code></pre>" in converted
+    assert "1 &lt; 2" in converted  # סימני < בתוך קוד חייבים לברוח
+    assert "<code>int</code>" in converted
+
+
+def test_unclosed_code_fence_is_closed():
+    assert _markdown_code_to_html("```\nprint(1)").endswith("</code></pre>")
+
+
+def test_raw_html_from_the_model_is_escaped():
+    assert "<script>" not in _markdown_code_to_html("<script>alert(1)</script>")
+
+
+def test_heuristic_grade_accepts_the_reference_solution():
+    lesson = LESSONS_BY_ID["02-variables"]
+    assert heuristic_grade(lesson, lesson.exercise.solution).passed
+
+
+def test_heuristic_grade_rejects_syntax_errors():
+    lesson = LESSONS_BY_ID["02-variables"]
+    grade = heuristic_grade(lesson, "price = 100\nprint(price")
+    assert not grade.passed and "תחביר" in grade.feedback
+
+
+def test_heuristic_grade_reports_missing_pieces():
+    lesson = LESSONS_BY_ID["02-variables"]
+    grade = heuristic_grade(lesson, "price = 100")
+    assert not grade.passed and "discount" in grade.feedback
+
+
+def test_parse_grade_reads_plain_json():
+    grade = _parse_grade('{"passed": true, "feedback": "יפה"}')
+    assert grade.passed and grade.feedback == "יפה"
+
+
+def test_parse_grade_reads_json_inside_a_code_fence():
+    grade = _parse_grade('```json\n{"passed": false, "feedback": "חסר return"}\n```')
+    assert not grade.passed and grade.feedback == "חסר return"
+
+
+def test_parse_grade_reads_json_with_surrounding_prose():
+    grade = _parse_grade('בדקתי:\n{"passed": true, "feedback": "נכון"}\nבהצלחה')
+    assert grade.passed
+
+
+def test_parse_grade_raises_on_garbage():
+    with pytest.raises(AIUnavailable):
+        _parse_grade("אין לי מושג")
diff --git a/tests/test_runner.py b/tests/test_runner.py
new file mode 100644
index 0000000..399d159
--- /dev/null
+++ b/tests/test_runner.py
@@ -0,0 +1,49 @@
+"""בדיקות למריץ הקוד המוגבל ולבדיקת הפתרונות לדוגמה."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.content import LESSONS
+from app.runner import check_code, run_code
+
+SOLUTIONS_WITH_OUTPUT = [
+    lesson
+    for lesson in LESSONS
+    if lesson.exercise.expected_output is not None
+    and "input(" not in lesson.exercise.solution
+]
+
+
+@pytest.mark.parametrize(
+    "lesson", SOLUTIONS_WITH_OUTPUT, ids=lambda lesson: lesson.id
+)
+async def test_reference_solution_produces_expected_output(lesson):
+    result = await run_code(lesson.exercise.solution)
+    assert result.ok, result.combined
+    assert result.output.strip() == lesson.exercise.expected_output.strip()
+
+
+def test_blocks_dangerous_imports():
+    assert check_code("import os") is not None
+    assert check_code("from subprocess import run") is not None
+    assert check_code("open('/etc/passwd')") is not None
+    assert check_code("print('hi')") is None
+
+
+def test_reports_syntax_errors_before_running():
+    problem = check_code("print('hi'")
+    assert problem is not None and "תחביר" in problem
+
+
+async def test_runaway_loop_is_stopped():
+    result = await run_code("while True:\n    pass")
+    assert not result.ok
+    assert "מגבלות" in result.error or "זמן" in result.error
+
+
+async def test_runtime_error_is_reported_briefly():
+    result = await run_code("print(1 / 0)")
+    assert not result.ok
+    assert "ZeroDivisionError" in result.error
+    assert result.error.count("\n") == 0
diff --git a/tests/test_storage.py b/tests/test_storage.py
new file mode 100644
index 0000000..f71f2f1
--- /dev/null
+++ b/tests/test_storage.py
@@ -0,0 +1,69 @@
+"""בדיקות לשכבת האחסון."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.storage import Storage
+
+
+@pytest.fixture
+async def storage(tmp_path):
+    store = Storage(tmp_path / "test.sqlite3")
+    await store.init()
+    return store
+
+
+async def test_new_user_starts_with_streak_one(storage):
+    assert await storage.touch_user(1, "דנה", "dana") == 1
+    assert await storage.touch_user(1, "דנה", "dana") == 1
+
+
+async def test_lesson_completion_is_idempotent(storage):
+    await storage.touch_user(2)
+    await storage.complete_lesson(2, "01-hello")
+    await storage.complete_lesson(2, "01-hello")
+    await storage.complete_lesson(2, "02-variables")
+
+    assert await storage.completed_lessons(2) == {"01-hello", "02-variables"}
+    assert (await storage.stats(2)).lessons_done == 2
+
+
+async def test_quiz_stats_are_accumulated(storage):
+    await storage.touch_user(3)
+    await storage.record_quiz_answer(3, "01-hello", 0, True)
+    await storage.record_quiz_answer(3, "01-hello", 1, False)
+    await storage.record_quiz_answer(3, "02-variables", 0, True)
+
+    stats = await storage.stats(3)
+    assert stats.quiz_total == 3
+    assert stats.quiz_correct == 2
+    assert stats.quiz_accuracy == 67
+
+
+async def test_exercise_pass_is_sticky(storage):
+    await storage.touch_user(4)
+    await storage.record_exercise(4, "05-conditions", False)
+    await storage.record_exercise(4, "05-conditions", True)
+    await storage.record_exercise(4, "05-conditions", False)
+
+    assert (await storage.stats(4)).exercises_passed == 1
+
+
+async def test_reset_clears_progress_only_for_that_user(storage):
+    await storage.touch_user(5)
+    await storage.touch_user(6)
+    await storage.complete_lesson(5, "01-hello")
+    await storage.complete_lesson(6, "01-hello")
+
+    await storage.reset(5)
+
+    assert await storage.completed_lessons(5) == set()
+    assert await storage.completed_lessons(6) == {"01-hello"}
+
+
+async def test_stats_for_unknown_user_are_empty(storage):
+    stats = await storage.stats(999)
+    assert stats.lessons_done == 0
+    assert stats.quiz_accuracy == 0
+    assert stats.streak == 0
diff --git a/tests/test_wiring.py b/tests/test_wiring.py
new file mode 100644
index 0000000..b1e97e3
--- /dev/null
+++ b/tests/test_wiring.py
@@ -0,0 +1,123 @@
+"""בדיקות חיווט: שהאפליקציה נבנית ושכל כפתור מוביל לפעולה מוכרת."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from telegram.ext import CallbackQueryHandler, CommandHandler, MessageHandler
+
+import main
+from app.config import Config
+from app.content import LESSONS
+from app import keyboards as kb
+
+FAKE_TOKEN = "123456789:AAExampleTokenForTestsOnly_0000000000000"
+
+KNOWN_ACTIONS = {
+    kb.CB_LESSON,
+    kb.CB_EXAMPLE,
+    kb.CB_EXERCISE,
+    kb.CB_SOLUTION,
+    kb.CB_HINT,
+    kb.CB_QUIZ,
+    kb.CB_ANSWER,
+    kb.CB_NEXT,
+    kb.CB_MENU,
+    "reset",
+}
+
+
+@pytest.fixture
+def config(tmp_path: Path) -> Config:
+    return Config(
+        telegram_token=FAKE_TOKEN,
+        anthropic_api_key=None,
+        claude_model="claude-opus-5",
+        webhook_url=None,
+        webhook_secret=None,
+        port=10000,
+        data_dir=tmp_path,
+        enable_code_runner=False,
+    )
+
+
+def _all_callback_data() -> list[str]:
+    data: list[str] = ["reset:yes", "reset:no"]
+    for lesson in LESSONS:
+        markups = [
+            kb.lesson_keyboard(lesson),
+            kb.example_keyboard(lesson),
+            kb.exercise_keyboard(lesson),
+            kb.menu_keyboard({lesson.id}),
+        ]
+        for index in range(len(lesson.quizzes)):
+            markups.append(kb.quiz_keyboard(lesson, index))
+            markups.append(kb.after_quiz_keyboard(lesson, index))
+        for markup in markups:
+            for row in markup.inline_keyboard:
+                for button in row:
+                    if button.callback_data:
+                        data.append(button.callback_data)
+    return data
+
+
+def test_application_builds_with_all_handlers(config):
+    application = main.build_application(config)
+    handlers = application.handlers[0]
+
+    assert any(isinstance(handler, CallbackQueryHandler) for handler in handlers)
+    assert any(isinstance(handler, MessageHandler) for handler in handlers)
+
+    commands = {
+        name
+        for handler in handlers
+        if isinstance(handler, CommandHandler)
+        for name in handler.commands
+    }
+    assert {
+        "start", "help", "lessons", "lesson", "next", "quiz",
+        "practice", "progress", "ask", "run", "cancel", "reset",
+    } <= commands
+
+    assert application.bot_data["enable_code_runner"] is False
+    assert application.bot_data["tutor"].enabled is False
+
+
+def test_menu_commands_are_registered_handlers(config):
+    application = main.build_application(config)
+    registered = {
+        name
+        for handler in application.handlers[0]
+        if isinstance(handler, CommandHandler)
+        for name in handler.commands
+    }
+    for command in main.COMMANDS:
+        assert command.command in registered
+
+
+def test_every_button_maps_to_a_known_action():
+    for data in _all_callback_data():
+        action = data.split(":")[0]
+        assert action in KNOWN_ACTIONS, data
+
+
+def test_callback_data_stays_within_telegram_limit():
+    for data in _all_callback_data():
+        assert len(data.encode("utf-8")) <= 64, data
+
+
+def test_quiz_buttons_cover_every_option():
+    lesson = LESSONS[0]
+    markup = kb.quiz_keyboard(lesson, 0)
+    assert len(markup.inline_keyboard) == len(lesson.quizzes[0].options)
+
+
+def test_last_lesson_has_no_next_button():
+    markup = kb.lesson_keyboard(LESSONS[-1])
+    data = [
+        button.callback_data
+        for row in markup.inline_keyboard
+        for button in row
+    ]
+    assert not any(item.startswith(f"{kb.CB_NEXT}:") for item in data)