@moda-ai/cli 1.55.42 → 1.55.44

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

package/skills/moda-cli/references/search-and-traces.md

@@ -37,7 +37,9 @@ These rows have no score or message index. Open one with
 `moda traces spans <conversation_id>` or `moda traces get <conversation_id>` to find the
 matching turn. When more traces exist, `fallback.has_more` is true and
 `next_commands` includes the `moda traces --search ... --offset` command to
-page. With `--mode=keyword`, ranked traces are not substituted. If the fallback
+page. With `--mode=keyword` the trace-level search is not run (it is
+relevance-ranked, so it could not be shown as literal matches); a warning says
+so and `next_commands` offers `moda traces --search` instead. If the fallback
 itself fails, you get a warning, not a silent empty result. Either way, zero
 results does not prove the topic never came up.
 

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

@@ -33,6 +33,20 @@ setup wizard; do not run it unprompted.
 The key is invalid, revoked, or for another environment. Get a new key and
 save it with `moda auth login --api-key`.
 
+**`Tenant <id> does not exist or is not accessible to this API key` (exit 1, `not_found`)**
+`MODA_TENANT_ID` (or `--tenant-id`) names a tenant that does not exist or was
+deleted. The key itself is fine. Set the tenant id to one from the dashboard
+URL, or from `moda auth whoami` with a browser session, and retry. A key that
+belongs to one tenant and is pointed at another gets `access_denied` with
+"Unset MODA_TENANT_ID" instead; a read-only key running a write gets
+`access_denied` saying it is read-only.
+
+**`MODA_BASE_URL=... is a loopback URL, and the active profile 'prod' is a prod profile` (exit 5, `input_required`)**
+Nothing was sent. Re-run with `--profile=local` (the choice's `resume_flags`)
+to use the local stack, or unset `MODA_BASE_URL` to use production.
+`moda auth status --online` then shows `online.baseUrl` and, from `/whoami`,
+the tenant the key acts on.
+
 **`not_found` (exit 1)**
 The trace, problem, or cluster id does not exist in this tenant (a trace with
 no generated world state returns a warning, not `not_found`).