Feat: refactoring codebase

docs/getting-started/staging.md

@@ -0,0 +1,50 @@
+# Stage / Commit
+
+Cagire requires you to `stage` changes you wish to make to the playback state and then `commit` it. It is way more simple than it seems. For instance, you mark pattern `04` and `05` to start playing, and _then_ you send the order to start the playback (`commit`). The same goes for stopping patterns. You mark which pattern to stop (`stage`) and then you give the order to stop them (`commit`). Why is staging useful? Here are some reasons why this design choice was made:
+
+- **To apply multiple changes**: Queue several patterns to start/stop, commit them together.
+- **To get clean timing**: All changes happen on beat/bar boundaries.
+- **To help with live performance**: Prepare the next section without affecting current playback.
+
+Staging is an essential feature to understand to be effective when doing live performances:
+
+1. Open the **Patterns** view (`Ctrl+Up` from sequencer)
+2. Navigate to a pattern you wish to change/play
+3. Press `Space` to stage it. The pending change is going to be displayed:
+   - `+` (staged to play) 
+   - `-` (staged to stop)
+4. Repeat for other patterns you want to change
+5. Press `c` to commit all changes
+6. Or press `Esc` to cancel
+
+A pattern might not start immediately depending on the sync mode you have chosen. It might wait for the next beat/bar boundary.
+
+## Status Indicators
+
+| Indicator | Meaning |
+|-----------|---------|
+| `>` | Currently playing |
+| `+` | Staged to play |
+| `-` | Staged to stop |
+
+A pattern can show both `>` (playing) and `-` (staged to stop).
+
+## Quantization
+
+Committed changes don't execute immediately. They wait for a quantization boundary:
+
+| Setting | Behavior |
+|---------|----------|
+| Immediate | Next sequencer tick |
+| Beat | Next beat |
+| 1 Bar | Next bar (default) |
+| 2/4/8 Bars | Next 2, 4, or 8-bar boundary |
+
+Edit quantization in pattern properties (press `e` on a pattern).
+
+## Sync Mode
+
+When a pattern starts, its playback position depends on sync mode:
+
+- **Reset**: Always start at step 0
+- **Phase-Lock**: Start at the current beat-aligned position (stays in sync with other patterns)