SkyTales Lesson Grammar — Guided Motion Over Live Instruments

Fourth document of the stack: BRAND.md (vocabulary), ANTIPATTERNS.md (what to refuse), THREEJS.md (how the engine is configured), this file (how a sim teaches). Paste it into any session that builds or edits a lesson, tutorial, or guided tour.

The founding observation: video serializes with the author’s voice on the author’s clock. SkyTales serializes with motion over an instrument that never stops working, on the user’s clock. The lesson guides attention. It never guards access. This is the structural advantage over film, and every rule below exists to protect it.

What we trade away, knowingly: film’s total control of pacing and attention. A viewer can sabotage a SkyTales lesson. That is not a defect to patch; it is the price of the medium and, handled correctly, its content.

1. The prime directive

A lesson is an overlay, never a mode. Every control works before, during, and after the lesson. If starting the lesson disables a single slider, the lesson is broken. The instrument never stops being an instrument.

2. Entry

Straight in. The sim loads live, at a curated default state: mid-range values chosen so the scene is already interesting and the first drag produces a visible consequence. Never all zeros, never empty.
No autoplay, no forced tour, no modal, no intro animation (instruments don’t do intros, per THREEJS.md).
One quiet Play affordance in the chrome. The lesson is replayable at any time, from any state, and running it twice from any state must work.

3. The jumpmaster

The guiding presence is a jumpmaster: it jumps with the student, demonstrates by doing, and the student is flying the entire time.

It shows by acting on the scene: building the space, scaling the vectors, flying the camera, drawing the path.
It never takes a control away. User input on any channel wins that channel instantly.
The camera may be flown by the lesson; a user grab kills the lesson’s camera track for that beat, and the lesson continues on its other channels.
It never resets the user’s state. Values the user set are values the lesson works with.

4. Live narration: the lesson reads the state

Every value, equation, and sentence in the lesson is a function of the current state, evaluated at display time. Baked constants in narration are banned.
Narration entries are closures returning strings, not strings. KaTeX renders at beat time with the values of that moment.
Consequence: the user can change a parameter mid-sentence and the sentence is about their parameter. The lesson cannot desync from the sim, because it is the sim, narrated.

5. Sabotage is sanctioned

Acceptance test for every lesson: run it while dragging every slider to its extremes. The lesson must remain coherent, its equations true, its demonstrations correct for the sabotaged values. If any beat breaks, contradicts the screen, or produces nonsense, that beat is a bug.
The demonstration is computed, not replayed, so it cannot be wrong; it can only be re-parameterized. Design beats so that this holds.

6. Serialization

One beat, one subject. A beat is: a statement (one sentence), a demonstration (motion in the scene), and an open invitation (the controls are already live; say nothing about it).
Depth folds away. Derivations, edge cases, and the extra-curious material live in the EQUATIONS drawer or behind an explicit fold. The phenomenon stays in front; the proof is the debrief.
Experience before derivation wherever possible. Let the user witness the fact, then explain why it had to be true. The derivation of a thing already felt lands; the derivation of a thing not yet seen is homework.

7. Motion

Entrances fall in along −y and decelerate on the house curve (skyFall, normalized tanh: fast, then flaring out to terminal). Camera moves use symmetric smoothing. Scene-to-scene camera transitions descend.
All motion is Δt-based per THREEJS.md. Expose a single timeScale for pacing.
prefers-reduced-motion: the lesson degrades to stepped text plus instant state changes. It still teaches; it stops performing.

8. Narration surface

Subtitles render bottom-center over the sim: text on the void with a strong text shadow, no card, no panel, no dimming of the scene behind them.
Ubuntu for prose, KaTeX inline for any math, at reading size (1.25rem minimum desktop). One sentence per beat.
Verdict colors may punctuate a beat’s conclusion: green when the demonstrated claim lands, red when the lesson deliberately breaks something. Same meanings as everywhere else; a lesson gets no private vocabulary.

