IncludeCPP 3.7.12__py3-none-any.whl → 3.7.14__py3-none-any.whl

includecpp/core/cssl/cssl_builtins.pyi

@@ -1,90 +1,181 @@
 """
-CSSL Built-in Functions Type Stubs
-===================================
+CSSL Built-in Functions - Complete Type Stubs & Documentation
+==============================================================
 
-This file provides type hints and documentation for all CSSL built-in functions.
-Total: 150+ functions across 15 categories.
+This file provides comprehensive type hints and documentation for all CSSL
+built-in functions and container types. All are available in CSSL scripts
+without imports.
+
+Total: 200+ functions + 9 container classes across 19 categories.
 
 Categories:
-- Output Functions (6)
-- Type Conversion (6)
-- Type Checking (8)
-- String Operations (22)
-- Array/List Operations (17)
-- Dictionary Operations (13)
-- Math Functions (26)
-- Date/Time Functions (7)
-- File System Functions (23)
-- JSON Functions (13)
-- Instance Introspection (8)
-- Regex Functions (4)
-- Hash Functions (3)
-- System/Control Functions (15)
-- CSSL-Specific Functions (10)
+    - Output Functions (7)
+    - Type Conversion (6)
+    - Type Checking (9)
+    - String Operations (30)
+    - Array/List Operations (25)
+    - Dictionary Operations (15)
+    - Math Functions (28)
+    - Date/Time Functions (8)
+    - File System Functions (23)
+    - JSON Functions (12) - json:: namespace
+    - Instance Introspection (9) - instance:: namespace
+    - Regex Functions (4)
+    - Hash Functions (3)
+    - System/Control Functions (18)
+    - Platform Detection (3)
+    - Container Classes (9) - stack<T>, vector<T>, array<T>, map<K,V>, etc.
+    - Function Keywords (10)
+    - Classes & OOP
+    - Special Syntax Reference
+
+Container Types with Methods (use lowercase names for quick lookup):
+    - stack: stack<T> - LIFO with push(), pop(), peek(), etc.
+    - vector: vector<T> - Dynamic array with at(), front(), back(), etc.
+    - array: array<T> - Standard array with similar methods
+    - map: map<K,V> - Ordered key-value with insert(), find(), erase(), etc.
+    - datastruct: datastruct<T> - Universal container for BruteInjection
+    - iterator: iterator<T> - Programmable with insert(), fill(), at()
+    - shuffled: shuffled<T> - Multi-value returns
+    - combo: combo<T> - Filter/search space
+    - dataspace: dataspace<T> - SQL-like data storage
+
+Type "vector." to see all available methods with documentation.
+
+Usage from Python:
+    from includecpp import CSSL
+
+    CSSL.run('''
+        stack<string> names;
+        names.push("Alice");
+        names.push("Bob");
+        printl(names.pop());  // "Bob"
+    ''')
 """
 
-from typing import Any, List, Dict, Optional, Callable, Union, Tuple
+from typing import Any, List, Dict, Optional, Callable, Union, Tuple, TypeVar
+
+T = TypeVar('T')
 
 # =============================================================================
 # OUTPUT FUNCTIONS
 # =============================================================================
 
 def print(*args: Any, sep: str = " ", end: str = "") -> None:
-    """Print values without newline.
+    """Print values without trailing newline.
+
+    Outputs text to the console without automatically adding a newline at the end.
+    Multiple arguments are joined with the separator.
 
     Args:
-        *args: Values to print
-        sep: Separator between values (default: space)
-        end: String appended after last value (default: empty)
+        *args: Values to print (any type, automatically converted to string)
+        sep: Separator between values (default: single space)
+        end: String appended after output (default: empty string)
 
     Example:
-        print("Hello", "World");  // Output: Hello World
+        print("Loading");
+        print(".");
+        print(".");
+        printl("Done!");
+        // Output: Loading...Done!
+
+        print("A", "B", "C", sep="-");
+        // Output: A-B-C
     """
     ...
 
 def printl(*args: Any, sep: str = " ") -> None:
-    """Print values with newline (primary CSSL print function).
+    """Print values with trailing newline (primary CSSL output function).
+
+    The most commonly used output function in CSSL. Prints values followed
+    by a newline character. Automatically converts all types to strings.
 
     Args:
-        *args: Values to print
-        sep: Separator between values (default: space)
+        *args: Values to print (any type)
+        sep: Separator between multiple values (default: space)
 
     Example:
-        printl("Hello World");  // Output: Hello World\\n
+        printl("Hello World");
+        // Output: Hello World
+
+        string name = "Alice";
+        int age = 30;
+        printl("Name:", name, "Age:", age);
+        // Output: Name: Alice Age: 30
+
+        // String concatenation also works:
+        printl("Value: " + 42);  // Auto-conversion
+        // Output: Value: 42
     """
     ...
 
 def println(*args: Any, sep: str = " ") -> None:
-    """Alias for printl. Print values with newline."""
+    """Alias for printl(). Print values with newline."""
     ...
 
 def debug(*args: Any) -> None:
     """Print debug information with [DEBUG] prefix.
 
+    Useful for development and troubleshooting. Output is prefixed
+    with [DEBUG] to distinguish from regular output.
+
     Args:
         *args: Debug values to display
 
     Example:
-        debug("Variable x =", x);  // Output: [DEBUG] Variable x = 42
+        int x = 42;
+        debug("Variable x =", x);
+        // Output: [DEBUG] Variable x = 42
+
+        debug("Entering function processData()");
+        debug("items.length =", len(items));
     """
     ...
 
 def error(*args: Any) -> None:
     """Print error message with [ERROR] prefix.
 
+    Used for reporting errors. Output is prefixed with [ERROR].
+    Does NOT throw an exception - just prints the message.
+
     Args:
         *args: Error message components
 
     Example:
         error("File not found:", path);
+        // Output: [ERROR] File not found: /path/to/file.txt
+
+        if (!pathexists(file)) {
+            error("Cannot read file:", file);
+        }
     """
     ...
 
 def warn(*args: Any) -> None:
     """Print warning message with [WARN] prefix.
 
+    Used for non-critical issues that should be noted.
+    Output is prefixed with [WARN].
+
     Args:
         *args: Warning message components
+
+    Example:
+        warn("Configuration file missing, using defaults");
+        // Output: [WARN] Configuration file missing, using defaults
+    """
+    ...
+
+def log(level: str, *args: Any) -> None:
+    """Print message with custom log level prefix.
+
+    Args:
+        level: Log level string (e.g., "INFO", "TRACE", "VERBOSE")
+        *args: Message components
+
+    Example:
+        log("INFO", "Server started on port", 8080);
+        // Output: [INFO] Server started on port 8080
     """
     ...
 
@@ -92,19 +183,27 @@ def warn(*args: Any) -> None:
 # TYPE CONVERSION FUNCTIONS
 # =============================================================================
 
-def int(value: Any) -> int:
+def int(value: Any, base: int = 10) -> int:
     """Convert value to integer.
 
+    Converts strings, floats, or booleans to integer representation.
+    For strings, optionally specify the numeric base.
+
     Args:
         value: Value to convert (string, float, bool)
+        base: Numeric base for string conversion (default: 10)
 
     Returns:
-        Integer representation
+        Integer representation of the value
 
     Example:
-        int("42");     // 42
-        int(3.14);     // 3
-        int(true);     // 1
+        int("42");        // 42
+        int(3.14);        // 3 (truncated, not rounded)
+        int(3.9);         // 3
+        int(true);        // 1
+        int(false);       // 0
+        int("ff", 16);    // 255 (hexadecimal)
+        int("1010", 2);   // 10 (binary)
     """
     ...
 
@@ -112,35 +211,46 @@ def float(value: Any) -> float:
     """Convert value to floating-point number.
 
     Args:
-        value: Value to convert
+        value: Value to convert (string, int, bool)
 
     Returns:
-        Float representation
+        Float representation of the value
 
     Example:
-        float("3.14");  // 3.14
-        float(42);      // 42.0
+        float("3.14");    // 3.14
+        float(42);        // 42.0
+        float("1e-5");    // 0.00001 (scientific notation)
+        float(true);      // 1.0
     """
     ...
 
 def str(value: Any) -> str:
-    """Convert value to string.
+    """Convert value to string representation.
 
     Args:
-        value: Value to convert
+        value: Any value to convert
 
     Returns:
         String representation
 
     Example:
-        str(42);       // "42"
-        str(true);     // "True"
+        str(42);          // "42"
+        str(3.14);        // "3.14"
+        str(true);        // "True"
+        str([1, 2, 3]);   // "[1, 2, 3]"
     """
     ...
 
 def bool(value: Any) -> bool:
     """Convert value to boolean.
 
+    Conversion rules:
+    - Empty string "", "0", "false", "no", "null", "none" -> false
+    - Any other non-empty string -> true
+    - 0 -> false, any other number -> true
+    - Empty list/dict -> false, non-empty -> true
+    - null/None -> false
+
     Args:
         value: Value to convert
 
@@ -148,9 +258,13 @@ def bool(value: Any) -> bool:
         Boolean representation
 
     Example:
-        bool(1);       // true
-        bool("");      // false
-        bool("text");  // true
+        bool(1);          // true
+        bool(0);          // false
+        bool("");         // false
+        bool("text");     // true
+        bool("false");    // false (special case)
+        bool([]);         // false
+        bool([1, 2]);     // true
     """
     ...
 
@@ -158,14 +272,17 @@ def list(value: Any = None) -> List[Any]:
     """Convert value to list or create empty list.
 
     Args:
-        value: Optional value to convert (string, iterable)
+        value: Optional value to convert (string splits to chars,
+               dict converts to list of tuples)
 
     Returns:
         List representation
 
     Example:
-        list("abc");     // ["a", "b", "c"]
-        list();          // []
+        list();               // []
+        list("abc");          // ["a", "b", "c"]
+        list((1, 2, 3));      // [1, 2, 3]
+        list({"a": 1});       // [("a", 1)]
     """
     ...
 
@@ -173,10 +290,14 @@ def dict(value: Any = None) -> Dict[str, Any]:
     """Convert value to dictionary or create empty dict.
 
     Args:
-        value: Optional value to convert
+        value: Optional value to convert (list of tuples)
 
     Returns:
         Dictionary representation
+
+    Example:
+        dict();                       // {}
+        dict([("a", 1), ("b", 2)]);  // {"a": 1, "b": 2}
     """
     ...
 
@@ -185,59 +306,116 @@ def dict(value: Any = None) -> Dict[str, Any]:
 # =============================================================================
 
 def typeof(value: Any) -> str:
-    """Get type name of value.
+    """Get the type name of a value as string.
 
     Args:
         value: Value to check
 
     Returns:
-        Type name as string
+        Type name: "int", "float", "str", "bool", "list", "dict", "null"
 
     Example:
-        typeof(42);        // "int"
-        typeof("hello");   // "str"
-        typeof([1,2,3]);   // "list"
+        typeof(42);           // "int"
+        typeof(3.14);         // "float"
+        typeof("hello");      // "str"
+        typeof(true);         // "bool"
+        typeof([1, 2, 3]);    // "list"
+        typeof({"a": 1});     // "dict"
+        typeof(null);         // "null"
     """
     ...
 
 def isinstance(value: Any, type_name: str) -> bool:
-    """Check if value is instance of type.
+    """Check if value is instance of specified type.
 
     Args:
         value: Value to check
-        type_name: Type name string
+        type_name: Type name string ("int", "float", "str", "bool",
+                   "list", "dict", "null")
 
     Returns:
-        True if value is instance of type
+        True if value matches the type
+
+    Example:
+        isinstance(42, "int");           // true
+        isinstance("hello", "str");      // true
+        isinstance([1, 2], "list");      // true
+        isinstance(null, "null");        // true
     """
     ...
 
 def isint(value: Any) -> bool:
-    """Check if value is an integer."""
+    """Check if value is an integer.
+
+    Note: Returns false for booleans even though bool is subclass of int.
+
+    Example:
+        isint(42);       // true
+        isint(3.14);     // false
+        isint("42");     // false
+        isint(true);     // false
+    """
     ...
 
 def isfloat(value: Any) -> bool:
-    """Check if value is a float."""
+    """Check if value is a floating-point number.
+
+    Example:
+        isfloat(3.14);   // true
+        isfloat(42);     // false
+        isfloat(42.0);   // true
+    """
     ...
 
 def isstr(value: Any) -> bool:
-    """Check if value is a string."""
+    """Check if value is a string.
+
+    Example:
+        isstr("hello");  // true
+        isstr(42);       // false
+        isstr("");       // true
+    """
     ...
 
 def isbool(value: Any) -> bool:
-    """Check if value is a boolean."""
+    """Check if value is a boolean.
+
+    Example:
+        isbool(true);    // true
+        isbool(false);   // true
+        isbool(1);       // false
+        isbool("true");  // false
+    """
     ...
 
 def islist(value: Any) -> bool:
-    """Check if value is a list/array."""
+    """Check if value is a list/array.
+
+    Example:
+        islist([1, 2, 3]);   // true
+        islist("abc");       // false
+        islist([]);          // true
+    """
     ...
 
 def isdict(value: Any) -> bool:
-    """Check if value is a dictionary."""
+    """Check if value is a dictionary.
+
+    Example:
+        isdict({"a": 1});    // true
+        isdict([]);          // false
+    """
     ...
 
 def isnull(value: Any) -> bool:
-    """Check if value is null/None."""
+    """Check if value is null/None.
+
+    Example:
+        isnull(null);        // true
+        isnull(None);        // true
+        isnull("");          // false
+        isnull(0);           // false
+    """
     ...
 
 # =============================================================================
@@ -248,14 +426,17 @@ def len(value: Union[str, List, Dict]) -> int:
     """Get length of string, list, or dictionary.
 
     Args:
-        value: String, list, or dictionary
+        value: String (returns character count), list (element count),
+               or dictionary (key count)
 
     Returns:
-        Number of characters/elements/keys
+        Number of items
 
     Example:
-        len("hello");     // 5
-        len([1,2,3]);     // 3
+        len("hello");         // 5
+        len([1, 2, 3]);       // 3
+        len({"a": 1, "b": 2}); // 2
+        len("");              // 0
     """
     ...
 
@@ -263,7 +444,8 @@ def upper(s: str) -> str:
     """Convert string to uppercase.
 
     Example:
-        upper("hello");  // "HELLO"
+        upper("hello");       // "HELLO"
+        upper("Hello World"); // "HELLO WORLD"
     """
     ...
 
@@ -271,79 +453,103 @@ def lower(s: str) -> str:
     """Convert string to lowercase.
 
     Example:
-        lower("HELLO");  // "hello"
+        lower("HELLO");       // "hello"
+        lower("Hello World"); // "hello world"
     """
     ...
 
-def trim(s: str) -> str:
-    """Remove whitespace from both ends of string.
+def trim(s: str, chars: str = None) -> str:
+    """Remove whitespace (or specified chars) from both ends.
+
+    Args:
+        s: String to trim
+        chars: Optional specific characters to remove
 
     Example:
-        trim("  hello  ");  // "hello"
+        trim("  hello  ");         // "hello"
+        trim("...hello...", "."); // "hello"
+        trim("\\n\\thello\\n");    // "hello"
     """
     ...
 
-def ltrim(s: str) -> str:
-    """Remove whitespace from left side of string."""
+def ltrim(s: str, chars: str = None) -> str:
+    """Remove whitespace (or specified chars) from left side only.
+
+    Example:
+        ltrim("  hello  ");   // "hello  "
+    """
     ...
 
