docs/demo/tour-de-force-script.md · cgcardona/muse

1

# Muse Tour de Force — Video Narration Script

2

3

> **Format:** YouTube walkthrough of the Tour de Force interactive demo.

4

> Open `artifacts/tour_de_force.html` before recording. Click **Play Tour**

5

> and let the demo advance step by step while you narrate. Timestamps are

6

> approximate at 1.2 s/step; adjust to your natural pace.

7

>

8

> **Tone:** conversational, curious, a little excited — like showing a friend

9

> something you built that you genuinely believe in.

---

## INTRO — Before clicking anything (~90 s)

14

15

*(Camera on screen, demo paused at step 0)*

16

17

Hey — so I want to show you something I've been building called **Muse**.

18

19

The elevator pitch: Muse is a version control system for multidimensional

20

state. Think Git, but instead of treating a file as the smallest thing you

21

can reason about, Muse understands the *internal structure* of your files —

22

and that changes everything about what a conflict means.

23

24

To make this concrete I'm going to use music, because music is a perfect

25

example of something that *looks* like a file but is actually several

26

completely independent things layered on top of each other.

27

28

Take a MIDI file. On disk it's one blob of bytes. But inside it there are at

29

least five things that have nothing to do with each other:

30

31

- **Melodic** — the notes being played, the pitch and duration of each one

32

- **Rhythmic** — when those notes land in time, the groove, the syncopation

33

- **Harmonic** — chord voicings, key changes, the tonal color

34

- **Dynamic** — velocity, expression, how hard or soft each note hits

35

- **Structural** — tempo, time signature, the skeleton the rest hangs on

36

37

These are orthogonal axes. A drummer and a pianist can edit the same MIDI

38

file — one touching only the rhythmic dimension, the other only the harmonic

39

— and there is *no conflict*. They didn't touch the same thing. Git would

40

flag the whole file. Muse resolves it in silence.

41

42

That's the idea. Let me show you the demo.

---

## HEADER — Reading the stats (~20 s)

47

48

*(Point to the stats bar: 14 commits · 6 branches · 1 merge · 1 conflict resolved · 41 operations)*

49

50

Everything you're about to see ran against a real Muse repository — real

51

commits, real branches, real SHA-256 content hashes. The whole demo took

52

about 150 milliseconds to execute.

53

54

Fourteen commits. Six branches. One merge conflict. All resolved. Let's

55

walk through how we got here.

---

## ACT 1 — Foundation (Steps 1–5)

60

61

*(Click Play Tour — steps 1–5 advance. Pause after step 5.)*

62

63

### Step 1 — `muse init`

64

65

We start with an empty directory. `muse init` creates the `.muse/` folder —

66

the repository root. Content-addressed object store, branch metadata, config

67

file. Same idea as `git init`, but designed from scratch to be domain-agnostic.

68

69

### Step 2 — `muse commit -m "Root: initial state snapshot"`

70

71

This is the first commit. Notice in the dimension matrix at the bottom —

72

every single dimension lights up on this first commit. Melodic, rhythmic,

73

harmonic, dynamic, structural — all five. Because this is the root: we're

74

establishing the baseline state for every dimension simultaneously.

75

76

Under the hood, Muse called `MusicPlugin.snapshot()` — which walked the

77

working directory, hashed every MIDI file with SHA-256, and returned a

78

content-addressed manifest. That manifest is what got committed to the DAG.

79

80

### Step 3 — `muse commit -m "Layer 1: add rhythmic dimension"`

81

82

Now we add a layer. Look at the dimension matrix: only **rhythmic** and

83

**structural** light up. Rhythmic because we're adding a new rhythmic layer

84

file. Structural because adding a file changes the shape of the snapshot.

85

The melodic, harmonic, and dynamic dimensions? Untouched. Muse sees that.

86

87

### Step 4 — `muse commit -m "Layer 2: add harmonic dimension"`

88

89

Same pattern — **harmonic** and **structural** light up. We're adding a

90

harmonic layer. The rhythmic work from the previous commit is preserved

91

exactly as-is. These are independent operations on independent dimensions.

92

93

### Step 5 — `muse log --oneline`

94

95

Quick sanity check. Three commits, linear history, on `main`. This is your

96

foundation — the musical canvas everyone will branch from.

