learnx-cli 0.3.0__py3-none-any.whl

tutor/sample_docs/java-basics.md

@@ -0,0 +1,78 @@
+# Java Fundamentals
+
+## How the JVM Works
+
+Java source code is compiled by `javac` into bytecode — `.class` files. The JVM
+(Java Virtual Machine) loads and executes bytecode. This means Java is
+"write once, run anywhere": the same `.class` file runs on any OS that has a JVM.
+
+The JVM uses a JIT (Just-In-Time) compiler to convert hot bytecode paths into
+native machine code at runtime. First execution is interpreted; repeated calls
+get compiled to native for speed.
+
+Memory is divided into the stack (local variables, method calls) and the heap
+(objects). When you write `int x = 5`, x lives on the stack. When you write
+`new Object()`, that object lives on the heap.
+
+## Primitive vs Reference Types
+
+Java has 8 primitive types: `int`, `long`, `double`, `float`, `boolean`,
+`char`, `byte`, `short`. Primitives live on the stack and hold values directly.
+
+Reference types (everything else) are objects. A variable of a reference type
+holds a memory address — a pointer to where the object lives on the heap. The
+variable is not the object; it points to the object.
+
+## Pass-by-Value
+
+Java is strictly pass-by-value. When you pass a variable to a method, Java
+copies the value of that variable into the parameter. For primitives, this is
+the actual number. For reference types, this is the memory address.
+
+This means: reassigning a parameter inside a method does NOT affect the
+caller's variable. But mutating the object via the reference (e.g., calling
+`list.add()`) DOES affect the caller, because both the original and the copy
+point to the same heap object.
+
+## String Equality
+
+Strings in Java are objects. The `==` operator compares references (memory
+addresses), not content. Two String variables can hold the same text but be
+different objects, so `==` returns `false`.
+
+Use `.equals()` to compare String content:
+
+```java
+String a = new String("hello");
+String b = new String("hello");
+a == b        // false — different objects
+a.equals(b)   // true — same content
+```
+
+String literals are interned: `"hello" == "hello"` may return `true` due to
+the string pool. Do not rely on this. Always use `.equals()`.
+
+## The final Keyword
+
+`final` on a variable means the variable cannot be reassigned. It does NOT
+make the object immutable.
+
+```java
+final List<String> names = new ArrayList<>();
+names = new ArrayList<>();   // compile error — reassignment blocked
+names.add("Alice");          // fine — mutation allowed
+```
+
+`final` on a method prevents overriding. `final` on a class prevents subclassing.
+
+## Checked vs Unchecked Exceptions
+
+Checked exceptions extend `Exception` directly. The compiler forces you to
+either catch them or declare them in the method signature with `throws`.
+Example: `IOException`, `SQLException`.
+
+Unchecked exceptions extend `RuntimeException`. The compiler does not require
+handling. Example: `NullPointerException`, `IllegalArgumentException`.
+
+The rule: use checked exceptions for recoverable conditions the caller should
+handle. Use unchecked for programming errors that should not occur.

tutor/tests/audio/test_audio_builder.py

