Add Arabic diacritics module and related tests

- Implemented `arabic_diacritics.py` to add Arabic vowel marks to words based on their IPA pronunciation.
- Created tests for the diacritics functionality in `test_arabic_diacritics.py`, covering various cases including short and long vowels, gemination, and phrase handling.
- Updated grading pipeline documentation to include detailed explanations of the scoring process and audio handling.

.env.example

@@ -7,7 +7,6 @@ SAWTAK_API_KEY=
 
 # Optional: a specific voice id from the Sawtak catalog.
 # Empty = the most liked ready Palestinian voice.
-SAWTAK_VOICE_ID=
 
 # Google sign-in through Supabase (Project Settings -> API Keys). Both values are public: the page gets them too.
 # Empty = no sign-in, the service is open. On Hugging Face these can be plain Space *variables*.

README.md

@@ -488,6 +488,6 @@ Tune them on a handful of labelled learner recordings. A useful target is that n
 
 - Local: `cp .env.example .env` and set `SAWTAK_API_KEY` (`.env` is git-ignored and excluded from the Docker image).
 - Hugging Face: add `SAWTAK_API_KEY` as a Space **secret** (Settings → Variables and secrets). It is injected as an environment variable at runtime.
-- `SAWTAK_VOICE_ID` is optional; by default the most liked ready Palestinian voice is used.
+- Playback, candidate generation and score calibration all use the Palestinian voice רַאאִף.
 - Without a key the endpoint answers 503 and the page falls back to the device's Arabic voice.
-- The same voices calibrate the scores (step 5 above). This generates the first voice of `tts.VOICES` once for every phrase that gets scored, also when the learner never presses "השמע"; the other voices are used only when already cached. The first score of a phrase waits up to 8 s for it. Without a key the scores are not calibrated; `/api/health` reports this as `references`.
+- The same רַאאִף voice calibrates the scores (step 5 above), once for every phrase that gets scored, also when the learner never presses "השמע". The first score of a phrase waits up to 8 s for it. Without a key the scores are not calibrated; `/api/health` reports this as `references`.

app/arabic_diacritics.py

@@ -0,0 +1,106 @@
+"""Add Arabic vowel marks to an answer from the pronunciation stored beside it.
+
+The phrase bank deliberately keeps a plain Arabic spelling and an exact IPA reading.
+This module combines them for the learner-facing answer without changing the spelling
+used by the scorer or by text-to-speech.
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+from .archi import _LETTERS, _align, _letters, _units
+from .phones import base
+
+FATHA, DAMMA, KASRA, SUKUN, SHADDA = "\u064e", "\u064f", "\u0650", "\u0652", "\u0651"
+_MARKS = re.compile(r"[\u0610-\u061a\u064b-\u065f\u0670\u06d6-\u06ed]")
+_VOWELS = {"a", "i", "u", "e", "o", "ə"}
+_VOWEL_MARK = {"a": FATHA, "i": KASRA, "e": KASRA, "ə": KASRA, "u": DAMMA, "o": DAMMA}
+
+
+def _vowel(ph: str) -> str | None:
+    sound = base(ph)
+    return sound if sound in _VOWELS else None
+
+
+def _point_word(word: str, ipa_word: str) -> str:
+    plain = _MARKS.sub("", word)
+    chars = list(plain)
+    letters = _letters(plain)
+    phs = ipa_word.split()
+    units = _units(phs)
+    if not letters or not units:
+        return plain
+
+    matched, _cost = _align(letters, [sound for sound, _positions in units])
+    unit_for_letter: dict[int, int] = {}
+    for letter_i, hits in matched.items():
+        real = [hit for hit in hits if hit >= 0]
+        if len(hits) == 1 and len(real) == 1:
+            unit_for_letter[letter_i] = real[0]
+
+    if not unit_for_letter:
+        return plain
+
+    marks: dict[int, list[str]] = {}
+    ordered = sorted(unit_for_letter.items(), key=lambda item: item[1])
+    for order_i, (letter_i, unit_i) in enumerate(ordered):
+        positions = units[unit_i][1]
+        if len(positions) > 1:
+            marks.setdefault(letter_i, []).append(SHADDA)
+
+        end = positions[-1] + 1
+        next_start = units[unit_i + 1][1][0] if unit_i + 1 < len(units) else len(phs)
+        following = next((_vowel(phs[i]) for i in range(end, next_start) if _vowel(phs[i])), None)
+        if following:
+            target = letter_i
+            next_letter_i = ordered[order_i + 1][0] if order_i + 1 < len(ordered) else len(letters)
+            between = range(letter_i + 1, next_letter_i)
+            # A final ta marbuta / h carries its spoken ending (qahwe, madrase).
+            ending = next((i for i in between if letters[i] in "ةه" and i == len(letters) - 1), None)
+            if ending is not None:
+                target = ending
+            marks.setdefault(target, []).append(_VOWEL_MARK[following])
+        else:
+            marks.setdefault(letter_i, []).append(SUKUN)
+
+    # A word-initial vowel belongs on its alif/hamza, before the first aligned consonant.
+    first_unit = ordered[0][1] if ordered else 0
+    first_phone = units[first_unit][1][0]
+    initial = next((_vowel(ph) for ph in phs[:first_phone] if _vowel(ph)), None)
+    if initial:
+        first_letter = ordered[0][0]
+        carrier = next((i for i in range(first_letter + 1) if letters[i] in "اٱأإآء"), first_letter)
+        marks.setdefault(carrier, []).append(_VOWEL_MARK[initial])
+
+    # In a sun-letter article the lam is silent but is still explicitly vowelless.
+    if plain.startswith("ال") and 1 not in unit_for_letter:
+        marks.setdefault(1, []).append(SUKUN)
+
+    output = []
+    letter_i = 0
+    for char in chars:
+        output.append(char)
+        if char in _LETTERS:
+            own = marks.get(letter_i, [])
+            output.extend(mark for mark in (SHADDA if SHADDA in own else "", next((m for m in own if m != SHADDA), "")) if mark)
+            letter_i += 1
+    return "".join(output)
+
+
+@lru_cache(maxsize=16384)
+def point_arabic(arabic: str, ipa: str) -> str:
+    """Return the original Arabic spelling with marks for its IPA pronunciation."""
+    ipa_words = [part.strip() for part in ipa.split("|")]
+    word_i = 0
+
+    def point(match: re.Match[str]) -> str:
+        nonlocal word_i
+        word = match.group(0)
+        if word_i >= len(ipa_words):
+            return word
+        result = _point_word(word, ipa_words[word_i])
+        word_i += 1
+        return result
+
+    return re.sub(r"[^\s]+", point, arabic) if len(arabic.split()) == len(ipa_words) else arabic

app/main.py

@@ -2,7 +2,7 @@
 
 Run:  uvicorn app.main:app --host 0.0.0.0 --port 7860
 Env:  MODEL_ID  (default facebook/wav2vec2-xlsr-53-espeak-cv-ft, or a path to a fine-tuned checkpoint)
-      SAWTAK_API_KEY, SAWTAK_VOICE_ID  (model-answer playback, see app/tts.py)
+      SAWTAK_API_KEY  (model-answer playback with the Raef voice, see app/tts.py)
       SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY  (Google sign-in, see app/auth.py)
       TEACHER_EMAILS, SUPABASE_SECRET_KEY  (the teacher's management panel, its classes and the lesson videos, see app/auth.py)
       TUTORS_EMAIL  (more accounts that, like the teachers, flag a recording scored wrong, see app/auth.py)
@@ -28,6 +28,7 @@ from fastapi import BackgroundTasks, Body, Depends, FastAPI, File, Form, HTTPExc
 from fastapi.responses import HTMLResponse, Response
 from fastapi.staticfiles import StaticFiles
 
+from .arabic_diacritics import point_arabic
 from .auth import AuthUnavailable, ClassConflict, SupabaseAuth, load_auth
 from .phrases import CATEGORIES, GAMES, LESSONS, LEVELS, PHRASES, public_phrases
 from .prompt_tts import ENGINES, PromptTTSUnavailable, hebrew_mp3
@@ -36,7 +37,7 @@ from .rules import TOGGLES, check_detectable
 from .scorer import Scorer, decode_audio, load_scorer
 from .speech_evaluation import SpeechEvaluationService
 from .texts import read_line, text_phrases
-from .tts import VOICES, SawtakTTS, TTSUnavailable, load_tts
+from .tts import RAEF_VOICE_ID, VOICES, SawtakTTS, TTSUnavailable, load_tts
 from .verb_game import VerbExerciseGenerator
 
 logging.basicConfig(level=logging.INFO)
@@ -91,7 +92,8 @@ def placed(rows: list[dict], lesson: str) -> list[dict]:
 # bank's: TEXT_BASE + the text's id * TEXT_SPAN + the line's number, so it holds as texts come and go.
 TEXT_BASE, TEXT_SPAN = 1_000_000, 1000
 MAX_LINES, MAX_LINE = 200, 300
-VOICE_NAMES = [re.sub(r"[\u0591-\u05c7]", "", name) for name in VOICES]   # as a topic names its voices: without the points
+# Historical dialogues retain their speaker names even though every line is now played by Raef.
+VOICE_NAMES = ["אמיר", "ראאף", "חנאן"]
 CREATE_TEXTS = ("create table public.texts (id bigint generated always as identity primary key, lesson text not null, "
                 "title text not null, voices text[] not null default '{}', lines jsonb not null, pos int, "
                 "ord int not null default 0, created_at timestamptz not null default now()); "
@@ -952,7 +954,8 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
         return {"categories": [{"id": f"t{r['id']}", "name": r["title"], "lesson": r["lesson"], "story": True, "text": r["id"],
                                 **({"voices": r["voices"]} if r["voices"] else {}), "pos": r["pos"], "ord": r["ord"],
                                 **({"guessed": built(r)[1]} if user["teacher"] else {})} for r in rows],
-                "phrases": [{"id": i, "cat": p["cat"], "he": p["he"], "tr": p["tr"], "ar": p["variants"][0][0], "seq": p["seq"]}
+                "phrases": [{"id": i, "cat": p["cat"], "he": p["he"], "tr": p["tr"], "ar": p["variants"][0][0],
+                             "ar_pointed": point_arabic(*p["variants"][0]), "seq": p["seq"]}
                             for i, p in text_bank(rows).items()]}
 
     def text_store_error(e: AuthUnavailable) -> str:
@@ -1226,27 +1229,35 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
                 "dialect_realisations_missing": {k: sorted(v) for k, v in s.vocab.class_missing.items()}}
 
     @app.get("/api/tts/{phrase_id}", dependencies=members)
-    def tts_phrase(phrase_id: int, voice: str = Query("", max_length=64)):
-        """The model answer (first variant) spoken by the TTS voice. 503 tells the page to use the device voice.
-
-        `voice` picks one of the voices in tts.VOICES instead of the configured one.
-        """
+    def tts_phrase(phrase_id: int):
+        """The model answer spoken by Raef. 503 tells the page to use the device voice."""
         names = {i: n for n, i in VOICES.items()}
-        if voice and voice not in names:
-            raise HTTPException(400, "unknown voice")
-        text = phrase_of(phrase_id)["variants"][0][0]
+        text = point_arabic(*phrase_of(phrase_id)["variants"][0])
         if app.state.tts is None:
             raise HTTPException(503, "tts not configured")
         try:
-            data, used = app.state.tts.wav(text, voice)
+            data, used = app.state.tts.wav(text, RAEF_VOICE_ID)
         except TTSUnavailable as e:
             raise HTTPException(503, str(e))
         tts = app.state.tts  # debug: lets the page show which voice spoke
         return Response(data, media_type="audio/wav", headers={
-            "Cache-Control": "private, max-age=86400", "X-TTS-Provider": "sawtakarabi.ai",
+            "Cache-Control": "private, no-store", "X-TTS-Provider": "sawtakarabi.ai",
             "X-TTS-Voice-Id": urllib.parse.quote(used),
             "X-TTS-Voice-Name": urllib.parse.quote(names.get(used) or getattr(tts, "voice_name", ""))})
 
+    @app.delete("/api/tts-cache")
+    def clear_tts_cache(_a: SupabaseAuth = Depends(teacher_only)):
+        """Delete generated Sawtak recordings; the next playback generates them again."""
+        if app.state.tts is None:
+            raise HTTPException(503, "tts not configured")
+        try:
+            removed = app.state.tts.clear_cache()
+        except TTSUnavailable as e:
+            raise HTTPException(503, str(e))
+        if app.state.refs:
+            app.state.refs.invalidate()
+        return {"ok": True, "removed": removed}
+
     @app.get("/api/prompt-audio/{phrase_id}", dependencies=members)
     def prompt_audio(phrase_id: int, engine: str = "gtts"):
         """The Hebrew prompt read aloud (edge-tts or gTTS). 503 tells the page to stay silent."""

app/phrases.py

@@ -11,6 +11,7 @@ Conventions (Palestinian urban speech as the main form):
   Emphatics are written with ˤ (sˤ tˤ dˤ ðˤ), long vowels with ː.
   Geminates are written doubled; the tokenizer collapses them for CTC.
 """
