diff --git a/AGENTS.md b/AGENTS.md
index 82a2260..97536a0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -167,8 +167,30 @@ can fail if the backing buffer is exhausted.
 passing a runtime variable triggers undefined behaviour and compiler warnings.
 Use `wpArrayAllocCapacity` with an arena allocator for runtime sizes.
 
-Initialise arrays with `WP_ARRAY_INIT_FILLED` to set `count = capacity`
-immediately, allowing direct indexing.
+Always use typed array aliases (`WpU64Array`, `PrNodeIdArray`, etc.) rather
+than raw pointers when declaring array variables. Follow the existing typedef
+pattern in the module (`typedef Type *TypeArray`).
+
+Use named init flags (`WP_ARRAY_INIT_NONE`, `WP_ARRAY_INIT_FILLED`) instead of
+bare `0` — they make the initialisation policy explicit.
+
+- `WP_ARRAY_INIT_FILLED`: sets `count = capacity` on allocation. Required when
+  you plan to index into the array directly (not via append/push), since the
+  array's `count` must reflect valid elements for any downstream use.
+- `WP_ARRAY_INIT_NONE`: leaves `count = 0`. Use when you'll fill the array
+  incrementally via `wpArrayAppendCapped` / `wpArrayAppendAlloc`.
+
+Use `wpArrayCapacity(arr)`, `wpArrayCount(arr)`, `wpArraySetCount(arr, n)` to
+query and control array state rather than computing sizes manually.
+
+### Local/scratch arenas
+
+For function-local scratch allocations, use `wpMemArenaAllocatorInitZero` with a
+fixed size rather than a stack buffer + `InitWithBuffer`:
+
+```c
+WpAllocator scratch = wpMemArenaAllocatorInitZero(KiB(16));
+```
 
 ## Documentation