Feat: documentation, UI/UX

docs/tutorials/periodic_script.md

@@ -0,0 +1,43 @@
+# The Periodic Script
+
+The periodic script is a hidden seventh view accessible with `F11`. It is a Forth script that runs continuously alongside your patterns, evaluated at every step like a pattern would be. Think of it as a free-running pattern with no grid — just code.
+
+## What is it for?
+
+The periodic script is useful for things that don't belong to any specific pattern:
+
+- **Global effects**: apply a filter sweep or reverb tail across everything.
+- **Drones**: run a sustained sound that keeps going regardless of which patterns are playing.
+- **Control logic**: update variables, send MIDI clock, or modulate global parameters.
+- **Experimentation**: sketch ideas without touching your pattern grid.
+
+## Opening the Script
+
+Press `F11` from any view. The script page appears with an editor on the left and visualizations on the right (scope, spectrum, prelude preview). The script is saved with your project.
+
+## Editing
+
+Press `Enter` to focus the editor. Write Forth code as you would in any step. Press `Esc` to unfocus and save. Press `Ctrl+E` to evaluate without unfocusing.
+
+```forth
+;; a simple drone
+saw s c2 note 0.3 gain 0.4 verb .
+```
+
+## Speed and Length
+
+The periodic script has its own speed and length settings, independent of any pattern. Press `S` (unfocused) to set the speed and `L` to set the length (1-256 steps). Speed and length are displayed in the editor title bar.
+
+The script loops over its length just like a pattern. Context words like `step`, `iter`, and `phase` work as expected, counting within the script's own cycle.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `F11` | Open periodic script view |
+| `Enter` | Focus editor |
+| `Esc` | Unfocus and save |
+| `Ctrl+E` | Evaluate |
+| `Ctrl+S` | Toggle stack display |
+| `S` | Set speed (unfocused) |
+| `L` | Set length (unfocused) |

docs/tutorials/randomness.md

@@ -94,37 +94,6 @@ Kick plays 50% of the time, snare 30%, hat 20%. Weights don't need to sum to 1 -
 
 Combined with `note`, this gives you a random permutation of a chord every time the step runs.
 
-## Cycling
-
-Cycling steps through values deterministically. No randomness -- pure rotation.
-
-`cycle` selects based on how many times this step has played (its `runs` count):
-
-```forth
-60 64 67 3 cycle note sine s .    ;; 60, 64, 67, 60, 64, 67, ...
-```
-
-`pcycle` selects based on the pattern iteration count (`iter`):
-
-```forth
-kick snare 2 pcycle s .    ;; kick on even iterations, snare on odd
-```
-
-The difference matters when patterns have different lengths. `cycle` counts per-step, `pcycle` counts per-pattern.
-
-Quotations work here too:
-
-```forth
-( c4 note ) ( e4 note ) ( g4 note ) 3 cycle
-sine s .
-```
-
-`bounce` ping-pongs instead of wrapping around:
-
-```forth
-60 64 67 72 4 bounce note sine s .    ;; 60, 64, 67, 72, 67, 64, 60, 64, ...
-```
-
 ## Periodic Execution
 
 `every` runs a quotation once every n pattern iterations:
@@ -139,6 +108,20 @@ sine s .
 ( 2 distort ) 4 except    ;; distort on all iterations except every 4th
 ```
 
+`every+` and `except+` take an extra offset argument to shift the phase:
+
+```forth
+( snare s . ) 4 2 every+     ;; fires at iter 2, 6, 10, 14...
+( snare s . ) 4 2 except+    ;; skips at iter 2, 6, 10, 14...
+```
+
+Without the offset, `every` fires at 0, 4, 8... The offset shifts that by 2, so it fires at 2, 6, 10... This lets you interleave patterns that share the same period:
+
+```forth
+( kick s . ) 4 every         ;; kick at 0, 4, 8...
+( snare s . ) 4 2 every+     ;; snare at 2, 6, 10...
+```
+
 `bjork` and `pbjork` use Bjorklund's algorithm to distribute k hits across n positions as evenly as possible. Classic Euclidean rhythms:
 
 ```forth