docs: migrate all book/docs examples from JSON actions to TypedAST actions

- docs/ZYN_GRAMMAR_SPEC.md: rewrite as v3.0 for TypedAST action system
- book/README.md: update description and example to TypedAST syntax
- book/01-introduction.md: update example, architecture diagram, chapter link
- book/02-getting-started.md: rewrite calculator grammar with fold_left_ops, named bindings
- book/04-grammar-syntax.md: replace fold_binary with fold_left_ops + make_pair pattern
- book/05-semantic-actions.md: complete rewrite covering all 5 action kinds
- book/08-zig-example.md: major rewrite - named bindings, no split pattern, consolidated op rules
- book/09-reference.md: replace Command Reference with TypedAST Action Reference
- book/13-async-runtime.md: update async grammar example with is_async field
- book/15-building-dsls.md: update ArtLang/ChartLang grammar snippets
- book/16-image-pipeline-dsl.md: update all grammar snippets and Key Concepts section

Old JSON command blocks (get_text, fold_binary, define, get_all_children, $1/$2)
replaced throughout with named bindings, intern(), fold_left_ops(), prepend_list(),
and TypedAST construct expressions.

Author: darmie

book/01-introduction.md

@@ -4,8 +4,8 @@
 
 Zyn (ZynPEG) is a grammar-driven language frontend system that transforms source code into a typed abstract syntax tree (TypedAST). It combines three powerful concepts:
 
-1. **PEG Parsing** - Uses Pest-compatible Parser Expression Grammars for syntax definition
-2. **Declarative Semantics** - JSON command blocks describe how to build AST nodes
+1. **PEG Parsing** - Parser Expression Grammars with Packrat memoization for O(n) parsing
+2. **TypedAST Actions** - Typed construct expressions build AST nodes directly at parse time
 3. **Universal TypedAST** - A target representation that supports multiple programming paradigms
 
 ## The Problem Zyn Solves
@@ -32,24 +32,20 @@ Source Code → Zyn Grammar → TypedAST → Compiler Backend
 
 A Zyn grammar file (`.zyn`) contains:
 
-1. **Grammar rules** - PEG syntax defining what to parse
-2. **Semantic actions** - JSON blocks defining what AST nodes to create
+1. **Grammar rules** - PEG syntax defining what to parse, with named bindings
+2. **Semantic actions** - TypedAST construct expressions defining what AST nodes to create
 
 ```zyn
-// Grammar rule
+// Atomic rule (@) captures matched text automatically
+// The binding name 'integer_literal' holds that text in the action
 integer_literal = @{ "-"? ~ ASCII_DIGIT+ }
-  -> TypedExpression {
-      "get_text": true,
-      "parse_int": true,
-      "define": "int_literal",
-      "args": { "value": "$result" }
-  }
+  -> TypedExpression::IntLiteral { value: integer_literal }
 ```
 
 When this rule matches, Zyn:
-1. Extracts the matched text (`get_text`)
-2. Parses it as an integer (`parse_int`)
-3. Calls `create_int_literal(value)` on the AST builder
+1. Captures the matched text automatically (the `@` modifier)
+2. Evaluates the action expression, constructing a `TypedExpression::IntLiteral` node
+3. Returns the node directly to the parent rule — no separate AST building pass needed
 
 ## The TypedAST
 
@@ -91,37 +87,31 @@ Grammar changes automatically propagate to AST construction - no separate files
 ```
 ┌─────────────────┐
 │   Source File   │
-│    (*.zig)      │
+│   (*.zynml)     │
 └────────┬────────┘
          │
          ▼
-┌─────────────────┐     ┌─────────────────┐
-│   Zyn Grammar   │────▶│   Pest Parser   │
-│    (*.zyn)      │     │   (generated)   │
-└─────────────────┘     └────────┬────────┘
-                                 │
-                                 ▼
-                        ┌─────────────────┐
-                        │ Command         │
-                        │ Interpreter     │
-                        └────────┬────────┘
-                                 │
-                                 ▼
-                        ┌─────────────────┐
-                        │  TypedAST       │
-                        │  Builder        │
-                        └────────┬────────┘
-                                 │
-                                 ▼
+┌─────────────────┐     ┌──────────────────────┐
+│   Zyn Grammar   │────▶│  GrammarInterpreter  │
+│    (*.zyn)      │     │  (Packrat memoized   │
+└─────────────────┘     │   PEG, O(n) time)    │
+                        └──────────┬───────────┘
+                                   │
+                                   │  TypedAST actions
+                                   │  evaluated inline
+                                   ▼
                         ┌─────────────────┐
                         │  TypedProgram   │
-                        │  (JSON/Binary)  │
+                        │  (direct, no    │
+                        │   JSON/VM)      │
                         └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │  Compiler       │
                         │  Backend        │
+                        │  (HIR → SSA →   │
+                        │   Native Code)  │
                         └─────────────────┘
 ```
 
