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 -p 10.20.20.2:8099:3000 --name epic-timeline-preview epic-timeline`
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.

## Open questions (in priority order)

1. Which sea-chart approach (08–11) reads best, or which mix?
2. What is the look of the whole: frieze-led (terracotta and black), chart-led (parchment), or
   something in between? The user is "not sure" yet.
3. How do 2D and 3D relate as products? Is the 3D the main experience with the chart inside it, while
   the chart also stands alone? This is unconfirmed.
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.