Epic-The-Musical-Timeline/docs/design/002-direction-round-notes.md

---
status: in-progress (brainstorming, round 2)
---

# 002 — Direction round notes (after the 7 mockups)

A running record of the user's words and the decisions they lead to, kept so that nothing gets lost
between sessions. **User quotes are verbatim.** Lines marked *(Claude's proposal)* are suggestions
the user has not confirmed yet. Newest entries go at the bottom.

Context: spec `docs/specs/001-timeline-mockups.md` produced mockups 01–07 (merged to `main`,
2026-10-23). This round picks the direction for the real app.

## 2026-10-23

### 1. Mockups that were dropped

> "First off, a lot of good stuff. Lets start with the easy ones. Vertical story, constellation and
> score/waveform is too uninteresting."

- **Dropped:** 02 Vertical story, 05 Score/waveform, 06 Constellation.
- **Still in play:** 01 Editorial scroll, 03 Transit map, 04 Greek frieze, 07 Sea voyage.
- The dropped mockups' code stays in place until the direction is settled.

### 2. A 2D version alongside a 3D version

> "They are all very nice. I see both a 2D version, and an accompanying 3D version, The editorial
> scroll combined with the transit map in some way could be nice fo9r a 2D layout / map, while using
> the sea voyage in 3d together with the greek frieze in some way could be nice as well. The sea
> voyage is nice to start off, buth could then in the different islands and places have sublevels,
> eg. landings where we see the cave of the cyclops, we see athenas fight in god games, and odysseus
> ithica when he comes home."

- **2D:** editorial scroll combined with transit map, as a layout/map.
- **3D:** sea voyage combined with the Greek frieze.
- **The 3D starts on the sea voyage.**
- **Sublevels at islands and places ("landings"), with the user's examples:**
  - the Cyclops' cave;
  - Athena's fight in God Games;
  - Odysseus coming home to Ithaca.
- **Implication:** the sample data must grow beyond Troy, Cyclops and Storm (Wisdom saga / God Games,
  Ithaca saga) so that those landings have content.

### 3. The frieze as the transition between 2D and 3D

> "Hmm. Maybe we can have the freize's look be the one that tries the different stuff together, like
> a curtain call from the first section to go over in the second, where it starts off 2d with the
> freize, then slowly morphs into the sea voytage, then when he lands on cyclops islands, it goes
> back to the freize, then into the cave? For the looks, im not sure. On one hand I want the 2D map to
> be a browsable and perhaps simple display, yet I also want it to be a kind of map in the 3D one."

- **The frieze is the connecting device**, "like a curtain call" between sections.
- **The flow:**
  1. The experience starts in 2D, on the frieze.
  2. The frieze morphs into the 3D sea voyage.
  3. At a landing (e.g. the Cyclops' island) it returns to the frieze.
  4. From the frieze it goes into the 3D sublevel (the cave).
- **Looks:** undecided.
- **The 2D map has two roles:**
  - a browsable, perhaps simple display;
  - a map used *inside* the 3D experience.

### 4. The sea chart

*(Claude's proposal)* A single map serves both uses. On its own it is the browsable 2D page. Inside
3D it is the same chart, unrolled as an overlay on the captain's table. Clicking a port sails or
jumps there.

> "Yeah i did think sea chart, im just not sure how we have it easy to navigate and look at as with
> the editorial scroll and transit map."

- **Agreed:** the 2D map is a sea chart.
- **Open problem:** keeping the chart as easy to navigate and read as 01 and 03.

### 5. Sea-chart mockup round

> "Hmm sure. Lets do 3 or 4 mockups and see."

- **Four throwaway spikes on branch `feat/sea-chart-round`:**
  - 08 Sea chart + log line
  - 09 Schematic sea chart
  - 10 Unrolling chart
  - 11 Atlas with insets
- **Each spike also shows the chart as the compact in-3D overlay.**
- **Spike rules:** no formal review loop; the user picks from what they see.

### 6. Process requests

> "Remember to write my words and thoughts down, such that if context is autocompacted, we dont lose
> anything"

This file exists because of that request. It gets updated after every user message in this round.

### 7. Paused at the usage limit

> "we have almost reached usage limit. Make the agents save their work for now, so we can continue
> without losing progress."

**State when paused (branch `feat/sea-chart-round`, not pushed):**

| Spike | State |
|---|---|
| 08 | Only `src/mockups/08-chart-logline/geo.ts` is written: chart geography, route and log-line maths. Nothing imports it yet, and it has not been typechecked. `main.ts` and `style.css` are still stubs. |
| 09 | No code yet; the stub is unchanged. The design plan and resume checklist are written. |
| 10 | No code yet; the stub is unchanged. The design plan and resume checklist are written. |
| 11 | Not started. It is still a stub. Idea: an overview chart of the whole sea; clicking an island opens a zoomed inset chart with that saga's songs as ports. |

- **Brief and per-spike plans:** `docs/design/002-sea-chart-spikes/`. It holds `round2-brief.md` and one `<slug>-report.md` per spike, each with a design plan, a what's-left checklist and the next step. Agents should keep writing reports to `.superpowers/brainstorm/`, and the controller copies them into this folder.
- **Preview:** http://10.20.20.2:8099/ still runs the `main` build (01–07). It does not show 08–11 yet.

**To resume:**
1. Read this file and the brief.
2. Dispatch one agent per spike, at most 3 at a time. Point each at its report file and the brief, and tell it to continue from the checklist.
3. Build 11.
4. Rebuild the preview container from this branch:
   `docker build -t epic-timeline . && docker rm -f epic-timeline-preview && docker run -d --restart unless-stopped -e PORT=3000 -e CONTENT_DIR=/content -v /home/user/epic-the-musical-content:/content:ro -p 10.20.20.2:8099:3000 --name epic-timeline-preview epic-timeline`
   (the content mount was added 2026-10-30, spec 003)
5. Ask the user which chart approach reads best.

## 2026-10-29

### 8. Resumed

> "continue."

- Resumed from section 7. Spikes 08, 09 and 10 were redispatched (3 concurrent), each continuing from its saved report.
- Spike 11 follows when a slot frees.
- **All four spikes are finished and committed on `feat/sea-chart-round`.** Each final report is in `docs/design/002-sea-chart-spikes/<slug>-report.md`.
  - 08 Sea chart + log line: a full Admiralty-style chart on top, synced to an editorial log line below.
  - 09 Schematic sea chart: an octilinear transit diagram over a faint chart, with a slider that morphs it into rough true geography.
  - 10 Unrolling chart: the editorial scroll drawn on a vellum portolan, with a ship marker and a minimap.
  - 11 Atlas with insets: an overview of the whole voyage on one screen; each island opens an atlas plate.
- The preview at http://10.20.20.2:8099/ was rebuilt from this branch so the user can compare them.

### 9. Verdict on the sea-chart spikes

> "8 and 9 doesnt work too well. 11 work ssurprisingly well, but the mtro map when you zoom into
> stuff doesnt hit as well. The style of 10 is much cooler."

- **Dropped:** 08 Sea chart + log line, 09 Schematic sea chart.
- **Keep from 11:** the atlas *navigation*: the whole voyage on one overview, islands opening inset plates.
- **Not working in 11:** the transit-style ("metro map") motif lines inside the zoomed plates.
- **Keep from 10:** the *style*: vellum portolan, rods, red dashed route, ship, compass rose.
- *(Claude's proposal)* Converge into one mockup, **12 Vellum atlas**: 11's overview → plate
  navigation drawn in 10's vellum style. The metro band inside plates is replaced, and the plate
  motif treatment is a toggle inside the mockup with three options to compare:
  - **A. Threads under the sea** (10/01-style): soft threads below the route, knots at ports.
  - **B. Pennants at ports**: no lines; each port flies small coloured pennants for its motifs, and
    a selected motif draws a faint sea-current curve linking its ports.
  - **C. Ink only**: no motif marks on the chart until a motif is picked; then its ports are ringed
    and named parts are written beside them in the motif's ink colour.

### 10. Paused again at the usage limit

> "We are going to hit 5 hour limit soon, wind down and wait for my go to continue."

- 12 Vellum atlas was being built by one agent from `docs/design/002-sea-chart-spikes/12-vellum-atlas-brief.md`.
  It was told to stop and write a pause report (what's done / checklist / next step) to
  `docs/design/002-sea-chart-spikes/12-vellum-atlas-report.md`; its partial work is in
  `src/mockups/12-vellum-atlas/` and committed as WIP on `feat/sea-chart-round` (not pushed).
- **To resume (only on the user's go):** read this file, the 12 brief and the 12 report; dispatch one
  agent to continue from the report's checklist; check its screenshots; rebuild the preview
  container (command in §7); tell the user 12 is live and ask A/B/C.

### 11. Resumed

> "All right, usage limits back. Continue."

- Resumed from §10: one agent continues 12 from its pause report.

- **12 is finished and committed** (`feat/sea-chart-round`, not pushed); final report in
  `docs/design/002-sea-chart-spikes/12-vellum-atlas-report.md`. Preview rebuilt with 01–12.
- *(Agent's recommendation, unconfirmed)* A as default with more room on busy plates, borrowing C's
  hand-lettered part names for the picked theme. Known weak spot: A's faded labels on the 7-theme
  Cyclops plate are ~9px.

### 12. Motifs inside a plate: threads

> "Threads, definetly."

- **Chosen:** treatment **A, Threads under the sea**, for motifs inside a plate. B (pennants) and C
  (ink only) are deselected.
- Known weak spot to fix when it is built for real: faded thread labels on busy plates (~9px on the
  7-theme Cyclops plate) need more room.
- *(Claude's proposal)* The 2D sea chart is now 12 Vellum atlas with threads. Next open questions are
  the look of the whole and how the frieze/3D layers attach to this chart.

### 13. A short mockup of the transition

*(Claude's question)* The look of the whole: 1 vellum throughout, 2 two worlds (vellum chart and 3D,
terracotta frieze only at transitions; Claude's recommendation), 3 frieze-led. Offered a short
mockup of the transition.

> "Short mockup please :)"

- The user did not pick 1/2/3 yet, so mockup **13 Curtain call** shows the transition sequence with
  the look as a toggle (1/2/3), defaulting to 2.
- Sequence: frieze (2D) → morphs into the 3D sea → ship reaches Cyclops' Island → back to the frieze
  → into the cave. The vellum chart (12) appears as the map on the captain's table at sea.
- three.js is allowed in 13 (it is already a dependency; it reuses 07's sea).

- **13 is finished and committed** (`feat/sea-chart-round`, not pushed); report in
  `docs/design/002-sea-chart-spikes/13-curtain-call-report.md`. Preview rebuilt with 01–13.
  Known rough spots: a small sideways camera shuffle at landfall, sun glare in looks 1/2, a boxy giant.

### 14. Verdict on 13 Curtain call

> "Yes it looks pretty good! Small design issues here and there but these can be fixed. 1, 2 and 3 all
> look decent. The UI of 2 and 3 tend to look a bit better though. For the models/3d, its better to go
> stylistic than realistic. While going through the 3D experience, its still important to have the
> right side window open, to show information, paths, lyrics, and fan works."

- **Accepted:** the curtain-call flow (frieze → sea → landfall → frieze → landing) works; small design
  issues are fixable later.
- **Look:** all three are "decent"; the UI of **2 (two worlds)** and **3 (frieze-led)** looks better.
  Look 1 (vellum throughout) is effectively out; 2 vs 3 is not decided.
- **3D models: stylistic, not realistic.**
- **New requirement:** during the 3D experience a **right-side window stays open**, showing:
  - information (about the current song/place);
  - paths (motif threads / the route);
  - lyrics;
  - fan works.
- *(Claude's proposal)* Converge into **14 Voyage with side panel**: 13's flow with stylised models and
  a persistent right panel (tabs: About · Paths · Lyrics · Fan works), with a 2/3 look toggle.
  Fan works and lyrics are placeholders (no real lyrics, no real fan artists' names or links).

- **14 is finished and committed** (`feat/sea-chart-round`, not pushed); report in
  `docs/design/002-sea-chart-spikes/14-voyage-panel-report.md`. Preview rebuilt with 01–14.
  Agent's choices: the panel stays open in all five beats (frieze beats too); the small vellum chart
  moved into the Paths tab. Rough spots: empty space around the frieze band with the panel open, light
  sea patches that read like lily pads, heavy outlines on the giant.

### 15. Verdict on 14: leaning look 2, paths too hidden

> "This is actually surprisingly really good work. The design for 3 really makes the whole site feels
> like it works together, both in terms of frieze, the side panel and the world. However, im leaning a
> lot more towards 2. The colors pop a lot more. The paths feel a bit too hidden away now. All in all
> though, its looking better and better"

- **Look:** leaning strongly to **2 (two worlds)**: "the colors pop a lot more".
- **What 3 does better:** it makes frieze, side panel and world feel like one site. Worth carrying
  that cohesion into 2.
- **Problem:** the paths (motif threads) are "a bit too hidden away" inside the Paths tab.
- Not yet a final approval ("looking better and better").
- *(Claude's proposal)* Mockup **15 Voyage, look 2**: look 2 only, borrowing 3's cohesion (shared
  frieze border/ornament and type across frieze, panel and HUD), and paths brought out of the tab, with
  a toggle of three placements:
  - **A. Pinned strip** — a compact thread strip always visible at the top of the panel, above the tabs.
  - **B. Threads in the world** — the current song's motifs as coloured ribbons in the 3D sea,
    trailing the ship and running ahead to where they return.
  - **C. Timeline at the bottom** — the step bar becomes a horizontal song timeline with motif threads
    under it (the original "big horizontal line"), with "you are here".

- **15 is finished and committed** (`feat/sea-chart-round`, not pushed); report in
  `docs/design/002-sea-chart-spikes/15-voyage-look2-report.md`. Preview rebuilt with 01–15.
  Agent's recommendation (unconfirmed): C (bottom timeline) as the home for paths, with B's ribbons
  as an optional extra in 3D. Known: B's labels stack over the cave mouth; A is dense (numbers only);
  C takes ~220px of stage height.

- User asked to compare with 14: "can you open mockup 14 again so i can compare?" (14 is still served
  unchanged at /mockups/14-voyage-panel/.)

### 16. 14 vs 15 compared

> "Thanks. First off, 15's font is very hard to read. 15 Accents with the freisa patterns on all the
> menus are very nice though, and the colors on the "between sagas a year at sea" looks nice. The hard
> question is paths A, B and C, cause they all have their strengths. In terms of menu, listen should be
> easier to do, and perhaps closer tied to the lyrics tab."

- **Fix:** 15's typography is "very hard to read" (the small, wide-tracked Cormorant capitals used for
  labels, and small SVG text). Go back to readable labels (14's style) at comfortable sizes.
- **Keep:** the frieze-pattern accents on all menus/panels (15).
- **Keep:** the colours of the "Between sagas · a year at sea" beat (15's beat 2).
- **Paths A/B/C:** undecided, "they all have their strengths".
- **Listen:** should be easier, and tied more closely to the Lyrics tab.
- *(Claude's proposal)* Mockup **16** from 15:
  - readable type: Inter for all labels/UI (no wide-tracked small caps), Cormorant only for large titles;
    nothing under 13px;
  - **Listen + Lyrics as one tab**: a player at the top of the tab (play, scrub bar with part markers),
    lyrics by part below; clicking a part jumps there, the current part is highlighted as it plays;
    plus a play button always visible in the panel header;
  - **paths combined rather than chosen**: C's timeline is the default home and can be collapsed to a
    slim bar; when collapsed, A's strip appears in the panel; B's ribbons in the sea are an on/off
    switch ("Threads on the sea").

### 17. Real content added outside the repo

> "We have also added audio files, as well as a full version of Homer's Oddysey and Illiad to the
> epic-the-musical-content directory in home."

What is in `~/epic-the-musical-content/` (1.5 GB, checked 2026-10-30):
- `Songs and Lyrics/EPIC - The <Saga> Saga (<year>)/`: all 9 sagas, **40 songs as FLAC**, **37 `.lrc`
  timed-lyrics files** (3 songs have none), plus `album.nfo` (saga blurb, fandom-wiki credited) and
  `folder.jpg` cover art. File names: `Jorge Rivera-Herrans - EPIC - The <Saga> Saga - NN - <Title>.flac|.lrc`.
- `Homers the Odyssey Book/The Odyssey.txt` and `The Illiad.txt`: Project Gutenberg #1727 and #2199,
  **Samuel Butler's prose translations** (public domain). Being prose, they have books and paragraphs,
  not line numbers, so the sample data's "Book 9, lines 105–460" references will not map onto them.

*(Claude's notes)*
- The `.lrc` files make **synced lyrics** possible: the Listen & lyrics player can highlight the
  current line, not just the current part.
- The Odyssey text makes the "real place in the Odyssey" link able to open the actual passage.
- The audio, lyrics and cover art are Jorge Rivera-Herrans' copyrighted work. AGENTS.md currently says
  "lyrics are placeholders, never real lyrics". Proposed: keep this folder **out of git and out of the
  Docker image**; the server reads it from a `CONTENT_DIR` path, mounted read-only into the container.
  Needs the user's OK (it touches `src/server.ts`, the Dockerfile and the lyrics rule).

- **User's answers (2026-10-30):** content access: **"Mount it, never commit"**; next step: **"Yes, in 17
  after 16"** (16 finishes with its simulated player, then 17 uses real FLAC playback, line-synced
  `.lrc` lyrics and the actual Odyssey passage). Implemented as spec `docs/specs/003-content-mount.md`.
- Note: Butler's translation uses Roman names (Ulysses, Minerva, Jove). Worth a line in the UI.

- **16 is finished and committed**; report in `docs/design/002-sea-chart-spikes/16-voyage-readable-report.md`.
  Preview rebuilt with 01–16 and the content folder mounted. Known: timeline at its height budget with
  3 motif rows; the panel strip still shows numbers only; ribbon labels sit on the mountain face.

### 18. Paused at the usage limit (third time)

> "Wind down current session and wait for usage limit reset."

**State (branch `feat/sea-chart-round`, not pushed, working tree clean):**
- 01–16 committed; preview at http://10.20.20.2:8099/ runs 01–16 with the content folder mounted
  (`/content/library.json`, audio with seeking, Homer books all verified 200/206; no content in the image).
- Spec 003 (content mount) implemented and committed; `docs/plans/003-content-mount.md` must be `git rm`'d
  before a merge request.
- **Not started:** 17 (real audio, line-synced `.lrc` lyrics, the actual Odyssey passage), agreed by the
  user as "Yes, in 17 after 16". No agents are running.
- The user has not yet reacted to 16.

**To resume (only on the user's go):** read this file; show the user 16
(http://10.20.20.2:8099/mockups/16-voyage-readable/) and ask for their reaction; then wire slot 17
(server route, registry, index card, count test 16→17, AGENTS/PERMISSIONS count refs, three.js note)
and brief one agent from a copy of 16, using `/content/library.json`, `parseLrc` from
`src/shared/lrc.ts` and `/content/homer/odyssey/<book>.json`. Its test server must run with
`CONTENT_DIR=/home/user/epic-the-musical-content`.

### 19. Resumed

> "Continue."

- Resumed from §18. 17 (real content) is started now, as agreed; the user's reaction to 16 is asked
  in parallel.

- **17 is finished and committed**; report in `docs/design/002-sea-chart-spikes/17-voyage-real-report.md`.
  Real FLAC playback with seeking, line-synced lyrics (click a line to seek), the Butler Odyssey passage
  in a reading view, fallback to 16 without the folder. Agent's choices: "Play voyage" stays silent (no
  excerpts, avoids near-autoplay); part buttons dropped in real mode (sample part times don't match the
  recordings). Open: passage start points are keyword guesses; parts/motifs aren't timed to the
  recordings yet (report proposes a small mapping file in the content folder).

### 20. Direction approved

*(Claude's question)* "If this is the direction, say so. I'll then write it up and build the real app
(full album, all sagas) without stopping for more reviews…"

> "Yes. But listen wit hthe lyrics and watch should probably both be in the listen & lyrics tab. Threads
> on the sea toggle works nicely. If hide timeline is off, maybe just put it into paths or something."

- **Approved:** the direction of 16/17 (look 2, frieze accents, curtain-call voyage, stylised 3D,
  side panel, bottom timeline with threads, real content) → build the real app. Per the user's global
  rule: spec → plan → execution with no extra review stops; report decisions at the end.
- **Changes on top of 17:**
  - "Listen with the lyrics" and **Watch** both live in the **Listen & lyrics** tab (not in About).
  - **"Threads on the sea"** toggle: keep as is ("works nicely").
  - When the timeline is hidden, the motif strip goes **into the Paths tab** (not pinned above the tabs).

### 21. Greek names, not Roman

> "I dont like that Samuel Butler uses Roman names instead, is there a  version with original names we
> can download on Project Gutenberg?"

- Yes. Downloaded into the content folder (Butler's files kept as a fallback):
  - `The Odyssey (Butcher and Lang).txt`: Gutenberg #1728, S. H. Butcher & Andrew Lang (1879): Odysseus,
    Athene, Poseidon, Zeus.
  - `The Iliad (Lang, Leaf and Myers).txt`: Gutenberg #3059, Lang, Leaf & Myers: same Greek names.
  - Checked by counting names: Butcher & Lang has 718× "Odysseus", 0× "Ulysses"; Pope's and Cowper's
    translations also use Roman names.
- The server now prefers these (`src/content/routes.ts`); the app drops the Roman-names note.

## Open questions (in priority order)

1. ~~Which sea-chart approach (08–11) reads best, or which mix?~~ 11's navigation + 10's style (§9).
   Then A/B/C inside plates: **A threads** (§12).
2. What is the look of the whole? Leaning strongly to look 2, with 3's cohesion (§15). Where do paths live (15's A/B/C)?
3. How do 2D and 3D relate as products? Partly answered: in 3D a right-side panel stays open with
   info, paths, lyrics and fan works (§14). Whether the chart also stands alone is unconfirmed.
3b. Fan works: what are they (art, covers, animatics?), where do they come from, and how are they
   credited? No data model for them yet.
4. Which landings are in scope for the first build? The user's examples are the Cyclops' cave, God
   Games and Ithaca.
5. Earlier, still open from 001: lyrics copyright (deferred), branching policy, linter, and what
   happens to dropped mockups.