tour-de-force-script.md
markdown
| 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. |
| 10 | |
| 11 | --- |
| 12 | |
| 13 | ## 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. |
| 43 | |
| 44 | --- |
| 45 | |
| 46 | ## 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. |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## 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. |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## 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. |
| 144 | |
| 145 | --- |
| 146 | |
| 147 | ## 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. |
| 186 | Clean. |
| 187 | |
| 188 | --- |
| 189 | |
| 190 | ## 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` |
| 222 | |
| 223 | Fast-forward. Clean. |
| 224 | |
| 225 | ### 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, |
| 267 | permanent. |
| 268 | |
| 269 | --- |
| 270 | |
| 271 | ## 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 | ### Step 32 — `muse cherry-pick` |
| 279 | |
| 280 | We grab a specific commit from the `gamma` branch — the ascending melody — |
| 281 | and apply it on top of `main`. Cherry-pick: same as Git, but the domain |
| 282 | plugin handles the content extraction and replay. |
| 283 | |
| 284 | ### Step 33 — `muse show` |
| 285 | |
| 286 | Full commit detail: hash, parent, date, changed files, delta. Every commit |
| 287 | is inspectable. |
| 288 | |
| 289 | ### Step 34 — `muse diff` |
| 290 | |
| 291 | Diff between HEAD and working state. `No differences.` Working tree is clean. |
| 292 | |
| 293 | ### Steps 35–37 — `muse stash` / `muse stash pop` |
| 294 | |
| 295 | Stash your uncommitted changes, do something, pop them back. Standard |
| 296 | workflow, full implementation. |
| 297 | |
| 298 | ### Step 38 — `muse revert` |
| 299 | |
| 300 | We undo the cherry-pick with `muse revert`. This doesn't delete the commit — |
| 301 | it creates a *new* commit whose snapshot is the inverse of the change. |
| 302 | Auditable. Reversible. Non-destructive. |
| 303 | |
| 304 | *(Point to the revert node in the DAG — melodic dimension lights up, because the revert undoes a melodic change)* |
| 305 | |
| 306 | ### Steps 39–40 — `muse tag add release:v1.0` / `muse tag list` |
| 307 | |
| 308 | Tag the final state. `release:v1.0`. Permanent named reference to this point |
| 309 | in history. |
| 310 | |
| 311 | ### Step 41 — `muse log --stat` |
| 312 | |
| 313 | Full log with file-level stats for every commit. The entire history of this |
| 314 | project — 14 commits, 6 branches, 1 real conflict, resolved — in one |
| 315 | scrollable view. |
| 316 | |
| 317 | *(Let the demo settle. Let it breathe for a second.)* |
| 318 | |
| 319 | --- |
| 320 | |
| 321 | ## DIMENSION MATRIX — Closing walkthrough (~60 s) |
| 322 | |
| 323 | *(Scroll down to the Dimension State Matrix. Let the audience take it in.)* |
| 324 | |
| 325 | This is the view I want to leave you with. |
| 326 | |
| 327 | Every column is a commit. Every row is a dimension. Every colored cell is |
| 328 | a dimension that changed in that commit. The red-bordered cell — that one |
| 329 | structural change — is the only moment in this entire session where a human |
| 330 | had to make a decision. |
| 331 | |
| 332 | *(Trace across the rows)* |
| 333 | |
| 334 | Look at the melodic row. It moves. It's active on alpha commits, on gamma |
| 335 | commits, on the cherry-pick, on the revert. A continuous creative thread. |
| 336 | |
| 337 | Look at the rhythmic row. It's its own thread. Beta's work. Completely |
| 338 | parallel. Never interfered with melody. |
| 339 | |
| 340 | Look at structural — it barely touches anything until the conflict commit. |
| 341 | Then it lights up on both sides at once. That's the red cell. That's the |
| 342 | conflict. One cell out of seventy. |
| 343 | |
| 344 | This is what multidimensional version control means. Not "track files better." |
| 345 | Track the *dimensions of your work* so that conflicts only happen when two |
| 346 | people genuinely disagree about the same thing — not because they happened |
| 347 | to edit the same file on the same day. |
| 348 | |
| 349 | --- |
| 350 | |
| 351 | ## OUTRO (~45 s) |
| 352 | |
| 353 | *(Back to camera or full screen)* |
| 354 | |
| 355 | So that's Muse. It's version zero — local-only right now, music as the |
| 356 | reference domain. But the architecture is domain-agnostic by design. |
| 357 | |
| 358 | The same five-method plugin protocol that powers the music domain can power |
| 359 | a genomics sequencer, a scientific simulation, a 3D spatial field, a neural |
| 360 | network checkpoint. If your data has structure — and it does — Muse can |
| 361 | understand it. |
| 362 | |
| 363 | What's next: **MuseHub** — the remote layer. Push, pull, and a PR interface |
| 364 | that shows you the dimension matrix for every proposed merge before you |
| 365 | accept it. The kind of diff interface that actually tells you what changed |
| 366 | and why it matters. |
| 367 | |
| 368 | If this resonated — the code is on GitHub, link in the description. Star it |
| 369 | if you want to follow along. And if you're building something with structured |
| 370 | state that deserves better version control — reach out. I'd love to talk. |
| 371 | |
| 372 | --- |
| 373 | |
| 374 | ## APPENDIX — Speaker Notes |
| 375 | |
| 376 | ### On questions you might get |
| 377 | |
| 378 | **"Why not just use Git with LFS?"** |
| 379 | Git LFS stores big files — it doesn't understand them. You still get binary |
| 380 | merge conflicts on the whole file. The dimension is the thing. |
| 381 | |
| 382 | **"What does 'domain-agnostic' actually mean?"** |
| 383 | The core engine — DAG, branches, object store, merge state machine — has |
| 384 | zero knowledge of music. It calls five methods on a plugin object. Swap the |
| 385 | plugin, get a different domain. The same commit graph, the same `muse merge`, |
| 386 | different semantics. |
| 387 | |
| 388 | **"Is this production-ready?"** |
| 389 | v0.1.1. It's a solid foundation with strict typing, CI, tests. Not production |
| 390 | for a studio yet — but the architecture is sound and the hard parts |
| 391 | (content-addressed storage, three-way merge) are working. |
| 392 | |
| 393 | **"What about performance?"** |
| 394 | The demo runs in 150ms for 14 commits and 41 operations. The bottleneck will |
| 395 | be large files, which is a known problem (handled by chunked object storage |
| 396 | in future). The merge algorithm is O(n) in the number of MIDI events per |
| 397 | dimension — fast in practice. |
| 398 | |
| 399 | ### Suggested chapter markers for YouTube |
| 400 | |
| 401 | | Timestamp | Chapter | |
| 402 | |-----------|---------| |
| 403 | | 0:00 | Intro — what is multidimensional VCS? | |
| 404 | | 1:30 | The five musical dimensions | |
| 405 | | 3:00 | Act 1 — Foundation | |
| 406 | | 5:30 | Act 2 — Three branches diverge | |
| 407 | | 9:00 | Act 3 — Clean merges | |
| 408 | | 11:30 | Act 4 — The conflict (and why it's different) | |
| 409 | | 16:00 | Act 5 — Full VCS surface area | |
| 410 | | 18:30 | Dimension Matrix walkthrough | |
| 411 | | 20:00 | Outro and what's next | |