9. The dive plan

A lesson is data: a storyboard of steps { t, target, action, params, duration, ease } interpreted by the shared runtime, stored in the repo next to its sim, versioned like code.
Anywhere a value appears in narration or params, it is a function of state, per section 4.
The dive plan is rehearsed on the ground and survives contact with the user. If the plan can only succeed from the default state, it is not a plan.

10. Chapters

A lesson is a set of short chapters, not a feature. Video is forced into length because production cost amortizes over one artifact; here the amortized asset is the sim itself, and a chapter only choreographs what is already built. Chapters stay cheap, and cheap ships.

A chapter is 30 to 90 seconds of storyboard. Past roughly three minutes, split it.
Chapter contract: establish (under two seconds of visual build-state: opacities, lerps, camera; never user values), teach (one idea, per the beat rules), release (chrome returns to live defaults, the sim keeps running, and the silence after is the invitation to touch).
Any chapter plays from any state, including states left by other chapters or by the user. The establish step is what buys this independence.
All chapters of a sim live in its one monolith, registered on a single runtime. Play-all is concatenation of chapters, not a separate artifact.
Chapters ship incrementally. A sim with one good chapter ships today; more chapters land later without touching the sim. Never hold a sim hostage to an unfinished curriculum.
Chapter list UI: quiet mono labels with durations, one tap to play, replay always. No progress bars, no checkmarks, no locked chapters, no “course” framing.

11. Exercises and the logbook

A chapter may end with a challenge. The challenge is the fourth part of the contract, after release: the sim is live, and one sentence on the narration surface names a state to reach.

The answer is flown, not picked. No multiple choice, no answer boxes as default. The challenge names a target state; the sliders and the scene are the answer sheet. The sim verifies its own state, within a stated tolerance.
Verdicts do their real job here. Green when the state is reached, red when a committed prediction fails. Verdict copy is dry and mono: the value, then one word. Instruments don’t cheer.
Predict-then-verify is the strongest form: ask for a committed number or direction before the sim reveals it. Commitment is what makes red sting and green land. This is the medium’s answer to the viewer who is never wrong.
The logbook is the scoreboard, and it is verbal. Local, no account: dry entries with sim, feat, and date. Facts, never points. Aggregation is a countable claim (“23 exercises signed across 6 sims”), never a level, streak, or league.
Exercises mint sentences. Write each challenge so its completion line is something a person would say out loud to another person. The completion line, the logbook entry, and the share text are the same sentence.
Every state is a link. Slider state encodes into the URL; one quiet copy-link affordance. A claim travels with reproduction attached.

12. Banned

Modal wizards, Next buttons, numbered coach marks with arrows pointing at the UI.
Locking, disabling, or hiding controls during a lesson.
Dimming or blurring the sim behind a tutorial card.
Baked values in narration.
Autoplaying lessons and forced entry tours.
Resetting user state as a side effect of starting or ending a lesson.
Lessons that only work from the default state.
One continuous lesson where chapters would do. Past a few minutes of storyboard, it is a film, and films belong on YouTube.
The retention casino: XP, streaks, leagues, badges, daily goals, progress rings, celebratory confetti.
Multiple choice as the default exercise form, and any “Correct!” that cheers instead of states.

The one-paragraph version

The sim is live when you arrive, live while it teaches, live after it finishes. A lesson is a jumpmaster: it demonstrates on the real instrument, narrates with the real values, flies the camera until you grab it, and never once takes your hand off the controls. You can wreck its demonstration, and because the demonstration is computed rather than recorded, wrecking it just gives you a different true demonstration. One beat, one subject, depth behind a fold, derivation after experience. Lessons ship as short chapters in the same file, each a complete jump on its own, and a sim never waits for its curriculum. Film controls attention absolutely and pays for it with a dead artifact; SkyTales gives up that control and gets a living one.