@moda-ai/cli 1.55.42 → 1.55.43

package/skills/moda-cli/references/commands.md

@@ -15,7 +15,7 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `moda auth status` | Both credentials; exit `0` if either is usable, `4` if neither (expected, not an error) |
 | `moda auth token` | Print the raw bearer token for `$(moda auth token)` composition |
 | `moda traces search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
-| `moda overview` | Dashboard KPIs, top clusters, recent activity |
+| `moda overview` | Dashboard KPIs, top clusters, recent activity. `--compare` adds `trends`: overview KPIs, per-unit rates, Problems and each detector family against the previous window of equal length; `--series` adds `[bucket, value]` arrays; `--since=<ISO> [--until=<ISO>]` sets the window (before/after a deploy); `--agent-name=<sub-agent>`; `--unit=conversation\|segment\|turn` |
 | `moda ask "<question>"` | Natural-language production/harness answer with evidence (exit `3` = degraded local fallback) |
 | `moda investigate` | Rank production issues (tool failures, frustrations, top Problems) with evidence + next commands |
 | `moda clusters` | Browse topic cluster hierarchy; `--search="q"` finds clusters by meaning, `--node-id=ID` resolves a deep link |
@@ -25,7 +25,7 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `moda detections list --family=frustration` | User frustration detections with evidence (the frustration family of `emotions`, legacy field names) |
 | `moda detections list --family=emotion` | Multi-family emotion detections: frustration, disapproval, sadness, confusion, anxiety, trust, positive (`--family=F`, `--user-id`, `--conversation-id`, limit 1–20) |
 | `moda detections list --family=hallucination` | Grounding detections: contradicted/verified outputs, rule breakdown (`--kind=contradicted\|verified`, `--conversation-id=ID`) |
-| `moda detections tools` | Tool failure overview |
+| `moda detections tools` | Tool failure overview (`--compare` adds `summary.compare`) |
 | `moda detections tools <tool_name>` | Per-tool failure breakdown + examples |
 | `moda tools list` | Tool catalog: every tool called in the window with calls, failed calls, success rate, traces, effect direction, last seen (`--sort=calls\|failure_rate\|failures\|traces\|last_seen`, `--search`, `--direction`, `--limit` 1-200, `--offset`) |
 | `moda tools get <tool_name>` | One tool: call stats, registered description and schema, observed payload fields, usage over time, top failure categories with the newest failure (`--days-back`, `--full`) |
@@ -35,6 +35,8 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `moda review <kind> <target>` | Write: kinds `problem\|problem-detection\|quote\|tool\|laziness\|hallucination\|custom-signal`; `--reason` optional; problem-detection needs `--conversation-id` + `--attribution-id`; quote needs `--family`, `--turn`, `--quote`; tool needs `--tool` plus `--tool-use-id` or `--msg-index`; custom-signal needs `--conversation-id`; `--verdict=clear` removes a mark (not for problem) |
 | `moda reviews list [conversation_id]` | Current false-positive marks: all (`--kind=quote\|tool\|laziness\|hallucination\|custom-signal`, `--all` to include removed, `--limit`) or one trace with its problem detection reviews. Problem dismissals are read with `moda problems get <problem_id> --feedback`, detection reviews with `moda reviews list <conversation_id> --kind=problem-detection` |
 | `moda detections list --family=laziness` | Laziness detections per trace (`--days-back`, `--limit` 1-50, `--conversation-id`, `--family`) |
+| `moda detections list --family=<f> --compare` | Adds `summary.compare`: the family's dashboard KPI tiles and per-trace rate for the list's `--days-back` window against the previous window of equal length (whole family; not with `--conversation-id`/`--user-id`) |
+| `moda problems get <problem_id> --trend` | Incidents and users per day (`[date, value]`) and incidents/signals against the previous window of equal length (`--days-back`, default 30; no comparison above 45) |
 | `moda detections list --family=<f> --group-by=trace` | The dashboard's per-trace list for emotion, frustration and hallucination: totals count traces. Dashboard filters imply it: emotion/frustration `--search --status --elicitor --trajectory --signal --sort --order`; hallucination `--search --status --rule --source --sort --order`; laziness (always per trace) `--search --status --sort --order`. See detections.md 5a |
 | `moda problems linear <problem_id>` | The Problem's linked Linear issue (key, state, URL) or `link: null`; needs Linear connected (Integrations → Linear) |
 | `moda problems link <problem_id>` | Write: file the Problem as a Linear issue (`--team-id`, `--title`, `--priority=0-4`), or link an existing one with `--issue=ENG-123\|URL` (exclusive with the others). Idempotent per Problem |

package/skills/moda-cli/references/dashboard-parity.md

@@ -14,6 +14,9 @@ Writes listed here accept `--dry-run`: it validates the call, prints the exact r
 | Traces list: Processed, Use case confidence, Indexed columns | `moda traces` rows: `processing_status`, `error_message`, `membership_score`, `indexed_at`; `moda traces get <id>`: `trace_state` |
 | Signals tabs: per-trace list, filters, sort | `moda detections list --family=<f> --group-by=trace` plus `--trajectory --elicitor --signal --status --search --sort --order` (emotion), `--rule --source` (hallucination) |
 | Settings: which detectors run | `moda overview` → `detectors` (read-only; switching one is dashboard-only) |
+| Home / Analytics / Signals KPI cards: change against the previous period, sparklines, agent selector | `moda overview --compare [--series] [--since=<ISO> --until=<ISO>] [--agent-name=<sub-agent>] [--unit=turn]` |
+| Detector tab KPI tiles with deltas | `moda detections list --family=<f> --compare` (`summary.compare`) |
+| Problem history per day | `moda problems get <problem_id> --trend [--days-back=N]` |
 | Users page / user profile | `moda users [--window --cohort --sort --order --health-status]`, `moda user <id>` (`--cohort` takes `builtin:<key>`, a saved cohort id, or a bare built-in key) |
 | Cohort selector on Problems, Traces, Signals tabs, custom signals, Topics | `--cohort=builtin:<key>\|<saved id>` on `problems list`, `traces list`, `detections list` (emotion, frustration and hallucination read the per-trace list; laziness; custom_signal `--signal-id`), `detections tools`, `clusters` (`--time-range=all\|3d\|7d\|30d`, also with `--search`). Output says which cohort scoped it (summary line and `cohort` in the data). `traces search` has no cohort scope |
 | Cohort builder: list, fields, preview, compare, save, edit | `moda cohorts list [--include-archived]`, `get <ref>`, `fields`, `preview --file=<definition.json>`, `compare <a> <b> [--days=7\|30\|90]`, `create --name --file [--dry-run]`, `update <cohort_id> [--name --file --note] [--dry-run]` (archiving is dashboard-only) |

package/skills/moda-cli/references/detections.md

@@ -126,6 +126,26 @@ An empty detection list is not proof a trace is clean:
   pending or errored traces: a pending trace may already have some detections,
   but its detections may be incomplete.
 
+### 5c. Is a family getting worse? (`--compare`)
+
+```bash
+moda detections list --family=frustration --compare --days-back=7
+moda detections list --family=laziness:stub_body --compare
+moda detections tools --compare --days-back=14
+```
+
+`--compare` adds `summary.compare`, one more read (GET `/v1/data/trends`)
+with the dashboard's KPI tiles for the family: `kpis` (for example emotion
+analyzed traces, negative rate, negative detections, affected users and traces
+per family) and `rate` (share of traces with a detection, the Signals rate
+card; left out for `frustration` and a sub-family, since the card counts the
+whole detector, and `notes` says so). Each figure is `{current, previous, delta, delta_pct, spike?}` for the
+list's `--days-back` window against the window of equal length just before it.
+It covers the whole family, so it rejects `--conversation-id` and `--user-id`;
+other list filters do not narrow it. For a before/after-deploy window, or a
+series per hour or day, use `moda overview --compare --since=<deploy time>`
+and `--series` (see production-intelligence.md).
+
 ### 6. Tool failure investigation
 
 ```bash

