diff --git a/app/vpn/tunnelmanager.h b/app/vpn/tunnelmanager.h
index 53b12c1..8990393 100644
--- a/app/vpn/tunnelmanager.h
+++ b/app/vpn/tunnelmanager.h
@@ -1,9 +1,13 @@
 // tunnelmanager.h — Platform-agnostic interface for the WireGuard tunnel.
 //
 // Platform implementations:
-//   tunnelmanager_mac.mm   — macOS (utun + boringtun, no root required for TUN open)
-//   tunnelmanager_linux.cpp — Linux (kernel WireGuard via wgctrl, future)
-//   tunnelmanager_win.cpp  — Windows (Wintun + boringtun, future)
+//   tunnelmanager_mac.mm    — macOS   (utun + boringtun, no root for TUN open)
+//   tunnelmanager_linux.cpp — Linux   (/dev/net/tun + boringtun userspace,
+//                                       requires CAP_NET_ADMIN or root)
+//   tunnelmanager_win.cpp   — Windows (Wintun + boringtun, requires Admin)
+//
+// The QML layer talks to TunnelManager indirectly via DragonRelayBackend.
+// All signals are emitted on the QObject's thread (the Qt main thread).
 
 #pragma once
 
@@ -25,14 +29,12 @@ public:
     /// Bring up the WireGuard tunnel described by cfg.
     ///
     /// This call returns quickly; the tunnel comes up asynchronously.
-    /// Listen to connected() / error() for status.  The first thing that
-    /// happens is a handshake initiation — if the server is reachable the
-    /// connected() signal fires within ~500 ms.
+    /// Listen for tunnelUp() / tunnelError() to observe the result.
     ///
-    /// Calling start() while already running silently stops the previous tunnel
-    /// first (equivalent to stop() then start()).
+    /// Calling start() while already running silently stops the previous
+    /// tunnel first (equivalent to stop() then start()).
     ///
-    /// @return false immediately if cfg.isValid() == false (error() is also emitted).
+    /// Returns false immediately and emits tunnelError() if cfg.isValid() is false.
     bool start(const WireGuardConfig &cfg);
 
     /// Tear down the tunnel synchronously.  Safe to call when not running.
@@ -41,18 +43,23 @@ public:
     // ── State ──────────────────────────────────────────────────────────────
 
     bool    isRunning()    const { return m_running; }
-    QString errorString()  const { return m_error; }
+    QString errorString()  const { return m_error;   }
 
     /// The bare WireGuard IP assigned to this peer, e.g. "10.99.0.2".
     /// Empty string when not connected.
     QString localAddress() const { return m_localAddr; }
 
 signals:
-    /// Emitted after the first successful handshake with the server.
-    void connected();
+    /// Emitted once the tunnel is ready to carry traffic.
+    /// The argument is the local WireGuard IP (e.g. "10.99.0.2").
+    ///
+    /// On macOS this fires after a short post-handshake delay; on Linux and
+    /// Windows it fires once the kernel TUN/Wintun adapter is configured and
+    /// boringtun reports a successful handshake.
+    void tunnelUp(const QString &localIP);
 
     /// Emitted when the tunnel is fully torn down.
-    void disconnected();
+    void tunnelDown();
 
     /// Emitted on any non-recoverable error.  The tunnel is stopped.
     void tunnelError(const QString &message);