included cloud logging with filters

README.md

@@ -15,13 +15,39 @@ Check any MAC address directly through the Zyxel client with:
 python lib/_zyxel.py --mac AA:BB:CC:DD:EE:FF
 ```
 
-Omit `--mac` to check `arrival_detection.device.mac` from `service.yaml`.
+Omit `--mac` to check the first entry in `arrival_detection.devices` from
+`service.yaml`. Arrival detection supports one to three devices and tracks each
+device independently.
+
+Set `arrival_detection.zyxel.debug` to `true` to log every Zyxel HTTP/DAL call
+and MAC presence result. Under systemd, view these messages with
+`journalctl -u home-control.service -f`.
 
 An arrival is logged after the phone was confirmed absent and then present. It
-also calls `send_notification()` from `notify.py`; its message, ntfy topic, and
-timeout are configured under `arrival_detection.notification`. Set
+also calls `send_notification()` from `lib/_notify.py`; its message, ntfy topic,
+and timeout are configured under the top-level `notify` section. Set
 `arrival_detection.enabled` to `false` to disable this function.
 
+Plugins emit dictionaries containing `sender`, `event`, `id`, and `text`. The
+controller routes each sender to one or more actions through `controller.plugins`.
+For example, `_arrival_detection` emits an `arrived` event and can be routed to
+both actions through `on_event: [_notify, _cloud_logger]`. A single action name
+such as `on_event: _notify` remains supported.
+
+Arrival detection emits `arrived` and `departed` for individual device IDs. It
+also emits `empty` with ID `house` after the last present device departs. Initial
+startup state never generates these transition events.
+
+Plugin modules, factories, configuration sections, and event actions are all
+declared under `controller`. The controller contains no plugin-specific imports
+or startup logic. A plugin module exposes a configured factory (normally
+`create`), and an action module exposes a configured handler (normally
+`on_event`).
+
+The `_notify` action can filter by event or ID under `notify.filter`. Empty
+`accept` lists allow all values; populated lists act as allow-lists. Values in
+`ignore` are always rejected, even when also accepted.
+
 On the iPhone, open **Settings > Wi-Fi**, tap the info button beside the home
 network, and copy **Wi-Fi Address**. If Private Wi-Fi Address is enabled, that
 per-network address is the correct one to configure.
@@ -50,4 +76,4 @@ sudo journalctl -u home-control.service -f
 
 Confirmed arrival notifications are also appended to
 `/log/detect-arrivals.txt`. The path is configurable as
-`arrival_detection.notification.event_log`.
+`arrival_detection.event_log`.