Initial spec for Sagaphone

Pulled from Notion project docs: overview, architecture, data model,
event system, line logic, and implementation notes for the family-tree
generator + TTS narrator.

Co-Authored-By: Claude <noreply@anthropic.com>

SPEC.md

@@ -0,0 +1,57 @@
+# Sagaphone — Spec
+
+A web-based, procedural family-saga narrator with TTS. Sagaphone generates a
+random family tree and narrates its story via text-to-speech in the browser.
+It's meant as a "fall asleep" tool: open it on an iPad or phone, set a timer,
+and it reads family sagas until the timer runs out.
+
+**Language of narration:** English. **Tone:** fantasy-medieval.
+
+## Architecture
+
+- **Frontend:** SvelteKit — audio playback + UI only, no business logic.
+- **Backend:** FastAPI, deployed on Zeus, reachable via a URL (e.g.
+  `sagaphone.orbitstack.casa`).
+- **Reverse proxy:** Caddy.
+- **TTS:** Piper, runs server-side, audio streamed to the browser. Deliberately
+  not Web Speech API — avoids iOS Audio Session issues, works in all browsers.
+- **Narration:** Anthropic Haiku API, called server-side only (~$1.50/month at
+  daily use). API key is never exposed to the client — no API keys in the
+  frontend at all.
+
+## Flow
+
+1. User opens Sagaphone in the browser and sets a timer.
+2. On start: a family tree up to generation 6 is pre-generated as JSON — pure
+   random logic, no LLM involved, runs in milliseconds.
+3. An active line (branch) is picked at random.
+4. The LLM generates a paragraph for the active person's current life stage.
+5. TTS reads the paragraph aloud; the next paragraph is fetched in the
+   background while it plays.
+6. When a person's story is fully told: move to the next person in the active
+   line, or switch lines if the line has died out.
+7. Repeat until the timer runs out.
+
+## Features / Design Areas
+
+- [Data Model](spec/data-model.md) — enums, `Person`, `Stage`, `EventEntry`, `FamilyTree`, `World`.
+- [Event System](spec/event-system.md) — event categories, death probability, event tables, follow-bonus map.
+- [Line Logic](spec/line-logic.md) — how the active family branch is chosen and switched.
+- [Implementation Notes](spec/implementation-notes.md) — event weights/stage locks, living-family lookup, location/name/appearance generators.
+
+## Open Questions (from planning, still unresolved)
+
+- [ ] Tune `magic_factor` and death probabilities via playtesting.
+- [ ] Fill event tables with more concrete fantasy events.
+- [ ] Define appearance generation in more detail.
+- [ ] Work out the LLM prompt structure per life stage.
+- [ ] Test the audio-loop workaround on iOS.
+- [ ] Decide name / seed mechanism for the first test person.
+- [ ] Plan deployment on Zeus.
+
+## Source
+
+Planning originally done in Notion ("Sagaphone" page under "Dokumentation").
+This repo is the implementation target; specs here are the source of truth
+going forward — update them alongside the code, don't let Notion and the repo
+drift apart.