Working on internal documentation

docs/editing.md

@@ -0,0 +1,62 @@
+# Editing a Step
+
+Each step in Cagire contains a Forth script. When the sequencer reaches that step, it runs the script to produce sound. This is where you write your music. Press `Enter` when hovering over any step to open the `code editor`. The editor appears as a modal overlay with the step number in the title bar. If the step is a linked step (shown with an arrow like `→05`), pressing `Enter` navigates to the source step instead.
+
+## Writing Scripts
+
+Scripts are written in Forth. Type words and numbers separated by spaces. The simplest script that makes sound is:
+
+```forth
+sine sound .
+```
+
+Add parameters before words to modify them:
+
+```forth
+c4 note 0.75 decay sine sound .
+```
+
+Writing long lines is not recommended because it can become quite unmanageable. Instead, break them into multiple lines for clarity:
+
+```forth
+c4 note
+0.75 decay
+sine sound
+0.4 verb
+.
+```
+
+## Saving
+
+- `Esc` - Save and close the editor
+- `Ctrl+E` - Save without closing
+
+When you save, the script is compiled and sent to the sequencer. If there's an error, a message appears briefly at the bottom of the screen. You will also receive visual feedback in the form of a flashing window when saving / evaluating a script.
+
+## Completion
+
+As you type, the editor suggests matching Forth words. The completion list shows all built-in words that start with your current input. Press `Tab` to insert the selected suggestion, or `Esc` to dismiss the list. Use arrow keys to navigate between suggestions.
+
+Completion helps you discover words without memorizing them all. Type a few letters and browse what's available. For example, typing `ver` will suggest `verb` (reverb), typing `fil` will show filter-related words.
+
+## Debugging
+
+Press `Ctrl+S` to toggle the stack display. This shows the stack state evaluated up to the cursor line, useful for understanding how values flow through your script. Press `Ctrl+R` to execute the script immediately without waiting for the sequencer to reach the step.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Save and close |
+| `Ctrl+E` | Save without closing |
+| `Ctrl+R` | Execute script once |
+| `Ctrl+S` | Toggle stack display |
+| `Ctrl+F` | Search |
+| `Ctrl+N` | Find next |
+| `Ctrl+P` | Find previous |
+| `Ctrl+A` | Select all |
+| `Ctrl+C` | Copy |
+| `Ctrl+X` | Cut |
+| `Ctrl+V` | Paste |
+| `Shift+Arrows` | Extend selection |
+| `Tab` | Accept completion |