updated documentation to have mermaid diagrams; updated AGENTS.md to note that all future diagrams should be mermaid diagrams first with text-based diagrams as fallback where not applicable

resources/ai/research/data-streaming/04-odin-client-integration.md

@@ -17,6 +17,21 @@ has two C-related access points:
    schema plus a small `libflatccrt.a` runtime. Works via the C ABI, so Odin's
    `foreign import` can consume it.
 
+Choosing a path:
+
+```mermaid
+flowchart TD
+    NAT{"primary target is native desktop?"}
+    NAT -- "yes" --> CGO{"want to avoid C in the build?"}
+    CGO -- "yes" --> PATHA["Path B · pure-Odin reader<br/>hand-rolled, no C dependency"]
+    CGO -- "no" --> PATHA
+    CGO -- "prefer proven lib / less maintenance" --> PATHC["Path A · FFI to FlatCC<br/>bind generated C headers"]
+    PATHC --> REUSE["Path C · OdinArrow reuse<br/>or borrow its decode patterns"]
+    NAT -- "no · browser/WASM" --> PATHD["Path D · TS/JS interop<br/>official JS lib → typed arrays into WASM"]
+```
+
+Index of paths:
+
 | Path | Effort | Zero-copy on reads | Notes |
 |---|---|---|---|
 | A: FFI to FlatCC (C runtime) | Medium | ✅ | Bind generated C headers to Odin `foreign` |
@@ -175,12 +190,14 @@ typed Odin slices.
 The rendering win only materializes if data stays zero-copy **into the frame
 loop**:
 
-1. Fetch frame bytes → owned `[dynamic]u8` (or a slice pinned for the lifetime
-   of the frame).
-2. `verify` the buffer once.
-3. Get `ra_slice := ObjectBatch.ra(&buf)` → `[]f64` view.
-4. Per object in `update()`/`draw()`: read `ra[i]`, `dec[i]`, `z[i]` straight
-   from that slice; build `rl.Vector3`; `DrawPoint3D`.
+```mermaid
+flowchart LR
+    A["fetch frame bytes → [dynamic]u8<br/>or a slice pinned for the frame"]
+    B["verify the buffer once"]
+    C["ObjectBatch.ra(&buf) → []f64 view"]
+    D["per object in update()/draw()<br/>ra[i] · dec[i] · z[i] → rl.Vector3 → DrawPoint3D"]
+    A --> B --> C --> D
+```
 
 No per-object allocation. The current `Galaxy { position, color }` dynamic array
 in `main.odin` is the data structure you'd replace with *slices into the