From c3e2ff4b4b740177b65194762d9d67a067724ebc Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Fri, 18 Jul 2025 23:06:07 -0400
Subject: [PATCH] docs: document GUI event subscriptions

---
 .../01-getting-started/06-gui_adapter.md      | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/docs/content/01-getting-started/06-gui_adapter.md b/docs/docs/content/01-getting-started/06-gui_adapter.md
index 54215c7..779fec4 100644
--- a/docs/docs/content/01-getting-started/06-gui_adapter.md
+++ b/docs/docs/content/01-getting-started/06-gui_adapter.md
@@ -116,3 +116,24 @@ events are published on the internal pubsub bus.
 When a ``vault_locked`` event is emitted, the GUI automatically returns to the
 lock screen so the session can be reopened with the master password.
 
+
+## Event Handling
+
+The GUI subscribes to a few core events so the interface reacts automatically when the vault changes state. When `MainWindow` is created it registers callbacks for `sync_started`, `sync_finished` and `vault_locked` on the global pubsub `bus`:
+
+```python
+bus.subscribe("sync_started", self.sync_started)
+bus.subscribe("sync_finished", self.sync_finished)
+bus.subscribe("vault_locked", self.vault_locked)
+```
+
+Each handler updates the status bar or returns to the lock screen. The `cleanup` method removes these hooks when the window closes:
+
+```python
+def cleanup(self, *args: object, **kwargs: object) -> None:
+    bus.unsubscribe("sync_started", self.sync_started)
+    bus.unsubscribe("sync_finished", self.sync_finished)
+    bus.unsubscribe("vault_locked", self.vault_locked)
+```
+
+The [TOTP window](../../02-api_reference.md#totp) demonstrates how such events keep the UI fresh: it shows live two-factor codes that reflect the latest vault data after synchronization.