@@ -0,0 +1,106 @@
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+from pydub import AudioSegment
+
+from tutor.audio.audio_builder import _assemble
+from tutor.constants import SILENCE_BREATH_MS, SILENCE_TURN_MS
+from tutor.models import DialogueLine, RenderedSegment
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+CLIP_MS = 1000  # fake MP3 duration returned by the mock
+
+
+def _line(unit: int, speaker: str, text: str = "test line") -> DialogueLine:
+    return DialogueLine(speaker=speaker, text=text, unit_number=unit)
+
+
+def _seg(line: DialogueLine) -> RenderedSegment:
+    return RenderedSegment(line=line, audio_path="dummy.mp3", duration_ms=CLIP_MS)
+
+
+def _run_assemble(tmp_path: Path, segments: list[RenderedSegment]) -> dict:
+    """Run _assemble() with mocked I/O; return parsed timing JSON."""
+    out_path = tmp_path / "tutorial.mp3"
+    units_dir = tmp_path / "units"
+    units_dir.mkdir()
+
+    with (
+        patch(
+            "tutor.audio.audio_builder.AudioSegment.from_mp3",
+            return_value=AudioSegment.silent(duration=CLIP_MS),
+        ),
+        patch.object(AudioSegment, "export"),
+    ):
+        _assemble(segments, str(out_path), str(units_dir))
+
+    return json.loads((tmp_path / "tutorial.timing.json").read_text())
+
+
+# ── tests ─────────────────────────────────────────────────────────────────────
+
+
+def test_timing_file_written_after_build(tmp_path):
+    segs = [_seg(_line(1, "ALEX")), _seg(_line(1, "MAYA"))]
+    _run_assemble(tmp_path, segs)
+    assert (tmp_path / "tutorial.timing.json").exists()
+
+
+def test_timing_version_field_is_1(tmp_path):
+    segs = [_seg(_line(1, "ALEX")), _seg(_line(1, "MAYA"))]
+    data = _run_assemble(tmp_path, segs)
+    assert data["version"] == 1
+
+
+def test_timing_keys_are_string_integers(tmp_path):
+    segs = [_seg(_line(1, "ALEX")), _seg(_line(2, "ALEX"))]
+    data = _run_assemble(tmp_path, segs)
+    keys = set(data["units"].keys())
+    assert "1" in keys
+    assert "2" in keys
+    assert not any("unit_" in k for k in keys)
+
+
+def test_timing_keys_match_teaching_units(tmp_path):
+    segs = [
+        _seg(_line(0, "ALEX")),  # intro — excluded
+        _seg(_line(1, "ALEX")),
+        _seg(_line(1, "MAYA")),
+        _seg(_line(2, "ALEX")),
+        _seg(_line(-1, "ALEX")),  # outro — excluded
+    ]
+    data = _run_assemble(tmp_path, segs)
+    units = data["units"]
+    assert "1" in units
+    assert "2" in units
+    assert "0" not in units
+    assert "-1" not in units
+
+
+def test_timing_offsets_no_gaps_no_overlaps(tmp_path):
+    segs = [
+        _seg(_line(1, "ALEX", "First line")),
+        _seg(_line(1, "MAYA", "Second line")),
+        _seg(_line(1, "ALEX", "Third line")),
+    ]
+    data = _run_assemble(tmp_path, segs)
+    entries = data["units"]["1"]
+    for i in range(len(entries) - 1):
+        cur, nxt = entries[i], entries[i + 1]
+        gap = SILENCE_BREATH_MS if cur["speaker"] == nxt["speaker"] else SILENCE_TURN_MS
+        assert nxt["start_ms"] == cur["end_ms"] + gap
+
+
+def test_timing_duration_matches_pydub_len(tmp_path):
+    segs = [_seg(_line(1, "ALEX")), _seg(_line(1, "MAYA"))]
+    data = _run_assemble(tmp_path, segs)
+    for entry in data["units"]["1"]:
+        assert entry["end_ms"] - entry["start_ms"] == CLIP_MS
+
+
+def test_intro_and_outro_excluded_from_timing(tmp_path):
+    segs = [_seg(_line(0, "ALEX")), _seg(_line(-1, "ALEX"))]
+    data = _run_assemble(tmp_path, segs)
+    assert data["units"] == {}

tutor/tests/audio/test_sanitizer.py

@@ -0,0 +1,41 @@
+from tutor.audio.sanitizer import apply
+
+
+def test_list_of_strings():
+    assert apply("Use List<String> here") == "Use a List of Strings here"
+
+
+def test_hashmap():
+    assert apply("HashMap<String, Integer>") == "a HashMap from String to Integer"
+
+
+def test_not_equal():
+    assert apply("if (a != b)") == "if (a not equal to b)"
+
+
+def test_double_equals():
+    assert apply("if (a == b)") == "if (a double equals b)"
+
+
+def test_annotation():
+    assert apply("@Override") == "Override annotation"
+
+
+def test_int_array():
+    assert apply("int[] arr") == "int array arr"
+
+
+def test_null_pointer():
+    assert apply("throws NullPointerException") == "throws Null Pointer Exception"
+
+
+def test_no_change():
+    result = apply("Java is a statically typed language")
+    assert result == "Java is a statically typed language"
+
+
+def test_multiple_substitutions():
+    result = apply("List<String> with != and ==")
+    assert "a List of Strings" in result
+    assert "not equal to" in result
+    assert "double equals" in result

tutor/tests/cli/test_commands.py

