🧩 Quiz Wizard BP CS

status: recycle → wizard | surface: https://wiki.elv3.loca.zone/quiz/* | app: https://elv3.loca.zone | voice: Eleven v3 | intelligence: OpenRouter (text + optional multimodal)

Dense operator blueprint. Legacy monolithic WWTBAM pack is input debt; wizard atoms are the target product.

0 · Verdict

problem: 600 monolithic MP3s bake letters, login CTA, always-right praise, and A≠correct bias into audio.
product: atomic quiz wizard — UI owns letters/shuffle/flow; VO owns question + reveal + shared feedback only.
doctrine: JSONL/YAML = SSOT · multimodal = salvage/QC only · prefer re-TTS over carving contaminated clips.
public wiki: workflows + schemas · never secrets, cookies, loopback, provider keys.

1 · Stack

surfaces:
  wiki:  https://wiki.elv3.loca.zone/quiz/*      # Quartz docs SSOT
  app:   https://elv3.loca.zone                  # SvelteKit Eleven3 bench
  auth:  https://elv3.loca.zone/auth
runtime:
  wiki_engine: Quartz v5 via /home/loca/dev/wikis/build.sh elv3
  app:         SvelteKit + Node 22 · systemd elv3.service · PORT 51115
  tts:         ElevenLabs eleven_v3 via app proxy /api/elevenlabs/tts
  recycle_ai:  OpenRouter text (enrich) + optional audio multimodal (salvage)
tooling:
  recycle: batches/recycle_wwtbam.py
  pilot:   batches/quiz-wizard-v1/
  legacy:  batches/wwtbam-de-eleven3-*.{jsonl,tsv,yaml,json} + batches/audio/
media:
  format: mp3_44100_128
  voice:  nsiEp1alHkdiizNqCK2X   # keep stable across recycle unless A/B voice test

2 · Architecture

┌──────────── source.yaml ────────────┐
│ answers[0]=correct · no letters     │
└───────────────┬─────────────────────┘
                ▼
┌──────── recycle pipeline ───────────┐
│ 1 dissect (deterministic)           │
│ 2 enrich  (OpenRouter text)         │
│ 3 salvage (multimodal · optional)   │
│ 4 emit    (quiz-pack + tts-batch)   │
│ 5 render  (ElevenLabs via elv3)     │
│ 6 qc      (facts · durations · bal) │
└───────────────┬─────────────────────┘
                ▼
