1 files changed, 85 insertions, 0 deletions
diff --git a/js/baba-yaga/docs/02_data-structures.md b/js/baba-yaga/docs/02_data-structures.md
index ebd39cf..aa41ed9 100644
--- a/js/baba-yaga/docs/02_data-structures.md
+++ b/js/baba-yaga/docs/02_data-structures.md
@@ -28,11 +28,96 @@ res : calculator.add 10 5; // 15
 ```
 
 ## Utilities
+
+### Core Utilities
 ```baba
 length : Built-in; works on lists and strings
 shape  : Built-in; returns a metadata table for lists, strings, tables, scalars
 ```
 
+### Array Programming Operations
+
+Baba Yaga provides powerful array programming operations inspired by APL, K, and Q:
+
+#### Indexing and Selection
+```baba
+data : [10, 20, 30, 40, 50];
+
+// Select elements at specific indices
+selected : at [0, 2, 4] data;        // [10, 30, 50]
+
+// Find indices where predicate is true
+evenIndices : where (x -> x % 2 = 0) data;  // [0, 1, 2, 3, 4]
+
+// Take first n elements
+firstThree : take 3 data;            // [10, 20, 30]
+
+// Drop first n elements  
+lastTwo : drop 3 data;               // [40, 50]
+```
+
+#### Cumulative Operations
+```baba
+numbers : [1, 2, 3, 4, 5];
+
+// General scan operation
+addFunc : acc x -> acc + x;
+scanned : scan addFunc 0 numbers;    // [0, 1, 3, 6, 10, 15]
+
+// Cumulative sum and product utilities
+cumSum : cumsum numbers;             // [0, 1, 3, 6, 10, 15]
+cumProd : cumprod numbers;           // [1, 1, 2, 6, 24, 120]
+```
+
+#### Broadcasting and Element-wise Operations
+```baba
+values : [1, 2, 3, 4];
+
+// Apply scalar operation to each element
+addTen : broadcast (x y -> x + y) 10 values;  // [11, 12, 13, 14]
+
+// Element-wise operations on two arrays
+array1 : [1, 2, 3];
+array2 : [4, 5, 6];
+multiplied : zipWith (x y -> x * y) array1 array2;  // [4, 10, 18]
+
+// Reshape flat array into matrix
+flatData : [1, 2, 3, 4, 5, 6];
+matrix : reshape [2, 3] flatData;    // 2x3 matrix
+```
+
+#### Monadic Operations
+```baba
+// flatMap for flattening mapped results
+duplicator : x -> [x, x];
+original : [1, 2, 3];
+flattened : flatMap duplicator original;  // [1, 1, 2, 2, 3, 3]
+```
+
+### Traditional Data Processing Utilities
+```baba
+// Array manipulation
+numbers : [1, 2, 3, 4, 5, 6];
+grouped : chunk numbers 2;        // [[1, 2], [3, 4], [5, 6]]
+sequence : range 1 10;            // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+duplicated : repeat 4 "item";     // ["item", "item", "item", "item"]
+
+// Sorting and grouping
+people : [{name: "Alice", age: 30}, {name: "Bob", age: 25}];
+sorted : sort.by people (p -> p.age);     // Sorted by age
+grouped : group.by people (p -> p.age > 27); // Group by age criteria
+
+// Data validation
+valid : validate.notEmpty numbers;        // true
+inRange : validate.range 1 10 5;         // true
+correctType : validate.type "List" numbers; // true
+
+// Text processing
+text : "hello world example";
+words : text.words text;                 // ["hello", "world", "example"]
+padded : text.padLeft 15 "centered";     // "     centered"
+```
+
 ## Shape
 `shape` returns a metadata table describing the argument. It is similar in spirit to APL's shape (⍴) but returns a table with fields.