-def rtrim(s: str) -> str:
-    """Remove whitespace from right side of string."""
+def rtrim(s: str, chars: str = None) -> str:
+    """Remove whitespace (or specified chars) from right side only.
+
+    Example:
+        rtrim("  hello  ");   // "  hello"
+    """
     ...
 
-def split(s: str, delimiter: str = " ") -> List[str]:
+def split(s: str, delimiter: str = None, maxsplit: int = -1) -> List[str]:
     """Split string into list by delimiter.
 
     Args:
         s: String to split
-        delimiter: Split delimiter (default: space)
+        delimiter: Split character/string (default: whitespace)
+        maxsplit: Maximum number of splits (-1 for unlimited)
 
     Returns:
         List of substrings
 
     Example:
-        split("a,b,c", ",");  // ["a", "b", "c"]
+        split("a,b,c", ",");          // ["a", "b", "c"]
+        split("hello world");          // ["hello", "world"]
+        split("a-b-c-d", "-", 2);     // ["a", "b", "c-d"]
     """
     ...
 
-def join(arr: List[str], delimiter: str = "") -> str:
-    """Join list elements into string.
+def join(delimiter: str, items: List[str]) -> str:
+    """Join list elements into string with delimiter.
 
     Args:
-        arr: List of strings
-        delimiter: Join delimiter
+        delimiter: String to place between elements
+        items: List of strings to join
 
     Returns:
         Joined string
 
     Example:
-        join(["a", "b", "c"], "-");  // "a-b-c"
+        join("-", ["a", "b", "c"]);   // "a-b-c"
+        join(", ", ["Alice", "Bob"]); // "Alice, Bob"
+        join("", ["H", "i"]);         // "Hi"
     """
     ...
 
-def replace(s: str, old: str, new: str) -> str:
-    """Replace all occurrences of substring.
+def replace(s: str, old: str, new: str, count: int = -1) -> str:
+    """Replace occurrences of substring.
 
     Args:
         s: Original string
-        old: Substring to replace
+        old: Substring to find
         new: Replacement string
+        count: Max replacements (-1 for all)
 
     Example:
-        replace("hello", "l", "x");  // "hexxo"
+        replace("hello", "l", "x");       // "hexxo"
+        replace("aaa", "a", "b", 2);      // "bba"
     """
     ...
 
 def substr(s: str, start: int, length: int = None) -> str:
-    """Extract substring.
+    """Extract substring by start position and length.
 
     Args:
         s: Original string
         start: Start index (0-based)
-        length: Number of characters (optional)
+        length: Number of characters (optional, defaults to end)
 
     Example:
-        substr("hello", 1, 3);  // "ell"
+        substr("hello", 1, 3);    // "ell"
+        substr("hello", 2);       // "llo"
+        substr("hello", 0, 1);    // "h"
     """
     ...
 
@@ -351,7 +557,9 @@ def contains(s: str, substring: str) -> bool:
     """Check if string contains substring.
 
     Example:
-        contains("hello", "ell");  // true
+        contains("hello world", "world");  // true
+        contains("hello", "xyz");          // false
+        contains("", "");                  // true
     """
     ...
 
@@ -359,7 +567,8 @@ def startswith(s: str, prefix: str) -> bool:
     """Check if string starts with prefix.
 
     Example:
-        startswith("hello", "he");  // true
+        startswith("hello", "he");     // true
+        startswith("hello", "lo");     // false
     """
     ...
 
@@ -367,27 +576,32 @@ def endswith(s: str, suffix: str) -> bool:
     """Check if string ends with suffix.
 
     Example:
-        endswith("hello", "lo");  // true
+        endswith("hello", "lo");       // true
+        endswith("hello.txt", ".txt"); // true
     """
     ...
 
 def format(template: str, *args: Any) -> str:
-    """Format string with placeholders.
+    """Format string with {} placeholders.
 
     Args:
         template: String with {} placeholders
-        *args: Values to insert
+        *args: Values to insert (in order)
 
     Example:
-        format("Hello, {}!", "World");  // "Hello, World!"
+        format("Hello, {}!", "World");           // "Hello, World!"
+        format("{} + {} = {}", 2, 3, 5);         // "2 + 3 = 5"
     """
     ...
 
 def concat(*strings: str) -> str:
-    """Concatenate multiple strings.
+    """Concatenate multiple strings efficiently.
+
+    More efficient than repeated + for many strings.
 
     Example:
-        concat("a", "b", "c");  // "abc"
+        concat("a", "b", "c");     // "abc"
+        concat("Hello", " ", "World"); // "Hello World"
     """
     ...
 
@@ -395,15 +609,17 @@ def repeat(s: str, count: int) -> str:
     """Repeat string n times.
 
     Example:
-        repeat("ab", 3);  // "ababab"
+        repeat("ab", 3);          // "ababab"
+        repeat("-", 10);          // "----------"
     """
     ...
 
 def reverse(s: str) -> str:
-    """Reverse string.
+    """Reverse string character order.
 
     Example:
-        reverse("hello");  // "olleh"
+        reverse("hello");         // "olleh"
+        reverse("12345");         // "54321"
     """
     ...
 
@@ -413,13 +629,15 @@ def indexof(s: str, substring: str, start: int = 0) -> int:
     Args:
         s: String to search in
         substring: Substring to find
-        start: Start position (default: 0)
+        start: Starting position for search (default: 0)
 
     Returns:
         Index of first occurrence, -1 if not found
 
     Example:
-        indexof("hello", "l");  // 2
+        indexof("hello", "l");        // 2
+        indexof("hello", "l", 3);     // 3
+        indexof("hello", "xyz");      // -1
     """
     ...
 
@@ -428,30 +646,42 @@ def lastindexof(s: str, substring: str) -> int:
 
     Returns:
         Index of last occurrence, -1 if not found
+
+    Example:
+        lastindexof("hello", "l");    // 3
+        lastindexof("abcabc", "bc");  // 4
     """
     ...
 
-def padleft(s: str, length: int, char: str = " ") -> str:
-    """Pad string on left to specified length.
+def padleft(s: str, width: int, char: str = " ") -> str:
+    """Pad string on left to specified width.
+
+    Args:
+        s: Original string
+        width: Target width
+        char: Padding character (default: space)
 
     Example:
-        padleft("42", 5, "0");  // "00042"
+        padleft("42", 5, "0");     // "00042"
+        padleft("hi", 6);         // "    hi"
     """
     ...
 
-def padright(s: str, length: int, char: str = " ") -> str:
-    """Pad string on right to specified length.
+def padright(s: str, width: int, char: str = " ") -> str:
+    """Pad string on right to specified width.
 
     Example:
-        padright("42", 5, "0");  // "42000"
+        padright("42", 5, "0");    // "42000"
+        padright("hi", 6);        // "hi    "
     """
     ...
 
 def capitalize(s: str) -> str:
-    """Capitalize first character.
+    """Capitalize first character of string.
 
     Example:
-        capitalize("hello");  // "Hello"
+        capitalize("hello");      // "Hello"
+        capitalize("hELLO");      // "Hello"
     """
     ...
 
@@ -459,7 +689,88 @@ def title(s: str) -> str:
     """Capitalize first character of each word.
 
     Example:
-        title("hello world");  // "Hello World"
+        title("hello world");     // "Hello World"
+        title("the quick fox");   // "The Quick Fox"
+    """
+    ...
+
+def swapcase(s: str) -> str:
+    """Swap uppercase and lowercase characters.
+
+    Example:
+        swapcase("Hello");        // "hELLO"
+        swapcase("PyThOn");       // "pYtHoN"
+    """
+    ...
+
+def center(s: str, width: int, fillchar: str = " ") -> str:
+    """Center string within specified width.
+
+    Example:
+        center("hi", 10);         // "    hi    "
+        center("hi", 10, "-");    // "----hi----"
+    """
+    ...
+
+def zfill(s: str, width: int) -> str:
+    """Pad numeric string with leading zeros.
+
+    Example:
+        zfill("42", 5);           // "00042"
+        zfill("-42", 5);          // "-0042"
+    """
+    ...
+
+def chars(s: str) -> List[str]:
+    """Convert string to list of characters.
+
+    Example:
+        chars("hello");           // ["h", "e", "l", "l", "o"]
+    """
+    ...
+
+def ord(c: str) -> int:
+    """Get ASCII/Unicode code point of character.
+
+    Example:
+        ord("A");                 // 65
+        ord("a");                 // 97
+        ord("0");                 // 48
+    """
+    ...
+
+def chr(n: int) -> str:
+    """Convert ASCII/Unicode code point to character.
+
+    Example:
+        chr(65);                  // "A"
+        chr(97);                  // "a"
+        chr(8364);                // "€"
+    """
+    ...
+
+def isalpha(s: str) -> bool:
+    """Check if string contains only alphabetic characters."""
+    ...
+
+def isdigit(s: str) -> bool:
+    """Check if string contains only digits."""
+    ...
+
+def isalnum(s: str) -> bool:
+    """Check if string contains only alphanumeric characters."""
+    ...
+
+def isspace(s: str) -> bool:
+    """Check if string contains only whitespace."""
+    ...
+
+def sprintf(fmt: str, *args: Any) -> str:
+    """C-style format string with % placeholders.
+
+    Example:
+        sprintf("%s: %d", "Count", 42);   // "Count: 42"
+        sprintf("%.2f", 3.14159);         // "3.14"
     """
     ...
 
@@ -467,133 +778,163 @@ def title(s: str) -> str:
 # ARRAY/LIST OPERATIONS
 # =============================================================================
 
-def push(arr: List[Any], value: Any) -> List[Any]:
-    """Add element to end of array.
+def push(arr: List[Any], *values: Any) -> List[Any]:
+    """Add one or more elements to end of array.
 
     Args:
         arr: Target array
-        value: Value to add
+        *values: Values to add
 
     Returns:
         Modified array
 
     Example:
-        push([1, 2], 3);  // [1, 2, 3]
+        stack<int> nums = [1, 2];
+        nums = push(nums, 3);        // [1, 2, 3]
+        nums = push(nums, 4, 5);     // [1, 2, 3, 4, 5]
     """
     ...
 
-def pop(arr: List[Any]) -> Any:
-    """Remove and return last element.
+def pop(arr: List[Any], index: int = -1) -> Any:
+    """Remove and return element at index (default: last).
+
+    Args:
+        arr: Source array (modified in place)
+        index: Index to remove (default: -1 for last element)
 
     Returns:
         Removed element
 
     Example:
-        pop([1, 2, 3]);  // 3, array becomes [1, 2]
+        stack<int> nums = [1, 2, 3];
+        int last = pop(nums);        // 3, nums is now [1, 2]
+        int first = pop(nums, 0);    // 1, nums is now [2]
     """
     ...
 
 def shift(arr: List[Any]) -> Any:
     """Remove and return first element.
 
-    Returns:
-        Removed element
+    Example:
+        stack<string> names = ["Alice", "Bob"];
+        string first = shift(names);  // "Alice", names is ["Bob"]
     """
     ...
 
-def unshift(arr: List[Any], value: Any) -> List[Any]:
-    """Add element to beginning of array.
+def unshift(arr: List[Any], *values: Any) -> List[Any]:
+    """Add elements to beginning of array.
 
-    Returns:
-        Modified array
+    Example:
+        stack<int> nums = [3, 4];
+        nums = unshift(nums, 1, 2);   // [1, 2, 3, 4]
     """
     ...
 
 def slice(arr: List[Any], start: int, end: int = None) -> List[Any]:
-    """Extract portion of array.
+    """Extract portion of array (does not modify original).
 
     Args:
         arr: Source array
-        start: Start index
+        start: Start index (inclusive)
         end: End index (exclusive, optional)
 
     Returns:
         New array with extracted elements
 
     Example:
-        slice([1, 2, 3, 4], 1, 3);  // [2, 3]
+        slice([1, 2, 3, 4, 5], 1, 4);  // [2, 3, 4]
+        slice([1, 2, 3, 4, 5], 2);     // [3, 4, 5]
+        slice([1, 2, 3, 4, 5], -2);    // [4, 5]
     """
     ...
 
-def sort(arr: List[Any]) -> List[Any]:
+def sort(arr: List[Any], key: str = None) -> List[Any]:
     """Sort array in ascending order.
 
+    Args:
+        arr: Array to sort
+        key: Optional key name for sorting dicts/objects
+
     Returns:
         Sorted array
+
+    Example:
+        sort([3, 1, 2]);              // [1, 2, 3]
+        sort(["c", "a", "b"]);        // ["a", "b", "c"]
+
+        // Sort objects by key
+        stack<json> users = [{"name": "Bob"}, {"name": "Alice"}];
+        sort(users, "name");          // [{name: "Alice"}, {name: "Bob"}]
     """
     ...
 
-def rsort(arr: List[Any]) -> List[Any]:
+def rsort(arr: List[Any], key: str = None) -> List[Any]:
     """Sort array in descending order.
 
-    Returns:
-        Reverse sorted array
+    Example:
+        rsort([1, 3, 2]);             // [3, 2, 1]
     """
     ...
 
 def unique(arr: List[Any]) -> List[Any]:
-    """Remove duplicate elements.
-
-    Returns:
-        Array with unique elements only
+    """Remove duplicate elements (preserves first occurrence order).
 
     Example:
-        unique([1, 2, 2, 3]);  // [1, 2, 3]
+        unique([1, 2, 2, 3, 1]);      // [1, 2, 3]
+        unique(["a", "b", "a"]);      // ["a", "b"]
     """
     ...
 
-def flatten(arr: List[Any]) -> List[Any]:
-    """Flatten nested arrays.
+def flatten(arr: List[Any], depth: int = 1) -> List[Any]:
+    """Flatten nested arrays to specified depth.
+
+    Args:
+        arr: Nested array
+        depth: How many levels to flatten (default: 1)
 
     Example:
-        flatten([[1, 2], [3, 4]]);  // [1, 2, 3, 4]
+        flatten([[1, 2], [3, 4]]);           // [1, 2, 3, 4]
+        flatten([[[1]], [[2]]]);             // [[1], [2]]
+        flatten([[[1]], [[2]]], 2);          // [1, 2]
     """
     ...
 
 def filter(arr: List[Any], predicate: Callable[[Any], bool]) -> List[Any]:
     """Filter array by predicate function.
 
+    Note: In CSSL, use inline conditions or lambda-like syntax.
+
     Args:
         arr: Source array
         predicate: Function returning true for elements to keep
 
     Returns:
-        Filtered array
+        Filtered array (only elements where predicate returned true)
     """
     ...
 
 def map(arr: List[Any], func: Callable[[Any], Any]) -> List[Any]:
-    """Apply function to each element.
+    """Apply transformation function to each element.
 
     Args:
         arr: Source array
         func: Transformation function
 
     Returns:
-        Transformed array
+        Array of transformed elements
     """
     ...
 
 def reduce(arr: List[Any], func: Callable[[Any, Any], Any], initial: Any = None) -> Any:
-    """Reduce array to single value.
+    """Reduce array to single value using accumulator function.
 
     Args:
         arr: Source array
-        func: Reducer function (accumulator, current) -> result
-        initial: Initial accumulator value
+        func: Reducer (accumulator, current) -> result
+        initial: Starting accumulator value
 
     Returns:
-        Reduced value
+        Final accumulated value
     """
     ...
 
@@ -601,33 +942,146 @@ def find(arr: List[Any], predicate: Callable[[Any], bool]) -> Optional[Any]:
     """Find first element matching predicate.
 
     Returns:
