From 7291c3192c23ea8175d422f2572a62c888313052 Mon Sep 17 00:00:00 2001
From: astronaut808 <38975427+astronaut808@users.noreply.github.com>
Date: Sat, 18 Jul 2026 21:25:40 +0500
Subject: [PATCH] docs handshake failure stage diagnostics

---
 docs/Architecture/API/API.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/Architecture/API/API.md b/docs/Architecture/API/API.md
index 78b34e8..9685b29 100644
--- a/docs/Architecture/API/API.md
+++ b/docs/Architecture/API/API.md
@@ -350,6 +350,32 @@ Returned by `PATCH /v1/config` on success (`200`, or `202` when a reload was acc
 | `stage` | `string` | State-machine stage label. |
 | `total` | `u64` | Counter value for this stage. |
 
+#### Handshake failure stage diagnostics
+
+`handshake_failures_by_class` and `telemt_handshake_failures_by_class_total` describe the error kind. `handshake_failures_by_stage` and `telemt_handshake_failures_by_stage_total` describe where the same failure happened in the handshake state machine.
+
+This does not add a DPI verdict or any protocol decision. The stage is derived from the existing Telemt handshake control flow and is counted only when the existing handshake failure or timeout accounting path is reached.
+
+Fixed stage labels:
+
+| Stage | Meaning |
+| --- | --- |
+| `first_packet_prelude` | Reading the first 5 bytes before selecting the TLS or direct branch. |
+| `tls_clienthello_body` | Reading the TLS ClientHello body after the TLS record header. |
+| `tls_core` | Running the TLS-F handshake/auth flow. |
+| `tls_post_serverhello_mtproto` | Waiting for the 64-byte MTProto handshake after TLS ServerHello. |
+| `direct_mtproto` | Reading the direct classic/secure 64-byte MTProto handshake. |
+
+Example:
+
+```text
+telemt_handshake_failures_by_class_total{class="expected_64_got_0_unexpected_eof"} 3
+telemt_handshake_failures_by_stage_total{stage="direct_mtproto"} 1
+telemt_handshake_failures_by_stage_total{stage="tls_post_serverhello_mtproto"} 2
+```
+
+This means the same EOF-while-reading-64-bytes failure happened once in the direct MTProto path and twice after TLS ServerHello.
+
 ### `SystemInfoData`
 | Field | Type | Description |
 | --- | --- | --- |