diff --git a/AGENTS.md b/AGENTS.md
index 4970ed1..8b7c9bb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -280,6 +280,40 @@ go run -tags dev ./apps/server-core -create-admin -user admin -pass "..."
 sudo /usr/local/bin/nexusguard-server -create-admin -user admin -pass "..."
 ```
 
+## heartbeat server <-> device-agent
+
+Konsep yang Benar
+Heartbeat = satu konsep, tiga jalur transport:
+
+0	Transport	Protocol	Endpoint	Kapan Dipakai
+1	gRPC via domain (HTTPS proxy)	gRPC bidi stream	api-nexus.datadunia.com:443	Pertama dicoba
+2	gRPC via WG IP (direct)	gRPC bidi stream	10.172.21.1:8080	Fallback jika proxy swallowed
+3	HTTP API	REST POST	/api/v1/heartbeat	Fallback terakhir / always running
+Satu konsep yang sama: kirim config_hash + last_handshake + tunnel_up → server compare → respond dengan config jika berubah.
+
+Yang Perlu Diperbaiki
+client.go: Perlu ada gRPC heartbeat loop (kirim HeartbeatRequest via stream periodik) + handle HeartbeatResponse
+heartbeat.go: HTTP heartbeat tetap ada sebagai fallback
+Transport switching: Saat gRPC connected → heartbeat via gRPC. Saat gRPC disconnected → heartbeat via HTTP
+handler.go: Perlu handleHeartbeatResponse untuk process config dari gRPC heartbeat
+Server manager.go: Perlu sendMu untuk prevent concurrent stream.Send()
+Alur yang Benar (setelah perbaikan)
+Agent Start
+  → Provision (HTTP) → config pertama dari HTTP API → build tunnel
+  → Start HTTP heartbeat (always running, fallback transport)
+  → Start gRPC (HTTPS → WG IP)
+  
+gRPC Connected:
+  → establishStream: kirim HelloMessage → terima ConfigUpdate (verify only, jangan rebuild)
+  → heartbeatLoop: kirim HeartbeatRequest via gRPC setiap 30s
+  → Server respond: HeartbeatResponse (config_changed? → rebuild via handler)
+  → dispatch: handle Suspend/Resume/ConfigUpdate/Reconnect/Disconnect
+
+gRPC Disconnected:
+  → HTTP heartbeat continues (unaffected)
+  → gRPC reconnect loop
+  → When reconnected → switch heartbeat back to gRPC
+  
 ## NOTES
 - Submodules → private Gitea (`git.datadunia.com`); CI via Gitea Actions per submodule
 - Go versions diverge: server-core `1.25.7`, device-agent `1.25.1`