-        First matching element or null
+        First matching element or null if none found
     """
     ...
 
 def findindex(arr: List[Any], predicate: Callable[[Any], bool]) -> int:
-    """Find index of first matching element.
+    """Find index of first element matching predicate.
+
+    Returns:
+        Index of first match, -1 if not found
+    """
+    ...
+
+def every(arr: List[Any], predicate: Callable[[Any], bool]) -> bool:
+    """Check if ALL elements satisfy predicate.
+
+    Returns:
+        True if predicate returns true for all elements
+    """
+    ...
+
+def some(arr: List[Any], predicate: Callable[[Any], bool]) -> bool:
+    """Check if ANY element satisfies predicate.
 
     Returns:
-        Index or -1 if not found
+        True if predicate returns true for at least one element
     """
     ...
 
 def range(start_or_stop: int, stop: int = None, step: int = 1) -> List[int]:
-    """Generate range of integers.
+    """Generate list of integers in range.
 
     Args:
-        start_or_stop: Start value (or stop if only arg)
-        stop: Stop value (exclusive)
-        step: Step increment
+        start_or_stop: If only arg, this is stop (start=0). Otherwise start.
+        stop: End value (exclusive)
+        step: Increment between values (default: 1)
 
     Returns:
         List of integers
 
     Example:
-        range(5);           // [0, 1, 2, 3, 4]
-        range(1, 5);        // [1, 2, 3, 4]
-        range(0, 10, 2);    // [0, 2, 4, 6, 8]
+        range(5);               // [0, 1, 2, 3, 4]
+        range(1, 5);            // [1, 2, 3, 4]
+        range(0, 10, 2);        // [0, 2, 4, 6, 8]
+        range(10, 0, -1);       // [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
+    """
+    ...
+
+def enumerate(arr: List[Any], start: int = 0) -> List[Tuple[int, Any]]:
+    """Return list of (index, value) pairs.
+
+    Args:
+        arr: Array to enumerate
+        start: Starting index number (default: 0)
+
+    Example:
+        enumerate(["a", "b", "c"]);      // [(0, "a"), (1, "b"), (2, "c")]
+        enumerate(["a", "b"], 1);        // [(1, "a"), (2, "b")]
+    """
+    ...
+
+def zip(*arrays: List[Any]) -> List[Tuple[Any, ...]]:
+    """Combine multiple arrays into array of tuples.
+
+    Example:
+        zip([1, 2], ["a", "b"]);         // [(1, "a"), (2, "b")]
+    """
+    ...
+
+def reversed(arr: List[Any]) -> List[Any]:
+    """Return reversed copy of array.
+
+    Example:
+        reversed([1, 2, 3]);              // [3, 2, 1]
+    """
+    ...
+
+def count(collection: Union[List, str], item: Any) -> int:
+    """Count occurrences of item in list or string.
+
+    Example:
+        count([1, 2, 2, 3, 2], 2);        // 3
+        count("hello", "l");              // 2
+    """
+    ...
+
+def first(arr: List[Any], default: Any = None) -> Any:
+    """Get first element or default if empty.
+
+    Example:
+        first([1, 2, 3]);                 // 1
+        first([], "none");                // "none"
+    """
+    ...
+
+def last(arr: List[Any], default: Any = None) -> Any:
+    """Get last element or default if empty.
+
+    Example:
+        last([1, 2, 3]);                  // 3
+        last([], "none");                 // "none"
+    """
+    ...
+
+def take(arr: List[Any], n: int) -> List[Any]:
+    """Take first n elements.
+
+    Example:
+        take([1, 2, 3, 4, 5], 3);         // [1, 2, 3]
+    """
+    ...
+
+def drop(arr: List[Any], n: int) -> List[Any]:
+    """Drop first n elements, return rest.
+
+    Example:
+        drop([1, 2, 3, 4, 5], 2);         // [3, 4, 5]
+    """
+    ...
+
+def chunk(arr: List[Any], size: int) -> List[List[Any]]:
+    """Split array into chunks of specified size.
+
+    Example:
+        chunk([1, 2, 3, 4, 5], 2);        // [[1, 2], [3, 4], [5]]
+    """
+    ...
+
+def shuffle(arr: List[Any]) -> List[Any]:
+    """Return randomly shuffled copy of array.
+
+    Example:
+        shuffle([1, 2, 3, 4]);            // [3, 1, 4, 2] (random)
+    """
+    ...
+
+def sample(arr: List[Any], k: int) -> List[Any]:
+    """Return k random elements from array (without replacement).
+
+    Example:
+        sample([1, 2, 3, 4, 5], 3);       // [2, 5, 1] (random 3 elements)
     """
     ...
 
@@ -636,26 +1090,26 @@ def range(start_or_stop: int, stop: int = None, step: int = 1) -> List[int]:
 # =============================================================================
 
 def keys(d: Dict[str, Any]) -> List[str]:
-    """Get all dictionary keys.
+    """Get all keys from dictionary.
 
-    Returns:
-        List of keys
+    Example:
+        keys({"a": 1, "b": 2});           // ["a", "b"]
     """
     ...
 
 def values(d: Dict[str, Any]) -> List[Any]:
-    """Get all dictionary values.
+    """Get all values from dictionary.
 
-    Returns:
-        List of values
+    Example:
+        values({"a": 1, "b": 2});          // [1, 2]
     """
     ...
 
 def items(d: Dict[str, Any]) -> List[Tuple[str, Any]]:
-    """Get all key-value pairs.
+    """Get all key-value pairs as list of tuples.
 
-    Returns:
-        List of (key, value) tuples
+    Example:
+        items({"a": 1, "b": 2});           // [("a", 1), ("b", 2)]
     """
     ...
 
@@ -663,7 +1117,8 @@ def haskey(d: Dict[str, Any], key: str) -> bool:
     """Check if dictionary has key.
 
     Example:
-        haskey({"a": 1}, "a");  // true
+        haskey({"a": 1}, "a");             // true
+        haskey({"a": 1}, "b");             // false
     """
     ...
 
@@ -673,143 +1128,325 @@ def getkey(d: Dict[str, Any], key: str, default: Any = None) -> Any:
     Args:
         d: Dictionary
         key: Key to look up
-        default: Default value if key not found
+        default: Value to return if key not found
 
-    Returns:
-        Value or default
+    Example:
+        getkey({"a": 1}, "a", 0);          // 1
+        getkey({"a": 1}, "b", 0);          // 0
+        getkey({"a": 1}, "b");             // null
     """
     ...
 
 def setkey(d: Dict[str, Any], key: str, value: Any) -> Dict[str, Any]:
-    """Set key-value pair in dictionary.
+    """Set key-value pair in dictionary (returns modified copy).
 
-    Returns:
-        Modified dictionary
+    Example:
+        json obj = {"a": 1};
+        obj = setkey(obj, "b", 2);        // {"a": 1, "b": 2}
     """
     ...
 
 def delkey(d: Dict[str, Any], key: str) -> Dict[str, Any]:
-    """Delete key from dictionary.
+    """Delete key from dictionary (returns modified copy).
 
-    Returns:
-        Modified dictionary
+    Example:
+        json obj = {"a": 1, "b": 2};
+        obj = delkey(obj, "a");           // {"b": 2}
     """
     ...
 
 def merge(*dicts: Dict[str, Any]) -> Dict[str, Any]:
-    """Merge multiple dictionaries.
+    """Merge multiple dictionaries (later values override).
 
-    Returns:
-        Merged dictionary (later values override earlier)
+    Example:
+        merge({"a": 1}, {"b": 2}, {"a": 3});  // {"a": 3, "b": 2}
     """
     ...
 
-# =============================================================================
-# MATH FUNCTIONS
-# =============================================================================
+def update(d: Dict[str, Any], other: Dict[str, Any]) -> Dict[str, Any]:
+    """Update dictionary with another (returns new dict).
 
-def abs(x: Union[int, float]) -> Union[int, float]:
-    """Absolute value."""
+    Example:
+        update({"a": 1}, {"b": 2});        // {"a": 1, "b": 2}
+    """
     ...
 
-def min(*values: Union[int, float]) -> Union[int, float]:
-    """Minimum value."""
-    ...
+def fromkeys(keys: List[str], value: Any = None) -> Dict[str, Any]:
+    """Create dictionary from list of keys with default value.
 
-def max(*values: Union[int, float]) -> Union[int, float]:
-    """Maximum value."""
+    Example:
+        fromkeys(["a", "b", "c"], 0);      // {"a": 0, "b": 0, "c": 0}
+    """
     ...
 
-def sum(arr: List[Union[int, float]]) -> Union[int, float]:
-    """Sum of array elements."""
-    ...
+def invert(d: Dict[str, Any]) -> Dict[Any, str]:
+    """Swap keys and values (values must be hashable).
 
-def avg(arr: List[Union[int, float]]) -> float:
-    """Average of array elements."""
+    Example:
+        invert({"a": 1, "b": 2});          // {1: "a", 2: "b"}
+    """
     ...
 
-def round(x: float, decimals: int = 0) -> float:
-    """Round to specified decimal places."""
-    ...
+def pick(d: Dict[str, Any], *keys: str) -> Dict[str, Any]:
+    """Pick only specified keys from dictionary.
 
-def floor(x: float) -> int:
-    """Round down to nearest integer."""
+    Example:
+        pick({"a": 1, "b": 2, "c": 3}, "a", "c");  // {"a": 1, "c": 3}
+    """
     ...
 
-def ceil(x: float) -> int:
-    """Round up to nearest integer."""
-    ...
+def omit(d: Dict[str, Any], *keys: str) -> Dict[str, Any]:
+    """Omit specified keys from dictionary.
 
-def pow(base: float, exponent: float) -> float:
-    """Raise base to power."""
+    Example:
+        omit({"a": 1, "b": 2, "c": 3}, "b");       // {"a": 1, "c": 3}
+    """
     ...
 
-def sqrt(x: float) -> float:
-    """Square root."""
-    ...
+def groupby(arr: List[Any], key: str) -> Dict[Any, List[Any]]:
+    """Group list of dicts/objects by key value.
 
-def random() -> float:
-    """Random float between 0 and 1."""
+    Example:
+        stack<json> users = [
+            {"name": "Alice", "role": "admin"},
+            {"name": "Bob", "role": "user"},
+            {"name": "Carol", "role": "admin"}
+        ];
+        groupby(users, "role");
+        // {"admin": [{Alice}, {Carol}], "user": [{Bob}]}
+    """
     ...
 
-def randint(min_val: int, max_val: int) -> int:
-    """Random integer in range [min, max]."""
-    ...
+# =============================================================================
+# MATH FUNCTIONS
+# =============================================================================
 
-def sin(x: float) -> float:
-    """Sine (radians)."""
-    ...
+def abs(x: Union[int, float]) -> Union[int, float]:
+    """Absolute value.
 
-def cos(x: float) -> float:
-    """Cosine (radians)."""
+    Example:
+        abs(-5);          // 5
+        abs(3.14);        // 3.14
+        abs(-3.14);       // 3.14
+    """
     ...
 
-def tan(x: float) -> float:
-    """Tangent (radians)."""
-    ...
+def min(*values: Union[int, float, List]) -> Union[int, float]:
+    """Minimum value from arguments or list.
 
-def asin(x: float) -> float:
-    """Arc sine (returns radians)."""
+    Example:
+        min(3, 1, 2);             // 1
+        min([3, 1, 2]);           // 1
+    """
     ...
 
-def acos(x: float) -> float:
-    """Arc cosine (returns radians)."""
+def max(*values: Union[int, float, List]) -> Union[int, float]:
+    """Maximum value from arguments or list.
+
+    Example:
+        max(3, 1, 2);             // 3
+        max([3, 1, 2]);           // 3
+    """
+    ...
+
+def sum(arr: List[Union[int, float]], start: Union[int, float] = 0) -> Union[int, float]:
+    """Sum of list elements.
+
+    Args:
+        arr: List of numbers
+        start: Starting value to add to sum (default: 0)
+
+    Example:
+        sum([1, 2, 3, 4]);        // 10
+        sum([1, 2, 3], 10);       // 16
+    """
+    ...
+
+def avg(arr: List[Union[int, float]]) -> float:
+    """Average (mean) of list elements.
+
+    Example:
+        avg([1, 2, 3, 4, 5]);     // 3.0
+        avg([10, 20]);            // 15.0
+    """
+    ...
+
+def round(x: float, decimals: int = 0) -> float:
+    """Round to specified decimal places.
+
+    Example:
+        round(3.14159, 2);        // 3.14
+        round(3.5);               // 4.0
+        round(2.5);               // 2.0 (banker's rounding)
+    """
+    ...
+
+def floor(x: float) -> int:
+    """Round down to nearest integer.
+
+    Example:
+        floor(3.9);               // 3
+        floor(3.1);               // 3
+        floor(-3.1);              // -4
+    """
+    ...
+
+def ceil(x: float) -> int:
+    """Round up to nearest integer.
+
+    Example:
+        ceil(3.1);                // 4
+        ceil(3.9);                // 4
+        ceil(-3.9);               // -3
+    """
+    ...
+
+def pow(base: float, exponent: float) -> float:
+    """Raise base to power.
+
+    Example:
+        pow(2, 3);                // 8.0
+        pow(9, 0.5);              // 3.0 (square root)
+        pow(2, -1);               // 0.5
+    """
+    ...
+
+def sqrt(x: float) -> float:
+    """Square root.
+
+    Example:
+        sqrt(16);                 // 4.0
+        sqrt(2);                  // 1.41421...
+    """
+    ...
+
+def mod(a: int, b: int) -> int:
+    """Modulo (remainder after division).
+
+    Example:
+        mod(7, 3);                // 1
+        mod(10, 5);               // 0
+    """
+    ...
+
+def random() -> float:
+    """Random float between 0.0 (inclusive) and 1.0 (exclusive).
+
+    Example:
+        float r = random();       // 0.0 <= r < 1.0
+    """
+    ...
+
+def randint(min_val: int, max_val: int) -> int:
+    """Random integer in inclusive range [min, max].
+
+    Example:
+        randint(1, 6);            // 1, 2, 3, 4, 5, or 6
+        randint(0, 100);          // 0 to 100 inclusive
+    """
+    ...
+
+def sin(x: float) -> float:
+    """Sine (argument in radians).
+
+    Example:
+        sin(0);                   // 0.0
+        sin(pi() / 2);            // 1.0
+    """
+    ...
+
+def cos(x: float) -> float:
+    """Cosine (argument in radians).
+
+    Example:
+        cos(0);                   // 1.0
+        cos(pi());                // -1.0
+    """
+    ...
+
+def tan(x: float) -> float:
+    """Tangent (argument in radians)."""
+    ...
+
+def asin(x: float) -> float:
+    """Arc sine (result in radians)."""
+    ...
+
+def acos(x: float) -> float:
+    """Arc cosine (result in radians)."""
     ...
 
 def atan(x: float) -> float:
-    """Arc tangent (returns radians)."""
+    """Arc tangent (result in radians)."""
     ...
 
 def atan2(y: float, x: float) -> float:
-    """Two-argument arc tangent."""
+    """Two-argument arc tangent (result in radians).
+
+    Returns angle from positive x-axis to point (x, y).
+    """
     ...
 
 def log(x: float, base: float = None) -> float:
-    """Natural logarithm (or log with specified base)."""
+    """Logarithm. Natural log if base not specified.
+
+    Example:
+        log(e());                 // 1.0 (natural log)
+        log(100, 10);             // 2.0 (log base 10)
+        log(8, 2);                // 3.0 (log base 2)
+    """
     ...
 
 def log10(x: float) -> float:
