Add keystore for managing API keys securely and update tests

- Implemented a new KeyStore class to handle API keys securely, encrypting them and ensuring they are never exposed.
- Added functionality to load, save, and clear keys, with validation against their respective providers.
- Created tests for the KeyStore to ensure keys are stored encrypted, swapped in place, and reverted to environment variables when cleared.
- Updated existing tests to include checks for new functionality related to API keys and tutor model management.

.env.example

@@ -55,3 +55,9 @@ APP_VERSION=
 BUILD_DATE=
 GIT_COMMIT=
 GIT_COMMIT_MESSAGE=
+
+# Lets a developer replace SAWTAK_API_KEY / ANTHROPIC_API_KEY from the management panel (kept encrypted in Supabase,
+# table app_secrets; see the README). Make one with:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+# Keep it only here / as a Space secret. Losing it loses the keys set in the panel (the ones above still work).
+SECRETS_MASTER_KEY=

README.md

@@ -158,6 +158,28 @@ create index system_events_created_at_idx on public.system_events (created_at de
 alter table public.system_events enable row level security;
 ```
 
+API keys a developer replaces from the panel (`SAWTAK_API_KEY`, `ANTHROPIC_API_KEY`, see `app/keystore.py`), and the tutor's model (`TUTOR_MODEL`, chosen from a list or typed), so changing one needs no access to the Space. Each value is stored encrypted with `SECRETS_MASTER_KEY`, a Space secret, and the page never gets a key back (the model, which is no secret, it shows). No browser role can read the table:
+
+```sql
+create table public.app_secrets (
+  name        text primary key check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL')),
+  ciphertext  text not null,
+  last4       text not null default '',
+  updated_by  text not null default '',
+  updated_at  timestamptz not null default now()
+);
+alter table public.app_secrets enable row level security;
+revoke all on public.app_secrets from anon, authenticated;
+```
+
+A table made before the panel could set `TUTOR_MODEL` needs its name check widened once (saving the model answers 409 with this SQL until then):
+
+```sql
+alter table public.app_secrets drop constraint if exists app_secrets_name_check;
+alter table public.app_secrets add constraint app_secrets_name_check
+  check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL'));
+```
+
 For an existing `attempts` table, add the compact diagnostics once. Until this migration is run, attempts continue to be saved without diagnostics:
 
 ```sql
@@ -610,3 +632,45 @@ Tune them on a handful of labelled learner recordings. A useful target is that n
 - 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 רַאאִף 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`.
+
+## Cost estimate (API keys)
+
+Estimated 2026-10-18 for **100 students, each doing 5 tutor chats a day (the daily limit, `DAILY_LIMIT`) of 10 turns each**: 500 chats a day, 15,000 a month (30 days). Anthropic prices are list prices per million tokens; the Sawtak price is the rate your own account was charged.
+
+### Anthropic (`ANTHROPIC_API_KEY`) — the tutor game יאללה נדבר
+
+How a chat is billed: 11 calls (the opening plus 10 turns). Each call sends the scenario's system prompt and the reply schema (the prefix), plus the conversation so far. The prefix grows with the lessons' vocabulary: 4,364 tokens in lesson 1, 16,466 mid-course and 22,728 in the last lesson (measured with `count_tokens`; the 5.5 models count the same). Each turn adds about 540 tokens of history, and each answer is about 490 output tokens. `cache_control` caches the prompt, so every call after the first reads the earlier part from the cache and writes only the new turn. That assumes the turns are less than 5 minutes apart, which a spoken conversation is.
+
+Tokens per chat (mid-course): ~22K cache writes (1.25× the input price), ~189K cache reads, ~5.7K output.
+
+| Model (`TUTOR_MODEL`) | $ in / out / cache read per 1M | Per chat (mid-course) | Per day | **Per month**: lesson 1 / mid / last | Per student per month (mid) |
+|---|---|---|---|---|---|
+| `claude-haiku-5-5` (the default) | 0.10 / 0.50 / 0.01 | $0.0075 | $3.73 | **$71 / $112 / $133** | $1.12 |
+| `claude-haiku-4-5` | 1 / 5 / 0.10 | $0.075 | $37 | $712 / $1,120 / $1,332 | $11.20 |
+| `claude-sonnet-5-5` | 2 / 10 / 0.20 | $0.149 | $75 | $1,424 / $2,241 / $2,663 | $22.40 |
+| `claude-opus-5-5` ¹ | 4 / 20 / 0.20 | $0.261 | $130 | $2,644 / $3,914 / $4,572 | $39.10 |
+| `claude-fable-5-1` ¹ | 10 / 50 / 0.25 | $0.605 | $303 | $6,354 / $9,077 / $10,486 | $90.80 |
+
+- **Without the prompt cache** the input would cost 3–3.5× more (for example Haiku 5.5 mid-course: $359 a month instead of $112). Keep `cache_control` in `Tutor._ask`.
+- These are upper bounds for the volume: every student uses all 5 chats, every day, all 10 turns. Real use is usually lower; `tutor_chats` records each chat's `input_tokens` and `output_tokens`, so the real bill can be checked against this table.
+- ¹ Opus 5.5 and Fable 5.1 cannot turn thinking off, so the tutor leaves it adaptive at `effort: "low"` (`thinking_for()` in `app/tutor.py`). The thinking tokens they spend are billed as output and are not in this table, so expect somewhat more for these two.
+- Set a monthly spending limit in the Console (Settings → Limits), so that a bug or unexpected use cannot cost more than planned.
+
+### Sawtak Arabi (`SAWTAK_API_KEY`) — the model-answer voice
+
+Sawtak charges per character of text spoken. This account was charged **$5.00 for 99,600 characters (about $0.05 per 1,000 characters, $50 per million)** in the 30 days before 2026-10-18 (`GET /v1/usage`).
+
+- **If the tutor's messages are spoken with Sawtak too** (the code does not do this yet), each one costs again: every message is new text, so none comes from the cache. A message is one or two short sentences, about 90 characters with vowel marks (the phrase bank averages 51 per phrase). A chat has 11 messages (the opening and 10 answers), so about 1,000 characters:
+
+  | | Characters | Cost |
+  |---|---|---|
+  | Per chat | ~990 | ~$0.05 |
+  | Per day (500 chats) | ~495,000 | ~$25 |
+  | **Per month (15,000 chats)** | ~14.9 million | **~$745** (between ~$500 and ~$1,000 for messages of 60–120 characters) |
+  | Per student per month | ~149,000 | ~$7.45 |
+
+  That is more than the tutor's model costs on Haiku 5.5 (~$112 a month), so voicing the tutor would be most of the bill.
+- The rest of the cost comes from "🔊 השמע" and from the native baseline the scores are calibrated against, both for the phrase bank:
+- Each phrase is generated once and kept in the voice cache (`TTS_CACHE_DIR`). All 3,546 phrases come to about 180,000 characters with their vowel marks, so **voicing the whole bank costs about $9, once**. A text's dialogue lines in the second voice add a little.
+- **The number of students does not change this cost**: 100 students cost the same as 1, because the second student to play a phrase gets it from the cache.
+- What does cost more: the cache is a folder on the server's disk. A Hugging Face Space without persistent storage loses it on every restart and rebuild, and "מחיקת מטמון ההקלטות" in the panel empties it. After either, the phrases are generated again as they are played, up to about $9 each time. To avoid that, give the Space persistent storage and set `TTS_CACHE_DIR=/data/ihki-tts`.

app/align.py

@@ -111,6 +111,7 @@ class TokenScore:
     realised: int | None = None  # a class target (several correct realisations): the one said
     other: bool = False          # the strongest competitor is a sound outside the named set
     comp_peak: float = NEG       # max log-posterior of the strongest competitor (named or not) in the window
+    comp_frames: int = 0         # frames where that competitor clears deleted_comp (duration evidence)
     window: tuple[int, int] = (0, 0)  # [start, end) frames the target and its competitors were read from
 
 
@@ -239,6 +240,9 @@ def compute_token_gop(logp: np.ndarray, spans: list[tuple[int, int]], i: int, to
     ratio[mask] = NEG
     comp = int(ratio.argmax())
     comp_peak = float(maxed[comp]) if ratio[comp] > NEG / 2 else NEG
+    # A lone CTC spike can be a breath or microphone onset rather than a produced consonant. Keep duration
+    # evidence separately from the peak so pronunciation policy can distinguish transients from substitutions.
+    comp_frames = int(np.count_nonzero(rcols[:, comp] >= cfg.deleted_comp)) if ratio[comp] > NEG / 2 else 0
     tseg = logp[ra:rb, [tok]]
     target = float(tseg.max()) if how == "max" else float(pool_frames(tseg, how, cfg.pool_k, cfg.pool_tau, weight)[0])
 
@@ -248,7 +252,7 @@ def compute_token_gop(logp: np.ndarray, spans: list[tuple[int, int]], i: int, to
     present = comp_peak > NEG / 2
     other = bool(present and named is not None and comp not in named)
     return TokenScore(round(score, 1), round(gop, 3), round(peak, 3), comp if present and not other else None,
-                      deleted, realised, other, round(comp_peak, 3), (int(ra), int(rb)))
+                      deleted, realised, other, round(comp_peak, 3), comp_frames, (int(ra), int(rb)))
 
 
 def score_tokens(logp: np.ndarray, align: Alignment, tokens: list[int], blank: int,

app/auth.py

@@ -661,6 +661,24 @@ class SupabaseAuth:
             log.warning("access changed but audit row was not stored: %s", e)
         self.log_event("permission", actor, target["email"], {"roles": roles, "entitlements": entitlements})
 
+    def secret_rows(self) -> list[dict] | None:
+        """The API keys set in the panel, encrypted (see keystore.py), or None until the table `app_secrets` exists."""
+        try:
+            return self._admin("/rest/v1/app_secrets?select=name,ciphertext,last4,updated_by,updated_at") or []
+        except AuthUnavailable as e:
+            if "answered 404" in str(e):
+                return None
+            raise
+
+    def save_secret(self, row: dict) -> None:
+        self._admin("/rest/v1/app_secrets?on_conflict=name", "POST",
+                    {**row, "updated_at": datetime.now(timezone.utc).isoformat()},
+                    prefer="resolution=merge-duplicates,return=minimal")
+
+    def delete_secret(self, name: str) -> None:
+        self._admin("/rest/v1/app_secrets?" + urllib.parse.urlencode({"name": f"eq.{name}"}), "DELETE",
+                    prefer="return=minimal")
+
     def all_attempts(self) -> list[dict]:
         """Every student's attempts, as `attempts` gives one student's, each with its user_id. "Different sentence"
         rows remain marked as unrelated for diagnostics, but count toward progress like every non-empty recording."""

app/keystore.py

@@ -0,0 +1,204 @@
+"""API keys a developer sets in the management panel (SAWTAK_API_KEY, ANTHROPIC_API_KEY), and the tutor's model
+(TUTOR_MODEL), so changing one needs no access to the host (the Hugging Face Space).
+
+Each key is kept in the Supabase table `app_secrets`, encrypted with Fernet under SECRETS_MASTER_KEY, which lives only in
+the host's environment: the table, a backup of it or a look at the Supabase dashboard shows no key. The table has
+row-level security on and no policy, so only the server's secret key reads it. A key never goes back to the page: the
+panel sees whether it is set, where from, and its last four characters. A new key is tried with its provider before it
+is kept, so a typo cannot switch the playback or the tutor off. TUTOR_MODEL is no secret: it is kept the same way, but
+the panel shows it, and a model is checked by asking Anthropic for it with the key in use.
+
+A key kept in the table takes the place of the environment's; without one (or without the table, the secret key or the
+master key) the environment's is used, as before.
+
+Env:  SECRETS_MASTER_KEY  (a Fernet key; make one with
+                           python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+                           and keep it as a Space secret. Losing it loses the stored keys, not the environment's.)
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import threading
+import urllib.error
+import urllib.request
+
+from .auth import AuthUnavailable
+
+log = logging.getLogger("ihki.keys")
+# the keys the panel may set, and how the panel names them; nothing else (the master key, the Supabase keys) is settable
+NAMES = {"SAWTAK_API_KEY": "Sawtak Arabi · השמעת התשובה", "ANTHROPIC_API_KEY": "Anthropic · המורה (יאללה נדבר)",
+         "TUTOR_MODEL": "המודל של המורה (TUTOR_MODEL)"}
+FALLBACK = {"ANTHROPIC_API_KEY": ("ANTHROPIC_API_KEY", "CLAUDE_API_KEY"), "SAWTAK_API_KEY": ("SAWTAK_API_KEY",),
+            "TUTOR_MODEL": ("TUTOR_MODEL",)}
+PUBLIC = frozenset({"TUTOR_MODEL"})   # settings the panel may show in full
+# the panel's list of tutor models (any other id can be typed); empty = the code's default (tutor.DEFAULT_MODEL)
+MODEL_CHOICES = [("claude-haiku-5-5", "Haiku 5.5 · ברירת המחדל, הזול ביותר"), ("claude-sonnet-5-5", "Sonnet 5.5"),
+                 ("claude-opus-5-5", "Opus 5.5"), ("claude-fable-5-1", "Fable 5.1 · היקר ביותר"), ("claude-haiku-4-5", "Haiku 4.5")]
+MODEL_ID = re.compile(r"^claude-[a-z0-9][a-z0-9.-]{2,60}$")
+MAX_LEN = 300
+TIMEOUT = 15
+CREATE_APP_SECRETS = ("create table public.app_secrets (name text primary key check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL')), "
+                      "ciphertext text not null, last4 text not null default '', updated_by text not null default '', "
+                      "updated_at timestamptz not null default now()); "
+                      "alter table public.app_secrets enable row level security; "
+                      "revoke all on public.app_secrets from anon, authenticated;")
+# for a table made before TUTOR_MODEL could be kept in it
+MIGRATE_APP_SECRETS = ("alter table public.app_secrets drop constraint if exists app_secrets_name_check; "
+                       "alter table public.app_secrets add constraint app_secrets_name_check "
+                       "check (name in ('SAWTAK_API_KEY','ANTHROPIC_API_KEY','TUTOR_MODEL'));")
+
+
+class KeyRefused(ValueError):
+    """The provider refused the key, or it could not be tried. The message is safe to show."""
+
+
+class KeyStore:
+    def __init__(self, auth, master: str = ""):
+        self.auth = auth
+        self._fernet, self.why = None, ""   # why: what keeps the panel from saving keys, in words for the page
+        if master:
+            try:
+                from cryptography.fernet import Fernet
+                self._fernet = Fernet(master.strip().encode())
+            except ImportError:
+                self.why = "החבילה cryptography לא מותקנת בשרת."
+            except ValueError:
+                log.error("SECRETS_MASTER_KEY is not a valid Fernet key: keys set in the panel are off")
+                self.why = "SECRETS_MASTER_KEY בשרת אינו מפתח Fernet תקין."
+        else:
+            self.why = "חסר SECRETS_MASTER_KEY בסודות השרת, ולכן אי אפשר לשמור מפתחות מהפאנל."
+        if not self.why and not getattr(auth, "secret", ""):
+            self.why = "חסר SUPABASE_SECRET_KEY בשרת, ולכן אי אפשר לשמור מפתחות מהפאנל."
+        self.missing = False   # the table is not there yet (CREATE_APP_SECRETS)
+        self._rows: dict[str, dict] = {}   # name -> {"value", "last4", "updated_by", "updated_at"}
+        self._lock = threading.Lock()
+
+    @property
+    def writable(self) -> bool:
+        return not self.why and not self.missing
+
+    def _seal(self, name: str, value: str) -> str:
+        # the name goes inside the ciphertext, so one key's row copied into another's does not decrypt as it
+        return self._fernet.encrypt(f"{name}\n{value}".encode()).decode()
+
+    def _open(self, name: str, token: str) -> str | None:
+        from cryptography.fernet import InvalidToken
+        try:
+            got, _, value = self._fernet.decrypt(token.encode()).decode().partition("\n")
+        except (InvalidToken, ValueError):
+            return None
+        return value if got == name else None
+
+    def load(self) -> None:
+        """Reads the stored keys. A failure is logged and leaves the environment's keys in use."""
+        if self.why or not hasattr(self.auth, "secret_rows"):
+            return
+        try:
+            rows = self.auth.secret_rows()
+        except AuthUnavailable as e:
+            log.warning("stored API keys not read, the environment's are used: %s", e)
+            return
+        if rows is None:
+            self.missing = True
+            return
+        found = {}
+        for r in rows:
+            value = self._open(r["name"], r.get("ciphertext") or "") if r.get("name") in NAMES else None
+            if value is None:
+                log.warning("stored key %s does not decrypt with this SECRETS_MASTER_KEY: the environment's is used", r.get("name"))
+                continue
+            found[r["name"]] = {"value": value, "last4": r.get("last4") or "", "updated_by": r.get("updated_by") or "",
+                                "updated_at": r.get("updated_at")}
+        with self._lock:
+            self._rows = found
+
+    @staticmethod
+    def _env(name: str) -> str:
+        return next((v for v in (os.environ.get(n, "").strip() for n in FALLBACK[name]) if v), "")
+
+    def get(self, name: str) -> str:
+        """The key in use: the panel's, else the environment's, else empty."""
+        with self._lock:
+            row = self._rows.get(name)
+        return row["value"] if row else self._env(name)
+
+    def status(self) -> list[dict]:
+        """What the panel shows of each key: never the key itself."""
+        out = []
+        for name, label in NAMES.items():
+            with self._lock:
+                row = self._rows.get(name)
+            env = self._env(name)
+            item = {"name": name, "label": label, "source": "db" if row else "env" if env else "none",
+                    "last4": "" if name in PUBLIC else row["last4"] if row else env[-4:] if len(env) >= 12 else "",
+                    "updated_by": row["updated_by"] if row else "", "updated_at": row["updated_at"] if row else None}
+            if name in PUBLIC:
+                item.update(value=row["value"] if row else env, choices=[{"id": i, "label": l} for i, l in MODEL_CHOICES])
+            out.append(item)
+        return out
+
+    def set(self, name: str, value: str, by: str) -> None:
+        """Encrypts and keeps a key that check() accepted."""
+        row = {"name": name, "ciphertext": self._seal(name, value), "last4": value[-4:], "updated_by": by}
+        self.auth.save_secret(row)
+        with self._lock:
+            self._rows[name] = {"value": value, "last4": row["last4"], "updated_by": by, "updated_at": None}
+
+    def clear(self, name: str) -> None:
+        """Forgets the panel's key; the environment's (if any) is used again."""
+        self.auth.delete_secret(name)
+        with self._lock:
+            self._rows.pop(name, None)
+
+
+def check(name: str, value: str, anthropic_key: str = "") -> None:
+    """Tries the key with its provider, with a call that costs nothing; a tutor model, by asking Anthropic for it with
+    `anthropic_key` (the key in use). Raises KeyRefused."""
+    if name == "TUTOR_MODEL":
+        if not MODEL_ID.match(value):
+            raise KeyRefused("מזהה מודל נראה כך: claude-haiku-5-5.")
+        if not anthropic_key:
+            raise KeyRefused("אין מפתח Anthropic, ולכן אי אפשר לבדוק את המודל. שמרו קודם מפתח.")
+        import anthropic
+        try:
+            anthropic.Anthropic(api_key=anthropic_key, timeout=TIMEOUT, max_retries=0).models.retrieve(value)
+        except anthropic.NotFoundError:
+            raise KeyRefused(f"Anthropic לא מכיר את המודל {value}.") from None
+        except (anthropic.AuthenticationError, anthropic.PermissionDeniedError):
+            raise KeyRefused("מפתח Anthropic שבשימוש נדחה, ולכן אי אפשר לבדוק את המודל.") from None
+        except anthropic.APIStatusError as e:
+            raise KeyRefused(f"לא ניתן לבדוק את המודל מול Anthropic כרגע ({e.status_code}). נסו שוב.") from None
+        except anthropic.APIConnectionError:
+            raise KeyRefused("אין חיבור ל-Anthropic כרגע. נסו שוב.") from None
+        return
+    if name == "SAWTAK_API_KEY":
+        req = urllib.request.Request("https://api.sawtakarabi.ai/v1/voices", headers={
+            "Authorization": f"Bearer {value}", "User-Agent": "ihki/1.0"})
+        try:
+            with urllib.request.urlopen(req, timeout=TIMEOUT):
+                return
+        except urllib.error.HTTPError as e:
+            if e.code == 403:   # a valid key restricted to `tts` may not list voices; speech is all it is used for
+                return
+            if e.code == 401:
+                raise KeyRefused("Sawtak דחה את המפתח.") from None
+            raise KeyRefused(f"לא ניתן לבדוק את המפתח מול Sawtak כרגע ({e.code}). נסו שוב.") from None
+        except OSError:
+            raise KeyRefused("אין חיבור ל-Sawtak כרגע. נסו שוב.") from None
+    import anthropic
+    try:
+        anthropic.Anthropic(api_key=value, timeout=TIMEOUT, max_retries=0).models.list(limit=1)
+    except (anthropic.AuthenticationError, anthropic.PermissionDeniedError):
+        raise KeyRefused("Anthropic דחה את המפתח.") from None
+    except anthropic.APIStatusError as e:
+        raise KeyRefused(f"לא ניתן לבדוק את המפתח מול Anthropic כרגע ({e.status_code}). נסו שוב.") from None
+    except anthropic.APIConnectionError:
+        raise KeyRefused("אין חיבור ל-Anthropic כרגע. נסו שוב.") from None
+
+
+def load_keys(auth) -> KeyStore:
+    keys = KeyStore(auth, os.environ.get("SECRETS_MASTER_KEY", ""))
+    keys.load()
+    return keys

app/main.py

@@ -7,6 +7,7 @@ Env:  MODEL_ID  (default facebook/wav2vec2-xlsr-53-espeak-cv-ft, or a path to a
       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)
       ANTHROPIC_API_KEY, TUTOR_MODEL  (the permission-controlled AI tutor game יאללה נדבר, see app/tutor.py)
+      SECRETS_MASTER_KEY  (lets a developer replace the two API keys from the panel, see app/keystore.py)
 A local .env file is loaded if present; real environment variables win over it.
 """
 from __future__ import annotations
@@ -32,6 +33,8 @@ from fastapi.staticfiles import StaticFiles
 from .arabic_diacritics import point_arabic
 from . import lab
 from .auth import AuthUnavailable, ClassConflict, SupabaseAuth, load_auth
+from .keystore import (CREATE_APP_SECRETS, MAX_LEN as MAX_KEY_LEN, MIGRATE_APP_SECRETS, NAMES as KEY_NAMES, KeyRefused,
+                       check as check_key, load_keys)
 from .phrases import CATEGORIES, GAMES, LESSONS, LEVELS, PHRASES, public_phrases
 from .prompt_tts import ENGINES, PromptTTSUnavailable, hebrew_mp3
 from .reference import References
@@ -41,7 +44,7 @@ from .speech_evaluation import SpeechEvaluationService
 from .texts import read_line, text_phrases
 from .tts import LINE_VOICES, RAEF_VOICE_ID, VOICES, SawtakTTS, TTSUnavailable, load_tts
 from .tutor import (BY_ID, DAILY_LIMIT, MAX_TEXT, MAX_TURNS, SCENARIOS, Tutor, TutorLimit,
-                    TutorUnavailable, load_tutor)
+                    DEFAULT_MODEL as DEFAULT_TUTOR_MODEL, TutorUnavailable, load_tutor, tutor_client)
 from .verb_game import VerbExerciseGenerator
 
 logging.basicConfig(level=logging.INFO)
@@ -384,11 +387,12 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
     @asynccontextmanager
     async def lifespan(app: FastAPI):
         app.state.scorer = scorer or load_scorer(MODEL_ID)
-        app.state.tts = tts or load_tts()
-        app.state.tutor = tutor or load_tutor()
+        app.state.auth = auth or load_auth()
+        app.state.keys = load_keys(app.state.auth)   # the API keys a developer set in the panel, else the environment's
+        app.state.tts = tts or load_tts(app.state.keys.get("SAWTAK_API_KEY"))
+        app.state.tutor = tutor or load_tutor(app.state.keys.get("ANTHROPIC_API_KEY"), app.state.keys.get("TUTOR_MODEL"))
         # the playback voices double as the native baseline of the scores (see reference.py)
         app.state.refs = References(app.state.scorer, app.state.tts, list(VOICES.values())) if app.state.tts else None
-        app.state.auth = auth or load_auth()
         if app.state.auth and hasattr(app.state.auth, "calibrations"):
             try:
                 rows = app.state.auth.calibrations("applied")
@@ -1973,6 +1977,91 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
             app.state.refs.invalidate()
         return {"ok": True, "removed": removed}
 
+    def keys_only(user: dict | None = Depends(signed_in)) -> SupabaseAuth:
+        """Only developers ("*"): a key decides where the bills go. Unlike require(), an open deployment (no sign-in)
+        is refused too."""
+        permissions = set((user or {}).get("permissions", ()))
+        if app.state.auth is None or ("*" not in permissions and "keys.manage" not in permissions):
+            raise HTTPException(403, "missing permission: keys.manage")
+        return app.state.auth
+
+    def keys_status(response: Response) -> dict:
+        response.headers["Cache-Control"] = "no-store"
+        keys = app.state.keys
+        return {"keys": keys.status(), "writable": keys.writable, "why": keys.why,
+                "setup": CREATE_APP_SECRETS if keys.missing else ""}
+
+    def use_key(name: str) -> None:
+        """Puts the key now in force to work, without a restart. The voice cache, the scores' native baseline and the
+        tutor's open conversations stay."""
+        value = app.state.keys.get(name)
+        if name == "TUTOR_MODEL":   # open conversations go on with the new model from their next sentence
+            if app.state.tutor is not None:
+                app.state.tutor.model = value or DEFAULT_TUTOR_MODEL
+        elif name == "SAWTAK_API_KEY":
+            if app.state.tts is not None and value:
+                app.state.tts.api_key = value
+            else:
+                app.state.tts = load_tts(value)
+                app.state.refs = References(app.state.scorer, app.state.tts, list(VOICES.values())) if app.state.tts else None
+        elif app.state.tutor is not None and value:
+            app.state.tutor.client = tutor_client(value)
+        else:
+            app.state.tutor = load_tutor(value, app.state.keys.get("TUTOR_MODEL"))
+
+    def key_name(name: str) -> str:
+        if name not in KEY_NAMES:
+            raise HTTPException(404, "unknown key")
+        return name
+
+    @app.get("/api/admin/keys")
+    def api_keys(response: Response, _a: SupabaseAuth = Depends(keys_only)):
+        """Which API keys are set and where from (the panel, the server's environment, or none); never the keys."""
+        return keys_status(response)
+
+    @app.put("/api/admin/keys/{name}")
+    def set_api_key(name: str, response: Response, body: dict = Body(...), _a: SupabaseAuth = Depends(keys_only),
+                    user: dict | None = Depends(signed_in)):
+        """Tries a new key with its provider, then keeps it encrypted and puts it to work. The key is never logged."""
+        name, value = key_name(name), body.get("value")
+        if not isinstance(value, str) or not value.strip() or len(value.strip()) > MAX_KEY_LEN or any(c.isspace() for c in value.strip()):
+            raise HTTPException(400, "a key is one word of up to 300 characters")
+        if not app.state.keys.writable:
+            raise HTTPException(503, app.state.keys.why or f"the table app_secrets is missing; run: {CREATE_APP_SECRETS}")
+        value = value.strip()
+        try:
+            check_key(name, value, app.state.keys.get("ANTHROPIC_API_KEY"))
+        except KeyRefused as e:
+            raise HTTPException(400, str(e))
+        try:
+            app.state.keys.set(name, value, (user or {}).get("email", ""))
+        except AuthUnavailable as e:
+            if any(mark in str(e).lower() for mark in ("check constraint", "23514")):   # a table made before TUTOR_MODEL
+                raise HTTPException(409, f"הטבלה app_secrets צריכה עדכון; הריצו ב-Supabase: {MIGRATE_APP_SECRETS}")
+            raise HTTPException(503, f"Supabase לא זמין: {e}")
+        use_key(name)
+        log.info("API key %s replaced by %s", name, (user or {}).get("email", "?"))
+        if app.state.auth:
+            app.state.auth.log_event("permission", user, f"מפתח API: {name}", {"key": name, "action": "set"})
+        return keys_status(response)
+
+    @app.delete("/api/admin/keys/{name}")
+    def clear_api_key(name: str, response: Response, _a: SupabaseAuth = Depends(keys_only),
+                      user: dict | None = Depends(signed_in)):
+        """Forgets the panel's key: the server's environment key (if any) is used again."""
+        name = key_name(name)
+        if not app.state.keys.writable:
+            raise HTTPException(503, app.state.keys.why or "the table app_secrets is missing")
+        try:
+            app.state.keys.clear(name)
+        except AuthUnavailable as e:
+            raise HTTPException(503, f"Supabase לא זמין: {e}")
+        use_key(name)
+        log.info("API key %s cleared by %s", name, (user or {}).get("email", "?"))
+        if app.state.auth:
+            app.state.auth.log_event("permission", user, f"מפתח API: {name}", {"key": name, "action": "clear"})
+        return keys_status(response)
+
     @app.get("/api/prompt-audio/{phrase_id}", dependencies=[Depends(require("practice.use"))])
     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."""
@@ -2023,7 +2112,8 @@ def create_app(scorer: Scorer | None = None, tts: SawtakTTS | None = None,
                 "version": build_version()})
             game_ids = {g["id"] for g in GAMES}
             tasks.add_task(app.state.auth.log_event, "game" if phrase["cat"] in game_ids else "exercise", user,
-                           phrase.get("he", ""), {"cat": phrase["cat"]})
+                           phrase.get("he", ""), {"cat": phrase["cat"], "score": round(result["score"]),
+                                                   "flags": len(issues), "unrelated": bool(result.get("unrelated"))})
         return result
 
     @app.post("/api/flags")

app/rules.py

@@ -14,6 +14,7 @@ with ʁ matches a model that heard ɣ. check_detectable() tells which rules a mo
 from __future__ import annotations
 
 import re
+import math
 from dataclasses import dataclass, field
 from functools import lru_cache
 from pathlib import Path
@@ -224,8 +225,13 @@ def elided_article(toks, i: int, ar_words: list[str]) -> bool:
 
 # A glottal stop that is simply not there is how natives say it too (انا, اهلا; ق between vowels): #1, #2.
 # A glottal stop replaced by another consonant still counts, unless the class accepts it (ق said as k).
+# At utterance onset, though, one weak competitor frame is commonly a breath or microphone transient. Treat that
+# as an omission regardless of the phone the multilingual model names; two frames (~40 ms) remain a substitution.
 def _glottal_dropped(toks, i, sc, heard, ar_words):
-    return sc.deleted and toks[i].sound in ("ʔ", "Q")
+    if toks[i].sound not in ("ʔ", "Q"):
+        return False
+    transient_onset = i == 0 and sc.peak < math.log(0.05) and sc.comp_frames < 2
+    return sc.deleted or transient_onset
 
 
 def _article_vowel_elided(toks, i, sc, heard, ar_words):     # #3

app/tts.py

@@ -125,8 +125,9 @@ class SawtakTTS:
             return data, voice
 
 
-def load_tts() -> SawtakTTS | None:
-    key = os.environ.get("SAWTAK_API_KEY", "").strip()
+def load_tts(key: str | None = None) -> SawtakTTS | None:
+    """`key`: the one the panel set (see keystore.py); None reads the environment's."""
+    key = (os.environ.get("SAWTAK_API_KEY", "") if key is None else key).strip()
     if not key:
         log.info("SAWTAK_API_KEY not set: playback uses the device voice")
         return None

app/tutor.py

@@ -18,6 +18,7 @@ this process's memory while it runs (a restart ends it) and is kept, turn by tur
 Env:  ANTHROPIC_API_KEY (or CLAUDE_API_KEY)  required; without it the game is not offered
       Access is granted per account in the management panel; an open service remains open.
       TUTOR_MODEL  optional: the Claude model the tutor runs on (default DEFAULT_MODEL), e.g. claude-sonnet-5-5
+                   (request_options() fits the request to it: Haiku 5.5/4.5, Sonnet 5.5, Opus 5.5 and Fable 5.1 all run)
 """
 from __future__ import annotations
 
@@ -324,10 +325,40 @@ class Chat:
                 "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())}
 
 
-def thinking_for(model: str) -> dict:
-    """No thinking for a chat answer: Haiku turns it off with "disabled", Sonnet 5.5 (which refuses that) with
-    "between_tools"."""
-    return {"type": "between_tools"} if model.startswith("claude-sonnet-5-5") else {"type": "disabled"}
+# models that take a `role: "system"` message in the middle of `messages` (the others answer 400)
+SYSTEM_MESSAGES = ("claude-opus-5", "claude-opus-4-8", "claude-fable-5", "claude-mythos-5", "claude-sonnet-5-5", "claude-haiku-5-5")
+
+
+def thinking_for(model: str) -> dict | None:
+    """As little thinking as each model allows for a chat answer. Sonnet 5.5 refuses "disabled" and turns thinking off
+    with "between_tools"; Opus 5.5 and Fable 5.x cannot turn it off at all (None: the parameter is left out, so it is
+    adaptive, and effort "low" keeps it short); the others take "disabled". Only the answer's text goes back into the
+    history, never a thinking block, so the history stays append-only and nothing is checked against it."""
+    if model.startswith("claude-sonnet-5-5"):
+        return {"type": "between_tools"}
+    if model.startswith(("claude-opus-5-5", "claude-fable-5", "claude-mythos-5")):
+        return None
+    return {"type": "disabled"}
+
+
+def request_options(model: str) -> dict:
+    """The arguments of a chat answer that differ by model: thinking (see thinking_for), effort (Haiku 4.5 has none),
+    and room for a thinking model to think before it answers."""
+    thinking = thinking_for(model)
+    config = {"format": {"type": "json_schema", "schema": REPLY_SCHEMA}}
+    if not model.startswith("claude-haiku-4-5"):
+        config["effort"] = "low"
+    return {"max_tokens": 4000 if thinking else 8000, "output_config": config, **({"thinking": thinking} if thinking else {})}
+
+
+def last_turn(model: str, messages: list[dict], note: str) -> list[dict]:
+    """Tells the model this is the last sentence: as a system message where the model takes one, else after the
+    student's sentence in the same user turn."""
+    if model.startswith(SYSTEM_MESSAGES):
+        return messages + [{"role": "system", "content": note}]
+    *before, student = messages
+    return before + [{"role": "user", "content": [{"type": "text", "text": student["content"]},
+                                                  {"type": "text", "text": f"(Instruction: {note})"}]}]
 
 
 class Tutor:
@@ -404,8 +435,8 @@ class Tutor:
         last = chat.turns + 1 >= MAX_TURNS
         messages = chat.messages + [{"role": "user", "content": text}]
         if last:
-            messages.append({"role": "system", "content": "This is the student's last sentence. Answer it and say "
-                             "goodbye warmly, and write the summary."})
+            messages = last_turn(self.model, messages, "This is the student's last sentence. Answer it and say "
+                                 "goodbye warmly, and write the summary.")
         data = self._answer(chat, messages)
         chat.turns += 1
         chat.done = last
@@ -424,6 +455,7 @@ class Tutor:
     def _answer(self, chat: Chat, messages: list[dict]) -> dict:
         """Asks the model and keeps the exchange in the conversation's history (only once it has answered)."""
         data, usage = self._ask(chat.system, messages)
+        chat.model = self.model   # the panel may have changed it since the conversation began
         chat.messages = messages + [{"role": "assistant", "content": json.dumps(data, ensure_ascii=False)}]
         chat.seen = time.monotonic()
         chat.input_tokens += usage[0]
@@ -434,10 +466,8 @@ class Tutor:
         import anthropic
         try:
             res = self.client.messages.create(
-                model=self.model, max_tokens=4000, system=system, messages=messages,
-                thinking=thinking_for(self.model),
-                output_config={"effort": "low", "format": {"type": "json_schema", "schema": REPLY_SCHEMA}},
-                cache_control={"type": "ephemeral"},
+                model=self.model, system=system, messages=messages, cache_control={"type": "ephemeral"},
+                **request_options(self.model),
             )
         except anthropic.RateLimitError as e:
             log.warning("tutor rate limited: %s", e)
@@ -476,8 +506,16 @@ class Tutor:
             self._started.clear()
 
 
-def load_tutor() -> Tutor | None:
-    key = (os.environ.get("ANTHROPIC_API_KEY", "") or os.environ.get("CLAUDE_API_KEY", "")).strip()
+def tutor_client(key: str):
+    import anthropic
+    return anthropic.Anthropic(api_key=key, timeout=30.0, max_retries=2)
+
+
+def load_tutor(key: str | None = None, model: str | None = None) -> Tutor | None:
+    """`key`, `model`: the ones the panel set (see keystore.py); None reads the environment's."""
+    if key is None:
+        key = os.environ.get("ANTHROPIC_API_KEY", "") or os.environ.get("CLAUDE_API_KEY", "")
+    key = key.strip()
     if not key:
         log.info("no ANTHROPIC_API_KEY: the tutor game (יאללה נדבר) is off")
         return None
@@ -486,9 +524,9 @@ def load_tutor() -> Tutor | None:
     except ImportError:
         log.warning("ANTHROPIC_API_KEY is set but the anthropic package is not installed: the tutor game is off")
         return None
-    model = os.environ.get("TUTOR_MODEL", "").strip() or DEFAULT_MODEL
+    model = (os.environ.get("TUTOR_MODEL", "") if model is None else model).strip() or DEFAULT_MODEL
     log.info("the tutor game (יאללה נדבר) runs on %s", model)
-    return Tutor(anthropic.Anthropic(api_key=key, timeout=30.0, max_retries=2), model)
+    return Tutor(tutor_client(key), model)
 
 
 def tutor_open() -> bool:

app/workbook.py

@@ -4115,8 +4115,14 @@ def workbook_phrases() -> list[dict]:
                 who = said = m[1]
                 he, sentence = he[m.end():], SPEAKER.sub("", sentence)
             words = [_word(t) for t in sentence.split()]
+            variants = _variants(words)
+            # These vocabulary prompts teach two synonymous words. Saying both remains valid, but unlike
+            # conjugation and singular/dual pairs, either synonym on its own is also a complete answer.
+            if "(שתי מילים)" in he:
+                singles = [(a.rstrip("".join(PUNCT)), tr.rstrip("".join(PUNCT.values())), ipas) for a, tr, ipas in words]
+                variants += [variant for word in singles for variant in _variants([word]) if variant not in variants]
             phrase = dict(cat=f"l{lesson_id(*key)}-{tid}", he=he, tr=" ".join(t for _, t, _ in words),
-                          variants=_variants(words), read=kind == "read", **extra)
+                          variants=variants, read=kind == "read", **extra)
             say = _voiced(he_say[0] if he_say else he)
             if say != he:
                 phrase["he_say"] = say

requirements.txt

@@ -8,6 +8,7 @@ huggingface_hub>=0.23
 # torch: CPU build installed separately in the Dockerfile (see README for local installs)
 python-dotenv>=1.0
 anthropic>=1.0  # the AI tutor game בחכי ערבי (app/tutor.py)
+cryptography>=42  # the API keys set in the panel are kept encrypted (app/keystore.py)
 edge-tts>=7.0
 gTTS>=2.5
 tzdata>=2024.1  # time zones for zoneinfo: the slim image may not carry the system ones

static/index.html

@@ -752,7 +752,14 @@ body.manage #manage{width:100%;max-width:none}
 .activity-head select{font:inherit;padding:7px 10px;border:1px solid var(--line);border-radius:9px;background:var(--surface);color:var(--ink)}
 .activity-stats{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}.activity-stat{padding:10px;border:1px solid var(--line);border-radius:10px;background:var(--bg)}.activity-stat b{display:block;font:400 28px/1 var(--f-display);font-variant-numeric:tabular-nums}.activity-stat small{color:var(--muted);font-size:12px}
 .activity-chart{width:100%;height:190px;overflow:visible}.activity-chart .grid{stroke:var(--line);stroke-width:1}.activity-chart .bar{fill:var(--olive);opacity:.82}.activity-chart .bar:hover{opacity:1}.activity-chart text{fill:var(--muted);font:11px var(--f-body)}
-.system-feed{display:flex;flex-direction:column;gap:0}.system-event{display:grid;grid-template-columns:auto 1fr auto;gap:10px;align-items:center;padding:10px 0;border-bottom:1px solid var(--line)}.system-event:last-child{border-bottom:0}.system-event i{display:grid;place-items:center;width:34px;height:34px;border-radius:50%;background:var(--olive-soft);font-style:normal}.system-event b,.system-event small{display:block}.system-event small,.system-event time{color:var(--muted);font-size:12px}.system-event time{direction:ltr;white-space:nowrap}
+.system-activity summary{cursor:pointer}.system-activity summary h2{display:inline;margin:0}.system-activity details[open]>summary{margin-bottom:8px}
+.system-hard{margin:2px 0 4px;padding:10px;border-radius:10px;background:var(--bg)}.system-hard h3{margin:0 0 6px;font:700 15px/1.3 var(--f-body)}.system-hard-row{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:10px;padding:6px 0;border-bottom:1px solid var(--line)}.system-hard-row:last-child{border-bottom:0}.system-hard-row span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.system-hard-row small{color:var(--muted);white-space:nowrap}.system-feed{display:flex;flex-direction:column;gap:14px}.system-topic{border-top:1px solid var(--line);padding-top:10px}.system-topic:first-child{border-top:0;padding-top:0}.system-topic h3{margin:0 0 3px;font:700 15px/1.3 var(--f-body)}.system-topic h3 small{color:var(--muted);font-weight:600}.system-event{display:grid;grid-template-columns:auto 1fr auto;gap:10px;align-items:center;padding:8px 0;border-bottom:1px solid var(--line)}.system-event:last-child{border-bottom:0}.system-event i{display:grid;place-items:center;width:34px;height:34px;border-radius:50%;background:var(--olive-soft);font-style:normal}.system-event b,.system-event small{display:block}.system-event small,.system-event time{color:var(--muted);font-size:12px}.system-event time{direction:ltr;white-space:nowrap}
+/* the API keys card (developers only): a row per key, where it comes from and a field for a new one; a key is never shown */
+.key-row{display:flex;flex-direction:column;gap:8px;padding:10px 0;border-bottom:1px solid var(--line)}.key-row:last-child{border-bottom:0}.key-row b,.key-row small{display:block}.key-row small{color:var(--muted);font-size:12px}
+.key-guide summary{cursor:pointer;color:var(--olive);font-size:14px;font-weight:600}.key-guide ol{margin:8px 0 4px;padding-inline-start:22px;display:flex;flex-direction:column;gap:5px;font-size:14px;line-height:1.5}.key-guide a{color:var(--olive);font-weight:600}.key-cost{margin-top:10px;padding:10px;border-radius:10px;background:var(--bg);font-size:14px;line-height:1.5}.key-cost p{margin:4px 0 8px}.key-cost ul{margin:6px 0 0;padding-inline-start:20px;display:flex;flex-direction:column;gap:4px;color:var(--muted);font-size:13px}
+.key-cost-table{overflow-x:auto}.key-cost table{border-collapse:collapse;width:100%;font-size:13px}.key-cost th,.key-cost td{padding:5px 8px;border-bottom:1px solid var(--line);text-align:start;white-space:nowrap}.key-cost th{color:var(--muted);font-weight:600}.key-cost td[dir=ltr]{font-variant-numeric:tabular-nums}
+.key-guide .note{margin:4px 0 0;color:var(--muted);font-size:13px}
+.key-row form{display:flex;flex-wrap:wrap;gap:8px;align-items:center}.key-row select{flex:1 1 220px;min-width:0;font:inherit;padding:7px 10px;border:1px solid var(--line);border-radius:9px;background:var(--surface);color:var(--ink)}.key-row input[hidden]{display:none}.key-row input{flex:1 1 220px;min-width:0;font:inherit;padding:7px 10px;border:1px solid var(--line);border-radius:9px;background:var(--surface);color:var(--ink)}
 @media(max-width:560px){.activity-stats{grid-template-columns:1fr}.activity-chart{height:160px}}
 /* the content part: a level's name, then a card per lesson with its topics and videos, a row each, and the form that adds a video */
 #mContent{display:flex;flex-direction:column;gap:12px}
@@ -4413,6 +4420,7 @@ function drawScoringRules(box){
 function drawFlags(){
   const box=$("mFlags"); box.innerHTML=""; for(const url of flagAudioUrls) URL.revokeObjectURL(url); flagAudioUrls=[];
   drawActivity(box);
+  drawApiKeys(box);
   drawSystemActivity(box);
   drawTtsCacheControls(box);
   if(!flagsLoaded){ box.append(mark("card","בחרו בניטור כדי לטעון את הנתונים.")); return; }
@@ -4515,14 +4523,41 @@ function drawFlags(){
     confirm.onclick=()=>save("confirmed"); reject.onclick=()=>save("rejected"); actions.append(category,diagnose,confirm,reject,msg); card.append(note,actions); box.append(card);
   }
 }
+let systemActivityOpen=false;   // the recent activity starts closed; a redraw keeps it as the teacher left it
 function drawSystemActivity(box){
-  const card=mark("card",""), title=mark("","פעילות אחרונה במערכת","h2"); card.append(title); box.append(card);
+  const outer=mark("card system-activity",""), card=document.createElement("details"), summary=document.createElement("summary");
+  summary.append(mark("","פעילות אחרונה במערכת","h2")); card.open=systemActivityOpen; card.ontoggle=()=>{ systemActivityOpen=card.open; };
+  card.append(summary); outer.append(card); box.append(outer);
   if(systemActivityError){ card.append(mark("note","לא ניתן לטעון פעילות אחרונה: "+systemActivityError,"p")); return; }
   if(!SYSTEM_ACTIVITY){ card.append(mark("note","טוען פעילות…","p")); return; }
   if(SYSTEM_ACTIVITY.setup){ const code=mark("",SYSTEM_ACTIVITY.setup,"code"); code.dir="ltr"; card.append(mark("setup","כדי להתחיל לשמור פעילות, יש ליצור את הטבלה system_events ב־Supabase:","p"),code); return; }
   const events=SYSTEM_ACTIVITY.events||[], labels={exercise:["🎙️","הכנת תרגילים"],game:["🎮","משחקים"],permission:["🔐","שינוי הרשאות"],content:["➕","הוספת תכנים"]}, feed=mark("system-feed","");
   if(!events.length){ card.append(mark("note","עדיין לא נרשמה פעילות.","p")); return; }
-  for(const event of events){ const [icon,kind]=labels[event.kind]||["•","פעילות"], row=mark("system-event",""), text=document.createElement("div"), time=document.createElement("time"), when=new Date(event.created_at); text.append(mark("",kind,"b"),mark("",[event.actor_email,event.label].filter(Boolean).join(" · ")||"פעילות במערכת","small")); time.dateTime=event.created_at; time.textContent=when.toLocaleString("he-IL",{day:"numeric",month:"numeric",hour:"2-digit",minute:"2-digit",timeZone:"Asia/Jerusalem"}); row.append(mark("",icon,"i"),text,time); feed.append(row); }
+  const difficult=new Map;
+  for(const event of events){
+    const details=event.details||{}, score=+details.score;
+    if(event.kind!=="exercise"||!event.label||!Number.isFinite(score)||details.unrelated) continue;
+    const key=`${details.cat||""}\n${event.label}`, row=difficult.get(key)||{label:event.label,scores:[],flags:0,students:new Set};
+    row.scores.push(score); row.flags+=Number.isFinite(+details.flags)?+details.flags:0; if(event.actor_email) row.students.add(event.actor_email); difficult.set(key,row);
+  }
+  const hardest=[...difficult.values()].map(x=>({...x,average:Math.round(x.scores.reduce((a,b)=>a+b,0)/x.scores.length)})).sort((a,b)=>a.average-b.average||b.scores.length-a.scores.length).slice(0,5);
+  if(hardest.length){
+    const hard=mark("system-hard",""), heading=mark("","התרגילים המאתגרים ביותר","h3"); hard.append(heading);
+    for(const row of hardest){ const line=mark("system-hard-row",""), attempts=row.scores.length, students=row.students.size; line.append(mark("",row.label,"span"),mark("",`ממוצע ${row.average} · ${attempts} ניסיונות · ${students} תלמידים · ${row.flags} דגלונים`,"small")); hard.append(line); }
+    card.append(hard);
+  }
+  const groups=new Map;
+  for(const event of events){
+    const details=event.details||{}, topic=ALL_CATS.find(c=>c.id===details.cat)||GAMES.find(g=>g.id===details.cat), fallback=(labels[event.kind]||["","פעילות"])[1], key=details.cat?`topic:${details.cat}`:`kind:${event.kind}`;
+    if(!groups.has(key)) groups.set(key,{name:(topic&&topic.name)||fallback,events:[],flags:0});
+    const group=groups.get(key); group.events.push(event); group.flags+=Number.isFinite(+details.flags)?+details.flags:0;
+  }
+  for(const group of groups.values()){
+    const section=mark("system-topic",""), heading=mark("",group.name,"h3");
+    heading.append(" ",mark("",`(${group.events.length} רשומות · ${group.flags} דגלונים)`,"small")); section.append(heading);
+    for(const event of group.events){ const [icon,kind]=labels[event.kind]||["•","פעילות"], row=mark("system-event",""), text=document.createElement("div"), time=document.createElement("time"), when=new Date(event.created_at); text.append(mark("",kind,"b"),mark("",[event.actor_email,event.label].filter(Boolean).join(" · ")||"פעילות במערכת","small")); time.dateTime=event.created_at; time.textContent=when.toLocaleString("he-IL",{day:"numeric",month:"numeric",hour:"2-digit",minute:"2-digit",timeZone:"Asia/Jerusalem"}); row.append(mark("",icon,"i"),text,time); section.append(row); }
+    feed.append(section);
+  }
   card.append(feed);
 }
 function drawTtsCacheControls(box){
@@ -4542,6 +4577,119 @@ function drawTtsCacheControls(box){
   };
   row.append(button,msg); card.append(title,text,row); box.append(card);
 }
+// how to get each key, step by step: a step is its parts, text or [text, link]
+const KEY_GUIDES={
+  SAWTAK_API_KEY:[
+    ["היכנסו ל־",["sawtakarabi.ai/dashboard/api-keys","https://sawtakarabi.ai/dashboard/api-keys"]," והתחברו (או הירשמו, אם עדיין אין חשבון)."],
+    ["לחצו על Create key, תנו למפתח שם שתזהו (למשל ihki) וצרו אותו."],
+    ["העתיקו את המפתח מיד: הוא מוצג פעם אחת בלבד. אם הוא אבד, צרו מפתח חדש."],
+    ["ודאו שיש יתרה בחשבון ב־",["Billing","https://sawtakarabi.ai/dashboard/billing"],". בלי יתרה ההשמעה נכשלת והדף עובר לקול של המכשיר."],
+    ["הדביקו את המפתח כאן ולחצו שמירה. מפתח שנוצר בדשבורד מתאים כמו שהוא; מפתח מוגבל צריך לפחות את ההרשאה tts."],
+    ["אחרי שהמפתח החדש עובד, מחקו את הישן בדשבורד של Sawtak."]],
+  ANTHROPIC_API_KEY:[
+    ["היכנסו ל־",["platform.claude.com","https://platform.claude.com/"]," (ה־Console של Anthropic, לשעבר console.anthropic.com) והתחברו או הירשמו."],
+    ["טענו קרדיט ב־",["Billing","https://platform.claude.com/settings/billing"],". ה־API מחויב בנפרד ממנוי Claude.ai, כך שמנוי לבדו לא מספיק."],
+    ["עברו ל־",["API keys","https://platform.claude.com/settings/keys"],", לחצו Create key, תנו שם (למשל ihki) ובחרו workspace (ברירת המחדל מתאימה)."],
+    ["העתיקו את המפתח מיד (הוא מתחיל ב־sk-ant-): הוא מוצג פעם אחת בלבד."],
+    ["מומלץ: קבעו תקרת הוצאה חודשית ב־",["Limits","https://platform.claude.com/settings/limits"],", כדי שתקלה או שימוש חריג לא יעלו יותר ממה שתכננתם."],
+    ["הדביקו את המפתח כאן ולחצו שמירה. אחרי שהוא עובד, מחקו את המפתח הישן ב־Console."]],
+  TUTOR_MODEL:[
+    ["בחרו מודל מהרשימה. Haiku 5.5 הוא ברירת המחדל והזול ביותר; השוואת העלויות נמצאת בהערכת העלות של מפתח Anthropic למעלה."],
+    ["למודל שלא ברשימה בחרו \"אחר\" והקלידו את המזהה שלו (למשל claude-sonnet-5-5). המזהים מופיעים ב־",["רשימת המודלים של Anthropic","https://platform.claude.com/docs/en/models/overview"],"."],
+    ["השמירה בודקת מול Anthropic שהמודל קיים ושהמפתח שבשימוש יכול להשתמש בו. היא לא עולה כסף."],
+    ["המודל החדש נכנס לשימוש מיד, גם בשיחות פתוחות, מהמשפט הבא של התלמיד."],
+    ["הבקשה מותאמת לכל אחד מהמודלים שברשימה. מודל אחר שתקלידו אולי לא יקבל אותה; אם השיחות נכשלות, חזרו לאחד מהרשימה."]]};
+// what each key costs, estimated 2026-10-18 for 100 students × 5 chats a day × 10 turns (the README has how it was worked out)
+const KEY_COSTS={
+  SAWTAK_API_KEY:{intro:"Sawtak מחייב לפי תווים של טקסט מוקרא: בחשבון הזה כ־$0.05 לכל 1,000 תווים ($50 למיליון).",
+    head:["השמעת המורה (בלי מטמון)","תווים","עלות"],
+    rows:[["לשיחה (11 הודעות)","~990","~$0.05"],["ליום (500 שיחות)","~495,000","~$25"],["לחודש (15,000 שיחות)","~14.9 מיליון","~$745"],["לתלמיד לחודש","~149,000","~$7.45"]],
+    notes:["אם גם ההודעות של המורה (יאללה נדבר) יושמעו ב־Sawtak (הקוד עדיין לא עושה את זה), כל הודעה עולה מחדש: הטקסט תמיד חדש, ולכן אין מטמון. הודעה היא משפט או שניים, כ־90 תווים עם ניקוד. בהודעות של 60 עד 120 תווים: בין כ־$500 לכ־$1,000 לחודש, יותר מהמודל עצמו ב־Haiku 5.5.",
+           "כל משפט נוצר פעם אחת ונשמר במטמון. כל 3,546 המשפטים הם כ־180 אלף תווים, כלומר כ־$9 בסך הכול, פעם אחת.",
+           "מספר התלמידים לא משנה את העלות: 100 תלמידים עולים כמו תלמיד אחד, כי מהשני והלאה המשפט מגיע מהמטמון.",
+           "מה כן עולה: ריסטארט של ה־Space בלי אחסון קבוע, או מחיקת מטמון ההקלטות, מוחקים את המטמון, וההקלטות נוצרות מחדש (עד כ־$9 בכל פעם). מומלץ אחסון קבוע ו־TTS_CACHE_DIR=/data/ihki-tts."]},
+  ANTHROPIC_API_KEY:{intro:"לפי 100 תלמידים × 5 שיחות ביום × 10 תורות: 500 שיחות ביום, 15,000 בחודש. העלות גדלה ��ם השיעורים, כי ההנחיות למורה כוללות את אוצר המילים שנלמד עד אז.",
+    head:["מודל","לשיחה","ליום","לחודש (שיעור 1 / אמצע / אחרון)"],
+    rows:[["Haiku 5.5 (ברירת המחדל)","$0.0075","$3.73","$71 / $112 / $133"],["Haiku 4.5","$0.075","$37","$712 / $1,120 / $1,332"],
+          ["Sonnet 5.5","$0.15","$75","$1,424 / $2,241 / $2,663"],["Opus 5.5 *","$0.26","$130","$2,644 / $3,914 / $4,572"],["Fable 5.1 *","$0.61","$303","$6,354 / $9,077 / $10,486"]],
+    notes:["העמודות לשיחה וליום הן לאמצע הקורס. ההערכה היא תקרה: כל תלמיד מנצל את 5 השיחות, כל יום, את כל 10 התורות.",
+           "המחירים כוללים את מטמון ההנחיות (prompt cache). בלעדיו הקלט היה עולה פי 3 עד 3.5.",
+           "* ב־Opus 5.5 וב־Fable 5.1 אי אפשר לכבות את החשיבה, ולכן המורה משאיר אותה במאמץ נמוך. טוקני החשיבה מחויבים כפלט ולא נספרו בטבלה, כך שבפועל העלות שלהם קצת גבוהה יותר.",
+           "את המודל בוחרים ב־TUTOR_MODEL בסודות השרת."]}};
+function keyCost(name){
+  const c=KEY_COSTS[name]; if(!c) return null;
+  const box=mark("key-cost",""); box.append(mark("","הערכת עלות","b"),mark("",c.intro,"p"));
+  if(c.rows){
+    const wrap=mark("key-cost-table",""), table=document.createElement("table"), tr=document.createElement("tr");
+    for(const h of c.head) tr.append(mark("",h,"th")); table.append(tr);
+    for(const r of c.rows){ const row=document.createElement("tr"); r.forEach((v,i)=>{ const td=mark("",v,"td"); if(i) td.dir="ltr"; row.append(td); }); table.append(row); }
+    wrap.append(table); box.append(wrap);
+  }
+  const ul=document.createElement("ul"); for(const n of c.notes) ul.append(mark("",n,"li")); box.append(ul);
+  return box;
+}
+function keyGuide(name){
+  const steps=KEY_GUIDES[name]; if(!steps) return null;
+  const details=document.createElement("details"), summary=document.createElement("summary"), list=document.createElement("ol");
+  details.className="key-guide"; summary.textContent="איך משיגים את המפתח?";
+  for(const step of steps){
+    const li=document.createElement("li");
+    for(const part of step){
+      if(typeof part==="string"){ li.append(part); continue; }
+      const a=document.createElement("a"); a.textContent=part[0]; a.href=part[1]; a.target="_blank"; a.rel="noopener noreferrer"; a.dir="ltr"; li.append(a);
+    }
+    list.append(li);
+  }
+  const cost=keyCost(name);
+  details.append(summary,list,...(cost?[cost]:[]),mark("note","אל תשלחו מפתח בצ׳אט, במייל או בווטסאפ: הדביקו אותו רק כאן.","p"));
+  return details;
+}
+let API_KEYS=null;   // what /api/admin/keys answered: whether each key is set and where from, never the key
+function drawApiKeys(box){
+  if(!can("keys.manage")) return;
+  const card=mark("card",""), list=document.createElement("div");
+  card.append(mark("","מפתחות API ומודל","h2"),mark("","מפתח חדש נבדק מול הספק, נשמר מוצפן בשרת ונכנס לשימוש מיד. אחרי השמירה הוא לא מוצג שוב, רק ארבעת התווים האחרונים שלו. גם המודל של המורה נקבע כאן.","p"),list); box.append(card);
+  const show=data=>{
+    API_KEYS=data; list.innerHTML="";
+    if(data.setup){ const code=mark("",data.setup,"code"); code.dir="ltr"; list.append(mark("note","כדי לשמור מפתחות מהפאנל, יש ליצור את הטבלה app_secrets ב־Supabase:","p"),code); }
+    else if(!data.writable&&data.why) list.append(mark("note",data.why,"p"));
+    const sources={db:"נשמר בפאנל",env:"מוגדר בשרת",none:"לא מוגדר"};
+    for(const k of data.keys||[]){
+      const row=mark("key-row",""), info=document.createElement("div"), when=k.updated_at?new Date(k.updated_at).toLocaleDateString("he-IL",{timeZone:"Asia/Jerusalem"}):"";
+      const choice=!!k.choices, inUse=choice&&(k.value?`בשימוש: ${k.value}`:"ברירת המחדל של הקוד (claude-haiku-5-5)");
+      info.append(mark("",k.label,"b"),mark("",[choice&&k.source==="none"?"":sources[k.source]||k.source,inUse,k.last4&&`מסתיים ב־${k.last4}`,k.updated_by&&`על ידי ${k.updated_by}`,when].filter(Boolean).join(" · "),"small"));
+      row.append(info); const guide=keyGuide(k.name); if(guide) row.append(guide); list.append(row);
+      if(!data.writable) continue;
+      const form=document.createElement("form"), input=document.createElement("input"), save=mark("btn primary","שמירה","button"), msg=mark("msg","");
+      input.type=choice?"text":"password"; input.autocomplete="off"; input.spellcheck=false; input.dir="ltr"; input.maxLength=300; input.placeholder=choice?"claude-…":"מפתח חדש"; input.setAttribute("aria-label",choice?"מזהה מודל אחר":`מפתח חדש: ${k.label}`); save.type="submit";
+      let select=null;
+      if(choice){   // the list, and "other" for an id typed in the field
+        select=document.createElement("select"); select.setAttribute("aria-label",k.label);
+        for(const c of [...k.choices,{id:"",label:"אחר (הקלדה חופשית)…"}]){ const o=document.createElement("option"); o.value=c.id; o.textContent=c.id?`${c.label} · ${c.id}`:c.label; select.append(o); }
+        const listed=k.choices.some(c=>c.id===(k.value||k.choices[0].id));
+        select.value=listed?(k.value||k.choices[0].id):""; if(!listed) input.value=k.value;
+        const other=()=>{ input.hidden=select.value!==""; if(!input.hidden) input.focus(); };
+        select.onchange=other; input.hidden=select.value!=="";
+      }
+      const send=async(method,body,busy)=>{
+        for(const b of form.querySelectorAll("button")) b.disabled=true; msg.textContent=busy;
+        try{
+          const res=await api(`/api/admin/keys/${k.name}`,{method,...(body?{headers:{"Content-Type":"application/json"},body:JSON.stringify(body)}:{})}), d=await res.json().catch(()=>({}));
+          if(!res.ok) throw new Error(d.detail||res.status);
+          input.value=""; show(d);
+        }catch(err){ msg.textContent="נכשל: "+err.message; for(const b of form.querySelectorAll("button")) b.disabled=false; }
+      };
+      form.onsubmit=e=>{ e.preventDefault(); const value=select&&select.value?select.value:input.value.trim(); if(value) send("PUT",{value},choice?"בודק את המודל מול Anthropic…":"בודק את המפתח מול הספק…"); };
+      if(select) form.append(select); form.append(input,save);
+      if(k.source==="db"){ const back=mark("btn",choice?"חזרה לברירת המחדל של השרת":"חזרה למפתח השרת","button"); back.type="button"; back.onclick=()=>{ if(confirm(choice?"לחזור למודל שמוגדר בשרת (או לברירת המחדל)?":"למחוק את המפתח שנשמר בפאנל ולחזור למפתח שמוגדר בשרת (אם יש)?")) send("DELETE",null,"מוחק…"); }; form.append(back); }
+      form.append(msg); row.append(form);
+    }
+  };
+  if(API_KEYS){ show(API_KEYS); return; }
+  list.append(mark("note","טוען…","p"));
+  api("/api/admin/keys").then(async res=>{ const d=await res.json().catch(()=>({})); if(!res.ok) throw new Error(d.detail||res.status); show(d); })
+    .catch(err=>{ list.innerHTML=""; list.append(mark("note","לא ניתן לטעון את המפתחות: "+err.message,"p")); });
+}
 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");

tests/test_keystore.py

@@ -0,0 +1,185 @@
+"""The API keys a developer replaces from the panel (app/keystore.py): kept encrypted, never shown back, put to work at once."""
+import pytest
+from cryptography.fernet import Fernet
+from fastapi.testclient import TestClient
+from test_lab import FakeAuth
+from test_scoring import emissions, scorer_for
+
+import app.main
+from app.keystore import KeyStore
+from app.main import create_app
+from app.tts import SawtakTTS
+from app.tutor import Tutor
+
+MASTER = Fernet.generate_key().decode()
+NEW = "sk-ant-new-key-0123456789wxyz"
+
+
+class KeyAuth(FakeAuth):
+    secret = "sb_secret_x"
+
+    def __init__(self, table=True):
+        super().__init__()
+        self.rows, self.table, self.events = {}, table, []
+
+    def secret_rows(self):
+        return list(self.rows.values()) if self.table else None
+
+    def save_secret(self, row):
+        self.rows[row["name"]] = {**row, "updated_at": "2026-10-18T10:00:00+00:00"}
+
+    def delete_secret(self, name):
+        self.rows.pop(name, None)
+
+    def log_event(self, kind, user, label="", details=None):
+        self.events.append((kind, label, details))
+
+
+class AdminAuth(KeyAuth):
+    developers = frozenset()   # t@b.c is a teacher (the panel), not a developer
+
+
+def bearer(token):
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.fixture
+def keys_env(monkeypatch):
+    monkeypatch.setenv("SECRETS_MASTER_KEY", MASTER)
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-from-the-environment-1111")
+    monkeypatch.setattr(app.main, "check_key", lambda name, value, anthropic_key="": None)
+
+
+def client(auth, tmp_path, tutor=None):
+    return TestClient(create_app(scorer_for(emissions(["ħ", "aː", "l"])), SawtakTTS("old-sawtak-key", cache_dir=tmp_path),
+                                 auth=auth, tutor=tutor or Tutor(object())))
+
+
+def test_a_key_is_kept_encrypted_and_never_shown_back(keys_env, tmp_path):
+    auth = KeyAuth()
+    with client(auth, tmp_path) as c:
+        before = c.get("/api/admin/keys", headers=bearer("teacher")).json()
+        assert {k["name"]: k["source"] for k in before["keys"]}["ANTHROPIC_API_KEY"] == "env"
+        assert "1111" in repr(before) and "from-the-environment" not in repr(before)   # its last four only
+        res = c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": f"  {NEW} "}, headers=bearer("teacher"))
+        assert res.status_code == 200, res.text
+        assert NEW not in res.text and res.headers["cache-control"] == "no-store"
+        row = next(k for k in res.json()["keys"] if k["name"] == "ANTHROPIC_API_KEY")
+        assert (row["source"], row["last4"], row["updated_by"]) == ("db", "wxyz", "T@b.c")
+        stored = auth.rows["ANTHROPIC_API_KEY"]
+        assert NEW not in stored["ciphertext"]
+        assert c.app.state.tutor.client.api_key == NEW   # in use without a restart
+        assert auth.events and NEW not in repr(auth.events)
+    # a restart reads it back from the table
+    assert KeyStore(auth, MASTER).get("ANTHROPIC_API_KEY") == "sk-ant-from-the-environment-1111"   # not loaded yet
+    keys = KeyStore(auth, MASTER)
+    keys.load()
+    assert keys.get("ANTHROPIC_API_KEY") == NEW
+
+
+def test_the_sawtak_key_is_swapped_in_place(keys_env, tmp_path):
+    with client(KeyAuth(), tmp_path) as c:
+        tts = c.app.state.tts
+        assert c.put("/api/admin/keys/SAWTAK_API_KEY", json={"value": "sawtak-new-9876"},
+                     headers=bearer("teacher")).status_code == 200
+        assert c.app.state.tts is tts and tts.api_key == "sawtak-new-9876"
+
+
+def test_clearing_goes_back_to_the_environment_key(keys_env, tmp_path):
+    auth = KeyAuth()
+    with client(auth, tmp_path) as c:
+        c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": NEW}, headers=bearer("teacher"))
+        res = c.delete("/api/admin/keys/ANTHROPIC_API_KEY", headers=bearer("teacher"))
+        assert res.status_code == 200 and "ANTHROPIC_API_KEY" not in auth.rows
+        assert c.app.state.tutor.client.api_key == "sk-ant-from-the-environment-1111"
+
+
+def test_only_developers_reach_the_keys(keys_env, tmp_path, monkeypatch):
+    with client(KeyAuth(), tmp_path) as c:   # a student
+        assert c.get("/api/admin/keys", headers=bearer("student")).status_code == 403
+        assert c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": NEW}, headers=bearer("student")).status_code == 403
+    with client(AdminAuth(), tmp_path) as c:   # the management panel is not enough
+        assert c.get("/api/admin/keys", headers=bearer("teacher")).status_code == 403
+    monkeypatch.setattr(app.main, "load_auth", lambda: None)   # an open deployment, without sign-in
+    with TestClient(create_app(scorer_for(emissions(["ħ"])), SawtakTTS("k", cache_dir=tmp_path),
+                               tutor=Tutor(object()))) as c:
+        assert c.get("/api/admin/keys").status_code == 403
+
+
+def test_only_the_two_keys_are_settable(keys_env, tmp_path):
+    with client(KeyAuth(), tmp_path) as c:
+        for name in ("SUPABASE_SECRET_KEY", "SECRETS_MASTER_KEY"):
+            assert c.put(f"/api/admin/keys/{name}", json={"value": NEW}, headers=bearer("teacher")).status_code == 404
+        assert c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": "two words"}, headers=bearer("teacher")).status_code == 400
+
+
+def test_a_refused_key_is_not_kept(keys_env, tmp_path, monkeypatch):
+    from app.keystore import KeyRefused
+
+    def refuse(name, value, anthropic_key=""):
+        raise KeyRefused("Anthropic דחה את המפתח.")
+    monkeypatch.setattr(app.main, "check_key", refuse)
+    auth = KeyAuth()
+    with client(auth, tmp_path) as c:
+        res = c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": NEW}, headers=bearer("teacher"))
+        assert res.status_code == 400 and NEW not in res.text and not auth.rows
+
+
+def test_without_the_master_key_or_the_table_nothing_is_saved(keys_env, tmp_path, monkeypatch):
+    with client(KeyAuth(table=False), tmp_path) as c:
+        data = c.get("/api/admin/keys", headers=bearer("teacher")).json()
+        assert not data["writable"] and "app_secrets" in data["setup"]
+        assert c.put("/api/admin/keys/ANTHROPIC_API_KEY", json={"value": NEW}, headers=bearer("teacher")).status_code == 503
+    monkeypatch.delenv("SECRETS_MASTER_KEY")
+    with client(KeyAuth(), tmp_path) as c:
+        data = c.get("/api/admin/keys", headers=bearer("teacher")).json()
+        assert not data["writable"] and "SECRETS_MASTER_KEY" in data["why"]
+
+
+def test_a_row_does_not_decrypt_under_another_name_or_master(tmp_path):
+    auth = KeyAuth()
+    keys = KeyStore(auth, MASTER)
+    keys.set("ANTHROPIC_API_KEY", NEW, "t@b.c")
+    auth.rows["SAWTAK_API_KEY"] = {**auth.rows["ANTHROPIC_API_KEY"], "name": "SAWTAK_API_KEY"}   # copied across
+    again = KeyStore(auth, MASTER)
+    again.load()
+    assert again.get("ANTHROPIC_API_KEY") == NEW and again.get("SAWTAK_API_KEY") != NEW
+    other = KeyStore(auth, Fernet.generate_key().decode())
+    other.load()
+    assert other.get("ANTHROPIC_API_KEY") != NEW
+
+
+def test_the_tutor_model_is_shown_and_switched_at_once(keys_env, tmp_path, monkeypatch):
+    seen = []
+    monkeypatch.setattr(app.main, "check_key", lambda name, value, anthropic_key="": seen.append((name, anthropic_key)))
+    monkeypatch.delenv("TUTOR_MODEL", raising=False)
+    auth = KeyAuth()
+    with client(auth, tmp_path, tutor=Tutor(object(), "claude-haiku-5-5")) as c:
+        row = next(k for k in c.get("/api/admin/keys", headers=bearer("teacher")).json()["keys"] if k["name"] == "TUTOR_MODEL")
+        assert row["source"] == "none" and row["value"] == "" and row["choices"][0]["id"] == "claude-haiku-5-5"
+        res = c.put("/api/admin/keys/TUTOR_MODEL", json={"value": "claude-sonnet-5-5"}, headers=bearer("teacher"))
+        assert res.status_code == 200, res.text
+        row = next(k for k in res.json()["keys"] if k["name"] == "TUTOR_MODEL")
+        assert (row["source"], row["value"], row["last4"]) == ("db", "claude-sonnet-5-5", "")   # no secret: shown in full
+        assert c.app.state.tutor.model == "claude-sonnet-5-5"
+        assert seen == [("TUTOR_MODEL", "sk-ant-from-the-environment-1111")]   # checked with the key in use
+        c.delete("/api/admin/keys/TUTOR_MODEL", headers=bearer("teacher"))
+        assert c.app.state.tutor.model == "claude-haiku-5-5"   # back to the code's default
+
+
+def test_a_model_id_must_look_like_one():
+    from app.keystore import KeyRefused, check
+    for bad in ("gpt-5", "claude haiku", "claude-"):
+        with pytest.raises(KeyRefused):
+            check("TUTOR_MODEL", bad, "sk-ant-x")
+
+
+def test_an_old_table_asks_for_its_migration(keys_env, tmp_path):
+    from app.auth import AuthUnavailable
+
+    class OldTable(KeyAuth):
+        def save_secret(self, row):
+            raise AuthUnavailable('supabase answered 400: {"code":"23514","message":"violates check constraint"}')
+    with client(OldTable(), tmp_path) as c:
+        res = c.put("/api/admin/keys/TUTOR_MODEL", json={"value": "claude-sonnet-5-5"}, headers=bearer("teacher"))
+        assert res.status_code == 409 and "app_secrets_name_check" in res.json()["detail"]

tests/test_scoring.py

@@ -722,6 +722,10 @@ def test_workbook_lesson_2():
     assert all("seq" not in p for p in pub if p["cat"] == "l2-poss")   # drilled in random order, like the conjugations
     by = {(p["cat"], p["he"]): p for p in PHRASES}
     assert by["l2-dual", "שולחן, שני שולחנות"]["tr"] == "טַאוְלֵה, טַאוְלְתֵין"   # singular and dual said together
+    grandpa = by["l2-family", "סבא (שתי מילים)"]
+    grandma = by["l2-family", "סבתא (שתי מילים)"]
+    assert grandpa["variants"] == [("سيد، جدّ", "s iː d | dʒ i d d"), ("سيد", "s iː d"), ("جدّ", "dʒ i d d")]
+    assert grandma["variants"] == [("ستّ، جدّة", "s i t t | dʒ i d d e"), ("ستّ", "s i t t"), ("جدّة", "dʒ i d d e")]
     # כינויי הקניין: the stem changes before a consonant suffix, and שלך is pointed for the prompt voice
     assert by["l2-poss", "השולחן שלי"]["tr"] == "טַאוְלְת-י" and by["l2-poss", "השולחן שלנו"]["tr"] == "טַאוְלֵת-נַא"
     you = by["l2-poss", "הבת שלך (לאישה)"]

tests/test_tutor.py

@@ -193,3 +193,27 @@ def test_a_refused_answer_does_not_count():
         model.stop = "end_turn"
         assert c.post("/api/tutor/turn", json={"id": chat["id"], "text": "مرحبا"}, headers=bearer("teacher")).json()["turn"] == 1
         assert c.post("/api/tutor/turn", json={"id": chat["id"], "text": ""}, headers=bearer("teacher")).status_code == 400
+
+
+@pytest.mark.parametrize("model, thinking, effort", [
+    ("claude-haiku-5-5", {"type": "disabled"}, "low"),
+    ("claude-sonnet-5-5", {"type": "between_tools"}, "low"),
+    ("claude-opus-5-5", None, "low"),          # cannot turn thinking off: left adaptive, kept short by effort
+    ("claude-fable-5-1", None, "low"),
+    ("claude-haiku-4-5", {"type": "disabled"}, None),   # no effort parameter
+])
+def test_each_model_gets_only_what_it_accepts(model, thinking, effort):
+    from app.tutor import request_options
+    opts = request_options(model)
+    assert opts.get("thinking") == thinking and opts["output_config"].get("effort") == effort
+    assert opts["output_config"]["format"]["type"] == "json_schema"
+    assert opts["max_tokens"] == (8000 if thinking is None else 4000)   # room to think before the answer
+
+
+def test_the_last_turn_note_fits_the_model():
+    from app.tutor import last_turn
+    history = [{"role": "user", "content": "פתיחה"}, {"role": "assistant", "content": "{}"}, {"role": "user", "content": "مرحبا"}]
+    assert last_turn("claude-haiku-5-5", history, "last")[-1] == {"role": "system", "content": "last"}
+    folded = last_turn("claude-haiku-4-5", history, "last")   # no system messages there: one user turn, two blocks
+    assert len(folded) == 3 and folded[-1]["role"] == "user" and folded[-1]["content"][0]["text"] == "مرحبا"
+    assert "last" in folded[-1]["content"][1]["text"]