update docs

docs/graphs/cold_warm_timeline.dot

@@ -0,0 +1,55 @@
+digraph cold_warm_timeline {
+    rankdir=LR
+    bgcolor="#0a0e17"
+    fontname="Helvetica"
+    node [fontname="Helvetica" fontsize=11 style=filled color="#1e2a4a" fontcolor="#e8eaf0" shape=box]
+    edge [fontname="Helvetica" fontsize=9 fontcolor="#8892a8" color="#4a5568"]
+
+    label="Cold vs warm — what gets billed, what gets measured"
+    labelloc=t
+    fontsize=16
+    fontcolor="#0066ff"
+
+    subgraph cluster_cold {
+        label="INVOCATION 1 — cold (Init Duration shows in CloudWatch)"
+        style=dashed
+        color="#ff3d00"
+        fontcolor="#ff3d00"
+
+        c_dl [label="Download code\n~50–200 ms\n(NOT billed)" fillcolor="#121829" fontcolor="#8892a8"]
+        c_init [label="Init phase\n~200–800 ms typical\n(boto3/aioboto3 imports,\nclient build)\n(billed at full mem)" fillcolor="#1a1a3a" fontcolor="#ffc107"]
+        c_handler [label="Handler\n~5–500 ms\n(billed)" fillcolor="#0d1a33"]
+        c_freeze [label="freeze" fillcolor="#121829" fontcolor="#8892a8"]
+    }
+
+    subgraph cluster_warm1 {
+        label="INVOCATION 2 — warm (no Init Duration logged)"
+        style=dashed
+        color="#00c853"
+        fontcolor="#00c853"
+
+        w_thaw [label="thaw\nmicroseconds\n(NOT billed)" fillcolor="#121829" fontcolor="#8892a8"]
+        w_handler [label="Handler\n~5–500 ms\n(billed)" fillcolor="#0d1a33" fontcolor="#00c853"]
+        w_freeze [label="freeze" fillcolor="#121829" fontcolor="#8892a8"]
+    }
+
+    subgraph cluster_warm2 {
+        label="INVOCATION 3 — warm"
+        style=dashed
+        color="#00c853"
+        fontcolor="#00c853"
+
+        w2_thaw [label="thaw" fillcolor="#121829" fontcolor="#8892a8"]
+        w2_handler [label="Handler\n(billed)" fillcolor="#0d1a33" fontcolor="#00c853"]
+    }
+
+    notes [label="Init Duration is ONLY in cold-start logs.\nDuration is the handler portion only.\nBilled Duration rounds Duration up to 1 ms.\nWith Provisioned Concurrency, init runs ahead of time —\nyou pay for it in PC pricing, not per invocation." fillcolor="#0a0e17" color="#1e2a4a" shape=note fontcolor="#b4bccf" fontsize=10]
+
+    c_dl -> c_init -> c_handler -> c_freeze
+    c_freeze -> w_thaw [label="next event\n(< idle window)" color="#00c853"]
+    w_thaw -> w_handler -> w_freeze
+    w_freeze -> w2_thaw [color="#00c853"]
+    w2_thaw -> w2_handler
+
+    {rank=sink; notes}
+}