-    """Base-10 logarithm."""
+    """Base-10 logarithm.
+
+    Example:
+        log10(100);               // 2.0
+        log10(1000);              // 3.0
+    """
     ...
 
 def exp(x: float) -> float:
-    """Exponential function (e^x)."""
+    """Exponential function (e^x).
+
+    Example:
+        exp(1);                   // 2.71828...
+        exp(0);                   // 1.0
+    """
     ...
 
 def pi() -> float:
-    """Mathematical constant pi (3.14159...)."""
+    """Mathematical constant pi (3.14159265358979...).
+
+    Example:
+        float circumference = 2 * pi() * radius;
+    """
     ...
 
 def e() -> float:
-    """Mathematical constant e (2.71828...)."""
+    """Mathematical constant e (2.71828182845904...).
+
+    Example:
+        float growth = e() ** rate;
+    """
     ...
 
 def radians(degrees: float) -> float:
-    """Convert degrees to radians."""
+    """Convert degrees to radians.
+
+    Example:
+        radians(180);             // 3.14159... (pi)
+        radians(90);              // 1.5708... (pi/2)
+    """
     ...
 
 def degrees(radians: float) -> float:
-    """Convert radians to degrees."""
+    """Convert radians to degrees.
+
+    Example:
+        degrees(pi());            // 180.0
+        degrees(pi() / 2);        // 90.0
+    """
     ...
 
 # =============================================================================
@@ -817,18 +1454,39 @@ def degrees(radians: float) -> float:
 # =============================================================================
 
 def now() -> float:
-    """Current timestamp as float (seconds since epoch)."""
+    """Current timestamp as float (seconds since Unix epoch).
+
+    Example:
+        float ts = now();         // 1703956800.123456
+    """
     ...
 
 def timestamp() -> int:
-    """Current timestamp as integer."""
+    """Current timestamp as integer (seconds since Unix epoch).
+
+    Example:
+        int ts = timestamp();     // 1703956800
+    """
     ...
 
 def sleep(seconds: float) -> None:
     """Pause execution for specified seconds.
 
+    Args:
+        seconds: Duration to sleep (can be fractional)
+
     Example:
-        sleep(1.5);  // Wait 1.5 seconds
+        sleep(1.5);               // Wait 1.5 seconds
+        sleep(0.1);               // Wait 100 milliseconds
+    """
+    ...
+
+def delay(ms: float) -> None:
+    """Pause execution for specified milliseconds.
+
+    Example:
+        delay(500);               // Wait 500 milliseconds
+        delay(1000);              // Wait 1 second
     """
     ...
 
@@ -838,9 +1496,18 @@ def date(format: str = "%Y-%m-%d") -> str:
     Args:
         format: strftime format string
 
+    Common format codes:
+        %Y - 4-digit year
+        %m - 2-digit month
+        %d - 2-digit day
+        %H - Hour (24-hour)
+        %M - Minute
+        %S - Second
+
     Example:
-        date();              // "2025-12-30"
-        date("%d/%m/%Y");    // "30/12/2025"
+        date();                   // "2025-12-30"
+        date("%d/%m/%Y");         // "30/12/2025"
+        date("%Y%m%d");           // "20251230"
     """
     ...
 
@@ -848,12 +1515,18 @@ def time(format: str = "%H:%M:%S") -> str:
     """Current time as formatted string.
 
     Example:
-        time();              // "14:30:45"
+        time();                   // "14:30:45"
+        time("%H:%M");            // "14:30"
+        time("%I:%M %p");         // "02:30 PM"
     """
     ...
 
 def datetime(format: str = "%Y-%m-%d %H:%M:%S") -> str:
-    """Current date and time as formatted string."""
+    """Current date and time as formatted string.
+
+    Example:
+        datetime();               // "2025-12-30 14:30:45"
+    """
     ...
 
 def strftime(format: str, timestamp: float = None) -> str:
@@ -861,7 +1534,10 @@ def strftime(format: str, timestamp: float = None) -> str:
 
     Args:
         format: strftime format string
-        timestamp: Unix timestamp (default: now)
+        timestamp: Unix timestamp (default: current time)
+
+    Example:
+        strftime("%Y-%m-%d", 0);  // "1970-01-01"
     """
     ...
 
@@ -870,17 +1546,18 @@ def strftime(format: str, timestamp: float = None) -> str:
 # =============================================================================
 
 def read(path: str, encoding: str = "utf-8") -> str:
-    """Read entire file content.
+    """Read entire file content as string.
 
     Args:
-        path: File path
+        path: File path (absolute or relative)
         encoding: Character encoding (default: utf-8)
 
     Returns:
         File content as string
 
     Example:
-        string content = read("/path/to/file.txt");
+        string content = read("config.txt");
+        string data = read("/path/to/file.txt");
     """
     ...
 
@@ -888,19 +1565,20 @@ def readline(line: int, path: str) -> str:
     """Read specific line from file (1-indexed).
 
     Args:
-        line: Line number (1-based)
+        line: Line number (1-based, first line is 1)
         path: File path
 
     Returns:
-        Line content
+        Content of that line (without newline)
 
     Example:
         string line5 = readline(5, "file.txt");
+        string first = readline(1, "config.ini");
     """
     ...
 
 def write(path: str, content: str) -> int:
-    """Write content to file (overwrites).
+    """Write content to file (overwrites existing).
 
     Args:
         path: File path
@@ -908,91 +1586,171 @@ def write(path: str, content: str) -> int:
 
     Returns:
         Number of characters written
+
+    Example:
+        write("output.txt", "Hello World");
+        write("data.json", json::stringify(myData));
     """
     ...
 
 def writeline(line: int, content: str, path: str) -> bool:
-    """Write/replace specific line in file.
+    """Write/replace specific line in file (1-indexed).
+
+    Creates lines if file is shorter than specified line number.
 
     Args:
         line: Line number (1-based)
-        content: New line content
+        content: New content for that line
         path: File path
 
     Returns:
         Success status
+
+    Example:
+        writeline(3, "New third line", "file.txt");
     """
     ...
 
 def appendfile(path: str, content: str) -> int:
-    """Append content to file.
+    """Append content to end of file.
 
     Returns:
         Number of characters written
+
+    Example:
+        appendfile("log.txt", "New log entry\\n");
     """
     ...
 
 def readlines(path: str) -> List[str]:
-    """Read all lines from file.
+    """Read all lines from file as list.
 
     Returns:
-        List of lines
+        List of lines (including newline characters)
+
+    Example:
+        stack<string> lines = readlines("file.txt");
+        foreach (line in lines) {
+            printl(trim(line));
+        }
     """
     ...
 
 def pathexists(path: str) -> bool:
-    """Check if path exists (file or directory)."""
+    """Check if path exists (file or directory).
+
+    Example:
+        if (pathexists("config.json")) {
+            json config = json::read("config.json");
+        }
+    """
     ...
 
 def isfile(path: str) -> bool:
-    """Check if path is a file."""
+    """Check if path is a file (not directory).
+
+    Example:
+        if (isfile("data.txt")) {
+            string content = read("data.txt");
+        }
+    """
     ...
 
 def isdir(path: str) -> bool:
-    """Check if path is a directory."""
+    """Check if path is a directory.
+
+    Example:
+        if (isdir("output")) {
+            // Directory exists
+        } else {
+            makedirs("output");
+        }
+    """
     ...
 
-def listdir(path: str) -> List[str]:
-    """List directory contents.
+def listdir(path: str = ".") -> List[str]:
+    """List directory contents (file and folder names).
+
+    Args:
+        path: Directory path (default: current directory)
 
     Returns:
-        List of file/folder names
+        List of file/folder names (not full paths)
+
+    Example:
+        stack<string> files = listdir("./data");
+        foreach (f in files) {
+            printl(f);
+        }
     """
     ...
 
 def makedirs(path: str) -> bool:
-    """Create directory and parent directories.
+    """Create directory and all parent directories.
 
-    Returns:
-        Success status
+    Does not raise error if directory already exists.
+
+    Example:
+        makedirs("output/reports/2025");
     """
     ...
 
 def removefile(path: str) -> bool:
-    """Delete a file."""
+    """Delete a file.
+
+    Example:
+        removefile("temp.txt");
+    """
     ...
 
 def removedir(path: str) -> bool:
-    """Delete an empty directory."""
+    """Delete an empty directory.
+
+    Note: Directory must be empty. Use with caution.
+
+    Example:
+        removedir("empty_folder");
+    """
     ...
 
-def copyfile(src: str, dst: str) -> bool:
-    """Copy file from source to destination."""
+def copyfile(src: str, dst: str) -> str:
+    """Copy file from source to destination.
+
+    Returns:
+        Destination path
+
+    Example:
+        copyfile("original.txt", "backup.txt");
+    """
     ...
 
-def movefile(src: str, dst: str) -> bool:
-    """Move/rename file."""
+def movefile(src: str, dst: str) -> str:
+    """Move or rename file.
+
+    Returns:
+        Destination path
+
+    Example:
+        movefile("old_name.txt", "new_name.txt");
+        movefile("file.txt", "archive/file.txt");
+    """
     ...
 
 def filesize(path: str) -> int:
-    """Get file size in bytes."""
+    """Get file size in bytes.
+
+    Example:
+        int size = filesize("large_file.zip");
+        printl("Size: " + size + " bytes");
+    """
     ...
 
 def basename(path: str) -> str:
     """Get filename from path.
 
     Example:
-        basename("/path/to/file.txt");  // "file.txt"
+        basename("/path/to/file.txt");    // "file.txt"
+        basename("C:\\Users\\file.txt"); // "file.txt"
     """
     ...
 
@@ -1000,20 +1758,41 @@ def dirname(path: str) -> str:
     """Get directory from path.
 
     Example:
-        dirname("/path/to/file.txt");  // "/path/to"
+        dirname("/path/to/file.txt");     // "/path/to"
     """
     ...
 
 def joinpath(*parts: str) -> str:
-    """Join path components.
+    """Join path components with correct separator.
 
     Example:
         joinpath("/path", "to", "file.txt");  // "/path/to/file.txt"
+        joinpath("data", "output.csv");       // "data/output.csv"
     """
     ...
 
 def abspath(path: str) -> str:
-    """Get absolute path."""
+    """Get absolute path from relative path.
+
+    Example:
+        abspath("./file.txt");    // "/current/working/dir/file.txt"
+    """
+    ...
+
+def normpath(path: str) -> str:
+    """Normalize path (resolve .. and ., fix separators).
+
+    Example:
+        normpath("/path/to/../file.txt");  // "/path/file.txt"
+    """
+    ...
+
+def splitpath(path: str) -> List[str]:
+    """Split path into [directory, filename].
+
+    Example:
+        splitpath("/path/to/file.txt");   // ["/path/to", "file.txt"]
+    """
     ...
 
 # =============================================================================
@@ -1023,94 +1802,154 @@ def abspath(path: str) -> str:
 def json_read(path: str) -> Any:
     """Read and parse JSON file.
 
-    Usage: json::read("/path/to/file.json")
+    Usage in CSSL: json::read("/path/to/file.json")
+
+    Args:
+        path: Path to JSON file
 
     Returns:
-        Parsed JSON data
+        Parsed JSON data (dict, list, or primitive)
+
+    Example:
+        json config = json::read("config.json");
+        printl(config.name);
+        printl(config.settings.theme);
     """
     ...
 
 def json_write(path: str, data: Any, indent: int = 2) -> bool:
-    """Write data to JSON file.
+    """Write data to JSON file with formatting.
 
-    Usage: json::write("/path/to/file.json", data)
+    Usage in CSSL: json::write("/path/to/file.json", data)
+
+    Args:
+        path: Output file path
+        data: Data to serialize (dict, list, primitives)
+        indent: Indentation spaces (default: 2)
 
     Returns:
         Success status
+
+    Example:
+        json data = {"name": "Alice", "age": 30};
+        json::write("user.json", data);
     """
     ...
 
 def json_parse(s: str) -> Any:
-    """Parse JSON string.
+    """Parse JSON string to object.
 
-    Usage: json::parse('{"key": "value"}')
+    Usage in CSSL: json::parse('{"key": "value"}')
 
-    Returns:
-        Parsed object/array
+    Example:
+        string jsonStr = '{"name": "Bob", "active": true}';
+        json obj = json::parse(jsonStr);
+        printl(obj.name);    // "Bob"
     """
     ...
 
 def json_stringify(data: Any) -> str:
-    """Convert data to JSON string.
+    """Convert object to JSON string (compact).
 
-    Usage: json::stringify(data)
+    Usage in CSSL: json::stringify(data)
+
+    Example:
+        json obj = {"a": 1, "b": [1, 2, 3]};
+        string s = json::stringify(obj);
+        // '{"a":1,"b":[1,2,3]}'
     """
     ...
 
 def json_pretty(data: Any, indent: int = 2) -> str:
-    """Pretty print JSON with indentation.
+    """Convert object to formatted JSON string.
 
-    Usage: json::pretty(data)
+    Usage in CSSL: json::pretty(data)
+
+    Example:
+        string formatted = json::pretty(config);
+        printl(formatted);
     """
     ...
 
 def json_get(data: Any, path: str, default: Any = None) -> Any:
-    """Get value by dot-path.
+    """Get value by dot-path from nested structure.
 
-    Usage: json::get(data, "user.name")
+    Usage in CSSL: json::get(data, "user.profile.name")
+
+    Supports array indexing with numeric path segments.
 
     Args:
-        data: JSON object
-        path: Dot-separated path (e.g., "user.profile.age")
-        default: Default value if path not found
+        data: JSON object/dict
+        path: Dot-separated path (e.g., "user.address.city")
+        default: Value if path not found
+
+    Example:
+        json data = {"user": {"name": "Alice", "tags": ["a", "b"]}};
+        json::get(data, "user.name");         // "Alice"
+        json::get(data, "user.tags.0");       // "a"
+        json::get(data, "user.email", "N/A"); // "N/A"
     """
     ...
 
 def json_set(data: Any, path: str, value: Any) -> Any:
-    """Set value by dot-path.
+    """Set value by dot-path in nested structure.
+
+    Usage in CSSL: json::set(data, "user.name", "Bob")
 
-    Usage: json::set(data, "user.name", "John")
+    Creates intermediate objects if they don't exist.
 
     Returns:
-        Modified data
+        Modified data (new copy)
+
+    Example:
+        json data = {"user": {}};
+        data = json::set(data, "user.name", "Alice");
+        data = json::set(data, "user.profile.age", 30);
     """
     ...
 
 def json_has(data: Any, path: str) -> bool:
-    """Check if path exists.
+    """Check if dot-path exists in structure.
 
-    Usage: json::has(data, "user.email")
+    Usage in CSSL: json::has(data, "user.email")
+
+    Example:
+        if (json::has(config, "database.host")) {
+            string host = json::get(config, "database.host");
+        }
     """
     ...
 
 def json_keys(data: Dict) -> List[str]:
-    """Get all keys from JSON object.
+    """Get all top-level keys from JSON object.
 
-    Usage: json::keys(data)
+    Usage in CSSL: json::keys(data)
+
+    Example:
+        stack<string> k = json::keys(config);
+        // ["name", "version", "settings"]
     """
     ...
 
 def json_values(data: Dict) -> List[Any]:
-    """Get all values from JSON object.
+    """Get all top-level values from JSON object.
 
-    Usage: json::values(data)
+    Usage in CSSL: json::values(data)
     """
     ...
 
 def json_merge(*dicts: Dict) -> Dict:
     """Deep merge multiple JSON objects.
 