---

## ACT 2 — Divergence (Steps 6–16)

101

102

*(Resume Play Tour — steps 6–16. Pause after step 16.)*

103

104

*(Point to the DAG as branches appear)*

105

106

This is where it gets interesting. We're going to branch the repository three

107

ways simultaneously — three different creative directions diverging from the

108

same base.

109

110

### Steps 6–8 — Branch `alpha`

111

112

`muse checkout -b alpha` creates a new branch. We commit two texture patterns:

113

114

- **"Alpha: texture pattern A (sparse)"** — melodic and rhythmic dimensions.

115

A sparse arrangement: few notes, lots of space.

116

- **"Alpha: texture pattern B (dense)"** — melodic and dynamic dimensions.

117

The dense version: more notes, more expression.

118

119

Watch the dimension dots on the DAG nodes — each commit shows exactly which

120

dimensions it touched. Alpha is doing melodic work.

121

122

### Steps 9–11 — Branch `beta`

123

124

Back to `main`, then `muse checkout -b beta`. One commit:

125

126

- **"Beta: syncopated rhythm pattern"** — rhythmic and dynamic dimensions.

127

128

Beta is a completely different musical idea. It's not touching melody at all —

129

it's a rhythm section, working in its own lane. Rhythmic and dynamic only.

130

131

### Steps 12–15 — Branch `gamma`

132

133

Back to `main`, then `muse checkout -b gamma`. Two commits:

134

135

- **"Gamma: ascending melody A"** — pure melodic dimension.

136

- **"Gamma: descending melody B"** — melodic and harmonic. The descending

137

line implies a harmonic movement, so two dimensions change.

138

139

### Step 16 — `muse log --oneline`

140

141

Three parallel stories. Alpha is building texture. Beta is building rhythm.

142

Gamma is building melody. None of them know about each other. The DAG is

143

starting to look like a real project.

---

## ACT 3 — Clean Merges (Steps 17–21)

148

149

*(Resume Play Tour — steps 17–21. Pause after step 21.)*

150

151

Now we bring it together. This is the part that's usually painful in Git.

152

In Muse, it's going to be boring — which is the point.

153

154

### Steps 17–18 — Merge `alpha` → `main`

155

156

`muse checkout main`, then `muse merge alpha`. The output says:

157

`Fast-forward to cb4afaed`.

158

159

Alpha was strictly ahead of main — no divergence. Fast-forward. Zero conflict.

160

161

### Step 19 — `muse status`

162

163

`Nothing to commit, working tree clean.` Main now has all of alpha's work.

164

165

### Step 20 — Merge `beta` → `main`

166

167

`muse merge beta`. This one creates a real merge commit —

168

`Merged 'beta' into 'main'`.

169

170

Here's what happened under the hood: Muse found the common ancestor (the

171

`Layer 2` commit), computed the three-way delta, and asked: did the same

172

dimension change on both sides?

173

174

- Alpha touched **melodic** and **dynamic**.

175

- Beta touched **rhythmic** and **dynamic**.

176

- Dynamic changed on *both sides*.

177

178

In Git: `CONFLICT`. In Muse: the dynamic changes are on different files, so

179

the union is clean. Merge commit. No human intervention. Done.

180

181

*(Point to the merge commit node in the DAG — it has the double-ring that marks it as a merge)*

182

183

### Step 21 — `muse log --oneline`

184

185

The DAG shows the merge. Main now contains the work of three contributors.

Clean.

---

## ACT 4 — Conflict & Resolution (Steps 22–31)

191

192

*(Resume Play Tour — steps 22–31. Pause after step 31.)*

193

194

*(Lean in a little — this is the money shot)*

195

196

Now we're going to manufacture a real conflict. Two branches are going to

197

modify the *same file* on the *same dimension*. This is where Muse shows

198

what makes it different.

199

200

### Steps 22–23 — Branch `conflict/left`

201

202

`muse checkout -b conflict/left`. Commit: **"Left: introduce shared state

203

(version A)"**.

204

205

This branch adds `shared-state.mid` and edits it with a **melodic** approach

206

and a **structural** change.

207

208

### Steps 24–26 — Branch `conflict/right`

209

210

Back to main, then `muse checkout -b conflict/right`. Commit: **"Right:

211

