docs: clarify Path 1 vs Path 2 notification capabilities across all docs

Path 1 now supports direct FCM push notifications (ZM 1.39.2+), but the
docs still described it as "detection only" with "no notifications" in
multiple places. This updates all references to accurately reflect both
paths: feature table, principles, install guides, hooks, and FAQ.

Also adds push testing instructions to install_path1 Step 5 so users
can find them when following the Path 1 setup flow.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pliablepixels

docs/guides/_feature_table.rst

@@ -21,7 +21,7 @@
      - |yes|
      - |yes|
    * - Push notifications (iOS/Android via FCM)
-     - |no|
+     - |opt| :sup:`1`
      - |yes|
    * - WebSocket notifications
      - |no|
@@ -43,4 +43,9 @@
      - |yes|
 
 .. |yes| unicode:: U+2714 .. heavy checkmark
+.. |opt| unicode:: U+2714 .. heavy checkmark
 .. |no| unicode:: U+2014 .. em dash
+
+:sup:`1` Path 1 push requires ZM 1.39.2+ and ``push.enabled: "yes"`` in ``objectconfig.yml``.
+Devices register tokens via the ZM Notifications REST API (not ``tokens.txt``).
+See :ref:`push_config` for setup.

docs/guides/hooks.rst

@@ -4,7 +4,7 @@ Machine Learning Hooks
 .. note::
 
         This page covers the ML detection pipeline, which is required for **both**
-        Path 1 (detection only) and Path 2 (full ES).
+        Path 1 (detection + optional push) and Path 2 (full ES).
         For installation instructions, see :doc:`installation`.
         The hooks use `pyzm <https://pyzmv2.readthedocs.io/en/latest/>`__ v2
         for detection. Make sure you have ``pyzm`` installed before proceeding.
@@ -48,10 +48,10 @@ connects to ZoneMinder, downloads event frames, runs the ML detection pipeline
 
 .. _path1_setup:
 
-Path 1: Detection only (no ES)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Path 1: Detection + optional push (no ES)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Requires ZM 1.37+.** ZoneMinder can call ``zm_detect.py`` directly via its
+**Requires ZM 1.38.1+.** ZoneMinder can call ``zm_detect.py`` directly via its
 Event Start Command feature — no Event Server needed.
 
 Configure per monitor in ZM: go to the monitor's **Config -> Recording** tab and set:

docs/guides/hooks_faq.rst

@@ -4,9 +4,11 @@ Machine Learning Hooks FAQ
 How do the hooks actually invoke object detection?
 -----------------------------------------------------
 
-* When the Event Notification Server detects an event, it invokes the script specified in ``event_start_hook`` in your ``zmeventnotification.yml``. This is typically ``/var/lib/zmeventnotification/bin/zm_event_start.sh``
+There are two paths:
 
-* ``zm_event_start.sh`` in turn invokes ``zm_detect.py`` that does the actual machine learning. Upon exit, it returns ``0`` (success) meaning an object was found, or ``1`` (failure) meaning nothing was detected. Based on how you have configured your settings, this information is then stored in ZM and/or pushed to your mobile device as a notification.
+**Path 1 (no ES):** ZoneMinder calls ``zm_detect.py`` directly via ``EventStartCommand``. The script runs ML detection and writes results back to the event. If ``push.enabled`` is ``yes`` in ``objectconfig.yml`` (requires ZM 1.39.2+), it also sends FCM push notifications directly to registered devices.
+
+**Path 2 (full ES):** The Event Notification Server detects an event and invokes the script specified in ``event_start_hook`` in ``zmeventnotification.yml`` (typically ``/var/lib/zmeventnotification/bin/zm_event_start.sh``). That script in turn invokes ``zm_detect.py`` for the actual machine learning. Upon exit, it returns ``0`` (success) meaning an object was found, or ``1`` (failure) meaning nothing was detected. The ES then decides whether to send notifications based on your channel configuration.
 
 
 Necessary Reading - Sample Config Files

docs/guides/install_path1.rst

@@ -1,12 +1,15 @@
-Path 1: Detection Only (no ES)
-==============================
+Path 1: Detection + Optional Push (no ES)
+==========================================
 
 Use ZoneMinder's ``EventStartCommand`` to run ML detection directly — no Event Server needed.
 Requires **ZM 1.38.1 or above**.
 