-    Usage: json::merge(obj1, obj2, obj3)
+    Usage in CSSL: json::merge(obj1, obj2, obj3)
+
+    Later objects override earlier ones. Nested objects are merged recursively.
+
+    Example:
+        json defaults = {"theme": "light", "lang": "en"};
+        json user = {"theme": "dark"};
+        json config = json::merge(defaults, user);
+        // {"theme": "dark", "lang": "en"}
     """
     ...
 
@@ -1119,67 +1958,112 @@ def json_merge(*dicts: Dict) -> Dict:
 # =============================================================================
 
 def instance_getMethods(obj: Any) -> List[str]:
-    """Get all method names from object/module.
+    """Get all public method names from object/module.
 
-    Usage: instance::getMethods(@module)
+    Usage in CSSL: instance::getMethods(@module)
 
-    Returns:
-        List of callable method names
+    Returns list of callable method names (excludes private _ methods).
+
+    Example:
+        @tk = include("tkinter.cssl-mod");
+        stack<string> methods = instance::getMethods(@tk);
+        foreach (m in methods) {
+            printl("Method: " + m);
+        }
     """
     ...
 
 def instance_getClasses(obj: Any) -> List[str]:
     """Get all class names from module.
 
-    Usage: instance::getClasses(@module)
+    Usage in CSSL: instance::getClasses(@module)
+
+    Example:
+        stack<string> classes = instance::getClasses(@tk);
+        // ["Tk", "Frame", "Button", "Label", ...]
     """
     ...
 
 def instance_getVars(obj: Any) -> List[str]:
-    """Get all variable/attribute names.
+    """Get all public variable/attribute names (non-callable).
 
-    Usage: instance::getVars(@module)
+    Usage in CSSL: instance::getVars(@module)
+
+    Example:
+        stack<string> vars = instance::getVars(@config);
+        // ["VERSION", "DEBUG", "API_URL", ...]
     """
     ...
 
 def instance_getAll(obj: Any) -> Dict[str, List[str]]:
-    """Get all attributes categorized.
+    """Get all attributes categorized by type.
 
-    Usage: instance::getAll(@module)
+    Usage in CSSL: instance::getAll(@module)
 
-    Returns:
-        Dict with 'methods', 'classes', 'vars' keys
+    Returns dict with keys: 'methods', 'classes', 'vars'
+
+    Example:
+        json all = instance::getAll(@module);
+        printl("Methods: " + len(all.methods));
+        printl("Classes: " + len(all.classes));
+        printl("Variables: " + len(all.vars));
     """
     ...
 
 def instance_call(obj: Any, method_name: str, *args: Any, **kwargs: Any) -> Any:
-    """Dynamically call method on object.
+    """Dynamically call method on object by name.
+
+    Usage in CSSL: instance::call(@module, "methodName", arg1, arg2)
+
+    Example:
+        // Instead of @module.process(data)
+        result = instance::call(@module, "process", data);
 
-    Usage: instance::call(@module, "methodName", arg1, arg2)
+        // Useful for dynamic method selection
+        string action = "save";
+        instance::call(@handler, action, document);
     """
     ...
 
 def instance_has(obj: Any, name: str) -> bool:
-    """Check if object has attribute.
+    """Check if object has attribute (method or variable).
 
-    Usage: instance::has(@module, "methodName")
+    Usage in CSSL: instance::has(@module, "methodName")
+
+    Example:
+        if (instance::has(@plugin, "initialize")) {
+            instance::call(@plugin, "initialize");
+        }
     """
     ...
 
 def instance_type(obj: Any) -> str:
     """Get type name of object.
 
-    Usage: instance::type(@module)
+    Usage in CSSL: instance::type(@module)
+
+    Example:
+        string t = instance::type(@data);
+        printl("Type: " + t);  // "dict", "list", "CSSLModule", etc.
     """
     ...
 
 def isavailable(name_or_obj: Any) -> bool:
     """Check if shared instance exists.
 
+    Can check by name string or by shared reference.
+
     Usage:
-        isavailable("MyInstance")    // Check by name
-        isavailable($MyInstance)     // Check if not null
-        instance::exists("Name")     // Alias
+        isavailable("MyInstance")     // Check by name
+        isavailable($MyInstance)      // Check if shared ref is not null
+        instance::exists("Name")      // Alias
+
+    Example:
+        if (isavailable("DatabaseConnection")) {
+            $DatabaseConnection.query("SELECT * FROM users");
+        } else {
+            error("Database not connected");
+        }
     """
     ...
 
@@ -1188,34 +2072,62 @@ def isavailable(name_or_obj: Any) -> bool:
 # =============================================================================
 
 def match(pattern: str, string: str) -> Optional[Dict]:
-    """Match regex at start of string.
+    """Match regex pattern at START of string.
+
+    Args:
+        pattern: Regular expression pattern
+        string: String to match against
 
     Returns:
-        Dict with 'match', 'groups', 'start', 'end' or null
+        Dict with 'match', 'groups', 'start', 'end' if matched, null otherwise
+
+    Example:
+        json m = match("\\d+", "123abc");
+        if (m != null) {
+            printl(m.match);   // "123"
+            printl(m.start);   // 0
+            printl(m.end);     // 3
+        }
     """
     ...
 
 def search(pattern: str, string: str) -> Optional[Dict]:
-    """Search for regex anywhere in string.
+    """Search for regex pattern ANYWHERE in string.
 
     Returns:
         Dict with match info or null
+
+    Example:
+        json m = search("\\d+", "abc123def");
+        printl(m.match);       // "123"
+        printl(m.start);       // 3
     """
     ...
 
 def findall(pattern: str, string: str) -> List[str]:
-    """Find all regex matches.
+    """Find all non-overlapping matches of pattern.
 
     Returns:
-        List of all matches
+        List of all matching strings
+
+    Example:
+        stack<string> nums = findall("\\d+", "a1b22c333");
+        // ["1", "22", "333"]
     """
     ...
 
-def sub(pattern: str, replacement: str, string: str) -> str:
-    """Replace all regex matches.
+def sub(pattern: str, replacement: str, string: str, count: int = 0) -> str:
+    """Replace regex matches with replacement string.
+
+    Args:
+        pattern: Regex pattern to find
+        replacement: Replacement string
+        string: Source string
+        count: Max replacements (0 = unlimited)
 
     Example:
-        sub("\\d+", "X", "a1b2c3");  // "aXbXcX"
+        sub("\\d+", "X", "a1b2c3");        // "aXbXcX"
+        sub("\\d+", "X", "a1b2c3", 2);     // "aXbXc3"
     """
     ...
 
@@ -1224,19 +2136,36 @@ def sub(pattern: str, replacement: str, string: str) -> str:
 # =============================================================================
 
 def md5(s: str) -> str:
-    """Calculate MD5 hash.
+    """Calculate MD5 hash of string.
 
     Returns:
-        Hexadecimal hash string
+        32-character hexadecimal hash string
+
+    Example:
+        md5("hello");         // "5d41402abc4b2a76b9719d911017c592"
     """
     ...
 
 def sha1(s: str) -> str:
-    """Calculate SHA1 hash."""
+    """Calculate SHA-1 hash of string.
+
+    Returns:
+        40-character hexadecimal hash string
+
+    Example:
+        sha1("hello");        // "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
+    """
     ...
 
 def sha256(s: str) -> str:
-    """Calculate SHA256 hash."""
+    """Calculate SHA-256 hash of string.
+
+    Returns:
+        64-character hexadecimal hash string
+
+    Example:
+        sha256("hello");      // "2cf24dba5fb0a30e26e83b2ac5b9e29e..."
+    """
     ...
 
 # =============================================================================
@@ -1244,135 +2173,239 @@ def sha256(s: str) -> str:
 # =============================================================================
 
 def exit(code: int = 0) -> None:
-    """Exit CSSL execution.
+    """Exit CSSL script execution.
+
+    Can be intercepted with CodeInfusion for cleanup.
 
     Args:
-        code: Exit code (default: 0)
+        code: Exit code (0 = success, non-zero = error)
+
+    Example:
+        // Basic exit
+        exit();
+        exit(0);    // Success
+        exit(1);    // Error
+
+        // With cleanup via CodeInfusion
+        exit() <<== {
+            printl("Cleaning up...");
+            // cleanup code
+        }
     """
     ...
 
 def input(prompt: str = "") -> str:
-    """Read user input from console.
+    """Read line of user input from console.
 
     Args:
-        prompt: Optional prompt message
+        prompt: Optional prompt message to display
 
     Returns:
-        User input string
+        User input string (without newline)
+
+    Example:
+        string name = input("Enter your name: ");
+        printl("Hello, " + name);
+
+        string answer = input("Continue? (y/n): ");
+        if (answer == "y") {
+            // continue
+        }
     """
     ...
 
-def env(name: str) -> Optional[str]:
-    """Get environment variable.
+def env(name: str, default: str = None) -> Optional[str]:
+    """Get environment variable value.
 
     Args:
-        name: Variable name
+        name: Environment variable name
+        default: Default if not set
 
     Returns:
-        Variable value or null
+        Variable value or default/null
+
+    Example:
+        string home = env("HOME");
+        string path = env("MY_APP_PATH", "/default/path");
     """
     ...
 
 def setenv(name: str, value: str) -> None:
-    """Set environment variable."""
+    """Set environment variable.
+
+    Example:
+        setenv("MY_VAR", "my_value");
+    """
     ...
 
 def clear() -> None:
-    """Clear console screen."""
+    """Clear console screen.
+
+    Example:
+        clear();
+        printl("Fresh screen!");
+    """
     ...
 
 def copy(obj: Any) -> Any:
-    """Create shallow copy of object."""
+    """Create shallow copy of object.
+
+    For lists/dicts, creates new container but references same nested objects.
+
+    Example:
+        stack<int> original = [1, 2, 3];
+        stack<int> copied = copy(original);
+        copied.push(4);
+        // original is still [1, 2, 3]
+    """
     ...
 
 def deepcopy(obj: Any) -> Any:
-    """Create deep copy of object."""
+    """Create deep copy of object (recursively copies nested objects).
+
+    Example:
+        json original = {"nested": {"value": 1}};
+        json copied = deepcopy(original);
+        copied.nested.value = 2;
+        printl(original.nested.value);  // Still 1
+    """
     ...
 
-def pyimport(module_name: str) -> Any:
-    """Import Python module dynamically.
+def assert_condition(condition: bool, message: str = "Assertion failed") -> None:
+    """Assert condition is true, raise error if false.
+
+    Usage in CSSL: assert(condition, "message")
 
     Example:
-        @os = pyimport("os");
-        @os.getcwd();
+        assert(x > 0, "x must be positive");
+        assert(isstr(name), "name must be string");
     """
     ...
 
-def include(path: str) -> Any:
-    """Include/import CSSL module.
+def pyimport(module_name: str) -> Any:
+    """Import Python module for use in CSSL.
+
+    Provides access to Python's standard library and installed packages.
 
     Args:
-        path: Module path (e.g., "mymodule.cssl-mod")
+        module_name: Python module name
 
     Returns:
         Imported module object
+
+    Example:
+        @os = pyimport("os");
+        string cwd = @os.getcwd();
+
+        @re = pyimport("re");
+        json match = @re.search("\\d+", "abc123");
+
+        @datetime = pyimport("datetime");
+        @datetime.datetime.now();
     """
     ...
 
-def payload(path: str) -> Any:
-    """Load CSSL payload file.
+def include(path: str) -> Any:
+    """Import CSSL module or file.
+
+    Supports .cssl files and .cssl-mod compiled modules.
+    Returns module object with accessible functions and variables.
 
     Args:
-        path: Payload file path (e.g., "data.cssl-pl")
-    """
-    ...
+        path: Path to module file
 
-# =============================================================================
-# CSSL-SPECIFIC FUNCTIONS
-# =============================================================================
+    Returns:
+        Imported module object
 
-def OpenFind(type_or_combo: Any, index: int = 0) -> Optional[Any]:
-    """Find open parameter by type or combo space.
+    Example:
+        // Import compiled Python module
+        @Math = include("mathlib.cssl-mod");
+        int result = @Math.add(5, 3);
 
-    Usage:
-        string name = OpenFind<string>(0);
-        value = OpenFind(&comboSpace);
+        // Import CSSL file
+        @Utils = include("utils.cssl");
+        @Utils.formatDate(now());
     """
     ...
 
-def datastruct(element_type: str = "dynamic") -> Any:
-    """Create datastruct container.
+def payload(path_or_name: str) -> None:
+    """Load CSSL payload file into current scope.
+
+    Payloads are like headers - they define globals, functions, and
+    can inject code into existing functions. All definitions become
+    available in the current execution context.
+
+    Supports:
+    - File paths: "helpers.cssl-pl"
+    - Registered names: payload registered via CSSL.code() in Python
+
+    Args:
+        path_or_name: Path to .cssl-pl file or registered payload name
 
     Example:
-        datastruct<string> data;
+        // In helpers.cssl-pl:
+        global DEBUG = true;
+        void log(string msg) {
+            if (@DEBUG) printl("[LOG] " + msg);
+        }
+
+        // In main.cssl:
+        payload("helpers.cssl-pl");
+        log("Hello!");    // Works - function from payload
+
+        // From Python:
+        CSSL.code("myhelper", "void greet() { printl('Hi'); }")
+        CSSL.run('payload("myhelper"); greet();')
     """
     ...
 
-def shuffled(element_type: str = "dynamic") -> Any:
-    """Create shuffled container for unorganized fast storage."""
-    ...
+def color(text: str, color_name: str) -> str:
+    """Apply ANSI color to text for terminal output.
 
-def iterator(element_type: str = "int", size: int = 16) -> Any:
-    """Create iterator with programmable tasks."""
-    ...
+    Available colors:
+        Basic: black, red, green, yellow, blue, magenta, cyan, white
+        Bright: bright_black, bright_red, bright_green, etc.
+        Styles: bold, dim, italic, underline, blink, reverse
 
-def combo(element_type: str = "dynamic") -> Any:
-    """Create combo filter/search space."""
+    Example:
+        printl(color("Error!", "red"));
+        printl(color("Success", "green"));
+        printl(color("Warning", "yellow"));
+        printl(color("Important", "bold"));
+    """
     ...
 
-def share(name: str, obj: Any) -> None:
-    """Share Python object with CSSL.
+def original(func_name: str, *args: Any) -> Any:
+    """Call the original version of a replaced function.
 
-    Args:
-        name: Instance name for CSSL access
-        obj: Python object to share
+    Used within CodeInfusion to call the function that was replaced.
 
-    Example (Python):
-        CSSL.share("mydata", data_object)
-
-    Example (CSSL):
-        $mydata.property;
+    Example:
+        // Replace exit with custom behavior
+        exit() <<== {
+            printl("Custom cleanup...");
+            original("exit");  // Call original exit
+        }
     """
     ...
 
 def delete(name: str) -> bool:
-    """Delete shared object.
+    """Delete a shared object by name.
+
+    Removes object from shared instance registry.
 
     Args:
-        name: Shared object name
+        name: Shared object name (without $ prefix)
 
     Returns:
         True if deleted, False if not found
+
+    Example:
+        // In Python: CSSL.share(myObj, "temp")
+        // In CSSL:
+        $temp.doSomething();
+        delete("temp");  // Remove when done
+        // $temp is now null
     """
     ...
 
@@ -1381,13 +2414,1805 @@ def delete(name: str) -> bool:
 # =============================================================================
 
 def isLinux() -> bool:
