Drop family framing from anki-progress; add anki-deck-*.py tools

anki-progress.sh and its embedded app.py assumed a family/kids use case
(dashboard title, ntfy topic default, Authelia warning text, comments)
that was never actually stated — nothing in this repo should assume who
the accounts belong to. Retitled to plain "Anki Progress" throughout,
default ntfy topic changed from family-anki to anki-progress, and every
"family member" reference reworded to "account".

Also adds tools/anki-deck-math.py, tools/anki-deck-periodic.py, and
tools/anki-deck-visual.py — the Anki deck-generation scripts developed
earlier in this session, now committed as standalone, self-documented
tools (same tools/*.{sh,py} convention as tools/dedupe-finder.py) rather
than living only in chat. Each script's own header docstring carries the
full one-time setup (venv, genanki + piper-tts, downloading a voice) and
usage — anki-deck-periodic.py and anki-deck-visual.py point back to
anki-deck-math.py's copy rather than repeating it three times. Content is
generic (multiplication/division/addition/subtraction/fractions/decimals,
the periodic table, shapes/clocks/coin-counting) — nothing here assumes
who's using it or why.

Re-verified after the rename: the embedded app.py still passes its full
logic test suite once written out by the installer, and all three
tools/anki-deck-*.py scripts still build correct decks under
--dry-run-tts after their docstrings were rewritten.

Adds a README.md section pointing at the three scripts, and updates the
anki-progress Services table entry to drop "family" from its wording.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014DyceEVVeQ33EeS6C1PDv5

README.md

@@ -186,7 +186,7 @@ a ready-to-copy Caddy config snippet to `~/docker/caddy-snippets/`.
 |-------|---------|
 | `base` | `net-tools`, `ncdu`, `git`, `curl`, `wget`, `htop`, `tree`, `zip`/`unzip`, `ca-certificates`, `gnupg`, `jq`, `rsync`; `glow` (terminal markdown reader, Charm apt repo); Docker CE + Compose plugin; `openssh-server` with GitHub/Launchpad SSH key import, optional password-auth lockdown, and SSH Host aliases; optional NetBird overlay network |
 | `homelab` | `caddy`, `crowdsec`, `authelia`, `homeassistant`, `asterisk` (own dedicated coturn for TURN/STUN — see `mattermost` below for the other coturn-owning service), `pstn-trunk`, `sms-inbound`, `security-dashboard`, `sunshine`, `vpn-data-mount` (mount existing SMB shares from a NetBird-connected home box — SSH trust bootstrap, then read-only discovery of shares already configured there; never writes to the home box's Samba config; repeatable, pick from any number of a home box's shares in one pass; optional per-share [gocryptfs decrypt layer](#client-side-encryption-for-vpn-data-mount) so the VPS only ever handles ciphertext) |
-| `utilities` | `actualbudget`, `ai-gpu`, `ai-stack`, `anki-progress` (read-only family study-progress dashboard for an `anki-sync-server` instance — reviews/accuracy/streak per account, plus an ntfy notification once a study session has been going for a configurable number of minutes; reads collection files with SQLite's read-only mode so it can't interfere with the live sync server), `anki-sync-server` (self-hosted sync backend for the Anki flashcard app — spaced-repetition scheduling stays in the Anki client, this just syncs collections across devices without AnkiWeb; supports multiple independent accounts per instance), `archivebox`, `beszel` (lightweight server + Docker monitoring — CPU/RAM/disk/network, auto-discovers running containers via the Docker socket; complements Gatus rather than replacing it — Gatus is a black-box HTTP check, Beszel is white-box host/process monitoring), `beszel-agent` (agent-only Beszel install for a remote/homelab box reporting to a hub elsewhere — connects outbound over HTTPS, no VPN/port-forwarding/FQDN needed on that box), `changedetection`, `ddclient`, `filebrowser`, `fmd`, `garage` (self-hosted S3-compatible object storage, single node — MinIO CE's actively-maintained replacement), `garage-webui` (browser-based bucket/object browser for an existing `garage` install — folders/files view, the same kind of thing Backblaze's own web console gives you), `gatus`, `gitea` (self-hosted Git server — raw local clones plus optional two-way GitHub mirror sync, standalone from the `ai-stack` bundle's own Gitea container), `homebox`, `iopaint`, `joplin`, `koha`, `magicmirror`, `mail-archiver`, `mattermost`, `mealie`, `meshcentral`, `n8n`, `nextcloud`, `ntfy`, `onlyoffice`, `paintplus`, `pihole` (standalone DNS ad/tracker blocking — not wired into any VPN's DNS push), `portainer`, `pressbooks` (self-hosted book platform — WordPress Multisite, drag-and-drop chapter editing, PDF export via PrinceXML/DocRaptor, Authelia-gated), `rustdesk`, `samba` (SMB/CIFS file sharing — shares, dedicated Samba users/passwords, LAN-scoped firewall by default; also offered as an optional nudge from `base`), `stirling-pdf`, `syncthing`, `traccar`, `unifi`, `uptimekuma`, `vaultwarden`, `watchyourlan`, `watchtower`, `wg-easy`, `wordpress` (multi-site, dedicated MariaDB per site — blogs, business sites, e-commerce via WooCommerce) |
+| `utilities` | `actualbudget`, `ai-gpu`, `ai-stack`, `anki-progress` (read-only study-progress dashboard for an `anki-sync-server` instance — reviews/accuracy/streak per account, plus an ntfy notification once a study session has been going for a configurable number of minutes; reads collection files with SQLite's read-only mode so it can't interfere with the live sync server), `anki-sync-server` (self-hosted sync backend for the Anki flashcard app — spaced-repetition scheduling stays in the Anki client, this just syncs collections across devices without AnkiWeb; supports multiple independent accounts per instance), `archivebox`, `beszel` (lightweight server + Docker monitoring — CPU/RAM/disk/network, auto-discovers running containers via the Docker socket; complements Gatus rather than replacing it — Gatus is a black-box HTTP check, Beszel is white-box host/process monitoring), `beszel-agent` (agent-only Beszel install for a remote/homelab box reporting to a hub elsewhere — connects outbound over HTTPS, no VPN/port-forwarding/FQDN needed on that box), `changedetection`, `ddclient`, `filebrowser`, `fmd`, `garage` (self-hosted S3-compatible object storage, single node — MinIO CE's actively-maintained replacement), `garage-webui` (browser-based bucket/object browser for an existing `garage` install — folders/files view, the same kind of thing Backblaze's own web console gives you), `gatus`, `gitea` (self-hosted Git server — raw local clones plus optional two-way GitHub mirror sync, standalone from the `ai-stack` bundle's own Gitea container), `homebox`, `iopaint`, `joplin`, `koha`, `magicmirror`, `mail-archiver`, `mattermost`, `mealie`, `meshcentral`, `n8n`, `nextcloud`, `ntfy`, `onlyoffice`, `paintplus`, `pihole` (standalone DNS ad/tracker blocking — not wired into any VPN's DNS push), `portainer`, `pressbooks` (self-hosted book platform — WordPress Multisite, drag-and-drop chapter editing, PDF export via PrinceXML/DocRaptor, Authelia-gated), `rustdesk`, `samba` (SMB/CIFS file sharing — shares, dedicated Samba users/passwords, LAN-scoped firewall by default; also offered as an optional nudge from `base`), `stirling-pdf`, `syncthing`, `traccar`, `unifi`, `uptimekuma`, `vaultwarden`, `watchyourlan`, `watchtower`, `wg-easy`, `wordpress` (multi-site, dedicated MariaDB per site — blogs, business sites, e-commerce via WooCommerce) |
 | `media` | `arm`, `audiobookshelf`, `calibre-web`, `emby`, `immich`, `jellyfin`, `lyrion` |
 | `cameras` | `frigate`, `frigate-audio`, `frigate-notify`, `sky-cam` |
 | `gaming` | `drum-rhythm-game`, `js99er`, `kyber-launcher`, `kyber-server`, `minecraft`, `wolf`, `wolf-pair` |
@@ -293,6 +293,28 @@ backup
 
 </details>
 
+## Generating Anki decks (tools/anki-deck-*.py)
+
+`anki-sync-server` gives you a self-hosted sync backend, but a fresh
+account has no content — `tools/anki-deck-math.py`,
+`tools/anki-deck-periodic.py`, and `tools/anki-deck-visual.py` generate
+ready-to-import `.apkg` decks (multiplication/division/addition/
+subtraction/fractions/decimals, the periodic table, and shapes/clocks/
+coin-counting) with Anki's built-in type-the-answer input and offline
+neural TTS audio (Piper) on every card. All three are standalone Python
+scripts, unrelated to the `services/*.sh` installer framework — run them
+on any machine with Python, not necessarily the server itself. Full setup
+(a venv, `genanki` + `piper-tts`, downloading a voice) and every deck's
+exact usage is documented in `tools/anki-deck-math.py`'s own header
+docstring; the other two scripts point back to it rather than repeating
+the same instructions three times.
+
+Shapes, clocks, and coin images are drawn programmatically (SVG) rather
+than AI-generated — image generation is a poor fit for content that has
+to be exactly correct (an exact clock time, an exact side count), not
+just plausible-looking; see `tools/anki-deck-visual.py`'s own docstring
+for more on that tradeoff.
+
 ## Layout
 
 ```

services/anki-progress.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# services/anki-progress.sh — Family Anki study-progress dashboard + ntfy
+# services/anki-progress.sh — Anki study-progress dashboard + ntfy
 # "started studying" notifications. Reads an anki-sync-server instance's
 # data directly (read-only) — see services/anki-sync-server.sh, which this
 # service requires.
@@ -208,7 +208,7 @@ CBLOCK
 fi
 # ─────────────────────────────────────────────────────────────────────────────
 
-register_service anki-progress utilities "Family Anki study-progress dashboard + ntfy 'started studying' notifications (reads an anki-sync-server instance's data read-only)" 8099
+register_service anki-progress utilities "Anki study-progress dashboard + ntfy 'started studying' notifications (reads an anki-sync-server instance's data read-only)" 8099
 
 install_anki-progress() {
     require_docker || return 1
@@ -323,7 +323,7 @@ install_anki-progress() {
     else
         prompt_text "  ntfy server URL (e.g. https://ntfy.yourdomain.com, or https://ntfy.sh):" "https://ntfy.sh" NTFY_URL
     fi
-    prompt_text "  ntfy topic to publish 'started studying' notifications to:" "family-anki" NTFY_TOPIC
+    prompt_text "  ntfy topic to publish 'started studying' notifications to:" "anki-progress" NTFY_TOPIC
 
     local SESSION_GAP_MINUTES="" NOTIFY_DELAY_MINUTES=""
     prompt_text "  Minutes of inactivity that counts as a new study session starting:" "30" SESSION_GAP_MINUTES
@@ -356,7 +356,7 @@ networks:
     backup_if_exists app.py
     cat > app.py << 'PYEOF'
 #!/usr/bin/env python3
-"""Family Anki progress dashboard + ntfy "started studying" notifications.
+"""Anki study-progress dashboard + ntfy "started studying" notifications.
 
 Reads every account's collection.anki2 directly (READ-ONLY — never opens for
 write, so it can't corrupt live data the sync server or a client is using)
@@ -387,7 +387,7 @@ import requests
 from flask import Flask, render_template_string
 
 NTFY_URL = os.environ.get("NTFY_URL", "https://ntfy.example.com")
-NTFY_TOPIC = os.environ.get("NTFY_TOPIC", "family-anki")
+NTFY_TOPIC = os.environ.get("NTFY_TOPIC", "anki-progress")
 
 SESSION_GAP_MINUTES = int(os.environ.get("SESSION_GAP_MINUTES", 30))
 NOTIFY_DELAY_MINUTES = int(os.environ.get("NOTIFY_DELAY_MINUTES", 10))
@@ -502,7 +502,7 @@ def detect_current_session_start(revlog_rows, now_ms):
 
 DASHBOARD_TEMPLATE = """
 <!doctype html>
-<title>Family Anki Progress</title>
+<title>Anki Progress</title>
 <meta http-equiv="refresh" content="60">
 <style>
   body { font-family: Arial, sans-serif; background: #f4f6f8; margin: 0; padding: 24px; }
@@ -514,7 +514,7 @@ DASHBOARD_TEMPLATE = """
   .stat b { color: #1c4587; }
   .empty { color: #888; font-style: italic; }
 </style>
-<h1>Family Anki Progress</h1>
+<h1>Anki Progress</h1>
 <div class="grid">
   {% for user, s in stats.items() %}
   <div class="card">
@@ -667,8 +667,8 @@ ENVEOF
     fi
 
     # ── Caddy + Authelia-aware protection ────────────────────────────────────
-    # This dashboard shows every family member's personal study activity —
+    # This dashboard shows every account's personal study activity — same
-    # same "sensitive, protect by default" reasoning as
+    # "sensitive, protect by default" reasoning as
     # services/security-dashboard.sh: auto-use local Authelia if present, no
     # prompt needed; otherwise warn clearly and offer a remote instance,
     # since leaving it open is a real privacy tradeoff, not a neutral default.
@@ -677,9 +677,9 @@ ENVEOF
         EXTRA_BLOCK="    import authelia"
         log_info "Local Authelia detected — protecting with it."
     else
-        log_warning "No local Authelia found. This dashboard shows every family"
+        log_warning "No local Authelia found. This dashboard shows every account's"
-        log_warning "member's personal study activity — recommend protecting it"
+        log_warning "personal study activity — recommend protecting it before"
-        log_warning "before exposing it publicly."
+        log_warning "exposing it publicly."
         local _use_remote=""
         prompt_yn "  Protect with a remote Authelia instance (e.g. on a homelab)? (y/n):" "y" _use_remote
         if [[ "$_use_remote" =~ ^[Yy]$ ]]; then

tools/anki-deck-math.py

@@ -0,0 +1,420 @@
+#!/usr/bin/env python3
+"""tools/anki-deck-math.py — Generate math-fact Anki decks (.apkg) with a
+vertical/stacked problem layout, Anki's built-in type-the-answer input, and
+Piper (offline, local neural TTS) audio on both the question and answer
+side of every card.
+
+Standalone content-generation tool, unrelated to this repo's services/*.sh
+installers — run it on any machine with Python (your desktop, laptop, or
+the same box running services/anki-sync-server.sh), then import the
+resulting .apkg into Anki (File -> Import) or push it into a sync-server
+account with AnkiConnect's importPackage action. See services/anki-sync-server.sh
+and services/anki-progress.sh for the actual self-hosted sync backend and
+progress dashboard this content is meant to be studied through.
+
+Decks:
+    multiplication         1-12, all 144 ordered pairs (a x b), shuffled
+                            (not sequential — see the note near
+                            random.shuffle(pairs) below for why)
+    division                inverse of the multiplication deck (144 facts)
+    addsub --lo L --hi H    addition + subtraction fact family for [L, H]
+                            (subtraction facts derived from the addition
+                            facts, e.g. 7+3=10 also gives 10-7=3 and
+                            10-3=7 — never negative results)
+    fractions               reducing fractions to lowest terms (denominators 2-12)
+    decimals                fraction -> decimal conversion (only denominators
+                            whose decimal expansion terminates: 2,4,5,8,10,20,25)
+
+Setup (one time):
+    python3 -m venv ~/anki-deck-venv
+    source ~/anki-deck-venv/bin/activate
+    pip install genanki piper-tts
+
+    # Download at least one voice (one time per voice you want to try —
+    # download_voices saves into the CURRENT directory by default, so cd
+    # somewhere sensible first, e.g. your home directory):
+    python3 -m piper.download_voices en_US-lessac-medium
+    # Other options: en_US-amy-medium (warm/friendly), en_US-ryan-high
+    # (best-quality US male), en_US-libritts_r-medium (multi-speaker),
+    # en_GB-alba-medium / en_GB-cori-high (British accent). Tiers are
+    # low < medium < high — higher sounds more natural but is bigger/slower.
+
+    # Sanity-check the voice before generating a full deck's worth of clips:
+    echo "three times seven" | python3 -m piper -m en_US-lessac-medium.onnx -f /tmp/test.wav
+    # play /tmp/test.wav and confirm it sounds right first.
+
+Usage (run with the venv activated):
+    python3 anki-deck-math.py --deck multiplication
+    python3 anki-deck-math.py --deck division
+    python3 anki-deck-math.py --deck addsub --lo 3 --hi 7
+    python3 anki-deck-math.py --deck addsub --lo 3 --hi 13
+    python3 anki-deck-math.py --deck addsub --lo 2 --hi 21
+    python3 anki-deck-math.py --deck fractions
+    python3 anki-deck-math.py --deck decimals
+(add --voice en_US-amy-medium etc. to any of the above to use a voice other
+than the default en_US-lessac-medium; --model-path to point at a voice
+file directly if it's not found in any of the usual places checked
+automatically; --dry-run-tts to test the deck-building logic itself
+without Piper or any voice model at all, using silent placeholder audio)
+
+The addsub --hi 21 deck generates ~1600 audio clips and will take noticeably
+longer than the others — consider `nohup python3 anki-deck-math.py --deck
+addsub --lo 2 --hi 21 > addsub.log 2>&1 &` if you don't want to wait on it.
+"""
+import argparse
+import hashlib
+import genanki
+import math
+import os
+import random
+import subprocess
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--deck", required=True,
+                     choices=["multiplication", "division", "addsub", "fractions", "decimals"])
+parser.add_argument("--lo", type=int, default=None, help="addsub only: low end of range")
+parser.add_argument("--hi", type=int, default=None, help="addsub only: high end of range")
+parser.add_argument("--voice", default="en_US-lessac-medium")
+parser.add_argument("--model-path", default=None)
+parser.add_argument("--dry-run-tts", action="store_true",
+                     help="Skip Piper entirely and write silent placeholder audio instead"
+                          " (for testing the deck-building logic without a voice model).")
+args = parser.parse_args()
+
+if args.deck == "addsub":
+    if args.lo is None or args.hi is None:
+        raise SystemExit("--deck addsub requires --lo and --hi, e.g. --lo 3 --hi 7")
+    if args.lo >= args.hi:
+        raise SystemExit("--lo must be less than --hi")
+
+SCRATCH = os.path.dirname(os.path.abspath(__file__))
+
+# ─── Voice resolution (same search order as the multiplication script) ──────
+_CANDIDATES = [
+    args.model_path,
+    f"{args.voice}.onnx",
+    os.path.join(SCRATCH, f"{args.voice}.onnx"),
+    os.path.expanduser(f"~/{args.voice}.onnx"),
+    os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"),
+]
+VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None)
+
+if VOICE_MODEL is None and not args.dry_run_tts:
+    raise SystemExit(
+        f"Voice model for '{args.voice}' not found. Checked:\n"
+        + "\n".join(f"  {p}" for p in _CANDIDATES if p)
+        + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null"
+        + "\nThen pass its exact path with --model-path /the/real/path.onnx"
+        + "\n(or pass --dry-run-tts to test deck-building without any voice at all)"
+    )
+
+
+def piper_tts(text: str, out_path: str) -> None:
+    if args.dry_run_tts:
+        # 44-byte minimal valid WAV header, zero samples — enough for genanki
+        # to accept it as a real media file without needing Piper installed.
+        with open(out_path, "wb") as f:
+            f.write(
+                b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00"
+                b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00"
+            )
+        return
+    subprocess.run(
+        ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path],
+        input=text.encode("utf-8"),
+        check=True,
+        capture_output=True,
+    )
+
+
+# ─── Number -> words ─────────────────────────────────────────────────────────
+ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+        "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+        "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"]
+TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy",
+        "eighty", "ninety"]
+
+
+def num2words(n):
+    if n < 0:
+        return "negative " + num2words(-n)
+    if n < 20:
+        return ONES[n]
+    if n < 100:
+        t, o = divmod(n, 10)
+        return TENS[t] + ("-" + ONES[o] if o else "")
+    h, rem = divmod(n, 100)
+    return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "")
+
+
+_NUM_CHECKS = {0: "zero", 9: "nine", 10: "ten", 13: "thirteen", 20: "twenty",
+               21: "twenty-one", 45: "forty-five", 99: "ninety-nine",
+               100: "one hundred", 110: "one hundred ten",
+               121: "one hundred twenty-one", 144: "one hundred forty-four",
+               441: "four hundred forty-one"}
+for _n, _w in _NUM_CHECKS.items():
+    assert num2words(_n) == _w, f"num2words({_n}) = {num2words(_n)!r}, expected {_w!r}"
+
+# Ordinal words, singular form, denominators 2-21 (covers every deck below).
+# Irregular forms (half, third, fifth, eighth, ninth, twelfth) are real
+# English irregularities, not a suffix rule, so this is a lookup table, not
+# a formula — a formula would get exactly these wrong.
+ORDINAL_SINGULAR = {
+    2: "half", 3: "third", 4: "fourth", 5: "fifth", 6: "sixth",
+    7: "seventh", 8: "eighth", 9: "ninth", 10: "tenth", 11: "eleventh",
+    12: "twelfth", 13: "thirteenth", 14: "fourteenth", 15: "fifteenth",
+    16: "sixteenth", 17: "seventeenth", 18: "eighteenth", 19: "nineteenth",
+    20: "twentieth", 21: "twenty-first", 25: "twenty-fifth", 50: "fiftieth",
+    100: "hundredth",
+}
+
+
+def ordinal_plural(n):
+    s = ORDINAL_SINGULAR[n]
+    return "halves" if s == "half" else s + "s"
+
+
+def fraction_words(num, den):
+    """'three fourths', 'one half', 'seven tenths'."""
+    ord_word = ORDINAL_SINGULAR[den] if num == 1 else ordinal_plural(den)
+    return f"{num2words(num)} {ord_word}"
+
+
+_FRAC_CHECKS = {
+    (1, 2): "one half", (3, 4): "three fourths", (1, 4): "one fourth",
+    (7, 10): "seven tenths", (1, 3): "one third", (2, 3): "two thirds",
+    (5, 8): "five eighths", (1, 8): "one eighth",
+}
+for (_n, _d), _w in _FRAC_CHECKS.items():
+    assert fraction_words(_n, _d) == _w, f"fraction_words({_n},{_d}) = {fraction_words(_n, _d)!r}, expected {_w!r}"
+
+
+def decimal_words(decimal_str):
+    """'0.25' -> 'zero point two five' (each digit spoken individually,
+    avoids any ambiguity between e.g. 'point two five' vs 'twenty-five
+    hundredths')."""
+    whole, frac = decimal_str.split(".")
+    digit_words = " ".join(ONES[int(d)] for d in frac)
+    return f"{num2words(int(whole))} point {digit_words}"
+
+
+assert decimal_words("0.25") == "zero point two five"
+assert decimal_words("0.5") == "zero point five"
+assert decimal_words("0.375") == "zero point three seven five"
+
+
+# ─── Shared genanki model builder ────────────────────────────────────────────
+# Every deck here renders as two stacked lines with a line under them (same
+# visual language as the original multiplication deck): TOP over BOTTOM,
+# with an optional prefix (operator) on the bottom line. Fractions/decimals
+# reuse the exact same layout as numerator-over-denominator.
+def build_model(deck_key):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    model_id = 1_600_000_000 + (voice_hash % 90_000_000)
+    return model_id, genanki.Model(
+        model_id,
+        f"Math Fact ({deck_key}, {args.voice})",
+        fields=[{"name": "Top"}, {"name": "Bottom"}, {"name": "Answer"},
+                {"name": "QSound"}, {"name": "ASound"}],
+        templates=[{
+            "name": "Card",
+            "qfmt": """
+<div class="problem">
+  <div class="line1">{{Top}}</div>
+  <div class="line2">{{Bottom}}</div>
+  <div class="rule"></div>
+</div>
+{{QSound}}
+{{type:Answer}}
+""",
+            "afmt": """
+<div class="problem">
+  <div class="line1">{{Top}}</div>
+  <div class="line2">{{Bottom}}</div>
+  <div class="rule"></div>
+</div>
+<hr id="answer">
+{{type:Answer}}
+{{ASound}}
+""",
+        }],
+        css="""
+.card { font-family: Arial, sans-serif; font-size: 28px; text-align: center; }
+.problem { display: inline-block; text-align: right; margin: 20px auto; }
+.line1, .line2 { font-size: 48px; padding: 2px 10px; }
+.rule { border-top: 3px solid black; margin-top: 4px; width: 100%; }
+""",
+    )
+
+
+def build_deck(deck_key, deck_title):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    deck_id = 2_000_000_000 + (voice_hash % 90_000_000)
+    return genanki.Deck(deck_id, deck_title)
+
+
+def add_note(deck, model, top, bottom, answer, qtext, atext, media_files, tag):
+    qfile = f"q_{tag}.wav"
+    afile = f"a_{tag}.wav"
+    qpath = os.path.join(MEDIA_DIR, qfile)
+    apath = os.path.join(MEDIA_DIR, afile)
+    piper_tts(qtext, qpath)
+    piper_tts(atext, apath)
+    media_files += [qpath, apath]
+    deck.add_note(genanki.Note(
+        model=model,
+        fields=[top, bottom, answer, f"[sound:{qfile}]", f"[sound:{afile}]"],
+    ))
+
+
+# ─── Per-deck generators ─────────────────────────────────────────────────────
+def gen_multiplication():
+    deck_key = "multiplication"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Multiplication Facts (1-12)")
+    media_files = []
+    pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)]
+    random.seed(42)
+    random.shuffle(pairs)
+    for a, b in pairs:
+        ans = a * b
+        add_note(deck, model, str(a), f"&times; {b}", str(ans),
+                  f"{num2words(a)} times {num2words(b)}", num2words(ans),
+                  media_files, f"mul_{a}_{b}")
+    return deck, media_files, len(pairs)
+
+
+def gen_division():
+    deck_key = "division"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Division Facts (inverse of 1-12 times tables)")
+    media_files = []
+    # Same (a, b) pairs as multiplication: product / a = b. This is the
+    # direct inverse of every multiplication card in that deck.
+    pairs = [(a, b) for a in range(1, 13) for b in range(1, 13)]
+    random.seed(43)
+    random.shuffle(pairs)
+    for a, b in pairs:
+        product = a * b
+        add_note(deck, model, str(product), f"&divide; {a}", str(b),
+                  f"{num2words(product)} divided by {num2words(a)}", num2words(b),
+                  media_files, f"div_{a}_{b}")
+    return deck, media_files, len(pairs)
+
+
+def gen_addsub(lo, hi):
+    deck_key = f"addsub_{lo}_{hi}"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, f"Addition & Subtraction Facts ({lo}-{hi})")
+    media_files = []
+
+    add_pairs = [(a, b) for a in range(lo, hi + 1) for b in range(lo, hi + 1)]
+    random.seed(hash((lo, hi)) & 0xFFFFFFFF)
+    random.shuffle(add_pairs)
+
+    sub_facts = []  # (minuend, subtrahend, answer)
+    seen = set()
+    for a, b in add_pairs:
+        c = a + b
+        for minuend, subtrahend, answer in ((c, a, b), (c, b, a)):
+            key = (minuend, subtrahend)
+            if key not in seen:
+                seen.add(key)
+                sub_facts.append((minuend, subtrahend, answer))
+    random.shuffle(sub_facts)
+
+    count = 0
+    for a, b in add_pairs:
+        ans = a + b
+        add_note(deck, model, str(a), f"+ {b}", str(ans),
+                  f"{num2words(a)} plus {num2words(b)}", num2words(ans),
+                  media_files, f"add_{lo}_{hi}_{a}_{b}")
+        count += 1
+    for minuend, subtrahend, answer in sub_facts:
+        add_note(deck, model, str(minuend), f"&minus; {subtrahend}", str(answer),
+                  f"{num2words(minuend)} minus {num2words(subtrahend)}", num2words(answer),
+                  media_files, f"sub_{lo}_{hi}_{minuend}_{subtrahend}")
+        count += 1
+    return deck, media_files, count
+
+
+def gen_fractions():
+    deck_key = "fractions"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Reducing Fractions to Lowest Terms")
+    media_files = []
+
+    facts = []
+    for den in range(2, 13):
+        for num in range(1, den):
+            g = math.gcd(num, den)
+            if g > 1:
+                facts.append((num, den, num // g, den // g))
+    random.seed(44)
+    random.shuffle(facts)
+
+    for num, den, rnum, rden in facts:
+        answer = f"{rnum}/{rden}"
+        add_note(deck, model, str(num), f"&frasl; {den}", answer,
+                  fraction_words(num, den), fraction_words(rnum, rden),
+                  media_files, f"frac_{num}_{den}")
+    return deck, media_files, len(facts)
+
+
+def gen_decimals():
+    deck_key = "decimals"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Fraction to Decimal Conversion")
+    media_files = []
+
+    # Only denominators whose only prime factors are 2 and 5 terminate in a
+    # finite decimal (1/3 = 0.333... never terminates) — restricting to
+    # these avoids ever needing to round/repeat.
+    facts = []
+    for den in (2, 4, 5, 8, 10, 20, 25):
+        for num in range(1, den):
+            if math.gcd(num, den) != 1:
+                continue  # skip non-lowest-terms fractions (already covered by the fractions deck)
+            value = num / den
+            decimal_str = f"{value:.10f}".rstrip("0")
+            if decimal_str.endswith("."):
+                decimal_str += "0"
+            facts.append((num, den, decimal_str))
+    random.seed(45)
+    random.shuffle(facts)
+
+    for num, den, decimal_str in facts:
+        add_note(deck, model, str(num), f"&frasl; {den}", decimal_str,
+                  fraction_words(num, den), decimal_words(decimal_str),
+                  media_files, f"dec_{num}_{den}")
+    return deck, media_files, len(facts)
+
+
+# ─── Dispatch ─────────────────────────────────────────────────────────────────
+if args.deck == "addsub":
+    deck_key = f"addsub_{args.lo}_{args.hi}"
+else:
+    deck_key = args.deck
+
+MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}")
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+GENERATORS = {
+    "multiplication": lambda: gen_multiplication(),
+    "division": lambda: gen_division(),
+    "addsub": lambda: gen_addsub(args.lo, args.hi),
+    "fractions": lambda: gen_fractions(),
+    "decimals": lambda: gen_decimals(),
+}
+
+deck, media_files, count = GENERATORS[args.deck]()
+if count == 0:
+    raise SystemExit(f"No cards generated for --deck {args.deck} — check the range/args.")
+
+package = genanki.Package(deck)
+package.media_files = media_files
+out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg")
+package.write_to_file(out_path)
+
+size_mb = os.path.getsize(out_path) / (1024 * 1024)
+print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)")

tools/anki-deck-periodic.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+"""tools/anki-deck-periodic.py — Generate periodic table Anki decks (.apkg)
+with Anki's built-in type-the-answer input and Piper (offline, local
+neural TTS) audio on both sides. See tools/anki-deck-math.py's docstring
+for one-time setup (venv, genanki + piper-tts, downloading a voice) — same
+steps apply here, this is a standalone, self-contained script otherwise.
+
+Decks:
+    prehs       symbol<->name, elements 1-36 (H through Kr)
+    hs          symbol<->name plus number->symbol, all 118 elements
+    category    element category as multiple choice (A/B/C/D shown as
+                plain text options — not a clickable UI, since that needs
+                a desktop-only Anki add-on and would break on
+                AnkiDroid/AnkiMobile), type the letter — only elements
+                with a confirmed category (excludes 8 very recent
+                superheavy elements whose category is still officially
+                unconfirmed)
+
+Element data: Bowserinator/Periodic-Table-JSON (a widely used, actively
+maintained public dataset), fetched and spot-checked against known facts
+before being embedded below — not typed from memory.
+
+Usage (run with the venv from anki-deck-math.py's docstring activated):
+    python3 anki-deck-periodic.py --deck prehs
+    python3 anki-deck-periodic.py --deck hs
+    python3 anki-deck-periodic.py --deck category
+(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found
+automatically; --dry-run-tts to test the deck-building logic without any
+voice model at all, using silent placeholder audio)
+"""
+import argparse
+import hashlib
+import genanki
+import os
+import random
+import subprocess
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--deck", required=True, choices=["prehs", "hs", "category"])
+parser.add_argument("--voice", default="en_US-lessac-medium")
+parser.add_argument("--model-path", default=None)
+parser.add_argument("--dry-run-tts", action="store_true")
+args = parser.parse_args()
+
+SCRATCH = os.path.dirname(os.path.abspath(__file__))
+
+_CANDIDATES = [
+    args.model_path,
+    f"{args.voice}.onnx",
+    os.path.join(SCRATCH, f"{args.voice}.onnx"),
+    os.path.expanduser(f"~/{args.voice}.onnx"),
+    os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"),
+]
+VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None)
+
+if VOICE_MODEL is None and not args.dry_run_tts:
+    raise SystemExit(
+        f"Voice model for '{args.voice}' not found. Checked:\n"
+        + "\n".join(f"  {p}" for p in _CANDIDATES if p)
+        + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null"
+        + "\nThen pass its exact path with --model-path /the/real/path.onnx"
+        + "\n(or pass --dry-run-tts to test deck-building without any voice at all)"
+    )
+
+
+def piper_tts(text: str, out_path: str) -> None:
+    if args.dry_run_tts:
+        with open(out_path, "wb") as f:
+            f.write(
+                b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00"
+                b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00"
+            )
+        return
+    subprocess.run(
+        ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path],
+        input=text.encode("utf-8"),
+        check=True,
+        capture_output=True,
+    )
+
+
+ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+        "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+        "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"]
+TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy",
+        "eighty", "ninety"]
+
+
+def num2words(n):
+    if n < 20:
+        return ONES[n]
+    if n < 100:
+        t, o = divmod(n, 10)
+        return TENS[t] + ("-" + ONES[o] if o else "")
+    h, rem = divmod(n, 100)
+    return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "")
+
+
+assert num2words(1) == "one"
+assert num2words(26) == "twenty-six"
+assert num2words(118) == "one hundred eighteen"
+
+# ─── Element data: (atomic_number, symbol, name, category-or-None) ─────────
+# category is None for the 8 most recently synthesized superheavy elements
+# whose chemical category is still officially unconfirmed (excluded from
+# the category deck below, still included in prehs/hs symbol/name/number).
+ELEMENTS = [
+    (1, 'H', 'Hydrogen', 'diatomic nonmetal'),
+    (2, 'He', 'Helium', 'noble gas'),
+    (3, 'Li', 'Lithium', 'alkali metal'),
+    (4, 'Be', 'Beryllium', 'alkaline earth metal'),
+    (5, 'B', 'Boron', 'metalloid'),
+    (6, 'C', 'Carbon', 'polyatomic nonmetal'),
+    (7, 'N', 'Nitrogen', 'diatomic nonmetal'),
+    (8, 'O', 'Oxygen', 'diatomic nonmetal'),
+    (9, 'F', 'Fluorine', 'diatomic nonmetal'),
+    (10, 'Ne', 'Neon', 'noble gas'),
+    (11, 'Na', 'Sodium', 'alkali metal'),
+    (12, 'Mg', 'Magnesium', 'alkaline earth metal'),
+    (13, 'Al', 'Aluminium', 'post-transition metal'),
+    (14, 'Si', 'Silicon', 'metalloid'),
+    (15, 'P', 'Phosphorus', 'polyatomic nonmetal'),
+    (16, 'S', 'Sulfur', 'polyatomic nonmetal'),
+    (17, 'Cl', 'Chlorine', 'diatomic nonmetal'),
+    (18, 'Ar', 'Argon', 'noble gas'),
+    (19, 'K', 'Potassium', 'alkali metal'),
+    (20, 'Ca', 'Calcium', 'alkaline earth metal'),
+    (21, 'Sc', 'Scandium', 'transition metal'),
+    (22, 'Ti', 'Titanium', 'transition metal'),
+    (23, 'V', 'Vanadium', 'transition metal'),
+    (24, 'Cr', 'Chromium', 'transition metal'),
+    (25, 'Mn', 'Manganese', 'transition metal'),
+    (26, 'Fe', 'Iron', 'transition metal'),
+    (27, 'Co', 'Cobalt', 'transition metal'),
+    (28, 'Ni', 'Nickel', 'transition metal'),
+    (29, 'Cu', 'Copper', 'transition metal'),
+    (30, 'Zn', 'Zinc', 'transition metal'),
+    (31, 'Ga', 'Gallium', 'post-transition metal'),
+    (32, 'Ge', 'Germanium', 'metalloid'),
+    (33, 'As', 'Arsenic', 'metalloid'),
+    (34, 'Se', 'Selenium', 'polyatomic nonmetal'),
+    (35, 'Br', 'Bromine', 'diatomic nonmetal'),
+    (36, 'Kr', 'Krypton', 'noble gas'),
+    (37, 'Rb', 'Rubidium', 'alkali metal'),
+    (38, 'Sr', 'Strontium', 'alkaline earth metal'),
+    (39, 'Y', 'Yttrium', 'transition metal'),
+    (40, 'Zr', 'Zirconium', 'transition metal'),
+    (41, 'Nb', 'Niobium', 'transition metal'),
+    (42, 'Mo', 'Molybdenum', 'transition metal'),
+    (43, 'Tc', 'Technetium', 'transition metal'),
+    (44, 'Ru', 'Ruthenium', 'transition metal'),
+    (45, 'Rh', 'Rhodium', 'transition metal'),
+    (46, 'Pd', 'Palladium', 'transition metal'),
+    (47, 'Ag', 'Silver', 'transition metal'),
+    (48, 'Cd', 'Cadmium', 'transition metal'),
+    (49, 'In', 'Indium', 'post-transition metal'),
+    (50, 'Sn', 'Tin', 'post-transition metal'),
+    (51, 'Sb', 'Antimony', 'metalloid'),
+    (52, 'Te', 'Tellurium', 'metalloid'),
+    (53, 'I', 'Iodine', 'diatomic nonmetal'),
+    (54, 'Xe', 'Xenon', 'noble gas'),
+    (55, 'Cs', 'Cesium', 'alkali metal'),
+    (56, 'Ba', 'Barium', 'alkaline earth metal'),
+    (57, 'La', 'Lanthanum', 'lanthanide'),
+    (58, 'Ce', 'Cerium', 'lanthanide'),
+    (59, 'Pr', 'Praseodymium', 'lanthanide'),
+    (60, 'Nd', 'Neodymium', 'lanthanide'),
+    (61, 'Pm', 'Promethium', 'lanthanide'),
+    (62, 'Sm', 'Samarium', 'lanthanide'),
+    (63, 'Eu', 'Europium', 'lanthanide'),
+    (64, 'Gd', 'Gadolinium', 'lanthanide'),
+    (65, 'Tb', 'Terbium', 'lanthanide'),
+    (66, 'Dy', 'Dysprosium', 'lanthanide'),
+    (67, 'Ho', 'Holmium', 'lanthanide'),
+    (68, 'Er', 'Erbium', 'lanthanide'),
+    (69, 'Tm', 'Thulium', 'lanthanide'),
+    (70, 'Yb', 'Ytterbium', 'lanthanide'),
+    (71, 'Lu', 'Lutetium', 'lanthanide'),
+    (72, 'Hf', 'Hafnium', 'transition metal'),
+    (73, 'Ta', 'Tantalum', 'transition metal'),
+    (74, 'W', 'Tungsten', 'transition metal'),
+    (75, 'Re', 'Rhenium', 'transition metal'),
+    (76, 'Os', 'Osmium', 'transition metal'),
+    (77, 'Ir', 'Iridium', 'transition metal'),
+    (78, 'Pt', 'Platinum', 'transition metal'),
+    (79, 'Au', 'Gold', 'transition metal'),
+    (80, 'Hg', 'Mercury', 'transition metal'),
+    (81, 'Tl', 'Thallium', 'post-transition metal'),
+    (82, 'Pb', 'Lead', 'post-transition metal'),
+    (83, 'Bi', 'Bismuth', 'post-transition metal'),
+    (84, 'Po', 'Polonium', 'post-transition metal'),
+    (85, 'At', 'Astatine', 'diatomic nonmetal'),
+    (86, 'Rn', 'Radon', 'noble gas'),
+    (87, 'Fr', 'Francium', 'alkali metal'),
+    (88, 'Ra', 'Radium', 'alkaline earth metal'),
+    (89, 'Ac', 'Actinium', 'actinide'),
+    (90, 'Th', 'Thorium', 'actinide'),
+    (91, 'Pa', 'Protactinium', 'actinide'),
+    (92, 'U', 'Uranium', 'actinide'),
+    (93, 'Np', 'Neptunium', 'actinide'),
+    (94, 'Pu', 'Plutonium', 'actinide'),
+    (95, 'Am', 'Americium', 'actinide'),
+    (96, 'Cm', 'Curium', 'actinide'),
+    (97, 'Bk', 'Berkelium', 'actinide'),
+    (98, 'Cf', 'Californium', 'actinide'),
+    (99, 'Es', 'Einsteinium', 'actinide'),
+    (100, 'Fm', 'Fermium', 'actinide'),
+    (101, 'Md', 'Mendelevium', 'actinide'),
+    (102, 'No', 'Nobelium', 'actinide'),
+    (103, 'Lr', 'Lawrencium', 'actinide'),
+    (104, 'Rf', 'Rutherfordium', 'transition metal'),
+    (105, 'Db', 'Dubnium', 'transition metal'),
+    (106, 'Sg', 'Seaborgium', 'transition metal'),
+    (107, 'Bh', 'Bohrium', 'transition metal'),
+    (108, 'Hs', 'Hassium', 'transition metal'),
+    (109, 'Mt', 'Meitnerium', None),
+    (110, 'Ds', 'Darmstadtium', None),
+    (111, 'Rg', 'Roentgenium', None),
+    (112, 'Cn', 'Copernicium', None),
+    (113, 'Nh', 'Nihonium', 'post-transition metal'),
+    (114, 'Fl', 'Flerovium', 'post-transition metal'),
+    (115, 'Mc', 'Moscovium', None),
+    (116, 'Lv', 'Livermorium', None),
+    (117, 'Ts', 'Tennessine', None),
+    (118, 'Og', 'Oganesson', None),
+]
+assert len(ELEMENTS) == 118
+assert [e[0] for e in ELEMENTS] == list(range(1, 119))
+assert ELEMENTS[0] == (1, 'H', 'Hydrogen', 'diatomic nonmetal')
+assert ELEMENTS[25] == (26, 'Fe', 'Iron', 'transition metal')
+assert ELEMENTS[-1] == (118, 'Og', 'Oganesson', None)
+
+ALL_CATEGORIES = sorted({e[3] for e in ELEMENTS if e[3] is not None})
+
+
+def build_model(deck_key):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    model_id = 1_700_000_000 + (voice_hash % 90_000_000)
+    return model_id, genanki.Model(
+        model_id,
+        f"Periodic Table ({deck_key}, {args.voice})",
+        fields=[{"name": "Prompt"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}],
+        templates=[{
+            "name": "Card",
+            "qfmt": """
+<div class="prompt">{{Prompt}}</div>
+{{QSound}}
+{{type:Answer}}
+""",
+            "afmt": """
+<div class="prompt">{{Prompt}}</div>
+<hr id="answer">
+{{type:Answer}}
+{{ASound}}
+""",
+        }],
+        css="""
+.card { font-family: Arial, sans-serif; font-size: 26px; text-align: center; }
+.prompt { font-size: 40px; margin: 20px auto; white-space: pre-line; }
+""",
+    )
+
+
+def build_deck(deck_key, deck_title):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    deck_id = 2_100_000_000 + (voice_hash % 90_000_000)
+    return genanki.Deck(deck_id, deck_title)
+
+
+def add_note(deck, model, prompt, answer, qtext, atext, media_files, tag):
+    qfile = f"q_{tag}.wav"
+    afile = f"a_{tag}.wav"
+    qpath = os.path.join(MEDIA_DIR, qfile)
+    apath = os.path.join(MEDIA_DIR, afile)
+    piper_tts(qtext, qpath)
+    piper_tts(atext, apath)
+    media_files += [qpath, apath]
+    deck.add_note(genanki.Note(
+        model=model,
+        fields=[prompt, answer, f"[sound:{qfile}]", f"[sound:{afile}]"],
+    ))
+
+
+def gen_prehs():
+    deck_key = "periodic_prehs"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Periodic Table: Symbols & Names (1-36)")
+    media_files = []
+    subset = [e for e in ELEMENTS if e[0] <= 36]
+    cards = []
+    for number, symbol, name, category in subset:
+        cards.append(("symbol_to_name", number, symbol, name))
+        cards.append(("name_to_symbol", number, symbol, name))
+    random.seed(50)
+    random.shuffle(cards)
+    for kind, number, symbol, name in cards:
+        if kind == "symbol_to_name":
+            add_note(deck, model, symbol, name,
+                      f"What element has the symbol {symbol}?", name,
+                      media_files, f"prehs_s2n_{number}")
+        else:
+            add_note(deck, model, name, symbol,
+                      f"What is the symbol for {name}?", symbol,
+                      media_files, f"prehs_n2s_{number}")
+    return deck, media_files, len(cards)
+
+
+def gen_hs():
+    deck_key = "periodic_hs"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Periodic Table: Symbols, Names & Numbers (1-118)")
+    media_files = []
+    cards = []
+    for number, symbol, name, category in ELEMENTS:
+        cards.append(("symbol_to_name", number, symbol, name))
+        cards.append(("name_to_symbol", number, symbol, name))
+        cards.append(("number_to_symbol", number, symbol, name))
+    random.seed(51)
+    random.shuffle(cards)
+    for kind, number, symbol, name in cards:
+        if kind == "symbol_to_name":
+            add_note(deck, model, symbol, name,
+                      f"What element has the symbol {symbol}?", name,
+                      media_files, f"hs_s2n_{number}")
+        elif kind == "name_to_symbol":
+            add_note(deck, model, name, symbol,
+                      f"What is the symbol for {name}?", symbol,
+                      media_files, f"hs_n2s_{number}")
+        else:
+            add_note(deck, model, f"Element #{number}", symbol,
+                      f"What is the symbol for element number {num2words(number)}?", symbol,
+                      media_files, f"hs_num2s_{number}")
+    return deck, media_files, len(cards)
+
+
+def gen_category():
+    deck_key = "periodic_category"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Periodic Table: Element Categories (multiple choice)")
+    media_files = []
+    subset = [e for e in ELEMENTS if e[3] is not None]
+    random.seed(52)
+    shuffled = subset[:]
+    random.shuffle(shuffled)
+
+    letters = ["A", "B", "C", "D"]
+    for number, symbol, name, category in shuffled:
+        distractor_pool = [c for c in ALL_CATEGORIES if c != category]
+        distractors = random.sample(distractor_pool, 3)
+        choices = distractors + [category]
+        random.shuffle(choices)
+        correct_letter = letters[choices.index(category)]
+
+        prompt_lines = [f"{name} ({symbol})", ""]
+        for letter, choice in zip(letters, choices):
+            prompt_lines.append(f"{letter}) {choice}")
+        prompt = "\n".join(prompt_lines)
+
+        qtext = f"What category is {name}?"
+        atext = f"{category}"
+        add_note(deck, model, prompt, correct_letter, qtext, atext,
+                  media_files, f"cat_{number}")
+    return deck, media_files, len(subset)
+
+
+if args.deck == "prehs":
+    deck_key = "periodic_prehs"
+elif args.deck == "hs":
+    deck_key = "periodic_hs"
+else:
+    deck_key = "periodic_category"
+
+MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}")
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+GENERATORS = {"prehs": gen_prehs, "hs": gen_hs, "category": gen_category}
+deck, media_files, count = GENERATORS[args.deck]()
+
+package = genanki.Package(deck)
+package.media_files = media_files
+out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg")
+package.write_to_file(out_path)
+
+size_mb = os.path.getsize(out_path) / (1024 * 1024)
+print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} audio clips)")

tools/anki-deck-visual.py

@@ -0,0 +1,408 @@
+#!/usr/bin/env python3
+"""tools/anki-deck-visual.py — Generate image-based Anki decks (.apkg) for
+shapes, clocks, and coin-counting, with Anki's built-in type-the-answer
+input and Piper (offline, local neural TTS) audio. See
+tools/anki-deck-math.py's docstring for one-time setup (venv, genanki +
+piper-tts, downloading a voice) — same steps apply here.
+
+All images are drawn programmatically as SVG (regular-polygon geometry,
+clock-hand trigonometry, coin layouts) rather than AI-generated — image
+generation (local or cloud) is a poor fit for content that has to be
+exactly correct (an exact clock time, an exact side count, an exact coin
+total), not just plausible-looking. See this script's own point/angle
+generation functions for how each shape's geometry is computed directly
+rather than approximated.
+
+Decks:
+    shapes      regular polygons (3-10 sides, image->name and name->sides)
+                plus 5 quadrilateral types (image->name: square, rectangle,
+                rhombus, trapezoid, parallelogram — each one's geometry is
+                genuinely distinct, not just differently labeled)
+    clocks      analog clock faces, all 144 hour/5-min combinations,
+                type the time as H:MM (the hour hand moves fractionally
+                with the minutes, e.g. 6:30 sits halfway between 6 and 7 —
+                a static hour hand is the most common "looks right but
+                teaches wrong" bug in generated clock faces)
+    currency    US coins (nickel/dime/quarter — no pennies, since they're
+                barely used day to day at this point), 1-4 coins per card,
+                type the total in cents
+
+Usage (run with the venv from anki-deck-math.py's docstring activated):
+    python3 anki-deck-visual.py --deck shapes
+    python3 anki-deck-visual.py --deck clocks
+    python3 anki-deck-visual.py --deck currency
+(add --voice en_US-amy-medium etc.; --model-path if a voice isn't found
+automatically; --dry-run-tts to test the deck-building logic without any
+voice model at all, using silent placeholder audio)
+"""
+import argparse
+import hashlib
+import genanki
+import math
+import os
+import random
+import subprocess
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--deck", required=True, choices=["shapes", "clocks", "currency"])
+parser.add_argument("--voice", default="en_US-lessac-medium")
+parser.add_argument("--model-path", default=None)
+parser.add_argument("--dry-run-tts", action="store_true")
+args = parser.parse_args()
+
+SCRATCH = os.path.dirname(os.path.abspath(__file__))
+
+_CANDIDATES = [
+    args.model_path,
+    f"{args.voice}.onnx",
+    os.path.join(SCRATCH, f"{args.voice}.onnx"),
+    os.path.expanduser(f"~/{args.voice}.onnx"),
+    os.path.expanduser(f"~/.local/share/piper/voices/{args.voice}.onnx"),
+]
+VOICE_MODEL = next((p for p in _CANDIDATES if p and os.path.isfile(p)), None)
+
+if VOICE_MODEL is None and not args.dry_run_tts:
+    raise SystemExit(
+        f"Voice model for '{args.voice}' not found. Checked:\n"
+        + "\n".join(f"  {p}" for p in _CANDIDATES if p)
+        + f"\n\nFind it with: find / -iname '{args.voice}.onnx' 2>/dev/null"
+        + "\nThen pass its exact path with --model-path /the/real/path.onnx"
+        + "\n(or pass --dry-run-tts to test deck-building without any voice at all)"
+    )
+
+
+def piper_tts(text: str, out_path: str) -> None:
+    if args.dry_run_tts:
+        with open(out_path, "wb") as f:
+            f.write(
+                b"RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00"
+                b"\x22\x56\x00\x00\x44\xac\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00"
+            )
+        return
+    subprocess.run(
+        ["python3", "-m", "piper", "-m", VOICE_MODEL, "-f", out_path],
+        input=text.encode("utf-8"),
+        check=True,
+        capture_output=True,
+    )
+
+
+ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+        "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+        "fifteen", "sixteen", "seventeen", "eighteen", "nineteen"]
+TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy",
+        "eighty", "ninety"]
+
+
+def num2words(n):
+    if n < 20:
+        return ONES[n]
+    if n < 100:
+        t, o = divmod(n, 10)
+        return TENS[t] + ("-" + ONES[o] if o else "")
+    h, rem = divmod(n, 100)
+    return ONES[h] + " hundred" + (" " + num2words(rem) if rem else "")
+
+
+assert num2words(15) == "fifteen"
+assert num2words(40) == "forty"
+
+
+def time_words(hour, minute):
+    """3, 5 -> 'three oh five'; 3, 15 -> 'three fifteen'; 3, 0 -> 'three o'clock'."""
+    if minute == 0:
+        return f"{num2words(hour)} o'clock"
+    if minute < 10:
+        return f"{num2words(hour)} oh {num2words(minute)}"
+    return f"{num2words(hour)} {num2words(minute)}"
+
+
+assert time_words(3, 0) == "three o'clock"
+assert time_words(3, 5) == "three oh five"
+assert time_words(3, 15) == "three fifteen"
+assert time_words(12, 45) == "twelve forty-five"
+
+
+def build_model(deck_key):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    model_id = 1_800_000_000 + (voice_hash % 90_000_000)
+    return model_id, genanki.Model(
+        model_id,
+        f"Visual Fact ({deck_key}, {args.voice})",
+        fields=[{"name": "Image"}, {"name": "Answer"}, {"name": "QSound"}, {"name": "ASound"}],
+        templates=[{
+            "name": "Card",
+            "qfmt": """
+<div class="imgwrap">{{Image}}</div>
+{{QSound}}
+{{type:Answer}}
+""",
+            "afmt": """
+<div class="imgwrap">{{Image}}</div>
+<hr id="answer">
+{{type:Answer}}
+{{ASound}}
+""",
+        }],
+        css="""
+.card { font-family: Arial, sans-serif; font-size: 24px; text-align: center; }
+.imgwrap { margin: 10px auto; }
+.imgwrap img { max-width: 260px; max-height: 260px; }
+""",
+    )
+
+
+def build_deck(deck_key, deck_title):
+    voice_hash = int(hashlib.sha256(f"{deck_key}:{args.voice}".encode()).hexdigest(), 16)
+    deck_id = 2_200_000_000 + (voice_hash % 90_000_000)
+    return genanki.Deck(deck_id, deck_title)
+
+
+def add_note(deck, model, image_html, answer, qtext, atext, media_files, tag):
+    qfile = f"q_{tag}.wav"
+    afile = f"a_{tag}.wav"
+    qpath = os.path.join(MEDIA_DIR, qfile)
+    apath = os.path.join(MEDIA_DIR, afile)
+    piper_tts(qtext, qpath)
+    piper_tts(atext, apath)
+    media_files += [qpath, apath]
+    deck.add_note(genanki.Note(
+        model=model,
+        fields=[image_html, answer, f"[sound:{qfile}]", f"[sound:{afile}]"],
+    ))
+
+
+def add_text_note(deck, model, text, answer, qtext, atext, media_files, tag):
+    """For directions that don't need an image (e.g. name -> number of sides)."""
+    add_note(deck, model, f'<div style="font-size:36px;">{text}</div>', answer,
+              qtext, atext, media_files, tag)
+
+
+# ─── SVG generation ───────────────────────────────────────────────────────────
+def save_svg(svg_body, filename, viewbox="0 0 200 200"):
+    path = os.path.join(MEDIA_DIR, filename)
+    with open(path, "w") as f:
+        f.write(
+            f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="{viewbox}" '
+            f'width="200" height="200">{svg_body}</svg>'
+        )
+    return path
+
+
+def regular_polygon_points(n_sides, cx=100, cy=100, r=80):
+    points = []
+    # Start pointing up (-90deg) so shapes sit "upright" rather than vertex-right.
+    start_angle = -90
+    for i in range(n_sides):
+        angle_deg = start_angle + i * (360 / n_sides)
+        angle_rad = math.radians(angle_deg)
+        x = cx + r * math.cos(angle_rad)
+        y = cy + r * math.sin(angle_rad)
+        points.append((round(x, 1), round(y, 1)))
+    return points
+
+
+def polygon_svg(points):
+    pts_str = " ".join(f"{x},{y}" for x, y in points)
+    return f'<polygon points="{pts_str}" fill="#6fa8dc" stroke="#1c4587" stroke-width="4"/>'
+
+
+POLYGON_NAMES = {
+    3: "triangle", 4: "square", 5: "pentagon", 6: "hexagon", 7: "heptagon",
+    8: "octagon", 9: "nonagon", 10: "decagon",
+}
+
+QUADRILATERALS = {
+    "square": [(50, 50), (150, 50), (150, 150), (50, 150)],
+    "rectangle": [(30, 60), (170, 60), (170, 140), (30, 140)],
+    "rhombus": [(100, 20), (170, 100), (100, 180), (30, 100)],
+    "trapezoid": [(60, 60), (140, 60), (170, 140), (30, 140)],
+    "parallelogram": [(60, 60), (160, 60), (140, 140), (40, 140)],
+}
+
+
+def clock_svg(hour, minute):
+    cx, cy, r = 100, 100, 90
+    minute_angle = minute * 6 - 90
+    hour_angle = (hour % 12) * 30 + minute * 0.5 - 90
+
+    def hand(angle_deg, length, width, color):
+        rad = math.radians(angle_deg)
+        x2 = cx + length * math.cos(rad)
+        y2 = cy + length * math.sin(rad)
+        return f'<line x1="{cx}" y1="{cy}" x2="{x2:.1f}" y2="{y2:.1f}" stroke="{color}" stroke-width="{width}" stroke-linecap="round"/>'
+
+    ticks = []
+    numerals = []
+    for h in range(1, 13):
+        angle = math.radians(h * 30 - 90)
+        tx1, ty1 = cx + (r - 10) * math.cos(angle), cy + (r - 10) * math.sin(angle)
+        tx2, ty2 = cx + r * math.cos(angle), cy + r * math.sin(angle)
+        ticks.append(f'<line x1="{tx1:.1f}" y1="{ty1:.1f}" x2="{tx2:.1f}" y2="{ty2:.1f}" stroke="black" stroke-width="2"/>')
+        nx, ny = cx + (r - 22) * math.cos(angle), cy + (r - 22) * math.sin(angle)
+        numerals.append(f'<text x="{nx:.1f}" y="{ny:.1f}" font-size="14" text-anchor="middle" dominant-baseline="middle">{h}</text>')
+
+    body = (
+        f'<circle cx="{cx}" cy="{cy}" r="{r}" fill="white" stroke="black" stroke-width="3"/>'
+        + "".join(ticks) + "".join(numerals)
+        + hand(hour_angle, 45, 6, "black")
+        + hand(minute_angle, 70, 4, "black")
+        + f'<circle cx="{cx}" cy="{cy}" r="4" fill="black"/>'
+    )
+    return body
+
+
+COIN_INFO = {5: ("#c0c0c0", "5¢"), 10: ("#d9d9d9", "10¢"), 25: ("#b8b8b8", "25¢")}
+COIN_NAMES = {5: "nickel", 10: "dime", 25: "quarter"}
+
+
+def coins_svg(coin_values):
+    n = len(coin_values)
+    spacing = 200 // (n + 1)
+    parts = []
+    for i, v in enumerate(coin_values):
+        cx = spacing * (i + 1)
+        color, label = COIN_INFO[v]
+        radius = 30 if v == 25 else (26 if v == 10 else 28)
+        parts.append(
+            f'<circle cx="{cx}" cy="100" r="{radius}" fill="{color}" stroke="#444" stroke-width="2"/>'
+            f'<text x="{cx}" y="105" font-size="14" text-anchor="middle">{label}</text>'
+        )
+    return "".join(parts)
+
+
+def coin_list_words(coin_values):
+    names = [COIN_NAMES[v] for v in coin_values]
+    if len(names) == 1:
+        return f"a {names[0]}"
+    if len(names) == 2:
+        return f"a {names[0]} and a {names[1]}"
+    return ", ".join(f"a {n}" for n in names[:-1]) + f", and a {names[-1]}"
+
+
+# ─── Per-deck generators ─────────────────────────────────────────────────────
+def gen_shapes():
+    deck_key = "shapes"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Shapes: Polygons & Quadrilaterals")
+    media_files = []
+
+    jobs = []
+    for n in range(3, 11):
+        jobs.append(("polygon_image", n))
+        jobs.append(("polygon_sides", n))
+    for qname in QUADRILATERALS:
+        jobs.append(("quad_image", qname))
+    random.seed(60)
+    random.shuffle(jobs)
+
+    for kind, val in jobs:
+        if kind == "polygon_image":
+            n = val
+            name = POLYGON_NAMES[n]
+            svg_path = save_svg(polygon_svg(regular_polygon_points(n)), f"poly_{n}.svg")
+            media_files.append(svg_path)
+            add_note(deck, model, f'<img src="poly_{n}.svg">', name,
+                      "What shape is this?", name, media_files, f"shape_img_{n}")
+        elif kind == "polygon_sides":
+            n = val
+            name = POLYGON_NAMES[n]
+            add_text_note(deck, model, name.capitalize(), str(n),
+                          f"How many sides does a {name} have?", num2words(n),
+                          media_files, f"shape_sides_{n}")
+        else:
+            qname = val
+            svg_path = save_svg(polygon_svg(QUADRILATERALS[qname]), f"quad_{qname}.svg")
+            media_files.append(svg_path)
+            add_note(deck, model, f'<img src="quad_{qname}.svg">', qname,
+                      "What shape is this?", qname, media_files, f"shape_quad_{qname}")
+    return deck, media_files, len(jobs)
+
+
+def gen_clocks():
+    deck_key = "clocks"
+    model_id, model = build_model(deck_key)
+    deck = build_deck(deck_key, "Telling Time: Analog Clocks")
+    media_files = []
+
+    times = [(h, m) for h in range(1, 13) for m in range(0, 60, 5)]
+    random.seed(61)
+    random.shuffle(times)
+
+    # The question prompt ("What time is it?") is identical for every card —
+    # generate it once instead of 144 times.
+    shared_qfile = "q_clock_prompt.wav"
+    piper_tts("What time is it?", os.path.join(MEDIA_DIR, shared_qfile))
+    media_files.append(os.path.join(MEDIA_DIR, shared_qfile))
+
+    for hour, minute in times:
+        svg_path = save_svg(clock_svg(hour, minute), f"clock_{hour}_{minute:02d}.svg")
+        media_files.append(svg_path)
+        answer = f"{hour}:{minute:02d}"
+        afile = f"a_clock_{hour}_{minute:02d}.wav"
+        apath = os.path.join(MEDIA_DIR, afile)
+        piper_tts(time_words(hour, minute), apath)
+        media_files.append(apath)
+        deck.add_note(genanki.Note(
+            model=model,
+            fields=[f'<img src="clock_{hour}_{minute:02d}.svg">', answer,
+                    f"[sound:{shared_qfile}]", f"[sound:{afile}]"],
+        ))
+    return deck, media_files, len(times)
+
+
+def gen_currency():
+    deck_key = "currency"
+    model_id, model = build_model(deck_key)
+    # Deliberately nickel/dime/quarter only, no pennies — pennies are barely
+    # used day to day at this point, and skipping them keeps every total a
+    # multiple of 5 cents, which is a cleaner first pass at coin counting.
+    deck = build_deck(deck_key, "Counting Coins (nickels, dimes, quarters)")
+    media_files = []
+    denoms = [5, 10, 25]
+
+    combos = set()
+    for count in range(1, 5):
+        def rec(remaining, current):
+            if remaining == 0:
+                combos.add(tuple(sorted(current)))
+                return
+            for d in denoms:
+                if not current or d >= current[-1]:
+                    rec(remaining - 1, current + [d])
+        rec(count, [])
+    combos = sorted(combos)
+    random.seed(62)
+    random.shuffle(combos)
+
+    for coin_values in combos:
+        total = sum(coin_values)
+        svg_path = save_svg(coins_svg(list(coin_values)), f"coins_{'_'.join(map(str, coin_values))}.svg")
+        media_files.append(svg_path)
+        qtext = f"How much money is {coin_list_words(list(coin_values))}?"
+        atext = f"{num2words(total)} cents"
+        add_note(deck, model, f'<img src="coins_{"_".join(map(str, coin_values))}.svg">',
+                  str(total), qtext, atext, media_files, f"coins_{'_'.join(map(str, coin_values))}")
+    return deck, media_files, len(combos)
+
+
+if args.deck == "shapes":
+    deck_key = "shapes"
+elif args.deck == "clocks":
+    deck_key = "clocks"
+else:
+    deck_key = "currency"
+
+MEDIA_DIR = os.path.join(SCRATCH, f"media_{deck_key}_{args.voice}")
+os.makedirs(MEDIA_DIR, exist_ok=True)
+
+GENERATORS = {"shapes": gen_shapes, "clocks": gen_clocks, "currency": gen_currency}
+deck, media_files, count = GENERATORS[args.deck]()
+
+package = genanki.Package(deck)
+package.media_files = media_files
+out_path = os.path.join(SCRATCH, f"{deck_key}_{args.voice}.apkg")
+package.write_to_file(out_path)
+
+size_mb = os.path.getsize(out_path) / (1024 * 1024)
+print(f"\nDone: {out_path} ({size_mb:.1f} MB, {count} cards, {len(media_files)} media files)")