-Push notifications are supported directly via ``zm_detect`` (see the ``push`` section
-in ``objectconfig.yml`` and :ref:`push_config`). If you also want WebSockets or MQTT,
-see :doc:`install_path2`.
+**Push notifications** are supported directly from ``zm_detect`` — no ES required.
+Configure the ``push`` section in ``objectconfig.yml`` (see :ref:`push_config`).
+Requires **ZM 1.39.2+** (which adds the Notifications REST API for token storage).
+
+If you also want WebSocket notifications, MQTT, notification rules/muting, or the
+ES control interface, see :doc:`install_path2`.
 
 .. important::
 
@@ -180,6 +183,25 @@ Then test detection (``--config`` defaults to ``/etc/zm/objectconfig.yml``):
    sudo -u www-data /var/lib/zmeventnotification/bin/zm_detect.py \
        --file /tmp/bird.jpg --debug
 
+**Testing push notifications (Path 1 direct push):**
+
+If you have ``push.enabled: "yes"`` in ``objectconfig.yml`` and devices have registered
+tokens via the ZM Notifications API, you can test push delivery from the command line.
+Use ``--file`` with ``--eventid`` and ``--monitorid`` to trigger push without a live event.
+The ``--fakeit`` flag overrides detection results so you don't need an image that actually
+matches your detection pattern:
+
+.. code:: bash
+
+   sudo -u www-data /var/lib/zmeventnotification/bin/zm_detect.py \
+       --file /path/to/any/image.jpg --eventid <eid> --monitorid <mid> \
+       --debug --fakeit "person"
+
+Replace ``<eid>`` with a real event ID (so the notification links to a viewable event)
+and ``<mid>`` with the monitor ID. Registered devices should receive a push notification
+within a few seconds. Check the debug output for ``push:`` log lines to verify delivery.
+See :ref:`push_config` for push configuration details.
+
 Optional: Face recognition
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/guides/installation.rst

@@ -3,11 +3,12 @@ Installation
 
 There are two ways to use ML-powered object detection with ZoneMinder:
 
-.. topic:: Path 1: Detection only (no ES)
+.. topic:: Path 1: Detection + optional push (no ES)
 
    Wire ``zm_detect.py`` directly to ZoneMinder using ``EventStartCommand``
    (requires ZM 1.38.1+). ZM calls the detection script automatically when
-   an event starts. No daemon needed — simpler to set up.
+   an event starts. No daemon needed — simpler to set up. Can optionally
+   send FCM push notifications directly (requires ZM 1.39.2+).
    See :doc:`install_path1` for setup instructions.
 
 .. topic:: Path 2: Full Event Server
@@ -19,8 +20,10 @@ There are two ways to use ML-powered object detection with ZoneMinder:
 
 .. include:: _feature_table.rst
 
-If you only need detection results written to your ZM events, Path 1 is simpler to set up.
-If you need real-time notifications on your phone or other clients, you need Path 2.
+If you only need detection results written to your ZM events (with optional push
+notifications), Path 1 is simpler to set up.
+If you need WebSocket notifications, MQTT, notification rules, or the ES control
+interface, you need Path 2.
 
 .. toctree::
 

docs/guides/principles.rst

@@ -5,13 +5,13 @@ Summary
 +++++++++
 This guide explains the detection and notification flow for ZoneMinder's ML ecosystem. There are two paths:
 
-* **Path 1 (Detection + optional push)** — ZoneMinder calls ``zm_detect.py`` directly via ``EventStartCommand``. No daemon needed. Optionally sends FCM push notifications directly (requires ZM 1.39.2+).
-* **Path 2 (Full Event Server)** — The Event Notification Server (ES) monitors shared memory for new events, invokes ML hooks, and sends notifications via FCM push, WebSockets, MQTT, and 3rd-party APIs.
+* **Path 1 (Detection + optional push)** — ZoneMinder calls ``zm_detect.py`` directly via ``EventStartCommand``. No daemon needed. Optionally sends FCM push notifications directly to registered devices (requires ZM 1.39.2+). See :ref:`push_config` for push setup.
+* **Path 2 (Full Event Server)** — The Event Notification Server (ES) monitors shared memory for new events, invokes ML hooks, and sends notifications via FCM push, WebSockets, MQTT, and 3rd-party APIs. Also provides notification rules, per-device monitor filtering, and a dynamic control interface.
 