introduce shared state (version B)"**.

212

213

This branch adds its own version of `shared-state.mid` with a **harmonic**

214

approach and also a **structural** change.

215

216

*(Point to dimension matrix — both conflict/left and conflict/right columns)*

217

218

Look at the dimension matrix. Left touched melodic + structural. Right touched

219

harmonic + structural. **Structural appears on both sides.** That's the conflict.

220

221

### Steps 27–28 — Merge `conflict/left`

Fast-forward. Clean.

### Step 29 — Merge `conflict/right`

226

227

```

228

❌ Merge conflict in 1 file(s):

229

CONFLICT (both modified): shared-state.mid

230

```

231

232

Here it is. Now — in Git, you'd open the file, see angle-bracket markers,

233

and try to figure out what "their" version of a binary MIDI file even means.

234

Good luck.

235

236

In Muse, the merge engine already knows *which dimensions* conflicted.

237

It ran `MusicPlugin.merge()` with `repo_root` set, which:

238

239

1. Loaded `.museattributes` to check for strategy rules

240

2. Called `merge_midi_dimensions()` on `shared-state.mid`

241

3. Extracted the five dimension slices from base, left, and right

242

4. Compared them: melodic only changed on the left. Harmonic only changed on

243

the right. Structural changed on **both**.

244

5. Auto-merged melodic from left. Auto-merged harmonic from right.

245

6. Flagged structural as the one dimension that needs a human decision.

246

247

*(Point to the red-bordered structural cell in the dimension matrix for that commit)*

248

249

**One dimension conflicted. Four resolved automatically.** Git would have

250

thrown the entire file at you.

251

252

### Step 30 — Resolve and commit

253

254

The human makes a decision on the structural dimension and commits:

255

`"Resolve: integrate shared-state (A+B reconciled)"`.

256

257

Look at the dimension matrix for this commit — only **structural** lights up.

258

That's the exact scope of what was resolved. The merge result carries

259

`applied_strategies` and `dimension_reports` that document exactly which

260

dimension was manually resolved and which were auto-merged.

261

262

### Step 31 — `muse status`

263

264

`Nothing to commit, working tree clean.`

265

266

The conflict is history. Literally — it's in the DAG, attributed, auditable,

permanent.

---

## ACT 5 — Advanced Operations (Steps 32–41)

272

273

*(Resume Play Tour — steps 32–41. Let it play to completion.)*

274

275

The last act shows that Muse has the full surface area you'd expect from a

276

modern VCS.

277

278

### Steps 32–38 — The audition arc *(pause here and explain this slowly)*

279

280

This sequence is subtle but it's one of the most important things Muse

281

demonstrates. Watch what happens.

282

283

`muse cherry-pick` — we grab the *ascending melody* commit from the `gamma`

284

branch and replay it on top of `main`. This is an **audition**. We're not

285

merging gamma — we're borrowing one idea and trying it on.

286

287

Notice: this cherry-pick has no structural connection to gamma in the DAG.

288

It's a content copy — a new commit with a new hash, parented to main's HEAD.

289

Gamma doesn't know it happened. The two commits are not linked by an edge.

290

291

*(Brief pause — let the cherry-pick commit appear in the DAG)*

292

293

`muse show` — we inspect what actually changed. `muse diff` — working tree

294

is clean. The idea is in. Now we listen.

295

296

`muse stash`, `muse stash pop` — showing you can shelve unfinished work

297

mid-session without losing anything. Bread and butter.

298

299

Now — `muse revert`. The ascending melody doesn't fit. We undo it.

300

301

*(Point to the revert commit in the DAG — pause)*

302

303

This is the moment. Look at what just happened in the DAG: there are now

304

**two** commits sitting between the resolve and the tag. One that says

305

"here's the melody." One that says "never mind." Both are permanent. Both

306

are in the history forever.

307

308

That's not a mistake — that's the *point*. Six months from now, when someone

309

asks "did we ever try a melody in this section?" the answer is in the DAG:

310

yes, on this date, here's exactly what it was, and here's the explicit

311

decision to reject it. You can check it out, listen to it, and put it back

312

if you change your mind.

313

314

The `descending melody B` commit on gamma? It's still there too — never

315

used, never merged, never deleted. Muse doesn't garbage-collect ideas. The

