diff --git a/z21.md b/z21.md
index 5360ca9..25d2490 100644
--- a/z21.md
+++ b/z21.md
@@ -71,3 +71,27 @@ This document lists practical Z21 control items and their expected actions when
 - Make power and mode commands idempotent and return current state after execution.
 - For `switch_mode`, return explicit capability errors when unsupported, for example: `ERR_UNSUPPORTED_MODE_SWITCH`.
 - Keep internal model protocol-neutral (`ThrottleCommand`, `FunctionCommand`, `PowerStateEvent`) to simplify interoperability with XpressNet/LocoNet backends.
+
+## Sequence Diagram (Kroki / seqdiag)
+
+Example: drive locomotive `id=10` to speed `100` in `forward` direction.
+
+```seqdiag
+seqdiag {
+  browser  [label = "Web Client"];
+  wsapi    [label = "WS API"];
+  z21gw    [label = "Z21 Gateway"];
+  station  [label = "Z21 Command Station"];
+
+  browser -> wsapi [label = "WS send\n{type:z21.loco.drive, seq:301,\npayload:{address:10, speedStep:100, direction:forward}}"];
+  wsapi -> z21gw [label = "validate + map command"];
+  z21gw -> station [label = "Z21 LAN: set loco 10 speed=100 dir=FWD"];
+  station -> z21gw [label = "status/ack"];
+  z21gw -> wsapi [label = "mapped result"];
+  wsapi -> browser [label = "ACK\n{type:ack, seq:301, ok:true,\nresult:{address:10, speedStep:100, direction:forward}}"];
+
+  station -> z21gw [label = "async state broadcast (optional)"];
+  z21gw -> wsapi [label = "event.track/loco update"];
+  wsapi -> browser [label = "event.loco.state\n{address:10, speedStep:100, direction:forward}"];
+}
+```