updated camelot docs

src/pages/docs/camelot/core/io.md

@@ -72,6 +72,122 @@ This returns memory to the originating allocator, preventing double-frees and li
 | `STRING_format()` for allocator-aware formatting | Any format function bypassing `Allocator*` |
 | All return values checked via `Result` | Unchecked truncation or overrun |
 
+## API Reference
+
+### `IO_read`
+
+```c
+Result IO_read(Allocator* alloc, String path);
+```
+
+**Summary**: Reads the entire contents of a file into a dynamically allocated buffer. Uses the provided allocator for safe memory tracking.
+
+- **Parameters**:
+  - `alloc` (`Allocator*`): The allocator used to provision the read buffer.
+  - `path` (`String`): The file system path to read from.
+- **Returns**: `Result` containing `OK` with the file data payload, `NIL` if the file is empty, or `ERR` on system failure.
+- **Errors**: Returns `ERR_FILE_ERROR` if the file does not exist or permissions are denied.
+- **See Also**: [`IO_write`](#io_write)
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```c
+Result res = IO_read(arena, STRING("config.txt"));
+if (res.status == RESULT_OK) {
+    Slice data = res.payload;
+    // Process data...
+}
+```
+
+</details>
+
+### `IO_write`
+
+```c
+Result IO_write(Allocator* alloc, String path, Slice data);
+```
+
+**Summary**: Safely writes a slice of bytes to a file. Overwrites the file if it exists, or creates it if it does not.
+
+- **Parameters**:
+  - `alloc` (`Allocator*`): The allocator used for any internal temporary buffers.
+  - `path` (`String`): The destination file system path.
+  - `data` (`Slice`): The byte payload to write to disk.
+- **Returns**: `Result` containing `OK` on success, or `ERR` on failure.
+- **Errors**: Returns `ERR_FILE_ERROR` on permission denial or I/O failure.
+- **See Also**: [`IO_read`](#io_read)
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```c
+String content = STRING("Hello, Camelot!");
+Slice data = SLICE_FROM_STRING(content);
+Result res = IO_write(arena, STRING("output.txt"), data);
+```
+
+</details>
+
+### `STRING_format`
+
+```c
+[[nodiscard]] Result STRING_format(Allocator* alloc, const char* fmt, ...);
+```
+
+**Summary**: Allocator-aware string formatting utility. Acts as a memory-safe alternative to `asprintf`, preventing double-frees and unmanaged memory.
+
+- **Parameters**:
+  - `alloc` (`Allocator*`): The allocator to provision the resulting string.
+  - `fmt` (`const char*`): A standard `printf`-style format string.
+  - `...`: Variadic arguments matching the format specifiers.
+- **Returns**: `Result` containing an `OwnedString*` payload on success.
+- **Errors**: Returns `ERR_MEMORY_ERROR` if allocation fails, or `ERR_FORMAT_ERROR` on encoding issues.
+- **See Also**: [`OWNEDSTRING_deinit`](#ownedstring_deinit), [`STRING_formatVariadic`](#string_formatvariadic)
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```c
+Result res = STRING_format(arena, "Failed to open %s (Code: %d)", path.ptr, err_code);
+if (res.status == RESULT_OK) {
+    OwnedString* str = res.payload;
+    printf("%s\n", str->view.ptr);
+    OWNEDSTRING_deinit(str);
+}
+```
+
+</details>
+
+### `STRING_formatVariadic`
+
+```c
+[[nodiscard]] Result STRING_formatVariadic(Allocator* alloc, const char* fmt, va_list args);
+```
+
+**Summary**: Variadic list variant of `STRING_format`. Useful for building custom logging or formatting wrappers.
+
+- **Parameters**:
+  - `alloc` (`Allocator*`): The allocator to provision the resulting string.
+  - `fmt` (`const char*`): A standard `printf`-style format string.
+  - `args` (`va_list`): An initialized variadic argument list.
+- **Returns**: `Result` containing an `OwnedString*` payload on success.
+- **See Also**: [`STRING_format`](#string_format)
+
+### `OWNEDSTRING_deinit`
+
+```c
+void OWNEDSTRING_deinit(OwnedString* str);
+```
+
+**Summary**: Safely deallocates an `OwnedString`, returning its memory to the originating allocator.
+
+- **Parameters**:
+  - `str` (`OwnedString*`): A pointer to the owned string to destroy. If `NULL`, the function is a no-op.
+- **Side Effects**: The memory underlying `str->view` is freed, and the `str` struct itself is destroyed.
+- **See Also**: [`STRING_format`](#string_format)
+
+
 ## CI/CD Pipeline
 
 The I/O module is validated through the full CI/CD pipeline defined in `.github/workflows/ci.yml`:

src/pages/docs/camelot/core/merlin.md

@@ -123,16 +123,85 @@ When launched without arguments, Merlin presents an animated terminal dashboard
 🔮 Merlin >
 ```
 
-### Available Commands
-
-| Command | Aliases | Description |
-|---|---|---|
-| `all` | `build`, `1` | Compile the full framework |
-| `test` | `2` | Build and run the sanitizer test suite |
-| `run` | `3` | Build and launch the executable |
-| `clean` | `4` | Delete all object files and binaries |
-| `help` | `dashboard`, `h` | Redraw the dashboard with updated metrics |
-| `exit` | `quit`, `q`, `5` | Exit the Merlin shell |
+## Command Reference
+
+### `all`
+
+**Aliases**: `build`, `1`
+
+**Summary**: Compiles the entire Camelot framework. It discovers all `.c` files in the `src/` directory and compiles them based on the active profile.
+
+- **Side Effects**: Generates object files in `obj/` and outputs the final binary to `bin/camelot`.
+- **Errors**: Halts and displays compiler errors if any source file fails to compile.
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```bash
+# Interactive mode
+🔮 Merlin > all
+
+# Non-interactive CI mode
+./bin/merlin all
+```
+
+</details>
+
+### `test`
+
+**Aliases**: `2`
+
+**Summary**: Compiles and executes the sanitizer test suite. It builds all framework objects and test files, automatically excluding the main application entry point.
+
+- **Side Effects**: Generates the `bin/test_camelot` executable and runs it.
+- **Errors**: Returns a non-zero exit code if any assertions fail or if Address/Leak/Undefined Behavior Sanitizers detect issues.
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```bash
+🔮 Merlin > test
+```
+
+</details>
+
+### `run`
+
+**Aliases**: `3`
+
+**Summary**: Builds the executable (if not already up-to-date) and launches it directly from the build engine.
+
+- **Side Effects**: Suspends Merlin temporarily while the child process `bin/camelot` runs.
+- **See Also**: [`all`](#all)
+
+### `clean`
+
+**Aliases**: `4`
+
+**Summary**: Purges all generated artifacts to ensure a pristine workspace.
+
+- **Side Effects**: Recursively deletes the `obj/` and `bin/` directories.
+
+<details>
+<summary><b>Example Usage</b></summary>
+
+```bash
+🔮 Merlin > clean
+```
+
+</details>
+
+### `help`
+
+**Aliases**: `dashboard`, `h`
+
+**Summary**: Redraws the interactive dashboard UI. Useful if the terminal gets cluttered by compiler warnings or child process output.
+
+### `exit`
+
+**Aliases**: `quit`, `q`, `5`
+
+**Summary**: Gracefully terminates the interactive Merlin shell and returns to the system prompt.
 
 ### CI/CD Non-Interactive Mode