Feat: documentation, UI/UX

docs/forth/brackets.md

@@ -0,0 +1,108 @@
+# Brackets
+
+Cagire uses three bracket forms. Each one behaves differently.
+
+## ( ... ) — Quotations
+
+Parentheses create quotations: deferred code. The contents are not executed immediately — they are pushed onto the stack as a single value.
+
+```forth
+( dup + )
+```
+
+This pushes a block of code. You can store it in a variable, pass it to other words, or execute it later. Quotations are what make Cagire's control flow work.
+
+### Words that consume quotations
+
+Many built-in words expect a quotation on the stack:
+
+| Word | Effect |
+|------|--------|
+| `?` | Execute if condition is truthy |
+| `!?` | Execute if condition is falsy |
+| `ifelse` | Choose between two quotations |
+| `select` | Pick the nth quotation from a list |
+| `apply` | Execute unconditionally |
+| `times` | Loop n times |
+| `cycle` / `pcycle` | Rotate through quotations |
+| `choose` | Pick one at random |
+| `every` | Execute on every nth iteration |
+| `chance` / `prob` | Execute with probability |
+| `bjork` / `pbjork` | Euclidean rhythm gate |
+
+When a word like `cycle` or `choose` selects a quotation, it executes it. When it selects a plain value, it pushes it.
+
+### Nesting
+
+Quotations nest freely:
+
+```forth
+( ( c4 note ) ( e4 note ) coin ifelse ) 4 every
+```
+
+The outer quotation runs every 4th iteration. Inside, a coin flip picks the note.
+
+### The mute trick
+
+Wrapping code in a quotation without consuming it is a quick way to disable it:
+
+```forth
+( kick s . )
+```
+
+Nothing will execute this quotation — it just sits on the stack and gets discarded. Useful for temporarily silencing a line while editing.
+
+## [ ... ] — Square Brackets
+
+Square brackets execute their contents immediately, then push a count of how many values were produced. The values themselves stay on the stack.
+
+```forth
+[ 60 64 67 ]
+```
+
+After this runs, the stack holds `60 64 67 3` — three values plus the count `3`. This is useful with words that need to know how many items precede them:
+
+```forth
+[ 60 64 67 ] cycle note sine s .
+```
+
+The `cycle` word reads the count to know how many values to rotate through. Without brackets you would write `60 64 67 3 cycle` — the brackets save you from counting manually.
+
+Square brackets work with any word that takes a count:
+
+```forth
+[ c4 e4 g4 ] choose note saw s .    ;; random note from the list
+[ 60 64 67 ] note sine s .           ;; 3-note chord (note consumes all)
+```
+
+### Nesting
+
+Square brackets can nest. Each pair produces its own count:
+
+```forth
+[ [ 60 64 67 ] cycle [ 0.3 0.5 0.8 ] cycle ] choose
+```
+
+### Expressions inside brackets
+
+The contents are compiled and executed normally, so you can use any Forth code:
+
+```forth
+[ c4 c4 3 + c4 7 + ] note sine s .    ;; root, minor third, fifth
+```
+
+## { ... } — Curly Braces
+
+Curly braces are ignored by the compiler. They do nothing. Use them as a visual aid to group related code:
+
+```forth
+{ kick s } { 0.5 gain } { 0.3 verb } .
+```
+
+This compiles to exactly the same thing as:
+
+```forth
+kick s 0.5 gain 0.3 verb .
+```
+
+They can help readability in dense one-liners but have no semantic meaning.