Feat: documentation, UI/UX

crates/forth/README.md

@@ -0,0 +1,22 @@
+# cagire-forth
+
+Stack-based Forth VM for the Cagire sequencer. Tokenizes, compiles, and executes step scripts to produce audio and MIDI commands.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `vm` | Interpreter loop, `Forth::evaluate()` entry point |
+| `compiler` | Tokenization (with source spans) and single-pass compilation to ops |
+| `ops` | `Op` enum (~90 variants) |
+| `types` | `Value`, `StepContext`, shared state types |
+| `words/` | Built-in word definitions: `core`, `sound`, `music`, `midi`, `effects`, `sequencing`, `compile` |
+| `theory/` | Music theory lookups: `scales` (~200 patterns), `chords` (interval arrays) |
+
+## Key Types
+
+- **`Forth`** — VM instance, holds stacks and compilation state
+- **`Value`** — Stack value (int, float, string, list, quotation, ...)
+- **`StepContext`** — Per-step evaluation context (step index, tempo, variables, ...)
+- **`Op`** — Compiled operation; nondeterministic variants carry `Option<SourceSpan>` for tracing
+- **`ExecutionTrace`** — Records executed/selected spans and resolved values during evaluation

crates/forth/src/ops.rs

@@ -65,6 +65,7 @@ pub enum Op {
     NewCmd,
     SetParam(&'static str),
     Emit,
+    Print,
     Get,
     Set,
     SetKeep,

crates/forth/src/vm.rs

@@ -328,6 +328,16 @@ impl Forth {
                 Op::Drop => {
                     pop(stack)?;
                 }
+                Op::Print => {
+                    let val = pop(stack)?;
+                    let text = match &val {
+                        Value::Int(n, _) => n.to_string(),
+                        Value::Float(f, _) => format!("{f}"),
+                        Value::Str(s, _) => s.to_string(),
+                        _ => format!("{val:?}"),
+                    };
+                    outputs.push(format!("print:{text}"));
+                }
                 Op::Swap => {
                     ensure(stack, 2)?;
                     let len = stack.len();
@@ -558,9 +568,12 @@ impl Forth {
 
                 Op::NewCmd => {
                     ensure(stack, 1)?;
-                    let values = std::mem::take(stack);
+                    let values = drain_skip_quotations(stack);
+                    if values.is_empty() {
+                        return Err("expected sound name".into());
+                    }
                     let val = if values.len() == 1 {
-                        values.into_iter().next().expect("single value after len check")
+                        values.into_iter().next().unwrap()
                     } else {
                         Value::CycleList(Arc::from(values))
                     };
@@ -568,9 +581,12 @@ impl Forth {
                 }
                 Op::SetParam(param) => {
                     ensure(stack, 1)?;
-                    let values = std::mem::take(stack);
+                    let values = drain_skip_quotations(stack);
+                    if values.is_empty() {
+                        return Err("expected parameter value".into());
+                    }
                     let val = if values.len() == 1 {
-                        values.into_iter().next().expect("single value after len check")
+                        values.into_iter().next().unwrap()
                     } else {
                         Value::CycleList(Arc::from(values))
                     };
@@ -1866,6 +1882,21 @@ fn pop_bool(stack: &mut Vec<Value>) -> Result<bool, String> {
     Ok(pop(stack)?.is_truthy())
 }
 
+/// Drain the stack, returning non-quotation values.
+/// Quotations are pushed back onto the stack (transparent).
+fn drain_skip_quotations(stack: &mut Vec<Value>) -> Vec<Value> {
+    let values = std::mem::take(stack);
+    let mut result = Vec::new();
+    for v in values {
+        if matches!(v, Value::Quotation(..)) {
+            stack.push(v);
+        } else {
+            result.push(v);
+        }
+    }
+    result
+}
+
 fn ensure(stack: &[Value], n: usize) -> Result<(), String> {
     if stack.len() < n {
         return Err("stack underflow".into());

crates/forth/src/words/compile.rs

@@ -13,6 +13,7 @@ pub(super) fn simple_op(name: &str) -> Option<Op> {
         "dup" => Op::Dup,
         "dupn" => Op::Dupn,
         "drop" => Op::Drop,
+        "print" => Op::Print,
         "swap" => Op::Swap,
         "over" => Op::Over,
         "rot" => Op::Rot,

crates/forth/src/words/core.rs

@@ -33,6 +33,16 @@ pub(super) const WORDS: &[Word] = &[
         compile: Simple,
         varargs: false,
     },
+    Word {
+        name: "print",
+        aliases: &[],
+        category: "Stack",
+        stack: "(x --)",
+        desc: "Print top of stack to footer bar",
+        example: "42 print",
+        compile: Simple,
+        varargs: false,
+    },
     Word {
         name: "swap",
         aliases: &[],

crates/markdown/README.md

@@ -0,0 +1,15 @@
+# cagire-markdown
+
+Markdown parser and renderer that produces ratatui-styled lines. Used for the built-in help/documentation views.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `parser` | Markdown-to-styled-lines conversion |
+| `highlighter` | `CodeHighlighter` trait for syntax highlighting in fenced code blocks |
+| `theme` | Color mappings for markdown elements |
+
+## Key Trait
+
+- **`CodeHighlighter`** — Implement to provide language-specific syntax highlighting. Returns `Vec<(Style, String)>` per line.

crates/project/README.md

@@ -0,0 +1,22 @@
+# cagire-project
+
+Project data model and persistence for Cagire.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| `project` | `Project`, `Bank`, `Pattern`, `Step` structs and constants |
+| `file` | File I/O (save/load) |
+| `share` | Project sharing/export |
+
+## Key Types
+
+- **`Project`** — Top-level container: banks of patterns
+- **`Bank`** — Collection of patterns
+- **`Pattern`** — Sequence of steps with metadata
+- **`Step`** — Single step holding a Forth script
+
+## Constants
+
+`MAX_BANKS=32`, `MAX_PATTERNS=32`, `MAX_STEPS=1024`

crates/ratatui/README.md

@@ -0,0 +1,25 @@
+# cagire-ratatui
+
+TUI widget library and theme system for Cagire.
+
+## Widgets
+
+`category_list`, `confirm`, `editor`, `file_browser`, `hint_bar`, `lissajous`, `list_select`, `modal`, `nav_minimap`, `props_form`, `sample_browser`, `scope`, `scroll_indicators`, `search_bar`, `section_header`, `sparkles`, `spectrum`, `text_input`, `vu_meter`, `waveform`
+
+## Theme System
+
+The `theme/` module provides a palette-based theming system using Oklab color space.
+
+| Module | Description |
+|--------|-------------|
+| `mod` | `THEMES` array, `CURRENT_THEME` thread-local, `get()`/`set()` |
+| `palette` | `Palette` (14 fields), color manipulation helpers (`shift`, `mix`, `tint_bg`, ...) |
+| `build` | Derives ~190 `ThemeColors` fields from a `Palette` |
+| `transform` | HSV-based hue rotation for generated palettes |
+
+25 built-in themes.
+
+## Key Types
+
+- **`Palette`** — 14-field color definition, input to theme generation
+- **`ThemeColors`** — ~190 derived semantic colors used throughout the UI