┌──────── quiz-pack.json ─────────────┐
│ questions[] · clips{} · playback{}  │
└───────┬───────────────┬─────────────┘
        ▼               ▼
   wiki docs        wizard UI
   (Quartz)         (SPA / elv3 tab)
        │               │
        └────── audio/atoms/*.mp3 ────┘

boundaries:
- wiki: human SSOT + operator contracts.
- batches/: machine payloads (outside Quartz content when large).
- app: paid TTS proxy + future /quiz play surface.
- OpenRouter: rewrite/fact-check/salvage — not gameplay runtime.
anti-architecture (legacy — do not repeat):
- one MP3 = question + A–D + CTA.
- one MP3 = lettered reveal + praise + “next”.
- shuffle frozen into filename forever.
- “correct never on A” as a feature.

3 · Wiki Route Map (`/quiz/*`)

slug	role
`/quiz/`	hub — status, outputs, links
`/quiz/blueprint/`	this BP CS — stack → rollout
`/quiz/batch-files/`	legacy artifact map (debt reference)
`/quiz/prompt-stack/`	ear-first templates → migrate to atomic
`/quiz/tag-library/`	safe Eleven v3 tags
`/quiz/voice-batches/`	render loop / cache contract

future (add when built):
- /quiz/wizard-pack/ — quiz-pack schema + playback graph.
- /quiz/recycle/ — dissect → enrich → salvage → emit runbook.
- /quiz/qc/ — fact/letter/duration gates.

4 · Data Model

4.1 Source (canonical)

question:
  id: qw-01                    # stable
  category: allgemeinwissen
  difficulty: easy|medium|hard
  question: "…"                # DE, short, no prefix spam
  answers: [CORRECT, w1, w2, w3]  # index 0 ALWAYS correct

4.2 Runtime pack (`quiz-pack.json`)

pack:
  id: string
  language: de
  letter_policy: "UI assigns A–D after shuffle; VO never speaks letters"
  playback:
    on_start: [shared-intro]
    before_answer: [shared-ask]          # optional
    on_correct: [shared-correct-*, "{qid}-reveal", shared-next]
    on_wrong:   [shared-wrong-*,   "{qid}-reveal", shared-next]
    on_timeout: [shared-timeout,   "{qid}-reveal", shared-next]
    on_finish:  [shared-outro]
  questions[]:
    id, category, difficulty, question, answers, correct_index: 0
    clips: { question: "{id}-question", reveal: "{id}-reveal" }

4.3 TTS atoms (`tts-batch.jsonl`)

kind	count policy	text rules
`shared`	~9–12 total	intro/ask/correct×N/wrong×N/timeout/next/outro
`question`	1 per Q	question only · tags ok · no letters · no CTA
`reveal`	1 per Q	correct answer text only · no letter · no praise

forbidden in any atom: Logg dich ein · Antwort A–D · Gut gemerkt · Weiter geht's · baked correct letter.

4.4 Legacy bridge fields (dissect only)

dissected:
  id, category_*, question_nr
  question, answers_correct_first
  options_spoken_order      # from old script — discard for play
  baked_correct_letter      # QC evidence of bias
  files: { prompt_mp3, answer_mp3 }
  prompt_junk: { had_login_cta, had_which_cta, tag_count }
  reveal: { reveal_text, had_always_right_praise, had_baked_letter }

5 · UI / UX

5.1 Wizard loop (one job per beat)

intro VO → [category pick] →
  play question VO → show A–D (UI shuffle) →
  optional ask VO → await tap / timeout →
  play correct|wrong VO → play reveal VO →
  shared next VO → … → outro VO

5.2 Screen inventory

hub: start · resume · category · settings (voice mute, timer).
play: question text + 4 answer buttons + progress + timer ring.
feedback: correct/wrong state color · reveal text mirrored from VO.
summary: score · streak · replay misses · share (optional).

5.3 UX invariants

letters live only in UI chrome; never in VO.
wrong answers get real feedback (not fake praise).
last question uses outro, not “nächste Frage”.
skip VO allowed; UI remains playable muted.
no login CTA mid-question (auth is app gate, not quiz beat).
first viewport of play: brand-free focus — question + answers + one primary action.

motion: answer press · feedback flash · progress step (2–3 intentional).
a11y: keyboard 1–4 / Enter · ARIA live region on feedback · captions = question text.
timing: expose clip duration_s in manifest for UI sync; prefer short Q VO (~2–5s).

6 · App Routes & Integration

6.1 Existing Eleven3 (keep)

method	route	use
GET	`/auth`	session gate
GET	`/api/voices`	voice list
POST	`/api/elevenlabs/tts?stream=true`	atom render
POST	`/api/elevenlabs/sfx`	optional stings
UI tabs	Speech · Voices · Designer · SFX · Batch · History	operator bench

6.2 Proposed quiz surface (elv3 or sibling)

method	route	use
GET	`/quiz`	wizard SPA entry
GET	`/quiz/api/pack/:id`	serve quiz-pack.json
GET	`/quiz/api/audio/:clipId`	atom MP3 (auth’d or static)
POST	`/quiz/api/session`	optional score session
POST	`/api/admin/recycle/*`	operator-only; not public

6.3 Recycle CLI (batches)

# free
python3 batches/recycle_wwtbam.py dissect
python3 batches/recycle_wwtbam.py emit
 
# needs OPENROUTER_API_KEY
python3 batches/recycle_wwtbam.py enrich --limit 20
python3 batches/recycle_wwtbam.py salvage --limit 5   # multimodal sample
python3 batches/recycle_wwtbam.py all --limit 20

6.4 External systems

elevenlabs:  paid TTS via elv3 proxy only
openrouter:  enrich + optional salvage · key in env · never wiki
nginx:       elv3.loca.zone → :51115 · wiki.elv3.loca.zone → wikis/elv3/current
systemd:     elv3.service (user)
build:       /home/loca/dev/wikis/build.sh elv3

7 · Playback Graph (composition)

atoms:
  shared: [intro, ask, correct-01..N, wrong-01..N, timeout, next, outro]
  per_q:  [question, reveal]
compose:
  start:   intro
  turn:    question → (ask?) → wait → branch
  branch:
    correct: pick(correct-*) → reveal → next
    wrong:   pick(wrong-*)   → reveal → next
    timeout: timeout         → reveal → next
  end:     outro   # replaces next on last index
shuffle:
  ui_only: true
  balance_letters: target ~25% A/B/C/D over session
  seed: optional per-session · never bake into MP3

8 · QC Gates

facts: enrich fact_ok · spot-check elephants ≠ giraffes.
script: zero hits for login / Antwort [A-D] / Gut gemerkt / lettered reveal.
audio: MP3 magic · min bytes · duration bounds (Q: 1.5–8s · reveal: 0.8–4s · shared: 0.5–5s).
pack: every question has 4 answers · correct_index=0 · clips resolve on disk.
bias: if any atom still contains letters → fail build.
salvage: default recommend=regenerate unless clean silence boundaries.

9 · Rollout Phases

P0 — Hub & truth (now)

publish this BP under /quiz/blueprint/.
mark legacy quiz pages as debt reference.
keep pilot: batches/quiz-wizard-v1/ (20Q) as gold sample.

P1 — Recycle pilot

dissect full 300 · report login/praise/letter bias.
enrich --limit 20 via OpenRouter · emit wizard pack.
render 20Q atoms through elv3 TTS · listen QA.
decision: regenerate-all vs selective salvage (expect regenerate).

P2 — Wizard playable

ship /quiz play UI against quiz-pack + atoms.
shared VO bank locked · categories selectable · mute/timer.
score summary + miss list.

P3 — Full bank

enrich+emit remaining questions in chunks (50).
fact-fix pass · drop/rewrite bad items.
render full atom set · retire monolithic /quiz “600 tts_items” as success metric.

P4 — Polish

SFX stings · optional second host voice · captions.
session persistence · difficulty curves.
wiki pages: wizard-pack · recycle · qc.

10 · File Map (operator)

dev/wikis/elv3/
  content/quiz/
    index.md                 # hub
    blueprint/index.md       # THIS BP CS
    batch-files|prompt-stack|tag-library|voice-batches/
  batches/
    wwtbam-de-*              # LEGACY monolithic
    audio/                   # LEGACY mp3 (600)
    quiz-wizard-v1/          # GOLD pilot atoms schema
    recycle_wwtbam.py        # dissect→enrich→salvage→emit
    recycled/                # pipeline outputs
      01-dissected.jsonl
      02-enriched.jsonl
      03-salvage.jsonl
      wizard/{quiz-pack,tts-batch,manifest}
dev/elv3/                    # app · TTS proxy · future /quiz UI

11 · Invariants (new)

answers[0] = correct in source; UI shuffles; VO never speaks A–D.
branching feedback is shared clips, not per-question praise.
no auth/marketing CTA inside question audio.
multimodal never replaces JSONL as SSOT.
public wiki: behavior + contracts only.
metric of done: playable wizard · not “N MP3s rendered”.

loca.zone · elv3.loca.zone · wiki.elv3.loca.zone/quiz/

🧭 Explorer

Eleven3

Table of Contents

🧩 Quiz Wizard BP CS

0 · Verdict

1 · Stack

2 · Architecture

3 · Wiki Route Map (`/quiz/*`)

4 · Data Model

4.1 Source (canonical)

4.2 Runtime pack (`quiz-pack.json`)

4.3 TTS atoms (`tts-batch.jsonl`)

4.4 Legacy bridge fields (dissect only)

5 · UI / UX

5.1 Wizard loop (one job per beat)

5.2 Screen inventory

5.3 UX invariants

6 · App Routes & Integration

6.1 Existing Eleven3 (keep)

6.2 Proposed quiz surface (elv3 or sibling)

6.3 Recycle CLI (batches)

6.4 External systems

7 · Playback Graph (composition)

8 · QC Gates

9 · Rollout Phases

P0 — Hub & truth (now)

P1 — Recycle pilot

P2 — Wizard playable

P3 — Full bank

P4 — Polish

10 · File Map (operator)

11 · Invariants (new)

🧭 Explorer

Eleven3

Table of Contents

🧩 Quiz Wizard BP CS

0 · Verdict

1 · Stack

2 · Architecture

3 · Wiki Route Map (/quiz/*)

4 · Data Model

4.1 Source (canonical)

4.2 Runtime pack (quiz-pack.json)

4.3 TTS atoms (tts-batch.jsonl)

4.4 Legacy bridge fields (dissect only)

5 · UI / UX

5.1 Wizard loop (one job per beat)

5.2 Screen inventory

5.3 UX invariants

5.4 Motion / a11y

6 · App Routes & Integration

6.1 Existing Eleven3 (keep)

6.2 Proposed quiz surface (elv3 or sibling)

6.3 Recycle CLI (batches)

6.4 External systems

7 · Playback Graph (composition)

8 · QC Gates

9 · Rollout Phases

P0 — Hub & truth (now)

P1 — Recycle pilot

P2 — Wizard playable

P3 — Full bank

P4 — Polish

10 · File Map (operator)

11 · Invariants (new)

12 · Related

3 · Wiki Route Map (`/quiz/*`)

4.2 Runtime pack (`quiz-pack.json`)

4.3 TTS atoms (`tts-batch.jsonl`)