@@ -0,0 +1,67 @@
+import json
+
+from tutor.cli.commands import _format_duration, _read_meta
+
+
+def test_read_meta_returns_empty_on_missing_file(tmp_path):
+    result = _read_meta(tmp_path / "nonexistent.meta.json")
+    assert result == {}
+
+
+def test_read_meta_returns_empty_on_invalid_json(tmp_path):
+    bad = tmp_path / "bad.meta.json"
+    bad.write_text("not json", encoding="utf-8")
+    result = _read_meta(bad)
+    assert result == {}
+
+
+def test_read_meta_returns_dict_on_valid_file(tmp_path):
+    meta_file = tmp_path / "tutorial.meta.json"
+    data = {
+        "source_file": "week2/3.md",
+        "generated_at": "2026-05-09T14:32:11",
+        "total_duration_s": 1574.3,
+    }
+    meta_file.write_text(json.dumps(data), encoding="utf-8")
+    result = _read_meta(meta_file)
+    assert result["source_file"] == "week2/3.md"
+    assert result["total_duration_s"] == 1574.3
+
+
+def test_format_duration_zero_returns_blank():
+    assert _format_duration(0) == ""
+
+
+def test_format_duration_negative_returns_blank():
+    assert _format_duration(-5) == ""
+
+
+def test_format_duration_correct_formatting():
+    assert _format_duration(3674.0) == "61:14"
+
+
+def test_format_duration_simple():
+    assert _format_duration(90) == "1:30"
+
+
+def test_sessions_output_handles_missing_meta(tmp_path, capsys):
+    from pathlib import Path
+    from unittest.mock import patch
+
+    from tutor.cli.commands import cmd_sessions
+
+    session_dir = tmp_path / "test_session"
+    (session_dir / "tutorial_units").mkdir(parents=True)
+
+    with (
+        patch.object(Path, "exists", return_value=True),
+        patch("tutor.cli.commands.AUDIO_DIR", tmp_path),
+        patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path / "video"),
+    ):
+        from tutor.cli.commands import ShellContext
+
+        ctx = ShellContext()
+        cmd_sessions([], ctx)
+
+    captured = capsys.readouterr()
+    assert "test_session" in captured.out

tutor/tests/cli/test_video_commands.py

