docs: add zma event re-analysis utility documentation

Add dedicated documentation page for the zma binary covering synopsis,
all command-line options, operating modes (update-existing vs create-events),
save-analysis functionality, and usage examples. Add zma entry to the
components page and user guide toctree.

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

docs/userguide/components.rst

@@ -20,7 +20,10 @@ Binaries
   This is the ZoneMinder Streaming server. The web interface connects with this to get real-time or historical streamed images. It runs only when a live monitor stream or event stream is actually being viewed and dies when the event finishes or the associate web page is closed. If you find you have several zms processes running when nothing is being viewed then it is likely you need a patch for apache (see the Troubleshooting section). A non-parsed header version of zms, called nph-zms, is also installed and may be used instead depending on your web server configuration.
 
 **zmu**
-  This is the ZoneMinder Utility. It's basically a handy command line interface to several useful functions. It’s not really meant to be used by anyone except the web page (there's only limited 'help' in it so far) but can be if necessary, especially for debugging video problems.
+  This is the ZoneMinder Utility. It’s basically a handy command line interface to several useful functions. It’s not really meant to be used by anyone except the web page (there’s only limited ‘help’ in it so far) but can be if necessary, especially for debugging video problems.
+
+**zma**
+  This is the ZoneMinder Event Re-Analysis utility. It re-analyses a previously recorded event using the current zone settings for a monitor, running the full motion detection pipeline on each frame from the stored video or JPEG files. This allows you to tune zone settings and re-run analysis on existing footage without needing live cameras. See :doc:`zma` for full usage details.
 
 PHP
 ---

docs/userguide/index.rst

@@ -5,6 +5,7 @@ User Guide
 
    introduction
    components
+   zma
    gettingstarted
    definemonitor
    definezone

docs/userguide/zma.rst

@@ -0,0 +1,119 @@
+zma - Event Re-Analysis
+=======================
+
+Description
+-----------
+
+``zma`` re-analyses a previously recorded event using the current zone settings
+for the monitor. It decodes each frame from the event's stored video or JPEG
+files and runs the full motion detection pipeline.
+
+This is useful for tuning zone settings and re-running analysis on existing
+footage without needing live cameras. After adjusting zones in the web
+interface, you can use ``zma`` to see how those changes would affect detection
+on past events.
+
+By default, ``zma`` updates the existing event's motion statistics
+(AlarmFrames, TotScore, AvgScore, MaxScore) in the database. With the
+``--create-events`` option, it instead creates new events from the detected
+motion regions.
+
+Synopsis
+--------
+
+.. code-block:: bash
+
+   zma -e <event_id> [options]
+
+Options
+-------
+
+``-e, --event <event_id>``
+   Event ID to re-analyse. Required.
+
+``-m, --monitor <monitor_id>``
+   Override the monitor ID used for zone configuration. By default, ``zma``
+   uses the monitor that owns the event. Use this option to apply a different
+   monitor's zone settings to the event's footage.
+
+``-c, --create-events``
+   Create new events from detected motion instead of updating the original
+   event's scores. The new events are inserted into the database and linked
+   to the source video files via hard links (falling back to copies if on a
+   different filesystem).
+
+``-a, --save-analysis``
+   Write analysis JPEG images showing zone alarm overlays for each frame
+   that triggered motion. The images are written to the event's directory
+   using the standard analysis file naming convention.
+
+``-v, --verbose``
+   Increase debug verbosity. Can be specified multiple times for higher
+   verbosity levels.
+
+``-h, --help``
+   Display usage information.
+
+``-V, --version``
+   Print the installed version of ZoneMinder.
+
+Modes of Operation
+------------------
+
+Update Existing (default)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When run without ``--create-events``, ``zma`` processes every frame and then
+updates the original event row in the database with the recalculated scores:
+
+- **AlarmFrames** -- number of frames that triggered motion
+- **TotScore** -- sum of all alarm frame scores
+- **AvgScore** -- average score across alarm frames
+- **MaxScore** -- highest single-frame score
+
+This lets you see how zone tuning changes the event's score metrics without
+creating any new data.
+
+Create Events
+^^^^^^^^^^^^^
+
+With ``--create-events``, ``zma`` uses the monitor's alarm state machine
+(including ``AlarmFrameCount`` and ``PostEventCount`` settings) to detect
+alarm regions in the footage and creates new event records in the database for
+each one. The source video files are hard-linked into the new event directories
+so no additional disk space is used (on the same filesystem).
+
+Save Analysis
+^^^^^^^^^^^^^
+
+The ``--save-analysis`` flag can be combined with either mode. When a frame
+triggers motion, ``zma`` writes analysis JPEG images with zone alarm overlays
+into the event directory. These images show which zones were triggered and can
+be viewed in the web interface to visually verify zone configuration.
+
+Examples
+--------
+
+Re-analyse event 12345 and update its scores in the database:
+
+.. code-block:: bash
+
+   zma -e 12345
+
+Re-analyse event 12345 using monitor 2's zone settings:
+
+.. code-block:: bash
+
+   zma -e 12345 -m 2
+
+Create new events from detected motion in event 12345:
+
+.. code-block:: bash
+
+   zma -e 12345 --create-events
+
+Re-analyse with analysis images and verbose output:
+
+.. code-block:: bash
+
+   zma -e 12345 --save-analysis -v