Update base package documentation

base/Home.md

@@ -12,7 +12,7 @@ The `base` package provides core data structures and memory abstractions: dynami
 
 ## 🗄️ Allocator Interface
 
-A pluggable allocator that abstracts memory allocation strategies. See os package for the arena-backed implementation.
+A pluggable allocator that abstracts memory allocation strategies. See `os` package for the arena-backed implementation.
 
 ```c
 typedef struct Allocator Allocator;
@@ -86,11 +86,28 @@ A type-generic dynamic array with both stack-allocated and allocator-backed vari
 
 ### Allocator-backed Operations (may grow)
 
+These macros **return the array pointer**, which may differ from the input if reallocation occurred. Always assign the result back to your array variable.
+
 | Macro | Description |
 |-------|-------------|
-| `wapp_array_append_alloc(type, allocator, array, value_ptr, flags)` | Appends, growing via allocator |
+| `wapp_array_append_alloc(type, allocator, array, value_ptr, flags)` | Appends, growing via allocator. Returns (possibly new) array pointer. |
-| `wapp_array_extend_alloc(type, allocator, dst, src, flags)` | Extends, growing via allocator |
+| `wapp_array_extend_alloc(type, allocator, dst, src, flags)` | Extends, growing via allocator. Returns (possibly new) dst pointer. |
-| `wapp_array_copy_alloc(type, allocator, dst, src, flags)` | Copies, growing via allocator |
+| `wapp_array_copy_alloc(type, allocator, dst, src, flags)` | Copies, growing via allocator. Returns (possibly new) dst pointer. |
+
+```c
+I32Array arr = wapp_array_alloc_capacity(i32, &arena, 4, ARRAY_INIT_NONE);
+
+i32 val = 42;
+I32Array new_arr = wapp_array_append_alloc(i32, &arena, &arr, &val, ARRAY_INIT_NONE);
+
+if (new_arr != arr) {
+    // Reallocation occurred — the old memory is still valid
+    // but will be managed by the allocator (no manual free needed
+    // for arena allocators; for malloc-like allocators you may
+    // need to free the old array).
+    arr = new_arr;
+}
+```
 
 ### Other