Work on documentation

docs/engine_distortion.md

@@ -0,0 +1,65 @@
+# Distortion
+
+Distortion effects add harmonics by nonlinearly shaping the waveform.
+
+## Saturation
+
+Soft saturation using the transfer function `x / (1 + k|x|)`.
+
+```forth
+saw 2 distort .
+saw 8 distort 0.5 distortvol .   ( with volume compensation )
+```
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `distort` | 0+ | Saturation amount |
+| `distortvol` | 0-1 | Output volume |
+
+## Wavefolding
+
+Wavefolding reflects the signal when it exceeds ±1, using `sin(x × amount × π/2)`.
+
+```forth
+sine 4 fold .
+```
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `fold` | 0+ | Fold amount |
+
+## Wavewrapping
+
+Wavewrapping applies modulo to wrap the signal into the -1 to 1 range.
+
+```forth
+saw 3 wrap .
+```
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `wrap` | 0+ | Number of wraps |
+
+## Bit Crushing
+
+Bit crushing quantizes the signal to fewer amplitude levels.
+
+```forth
+snare 6 crush .              ( 6-bit = 32 levels )
+```
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `crush` | 1-16 | Bit depth |
+
+## Sample Rate Reduction
+
+Sample rate reduction holds each sample for multiple output samples.
+
+```forth
+hat 4 coarse .               ( 1/4 effective sample rate )
+```
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+| `coarse` | 1+ | Reduction factor (1 = bypass) |