-    """Check if running on Linux."""
+    """Check if running on Linux operating system.
+
+    Example:
+        if (isLinux()) {
+            string home = env("HOME");
+        }
+    """
     ...
 
 def isWindows() -> bool:
-    """Check if running on Windows."""
+    """Check if running on Windows operating system.
+
+    Example:
+        if (isWindows()) {
+            string home = env("USERPROFILE");
+        }
+    """
     ...
 
 def isMac() -> bool:
-    """Check if running on macOS."""
+    """Check if running on macOS operating system.
+
+    Example:
+        if (isMac()) {
+            printl("Running on Apple hardware");
+        }
+    """
+    ...
+
+# =============================================================================
+# CSSL CONTAINER TYPES - Class-based with method documentation
+# =============================================================================
+
+class CSSLStack:
+    """CSSL stack<T> container - LIFO (Last In, First Out) data structure.
+
+    A stack is a collection where elements are added and removed from the same end
+    (the "top"). The last element added is the first one removed.
+
+    Declaration in CSSL:
+        stack<string> names;
+        stack<int> numbers;
+        stack<dynamic> mixed;  // Can hold any type
+
+    Example:
+        stack<string> tasks;
+        tasks.push("First task");
+        tasks.push("Second task");
+        tasks.push("Third task");
+
+        printl(tasks);           // ['First task', 'Second task', 'Third task']
+        printl(tasks.peek());    // "Third task" (view top without removing)
+        printl(tasks.pop());     // "Third task" (removes and returns top)
+        printl(tasks.length());  // 2
+        printl(tasks[0]);        // "First task" (index access)
+    """
+
+    def push(self, value: T) -> 'CSSLStack':
+        """Add element to top of stack.
+
+        Args:
+            value: Element to add
+
+        Returns:
+            The stack (for chaining)
+
+        Example:
+            stack<int> nums;
+            nums.push(1).push(2).push(3);  // Chained calls
+            printl(nums);  // [1, 2, 3]
+        """
+        ...
+
+    def push_back(self, value: T) -> 'CSSLStack':
+        """Alias for push(). Add element to top of stack."""
+        ...
+
+    def pop(self) -> T:
+        """Remove and return top element.
+
+        Returns:
+            The removed element from top of stack
+
+        Example:
+            stack<string> names = ["Alice", "Bob", "Charlie"];
+            string last = names.pop();  // "Charlie"
+            printl(names);              // ["Alice", "Bob"]
+        """
+        ...
+
+    def peek(self) -> T:
+        """View top element without removing it.
+
+        Returns:
+            The top element (or None if empty)
+
+        Example:
+            stack<int> nums = [1, 2, 3];
+            printl(nums.peek());  // 3
+            printl(nums.peek());  // 3 (still there)
+        """
+        ...
+
+    def isEmpty(self) -> bool:
+        """Check if stack has no elements.
+
+        Returns:
+            True if stack is empty, False otherwise
+
+        Example:
+            stack<int> nums;
+            printl(nums.isEmpty());  // true
+            nums.push(1);
+            printl(nums.isEmpty());  // false
+        """
+        ...
+
+    def is_empty(self) -> bool:
+        """Alias for isEmpty(). Check if stack is empty."""
+        ...
+
+    def size(self) -> int:
+        """Get number of elements in stack.
+
+        Returns:
+            Number of elements
+
+        Example:
+            stack<string> names = ["A", "B", "C"];
+            printl(names.size());  // 3
+        """
+        ...
+
+    def length(self) -> int:
+        """Alias for size(). Get number of elements."""
+        ...
+
+    def contains(self, value: T) -> bool:
+        """Check if stack contains a specific value.
+
+        Args:
+            value: Value to search for
+
+        Returns:
+            True if found, False otherwise
+
+        Example:
+            stack<string> names = ["Alice", "Bob"];
+            printl(names.contains("Alice"));  // true
+            printl(names.contains("Carol"));  // false
+        """
+        ...
+
+    def indexOf(self, value: T) -> int:
+        """Find index of first occurrence of value.
+
+        Args:
+            value: Value to find
+
+        Returns:
+            Index (0-based), or -1 if not found
+
+        Example:
+            stack<string> names = ["A", "B", "C", "B"];
+            printl(names.indexOf("B"));  // 1
+            printl(names.indexOf("X"));  // -1
+        """
+        ...
+
+    def toArray(self) -> List[T]:
+        """Convert stack to plain array/list.
+
+        Returns:
+            List containing all stack elements
+
+        Example:
+            stack<int> nums = [1, 2, 3];
+            array = nums.toArray();
+            printl(array);  // [1, 2, 3]
+        """
+        ...
+
+    def swap(self) -> 'CSSLStack':
+        """Swap top two elements.
+
+        Returns:
+            The stack (for chaining)
+
+        Example:
+            stack<int> nums = [1, 2, 3];
+            nums.swap();
+            printl(nums);  // [1, 3, 2]
+        """
+        ...
+
+    def dup(self) -> 'CSSLStack':
+        """Duplicate top element.
+
+        Returns:
+            The stack (for chaining)
+
+        Example:
+            stack<int> nums = [1, 2, 3];
+            nums.dup();
+            printl(nums);  // [1, 2, 3, 3]
+        """
+        ...
+
+    def begin(self) -> int:
+        """Get iterator to first element (C++ style).
+
+        Returns:
+            Index 0
+        """
+        ...
+
+    def end(self) -> int:
+        """Get iterator past last element (C++ style).
+
+        Returns:
+            Length of stack
+        """
+        ...
+
+
+class CSSLVector:
+    """CSSL vector<T> container - Dynamic resizable array.
+
+    A vector provides random access to elements by index and automatically
+    grows as elements are added. Ideal for collections that need frequent
+    access by position.
+
+    Declaration in CSSL:
+        vector<int> numbers;
+        vector<string> names;
+        vector<float> prices;
+
+    Example:
+        vector<int> nums;
+        nums.push(10);
+        nums.push(20);
+        nums.push(30);
+
+        printl(nums);         // [10, 20, 30]
+        printl(nums.at(1));   // 20
+        printl(nums.front()); // 10
+        printl(nums.back());  // 30
+        printl(nums.size());  // 3
+    """
+
+    def push(self, value: T) -> 'CSSLVector':
+        """Add element to end of vector.
+
+        Args:
+            value: Element to add
+
+        Returns:
+            The vector (for chaining)
+
+        Example:
+            vector<string> items;
+            items.push("A").push("B").push("C");
+        """
+        ...
+
+    def push_back(self, value: T) -> 'CSSLVector':
+        """Alias for push(). Add element to end."""
+        ...
+
+    def push_front(self, value: T) -> 'CSSLVector':
+        """Add element to front of vector.
+
+        Args:
+            value: Element to add
+
+        Returns:
+            The vector (for chaining)
+
+        Example:
+            vector<int> nums = [2, 3];
+            nums.push_front(1);
+            printl(nums);  // [1, 2, 3]
+        """
+        ...
+
+    def pop_back(self) -> T:
+        """Remove and return last element.
+
+        Returns:
+            The removed element
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            int last = nums.pop_back();  // 3
+            printl(nums);                // [1, 2]
+        """
+        ...
+
+    def pop_front(self) -> T:
+        """Remove and return first element.
+
+        Returns:
+            The removed element
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            int first = nums.pop_front();  // 1
+            printl(nums);                  // [2, 3]
+        """
+        ...
+
+    def at(self, index: int) -> T:
+        """Get element at index.
+
+        Args:
+            index: Zero-based position
+
+        Returns:
+            Element at position (or None if out of bounds)
+
+        Example:
+            vector<string> names = ["Alice", "Bob", "Carol"];
+            printl(names.at(1));  // "Bob"
+        """
+        ...
+
+    def set(self, index: int, value: T) -> 'CSSLVector':
+        """Set element at index.
+
+        Args:
+            index: Zero-based position
+            value: New value
+
+        Returns:
+            The vector (for chaining)
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            nums.set(1, 99);
+            printl(nums);  // [1, 99, 3]
+        """
+        ...
+
+    def size(self) -> int:
+        """Get number of elements."""
+        ...
+
+    def length(self) -> int:
+        """Alias for size()."""
+        ...
+
+    def empty(self) -> bool:
+        """Check if vector is empty."""
+        ...
+
+    def isEmpty(self) -> bool:
+        """Alias for empty()."""
+        ...
+
+    def front(self) -> T:
+        """Get first element without removing.
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            printl(nums.front());  // 1
+        """
+        ...
+
+    def back(self) -> T:
+        """Get last element without removing.
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            printl(nums.back());  // 3
+        """
+        ...
+
+    def contains(self, value: T) -> bool:
+        """Check if vector contains value."""
+        ...
+
+    def indexOf(self, value: T) -> int:
+        """Find first index of value (-1 if not found)."""
+        ...
+
+    def lastIndexOf(self, value: T) -> int:
+        """Find last index of value (-1 if not found)."""
+        ...
+
+    def find(self, predicate: Callable[[T], bool]) -> T:
+        """Find first element matching predicate.
+
+        Args:
+            predicate: Function returning True for match
+
+        Returns:
+            First matching element or None
+
+        Example:
+            vector<int> nums = [1, 5, 10, 15];
+            int found = nums.find(x => x > 7);  // 10
+        """
+        ...
+
+    def findIndex(self, predicate: Callable[[T], bool]) -> int:
+        """Find index of first element matching predicate."""
+        ...
+
+    def slice(self, start: int, end: int = None) -> 'CSSLVector':
+        """Get sub-vector from start to end.
+
+        Args:
+            start: Start index (inclusive)
+            end: End index (exclusive), defaults to end
+
+        Example:
+            vector<int> nums = [1, 2, 3, 4, 5];
+            vector<int> sub = nums.slice(1, 4);  // [2, 3, 4]
+        """
+        ...
+
+    def join(self, separator: str = ",") -> str:
+        """Join elements into string.
+
+        Example:
+            vector<string> words = ["hello", "world"];
+            printl(words.join(" "));  // "hello world"
+        """
+        ...
+
+    def map(self, func: Callable[[T], Any]) -> 'CSSLVector':
+        """Apply function to each element, return new vector.
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            vector<int> doubled = nums.map(x => x * 2);  // [2, 4, 6]
+        """
+        ...
+
+    def filter(self, predicate: Callable[[T], bool]) -> 'CSSLVector':
+        """Return new vector with elements matching predicate.
+
+        Example:
+            vector<int> nums = [1, 2, 3, 4, 5];
+            vector<int> evens = nums.filter(x => x % 2 == 0);  // [2, 4]
+        """
+        ...
+
+    def forEach(self, func: Callable[[T], None]) -> 'CSSLVector':
+        """Execute function for each element.
+
+        Example:
+            vector<string> names = ["Alice", "Bob"];
+            names.forEach(name => printl("Hello " + name));
+        """
+        ...
+
+    def fill(self, value: T, start: int = 0, end: int = None) -> 'CSSLVector':
+        """Fill range with value.
+
+        Example:
+            vector<int> nums = [1, 2, 3, 4, 5];
+            nums.fill(0, 1, 4);
+            printl(nums);  // [1, 0, 0, 0, 5]
+        """
+        ...
+
+    def every(self, predicate: Callable[[T], bool]) -> bool:
+        """Check if all elements match predicate.
+
+        Example:
+            vector<int> nums = [2, 4, 6];
+            printl(nums.every(x => x % 2 == 0));  // true
+        """
+        ...
+
+    def some(self, predicate: Callable[[T], bool]) -> bool:
+        """Check if any element matches predicate.
+
+        Example:
+            vector<int> nums = [1, 2, 3];
+            printl(nums.some(x => x > 2));  // true
+        """
+        ...
+
+    def reduce(self, func: Callable[[Any, T], Any], initial: Any = None) -> Any:
+        """Reduce vector to single value.
+
+        Example:
+            vector<int> nums = [1, 2, 3, 4];
+            int sum = nums.reduce((acc, x) => acc + x, 0);  // 10
+        """
+        ...
+
+    def toArray(self) -> List[T]:
+        """Convert to plain list."""
+        ...
+
+    def begin(self) -> int:
+        """Get iterator to first element (C++ style)."""
+        ...
+
+    def end(self) -> int:
+        """Get iterator past last element (C++ style)."""
+        ...
+
+
+class CSSLArray:
+    """CSSL array<T> container - Standard array with CSSL methods.
+
+    Similar to vector but conceptually represents a fixed-purpose collection.
+    Supports all standard array operations.
+
+    Declaration in CSSL:
+        array<string> items;
+        array<int> scores;
+
+    Example:
+        array<string> colors;
+        colors.push("red");
+        colors.push("green");
+        colors.push("blue");
+        printl(colors.length());  // 3
+        printl(colors.first());   // "red"
+        printl(colors.last());    // "blue"
+    """
+
+    def push(self, value: T) -> 'CSSLArray':
+        """Add element to end of array."""
+        ...
+
+    def push_back(self, value: T) -> 'CSSLArray':
+        """Alias for push()."""
+        ...
+
+    def push_front(self, value: T) -> 'CSSLArray':
+        """Add element to front of array."""
+        ...
+
+    def pop(self) -> T:
+        """Remove and return last element."""
+        ...
+
+    def pop_back(self) -> T:
+        """Alias for pop()."""
+        ...
+
+    def pop_front(self) -> T:
+        """Remove and return first element."""
+        ...
+
+    def at(self, index: int) -> T:
+        """Get element at index."""
+        ...
+
+    def set(self, index: int, value: T) -> 'CSSLArray':
+        """Set element at index."""
+        ...
+
+    def size(self) -> int:
+        """Get number of elements."""
+        ...
+
+    def length(self) -> int:
+        """Alias for size()."""
+        ...
+
+    def empty(self) -> bool:
+        """Check if array is empty."""
+        ...
+
+    def isEmpty(self) -> bool:
+        """Alias for empty()."""
+        ...
+
+    def first(self) -> T:
+        """Get first element."""
+        ...
+
+    def last(self) -> T:
+        """Get last element."""
+        ...
+
+    def contains(self, value: T) -> bool:
+        """Check if array contains value."""
+        ...
+
+    def indexOf(self, value: T) -> int:
+        """Find first index of value."""
+        ...
+
+    def lastIndexOf(self, value: T) -> int:
+        """Find last index of value."""
+        ...
+
+    def find(self, predicate: Callable[[T], bool]) -> T:
+        """Find first element matching predicate."""
+        ...
+
+    def findIndex(self, predicate: Callable[[T], bool]) -> int:
+        """Find index of first match."""
+        ...
+
+    def slice(self, start: int, end: int = None) -> 'CSSLArray':
+        """Get sub-array from start to end."""
+        ...
+
+    def join(self, separator: str = ",") -> str:
+        """Join elements into string."""
+        ...
+
+    def map(self, func: Callable[[T], Any]) -> 'CSSLArray':
+        """Apply function to each element."""
+        ...
+
+    def filter(self, predicate: Callable[[T], bool]) -> 'CSSLArray':
+        """Filter elements by predicate."""
+        ...
+
+    def forEach(self, func: Callable[[T], None]) -> 'CSSLArray':
+        """Execute function for each element."""
+        ...
+
+    def fill(self, value: T, start: int = 0, end: int = None) -> 'CSSLArray':
+        """Fill range with value."""
+        ...
+
+    def every(self, predicate: Callable[[T], bool]) -> bool:
+        """Check if all elements match."""
+        ...
+
+    def some(self, predicate: Callable[[T], bool]) -> bool:
+        """Check if any element matches."""
+        ...
+
+    def reduce(self, func: Callable[[Any, T], Any], initial: Any = None) -> Any:
+        """Reduce to single value."""
+        ...
+
+    def toArray(self) -> List[T]:
+        """Convert to plain list."""
+        ...
+
+
+class CSSLMap:
+    """CSSL map<K, V> container - C++ style ordered key-value pairs.
+
+    A map stores key-value pairs with keys maintained in sorted order.
+    Provides efficient lookup, insertion, and deletion by key.
+
+    Declaration in CSSL:
+        map<string, int> ages;
+        map<string, string> config;
+        map<int, bool> flags;
+
+    Example:
+        map<string, int> ages;
+        ages.insert("Alice", 30);
+        ages.insert("Bob", 25);
+        ages.insert("Carol", 28);
+
+        printl(ages.find("Alice"));     // 30
+        printl(ages.contains("Bob"));   // true
+        printl(ages.size());            // 3
+
+        ages.erase("Bob");
+        printl(ages.size());            // 2
+    """
+
+    def insert(self, key: Any, value: Any) -> 'CSSLMap':
+        """Insert or update key-value pair.
+
+        Args:
+            key: The key to insert
+            value: The value to associate with the key
+
+        Returns:
+            The map (for chaining)
+
+        Example:
+            map<string, int> scores;
+            scores.insert("Alice", 100);
+            scores.insert("Bob", 95);
+            scores.insert("Alice", 105);  // Updates Alice's score
+            printl(scores.find("Alice")); // 105
+        """
+        ...
+
+    def find(self, key: Any) -> Optional[Any]:
+        """Find value by key.
+
+        Args:
+            key: The key to search for
+
+        Returns:
+            The value if found, None otherwise
+
+        Example:
+            map<string, int> ages;
+            ages.insert("Alice", 30);
+            printl(ages.find("Alice"));  // 30
+            printl(ages.find("Bob"));    // null
+        """
+        ...
+
+    def erase(self, key: Any) -> bool:
+        """Remove key-value pair.
+
+        Args:
+            key: The key to remove
+
+        Returns:
+            True if key existed and was removed, False otherwise
+
+        Example:
+            map<string, int> data;
+            data.insert("x", 1);
+            bool removed = data.erase("x");  // true
+            bool again = data.erase("x");    // false (already gone)
+        """
+        ...
+
+    def contains(self, key: Any) -> bool:
+        """Check if key exists.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            True if key exists, False otherwise
+
+        Example:
+            map<string, int> ages;
+            ages.insert("Alice", 30);
+            printl(ages.contains("Alice"));  // true
+            printl(ages.contains("Bob"));    // false
+        """
+        ...
+
+    def count(self, key: Any) -> int:
+        """Count occurrences of key (0 or 1 for map).
+
+        Returns:
+            1 if key exists, 0 otherwise
+        """
+        ...
+
+    def size(self) -> int:
+        """Get number of key-value pairs.
+
+        Example:
+            map<string, int> data;
+            data.insert("a", 1);
+            data.insert("b", 2);
+            printl(data.size());  // 2
+        """
+        ...
+
+    def empty(self) -> bool:
+        """Check if map has no elements.
+
+        Example:
+            map<string, int> data;
+            printl(data.empty());  // true
+            data.insert("x", 1);
+            printl(data.empty());  // false
+        """
+        ...
+
+    def at(self, key: Any) -> Any:
+        """Get value at key (throws if not found).
+
+        Unlike find(), this throws an error if key doesn't exist.
+
+        Args:
+            key: The key to access
+
+        Returns:
+            The value at key
+
+        Raises:
+            KeyError if key not found
+
+        Example:
+            map<string, int> ages;
+            ages.insert("Alice", 30);
+            int age = ages.at("Alice");  // 30
+            // ages.at("Bob");  // ERROR: Key not found
+        """
+        ...
+
+    def begin(self) -> Tuple[Any, Any]:
+        """Get first key-value pair (smallest key).
+
+        Returns:
+            Tuple of (key, value) or None if empty
+
+        Example:
+            map<string, int> data;
+            data.insert("banana", 2);
+            data.insert("apple", 1);
+            data.insert("cherry", 3);
+            tuple first = data.begin();  // ("apple", 1)
+        """
+        ...
+
+    def end(self) -> Tuple[Any, Any]:
+        """Get last key-value pair (largest key).
+
+        Returns:
+            Tuple of (key, value) or None if empty
+
+        Example:
+            map<string, int> data;
+            data.insert("apple", 1);
+            data.insert("cherry", 3);
+            data.insert("banana", 2);
+            tuple last = data.end();  // ("cherry", 3)
+        """
+        ...
+
+    def lower_bound(self, key: Any) -> Optional[Any]:
+        """Find first key >= given key.
+
+        Useful for range queries on sorted keys.
+
+        Args:
+            key: The key to search from
+
+        Returns:
+            First key >= given key, or None if none found
+
+        Example:
+            map<int, string> data;
+            data.insert(10, "ten");
+            data.insert(20, "twenty");
+            data.insert(30, "thirty");
+            printl(data.lower_bound(15));  // 20
+            printl(data.lower_bound(20));  // 20
+        """
+        ...
+
+    def upper_bound(self, key: Any) -> Optional[Any]:
+        """Find first key > given key.
+
+        Args:
+            key: The key to search from
+
+        Returns:
+            First key > given key, or None if none found
+
+        Example:
+            map<int, string> data;
+            data.insert(10, "ten");
+            data.insert(20, "twenty");
+            data.insert(30, "thirty");
+            printl(data.upper_bound(15));  // 20
+            printl(data.upper_bound(20));  // 30
+        """
+        ...
+
+
+class CSSLDataStruct:
+    """CSSL datastruct<T> container - Universal flexible container.
+
+    DataStruct is a lazy declarator that can hold any type of data.
+    It's the primary target container for BruteInjection operations.
+
+    Declaration in CSSL:
+        datastruct<string> data;
+        datastruct<int> numbers;
+        datastruct<dynamic> anything;
+
+    Usage with BruteInjection:
+        stack<string> source = ["A", "B", "C"];
+        datastruct<string> target;
+
+        target +<== source;                         // Copy from source
+        target +<== [string::contains="A"] source;  // Filtered copy
+
+    Example:
+        datastruct<string> names;
+        names.add("Alice");
+        names.add("Bob");
+        printl(names.content());  // ["Alice", "Bob"]
+    """
+
+    def content(self) -> List[T]:
+        """Get all elements as a list.
+
+        Returns:
+            List containing all elements
+
+        Example:
+            datastruct<int> data;
+            data.add(1);
+            data.add(2);
+            printl(data.content());  // [1, 2]
+        """
+        ...
+
+    def add(self, value: T) -> 'CSSLDataStruct':
+        """Add an element to the datastruct.
+
+        Args:
+            value: Element to add
+
+        Returns:
+            The datastruct (for chaining)
+
+        Example:
+            datastruct<string> data;
+            data.add("first").add("second");
+        """
+        ...
+
+    def remove_where(self, predicate: Callable[[T], bool]) -> 'CSSLDataStruct':
+        """Remove all elements matching predicate.
+
+        Args:
+            predicate: Function returning True for items to remove
+
+        Returns:
+            The datastruct (for chaining)
+
+        Example:
+            datastruct<int> nums;
+            nums.add(1);
+            nums.add(2);
+            nums.add(3);
+            nums.remove_where(x => x > 1);
+            printl(nums.content());  // [1]
+        """
+        ...
+
+    def find_where(self, predicate: Callable[[T], bool]) -> Optional[T]:
+        """Find first element matching predicate.
+
+        Args:
+            predicate: Function returning True for match
+
+        Returns:
+            First matching element or None
+
+        Example:
+            datastruct<int> nums = [5, 10, 15];
+            int found = nums.find_where(x => x > 7);  // 10
+        """
+        ...
+
+    def convert(self, target_type: type) -> Any:
+        """Convert first element to target type.
+
+        Args:
+            target_type: Type to convert to
+
+        Returns:
+            Converted value or None if empty
+        """
+        ...
+
+    def begin(self) -> int:
+        """Get iterator to first element (C++ style)."""
+        ...
+
+    def end(self) -> int:
+        """Get iterator past last element (C++ style)."""
+        ...
+
+
+class CSSLIterator:
+    """CSSL iterator<T, size> container - Advanced programmable iterator.
+
+    Iterator provides positions within a data container with the ability
+    to attach tasks (functions) to specific positions. Can be nested
+    for multi-dimensional structures.
+
+    Declaration in CSSL:
+        iterator<int> it;
+        iterator<int, 16> Map;              // 16 positions
+        iterator<iterator<int, 16>> Map2D;  // 2D grid
+
+    Example:
+        // 2D grid example
+        iterator<iterator<int, 16>> Map;
+        Map.insert(3, 12);     // Set value 12 at position 3
+        Map.fill(0);           // Fill all with 0
+        int value = Map.at(3); // Get value at position 3
+    """
+
+    def insert(self, position: int, value: T) -> 'CSSLIterator':
+        """Insert value at position.
+
+        Args:
+            position: Index position
+            value: Value to insert
+
+        Returns:
+            The iterator (for chaining)
+
+        Example:
+            iterator<int> it;
+            it.insert(0, 100);
+            it.insert(1, 200);
+        """
+        ...
+
+    def fill(self, value: T) -> 'CSSLIterator':
+        """Fill all positions with value.
+
+        Args:
+            value: Value to fill with
+
+        Returns:
+            The iterator (for chaining)
+
+        Example:
+            iterator<int, 10> grid;
+            grid.fill(0);  // All positions now 0
+        """
+        ...
+
+    def at(self, position: int) -> T:
+        """Get value at position.
+
+        Args:
+            position: Index position
+
+        Returns:
+            Value at position
+
+        Example:
+            iterator<int> it;
+            it.insert(5, 42);
+            printl(it.at(5));  // 42
+        """
+        ...
+
+    def set(self, position: int, value: T) -> 'CSSLIterator':
+        """Set value at iterator position.
+
+        Args:
+            position: Iterator index
+            value: Value to set
+
+        Returns:
+            The iterator (for chaining)
+        """
+        ...
+
+    def task(self, position: int, func: Callable) -> 'CSSLIterator':
+        """Attach task (function) to iterator position.
+
+        Args:
+            position: Iterator index
+            func: Function to attach
+
+        Returns:
+            The iterator (for chaining)
+
+        Example:
+            iterator<int> it;
+            it.task(0, myHandler);  // Attach handler to position 0
+        """
+        ...
+
+
+class CSSLShuffled:
+    """CSSL shuffled<T> container - Multi-value return container.
+
+    Shuffled is used with the 'shuffled' function keyword to enable
+    functions to return multiple values. Values are unpacked using
+    tuple assignment syntax.
+
+    Declaration in CSSL:
+        shuffled getValues() {
+            return "Alice", 30, true;
+        }
+
+    Usage:
+        shuffled string getNames() {
+            return "first", "middle", "last";
+        }
+
+        // Unpack all values
+        a, b, c = getNames();
+        printl(a);  // "first"
+        printl(b);  // "middle"
+        printl(c);  // "last"
+
+    Example with mixed types:
+        shuffled getData() {
+            return "name", 42, 3.14, true;
+        }
+
+        name, count, price, active = getData();
+        printl(name);   // "name"
+        printl(count);  // 42
+        printl(price);  // 3.14
+        printl(active); // true
+    """
+    pass
+
+
+class CSSLCombo:
+    """CSSL combo<T> container - Filter/search space for open parameters.
+
+    Combo is used for creating filtered search spaces, often in
+    conjunction with 'open' parameter functions.
+
+    Declaration in CSSL:
+        combo<string> searchSpace;
+        combo<open&string> filter = combo<open&string>::like="pattern";
+
+    Example:
+        combo<string> names;
+        names.add("Alice");
+        names.add("Bob");
+        names.add("Anna");
+
+        // Use with filter pattern
+        combo<open&string> filter = combo<open&string>::like="A*";
+    """
+    pass
+
+
+class CSSLDataSpace:
+    """CSSL dataspace<T> container - SQL-like data storage.
+
+    DataSpace provides SQL-like operations for data manipulation.
+    Used for complex data queries and transformations.
+
+    Declaration in CSSL:
+        dataspace<sql::table> table;
+
+    Note: Advanced container for specialized data operations.
+    """
+    pass
+
+
+def OpenFind(type_or_combo: Any, index: int = 0) -> Optional[Any]:
+    """Find parameter by type from open parameters.
+
+    Used inside functions declared with 'open' keyword to
+    extract typed parameters from variadic argument list.
+
+    Args:
+        type_or_combo: The type to search for (e.g., string, int)
+        index: Which occurrence to get (0 = first, 1 = second, etc.)
+
+    Returns:
+        The value at that index of that type, or None
+
+    Usage in CSSL:
+        open define flexibleFunc(open Params) {
+            string name = OpenFind<string>(0);   // First string
+            int num = OpenFind<int>(0);          // First int
+            float val = OpenFind<float>(1);      // Second float
+
+            printl("Name: " + name);
+            printl("Number: " + num);
+        }
+
+        flexibleFunc("Hello", 42, 3.14, "World", 100);
+        // name = "Hello" (first string)
+        // num = 42 (first int)
+        // val = (would need second float in args)
+    """
     ...