@@ -132,7 +122,7 @@ In the following chapters, you'll learn:
 - [Chapter 2](./02-getting-started.md): Set up your environment and write your first grammar
 - [Chapter 3](./03-using-the-cli.md): Use the CLI for compilation and REPL testing
 - [Chapter 4](./04-grammar-syntax.md): Master PEG syntax for parsing
-- [Chapter 5](./05-semantic-actions.md): Use JSON commands to build AST nodes
+- [Chapter 5](./05-semantic-actions.md): Use TypedAST actions to build AST nodes
 - [Chapter 6](./06-typed-ast.md): Understand the TypedAST structure
 - [Chapter 7](./07-typed-ast-builder.md): Use the builder API directly
 - [Chapter 8](./08-zig-example.md): Walk through a complete Zig implementation

book/02-getting-started.md

@@ -35,44 +35,40 @@ Create `calc.zyn`:
     entry_point: "main",
 }
 
-// Program structure
-program = { SOI ~ expr ~ EOI }
+// Program structure: wrap the expression in a main function
+program = { SOI ~ e:expr ~ EOI }
   -> TypedProgram {
-      "commands": [
-          { "define": "program_expr", "args": { "expr": "$1" } }
-      ]
+      declarations: [
+          TypedDeclaration::Function {
+              name: intern("main"),
+              params: [],
+              return_type: Type::Named { name: intern("i64") },
+              body: Some(TypedBlock {
+                  stmts: [TypedStatement::Return { value: Some(e) }],
+              }),
+              is_async: false,
+          }
+      ],
   }
 
-// Expression with addition/subtraction
-expr = { term ~ ((add_op | sub_op) ~ term)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "term", "operator": "add_op|sub_op" }
-  }
+// Expression with addition/subtraction (left-associative)
+expr = { first:term ~ rest:expr_rest* }
+  -> fold_left_ops(first, rest)
+
+expr_rest = { op:add_sub_op ~ operand:term }
+  -> make_pair(op, operand)
 
-// Terms are atoms or parenthesized expressions
+add_sub_op = @{ "+" | "-" }
+
+// Terms are atoms or parenthesized expressions — passthrough
 term = { integer | paren_expr }
-  -> TypedExpression {
-      "get_child": { "index": 0 }
-  }
 
 // Parenthesized expression (silent rule - doesn't create node)
 paren_expr = _{ "(" ~ expr ~ ")" }
 
-// Integer literal
+// Integer literal — atomic rule captures text automatically
 integer = @{ ASCII_DIGIT+ }
-  -> TypedExpression {
-      "get_text": true,
-      "parse_int": true,
-      "define": "int_literal",
-      "args": { "value": "$result" }
-  }
-
-// Operators
-add_op = { "+" }
-  -> String { "get_text": true }
-
-sub_op = { "-" }
-  -> String { "get_text": true }
+  -> TypedExpression::IntLiteral { value: integer }
 
 // Whitespace handling
 WHITESPACE = _{ " " | "\t" | "\n" }
@@ -113,13 +109,11 @@ This block defines metadata about your language:
 
 ### Grammar Rules
 
-Rules follow PEG syntax with semantic action blocks:
+Rules follow PEG syntax with optional semantic actions:
 
 ```zyn
 rule_name = { pattern }
-  -> ResultType {
-      // JSON commands
-  }
+  -> TypedAST::Variant { field: value, ... }
 ```
 
 | Syntax | Meaning |
@@ -155,32 +149,37 @@ rule_name = { pattern }
 
 ## Semantic Actions
 
-Each rule can have a semantic action block that describes how to build AST nodes:
+Each rule can have a semantic action that builds a TypedAST node directly from parsed bindings:
 
 ```zyn
+// Atomic rule (@) — matched text is available via the binding name 'integer'
 integer = @{ ASCII_DIGIT+ }
-  -> TypedExpression {
-      "get_text": true,      // Get matched text
-      "parse_int": true,     // Parse as integer
-      "define": "int_literal",
-      "args": { "value": "$result" }
-  }
+  -> TypedExpression::IntLiteral { value: integer }
 ```
 
-The `->` arrow connects the grammar rule to its semantic action:
-- `TypedExpression` is the expected result type
-- The JSON block contains commands to execute
+The `->` arrow connects the grammar rule to its action:
+- `TypedExpression::IntLiteral` is the TypedAST variant to construct
+- `value: integer` sets the field using the captured text from the binding
+
+Named bindings in the pattern make values available to the action:
+
+```zyn
+fn_param = { name:identifier ~ ":" ~ ty:type_expr }
+  -> TypedParameter { name: intern(name), ty: ty }
+//                          ^^^^                ^^
+//                    binding 'name'      binding 'ty'
+```
 