+from .arabic_diacritics import point_arabic
 from .grammar import day2_phrases
 from .workbook import CATEGORIES as WORKBOOK_CATEGORIES, GAMES as WORKBOOK_GAMES, LESSON_TABS, LEVEL_TABS, workbook_phrases
 
@@ -147,6 +148,7 @@ def public_phrases():
     shown = {c["id"] for c in CATEGORIES + GAMES}
     return [
         {"id": i, "cat": p["cat"], "he": p["he"], "tr": p["tr"], "ar": p["variants"][0][0],
+         "ar_pointed": point_arabic(*p["variants"][0]),
          **{k: p[k] for k in ("grp", "pron", "neg", "listed", "seq", "read", "unlock", "binyan", "gizra") if k in p}}
         for i, p in enumerate(PHRASES) if p["cat"] in shown
     ]

app/reference.py

@@ -16,6 +16,7 @@ import threading
 import time
 from concurrent.futures import Future, ThreadPoolExecutor, wait
 
+from .arabic_diacritics import point_arabic
 from .scorer import Reference, Scorer, decode_audio
 
 log = logging.getLogger("ihki.reference")
@@ -39,7 +40,7 @@ class References:
 
     def get(self, phrase_id: int, phrase: dict) -> list[Reference]:
         """The references of a phrase that are ready within the wait."""
-        text = phrase["variants"][0][0]
+        text = point_arabic(*phrase["variants"][0])
         jobs: list[tuple[tuple[int, str], Future]] = []
         with self._lock:
             for n, voice in enumerate(self.voices):
@@ -67,3 +68,18 @@ class References:
             if ref is not None:
                 refs.append(ref)
         return refs
+
+    def invalidate(self, phrase_id: int | None = None, voice: str | None = None) -> int:
+        """Forget matching in-memory baselines so the next score rebuilds them from the current WAV."""
+        with self._lock:
+            keys = [key for key in self._jobs
+                    if (phrase_id is None or key[0] == phrase_id) and (voice is None or key[1] == voice)]
+            for key in keys:
+                job = self._jobs.pop(key)
+                job.cancel()  # harmless when generation or analysis has already started
+                self._retry_at.pop(key, None)
+            retry_keys = [key for key in self._retry_at
+                          if (phrase_id is None or key[0] == phrase_id) and (voice is None or key[1] == voice)]
+            for key in retry_keys:
+                self._retry_at.pop(key, None)
+            return len(keys)

app/tts.py

@@ -4,7 +4,6 @@ The API key stays on the server: the browser asks for a phrase by id and gets a
 Only phrases from the phrase bank can be synthesised, and each one is generated once and cached on disk.
 
 Env:  SAWTAK_API_KEY   required; without it /api/tts answers 503 and the page falls back to the device voice
