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/02-flatbuffers-overview.md

@@ -105,19 +105,28 @@ These are the "thou shalt" rules for keeping buffers compatible:
 
 ## Reading a buffer (conceptual)
 
+Buffer layout:
+
+```mermaid
+flowchart LR
+    subgraph BUF["bytes: &[u8]"]
+        O["uoffset<br/>root table offset"]
+        FI["file_identifier<br/>(optional)"]
+        D["tables · vtables · data"]
+    end
+    O --> FI --> D
 ```
-bytes: &[u8]
 
-  ┌─────────────────────────────┐
-  │ uoffset (root table offset)  │
-  │ file_identifier (optional)   │
-  │ ... tables, vtables, data ...│
-  └─────────────────────────────┘
+Access sequence — each field is a few offset dereferences and a read:
 
-root = follow(bytes)              // jump to root table via uoffset
-vtable = root - root.vtable_off  // locate vtable for this table
-field_ra  = vtable.slot_ra != 0  // present?
-if present: ra = read_f64(bytes, root + slot_ra)
+```mermaid
+flowchart TD
+    R["root = follow(bytes)<br/>jump to root table via uoffset"]
+    V["vtable = root − root.vtable_off<br/>locate vtable for this table"]
+    Q{"field slot present?"}
+    R --> V --> Q
+    Q -- "no" --> DEF["use schema default"]
+    Q -- "yes" --> RD["ra = read_f64(bytes, root + slot_ra)"]
 ```
 
 There is **no parsing loop**. Each accessor is a few offset dereferences and a