-### Common Commands
+### Common Action Patterns
 
-| Command | Purpose |
-|---------|---------|
-| `get_text` | Extract matched text |
-| `get_child` | Get a specific child node |
-| `get_all_children` | Collect all child nodes |
-| `parse_int` | Parse text as integer |
-| `define` | Call an AST builder method |
-| `fold_binary` | Build left-associative binary expressions |
+| Pattern | Description |
+|---------|-------------|
+| `TypedX::Y { field: binding }` | Construct a TypedAST node from bindings |
+| `-> binding` | Passthrough — return a binding directly |
+| `-> fold_left_ops(first, rest)` | Build a left-associative binary expression tree |
+| `-> prepend_list(first, rest)` | Combine first element + rest Vec into a Vec |
+| `-> intern(name)` | Intern a string binding into the arena |
+| `-> if cond { ... } else { ... }` | Branch on a boolean binding |
 
 ## Project Structure
 

book/04-grammar-syntax.md

@@ -200,43 +200,68 @@ PEG handles operator precedence through grammar structure, not precedence tables
 
 ### Left-Associative Operators
 
-Build a chain of rules from lowest to highest precedence:
+Build a chain of rules from lowest to highest precedence. Each level uses `fold_left_ops` with a companion `rest` rule that packages `(op, operand)` pairs using `make_pair`:
 
 ```zyn
 // Lowest precedence: logical OR
-expr = { logical_or }
+expr = { e:logical_or }
+  -> e
 
-logical_or = { logical_and ~ ("or" ~ logical_and)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "logical_and", "operator": "or" }
-  }
+logical_or = { first:logical_and ~ rest:logical_or_rest* }
+  -> fold_left_ops(first, rest)
 
-logical_and = { comparison ~ ("and" ~ comparison)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "comparison", "operator": "and" }
-  }
+logical_or_rest = { op:or_op ~ operand:logical_and }
+  -> make_pair(op, operand)
 
-comparison = { addition ~ (("==" | "!=" | "<" | ">") ~ addition)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "addition", "operator": "==|!=|<|>" }
-  }
+or_op = @{ "or" }
 
-addition = { multiplication ~ (("+" | "-") ~ multiplication)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "multiplication", "operator": "+|-" }
-  }
+logical_and = { first:comparison ~ rest:logical_and_rest* }
+  -> fold_left_ops(first, rest)
 
-multiplication = { unary ~ (("*" | "/") ~ unary)* }
-  -> TypedExpression {
-      "fold_binary": { "operand": "unary", "operator": "*|/" }
-  }
+logical_and_rest = { op:and_op ~ operand:comparison }
+  -> make_pair(op, operand)
+
+and_op = @{ "and" }
+
+comparison = { first:addition ~ rest:comparison_rest* }
+  -> fold_left_ops(first, rest)
+
+comparison_rest = { op:comparison_op ~ operand:addition }
+  -> make_pair(op, operand)
+
+comparison_op = @{ "==" | "!=" | "<=" | ">=" | "<" | ">" }
+
+addition = { first:multiplication ~ rest:addition_rest* }
+  -> fold_left_ops(first, rest)
+
+addition_rest = { op:add_op ~ operand:multiplication }
+  -> make_pair(op, operand)
+
+add_op = @{ "+" | "-" }
+
+multiplication = { first:unary ~ rest:multiplication_rest* }
+  -> fold_left_ops(first, rest)
+
+multiplication_rest = { op:mul_op ~ operand:unary }
+  -> make_pair(op, operand)
+
+mul_op = @{ "*" | "/" }
 
 // Highest precedence: unary then atoms
-unary = { ("-" | "!") ~ unary | atom }
+unary = { unary_with_op | atom }
+
+unary_with_op = { op:unary_op ~ operand:atom }
+  -> TypedExpression::Unary { op: op, operand: Box::new(operand) }
+
+unary_op = @{ "-" | "!" }
 
-atom = { number | identifier | "(" ~ expr ~ ")" }
+atom = { number | identifier | paren_expr }
+
+paren_expr = _{ "(" ~ expr ~ ")" }
 ```
 
+`fold_left_ops` takes the `first` value and the `rest` Vec of `(op, operand)` pairs and builds a left-associative binary tree. For input `a + b - c` it produces `Binary(-, Binary(+, a, b), c)`.
+
 ### Right-Associative Operators
 
 Use recursion for right-associativity: