Feat: documentation, UI/UX

src/README.md

@@ -0,0 +1,26 @@
+# cagire (main application)
+
+Terminal UI application — ties together the Forth VM, audio engine, and project model.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `app/` | `App` struct and submodules: dispatch, editing, navigation, persistence, scripting, sequencer, clipboard, staging, undo |
+| `engine/` | Audio engine: `sequencer`, `audio`, `link` (Ableton Link), `dispatcher`, `realtime`, `timing` |
+| `input/` | Keyboard/mouse handling: per-page handlers, modal input, `InputContext` |
+| `views/` | Pure rendering functions taking `&App` |
+| `state/` | UI state modules (audio, editor, modals, panels, playback, ...) |
+| `services/` | Domain logic: clipboard, dict navigation, euclidean, help navigation, pattern editor, stack preview |
+| `model/` | Domain models: docs, categories, onboarding, script |
+| `commands` | `AppCommand` enum (~150 variants) |
+| `page` | `Page` navigation enum |
+| `midi` | MIDI I/O (up to 4 inputs/outputs) |
+| `settings` | Confy-based persistent settings |
+
+## Key Types
+
+- **`App`** — Central application state, coordinates all subsystems
+- **`AppCommand`** — Enum of all user actions, dispatched via `App::dispatch()`
+- **`InputContext`** — Holds `&mut App` + channel senders, bridges input to commands
+- **`Page`** — 3x2 page grid (Dict, Patterns, Options, Help, Main, Engine)