From 1d4c0dea4ae6ac3b515c420a803eec18dd4cf3db Mon Sep 17 00:00:00 2001
From: Maxime Lamothe-Brassard <maxime@refractionpoint.com>
Date: Mon, 25 May 2026 08:05:43 -0700
Subject: [PATCH] cli: clarify event overview/timeline/list --ai-help to
 prevent unreachable polling predicates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A real AI session burned its full 5-minute foreground-Bash timeout polling
"event overview" with `grep -q event_type` — a predicate unreachable by
construction because overview returns only millisecond-epoch timestamp
buckets, no event content. The previous --ai-help said overview gave a
"high-level summary of event activity" without showing the output shape,
which an AI can reasonably read as "richer than just timestamps".

This commit extends the three relevant explain blocks so any AI reading
--ai-help cold can pick the right tool the first time:

- event overview: shows the actual output shape (flat list of ms epochs),
  what empty looks like (`[]`), what overview is good for, and an explicit
  "do not use this for sampling content or for predicates keyed on
  in-payload fields — those are unreachable, you will spin until timeout."

- event timeline: alias, points at event overview's expanded text.

- event list: notes the empty result is the literal `[]` and that
  structural empty-vs-non-empty against `[]` is the reliable presence
  predicate — not greping for in-payload strings.

No behavior change; --ai-help text only.
---
 limacharlie/commands/event.py | 38 ++++++++++++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 5 deletions(-)

diff --git a/limacharlie/commands/event.py b/limacharlie/commands/event.py
index 4fd88dcb..dfdad90a 100644
--- a/limacharlie/commands/event.py
+++ b/limacharlie/commands/event.py
@@ -79,6 +79,12 @@ def group() -> None:
   routing:  oid, sid, event_type, event_time (ms), hostname, ext_ip, int_ip, tags
   event:    fields vary by event_type (e.g. FILE_PATH, COMMAND_LINE, DOMAIN_NAME)
 
+Empty result: the command returns "[]" (literal empty list).  Use
+that as the empty-check when polling for "did anything arrive yet?".
+Do NOT poll by greping for in-payload strings like "event_type" —
+the structural empty-vs-non-empty test against "[]" is the reliable
+signal.
+
 Events are linked by atom hashes: routing/this identifies the event,
 routing/parent links to the parent process.  Use 'event get' and
 'event children' to navigate the event tree.
@@ -178,9 +184,29 @@ def children(ctx: click.Context, sid: str, atom: str) -> None:
 # ---------------------------------------------------------------------------
 
 _EXPLAIN_OVERVIEW = """\
-Get an event overview (timeline) for a sensor.  The overview provides
-a high-level summary of event activity within a time range, showing
-when events occurred without returning full event data.
+Get an event overview (timeline) for a sensor.  The overview shows
+WHEN events occurred — NOT what they were.  No event_type, no
+payload, no fields.
+
+Output shape (--output yaml / json):
+  populated:  a flat list of millisecond-epoch timestamps, one per
+              bucketed event, e.g.
+                - 1779720718401
+                - 1779720598401
+                - 1779720478399
+  empty:      [] (literal empty list)
+
+Use this for:
+  - "did any events arrive in this window?" (non-empty test).
+  - rough activity heatmap / silence detection on a sensor.
+
+Do NOT use this for:
+  - sampling an event to inspect its content — overview NEVER returns
+    fields.  Use 'event list --limit N' instead.
+  - polling whose predicate keys on in-payload content (event_type,
+    methodName, serviceName, etc.) — overview's output is just
+    timestamps; such a predicate is unreachable against this command
+    and will spin until your timeout.
 
 You must provide --sid (sensor ID) and a time range via --start and
 --end (unix epoch seconds).
@@ -210,8 +236,10 @@ def overview(ctx: click.Context, sid: str, start: int, end: int) -> None:
 # ---------------------------------------------------------------------------
 
 _EXPLAIN_TIMELINE = """\
-Alias for 'event overview'.  Get an event timeline for a sensor showing
-when events occurred within a time range.
+Alias for 'event overview'.  Returns a flat list of millisecond-epoch
+timestamps showing WHEN events occurred — no event content.  See
+'event overview --ai-help' for output shape and the "use 'event list'
+to sample content" caveat.
 
 Example:
   limacharlie event timeline --sid <SID> --start 1700000000 --end 1700086400