1 files changed, 407 insertions, 0 deletions
diff --git a/js/scripting-lang/README.md b/js/scripting-lang/README.md
new file mode 100644
index 0000000..a194460
--- /dev/null
+++ b/js/scripting-lang/README.md
@@ -0,0 +1,407 @@
+# Baba Yaga
+
+> *A dangerously functional scripting language with minimal syntax and maximal expressiveness*
+
+Baba Yaga is a combinator-based functional programming language designed for elegance, immutability, and expressive pattern matching. Born from an aesthetic curiosity about ML-style pattern matching, it has evolved into a complete functional programming environment with a focus on simplicity and power.
+
+## Language Philosophy
+
+- **Minimal Syntax**: Less code is better code. Every construct serves a clear purpose.
+- **Purely Functional**: Immutable data structures, function composition, and side-effect isolation.
+- **Pattern Matching First**: Conditional logic through expressive `when...is` expressions.
+- **Tables Only**: Single, flexible Lua-like data structure serving as arrays, objects, and more.
+- **Combinator-Heavy**: Rich standard library of functional combinators for data transformation.
+
+## Quick Start
+
+### Hello World
+```baba-yaga
+/* Your first Baba Yaga program */
+..out "Hello, World!";
+```
+
+### Factorial with Pattern Matching
+```baba-yaga
+factorial : n -> 
+  when n is
+    0 then 1
+    _ then n * (factorial (n - 1));
+
+result : factorial 5;
+..out result; /* Outputs: 120 */
+```
+
+### Table Operations
+```baba-yaga
+/* Tables are the only data structure */
+person : {name: "Alice", age: 30, active: true};
+numbers : {1, 2, 3, 4, 5};
+
+/* Functional table transformations */
+doubled : t.map (x -> x * 2) numbers;
+adults : filter (p -> p.age >= 18) people_list;
+total : reduce (x y -> x + y) 0 numbers;
+```
+
+## Core Language Features
+
+### 1. **Function Definitions**
+```baba-yaga
+/* Simple function */
+double : x -> x * 2;
+
+/* Multi-parameter function */
+add : x y -> x + y;
+
+/* Nested function with local scope */
+make_adder : n -> x -> x + n;
+add_five : make_adder 5;
+```
+
+### 2. **Pattern Matching**
+```baba-yaga
+/* Basic pattern matching */
+classify : grade -> when grade is
+  90 then "A"
+  80 then "B" 
+  70 then "C"
+  _ then "F";
+
+/* Multi-parameter patterns */
+compare : x y -> when x y is
+  0 0 then "both zero"
+  _ 0 then "y is zero"
+  0 _ then "x is zero"
+  _ _ then "neither zero";
+
+/* Table pattern matching */
+process_user : user -> when user is
+  {status: "admin"} then "Admin access granted"
+  {status: "user", verified: true} then "User access granted"
+  _ then "Access denied";
+```
+
+### 3. **Tables (Lua-like)**
+```baba-yaga
+/* Array-like tables */
+numbers : {1, 2, 3, 4, 5};
+first : numbers[1];  /* 1-indexed */
+
+/* Object-like tables */
+person : {name: "Bob", age: 25};
+name : person.name;
+
+/* Mixed tables */
+mixed : {1: "first", name: "Alice", 2: "second"};
+
+/* Nested tables */
+company : {
+  name: "TechCorp",
+  employees: {
+    {name: "Alice", role: "Engineer"},
+    {name: "Bob", role: "Designer"}
+  }
+};
+```
+
+### 4. **Function References & Composition**
+```baba-yaga
+/* Function references with @ */
+double_ref : @double;
+result : double_ref 5; /* 10 */
+
+/* Function composition */
+increment : x -> x + 1;
+composed : compose @double @increment 5; /* double(increment(5)) = 12 */
+piped : pipe @increment @double 5; /* increment(double(5)) = 11 */
+
+/* Partial application */
+add_ten : add 10;  /* Partially applied function */
+result : add_ten 5; /* 15 */
+```
+
+### 5. **Immutable Table Operations**
+```baba-yaga
+/* t.* namespace for table operations */
+original : {name: "Alice", age: 30};
+
+/* All operations return new tables */
+updated : t.set original "age" 31;
+deleted : t.delete original "age";
+merged : t.merge original {city: "NYC"};
+
+/* Functional transformations */
+numbers : {1, 2, 3, 4, 5};
+doubled : t.map (x -> x * 2) numbers;
+evens : t.filter (x -> x % 2 = 0) numbers;
+sum : t.reduce (x y -> x + y) 0 numbers;
+
+/* Table metadata */
+shape : t.shape numbers; /* {size: 5, type: "array"} */
+has_name : t.has original "name"; /* true */
+length : t.length original; /* 2 */
+```
+
+### 6. **IO Operations**
+```baba-yaga
+/* Output */
+..out "Hello";
+..out 42;
+..out {name: "Alice"};
+
+/* Input (context-dependent) */
+input_value : ..listen;
+
+/* Assertions for testing */
+..assert 2 + 2 = 4;
+..assert factorial 5 = 120;
+
+/* Event emission (for integration) */
+..emit "user_logged_in" {user_id: 123};
+```
+
+## Style Guide & Best Practices
+
+### **Naming Conventions**
+```baba-yaga
+/* Variables: snake_case */
+user_count : 42;
+max_retries : 3;
+
+/* Functions: descriptive verbs */
+calculate_tax : amount -> amount * 0.08;
+validate_email : email -> /* validation logic */;
+
+/* Constants: ALL_CAPS (when obvious) */
+PI : 3.14159;
+MAX_CONNECTIONS : 100;
+```
+
+### **Function Design**
+```baba-yaga
+/* DO: Good: Pure, composable functions */
+add_tax : rate amount -> amount * (1 + rate);
+format_currency : amount -> "$" + amount;
+
+/* DO: Good: Single responsibility */
+is_adult : person -> person.age >= 18;
+get_adult_names : people -> 
+  map (p -> p.name) (filter @is_adult people);
+
+/* DON'T: Avoid: Complex nested logic */
+/* Use helper functions instead */
+```
+
+### **Pattern Matching Style**
+```baba-yaga
+/* DO: Good: Exhaustive patterns */
+handle_response : response -> when response is
+  {status: 200, data: data} then process_success data
+  {status: 404} then handle_not_found
+  {status: _} then handle_error response
+  _ then handle_unexpected response;
+
+/* DO: Good: Guard patterns for ranges */
+categorize_age : age -> when (age < 13) is
+  true then "child"
+  false then when (age < 20) is 
+    true then "teen"
+    false then when (age < 65) is
+      true then "adult"
+      false then "senior";
+```
+
+### **Table Operations**
+```baba-yaga
+/* DO: Good: Functional pipeline style */
+positive_numbers : filter (x -> x > 0) numbers;
+doubled_numbers : map (x -> x * 2) positive_numbers;
+result : reduce (x y -> x + y) 0 doubled_numbers;
+
+/* DO: Good: Immutable updates */
+user_with_login : t.set user "last_login" "2023-12-01";
+updated_user : t.set user_with_login "login_count" (user.login_count + 1);
+
+/* DON'T: Avoid: Complex nested table access */
+/* Extract to helper functions */
+```
+
+### **Error Handling**
+```baba-yaga
+/* DO: Good: Use pattern matching for error cases */
+safe_divide : x y -> when y is
+  0 then {error: "Division by zero"}
+  _ then {result: x / y};
+
+/* DO: Good: Validate inputs early */
+process_user : user -> when user is
+  {name: name, age: age} then 
+    when (age >= 0) is
+      true then {status: "valid", user: user}
+      false then {error: "Invalid age"}
+  _ then {error: "Invalid user data"};
+```
+
+## Language Limitations & Workarounds
+
+### **Parser Limitations**
+```baba-yaga
+/* DON'T: Nested lambda expressions not supported */
+/* y_comb : f -> (x -> f (x x)) (x -> f (x x)); */
+
+/* DO: Use helper functions instead */
+y_helper : f x -> f (x x);
+y_inner : f x -> y_helper f x;
+y_comb : f -> y_helper f @y_inner;
+
+/* DON'T: Complex when expressions in table literals */
+/* classifier : {
+     classify: x -> when x is
+       0 then "zero"
+       1 then "one"
+       _ then "other"
+   }; */
+
+/* DO: Define functions externally */
+classify_func : x -> when x is 0 then "zero" 1 then "one" _ then "other";
+classifier : {classify: classify_func};
+```
+
+### **When Expression Syntax**
+```baba-yaga
+/* DON'T: Direct boolean conditions */
+/* abs : x -> when x < 0 then -x; */
+
+/* DO: Explicit boolean patterns */
+abs : x -> when (x < 0) is 
+  true then -x 
+  _ then x;
+```
+
+### **No Array Literals**
+```baba-yaga
+/* DON'T: Array syntax not supported */
+/* list : [1, 2, 3]; */
+
+/* DO: Use table syntax */
+list : {1, 2, 3};
+
+/* DON'T: Array concatenation */
+/* result : list concat [4, 5]; */
+
+/* DO: Use table operations */
+result : t.append (t.append list 4) 5;
+/* Or use a helper function for multiple appends */
+```
+
+## Standard Library Highlights
+
+### **Combinators**
+```baba-yaga
+/* map, filter, reduce - work on tables */
+doubled : map (x -> x * 2) numbers;
+evens : filter (x -> x % 2 = 0) numbers;
+sum : reduce (x y -> x + y) 0 numbers;
+
+/* Function composition */
+f_g : compose @f @g;
+g_f : pipe @g @f;
+applied : apply @f x;
+
+/* Currying and partial application */
+add_ten : add 10;
+multiply_by : flip @multiply;
+```
+
+### **Table Operations (t. namespace)**
+```baba-yaga
+/* Core operations */
+length : t.length table;
+has_key : t.has table "key";
+value : t.get table "key" "default";
+
+/* Transformations */
+mapped : t.map @function table;
+filtered : t.filter @predicate table;
+reduced : t.reduce @combiner initial table;
+
+/* Updates (immutable) */
+updated : t.set table "key" value;
+removed : t.delete table "key";
+combined : t.merge table1 table2;
+
+/* New operations */
+shape : t.shape table; /* {size: N, type: "array"|"object"} */
+extended : t.append table value;
+prefixed : t.prepend table value;
+```
+
+### **Utilities**
+```baba-yaga
+/* Arithmetic with type coercion */
+"Alice" + 10;     /* "Alice10" - string concatenation */
+true + 10;        /* 11 - boolean to number */
+30 + 12;          /* 42 - numeric addition */
+
+/* Logical operations with truthiness */
+result : 1 and 1;     /* true */
+result : 0 or "text"; /* "text" */
+result : not false;   /* true */
+```
+
+## Integration Patterns
+
+### **Side-Effect Isolation**
+```baba-yaga
+/* Pure functional core */
+process_data : data ->
+  calculate (transform (validate data));
+
+/* Side effects at boundaries */
+main : input_data ->
+  result : process_data input_data;
+  ..emit "data_processed" result;
+```
+
+### **Testing Pattern**
+```baba-yaga
+/* Test with assertions */
+test_factorial : ->
+  ..assert factorial 0 = 1
+  ..assert factorial 5 = 120
+  ..assert factorial 1 = 1;
+
+/* Property testing */
+test_reverse_property : list ->
+  ..assert (reverse (reverse list)) = list;
+```
+
+## Implementation Status
+
+- **JavaScript**: Reference implementation (100% complete)
+- **C**: Production implementation (97.1% test compatibility)
+- **Shared Test Suite**: 34/35 tests passing (97.1% success rate)
+
+## Further Reading
+
+- **Detailed Tutorials**: `js/tutorials/` - Comprehensive language guide
+- **API Reference**: `js/tutorials/11_Standard_Library.md` - Complete function reference  
+- **Advanced Patterns**: `js/tutorials/14_Advanced_Combinators.md` - Complex functional patterns
+- **Integration Guide**: `js/tutorials/15_Integration_Patterns.md` - Using Baba Yaga in larger systems
+
+## Philosophy & Design
+
+Baba Yaga emerged from a simple question: *What if pattern matching was the primary control flow mechanism?* 
+
+The language embraces:
+- **Functional purity** with controlled side effects
+- **Immutable data** with efficient operations  
+- **Combinator composition** over imperative loops
+- **Expression-based** rather than statement-based syntax
+- **Minimal but powerful** standard library
+
+The result is a language that encourages thinking in terms of data transformations and function composition, leading to more declarative and maintainable code.
+
+---
+
+*"In the deep dark woods, where functions compose and data flows immutably, there lives Baba Yaga - a language both beautiful and dangerous, simple yet powerful."*
\ No newline at end of file