-      SAWTAK_VOICE_ID  optional; default is the most liked ready Palestinian voice in the catalog
       TTS_CACHE_DIR    optional; default ~/.cache/ihki-tts
 """
 from __future__ import annotations
@@ -16,7 +15,6 @@ import logging
 import os
 import threading
 import urllib.error
-import urllib.parse
 import urllib.request
 import wave
 from pathlib import Path
@@ -24,23 +22,20 @@ from pathlib import Path
 log = logging.getLogger("ihki.tts")
 BASE_URL = "https://api.sawtakarabi.ai/v1"
 MODEL = "arabic-tts-1"
-PALESTINIAN = ["ps", "ps-central", "ps-westbank", "ps-north", "ps-nablus", "ps-galilee", "ps-hebron", "ps-south", "ps-gaza"]
+CACHE_VERSION = "raef-pointed-enhanced-provider-default-v1"
 TIMEOUT = 60
-# Voices the page offers in its drop-down (name shown -> Sawtak voice id). Only these can be requested.
-VOICES = {
-    "אמיר": "5db8ef83-ac37-4a17-be23-e20446290367",
-    "רַאאִף": "273d81b2-991b-5b76-8525-eeacc6a3d759",
-    "חנאן": "e41781f5-127c-5eb0-b83c-50bf52a64caf",
-}
+# The single Sawtak voice used throughout the application.
+RAEF_VOICE_ID = "273d81b2-991b-5b76-8525-eeacc6a3d759"
+VOICES = {"רַאאִף": RAEF_VOICE_ID}
 
 class TTSUnavailable(Exception):
     """No key configured, or the provider refused / failed. The message is safe to show."""
 
 
 class SawtakTTS:
-    def __init__(self, api_key: str, voice_id: str = "", cache_dir: Path | None = None):
-        self.api_key, self.voice_id = api_key, voice_id
-        self.voice_name = ""  # known only when the voice was picked from the catalog
+    def __init__(self, api_key: str, voice_id: str = RAEF_VOICE_ID, cache_dir: Path | None = None):
+        self.api_key, self.voice_id = api_key, RAEF_VOICE_ID
+        self.voice_name = "רַאאִף"
         self.cache_dir = cache_dir or Path.home() / ".cache" / "ihki-tts"
         self._lock = threading.Lock()  # one generation at a time; also guards the voice lookup
 
@@ -65,50 +60,59 @@ class SawtakTTS:
             log.warning("sawtak %s unreachable: %s", path, e)
             raise TTSUnavailable("tts provider unreachable") from None
 
-    def _voice(self) -> str:
-        if not self.voice_id:
-            query = urllib.parse.urlencode(
-                [("dialect", d) for d in PALESTINIAN] + [("sort", "most_liked"), ("limit", "25")])
-            with self._request(f"/voices?{query}") as res:
-                voices = [v for v in json.load(res).get("data", []) if v.get("status") == "ready"]
-            if not voices:
-                raise TTSUnavailable("no Palestinian voice in the catalog; set SAWTAK_VOICE_ID")
-            self.voice_id, self.voice_name = voices[0]["id"], voices[0].get("name") or ""
-            log.info("sawtak voice: %s (%s, %s)", voices[0].get("name"), self.voice_id,
-                     (voices[0].get("labels") or {}).get("dialect"))
-        return self.voice_id
-
     def _path(self, text: str, voice: str) -> Path:
-        return self.cache_dir / (hashlib.sha1(f"{MODEL}|{voice}|{text}".encode()).hexdigest() + ".wav")
+        return self.cache_dir / (hashlib.sha1(f"{CACHE_VERSION}|{MODEL}|{voice}|{text}".encode()).hexdigest() + ".wav")
 
     def cached(self, text: str, voice: str) -> bool:
         """Has this voice said `text` before? Then wav() answers from disk, without the provider."""
         return self._path(text, voice).exists()
 
-    def wav(self, text: str, voice: str = "") -> tuple[bytes, str]:
-        """(WAV, voice id) for `text`, from the cache when this voice has said it before.
+    def _generate(self, text: str, voice: str) -> bytes:
+        """Generate one uncached WAV recording."""
+        # Sawtak currently returns 320 seconds of silence whenever `temperature` is present,
+        # including for 0 and 0.1. Omitting it uses the provider's deterministic supported path.
+        with self._request("/audio/speech", {"model": MODEL, "voice": voice, "input": text,
+                                             "response_format": "pcm", "enhance_pronunciation": True,
+                                             }) as res:
+            rate = int(res.headers.get("X-Sample-Rate", 24000))
+            pcm = res.read()
+        if len(pcm) < rate // 5:
+            raise TTSUnavailable("tts provider returned no audio")
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(rate)
+            w.writeframes(pcm[: len(pcm) // 2 * 2])
+        return buf.getvalue()
 
-        `voice` overrides the configured voice for this call (the page's voice drop-down).
-        """
+    def clear_cache(self) -> int:
+        """Delete only generated audio files from this instance's dedicated cache directory."""
+        with self._lock:
+            if not self.cache_dir.is_dir():
+                return 0
+            removed = 0
+            for path in self.cache_dir.iterdir():
+                if path.is_file() and (path.suffix == ".wav" or path.name.endswith(".tmp")):
+                    try:
+                        path.unlink()
+                        removed += 1
+                    except FileNotFoundError:
+                        pass
+                    except OSError as e:
+                        raise TTSUnavailable(f"could not clear voice cache: {e}") from None
+            return removed
+
+    def wav(self, text: str, voice: str = "") -> tuple[bytes, str]:
+        """(WAV, Raef's voice id) for `text`, using the disk cache when available."""
         with self._lock:
-            voice = voice or self._voice()
+            voice = RAEF_VOICE_ID
             path = self._path(text, voice)
             if path.exists():
                 return path.read_bytes(), voice
-            # enhance_pronunciation: the phrase bank is unvowelled, so let the voice's dialect add the tashkeel
-            with self._request("/audio/speech", {"model": MODEL, "voice": voice, "input": text,
-                                                 "response_format": "pcm", "enhance_pronunciation": True}) as res:
-                rate = int(res.headers.get("X-Sample-Rate", 24000))
-                pcm = res.read()
-            if len(pcm) < rate // 5:  # an error after streaming starts just cuts the audio short
-                raise TTSUnavailable("tts provider returned no audio")
-            buf = io.BytesIO()
-            with wave.open(buf, "wb") as w:  # raw stream is signed 16-bit little-endian mono
-                w.setnchannels(1)
-                w.setsampwidth(2)
-                w.setframerate(rate)
-                w.writeframes(pcm[: len(pcm) // 2 * 2])
-            data = buf.getvalue()
+            # The caller supplies the phrase's Palestinian vowel marks. Sawtak preserves existing
+            # marks; enhancement fills remaining pronunciation cues using the selected voice's dialect.
+            data = self._generate(text, voice)
             try:
                 self.cache_dir.mkdir(parents=True, exist_ok=True)
                 tmp = path.with_suffix(".tmp")
@@ -125,4 +129,4 @@ def load_tts() -> SawtakTTS | None:
         log.info("SAWTAK_API_KEY not set: playback uses the device voice")
         return None
     cache = os.environ.get("TTS_CACHE_DIR", "").strip()
-    return SawtakTTS(key, os.environ.get("SAWTAK_VOICE_ID", "").strip(), Path(cache) if cache else None)
+    return SawtakTTS(key, RAEF_VOICE_ID, Path(cache) if cache else None)

docs/grading-pipeline.md

@@ -0,0 +1,494 @@
+# How grading works: from a recording to an exercise grade
+
+This document traces one recording through the scorer, from the audio bytes and the reference text to the numbers the student and the teacher see. It is written for a reader who knows CTC, forced alignment and GOP, and wants the exact formulas, thresholds and order of operations this codebase uses.
+
+The pipeline has no ASR in it. The model never transcribes freely and then diffs against the text. Instead, the reference text is turned into phoneme sequences, the audio is force-aligned to each sequence, and each phoneme is scored by how strongly the model's posteriors support it inside its own time window.
+
+| Stage | Where |
+|---|---|
+| Audio decode, silence trim | [app/scorer.py](../app/scorer.py) `decode_audio` |
+| Phoneme posteriors (wav2vec2 CTC) | [app/scorer.py](../app/scorer.py) `HFEmitter` |
+| Vocab pooling, many-ways letters | [app/scorer.py](../app/scorer.py) `Vocab`, [app/phones.py](../app/phones.py), [app/archi.py](../app/archi.py) |
+| CTC Viterbi, GOP, greedy decode, edit distance | [app/align.py](../app/align.py) |
+| Linguistic rules, exemptions, margins | [app/rules.py](../app/rules.py), [static/assets/pronunciation-rules.md](../static/assets/pronunciation-rules.md) |
+| Native baseline from TTS | [app/reference.py](../app/reference.py) |
+| Result assembly, word and sentence score | [app/scorer.py](../app/scorer.py) `Scorer.score_logp` |
+| HTTP endpoint | [app/main.py](../app/main.py) `POST /api/score` |
+| Exercise-level grades | [static/index.html](../static/index.html), [app/speech_evaluation.py](../app/speech_evaluation.py) |
+
+---
+
+## 1. The whole pipeline at a glance
+
+```mermaid
+flowchart TD
+    A["Browser recording<br/>webm/opus, ogg, mp4, wav"] --> B["decode_audio<br/>ffmpeg → 16 kHz mono f32<br/>cap 32 s, energy trim"]
+    R["Phrase from the bank<br/>Hebrew prompt + accepted variants<br/>(Arabic, IPA)"] --> V
+    B --> E["wav2vec2-xlsr-53-espeak-cv-ft<br/>log-softmax → logp (T × V)"]
+    E --> M["Vocab.merge<br/>pool spelling variants of one sound"]
+    V["Expand variants<br/>archify: Q, K, TH, DH, ZH, J, E<br/>+ diphthong forms"] --> T["Tokenise each variant<br/>collapse geminates / repeats"]
+    M --> X["Vocab.extend<br/>add pooled class columns"]
+    T --> X
+    X --> F["CTC Viterbi per variant<br/>keep max total log-prob"]
+    F --> G["GOP per token<br/>in its window"]
+    G --> H["Exemptions<br/>glottal drop · article vowel · near vowel"]
+    H --> I["Vowel-insertion cap<br/>rule 3.10"]
+    I --> J["Native baseline<br/>divide by TTS voice's score"]
+    J --> K["Teacher calibration floors"]
+    K --> L["Flags, tips, issues<br/>margins + rules"]
+    L --> W["Word score<br/>0.5·min + 0.5·mean"]
+    W --> S["Sentence score<br/>0.5·phone mean + 0.5·word mean"]
+    F --> U["Greedy decode vs best variant<br/>edit distance ratio"]
+    U -->|"over 0.65"| C["unrelated: cap at 30, no tips"]
+    C --> S
+    S --> O["JSON result 0–100"]
+    O --> P["Exercise grades<br/>band, best score, topic, quiz, verb game"]
+```
+
+## 2. Request sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant UI as Browser (index.html)
+    participant API as FastAPI /api/score
+    participant FF as ffmpeg
+    participant Ref as References (TTS baseline)
+    participant TTS as Sawtak TTS
+    participant Sc as Scorer
+    participant M as wav2vec2 CTC
+    participant DB as Supabase attempts
+
+    UI->>API: multipart {phrase_id, audio}
+    API->>FF: decode to 16 kHz mono float32
+    FF-->>API: wav (silence-trimmed)
+    alt wav shorter than 0.3 s
+        API-->>UI: {error: too_short}
+    end
+    API->>Ref: get(phrase_id, phrase), wait ≤ 8 s
+    opt first time this phrase is scored
+        Ref->>TTS: synthesise variant 0 (first voice)
+        TTS-->>Ref: native audio
+        Ref->>Sc: reference(wav, phrase)
+        Sc->>M: emit
+        M-->>Sc: logp
+        Sc-->>Ref: per-sound native scores, or None if untrustworthy
+    end
+    Ref-->>API: list of References (possibly empty)
+    API->>Sc: score(wav, phrase, refs, diagnostics=teacher)
+    Sc->>M: emit(wav)
+    M-->>Sc: logp (T × V)
+    Sc->>Sc: merge → variants → Viterbi → GOP → rules → baseline → floors → aggregate
+    Sc-->>API: result JSON
+    API-->>UI: result
+    API--)DB: background: {cat, phrase, score, unrelated, flagged issues}
+    UI->>UI: band label, letter colours, keep best score per sentence
+```
+
+The reference text never arrives from the client: the client sends only `phrase_id`, and the server looks up the phrase (bank phrase, teacher text line, or a verb-game form held server-side). That matters for the verb game, where the expected answer must not be exposed to the browser.
+
+---
+
+## 3. Inputs
+
+### 3.1 Audio
+
+`decode_audio` pipes the upload through ffmpeg (`-ac 1 -ar 16000 -f f32le -t 32`). It then trims leading and trailing silence with a 20 ms RMS envelope (320 samples). A sample counts as voiced if its envelope is above `max(0.01, 0.05 · peak)`. 200 ms of padding is kept on each side. The trim keeps CTC from being fed seconds of blank, which would otherwise widen the first and last tokens' GOP windows.
+
+Anything shorter than 0.3 s after trimming is rejected before inference.
+
+### 3.2 Reference text: a phrase and its accepted variants
+
+A phrase in [app/phrases.py](../app/phrases.py) (and the generated workbook, grammar and teacher texts) carries a list of **accepted variants**, each `(arabic, ipa)`:
+
+```python
+dict(cat="meet", he="אני מירושלים", variants=[
+    ("انا من القدس", "ʔ a n a | m i n | i l ʔ u d s"),
+    ("انا من القدس", "ʔ a n a | m i n | i l q u d s"),
+])
+```
+
+IPA phonemes are space-separated, words are separated by `|`, and the Arabic and IPA must have the same word count. A variant is a genuinely different correct sentence (different lexical choice, a dropped word, a different vowel pattern). Dialectal realisations of single letters are handled by the next step instead.
+
+### 3.3 Variant expansion: many-ways letters ("archiphonemes")
+
+Six Arabic letters have more than one correct Palestinian realisation. [app/archi.py](../app/archi.py) `archify()` aligns each word's Arabic letters to its IPA consonants (a small edit-distance DP with cheap skips for weak letters like ا و ي ة ل). It then rewrites the phoneme that came from such a letter as `SYMBOL:written`:
+
+| Symbol | Letter | Accepted realisations (rules §5) |
+|---|---|---|
+| `Q` | ق | ʔ (urban), k (rural), q (also ok); g only if `optional_realisations_enabled` |
+| `K` | ك | k, tʃ (rural) |
+| `TH` | ث | t, θ; s only in learned words where the phrase writes s |
+| `DH` | ذ | d, ð; z only in learned words where the phrase writes z |
+| `ZH` | ظ | dˤ, zˤ, ðˤ |
+| `J` | ج | dʒ, ʒ |
+| `E` | final ة | a, e, i (positional) |
+| `O` | pronoun ending | o, u (positional) |
+
+So `ʔ a h w e` for قهوة becomes `Q:ʔ a h w E:e`. The written phoneme is kept for display, tips and calibration keys. The class membership is what gets scored.
+
+Two more expansions:
+
+- **Diphthongs** (§6.3 #8). `diphthong_variants()` adds a copy of the variant with `eː → a j` and `oː → a w` where the Arabic writes ي / و. A diphthong is two tokens instead of one, so it cannot be a class. It becomes a separate variant that competes in the Viterbi step.
+- **Deduplication.** Variants that differ only in how a many-ways letter is said collapse into one after archifying.
+
+A teacher can switch off any of these (the `dialect_*`, `final_vowel` and `diphthong` toggles). The scorer then requires the phoneme as written.
+
+---
+
+## 4. Acoustic model and vocabulary handling
+
+### 4.1 Emissions
+
+`HFEmitter` runs `facebook/wav2vec2-xlsr-53-espeak-cv-ft` (or a fine-tuned checkpoint via `MODEL_ID`) and returns `log_softmax(logits)`, shape `(T, V)`. That is ~50 frames/s (20 ms hop), V ≈ 392 espeak IPA symbols plus `<pad>` as the CTC blank.
+
+Nothing downstream depends on torch. `Scorer` takes any `Emitter` callable, which is how [tests/test_scoring.py](../tests/test_scoring.py) drives the full scorer with synthetic posteriors.
+
+### 4.2 Pooling spelling variants (`Vocab.merge`)
+
+The multilingual vocab spells one sound several ways (`t / t̪ / tʰ / tː`, `r / ɾ`, `a / æ / ɐ`, `x / χ`). Left alone, a correctly said `t` would lose its GOP to its own allophone `t̪`. [app/phones.py](../app/phones.py) `base()` maps each symbol to a canonical sound by stripping length, aspiration, dentality, nasality and so on, and folding a fixed equivalence table. Emphatics stay distinct.
+
+`merge()` replaces each group's columns with one representative column holding the group's `logsumexp`. The other columns are set to −1e9.
+
+> A consequence: vowel length is invisible to the scorer, because `aː` and `a` share a base. Length errors can surface only through the margins and rules on the written phoneme, not through separate posteriors.
+
+### 4.3 Class columns for many-ways letters (`Vocab.add_class`, `Vocab.extend`)
+
+For a token like `Q:ʔ`, the scorer looks up each accepted realisation's model id (falling back via `FALLBACKS`, e.g. `ðˤ → zˤ → z`, when the vocab lacks a symbol). If more than one distinct id remains, it allocates a **virtual id** past the real vocab. `extend()` appends one column per virtual id: the `logsumexp` of its members' posteriors.
+
+This implements rules §6.1. If P(ʔ)=0.35 and P(k)=0.40 in a frame, the `Q` column holds 0.75, and neither member is treated as a competitor of the other.
+
+### 4.4 Tokenisation
+
+`tokenize()` turns the archified IPA into a list of `TargetToken(phoneme, id, word, sound)`. Adjacent tokens with the same (canonical) id collapse into one, as in CTC. That means geminates (`m m`) become one token, and so do two neighbouring phonemes that map to the same sound. Gemination is therefore not scored (§6.3 #10).
+
+---
+
+## 5. Choosing the variant: CTC forced alignment
+
+For every expanded variant, [app/align.py](../app/align.py) `ctc_viterbi()` runs the standard CTC Viterbi over the extended label sequence `blank, y1, blank, y2, …, yN, blank` (S = 2N+1 states). It allows stay, advance by one, and the skip `s−2 → s` when the label differs from `s−2`. The path must end on the last label or the trailing blank.
+
+The result is `total_logp` (the best path's log-probability) and `spans[i] = [start, end)`, the frames where token *i* is emitted.
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    [*] --> b0
+    [*] --> y1
+    b0 --> b0
+    b0 --> y1
+    y1 --> y1
+    y1 --> b1
+    y1 --> y2: skip if y2 ≠ y1
+    b1 --> b1
+    b1 --> y2
+    y2 --> y2
+    y2 --> b2
+    b2 --> b2
+    y2 --> [*]
+    b2 --> [*]
+```
+
+The variant with the highest `total_logp` wins (not length-normalised; all variants are scored against the same T frames). If T < N for every variant, the result is `error: too_short`.
+
+> Example: قديش said with *k* aligns better to `Q a d d eː ʃ` than to an alternative wording. Because `Q` pools ʔ/k/q, the *k* realisation costs nothing.
+
+---
+
+## 6. Per-token scoring
+
+Each token goes through a fixed sequence of stages. The teacher's diagnostic view (`trace.tokens[i].stages`) reports the score after each one.
+
+```mermaid
+flowchart LR
+    G["1 · GOP<br/>score_tokens"] --> X["2 · Exemption<br/>max(score, floor)"]
+    X --> I["3 · Insertion cap<br/>min(score, 60)"]
+    I --> B["4 · Native baseline<br/>100·s / b"]
+    B --> C["5 · Calibration floor<br/>max(score, floor)"]
+    C --> F{"6 · Flag?<br/>score under 50<br/>AND beyond margin<br/>AND consonant or flagged vowel"}
+    F -->|yes| T["tip (by rule)"]
+    F -->|no| N["maybe an 'issue' if under 90"]
+```
+
+### 6.1 Stage 1: GOP (`score_tokens`)
+
+**Window.** Token *i*'s window runs from the end of token *i−1* to the start of token *i+1* (clamped to include its own span). It therefore contains the blank frames around the emission, which is where a substituted phoneme typically peaks when the path was forced through the target.
+
+**Target peak.** `peak = max_t logp[t, target]` inside the window. For a class token this is the pooled column. `realised` names the member with the highest peak (used for dialect detection and display).
+
+**Competitor.** Over the real columns only (no virtual columns), take each column's max inside the window. Then mask:
+- the blank,
+- the labels of tokens *i−1*, *i*, *i+1* and all their class members.
+
+Neighbours are masked because coarticulation into the adjacent phoneme is not an error (§6.3 #11). The argmax of what remains is the competitor, and its max is `comp_peak`. If the competitor is outside the set of sounds the system can name (Arabic, Hebrew interference sounds, rule labels), it is reported as `other` instead of by name. Example: a click or a retroflex from the multilingual vocab.
+
+**Score.**
+
+$$
+\text{gop} = \log p_{\text{target}} - \max(\log p_{\text{target}},\ \log p_{\text{comp}}) \;\le 0
+$$
+
+$$
+\text{confidence} = \min\!\left(1,\ \frac{p_{\text{target}}}{0.30}\right)
+$$
+
+$$
+\text{score} = 100 \cdot e^{\,\lambda\cdot \text{gop}} \cdot \sqrt{\text{confidence}}, \qquad \lambda = 0.5\ (\texttt{leniency})
+$$
+
+- With λ = 0.5 the ratio is square-rooted: a competitor twice as likely as the target gives 71, not 50. The zero-shot model is noisy on accented speech, so a linear ratio would punish the model's own uncertainty.
+- The confidence term penalises a target that wins but only weakly. Below a peak posterior of 0.30, the score shrinks with √(p/0.3).
+- A score of 100 requires the target to beat every non-neighbour competitor and reach p ≥ 0.30.
+
+**Deletion.** `deleted = p_target < 0.05 AND p_comp < 0.20`: nothing clearly there, target or otherwise. A deleted token is reported as heard `_`.
+
+**Worked numbers.** ħ said as a Hebrew ח (χ), with p(ħ) = 0.04 and p(χ) = 0.85 in the window:
+
+| quantity | value |
+|---|---|
+| gop | ln(0.04 / 0.85) = −3.056 |
+| e^(0.5·gop) | 0.217 |
+| confidence | 0.04 / 0.30 = 0.133, √ = 0.365 |
+| score | 100 · 0.217 · 0.365 ≈ **7.9** |
+| deleted? | no (p_comp 0.85 ≥ 0.20) |
+
+### 6.2 Stage 2: exemptions (rules §6.3)
+
+These are cases the model hears as a mistake that are ordinary native speech. The first rule that applies wins ([app/rules.py](../app/rules.py) `EXEMPTIONS`):
+
+| Exemption | Condition | Result |
+|---|---|---|
+| `glottal_dropped` | token deleted and its sound is ʔ or `Q` | 100 |
+| `article_vowel_elided` | deleted vowel of ال right after a word ending in a vowel | 100 |
+| `near_vowel` | vowel heard as same-group neighbour (i/e, u/o, a/ə/e) or other length | ≥ 90 (`near_vowel_floor`) |
+
+A glottal stop replaced by another consonant is not exempt (only a deletion is), unless the class accepts it (ق → k).
+
+### 6.3 Stage 3: vowel insertion inside a cluster (rule 3.10)
+
+Hebrew speakers often break a word-internal consonant cluster with an epenthetic vowel (*katiir* for *ktiir*). For each pair of adjacent consonants in the same word (not the sentence's first cluster, and not when either is w or j), the scorer looks at the greedy (argmax) frames between the two consonants' spans. If at least `min_frames` = 2 frames have a vowel as argmax with p ≥ `min_peak` = 0.5, the second consonant's score is capped at `score_cap` = 60, and a severity-1 tip is attached.
+
+### 6.4 Stage 4: native baseline
+
+The phoneme model mishears some sounds even from natives (ʕ in على heard as dropped, l as r). A learner should not lose points for the model's weaknesses.
+
+[app/reference.py](../app/reference.py) synthesises the phrase's first variant with a Palestinian TTS voice and scores it with the same `Scorer`. It keeps the per-sound scores, unless the fit is `unrelated` or the mean phoneme score is under `ref_min_mean` = 60, in which case the voice is not trusted. One voice is generated per phrase. Further voices are used only if already cached from playback. The score request waits up to 8 s for a reference, then proceeds without one.
+
+Learner tokens are matched to reference tokens with `difflib.SequenceMatcher` on `(word, sound)` pairs. Sounds compare by symbol, so a reference that said ق as q is a valid baseline for a learner who says ʔ. Per learner token, `b` is the minimum score over all references that share that sound. Then:
+
+$$
+s' = \begin{cases} s & b \text{ is None or } b \ge 100 \\ \min\!\left(100,\ 100\cdot s / \max(b, 1)\right) & \text{otherwise} \end{cases}
+$$
+
+So a sound the TTS voice scores 40 on and the learner scores 40 on becomes 100. The baseline only ever raises scores. A word whose sounds were raised this way, and now all score ≥ 90, also shows the expected transliteration as "heard": the visible difference is one a native produces too.
+
+### 6.5 Stage 5: teacher calibration floors
+
+Confirmed tutor flags can become calibration rules `(expected, heard, phrase?) → floor`. A rule is looked up by sound symbol first, then by written phoneme, phrase-specific before global. It raises a matching token to `floor` and never lowers it. Applied floors are listed in `result.calibrated`.
+
+### 6.6 Stage 6: is it a mistake? Flags, margins, rules
+
+Final per-token scores now exist. The decision to **flag** a token (show "heard as X" and a tip) needs all three of:
+
+1. `score < flag_below` (50).
+2. The competitor beats the target by at least the pair's **margin** (rules §6.2):
+   - substitution: `−gop ≥ margin(target, heard)`
+   - deletion: `p_target ≤ deleted_peak − margin(target, "_")` in log space
+3. The token is a consonant, or a short vowel a rule explicitly flags. Currently that is only **u after a consonant in the same word** (rule 3.11). Other short vowels are never flagged (§6.3 #7).
+
+Margins are natural-log ratios from the rules document:
+
+| Target | Heard | Margin | Meaning |
+|---|---|---|---|
+| sˤ tˤ dˤ zˤ ðˤ | s t d z ð | 0.7 | plain must be ≈ 2× likelier (emphasis is weak in the base model) |
+| h | `_` | 0.7 | h is short and quiet; natives reduce it too |
+| ħ | h | 0.4 | ≈ 1.5× |
+| long vowels | short | 1.1 | declared, but see the note below |
+| everything else | | 0.0 | the competitor merely has to win |
+
+> Margins on long-vowel targets are skipped at parse time (`"ː" not in t`), because `base()` drops length and the margin would otherwise land on vowel-quality pairs it was not meant for.
+
+The **rule** for a substitution is looked up as `(target, heard)` in the `checks` of [static/assets/pronunciation-rules.md](../static/assets/pronunciation-rules.md). Example:
+
+```yaml
+id: pharyngeal_h
+checks:
+  - {target: ħ, heard: [χ, x], severity: 3, feedback: "…"}
+  - {target: ħ, heard: [h, ɦ], severity: 2, feedback: "…"}
+  - {target: ħ, heard: ["_"],  severity: 2, feedback: "…"}
+```
+
+Severity 3 means the error changes meaning (ħ/χ, ʕ/ʔ); 1 is accent. The rule chooses the Hebrew feedback text and the tip ordering. **It does not change the number.** The score is pure acoustics plus the stages above.
+
+---
+
+## 7. From tokens to words, letters and the sentence
+
+```mermaid
+flowchart BT
+    P1["phoneme scores<br/>(vowels weight 0.5)"] --> WS["word score<br/>0.5 · min + 0.5 · mean"]
+    P1 --> PM["phone mean<br/>weighted"]
+    WS --> WM["word mean"]
+    PM --> SS["sentence = 0.5 · phone mean + 0.5 · word mean"]
+    WM --> SS
+    SS --> UC{"unrelated?"}
+    UC -->|yes| CAP["min(score, 30)"]
+    UC -->|no| R["round → 0–100"]
+    CAP --> R
+    P1 --> LT["letter colour<br/>= weakest of its sounds"]
+```
+
+**Word.** `word = 0.5 · min(phonemes) + 0.5 · mean(phonemes)` (`word_min_weight`). One bad sound drags its word down hard, but not to zero.
+
+**Sentence.**
+
+$$
+\text{phone\_mean} = \frac{\sum_i w_i s_i}{\sum_i w_i},\quad w_i = \begin{cases}0.5 & \text{vowel}\\ 1 & \text{consonant}\end{cases}
+\qquad
+\text{overall} = 0.5\cdot\text{phone\_mean} + 0.5\cdot\overline{\text{word}}
+$$
+
+The word term exists so that a single wrong consonant moves a sentence from "excellent" to "almost". A plain phoneme mean would dilute it across all the correct sounds.
+
+**Letters.** For display, the Hebrew-letter transliteration of each word is mapped back to the tokens that carry each letter (`_carriers`, `word_letters`). Each letter gets the minimum score among its tokens. A letter under `LETTER_GOOD` = 75 also carries `why` (what the sound was heard as) and `tip`. The page colours letters ≥ 75 / ≥ 50 / below.
+
+### 7.1 Worked example
+
+A hypothetical phrase `w eː n | i l ħ a m m aː m` ("where is the bathroom"), with ħ said as χ as in §6.1. Geminate `m m` is one token.
+
+| word | tokens and scores | mean | min | word score |
+|---|---|---|---|---|
+| ween | w 100 · eː 95 · n 100 | 98.3 | 95 | 96.7 |
+| ilħammaam | i 100 · l 100 · **ħ 7.9** · a 96 · m 100 · aː 92 · m 100 | 85.1 | 7.9 | **46.5** |
+
+- phone_mean = (5·100 + 7.9 + 0.5·(95+100+96+92)) / (6 + 4·0.5) = 699.4 / 8 = **87.4**
+- word_mean = (96.7 + 46.5) / 2 = **71.6**
+- overall = 0.5·87.4 + 0.5·71.6 = **79.5 → 80**, which the page labels "כמעט" (almost).
+
+With phoneme averaging alone, the same recording would score 87 and be called excellent.
+
+ħ is flagged: 7.9 < 50, the margin for (ħ, χ) is 0, so −gop = 3.06 ≥ 0, and ħ is a consonant. The rule `pharyngeal_h` gives a severity-3 tip.
+
+---
+
+## 8. "Different sentence?" detection
+
+Forced alignment always produces a path, even for the wrong sentence. To catch this, the scorer greedy-decodes the posteriors (argmax per frame, collapse repeats, drop blanks; real columns only). It then computes the Levenshtein distance to the chosen variant's token ids, with class members counting as equal.
+
+$$
+\text{unrelated} = \frac{\text{edit\_distance}}{N_{\text{tokens}}} > 0.65
+$$
+
+If unrelated, the sentence score is capped at 30, no tips or issues are produced, letters get no reasons, and the page shows "משפט אחר?". It also covers hesitations and restarts (§6.3 #14). The greedy decode is returned as `heard_ipa`. The Hebrew-letter rendering of what was heard (`heard_tr`) is built by cutting the greedy sequence at the aligned word starts.
+
+---
+
+## 9. Feedback selection
+
+```mermaid
+flowchart TD
+    A["Flagged tokens"] --> B["tip_for(sound, heard, rule)<br/>dedupe by tip key"]
+    B --> C["sort: severity desc, then score asc"]
+    C --> D["keep max_tips = 3"]
+    E["All tokens under 100 without a tip"] --> F["keep those under 90 AND beyond margin"]
+    F -->|none and no tips| G["the 3 weakest"]
+    F --> H["issues, up to 8, weakest first"]
+    G --> H
+```
+
+- **Tips** are the flagged substitutions with a rule, most severe first (meaning-changing before accent), then lowest score. At most 3 (4 with the `tips_by_severity` toggle off).
+- **Issues** explain any score short of 100. Every imprecise sound not already covered by a tip, so the student never sees 94 with no reason.
+- **Dialect.** If the accepted realisations used are all urban-only or all rural-only, the result carries `dialect`. If they disagree, it carries `mixed_dialect`. Either way this is informational and never affects the score (§6.3 #12).
+
+---
+
+## 10. The response
+
+```jsonc
+{
+  "score": 80,                          // sentence, 0–100
+  "variant": {"ar": "...", "tr": "...", "ipa": "..."},  // the chosen accepted variant
+  "heard_ipa": "w e n i l χ a m a m",   // greedy decode
+  "heard_tr": "...",                    // the same in Hebrew letters
+  "unrelated": false,
+  "words": [{
+    "ar": "...", "tr": "...", "heard_tr": "...", "score": 46.5,
+    "letters":  [{"t": "חַ", "score": 7.9, "why": "...", "tip": "..."}],
+    "phonemes": [{"ipa": "ħ", "word": 1, "score": 7.9, "flagged": true, "heard": "χ"}]
+  }],
+  "tips":   [{"key": "...", "title": "...", "text": "...", "severity": 3, "word": "...", "score": 8}],
+  "issues": [{"sound": "...", "word_tr": "...", "score": 92, "missing": false, "heard": "..."}],
+  "references": 1,                       // native baselines used
+  "dialect": "urban",                    // or "mixed_dialect": true
+  "calibrated": [ ... ],                 // only if a teacher floor applied
+  "phoneme_heatmap": { ... },            // teachers only: max-pooled posteriors, ≤ 180 columns
+  "trace": { ... }                       // teachers only: every stage, threshold and intermediate value
+}
+```
+
+`trace` is the place to start when debugging a surprising score. It holds the candidate variants with their path log-probs, the unrelated ratio, and per token: window, p_target, competitor, gop, confidence factor, each stage's score, margin needed vs. got, rule, and whether the token became a tip or an issue.
+
+---
+
+## 11. From a recording's score to exercise grades
+
+The scorer grades one recording. Everything above that level is aggregation, mostly on the client.
+
+```mermaid
+flowchart TD
+    R["Recording score 0–100"] --> BAND["Verdict on the card<br/>≥ 85 מצוין · ≥ 60 כמעט · else נסו שוב<br/>unrelated → משפט אחר?"]
+    R --> BEST["Sentence best = max over attempts<br/>(device + attempts table)"]
+    BEST --> TOPIC["Topic: done when every sentence has a best<br/>★ gold when all bests ≥ 85"]
+    TOPIC --> LESSON["Lesson / homework progress"]
+    BEST --> PANEL["Teacher panel: student grade = mean of bests<br/>class 'hard sentences' = class mean of bests under 70"]
+    BEST --> DAILY["Daily session review pool: bests under 85"]
+    R --> QUIZ["Story quiz: mean of line scores said<br/>+ top 3 mistakes by frequency"]
+    R --> VERB["Verb game L4–5: ≥ 75 correct<br/>unrelated / too short → uncertain, not counted"]
+    VERB --> GATE["Level gates: share correct ≥ 85–90 %"]
+```
+
+| Exercise | Grade | Where |
+|---|---|---|
+| Single sentence | The recording's `score`; band 85 / 60 | `index.html` (`EXCELLENT = 85`) |
+| Sentence progress | Best score over all attempts. Any non-empty recording, including an unrelated one, marks the sentence as practised | `keepScore` |
+| Topic | Practised count / total; gold if every best ≥ 85 | `tally()` |
+| Story quiz ("בוחן") | Arithmetic mean of the lines' scores. One recording per line, no retries | `quizEnd()` |
+| Verb game, levels 4–5 | `correct` if score ≥ 75. `unrelated` or too short → `outcome: "uncertain"`, `counts_as_attempt: false`, never a grammar error | [app/speech_evaluation.py](../app/speech_evaluation.py) |
+| Verb game, unlocking | Correct ratio ≥ `VERB_THRESH` (0.85–0.90) over a minimum number of attempts | `index.html` |
+| Arabic → Hebrew translation | Not scored by this pipeline: browser `he-IL` ASR, share of expected words heard in order, 0.8 = correct. Not stored | `index.html` (`HE`) |
+| Teacher panel | Student grade = mean of their best scores; class difficulty per sentence = mean of students' bests | `index.html`, `/api/class` |
+
+Verb game levels 1–3 (choice and matching) are graded server-side by exact match against a stored answer, with no audio involved.
+
+---
+
+## 12. Configuration reference
+
+The values live in code, not in the rules document. The `scoring:` block of `pronunciation-rules.md` is read for **`margins`, `margin_default` and `max_tips` only**. Its other keys (`flag_below`, `bands`, `sentence_score`, `severity_weight`, …) are documentation. Its `sentence_score` string (`mean(word_min)`) also describes an older word formula; the code uses `0.5·min + 0.5·mean`.
+
+| Knob | Default | Effect |
+|---|---|---|
+| `GopConfig.leniency` | 0.5 | exponent on the target/competitor ratio |
+| `GopConfig.confident_peak` | 0.30 | target posterior above which confidence stops lowering the score |
+| `GopConfig.deleted_peak` / `deleted_comp` | 0.05 / 0.20 | deletion thresholds |
+| `ScorerConfig.flag_below` | 50 | max score for a flag and tip |
+| `ScorerConfig.issue_below` | 90 | max score to be listed as an issue |
+| `ScorerConfig.near_vowel_floor` | 90 | floor for neighbouring vowel qualities |
+| `ScorerConfig.word_min_weight` | 0.5 | weight of the weakest phoneme in a word |
+| `ScorerConfig.unrelated_ratio` | 0.65 | edit-distance ratio for "different sentence" |
+| `ScorerConfig.ref_min_mean` | 60 | minimum mean for a TTS reference to be trusted |
+| vowel weight | 0.5 | in the sentence phone mean (hard-coded) |
+| unrelated cap | 30 | hard-coded |
+| `LETTER_GOOD` | 75 | letter colour / reason threshold |
+| insertion `min_peak`, `min_frames`, `score_cap` | 0.5, 2, 60 | rule 3.10, from the rules document |
+
+Teachers can switch off each rule-derived behaviour at runtime (the **ניטור** tab, `rules.TOGGLES`). Switching one off restores the pre-rules behaviour for that aspect from the next recording on.
+
+---
+
+## 13. Known limitations
+
+- **Zero-shot model.** The base model was not trained on Palestinian Arabic or Hebrew-accented speech. The native baseline and margins compensate partially; fine-tuning ([train/finetune.py](../train/finetune.py)) on teacher and labelled learner recordings is the intended fix.
+- **Duration is not modelled.** CTC posteriors are peaky and collapse repeats, so vowel length and gemination are effectively unscored.
+- **Fallback symbols.** If the vocab lacks a phoneme (e.g. `ðˤ`), it is scored as its stand-in. `/api/health` → `phoneme_fallbacks` lists these, and the contrast they lose cannot be detected.
+- **GOP is max-pooled, not frame-summed.** Using window peaks makes the score robust to alignment jitter, but a brief spurious competitor spike can still win the window.

static/guide.html

@@ -376,13 +376,13 @@ a,button{-webkit-tap-highlight-color:transparent}
         <div class="m-bar"><span class="m-btn p">→ חזרה למסלול</span><span class="m-sp"></span><span class="m-btn">☰ רשימה</span><span class="m-btn gear hl">⚙</span></div>
         <div class="dlg">
           <div class="dlg-h"><b>הגדרות השמעה</b><span class="m-btn">סגירה</span></div>
-          <div class="row at l"><span class="n">1</span><span>קול ההשמעה</span><span class="sel">אמיר ▾</span></div>
+          <div class="row at l"><span class="n">1</span><span>קול ההשמעה</span><span class="sel">רַאאִף</span></div>
           <div class="row at l"><span class="n">2</span><span>מהירות</span><span class="seg"><i>x0.8</i><i class="on">x1</i><i>x1.5</i></span></div>
           <div class="row at l"><span class="n">3</span><span>הקראת המשפט בעברית</span><span class="tg on" aria-hidden="true"></span></div>
         </div>
       </div>
       <ol class="key">
-        <li><span class="n">1</span><div><b>קול ההשמעה</b><span class="d">בוחרים מי מקריא את הערבית: <b style="display:inline">אמיר</b>, <b style="display:inline">ראאף</b> או <b style="display:inline">חנאן</b>. זה הקול של „השמע” ושל סיפורים. בשיחה יש לכל דובר קול משלו.</span></div></li>
+        <li><span class="n">1</span><div><b>קול ההשמעה</b><span class="d"><b style="display:inline">רַאאִף</b> מקריא את כל התשובות, הסיפורים והשיחות.</span></div></li>
         <li><span class="n">2</span><div><b>מהירות</b><span class="d"><b style="display:inline">x0.8</b> לאט יותר, כדי לשמוע כל הברה. <b style="display:inline">x1</b> רגיל. <b style="display:inline">x1.5</b> מהיר, לאימון הבנת שמיעה.</span></div></li>
         <li><span class="n">3</span><div><b>הקראת המשפט בעברית</b><span class="d">כשמסומן, כל משפט חדש מוקרא בקול בעברית לפני שעונים, כך שאפשר לתרגל בלי לקרוא מהמסך. בנושאי ערבית ← עברית אין הקראה, כי העברית היא התשובה.</span></div></li>
       </ol>

static/index.html

@@ -1013,7 +1013,6 @@ body.quiet :is(#mic,#playMine,#driveBtn,.phone-btn),body.driving :is(#quietBtn,#
 <dialog id="setDlg" aria-labelledby="setTitle">
   <div class="dlg-head"><h2 id="setTitle">הגדרות השמעה</h2><button class="btn" id="setClose">סגירה</button></div>
   <div class="voicebox">
-    <label>קול ההשמעה<select id="voiceId"></select></label>
     <label>מהירות<select id="speed"><option value="0.8">x0.8</option><option value="1">x1</option><option value="1.5">x1.5</option></select></label>
     <label>הקראת המשפט בעברית<input type="checkbox" id="readHe"></label>
   </div>
@@ -2689,7 +2688,7 @@ function drawAnalyzedAnswer(r){
     pair.append(expected,heard); main.append(pair);
   });
   card.replaceChildren(mark("analysis-key","למעלה: התשובה · למטה: המערכת שמעה","small"),main);
-  card.append(mark("ar",cur.ar,"small"));
+  card.append(mark("ar",cur.ar_pointed||cur.ar,"small"));
   if(cur.read) card.append(mark("he",cur.he,"small"));
   card.classList.add("revealed","scored"); card.removeAttribute("role"); card.removeAttribute("tabindex"); card.removeAttribute("aria-label"); card.onclick=null; card.onkeydown=null;
   $("hintLabel").textContent=hasWhy(r)?WHY_HINT:"התשובה וניתוח ההגייה";
@@ -2700,7 +2699,7 @@ function drawWordReveals(){
   const button=mark("word-reveal","","div"); button.setAttribute("role","button"); button.tabIndex=0;
   button.setAttribute("aria-label",cur.read?"גלו את התרגום לעברית":"גלו את התרגום לערבית");
   const main=mark("",answer); setTr(main,answer); main.setAttribute("aria-hidden","true"); button.append(main);
-  if(!cur.read){ const ar=mark("ar",cur.ar,"small"); ar.setAttribute("aria-hidden","true"); button.append(ar); }
+  if(!cur.read){ const ar=mark("ar",cur.ar_pointed||cur.ar,"small"); ar.setAttribute("aria-hidden","true"); button.append(ar); }
   button.onclick=()=>revealWord(button); box.append(button);
   button.onkeydown=e=>{ if(e.key==="Enter"||e.key===" "){ e.preventDefault(); revealWord(button); } };
   $("hintLabel").textContent=cur.read?"לחצו על הכרטיסייה כדי לגלות את התרגום לעברית":"לחצו על הכרטיסייה כדי לגלות את התרגום לערבית";
@@ -2730,7 +2729,7 @@ $("prevBtn").onclick=()=>{   // the sentence before this one in the topic, pract
 };
 function arVoice(){ const vs=speechSynthesis.getVoices(); return vs.find(v=>/^ar[-_](PS|JO|LB|SY|IL)/i.test(v.lang))||vs.find(v=>/^ar/i.test(v.lang)); }
 if("speechSynthesis" in window) speechSynthesis.getVoices();
-const ttsUrls={};   // "phrase id|voice" -> {url} of the server-generated answer
+const ttsUrls={};   // phrase id -> {url} of Raef's server-generated answer
 // the guide's line for a new student: until it is opened or closed once
 const guideSeen=()=>{ store.set("ihki.guideSeen",true); $("guideTip").hidden=true; };
 $("guideTip").hidden=store.get("ihki.guideSeen",false);
@@ -2740,41 +2739,49 @@ $("readHe").onchange=()=>{
   store.set("ihki.readHe",$("readHe").checked);
   if(!(rec&&rec.state==="recording")) promptRead=readPrompt();
 };
-$("voiceId").onchange=()=>store.set("ihki.voice",$("voiceId").value);   // Sawtak voice of the playback; options come from the server
 // Speed of the Arabic answer. The provider has no speed setting: the browser plays the same audio slower or faster, at the same pitch.
 $("speed").value=String(store.get("ihki.speed",1)); if(!$("speed").value) $("speed").value="1";
 $("speed").onchange=()=>store.set("ihki.speed",+$("speed").value);
 const answerRate=()=>+$("speed").value||1;
 function answerPlayer(url){ const a=new Audio(url); a.preservesPitch=true; a.playbackRate=answerRate(); return a; }
-let ttsOff=false;   // server has no TTS key: stop asking
-// A story is a dialogue: its lines are said in turn by the topic's two voices, found by name (without the points) in
-// the server's list, so the speakers sound apart. Anywhere else, and when a name is not in the list, the chosen voice.
-function lineVoice(id){
-  const sel=$("voiceId"), c=!daily&&CATS.find(c=>c.id===cat)||{}, k=topic.indexOf(id);
-  const name=c.story&&c.voices&&k>=0&&c.voices[k%2], o=name&&[...sel.options].find(o=>o.text.replace(/[\u0591-\u05C7]/g,"")===name);
-  return o?o.value:sel.value;
+let playbackContext=null;
+function unlockPlayback(){
+  try{
+    playbackContext=playbackContext||new (window.AudioContext||window.webkitAudioContext)();
+    playbackContext.resume(); return playbackContext;
+  }catch{return null}
+}
+async function playAnswer(recording,context){
+  const audio=answerPlayer(recording.url);
+  try{ await audio.play(); return; }catch(error){ if(!context) throw error; }
+  const buffer=await context.decodeAudioData(await recording.blob.arrayBuffer());
+  const source=context.createBufferSource(); source.buffer=buffer; source.playbackRate.value=answerRate();
+  source.connect(context.destination); source.start();
 }
+let ttsOff=false;   // server has no TTS key: stop asking
 async function answerAudio(id){   // {url} of the Sawtak answer, or null when the server voice is unavailable
-  const voice=lineVoice(id), key=id+"|"+voice;
-  if(!ttsOff && !ttsUrls[key]){
+  if(!ttsOff && !ttsUrls[id]){
     try{
-      const res=await api("/api/tts/"+id+(voice?"?voice="+encodeURIComponent(voice):""));
+      const res=await api("/api/tts/"+id+"?v=5");
       if(res.ok){
-        ttsUrls[key]={url:URL.createObjectURL(await res.blob())};
+        const blob=await res.blob(); ttsUrls[id]={blob,url:URL.createObjectURL(blob)};
       }else{
         const detail=(await res.json().catch(()=>({}))).detail||res.status;
         if(detail==="tts not configured") ttsOff=true;   // no key on the server: stop asking
       }
     }catch{}
   }
-  return ttsUrls[key]||null;
+  return ttsUrls[id]||null;
 }
 $("speakBtn").onclick=async()=>{
-  const id=cur.id, btn=$("speakBtn");
-  btn.disabled=true; const a=await answerAudio(id); btn.disabled=false;
-  if(a){ if(cur.id===id){ answerPlayer(a.url).play(); } return; }
+  const id=cur.id, btn=$("speakBtn"), label=btn.querySelector("small"), context=unlockPlayback();
+  btn.disabled=true; label.textContent="טוען…"; const a=await answerAudio(id); btn.disabled=false; label.textContent="השמע";
+  if(a){
+    if(cur.id===id) try{ await playAnswer(a,context); }catch{ $("status").textContent="הדפדפן חסם את ההשמעה. נסו שוב."; }
+    return;
+  }
   if(!("speechSynthesis" in window)) return;
-  const u=new SpeechSynthesisUtterance(cur.ar); const v=arVoice();
+  const u=new SpeechSynthesisUtterance(cur.ar_pointed||cur.ar); const v=arVoice();
   if(v){u.voice=v;u.lang=v.lang;} else u.lang="ar-SA";
   u.rate=.85*answerRate(); speechSynthesis.cancel(); speechSynthesis.speak(u);
 };
@@ -3044,6 +3051,7 @@ function drawScoringRules(box){
 function drawFlags(){
   const box=$("mFlags"); box.innerHTML=""; for(const url of flagAudioUrls) URL.revokeObjectURL(url); flagAudioUrls=[];
   drawActivity(box);
+  drawTtsCacheControls(box);
   if(!flagsLoaded){ box.append(mark("card","בחרו בניטור כדי לטעון את הנתונים.")); return; }
   drawScoringRules(box);
   if(flagsError){ const card=mark("card",""); card.append(mark("","לא ניתן לטעון את הדיווחים","h2"),mark("",flagsError,"p")); box.append(card); return; }
@@ -3128,6 +3136,23 @@ function drawFlags(){
     confirm.onclick=()=>save("confirmed"); reject.onclick=()=>save("rejected"); actions.append(category,confirm,reject,msg); card.append(note,actions); box.append(card);
   }
 }
+function drawTtsCacheControls(box){
+  const card=mark("card",""), title=mark("","מטמון הקלטות Sawtak","h2"), text=mark("","מחיקה גורמת ליצירה מחדש של הקלטות התשובה בהשמעה הבאה. גם הקלטות שנבחרו ידנית יימחקו.","p");
+  const row=mark("row",""), button=mark("btn","מחיקת מטמון ההקלטות","button"), msg=mark("msg","");
+  button.onclick=async()=>{
+    if(!confirm("למחוק את כל הקלטות התשובה מהמטמון? גם הקלטות שנבחרו ידנית יימחקו, ולא ניתן לבטל את הפעולה.")) return;
+    button.disabled=true; msg.textContent="מוחק…";
+    try{
+      const res=await api("/api/tts-cache",{method:"DELETE"}), data=await res.json().catch(()=>({}));
+      if(!res.ok) throw new Error(data.detail||res.status);
+      for(const value of Object.values(ttsUrls)) URL.revokeObjectURL(value.url);
+      for(const key of Object.keys(ttsUrls)) delete ttsUrls[key];
+      msg.textContent=`נמחקו ${data.removed} קבצי מטמון.`;
+    }catch(err){ msg.textContent="המחיקה נכשלה: "+err.message; }
+    button.disabled=false;
+  };
+  row.append(button,msg); card.append(title,text,row); box.append(card);
+}
 function drawActivity(box){
   const days=activityHours===168, range=days?"7 הימים":"24 השעות", bucket=days?"שעה":"15 דקות";
   const card=mark("card activity",""), head=mark("activity-head",""), title=mark("",`פעילות ב־${range} האחרונים`,"h2"), sub=mark("",`כל עמודה מייצגת ${bucket} · מתעדכן פעם בדקה`,"p");
@@ -3194,7 +3219,7 @@ function drawContent(){
   const guides=mark("guides","מדריכים:","div");
   for(const a of $("guideDlg").querySelectorAll("article")){ const b=mark("btn",a.dataset.title,"button"); b.onclick=()=>showGuide(a.dataset.guide); guides.append(b); }
   box.append(guides);
-  const voices=[...$("voiceId").options].filter(o=>o.value).map(o=>o.text.replace(/[֑-ׇ]/g,""));
+  const voices=["ראאף"];
   const adder=(adds,label,fields,note,submit)=>{   // a closed form under a lesson, or under a level's daily videos
     const add=document.createElement("details"), form=document.createElement("form"), row=mark("row",""), msg=mark("msg","");
     add.className="vadd"; add.append(mark("btn",label,"summary"),form); form.className="cform"; msg.setAttribute("role","alert");
@@ -3901,8 +3926,6 @@ const ready=fetch("/api/phrases").then(r=>r.json()).then(d=>{
   ALL_LEVELS=d.levels||[]; ALL_LESSONS=d.lessons; ALL_CATS=d.categories; GAMES=d.games||[]; PHRASES=d.phrases;
   $("nav").querySelector('[data-view="games"]').hidden=!GAMES.some(game=>!game.hidden);
   for(const c of ALL_CATS) c.name=c.name.replace(/ ← /g,"\u00a0←\u00a0");   // the arrow never ends a line
-  for(const v of d.voices||[]) $("voiceId").add(new Option(v.name,v.id));
-  const saved=store.get("ihki.voice",""); if((d.voices||[]).some(v=>v.id===saved)) $("voiceId").value=saved;
   useLessons(MY_LESSONS);
   startCat(); opened=true;
 }).catch(()=>{ $("prompt").textContent="השרת לא זמין."; });

tests/test_arabic_diacritics.py

@@ -0,0 +1,103 @@
+from app.arabic_diacritics import point_arabic
+
+
+def test_points_short_vowels_sukun_and_long_vowel():
+    assert point_arabic("مرحبا", "m a r ħ a b a") == "مَرْحَبَا"
+
+
+def test_points_geminate_and_keeps_punctuation():
+    assert point_arabic("يلّا!", "j a l l a") == "يَلَّا!"
+
+
+def test_points_each_word_of_a_phrase():
+    assert point_arabic("شو اسمك", "ʃ u | ʔ i s m a k") == "شُو اِسْمَكْ"
+
+
+def test_public_phrase_has_a_separate_pointed_answer():
+    from app.phrases import public_phrases
+
+    answer = next(phrase for phrase in public_phrases() if phrase["he"] == "אני")
+    assert answer["ar"] == "انا"
+    assert answer["ar_pointed"] == "اَنَا"
+
+
+def test_sawtak_keeps_pronunciation_enhancement_on_for_pointed_input(tmp_path):
+    from app.tts import SawtakTTS
+
+    request = {}
+
+    class Response:
+        headers = {"X-Sample-Rate": "24000"}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_args):
+            pass
+
+        def read(self):
+            return b"\0" * 5000
+
+    tts = SawtakTTS("key", cache_dir=tmp_path)
+
+    def fake_request(path, body=None):
+        request.update(path=path, body=body)
+        return Response()
+
+    tts._request = fake_request
+    tts.wav("اَكَلْ، يُاكُلْ", "voice")
+    assert request["path"] == "/audio/speech"
+    assert request["body"]["input"] == "اَكَلْ، يُاكُلْ"
+    assert request["body"]["enhance_pronunciation"] is True
+    assert "temperature" not in request["body"]
+
+
+def test_raef_recording_is_cached_and_cache_can_be_cleared(tmp_path):
+    from app.tts import RAEF_VOICE_ID, SawtakTTS
+
+    generated, requests = 0, []
+
+    class Response:
+        headers = {"X-Sample-Rate": "24000"}
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_args):
+            pass
+
+        def read(self):
+            return b"\0" * 5000
+
+    tts = SawtakTTS("key", cache_dir=tmp_path)
+
+    def fake_request(_path, _body=None):
+        nonlocal generated
+        generated += 1
+        requests.append(_body)
+        return Response()
+
+    tts._request = fake_request
+    first, voice = tts.wav("مَرْحَبَا", "ignored-voice")
+    second, second_voice = tts.wav("مَرْحَبَا")
+    assert first == second
+    assert voice == second_voice == RAEF_VOICE_ID
+    assert generated == 1
+    assert all("temperature" not in body and body["enhance_pronunciation"] is True for body in requests)
+
+    (tmp_path / "keep.txt").write_text("not audio")
+    assert tts.clear_cache() == 1
+    assert (tmp_path / "keep.txt").exists()
+    assert not list(tmp_path.glob("*.wav"))
+
+
+def test_only_raef_is_offered_and_is_the_configured_default(monkeypatch):
+    from app.tts import RAEF_VOICE_ID, VOICES, load_tts
+
+    monkeypatch.setenv("SAWTAK_API_KEY", "key")
+    monkeypatch.setenv("SAWTAK_VOICE_ID", "an-old-different-voice")
+    tts = load_tts()
+    assert VOICES == {"רַאאִף": RAEF_VOICE_ID}
+    assert tts.voice_id == RAEF_VOICE_ID
+
+

tests/test_scoring.py

@@ -361,24 +361,24 @@ def test_tts_endpoint_serves_phrase_audio_and_503_without_key():
     from app.main import create_app
 
     class FakeTTS:
-        voice_id, voice_name = "v-123", "ليلى"
+        from app.tts import RAEF_VOICE_ID
+        voice_id, voice_name = RAEF_VOICE_ID, "רַאאִף"
 
         def wav(self, text, voice=""):
-            assert text == PHRASES[0]["variants"][0][0]
-            return b"RIFFfake", voice or self.voice_id
+            from app.arabic_diacritics import point_arabic
+            assert text == point_arabic(*PHRASES[0]["variants"][0])
+            assert voice == self.voice_id
+            return b"RIFFfake", self.voice_id
 
     with TestClient(create_app(scorer_for(emissions(["w"])), FakeTTS())) as c:
         r = c.get("/api/tts/0")
         assert r.status_code == 200 and r.headers["content-type"] == "audio/wav" and r.content == b"RIFFfake"
-        assert r.headers["x-tts-provider"] == "sawtakarabi.ai" and r.headers["x-tts-voice-id"] == "v-123"
-        from urllib.parse import unquote
+        assert r.headers["x-tts-provider"] == "sawtakarabi.ai" and r.headers["x-tts-voice-id"] == FakeTTS.voice_id
 
         from app.tts import VOICES
         voices = c.get("/api/phrases").json()["voices"]
         assert [v["name"] for v in voices] == list(VOICES)
-        r = c.get("/api/tts/0?voice=" + voices[1]["id"])
-        assert r.headers["x-tts-voice-id"] == voices[1]["id"] and unquote(r.headers["x-tts-voice-name"]) == voices[1]["name"]
-        assert c.get("/api/tts/0?voice=not-in-the-list").status_code == 400
+        assert voices == [{"id": FakeTTS.voice_id, "name": "רַאאִף"}]
         assert c.get("/api/tts/9999").status_code == 404
         health = c.get("/api/health").json()
         assert health["tts"] is True and health["rules"]["pharyngeal_h"]["detectable"]
@@ -545,8 +545,10 @@ def test_references_use_one_generated_voice_and_any_cached_one():
         refs = References(s, tts, ["first", "never-played", "played"])
         assert len(refs.get(7, ALA)) == 2 and calls == ["first", "played"]
         assert len(refs.get(7, ALA)) == 2 and len(calls) == 2            # kept in memory
+        assert refs.invalidate(7, "first") == 1
+        assert len(refs.get(7, ALA)) == 2 and calls == ["first", "played", "first"]
         tts.down = True
-        assert refs.get(8, ALA) == [] and refs.get(8, ALA) == [] and len(calls) == 4   # failures are not retried at once
+        assert refs.get(8, ALA) == [] and refs.get(8, ALA) == [] and len(calls) == 5   # failures are not retried at once
     finally:
         reference.decode_audio = orig
 
@@ -1354,7 +1356,8 @@ def test_sign_in_guards_the_practice_endpoints():
                                       "pos": N1, "ord": 2, "guessed": ["זַלַמֶה"]}   # the course has the other words
         assert "voices" not in d["categories"][1] and d["categories"][1]["ord"] == 3
         line1, line2, line3 = d["phrases"][:3]
-        assert line1 == {"id": 1_001_000, "cat": "t1", "he": "שלום", "tr": "מַרְחַבַּא", "ar": "مرحبا", "seq": 1}
+        assert line1 == {"id": 1_001_000, "cat": "t1", "he": "שלום", "tr": "מַרְחַבַּא", "ar": "مرحبا",
+                         "ar_pointed": "مَرْحَبَا", "seq": 1}
         assert (line2["id"], line2["ar"], line3["ar"]) == (1_001_001, "كيف حالك؟", "مرحبا يا زلمة") and len(d["phrases"]) == 6
         # a line is a phrase like the bank's: it has a prompt and an answer to play, and its recordings count (two lines
         # with the same Hebrew stay apart)