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/05-streaming-protocols.md

@@ -24,14 +24,17 @@ offers two built-in mechanisms plus the community pattern:
 
 ### Option 1: Size-prefixed FlatBuffers (built-in)
 
+```mermaid
+flowchart LR
+    A["u32 LE<br/>total buffer len<br/><i>size prefix</i>"]
+    B["u32 LE<br/>root table offset"]
+    C["file identifier<br/>(4 bytes)"]
+    D["tables · vtables · data"]
+    A --> B --> C --> D
+```
+
 ```rust
 builder.finish_size_prefixed(root, Some("DESI"));
-// +---------------------------+
-// | u32 LE: total buffer len  |  <-- size prefix
-// | u32 LE: root table offset |
-// | file identifier (4 bytes) |
-// | ... data ...              |
-// +---------------------------+
 ```
 
 Reader side:
@@ -53,8 +56,12 @@ message kinds).
 
 ### Option 2: Custom length-prefix framing (like `flatstream`)
 
-```
-[ u32 LE: message_len ] [ optional checksum (e.g. u32 crc/xxhash) ] [ flatbuffer payload ]
+```mermaid
+flowchart LR
+    A["u32 LE<br/>message_len"]
+    B["optional checksum<br/>(u32 crc / xxhash)"]
+    C["FlatBuffer payload"]
+    A --> B --> C
 ```
 
 - `flatstream-rs` (see `03-rust-integration.md`) is a reference implementation
@@ -260,6 +267,16 @@ FlatBuffers long-term (mmap-friendly, page-in-what-you-touch).
 
 ## Decision summary for this repo
 
+```mermaid
+flowchart TD
+    A["HTTP GET → one FlatBuffer body per batch<br/>validate Rust builder + Odin reader"]
+    B["WebSocket → one Binary message per batch<br/>interactive path · no custom framing"]
+    C["Self-identifying messages<br/>file_identifier &#34;DESI&#34;"]
+    D["size-prefixed / flatstream-style framing<br/>or HTTP-range + mmap for static catalogs"]
+    A --> B --> C
+    C -. "later, if needed" .-> D
+```
+
 1. Start with **HTTP GET → one FlatBuffer body per batch** to validate the Rust
    builder + Odin reader (no protocol work at all).
 2. Then add **WebSocket** with one `Binary` message per batch (no custom framing)