bit more

GUIDE.md

@@ -100,7 +100,7 @@ CALL
 - `THROW` - Throw exception (pops error value)
 
 ### Native
-- `CALL_NATIVE <name>` - Call registered TypeScript function
+- `CALL_NATIVE <name>` - Call registered TypeScript function (consumes entire stack as args)
 
 ## Compiler Patterns
 
@@ -268,6 +268,32 @@ STORE factorial
 ### Truthiness
 Only `null` and `false` are falsy. Everything else (including `0`, `""`, empty arrays/dicts) is truthy.
 
+### Type Coercion
+
+**toNumber**:
+- `number` → identity
+- `string` → parseFloat (or 0 if invalid)
+- `boolean` → 1 (true) or 0 (false)
+- `null` → 0
+- Others → 0
+
+**toString**:
+- `string` → identity
+- `number` → string representation
+- `boolean` → "true" or "false"
+- `null` → "null"
+- `function` → "<function>"
+- `array` → "[item, item]"
+- `dict` → "{key: value, ...}"
+
+**Arithmetic ops** (ADD, SUB, MUL, DIV, MOD) coerce both operands to numbers.
+
+**Comparison ops** (LT, GT, LTE, GTE) coerce both operands to numbers.
+
+**Equality ops** (EQ, NEQ) use type-aware comparison with deep equality for arrays/dicts.
+
+**Note**: There is no string concatenation operator. ADD only works with numbers.
+
 ### Scope
 - Variables resolved through parent scope chain
 - STORE updates existing variable or creates in current scope
@@ -300,3 +326,10 @@ All calls push arguments in order:
 4. Positional count (as number)
 5. Named count (as number)
 6. CALL or TAIL_CALL
+
+### CALL_NATIVE Behavior
+Unlike CALL, CALL_NATIVE consumes the **entire stack** as arguments and clears the stack. The native function receives all values that were on the stack at the time of the call.
+
+### Empty Stack
+- RETURN with empty stack returns null
+- HALT with empty stack returns null