Epic-The-Musical-Timeline/docs/DECISIONS.md

Decisions

Append-only. Never edit or delete an entry — supersede it with a new one that links back. One entry per decision a future maintainer would otherwise have to reverse-engineer. No index: grep -n '^## ' docs/DECISIONS.md lists every entry (date, title, line number).

2026-10-23 — Mockups are committed and served, not throwaway

Status: accepted Context: The agent-repo playbook keeps mockups gitignored in design/mockups/, never wired into the app. Spec 001 asks for 7 design-direction mockups that run in the Docker image for the maintainer to compare. Decision: (maintainer decision) Mockups live in src/mockups/NN-slug/, are committed, served by the Bun server and covered by route smoke tests. Mockup agents edit only their own folder. Alternatives: Gitignored design/mockups/ (can't ship in the image or be reviewed from the remote). Consequences: Mockup code is in the bundle and the history; when a direction is chosen, the unused mockups need an explicit removal decision (docs/TODO.md).

2026-10-23 — Production bundle runs from dist/

Status: accepted Context: With Bun 1.3.14, a --production bundle of HTML imports resolves its assets relative to the current working directory; bun dist/server.js from the repo root throws "Bundled file … not found". Decision: bun run start is cd dist && bun server.js; the Docker runtime stage uses WORKDIR /app/dist. Alternatives: Not recorded (e.g. --asset-naming/naming options were not explored). Consequences: Any new run script or deploy target must set the cwd to dist/.

2026-10-23 — Bun only, self-contained assets

Status: accepted Context: Spec 001 constraints. Decision: Bun's own server, bundler and test runner with HTML imports; no Vite/Next. Fonts and three.js bundled from npm, no CDN. YouTube as link cards, not embeds. three.js only in the 3D mockups (06, 07). Alternatives: Not recorded. Consequences: The image works offline apart from outbound links.

2026-10-23 — Placeholder lyrics, unverified facts marked

Status: accepted Context: Lyrics recalled from memory risk inaccuracy, and their copyright question is open. Decision: Sample data uses clearly marked placeholder lyric lines in the real data shape; any fact, story time or Odyssey reference not confirmed carries // TODO(verify). Alternatives: Real lyrics (deferred by the maintainer). Consequences: Nothing in src/data/sample.ts may be presented as fact-checked.

2026-10-23 — Adopt AGENTS.md as single source of truth

Status: accepted Context: Agents had no durable project context and no consistent workflow between sessions. Decision: AGENTS.md is canonical; CLAUDE.md/GEMINI.md are pointers. Specs are permanent in docs/specs/. Plans live in docs/plans/ only while work is in progress and are removed before the merge request. Both override the superpowers default paths. Alternatives: Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore the repo every session — measurably slower and more tokens). Consequences: Rule changes happen in one file; pointer files must stay thin. Plans are working artefacts: kept after merge they go stale and contradict the code, so the spec is the record.

2026-10-30 — three.js allowed in mockup 13

Decision: mockup 13 (Curtain call) may use three.js, like 06 and 07. It mocks the frieze → 3D sea → frieze → cave transition, which needs the 3D sea. three.js is already a dependency; nothing new is added.

2026-10-30 — three.js allowed in mockup 14

Decision: mockup 14 (Voyage with side panel) may use three.js; it converges 13's 3D flow with a persistent side panel. No new dependency.

2026-10-30 — three.js allowed in mockup 15

Decision: mockup 15 (Voyage, look 2) may use three.js; it iterates on 14. No new dependency.

2026-10-30 — three.js allowed in mockup 16

Decision: mockup 16 (Voyage, readable) may use three.js; it iterates on 15. No new dependency.

2026-10-30 — Real content is mounted, never committed (spec 003)

Decision: the real audio, timed lyrics, cover art and Homer texts stay in a folder outside the repo (~/epic-the-musical-content on the dev host), served under /content/ from CONTENT_DIR and mounted read-only into the container. Why: the audio, lyrics and art are Jorge Rivera-Herrans' copyrighted work; committing them would push them to Gitea and bake 1.5 GB into the image. The user chose this ("Mount it, never commit"). Range requests are handled in src/content/routes.ts so audio can seek.

2026-10-30 — three.js allowed in mockup 17

Decision: mockup 17 (Voyage with real content) may use three.js; it iterates on 16. No new dependency.

2026-10-30 — Homer in translations with Greek names

Decision: the Odyssey and Iliad are served from Butcher & Lang (Gutenberg #1728) and Lang, Leaf & Myers (#3059) when present, falling back to Butler (#1727, #2199). Why: the user disliked Butler's Roman names (Ulysses, Minerva, Jove); EPIC uses the Greek ones. Both are public domain.

2026-10-30 — No thread for Odysseus himself

Decision: the album data has no Odysseus character theme. Why: character themes are derived from singers, and Odysseus sings in 35 of 40 songs, so his thread marked almost every stop and crowded the timeline ("+28 more"). His story is carried by the musical motifs (Warrior of the Mind, Just a Man, …).

2026-10-30 — The voyage app (spec 002): structure and v1 choices

• Album data is separate from the mockups' data (src/data/album/ vs src/data/types.ts/sample.ts), so the 17 mockups keep working unchanged.
• App at /, gallery at /mockups/. The mockups stay served as the design record.
• Odyssey references are a book plus keywords, not line numbers: the public-domain prose translations have no line numbers. Links point at Butcher & Lang (Gutenberg #1728).
• Landings: cave = Polyphemus, Survive; arena = God Games; hall = all five Ithaca songs.
• Transitions: same saga sails, the adjacent saga drops its frieze, further jumps fade. Last request wins; a curtain left down by a cancelled step is lifted by the next one.
• Play voyage is silent (3.4s per song): starting audio without a click is close to autoplay.
• Fan works are empty in v1 with an empty state; no invented works are shown.
• Without WebGL the frieze is the stage (dropped, never lifted), so the album stays browsable.
• Back to sea leaves a landing but keeps the song.