1 files changed, 130 insertions, 0 deletions
diff --git a/js/baba-yaga/docs/01_functional.md b/js/baba-yaga/docs/01_functional.md
index 92e7f11..ac8134e 100644
--- a/js/baba-yaga/docs/01_functional.md
+++ b/js/baba-yaga/docs/01_functional.md
@@ -31,6 +31,37 @@ evens   : filter (x -> x % 2 = 0) [1, 2, 3, 4, 5]; // [2, 4]
 sum     : reduce (acc x -> acc + x) 0 [1, 2, 3, 4]; // 10
 ```
 
+## Advanced Data Operations
+
+Enhanced utilities for sorting and grouping:
+```baba
+// Custom sorting with key functions
+students : [
+  {name: "Alice", grade: 85},
+  {name: "Bob", grade: 92},
+  {name: "Charlie", grade: 78}
+];
+byGrade : sort.by students (s -> s.grade);  // Sorted by grade: Charlie, Alice, Bob
+
+// Grouping data by criteria
+ages : [18, 25, 17, 30, 16, 45];
+byCategory : group.by ages (age -> 
+  when (age < 18) is
+    true then "minor"
+    _ then when (age < 65) is
+      true then "adult"
+      _ then "senior"
+);
+minors : byCategory."minor";    // [17, 16]
+adults : byCategory."adult";    // [18, 25, 30, 45]
+
+// Array processing utilities
+data : [1, 2, 3, 4, 5, 6, 7, 8];
+chunks : chunk data 3;         // [[1, 2, 3], [4, 5, 6], [7, 8]]
+sequence : range 0 4;          // [0, 1, 2, 3, 4]
+repeated : repeat 3 "x";       // ["x", "x", "x"]
+```
+
 ## Local Bindings with `with`
 
 Stage local bindings in a function header right after the arrow. Entries are processed left-to-right in an inner scope. You can type locals using the same style as globals.
@@ -99,7 +130,106 @@ math : {
 resAdd : math.add 2 3; // 5
 ```
 
+## Advanced Array Programming
+
+Baba Yaga includes powerful array programming features inspired by APL, K, and Q:
+
+### Scan Operations (Cumulative Operations)
+```baba
+// General scan operation
+numbers : [1, 2, 3, 4, 5];
+addFunc : acc x -> acc + x;
+scanned : scan addFunc 0 numbers;  // [0, 1, 3, 6, 10, 15]
+
+// Built-in utilities
+cumsum : cumsum numbers;           // [0, 1, 3, 6, 10, 15]
+cumprod : cumprod numbers;         // [1, 1, 2, 6, 24, 120]
+```
+
+### Advanced Array Indexing
+```baba
+data : [10, 21, 30, 43, 50];
+
+// Select elements at specific indices
+indices : [0, 2, 4];
+selected : at indices data;        // [10, 30, 50]
+
+// Find indices where predicate is true
+evenPredicate : x -> x % 2 = 0;
+evenIndices : where evenPredicate data;  // [0, 2, 4]
+
+// Take and drop elements
+firstThree : take 3 data;          // [10, 21, 30]
+lastTwo : drop 3 data;             // [43, 50]
+```
+
+### Array Broadcasting Operations
+```baba
+// Broadcast scalar operation over array
+addOp : x y -> x + y;
+numbers : [1, 2, 3, 4];
+broadcasted : broadcast addOp 10 numbers;  // [11, 12, 13, 14]
+
+// Element-wise operations between arrays
+array1 : [1, 2, 3];
+array2 : [10, 20, 30];
+zipped : zipWith addOp array1 array2;      // [11, 22, 33]
+
+// Reshape arrays into matrices
+flatArray : [1, 2, 3, 4, 5, 6];
+matrix : reshape [2, 3] flatArray;         // 2x3 matrix
+```
+
+### Enhanced Function Combinators
+```baba
+// Flip function arguments
+add : x y -> x + y;
+flippedAdd : flip add;
+result : flippedAdd 3 5;           // 8 (same as 5 + 3)
+
+// Apply function to value
+double : x -> x * 2;
+result : apply double 7;           // 14
+
+// Pipe value through function (reverse apply)
+result : pipe 5 double;            // 10
+
+// Function composition
+increment : x -> x + 1;
+composed : compose increment double;
+result : composed 4;               // 9 (double then increment)
+```
+
+### Monadic Operations
+```baba
+// flatMap for flattening mapped results
+duplicateFunc : x -> [x, x];
+original : [1, 2, 3];
+duplicated : flatMap duplicateFunc original;  // [1, 1, 2, 2, 3, 3]
+
+// Chain operations that produce lists
+rangeFunc : x -> range 1 x;
+chained : flatMap rangeFunc [2, 3];          // [1, 2, 1, 2, 3]
+```
+
+## Pattern Guards
+
+Pattern matching can be enhanced with conditional guards using the `if` keyword. For detailed documentation and examples, see [Pattern Matching](./03_pattern-matching.md#pattern-guards).
+
+```baba
+// Example: Age categorization with guards
+categorizeAge : age ->
+  when age is
+    a if (a >= 0 and a < 18) then "minor"
+    a if (a >= 18 and a < 65) then "adult" 
+    a if (a >= 65) then "senior"
+    _ then "invalid";
+```
+
 ## On Style
 
 - Prefer small, pure functions
 - Build complex behavior by composing simple functions
+- Use array programming operations for data transformation
+- Leverage pattern guards for complex conditional logic
+- Combine scan, broadcast, and flatMap for powerful data processing pipelines