1 files changed, 43 insertions, 9 deletions
diff --git a/js/baba-yaga/docs/07_gotchyas.md b/js/baba-yaga/docs/07_gotchyas.md
index bf8b300..dc71b38 100644
--- a/js/baba-yaga/docs/07_gotchyas.md
+++ b/js/baba-yaga/docs/07_gotchyas.md
@@ -11,6 +11,7 @@ This document catalogs the strict syntax requirements and common pitfalls discov
 5. [Function Definitions](#function-definitions)
 6. [Data Structure Syntax](#data-structure-syntax)
 7. [Common Error Patterns](#common-error-patterns)
+8. [JavaScript Interop Gotchas](#javascript-interop-gotchas)
 
 ## When Expression Syntax
 
@@ -230,14 +231,14 @@ isValid and hasData;       // Error: Unexpected token: KEYWORD (and)
 
 ### **Critical Rule: Complex Comparison Chains**
 
-** Incorrect: Complex comparisons without parentheses**
+**Incorrect: Complex comparisons without parentheses**
 ```baba
 // WRONG - Complex comparisons need parentheses
 math.abs (x * x + y * y) - (z * z) < 0.001;  // Error: Unexpected token: OPERATOR (-)
 side1 + side2 > side3;                         // Error: Unexpected token: OPERATOR (>)
 ```
 
-** Correct: Complex comparisons wrapped in parentheses**
+**Correct: Complex comparisons wrapped in parentheses**
 ```baba
 // CORRECT - Wrap complex comparisons in parentheses
 (math.abs ((x * x + y * y) - (z * z))) < 0.001;  // ✓ Works correctly
@@ -516,12 +517,13 @@ For comprehensive information about Baba Yaga's type system, see:
 - **[Types Documentation](./04_types.md)** - Complete type system reference
 - **[Recursion Documentation](./05_recursion-and-composition.md)** - Details on `with rec` usage
 - **[Crash Course](./00_crash-course.md)** - Examples and patterns
+- **[JavaScript Interop](./09_js-interop.md)** - Complete JS interop reference
 
 ## Common Error Patterns
 
 ### 1. **Unexpected SEMICOLON errors**
-- **Cause**: Missing semicolon after when expressions in with blocks
-- **Solution**: Always add semicolon after each with block entry
+- **Cause**: Missing semicolon after `when` expressions in `with` blocks
+- **Solution**: Always add semicolon after each `with` block entry
 
 ### 2. **Unexpected COLON errors**
 - **Cause**: Incorrect table literal syntax
@@ -549,7 +551,7 @@ For comprehensive information about Baba Yaga's type system, see:
 - Always use `_ then` for fallback cases
 - Use `then when` for nested conditions
 - Wrap complex conditions in parentheses
-- Add semicolons after when expressions in with blocks
+- Add semicolons after when expressions in `with` blocks
 
 ### 2. **With vs With Rec**
 - **Use `with`** for:
@@ -571,11 +573,10 @@ For comprehensive information about Baba Yaga's type system, see:
 ### 4. **Type System**
 - Use simple type declarations: `x Int; x : 5;`
 - Avoid function type annotations
-- Use documented functions only
 
 ### 5. **Data Structures**
-- Use explicit key: value pairs in tables
-- Use when expressions for conditional access
+- Use explicit `key: value` pairs in tables
+- Use `when` expressions for conditional access
 - Avoid dynamic property access
 
 ## Debugging Tips
@@ -605,4 +606,37 @@ For comprehensive information about Baba Yaga's type system, see:
 - Wrap function calls in comparisons: `(length list) > 0`
 - Wrap logical expressions: `(a > 0) and (b > 0)`
 - Wrap complex arithmetic: `(x + y) > z`
-- See [Operator Precedence Rules](#operator-precedence-and-parenthesization-rules) for details
\ No newline at end of file
+- See [Operator Precedence Rules](#operator-precedence-and-parenthesization-rules) for details
+
+## JavaScript Interop Gotchas
+
+When working with JavaScript interop, there are some specific gotchas to be aware of:
+
+### **JSValue Wrapper Behavior**
+
+```baba
+// WRONG - Expecting direct value access
+result : io.callJS "Math.abs" [-42];
+value : result.value;  // This is a JSValue wrapper, not the raw number
+
+// CORRECT - Pass JSValue directly to other io.* functions
+result : io.callJS "Math.abs" [-42];
+when result is
+  Ok jsValue then io.objectToTable jsValue  // JSValue accepted directly
+  Err msg then Err msg;
+```
+
+### **Type Conversion Timing**
+
+```baba
+// WRONG - Premature conversion can lose JS semantics
+parsed : io.callJS "JSON.parse" [jsonString];
+table : when parsed is
+  Ok jsValue then io.objectToTable jsValue;  // Converts immediately
+
+// CORRECT - Keep as JSValue until needed
+parsed : io.callJS "JSON.parse" [jsonString];
+// Work with JSValue directly, convert only when needed
+```
+
+For comprehensive JavaScript interop documentation, see [JavaScript Interop](./09_js-interop.md).
\ No newline at end of file