+
+
+# =============================================================================
+# CONTAINER TYPE ALIASES (for direct lookup)
+# =============================================================================
+# These aliases allow looking up container methods directly by their CSSL name.
+# Example: typing "stack." shows all stack methods with documentation.
+
+stack = CSSLStack
+"""stack<T> - LIFO (Last In, First Out) container.
+
+Methods:
+    .push(value)      Add element to top
+    .pop()            Remove and return top element
+    .peek()           View top without removing
+    .isEmpty()        Check if empty
+    .size()           Get element count
+    .length()         Alias for size()
+    .contains(value)  Check if value exists
+    .indexOf(value)   Find index of value
+    .toArray()        Convert to plain list
+    .swap()           Swap top two elements
+    .dup()            Duplicate top element
+
+Example:
+    stack<string> names;
+    names.push("Alice");
+    names.push("Bob");
+    printl(names.pop());   // "Bob"
+    printl(names.peek());  // "Alice"
+"""
+
+vector = CSSLVector
+"""vector<T> - Dynamic resizable array with random access.
+
+Methods:
+    .push(value)          Add to end
+    .push_front(value)    Add to front
+    .pop_back()           Remove last
+    .pop_front()          Remove first
+    .at(index)            Get element at index
+    .set(index, value)    Set element at index
+    .front()              Get first element
+    .back()               Get last element
+    .size()               Get element count
+    .contains(value)      Check if value exists
+    .indexOf(value)       Find index of value
+    .slice(start, end)    Get sub-vector
+    .join(separator)      Join to string
+    .map(func)            Transform elements
+    .filter(predicate)    Filter elements
+    .forEach(func)        Execute for each
+    .every(predicate)     Check all match
+    .some(predicate)      Check any match
+    .reduce(func, init)   Reduce to single value
+
+Example:
+    vector<int> nums;
+    nums.push(10).push(20).push(30);
+    printl(nums.at(1));     // 20
+    printl(nums.front());   // 10
+    printl(nums.back());    // 30
+"""
+
+array = CSSLArray
+"""array<T> - Standard array with CSSL methods.
+
+Methods:
+    .push(value)          Add to end
+    .pop()                Remove last
+    .at(index)            Get element at index
+    .set(index, value)    Set element at index
+    .first()              Get first element
+    .last()               Get last element
+    .size()               Get element count
+    .length()             Alias for size()
+    .contains(value)      Check if value exists
+    .indexOf(value)       Find index of value
+    .slice(start, end)    Get sub-array
+    .join(separator)      Join to string
+    .map(func)            Transform elements
+    .filter(predicate)    Filter elements
+
+Example:
+    array<string> colors;
+    colors.push("red");
+    colors.push("green");
+    printl(colors.first());   // "red"
+    printl(colors.length());  // 2
+"""
+
+map = CSSLMap
+"""map<K, V> - C++ style ordered key-value container.
+
+Methods:
+    .insert(key, value)   Insert or update key-value pair
+    .find(key)            Find value by key (returns None if not found)
+    .erase(key)           Remove key-value pair
+    .contains(key)        Check if key exists
+    .at(key)              Get value (throws if not found)
+    .size()               Get pair count
+    .empty()              Check if empty
+    .begin()              Get first (key, value) pair
+    .end()                Get last (key, value) pair
+    .lower_bound(key)     Find first key >= given key
+    .upper_bound(key)     Find first key > given key
+
+Example:
+    map<string, int> ages;
+    ages.insert("Alice", 30);
+    ages.insert("Bob", 25);
+    printl(ages.find("Alice"));     // 30
+    printl(ages.contains("Bob"));   // true
+    ages.erase("Bob");
+"""
+
+datastruct = CSSLDataStruct
+"""datastruct<T> - Universal container for BruteInjection operations.
+
+Methods:
+    .content()            Get all elements as list
+    .add(value)           Add element
+    .remove_where(pred)   Remove matching elements
+    .find_where(pred)     Find first matching element
+    .begin()              Iterator to start
+    .end()                Iterator to end
+
+Usage with BruteInjection:
+    stack<string> source = ["A", "B", "C"];
+    datastruct<string> target;
+    target +<== source;                         // Copy all
+    target +<== [string::contains="A"] source;  // Filtered copy
+
+Example:
+    datastruct<string> data;
+    data.add("Alice").add("Bob");
+    printl(data.content());  // ["Alice", "Bob"]
+"""
+
+iterator = CSSLIterator
+"""iterator<T, size> - Advanced programmable iterator container.
+
+Methods:
+    .insert(pos, value)   Insert value at position
+    .fill(value)          Fill all positions with value
+    .at(pos)              Get value at position
+    .set(pos, value)      Set value at position
+    .task(pos, func)      Attach function to position
+
+Example (2D grid):
+    iterator<iterator<int, 16>> Map;
+    Map.insert(3, 12);     // Set value 12 at position 3
+    Map.fill(0);           // Fill all with 0
+    int value = Map.at(3); // Get value at position 3
+"""
+
+shuffled = CSSLShuffled
+"""shuffled<T> - Container for multi-value returns.
+
+Used with 'shuffled' function keyword to return multiple values.
+Values are unpacked using tuple assignment syntax.
+
+Example:
+    shuffled string getNames() {
+        return "first", "middle", "last";
+    }
+
+    a, b, c = getNames();
+    printl(a);  // "first"
+    printl(b);  // "middle"
+    printl(c);  // "last"
+
+    // Mixed types
+    shuffled getData() {
+        return "name", 42, true;
+    }
+    name, count, flag = getData();
+"""
+
+combo = CSSLCombo
+"""combo<T> - Filter/search space for open parameters.
+
+Example:
+    combo<string> searchSpace;
+    combo<open&string> filter = combo<open&string>::like="A*";
+"""
+
+dataspace = CSSLDataSpace
+"""dataspace<T> - SQL-like data storage container.
+
+Example:
+    dataspace<sql::table> table;
+"""
+
+
+# =============================================================================
+# FUNCTION KEYWORDS (for defining functions)
+# =============================================================================
+
+class FunctionKeywords:
+    """
+    CSSL Function Keywords - Special modifiers for function definitions.
+
+    These are not callable functions but keywords used when defining functions.
+    """
+
+    def void(self) -> None:
+        """Function without return value.
+
+        Example:
+            void sayHello() {
+                printl("Hello!");
+            }
+        """
+        ...
+
+    def define(self) -> None:
+        """Constant function without type declaration.
+
+        Does not require return type or 'void'. Used for simple procedures.
+
+        Example:
+            define LOG_MESSAGE() {
+                printl("Log entry");
+            }
+
+            define processData() {
+                // do something
+            }
+        """
+        ...
+
+    def undefined(self) -> None:
+        """Function that silently ignores errors.
+
+        Any exceptions during execution are caught and ignored.
+        Useful for optional operations that may fail.
+
+        Example:
+            undefined void mayFail() {
+                riskyOperation();  // Errors ignored
+            }
+            mayFail();  // Won't crash even if error occurs
+        """
+        ...
+
+    def closed(self) -> None:
+        """Function protected from EXTERNAL code injection.
+
+        Prevents external scripts from using <<== to modify this function.
+        Internal injections (same file) still work.
+
+        Example:
+            closed void protectedFunc() {
+                printl("Protected from external injection");
+            }
+
+            // This will be BLOCKED if from different file:
+            protectedFunc() <<== { printl("Blocked!"); }
+        """
+        ...
+
+    def private(self) -> None:
+        """Function with ALL injections blocked.
+
+        Completely protects function from any CodeInfusion.
+        No <<==, +<<==, or -<<== operations will work.
+
+        Example:
+            private void superSecure() {
+                printl("Cannot be modified");
+            }
+        """
+        ...
+
+    def virtual(self) -> None:
+        """Function safe for import cycles.
+
+        Prevents infinite recursion when modules import each other.
+
+        Example:
+            virtual void safeForImport() {
+                // Safe to call from circular imports
+            }
+        """
+        ...
+
+    def meta(self) -> None:
+        """Function declared as source provider (must return).
+
+        Indicates function provides metadata or source information.
+
+        Example:
+            meta string getSource() {
+                return "source code here";
+            }
+        """
+        ...
+
+    def super_keyword(self) -> None:
+        """Function that forces execution without exceptions.
+
+        Function will complete even if errors occur internally.
+
+        Example:
+            super void forceRun() {
+                printl("Will ALWAYS complete");
+            }
+        """
+        ...
+
+    def shuffled_keyword(self) -> None:
+        """Function that can return multiple values.
+
+        Return statement can have comma-separated values.
+        Caller can unpack using tuple assignment.
+
+        Example:
+            shuffled string getNames() {
+                return "Alice", "Bob", "Charlie";
+            }
+
+            // Unpack all values
+            a, b, c = getNames();
+
+            // Or with mixed types
+            shuffled getValues() {
+                return "hello", 42, true;
+            }
+            text, num, flag = getValues();
+        """
+        ...
+
+    def open(self) -> None:
+        """Function that accepts any number/type of parameters.
+
+        Use with 'open Params' to accept variadic arguments.
+        Use OpenFind<type>(index) to extract typed values.
+
+        Example:
+            open define flexibleFunc(open Params) {
+                string name = OpenFind<string>(0);
+                int count = OpenFind<int>(0);
+                printl("Name: " + name + ", Count: " + count);
+            }
+
+            flexibleFunc("Alice", 42, true, "extra");
+            // Extracts: name="Alice", count=42
+        """
+        ...
+
+# =============================================================================
+# CLASSES & OOP
+# =============================================================================
+
+class ClassSyntax:
+    """
+    CSSL Class Syntax - Object-Oriented Programming support.
+
+    CSSL supports classes with constructors, members, and methods.
+    Use 'this->' to access instance members inside methods.
+    Use 'new' keyword to instantiate classes.
+    """
+
+    def class_definition(self) -> None:
+        """Define a class with members and methods.
+
+        Example:
+            class Person {
+                // Member variables
+                string name;
+                int age;
+
+                // Constructor (same name as class)
+                void Person(string n, int a) {
+                    this->name = n;
+                    this->age = a;
+                }
+
+                // Methods
+                void greet() {
+                    printl("Hello, I'm " + this->name);
+                }
+
+                string getName() {
+                    return this->name;
+                }
+
+                void setAge(int a) {
+                    this->age = a;
+                }
+            }
+        """
+        ...
+
+    def new_keyword(self) -> None:
+        """Instantiate a class using 'new' keyword.
+
+        Example:
+            Person p = new Person("Alice", 30);
+            p.greet();                    // "Hello, I'm Alice"
+            string name = p.getName();    // "Alice"
+            p.setAge(31);
+        """
+        ...
+
+    def this_keyword(self) -> None:
+        """Access instance members with 'this->' inside methods.
+
+        Example:
+            class Counter {
+                int count;
+
+                void Counter() {
+                    this->count = 0;
+                }
+
+                void increment() {
+                    this->count = this->count + 1;
+                }
+
+                int get() {
+                    return this->count;
+                }
+            }
+        """
+        ...
+
+# =============================================================================
+# SPECIAL SYNTAX REFERENCE
+# =============================================================================
+
+class SpecialSyntax:
+    """
+    CSSL Special Syntax Reference
+
+    Reference for CSSL-specific syntax elements.
+    """
+
+    def global_variables(self) -> None:
+        """Global variable syntax.
+
+        Declare with 'global' keyword, access with '@' prefix.
+
+        Example:
+            // Declaration
+            global myGlobal = "visible everywhere";
+            r@anotherGlobal = "alternative syntax";
+
+            // Access
+            printl(@myGlobal);
+            @myGlobal = "new value";
+
+            // In functions
+            void increment() {
+                @counter = @counter + 1;
+            }
+        """
+        ...
+
+    def shared_objects(self) -> None:
+        """Shared Python object syntax ($name).
+
+        Access Python objects shared via CSSL.share().
+        Changes reflect back to Python.
+
+        Example:
+            // Python: cssl.share(myObj, "data")
+
+            // CSSL:
+            $data.property = "value";
+            $data.method();
+            printl($data.result);
+
+            // Delete when done
+            delete("data");
+        """
+        ...
+
+    def captured_references(self) -> None:
+        """Value capture syntax (%identifier).
+
+        Captures value at registration time, not execution time.
+        Useful for saving original functions before replacement.
+
+        Example:
+            string version = "1.0";
+            savedVersion <== { %version; }
+            version = "2.0";
+            printl(savedVersion);  // Still "1.0"
+
+            // Save original function
+            originalExit <<== { %exit(); }
+            exit() <<== {
+                printl("Custom exit");
+                originalExit();  // Call saved original
+            }
+        """
+        ...
+
+    def code_infusion(self) -> None:
+        """CodeInfusion operators for modifying functions.
+
+        IMPORTANT: Write operators WITHOUT spaces!
+
+        Operators:
+            <<==   Replace function content
+            +<<==  Add code BEFORE original
+            -<<==  Remove matching code
+
+        Example:
+            void original() { printl("Original"); }
+
+            // Replace
+            original() <<== { printl("Replaced"); }
+
+            // Add before
+            original() +<<== { printl("Before"); }
+
+            // Remove code
+            original() -<<== { printl("Unwanted"); }
+        """
+        ...
+
+    def brute_injection(self) -> None:
+        """BruteInjection operators for data transfer.
+
+        Operators:
+            +<==   Copy data (source unchanged)
+            -<==   Move data (removes from source)
+            ==>    Replace target data
+            ==>-   Remove matching items from target
+
+        Example:
+            stack<string> source = ["A", "B", "C"];
+            datastruct<string> target;
+
+            target +<== source;           // Copy
+            target -<== source;           // Move (source empty)
+            target ==> newData;           // Replace
+            target ==>- ["A"];            // Remove "A" from target
+
+            // With filters
+            target +<== [string::contains="X"] source;
+        """
+        ...
+
+    def filter_syntax(self) -> None:
+        """Filter syntax for BruteInjection.
+
+        Format: [type::filter=value]
+
+        String filters:
+            string::where="value"      Exact match
+            string::not="value"        Exclude
+            string::contains="sub"     Contains substring
+            string::length=5           Exact length
+            string::cut=3              First N chars
+            string::cutAfter="sub"     After substring
+
+        Example:
+            stack<string> names = ["Alice", "Bob", "Anna"];
+            datastruct<string> result;
+            result +<== [string::contains="A"] names;
+            // result = ["Alice", "Anna"]
+        """
+        ...
+
+# =============================================================================
+# EXPORTS
+# =============================================================================
+
+__all__ = [
+    # Output
+    "print", "printl", "println", "debug", "error", "warn", "log",
+    # Type conversion
+    "int", "float", "str", "bool", "list", "dict",
+    # Type checking
+    "typeof", "isinstance", "isint", "isfloat", "isstr", "isbool",
+    "islist", "isdict", "isnull",
+    # String
+    "len", "upper", "lower", "trim", "ltrim", "rtrim", "split", "join",
+    "replace", "substr", "contains", "startswith", "endswith", "format",
+    "concat", "repeat", "reverse", "indexof", "lastindexof", "padleft",
+    "padright", "capitalize", "title", "swapcase", "center", "zfill",
+    "chars", "ord", "chr", "isalpha", "isdigit", "isalnum", "isspace",
+    "sprintf",
+    # Array/List
+    "push", "pop", "shift", "unshift", "slice", "sort", "rsort",
+    "unique", "flatten", "filter", "map", "reduce", "find", "findindex",
+    "every", "some", "range", "enumerate", "zip", "reversed", "count",
+    "first", "last", "take", "drop", "chunk", "shuffle", "sample",
+    # Dictionary
+    "keys", "values", "items", "haskey", "getkey", "setkey", "delkey",
+    "merge", "update", "fromkeys", "invert", "pick", "omit", "groupby",
+    # Math
+    "abs", "min", "max", "sum", "avg", "round", "floor", "ceil",
+    "pow", "sqrt", "mod", "random", "randint", "sin", "cos", "tan",
+    "asin", "acos", "atan", "atan2", "log", "log10", "exp", "pi", "e",
+    "radians", "degrees",
+    # Date/Time
+    "now", "timestamp", "sleep", "delay", "date", "time", "datetime",
+    "strftime",
+    # File System
+    "read", "readline", "write", "writeline", "appendfile", "readlines",
+    "pathexists", "isfile", "isdir", "listdir", "makedirs", "removefile",
+    "removedir", "copyfile", "movefile", "filesize", "basename", "dirname",
+    "joinpath", "abspath", "normpath", "splitpath",
+    # JSON (json:: namespace)
+    "json_read", "json_write", "json_parse", "json_stringify", "json_pretty",
+    "json_get", "json_set", "json_has", "json_keys", "json_values", "json_merge",
+    # Instance (instance:: namespace)
+    "instance_getMethods", "instance_getClasses", "instance_getVars",
+    "instance_getAll", "instance_call", "instance_has", "instance_type",
+    "isavailable",
+    # Regex
+    "match", "search", "findall", "sub",
+    # Hash
+    "md5", "sha1", "sha256",
+    # System/Control
+    "exit", "input", "env", "setenv", "clear", "copy", "deepcopy",
+    "assert_condition", "pyimport", "include", "payload", "color",
+    "original", "delete",
+    # Platform
+    "isLinux", "isWindows", "isMac",
+    # Container Classes (with methods)
+    "CSSLStack", "CSSLVector", "CSSLArray", "CSSLMap", "CSSLDataStruct",
+    "CSSLIterator", "CSSLShuffled", "CSSLCombo", "CSSLDataSpace", "OpenFind",
+    # Container Type Aliases (use these for quick method lookup)
+    "stack", "vector", "array", "map", "datastruct", "iterator", "shuffled", "combo", "dataspace",
+    # Syntax Reference Classes
+    "FunctionKeywords", "ClassSyntax", "SpecialSyntax",
+]