Feat: continue to improve documentation

docs/forth/prelude.md

@@ -1,51 +1,78 @@
 # The Prelude
 
-When you define a word in a step, it becomes available to all steps. But when you close and reopen the project, the dictionary is empty again. Words defined in steps only exist after those steps run.
+You can define words in any step and they become available to all other steps. But as a project grows, definitions get scattered across steps and become hard to find and maintain. The **prelude** is a dedicated place for this. It is a project-wide Forth script that runs once before the first step plays. Definitions, variables, settings — everything in one place. Press `d` to open the prelude editor. Press `Esc` to save and close. Press `D` (Shift+d) to re-evaluate it without opening the editor.
 
-The **prelude** solves this. It's a project-wide script that runs automatically when playback starts and when you load a project.
+## Naming Your Sounds
 
-## Accessing the Prelude
-
-Press `d` to open the prelude editor. Press `Esc` to save and evaluate. Press `D` (Shift+d) to re-evaluate the prelude without opening the editor.
-
-## What It's For
-
-Define words that should be available everywhere, always:
+The most common use of the prelude is to define words for your instruments. Without a prelude, every step that plays a bass has to spell out the full sound design or to create a new word before using it:
 
 ```forth
-: kick "kick" s 0.9 gain . ;
-: hat "hat" s 0.4 gain . ;
-: bass "saw" s 0.7 gain 200 lpf . ;
+pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width .
 ```
 
-Now every step in your project can use `kick`, `hat`, and `bass` from the first beat.
+Repeat this across eight steps without making a new word and you have eight copies of the same thing. Change the filter? Change it eight times.
+
+In the prelude, define it once:
+
+```forth
+: bass pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width . ;
+```
+
+Now every step just writes `c2 note bass`. Change the sound in one place, every step follows.
+
+A step that used to read:
+
+```forth
+pulse sound c2 note 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width .
+```
+
+Becomes:
+
+```forth
+c2 note bass
+```
+
+## Building a Vocabulary
+
+The prelude is where you build the vocabulary for your music. Not just instruments but any combination of code / words you want to reuse:
+
+```forth
+;; instruments
+: bass pulse sound 0.8 gain 400 lpf 1 lpd 8 lpe 0.6 width . ;
+: pad sine sound 0.5 gain 2 spread 1.5 attack 0.4 verb . ;
+: lead tri sound 0.6 gain 5000 lpf 2 decay . ;
+
+;; musical helpers
+: octup 12 + ;
+: octdn 12 - ;
+: quiet 0.3 gain ;
+: loud 0.9 gain ;
+```
+
+By using the prelude and predefined words, steps become expressive and short. The prelude carries the design decisions; steps carry the composition.
+
+## Setting Initial State
+
+The prelude also runs plain Forth, not just definitions. You can use it to set variables and seed the random generator:
+
+```forth
+c2 !root
+0 !mode
+42 seed
+```
+
+Every step can then read `@root` and `@mode`. And `42 seed` makes randomness reproducible — same seed, same sequence every time you hit play.
 
 ## When It Runs
 
-The prelude evaluates:
+The prelude evaluates at three moments:
 
-1. When you press Space to start playback (if stopped)
-2. When you load a project
-3. When you press `D` manually
+1. When you press **Space** to start playback
+2. When you **load** a project
+3. When you press **D** manually
 
-It does not run on every step, only once at these moments. This makes it ideal for setup code: word definitions, initial variable values, seed resets.
+It runs once at these moments, not on every step. This makes it the right place for definitions and initial values. If you edit the prelude while playing, press `D` to push changes into the running session. New definitions take effect immediately; the next time a step runs, it sees the updated words.
 
-## Practical Example
+## What Not to Put Here
 
-A prelude for a techno project:
-
-```forth
-: k "kick" s 1.2 attack . ;
-: sn "snare" s 0.6 gain 0.02 attack . ;
-: hh "hat" s 0.3 gain 8000 hpf . ;
-: sub "sine" s 0.8 gain 150 lpf . ;
-0 seed
-```
-
-Step scripts become trivial:
-
-```forth
-c1 note k sub
-```
-
-The sound design lives in the prelude. Steps focus on rhythm and melody.
+The prelude has no access to sequencer state. Words like `step`, `beat`, `iter`, and `phase` are meaningless here because no step is playing yet. Use the prelude for definitions and setup, not for logic that depends on timing. The prelude also should not emit sounds. It runs silently — any `.` calls here would fire before the sequencer clock is running and produce nothing useful.