316

entire creative history of the project — including the roads not taken — is

317

preserved.

318

319

*(Let that land before moving on)*

320

321

### Steps 39–40 — `muse tag add release:v1.0` / `muse tag list`

322

323

Tag the final state. `release:v1.0`. Permanent named reference to this point

324

in history.

325

326

### Step 41 — `muse log --stat`

327

328

Full log with file-level stats for every commit. The entire history of this

329

project — 14 commits, 6 branches, 1 real conflict, resolved — in one

330

scrollable view.

331

332

*(Let the demo settle. Let it breathe for a second.)*

---

## DIMENSION MATRIX — Closing walkthrough (~60 s)

337

338

*(Scroll down to the Dimension State Matrix. Let the audience take it in.)*

339

340

This is the view I want to leave you with.

341

342

Every column is a commit. Every row is a dimension. Every colored cell is

343

a dimension that changed in that commit. The red-bordered cell — that one

344

structural change — is the only moment in this entire session where a human

345

had to make a decision.

346

347

*(Trace across the rows)*

348

349

Look at the melodic row. It moves. It's active on alpha commits, on gamma

350

commits, on the cherry-pick, on the revert. A continuous creative thread.

351

352

Look at the rhythmic row. It's its own thread. Beta's work. Completely

353

parallel. Never interfered with melody.

354

355

Look at structural — it barely touches anything until the conflict commit.

356

Then it lights up on both sides at once. That's the red cell. That's the

357

conflict. One cell out of seventy.

358

359

This is what multidimensional version control means. Not "track files better."

360

Track the *dimensions of your work* so that conflicts only happen when two

361

people genuinely disagree about the same thing — not because they happened

362

to edit the same file on the same day.

---

## OUTRO (~45 s)

*(Back to camera or full screen)*

369

370

So that's Muse. It's version zero — local-only right now, music as the

371

reference domain. But the architecture is domain-agnostic by design.

372

373

The same five-method plugin protocol that powers the music domain can power

374

a genomics sequencer, a scientific simulation, a 3D spatial field, a neural

375

network checkpoint. If your data has structure — and it does — Muse can

376

understand it.

377

378

What's next: **MuseHub** — the remote layer. Push, pull, and a PR interface

379

that shows you the dimension matrix for every proposed merge before you

380

accept it. The kind of diff interface that actually tells you what changed

381

and why it matters.

382

383

If this resonated — the code is on GitHub, link in the description. Star it

384

if you want to follow along. And if you're building something with structured

385

state that deserves better version control — reach out. I'd love to talk.

---

## APPENDIX — Speaker Notes

390

391

### On questions you might get

392

393

**"Why not just use Git with LFS?"**

394

Git LFS stores big files — it doesn't understand them. You still get binary

395

merge conflicts on the whole file. The dimension is the thing.

396

397

**"What does 'domain-agnostic' actually mean?"**

398

The core engine — DAG, branches, object store, merge state machine — has

399

zero knowledge of music. It calls five methods on a plugin object. Swap the

400

plugin, get a different domain. The same commit graph, the same `muse merge`,

401

different semantics.

402

403

**"Is this production-ready?"**

404

v0.1.1. It's a solid foundation with strict typing, CI, tests. Not production

405

for a studio yet — but the architecture is sound and the hard parts

406

(content-addressed storage, three-way merge) are working.

407

408

**"What about performance?"**

409

The demo runs in 150ms for 14 commits and 41 operations. The bottleneck will

410

be large files, which is a known problem (handled by chunked object storage

411

in future). The merge algorithm is O(n) in the number of MIDI events per

412

dimension — fast in practice.

413

414

### Suggested chapter markers for YouTube

415

416

| Timestamp | Chapter |

417

|-----------|---------|

418

| 0:00 | Intro — what is multidimensional VCS? |

419

| 1:30 | The five musical dimensions |

420

| 3:00 | Act 1 — Foundation |

421

| 5:30 | Act 2 — Three branches diverge |

422

| 9:00 | Act 3 — Clean merges |

423

| 11:30 | Act 4 — The conflict (and why it's different) |

424

| 16:00 | Act 5 — Full VCS surface area |

425

| 18:30 | Dimension Matrix walkthrough |

426

| 20:00 | Outro and what's next |