package/skills/moda-cli/references/production-intelligence.md

@@ -12,6 +12,54 @@ moda overview --days-back=30
 Returns total traces, trend, frustration rate, tool failure summary,
 top clusters, recent activity.
 
+#### Before/after and trends (`--compare`, `--series`)
+
+```bash
+moda overview --compare                                   # last 7 days against the 7 days before
+moda overview --compare --since=2026-10-17T14:00:00Z      # after a deploy against the same span before it
+moda overview --compare --since=2026-10-10 --until=2026-10-12   # a fixed window against the one before it
+moda overview --series --days-back=14                     # adds [bucket, value] series (implies --compare)
+moda overview --compare --agent-name=planner              # one sub-agent (names in trends.agent.options)
+moda overview --compare --unit=turn                       # rates per user turn (or segment) instead of per trace
+```
+
+Adds `trends` (GET `/v1/data/trends`), read from the dashboard's own loaders.
+The previous window is always the span of equal length just before the window,
+as the dashboard defines it. So `--since=<deploy time>` (to now) compares after
+the deploy with the same length of time before it. There is no separate
+`--compare-to` flag: every dashboard loader computes "previous" this way.
+`--days-back` and `--since` are exclusive; `--until` needs `--since`; a window
+can be up to 90 days.
+
+Each figure is `{current, previous, delta, delta_pct, spike?}`. `delta` is
+current minus previous (percentage points for a `_pct` rate). `delta_pct` is the
+relative change. `spike` is the dashboard's spike rule. Sections:
+
+| Section | Dashboard source | Figures |
+|---|---|---|
+| `overview` | Analytics overview | traces, messages, negative emotion rate (per analyzed trace), failed tool calls (per call), ungrounded claims (per scored message); `n` gives numerator and denominator |
+| `problems` | Problems trend card | analysed traces, traces with any signal, signal rate (`--days-back` only) |
+| `rates` | Signals overview rate cards | each detector's share of units with a detection (`--unit=conversation\|segment\|turn`) |
+| `detectors` | Detector tab KPI tiles | emotion (analyzed, negative rate, detections, affected users, traces per family), tool_failure (failed traces, classified failures, failure rate, calls, users, tools), laziness, hallucination |
+
+The same detector can show different rates in different sections because each
+uses its own denominator (`rate_note` says which). `detectors.tool_failure.failure_rate_pct`
+counts classified failures per call and is higher than `overview.tool_failure_rate_pct`
+(failed call records per call).
+
+`--series` adds `trends.series`: compact `[bucket, value]` arrays, per hour for
+windows up to 2 days and per day above. Bucket keys are `YYYY-MM-DD` or
+`YYYY-MM-DDTHH:00Z`.
+
+`--agent-name` scopes the `overview` section only. The Problems, rates and
+detector loaders have no sub-agent filter, so those sections are left out and
+`trends.notes` says so.
+
+The `overview` section is the slow part: on a large workspace a 30-day window
+can take about 40 seconds, and the CLI waits up to 90. A figure whose read
+failed is `null` with `unavailable: true` (never zero), and `trends.notes`
+names it.
+
 ### 2b. Ask & investigate (production intelligence)
 
 `moda ask` answers a natural-language production/harness question (a paid