docs: Add pattern matching documentation for switch expressions

Update documentation to cover the newly implemented pattern matching
features for switch expressions including grammar commands and usage
examples.

- Add Pattern Matching section to book/05-semantic-actions.md with
  all pattern commands (literal, wildcard, range, struct, enum, etc.)
- Add comprehensive Switch Expressions section to book/08-zig-example.md
- Update README.md with pattern matching in language features
- Update BACKLOG.md with completed pattern matching status

Author: darmie

BACKLOG.md

@@ -5,6 +5,12 @@
 
 **Recent Progress**:
 
+- ✅ **Switch Expression Pattern Matching Complete** (November 27, 2025)
+  - Multi-case switch with literal patterns and else clause
+  - Tagged union patterns (`.some`, `.none`) with graceful non-enum handling
+  - Error patterns (`error.OutOfMemory`)
+  - Grammar support for all pattern types (literal, wildcard, range, struct, enum, array, pointer, error)
+  - Documentation updated (`book/05-semantic-actions.md`, `book/08-zig-example.md`)
 - ✅ **LLVM Backend Working** (AOT and JIT modes fully functional - functions, structs, generics)
   - Parameter value mapping for function calls
   - Struct initialization with InsertValue
@@ -285,16 +291,32 @@ Stack-unwinding exceptions for Haxe/Java-style languages. Required for Reflaxe i
 - [x] Switch expressions with literal and wildcard patterns
 - [x] `test_pattern_match_runtime_execution` passing (Some/None)
 - [x] `test_zig_jit_switch_expression` passing
+- [x] **Multi-case switch expressions** (multiple literal cases with else)
+- [x] **Tagged union patterns** (`.some`, `.none` - graceful handling for non-enum scrutinee)
+- [x] **Error patterns** (`error.OutOfMemory`)
+- [x] **Grammar support for all pattern types**:
+  - `literal_pattern` - Match exact values
+  - `wildcard_pattern` - Match anything (`_` or `else`)
+  - `range_pattern` - Match value ranges (`1..10`)
+  - `identifier_pattern` - Bind matched value to variable
+  - `struct_pattern` - Match struct fields
+  - `field_pattern` - Match individual struct field
+  - `enum_pattern` - Match tagged union variant
+  - `array_pattern` - Match array elements
+  - `pointer_pattern` - Match through pointer dereference
+  - `error_pattern` - Match error values
+- [x] **Documentation updated** (`book/05-semantic-actions.md`, `book/08-zig-example.md`)
 
 **Known Issue** (minor):
