1 files changed, 83 insertions, 0 deletions
diff --git a/docs/std/json.md b/docs/std/json.md
new file mode 100644
index 0000000..ce35d64
--- /dev/null
+++ b/docs/std/json.md
@@ -0,0 +1,83 @@
+# JSON (`std/json.zc`)
+
+The `std/json` module provides a DOM-style JSON parser and builder.
+
+## Usage
+
+```zc
+import "std/json.zc"
+```
+
+## Types
+
+### Struct `JsonValue`
+
+Represents a node in a JSON document.
+
+#### Creation Methods
+
+- **`fn null() -> JsonValue`**, **`fn null_ptr() -> JsonValue*`**
+- **`fn bool(b: bool) -> JsonValue`**, **`fn bool_ptr(b: bool) -> JsonValue*`**
+- **`fn number(n: double) -> JsonValue`**, **`fn number_ptr(n: double) -> JsonValue*`**
+- **`fn string(s: char*) -> JsonValue`**, **`fn string_ptr(s: char*) -> JsonValue*`**
+- **`fn array() -> JsonValue`**, **`fn array_ptr() -> JsonValue*`**
+- **`fn object() -> JsonValue`**, **`fn object_ptr() -> JsonValue*`**
+
+#### Parsing
+
+- **`fn parse(json: char*) -> Result<JsonValue*>`**
+  Parses a JSON string into a heap-allocated `JsonValue` tree.
+
+#### Accessors
+
+- **`fn is_null(self) -> bool`**, **`is_bool`**, **`is_number`**, **`is_string`**, **`is_array`**, **`is_object`**
+  Check the type of the value.
+
+- **`fn as_string(self) -> Option<char*>`**
+  Returns `Some(string)` if the value is a string, `None` otherwise.
+- **`fn as_int(self) -> Option<int>`**
+- **`fn as_float(self) -> Option<double>`**
+- **`fn as_bool(self) -> Option<bool>`**
+
+#### Object/Array Operations
+
+- **`fn push(self, val: JsonValue)`**
+  Appends a value to an array.
+- **`fn set(self, key: char*, val: JsonValue)`**
+  Sets a key-value pair in an object.
+
+- **`fn get(self, key: char*) -> Option<JsonValue*>`**
+  Retrieves a value from an object by key.
+- **`fn at(self, index: usize) -> Option<JsonValue*>`**
+  Retrieves a value from an array by index.
+
+#### Serialization
+
+- **`fn to_string(self) -> String`**
+  Serializes the JSON value to a string representation.
+  
+- **`fn stringify(self, buf: String*)`**
+  Internal recursive serialization method that appends to a string buffer.
+  
+**Example:**
+```zc
+let obj = JsonValue::object();
+obj.set("name", JsonValue::string("Alice"));
+obj.set("age", JsonValue::number(30.0));
+
+let json_str = obj.to_string();
+println "{json_str.c_str()}";  // {"name":"Alice","age":30}
+json_str.free();
+obj.free();
+```
+
+**Features:**
+- Proper escaping of special characters: `\"`, `\\`, `\n`, `\t`, `\r`, `\b`, `\f`
+- Numbers formatted with `%.15g` for precision
+- Recursive serialization for nested objects and arrays
+- Round-trip compatible with `parse()`
+
+#### Memory Management
+
+- **`fn free(self)`**
+  Recursively frees the JSON value and all its children.