From 036469ed21a51567d717f6df1cad5a218ed0440b Mon Sep 17 00:00:00 2001
From: Luna <anassaeneroi@pm.me>
Date: Fri, 3 Jul 2026 07:40:06 -0700
Subject: [PATCH] Document the desktop tray applet and check --json

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                 | 15 +++++++++++++++
 docs/COMMAND_REFERENCE.md | 18 +++++++++++++++++-
 docs/OPERATIONS.md        |  6 ++++++
 docs/PACKAGING.md         | 11 +++++++++++
 4 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3c20457..5d332e2 100644
--- a/README.md
+++ b/README.md
@@ -214,6 +214,21 @@ python3 -m enodia_sentinel.cli check        # run every detector once, print fin
 No pip, no virtualenv, no dependencies — it's stdlib-only and installs as a
 plain package directory plus a launcher wrapper.
 
+### Desktop tray (optional)
+
+A lightweight system-tray applet is available for desktop installs. It is an
+optional frontend — the daemon and core agent remain stdlib-only. Install the
+extra and launch it:
+
+    pip install 'enodia-sentinel[tray]'
+    enodia-sentinel-tray
+
+The tray menu opens the local dashboard, starts/stops/restarts the daemon via
+systemd, shows daemon status and alert count at a glance, and runs an on-demand
+quick check (results shown as a desktop notification). Copy
+`packaging/enodia-sentinel-tray.desktop` into `~/.config/autostart/` to launch
+it on login.
+
 ## The red-team harness
 
 `sentinel-redteam` is the demo and the integration test in one. It simulates
diff --git a/docs/COMMAND_REFERENCE.md b/docs/COMMAND_REFERENCE.md
index 3e873a6..8362ca0 100644
--- a/docs/COMMAND_REFERENCE.md
+++ b/docs/COMMAND_REFERENCE.md
@@ -35,11 +35,13 @@ Expected use: systemd, not an interactive shell.
 
 ```bash
 enodia-sentinel check
+enodia-sentinel check --json
 ```
 
 Runs the enabled detector set once and prints alerts. This forces the SUID scan
 and arms baseline-gated detectors immediately, so it is useful for health checks
-and debugging.
+and debugging. `--json` emits the alerts as a JSON array of alert dicts
+(severity-ordered) instead of text, for scripts and the tray applet.
 
 Exit code:
 
@@ -381,6 +383,20 @@ text/status contrast pairs are covered by the web test suite.
 
 Expected use: `enodia-sentinel-web.service`.
 
+### `enodia-sentinel-tray`
+
+```bash
+enodia-sentinel-tray
+```
+
+Launches the optional desktop system-tray applet (no subcommands). It is a GUI
+frontend over the commands above: the menu opens the dashboard (starting
+`enodia-sentinel-web.service` if needed), starts/stops/restarts
+`enodia-sentinel.service` via `systemctl`, shows daemon status and alert counts
+from `status --json`, and runs `check --json` on demand with the result shown
+as a desktop notification. Requires the `[tray]` extra (`pystray`, `Pillow`);
+the core agent stays dependency-free without it.
+
 ### `triage`
 
 ```bash
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
index 2f290ec..7bcd310 100644
--- a/docs/OPERATIONS.md
+++ b/docs/OPERATIONS.md
@@ -77,6 +77,12 @@ The HTTPS dashboard shows the same posture findings under the Posture tab and
 summarizes FIM/package anchors plus heartbeat freshness under the Integrity tab
 for quick remote review.
 
+On desktop hosts the optional tray applet (`enodia-sentinel-tray`, `[tray]`
+extra) wraps the same workflow: it drives the same `systemctl` units operators
+use directly, so daemon start/stop/restart prompts for polkit authorization as
+usual. The applet is purely a convenience frontend — it is not required for the
+daemon to run and adds nothing to the core agent.
+
 ## Alert Workflow
 
 When Sentinel fires:
diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md
index 52eebb5..44f094d 100644
--- a/docs/PACKAGING.md
+++ b/docs/PACKAGING.md
@@ -103,6 +103,17 @@ Notes:
 - Validate package verification behavior on the target distro before enabling
   signed-package mismatch alerting.
 
+## Desktop Tray Applet (optional)
+
+The `[tray]` optional extra (`pip install 'enodia-sentinel[tray]'`) pulls in
+`pystray` and `Pillow` and provides the `enodia-sentinel-tray` console script.
+The extra is never required by the daemon; core runtime dependencies stay
+empty.
+
+`packaging/enodia-sentinel-tray.desktop` is an opt-in autostart entry. It is
+not installed to a system autostart path by default — desktop users copy it to
+`~/.config/autostart/` themselves.
+
 ## Package Hardening Checklist
 
 - Package version matches `pyproject.toml` and `enodia_sentinel.__version__`.