@@ -0,0 +1,190 @@
+"""Tests for tutor/cli/video_commands.py."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from tutor.cli.commands import ShellContext
+from tutor.cli.video_commands import (
+    _assert_audio_ready,
+    _confirm_overwrite,
+    cmd_video,
+    cmd_vsessions,
+)
+
+
+def _ctx(**kwargs) -> ShellContext:
+    ctx = ShellContext()
+    for k, v in kwargs.items():
+        setattr(ctx, k, v)
+    return ctx
+
+
+# ── _assert_audio_ready ──────────────────────────────────────────────────────
+
+
+def test_cmd_video_missing_units_json(tmp_path):
+    """Audio dir exists, tutorial_units has MP3s, but no tutorial.units.json → ValueError."""
+    audio_dir = tmp_path / "audio" / "test_session"
+    units_dir = audio_dir / "tutorial_units"
+    units_dir.mkdir(parents=True)
+    (units_dir / "unit_01.mp3").touch()
+    # No tutorial.units.json
+
+    with pytest.raises(ValueError, match="tutorial.units.json"):
+        _assert_audio_ready(audio_dir)
+
+
+def test_cmd_video_unknown_session(tmp_path, capsys):
+    """Session not in audio/ → prints error, does not crash."""
+    with patch("tutor.cli.video_commands.AUDIO_DIR", tmp_path / "audio"):
+        ctx = _ctx()
+        cmd_video(["nonexistent_session"], ctx)
+        out = capsys.readouterr().out
+        assert "Error" in out or "not found" in out
+
+
+def test_assert_audio_ready_no_mp3s(tmp_path):
+    """audio dir exists with units.json but no MP3s → ValueError."""
+    audio_dir = tmp_path / "audio" / "sess"
+    units_dir = audio_dir / "tutorial_units"
+    units_dir.mkdir(parents=True)
+    (audio_dir / "tutorial.units.json").write_text("[]")
+
+    with pytest.raises(ValueError, match="No MP3"):
+        _assert_audio_ready(audio_dir)
+
+
+# ── session context inference ─────────────────────────────────────────────────
+
+
+def test_cmd_video_infers_session_from_context(capsys):
+    """ctx.current_session set, no arg → uses it (errors out at audio check)."""
+    ctx = _ctx(current_session="week2_3")
+    with patch("tutor.cli.video_commands.AUDIO_DIR", Path("/nonexistent")):
+        cmd_video([], ctx)
+    out = capsys.readouterr().out
+    # Should attempt to use "week2_3" and fail at audio check, not usage error
+    assert "Usage: /video" not in out
+
+
+def test_cmd_video_no_session_no_context_prints_usage(capsys):
+    """No arg and no current_session → prints usage."""
+    ctx = _ctx()
+    cmd_video([], ctx)
+    out = capsys.readouterr().out
+    assert "Usage" in out
+
+
+# ── overwrite prompt ──────────────────────────────────────────────────────────
+
+
+def test_cmd_video_prompts_before_overwrite(tmp_path, capsys):
+    """full_session.mp4 exists → ask before overwriting; 'n' → skip."""
+    # Set up a fake complete audio session
+    audio_dir = tmp_path / "audio" / "test_sess"
+    units_dir = audio_dir / "tutorial_units"
+    units_dir.mkdir(parents=True)
+    (units_dir / "unit_01.mp3").touch()
+    (audio_dir / "tutorial.units.json").write_text("[]")
+
+    # Pre-existing video
+    video_dir = tmp_path / "video" / "test_sess"
+    video_dir.mkdir(parents=True)
+    mp4 = video_dir / "full_session.mp4"
+    mp4.touch()
+
+    with (
+        patch("tutor.cli.video_commands.AUDIO_DIR", tmp_path / "audio"),
+        patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path / "video"),
+        patch("builtins.input", return_value="n"),
+    ):
+        ctx = _ctx()
+        cmd_video(["test_sess"], ctx)
+
+    out = capsys.readouterr().out
+    assert "Skipped" in out
+
+
+def test_confirm_overwrite_yes(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "y")
+    assert _confirm_overwrite(Path("dummy.mp4")) is True
+
+
+def test_confirm_overwrite_no(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "n")
+    assert _confirm_overwrite(Path("dummy.mp4")) is False
+
+
+# ── cmd_vsessions ─────────────────────────────────────────────────────────────
+
+
+def test_sessions_shows_mp4_badge(tmp_path, capsys):
+    """Session dir with full_session.mp4 → '[mp4]' in output."""
+    sess = tmp_path / "week2_3"
+    sess.mkdir()
+    mp4 = sess / "full_session.mp4"
+    mp4.write_bytes(b"x" * 1024)  # 1 KB fake MP4
+
+    with patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path):
+        cmd_vsessions([], _ctx())
+
+    out = capsys.readouterr().out
+    assert "[mp4]" in out
+    assert "week2_3" in out
+
+
+def test_sessions_no_output_when_empty(tmp_path, capsys):
+    """No completed videos → dim message."""
+    with patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path):
+        cmd_vsessions([], _ctx())
+    out = capsys.readouterr().out
+    assert "[mp4]" not in out
+
+
+# ── sessions badge in cmd_sessions ───────────────────────────────────────────
+
+
+def test_sessions_command_shows_mp4_badge(tmp_path, capsys):
+    """cmd_sessions shows [mp4] when video/<session>/full_session.mp4 exists."""
+    from tutor.cli.commands import cmd_sessions
+
+    audio_dir = tmp_path / "audio"
+    sess = audio_dir / "test_sess"
+    units_dir = sess / "tutorial_units"
+    units_dir.mkdir(parents=True)
+    (units_dir / "unit_01.mp3").touch()
+
+    video_dir = tmp_path / "video" / "test_sess"
+    video_dir.mkdir(parents=True)
+    (video_dir / "full_session.mp4").touch()
+
+    with (
+        patch("tutor.cli.commands.AUDIO_DIR", audio_dir),
+        patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path / "video"),
+    ):
+        cmd_sessions([], _ctx())
+
+    out = capsys.readouterr().out
+    assert "[video]" in out
+
+
+def test_sessions_no_badge_without_mp4(tmp_path, capsys):
+    """cmd_sessions shows no [video] when MP4 is absent."""
+    from tutor.cli.commands import cmd_sessions
+
+    audio_dir = tmp_path / "audio"
+    sess = audio_dir / "test_sess"
+    units_dir = sess / "tutorial_units"
+    units_dir.mkdir(parents=True)
+    (units_dir / "unit_01.mp3").touch()
+
+    with (
+        patch("tutor.cli.commands.AUDIO_DIR", audio_dir),
+        patch("tutor.cli.video_commands.VIDEO_DIR", tmp_path / "video"),
+    ):
+        cmd_sessions([], _ctx())
+
+    out = capsys.readouterr().out
+    assert "[video]" not in out

tutor/tests/e2e/README.md

@@ -0,0 +1,61 @@
+# E2E Smoke Tests
+
+## What These Tests Verify
+
+The unit test suite mocks all LLM and audio calls. These smoke tests run the **real
+pipeline** on a small committed fixture and assert on actual output files. They exist
+because several bugs passed all unit tests but were caught here:
+
+| Bug | Caught by |
+|-----|-----------|
+| Silent audio in output video (loudnorm / encoding bug) | `test_audio_stream_present`, `test_audio_not_silent` |
+| Blank slides / CSS not loaded | `test_slide_page_not_blank`, `test_slide_has_visible_text` |
+| Pipeline crash on real markdown input | `test_pipeline_exits_zero` |
+| A/V timing drift (estimation instead of actual) | `test_timing_end_matches_audio_duration` |
+| Video file has no audio stream | `test_audio_stream_present` |
+
+## How to Run
+
+```powershell
+# Windows (PowerShell)
+py -m pytest tutor/tests/e2e/ -v           # E2E tests only
+py -m pytest tutor/tests/ --ignore=tutor/tests/e2e/ -v   # unit tests only
+py -m pytest tutor/tests/ -v               # full suite
+py -m ruff check tutor/
+py -m ruff format --check tutor/
+```
+
+```bash
+# macOS / Linux
+python -m pytest tutor/tests/e2e/ -v
+python -m pytest tutor/tests/ --ignore=tutor/tests/e2e/ -v
+python -m pytest tutor/tests/ -v
+python -m ruff check tutor/
+python -m ruff format --check tutor/
+```
+
+## Requirements
+
+- **Internet connection** — TTS (edge-tts) runs for real; the LLM is mocked
+- **ffmpeg + ffprobe** — must be on PATH or in a standard Windows install location;
+  required by pydub (audio loading) and `test_video_streams.py` stream checks
+- **Playwright Chromium** — required by `test_slide_render.py`;
+  install with `playwright install chromium` (already done in Docker image)
+- **No API key needed** — `GROQ_API_KEY` is injected as a dummy value by conftest.py
+
+## Why the Fixture Is Small
+
+`tutor/tests/e2e/fixtures/sample.md` is a 3-paragraph document (~100 words). E2E
+tests are slow because they call real TTS. A single-unit run takes 30–60 seconds.
+Keeping the fixture tiny keeps the full suite under 3 minutes.
+
+## Output Location
+
+Pipeline output is written to `<tempdir>/learnx_e2e_smoke/` (e.g. `/tmp/learnx_e2e_smoke/`
+on Linux, `%TEMP%\learnx_e2e_smoke\` on Windows). The directory persists between runs
+so you can inspect the output manually.
+
+## Skipped Tests
+
+- `test_video_streams.py` — all tests skip if `tutorial.mp4` is absent (video pipeline optional)
+- `test_slide_render.py` — all tests skip if `slides/` directory is absent (visual pipeline optional)

tutor/tests/e2e/conftest.py

@@ -0,0 +1,117 @@
+"""
+Shared fixtures for E2E smoke tests.
+
+The pipeline_output fixture runs the full LearnX pipeline once per test session,
+with the LLM mocked so no API key is needed. TTS (edge-tts) runs for real.
+All E2E test modules depend on this fixture.
+"""
+
+import argparse
+import json
+import os
+import pathlib
+import tempfile
+from unittest.mock import patch
+
+import pytest
+
+FIXTURE_DOC = pathlib.Path("tutor/tests/e2e/fixtures/sample.md")
+# Fixed path so inspecting artifacts after a run is easy. Tests are serial
+# (session fixture), so no race condition from parallel execution.
+OUTPUT_DIR = pathlib.Path(tempfile.gettempdir()) / "learnx_e2e_smoke"
+
+CURRICULUM_RESPONSE = json.dumps(
+    [
+        {
+            "concept": "What is a Variable?",
+            "complexity": 1,
+            "source_sections": ["s01"],
+            "key_facts": [
+                "A variable is a named container for a value",
+                "Variables have a name and hold a value",
+                "Variables can store numbers, text, or lists",
+            ],
+            "common_misconception": "Variables and constants are the same thing",
+            "good_analogy": "A labeled box in a warehouse",
+            "question_style": "recall",
+            "memory_hook": "Variable equals labeled box",
+            "word_budget": 200,
+            "prerequisite_concepts": [],
+            "js_contrast": "",
+            "production_relevance": "",
+        },
+    ]
+)
+
+DIALOGUE_RESPONSE = "\n".join(
+    [
+        "ALEX: Welcome to today's lesson on variables in programming.",
+        "MAYA: What exactly is a variable?",
+        "ALEX: Think of a variable as a labeled box that stores a value you can retrieve later.",
+        "MAYA: Like how I would label a container in my kitchen?",
+        "ALEX: Exactly. In Python you write age equals 25 to create a variable called age.",
+        "MAYA: And then I can use the name age later to get 25 back?",
+        "ALEX: That is right. Variables make programs readable and flexible.",
+        "MAYA: What types of values can a variable hold?",
+        "ALEX: Numbers, text, lists, and almost anything else your program needs.",
+        "MAYA: Great, now variables make much more sense to me.",
+    ]
+)
+
+SUMMARIZE_RESPONSE = (
+    "A variable is a named container that holds a value in a computer program. "
+    "Variables can hold different types of data including numbers, text, and lists."
+)
+
+
+def _mock_llm(messages, call_type="dialogue", **kwargs):
+    """Return fixed LLM responses keyed on call_type, bypassing the real API."""
+    if call_type == "summarize":
+        return SUMMARIZE_RESPONSE
+    if call_type == "curriculum":
+        return CURRICULUM_RESPONSE
+    if call_type == "dialogue":
+        return DIALOGUE_RESPONSE
+    raise ValueError(f"Unexpected LLM call_type in mock: {call_type!r}")
+
+
+@pytest.fixture(scope="session")
+def pipeline_output():
+    """Run the full pipeline once for the entire E2E test session.
+
+    LLM responses are mocked; TTS (edge-tts) runs for real and requires
+    an internet connection. Output files are written to OUTPUT_DIR.
+    """
+    from tutor.tutor import cmd_generate
+
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    args = argparse.Namespace(
+        input=str(FIXTURE_DOC),
+        output=str(OUTPUT_DIR / "tutorial.mp3"),
+        provider="groq",
+        duration=5,
+        fmt="tutor-student",
+        difficulty="beginner",
+        units=1,
+        subject="general",
+        topic=None,
+        play=False,
+        script_only=False,
+        dry_run=False,
+        inspect=False,
+        show_summaries=False,
+        no_cache=False,
+        verbose=False,
+        debug=False,
+        explain=False,
+        conversation=False,
+    )
+
+    with (
+        patch("tutor.infra.llm.chat", side_effect=_mock_llm),
+        patch.dict(os.environ, {"GROQ_API_KEY": "test-key-not-used"}),
+    ):
+        cmd_generate(args)
+
+    return OUTPUT_DIR

tutor/tests/e2e/fixtures/README.md

@@ -0,0 +1,17 @@
+# E2E Test Fixtures
+
+## sample.md
+
+A minimal 3-paragraph document about variables in programming.
+
+**Why it is small:** E2E tests run the real TTS pipeline, which takes 2–4 seconds
+per audio segment. A short document keeps the full suite under 3 minutes. The
+fixture is intentionally not representative of real user content — it exists only
+to exercise the pipeline end-to-end.
+
+**Why this topic:** "What is a variable?" produces a single teaching unit with a
+short dialogue. The LLM is mocked (see conftest.py), so the content is fixed and
+the test suite is reproducible without a real API key.
+
+**Do not add more content to this file.** If you need to test a different scenario,
+add a new fixture file and a separate E2E test module.