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.
- **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.

## 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: 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.