+
 - [ ] None literal (arena symbol resolution - Symbol 7 doesn't resolve)
   - Root cause: Parser and SSA arena symbol lookup mismatch
   - Impact: Minor - workaround exists using if-let on None branch
 
 **Pending Features**:
+
 - [ ] Or patterns (`Some(x) | None`)
 - [ ] Pattern guards (`if` conditions)
-- [ ] Range patterns (`1..=10`)
 - [ ] Slice patterns (`[first, .., last]`)
 
 ---

README.md

@@ -253,10 +253,11 @@ Goodbye!
 ### Available Node Types
 
 - **Literals**: `int_literal`, `float_literal`, `string_literal`, `bool_literal`, `char_literal`
-- **Expressions**: `variable`, `binary_op`, `unary_op`, `call_expr`, `method_call`, `field_access`, `index`, `array`, `struct_literal`, `cast`, `lambda`
+- **Expressions**: `variable`, `binary_op`, `unary_op`, `call_expr`, `method_call`, `field_access`, `index`, `array`, `struct_literal`, `cast`, `lambda`, `switch_expr`
 - **Statements**: `let_stmt`, `assignment`, `return_stmt`, `if_stmt`, `while_stmt`, `for_stmt`, `break_stmt`, `continue_stmt`, `expression_stmt`, `block`
 - **Declarations**: `function`, `param`, `program`
 - **Types**: `primitive_type`, `pointer_type`, `array_type`, `named_type`, `function_type`
+- **Patterns**: `literal_pattern`, `wildcard_pattern`, `range_pattern`, `identifier_pattern`, `struct_pattern`, `field_pattern`, `enum_pattern`, `array_pattern`, `pointer_pattern`, `error_pattern`, `switch_case`
 
 See [Zyn Grammar Specification](./docs/ZYN_GRAMMAR_SPEC.md) for complete documentation.
 
@@ -466,7 +467,7 @@ cargo build --release
 - Basic arithmetic (`+`, `-`, `*`, `/`)
 - Function calls (including recursive)
 - Local variables with stack allocation
-- Pattern matching (basic)
+- Switch expressions with pattern matching (literals, wildcards, ranges, structs, enums, errors)
 - Async/await syntax and runtime
 
 #### ✅ Tiered JIT Compilation

book/05-semantic-actions.md

@@ -275,6 +275,99 @@ primitive_type = { "i32" | "i64" | "bool" | "void" }
   }
 ```
 
+#### Pattern Matching
+
+These commands create pattern nodes for switch expressions and pattern matching:
+
+| Method | Arguments | Creates |
+|--------|-----------|---------|
+| `literal_pattern` | `value` | Match a literal value (int, string) |
+| `wildcard_pattern` | | Match anything (`_` or `else`) |
+| `range_pattern` | `start`, `end`, `inclusive` | Match a range (`1..10`) |
+| `identifier_pattern` | `name` | Bind matched value to variable |
+| `struct_pattern` | `name`, `fields` | Match struct with field patterns |
+| `field_pattern` | `name`, `pattern`? | Match a struct field |
+| `enum_pattern` | `name`, `variant`, `fields` | Match enum/tagged union variant |
+| `array_pattern` | `elements` | Match array elements |
+| `pointer_pattern` | `inner`, `mutable` | Match pointer dereference |
+| `error_pattern` | `name` | Match error value (`error.OutOfMemory`) |
+| `switch_expr` | `scrutinee`, `cases` | Switch expression |
+| `switch_case` | `pattern`, `body` | Single switch case arm |
+
+```zyn
+// Literal pattern: match exact value
+switch_literal_pattern = { integer_literal }
+  -> TypedExpression {
+      "commands": [
+          { "define": "literal_pattern", "args": { "value": "$1" } }
+      ]
+  }
+
+// Wildcard pattern: match anything
+switch_wildcard_pattern = { "_" }
+  -> TypedExpression {
+      "commands": [
+          { "define": "wildcard_pattern" }
+      ]
+  }
+
+// Range pattern: match value in range
+switch_range_pattern = { integer_literal ~ ".." ~ integer_literal }
+  -> TypedExpression {
+      "commands": [
+          { "define": "range_pattern", "args": {
+              "start": { "define": "literal_pattern", "args": { "value": "$1" } },
+              "end": { "define": "literal_pattern", "args": { "value": "$2" } },
+              "inclusive": false
+          }}
+      ]
+  }
+
+// Struct pattern: match struct fields
+switch_struct_pattern = { identifier ~ "{" ~ struct_field_patterns? ~ "}" }
+  -> TypedExpression {
+      "commands": [
+          { "define": "struct_pattern", "args": {
+              "name": { "text": "$1" },
+              "fields": "$2"
+          }}
+      ]
+  }
+
+// Tagged union pattern: .some, .none
+switch_tagged_union_pattern = { "." ~ identifier }
+  -> TypedExpression {
+      "commands": [
+          { "define": "enum_pattern", "args": {
+              "name": "",
+              "variant": { "text": "$1" },
+              "fields": []
+          }}
+      ]
+  }
+
+// Error pattern: error.OutOfMemory
+switch_error_pattern = { "error" ~ "." ~ identifier }
+  -> TypedExpression {
+      "commands": [
+          { "define": "error_pattern", "args": {
+              "name": { "text": "$1" }
+          }}
+      ]
+  }
+
+// Pointer pattern: *x
+switch_pointer_pattern = { "*" ~ switch_pattern }
+  -> TypedExpression {
+      "commands": [
+          { "define": "pointer_pattern", "args": {
+              "inner": "$1",
+              "mutable": false
+          }}
+      ]
+  }
+```
+
 ## The `fold_binary` Command
 
 This special command builds left-associative binary expression trees from repetition patterns.