docs: document 14 new string/list built-ins in reference and spec

docs/reference/ax-language.md

@@ -236,7 +236,7 @@ import "std-name"
 
 Import statements load a standard library package at compile time. The library source is inlined into the compilation unit before type-checking. The import line itself is removed from the compiled output.
 
-Standard library packages are resolved from the `libs/` directory relative to the current working directory.
+Standard library packages are resolved from the `libs/` directory relative to the current working directory. When a library source is inlined, any `fn main() -> Int` stub present in the library file is stripped so it does not conflict with the importing program's own `main`.
 
 Example:
 
@@ -259,6 +259,20 @@ These functions are provided by the runtime and do not need to be imported:
 | `__builtin_float_to_string` | `(Float) -> String` | Convert a float to its string representation |
 | `__builtin_string_len` | `(String) -> Int` | Length of a string in bytes |
 | `__builtin_string_chars` | `(String) -> List<String>` | Split a string into a list of single-character strings |
+| `__builtin_string_contains` | `(String, String) -> Bool` | True if first string contains the second |
+| `__builtin_string_starts_with` | `(String, String) -> Bool` | True if string starts with prefix |
+| `__builtin_string_ends_with` | `(String, String) -> Bool` | True if string ends with suffix |
+| `__builtin_string_to_upper` | `(String) -> String` | Uppercase copy |
+| `__builtin_string_to_lower` | `(String) -> String` | Lowercase copy |
+| `__builtin_string_trim` | `(String) -> String` | Strip leading/trailing whitespace |
+| `__builtin_string_join` | `(List<String>, String) -> String` | Join list with separator |
+| `__builtin_list_len` | `(List<T>) -> Int` | Number of elements |
+| `__builtin_list_is_empty` | `(List<T>) -> Bool` | True if list has zero elements |
+| `__builtin_list_head` | `(List<T>) -> Option<T>` | First element, or None |
+| `__builtin_list_tail` | `(List<T>) -> List<T>` | All elements after the first |
+| `__builtin_list_append` | `(List<T>, T) -> List<T>` | New list with item added at end |
+| `__builtin_list_concat` | `(List<T>, List<T>) -> List<T>` | Concatenate two lists |
+| `__builtin_list_reverse` | `(List<T>) -> List<T>` | Reversed copy |
 
 These built-ins are also wrapped in `std-json` (via `int_to_string`, `json_escape`) and can be called directly in any `.ax` file.
 

docs/spec/ax-language-1.0.md

@@ -438,6 +438,42 @@ Pattern matching introduces bindings into the arm's scope:
 
 Bindings are only in scope within the arm's right-hand side.
 
+## 5a. Standard built-in functions
+
+The following functions are provided by the runtime in every compilation unit. They require no import. Their names begin with `__builtin_` to prevent shadowing by user-defined identifiers.
+
+All built-ins are pure (no capability annotation). Their semantics are defined below.
+
+### String operations
+
+| Name | Signature | Semantics |
+|------|-----------|-----------|
+| `__builtin_int_to_string` | `(Int) -> String` | Returns the decimal string representation of the argument. |
+| `__builtin_float_to_string` | `(Float) -> String` | Returns a string representation of the float argument. |
+| `__builtin_string_len` | `(String) -> Int` | Returns the number of bytes in the UTF-8 encoding of the string. |
+| `__builtin_string_chars` | `(String) -> List<String>` | Returns a list of single-character strings, one per Unicode scalar value. |
+| `__builtin_string_contains` | `(String, String) -> Bool` | Returns `true` iff the first argument contains the second as a substring. |
+| `__builtin_string_starts_with` | `(String, String) -> Bool` | Returns `true` iff the first argument begins with the prefix given by the second. |
+| `__builtin_string_ends_with` | `(String, String) -> Bool` | Returns `true` iff the first argument ends with the suffix given by the second. |
+| `__builtin_string_to_upper` | `(String) -> String` | Returns a copy of the string with all ASCII alphabetic characters uppercased. |
+| `__builtin_string_to_lower` | `(String) -> String` | Returns a copy of the string with all ASCII alphabetic characters lowercased. |
+| `__builtin_string_trim` | `(String) -> String` | Returns a copy of the string with leading and trailing ASCII whitespace removed. |
+| `__builtin_string_join` | `(List<String>, String) -> String` | Returns the elements of the list concatenated, with the second argument inserted between each pair of adjacent elements. |
+
+### List operations
+
+| Name | Signature | Semantics |
+|------|-----------|-----------|
+| `__builtin_list_len` | `(List<T>) -> Int` | Returns the number of elements in the list. |
+| `__builtin_list_is_empty` | `(List<T>) -> Bool` | Returns `true` iff the list has zero elements. |
+| `__builtin_list_head` | `(List<T>) -> Option<T>` | Returns `Some(first)` if the list is non-empty, otherwise `None`. |
+| `__builtin_list_tail` | `(List<T>) -> List<T>` | Returns a new list containing all elements after the first. Returns an empty list if the argument is empty. |
+| `__builtin_list_append` | `(List<T>, T) -> List<T>` | Returns a new list equal to the original with the second argument appended at the end. |
+| `__builtin_list_concat` | `(List<T>, List<T>) -> List<T>` | Returns a new list that is the concatenation of the two arguments, in order. |
+| `__builtin_list_reverse` | `(List<T>) -> List<T>` | Returns a new list containing the same elements in reversed order. |
+
+All list built-ins are non-mutating; the original list is unchanged. This is consistent with the immutability requirement in §7.2.
+
 ## 6. Capability semantics
 
 ### 6.1 Annotation form