-Both paths use the same ML pipeline (``zm_detect.py`` + ``objectconfig.yml``). The difference is what triggers detection and what happens with the results.
+Both paths use the same ML pipeline (``zm_detect.py`` + ``objectconfig.yml``). The difference is what triggers detection and what notification channels are available.
 
-Path 1: From Event to Detection
-+++++++++++++++++++++++++++++++++
+Path 1: From Event to Detection (+ Optional Push)
++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. note::
 
@@ -47,7 +47,19 @@ When detection finishes, ``zm_detect.py`` produces the following:
 * **Detection metadata** — An ``objects.json`` file with labels, boxes, confidences, and frame info is saved alongside the image.
 * **Event tags** — When ``tag_detected_objects: yes`` (requires ZM >= 1.37.44), detected labels are tagged in ZoneMinder.
 
-That is the complete Path 1 flow. There is no daemon running, no shared memory polling, and no notifications — ZoneMinder calls the script, the script runs detection, and results are written back to the event.
+That is the core Path 1 detection flow. There is no daemon running and no shared memory polling — ZoneMinder calls the script, the script runs detection, and results are written back to the event.
+
+4: Optional — Direct Push Notifications
+-----------------------------------------
+Starting with ZM 1.39.2+, ``zm_detect.py`` can also send **FCM push notifications directly** to registered mobile devices — no Event Server needed. This is configured via the ``push`` section in ``objectconfig.yml`` (see :ref:`push_config`).
+
+When ``push.enabled`` is set to ``yes``, after detection completes ``zm_detect`` reads registered device tokens from ZoneMinder's ``Notifications`` database table (devices register via the ZM REST API) and sends push notifications through an FCM cloud function proxy. It respects per-token monitor filtering, throttle intervals, and push state, and automatically cleans up invalid tokens.
+
+**What Path 1 push gives you:** FCM push notifications to registered iOS/Android devices after detection, with optional event images.
+
+**What Path 1 push does NOT give you:** WebSocket notifications, MQTT, notification rules/time-based muting, the ``tokens.txt`` per-device control file, or the ES control interface. For those, you need :ref:`Path 2 <from-detection-to-notification>`.
+
+See :ref:`push_config` in the configuration guide and the "Testing push notifications" section in :doc:`hooks` for how to test.
 
 .. _from-detection-to-notification:
 
@@ -56,7 +68,7 @@ Path 2: From Event Detection to Notification
 
 .. note::
 
-   This section covers the full Event Notification Server (ES) flow. If you are using Path 1 (detection only via ``EventStartCommand``), you can skip this section.
+   This section covers the full Event Notification Server (ES) flow. If you are using Path 1 (detection + optional push via ``EventStartCommand``), you can skip this section.
 
 1: How it starts
 ----------------------

docs/index.rst

@@ -60,11 +60,12 @@ Choose your setup
 
 There are two ways to use ML-powered object detection with ZoneMinder:
 
-.. topic:: Path 1: Detection only (no ES)
+.. topic:: Path 1: Detection + optional push (no ES)
 
    Wire ``zm_detect.py`` directly to ZoneMinder using ``EventStartCommand``
    (requires ZM 1.38.1+). ZM calls the detection script automatically when
-   an event starts. No daemon needed — simpler to set up.
+   an event starts. No daemon needed — simpler to set up. Can optionally
+   send FCM push notifications directly (requires ZM 1.39.2+).
    See :doc:`guides/install_path1` for setup instructions.
 
 .. topic:: Path 2: Full Event Server
@@ -76,8 +77,10 @@ There are two ways to use ML-powered object detection with ZoneMinder:
 
 .. include:: guides/_feature_table.rst
 
-If you only need detection results written to your ZM events, Path 1 is simpler to set up.
-If you need real-time notifications on your phone or other clients, you need Path 2.
+If you only need detection results written to your ZM events (with optional push
+notifications), Path 1 is simpler to set up.
+If you need WebSocket notifications, MQTT, notification rules, or the ES control
+interface, you need Path 2.
 
 See the :doc:`guides/installation` page for step-by-step setup instructions for either path.