@moda-ai/cli 1.55.41 → 1.55.43

package/dist/{index-w7v472w4.js → index-svfzq5rb.js}

@@ -1,6 +1,6 @@
 import {
   buildDoctorReport
-} from "./cli-a8nxbtpk.js";
+} from "./cli-h62j4jn7.js";
 import {
   selectTenantAndCreateKey
 } from "./cli-1z1sx8dg.js";
@@ -20,7 +20,7 @@ import {
 import {
   agentsMdProblem,
   runSkillSync
-} from "./cli-7bn406mt.js";
+} from "./cli-stfpr2ct.js";
 import"./cli-qm5b1vck.js";
 import {
   detectAgents
@@ -32,7 +32,7 @@ import {
 import {
   initPrompts,
   runPromptSync
-} from "./cli-4tg0hkbz.js";
+} from "./cli-k5drmy8r.js";
 import"./cli-mm48br00.js";
 import {
   codingAgentDisplayName,
@@ -46,7 +46,7 @@ import {
   runCodingAgent,
   runHarnessCommand,
   startRemoteAnalyze
-} from "./cli-azage7s0.js";
+} from "./cli-s1w5phms.js";
 import {
   canonicalText,
   renderInitBanner,
@@ -62,8 +62,9 @@ import"./cli-cesds766.js";
 import"./cli-qpq84eee.js";
 import {
   createCommandContext
-} from "./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+} from "./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import {
   VERSION,

package/dist/{production-intelligence-e5vsc6cw.js → production-intelligence-7jvfdz6b.js}

@@ -5,14 +5,19 @@ import {
   asString,
   contextTarget,
   frustrationAnchorIndex,
-  frustrationsFromEmotions
-} from "./cli-gt3yq1y5.js";
+  frustrationsFromEmotions,
+  loadTrends,
+  overviewTrendsQuery,
+  renderTrendsHuman,
+  trendsSummaryText
+} from "./cli-5y9tj6cb.js";
 import {
   renderMarkdownForTerminal,
   shouldColorTerminalOutput,
   stripAnsi,
   terminalStyles
 } from "./cli-97fnztpy.js";
+import"./cli-e0kbye4s.js";
 import {
   callControlAPI,
   callDataAPI
@@ -407,7 +412,12 @@ function isAuthFailure(error) {
 async function runProductionCommand(context) {
   const daysBack = daysBackFlag(context.flags);
   if (context.command === "overview") {
-    const briefing = await loadOverviewBriefing({ daysBack, cwd: context.cwd });
+    const trendsQuery = overviewTrendsQuery(context.flags, daysBack);
+    const [loaded, trends] = await Promise.all([
+      loadOverviewBriefing({ daysBack, cwd: context.cwd }),
+      trendsQuery ? loadTrends(trendsQuery) : Promise.resolve(undefined)
+    ]);
+    const briefing = trends ? { ...loaded, trends } : loaded;
     if (context.flags.raw === "true") {
       context.output.writeData(briefing.rawOverview, {
         summary: "Loaded raw Moda overview.",
@@ -1463,16 +1473,19 @@ function investigationAgentOptions(investigation) {
   };
 }
 function overviewAgentOptions(briefing) {
+  const trendText = briefing.trends ? trendsSummaryText(briefing.trends) : null;
+  const trendNotes = Array.isArray(briefing.trends?.notes) ? briefing.trends.notes.map(String) : [];
+  const warnings = [...detectorWarnings(briefing.detectors), ...trendNotes];
   return {
     summary: {
-      text: `Moda health briefing: ${briefing.status}. Next: ${briefing.nextCommand}`,
+      text: `Moda health briefing: ${briefing.status}.${trendText ? ` ${trendText}` : ""} Next: ${briefing.nextCommand}`,
       confidence: briefing.topFinding ? briefing.topFinding.confidence : "medium"
     },
     findings: briefing.topFinding ? [agentFinding(briefing.topFinding)] : [],
     evidenceRefs: briefing.evidenceRefs.map(agentEvidence),
     recommendedActions: briefing.topFinding ? briefing.topFinding.recommendedActions.map(agentAction) : [],
     nextCommands: [nextCommand(briefing.nextCommand)],
-    ...detectorWarnings(briefing.detectors).length > 0 ? { warnings: detectorWarnings(briefing.detectors) } : {}
+    ...warnings.length > 0 ? { warnings } : {}
   };
 }
 function askAgentOptions(result) {
@@ -1558,6 +1571,10 @@ function renderOverviewBriefingHuman(briefing) {
     for (const warning of detectorWarnings(briefing.detectors))
       lines.push(`  Warning: ${warning}`);
   }
+  if (briefing.trends) {
+    lines.push("");
+    lines.push(...renderTrendsHuman(briefing.trends));
+  }
   lines.push("");
   lines.push("Top signal");
   if (briefing.topFinding) {

package/dist/{prompt-attribution-3987hhqz.js → prompt-attribution-hc6mcvee.js}

@@ -1,15 +1,16 @@
 import {
   inventoryFiles,
   safePromptEvidencePath
-} from "./cli-azage7s0.js";
+} from "./cli-s1w5phms.js";
 import"./cli-xq45etg1.js";
 import"./cli-97fnztpy.js";
 import"./cli-cesds766.js";
 import {
   require_typescript
 } from "./cli-qpq84eee.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import"./cli-k4tqwah4.js";

package/dist/prompt-source-mcp.js

@@ -3,7 +3,7 @@ import {
   checkPromptMapping,
   discoverHarnessPromptSources,
   safePromptEvidencePath
-} from "./cli-azage7s0.js";
+} from "./cli-s1w5phms.js";
 import"./cli-xq45etg1.js";
 import"./cli-97fnztpy.js";
 import"./cli-cesds766.js";
@@ -11,8 +11,9 @@ import {
   inspectCodeSelectors,
   inspectPythonSelectors
 } from "./cli-qpq84eee.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import"./cli-k4tqwah4.js";

package/dist/{prompts-ab-gmd10n5d.js → prompts-ab-ws66335h.js}

@@ -23,12 +23,13 @@ import {
   runPromptAb,
   selectProblemCases,
   waitLabel
-} from "./cli-ypqwcf9n.js";
-import"./cli-4tg0hkbz.js";
+} from "./cli-fpd1pfvt.js";
+import"./cli-k5drmy8r.js";
 import"./cli-daqkdnm1.js";
 import"./cli-mm48br00.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import"./cli-k4tqwah4.js";

package/dist/{prompts-propose-q626zmm4.js → prompts-propose-a9m0p9nr.js}

@@ -7,12 +7,13 @@ import {
   formatVerdict,
   rerunWithYes,
   resolvePromptArmSpec
-} from "./cli-ypqwcf9n.js";
-import"./cli-4tg0hkbz.js";
+} from "./cli-fpd1pfvt.js";
+import"./cli-k5drmy8r.js";
 import"./cli-daqkdnm1.js";
 import"./cli-mm48br00.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import {
   callControlAPI
 } from "./cli-0xc5htv7.js";

package/dist/{prompts-ysm9ra72.js → prompts-xe5bgbx8.js}

@@ -11,12 +11,13 @@ import {
   runPromptSync,
   runPromptsCommand,
   writePromptSyncProgress
-} from "./cli-4tg0hkbz.js";
+} from "./cli-k5drmy8r.js";
 import {
   promptSourceHashPayload
 } from "./cli-mm48br00.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import"./cli-k4tqwah4.js";

package/dist/{provision-cya5rpxa.js → provision-a9kkfvp7.js}

@@ -7,7 +7,8 @@ import {
 } from "./cli-pmzh2qjy.js";
 import {
   stringOption
-} from "./cli-xddtv3yn.js";
+} from "./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
 import {
   resolveIngestUrl,
   resolveModaBaseUrl

package/dist/{registry-7xz09ry0.js → registry-j2dsfh6v.js}

@@ -1,6 +1,6 @@
 import {
   assertFlags
-} from "./cli-f1jfrqgf.js";
+} from "./cli-9a0a3v13.js";
 import {
   callControlAPI
 } from "./cli-0xc5htv7.js";

package/dist/{skills-x6yszxxn.js → skills-vveagdwe.js}

@@ -3,12 +3,13 @@ import {
   pullSkills,
   runSkillSync,
   runSkillsCommand
-} from "./cli-7bn406mt.js";
+} from "./cli-stfpr2ct.js";
 import"./cli-qm5b1vck.js";
 import"./cli-rjav0vj1.js";
 import"./cli-hcwdz9sd.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import"./cli-k4tqwah4.js";

package/dist/{sync-trjzvam9.js → sync-yy3fgnxe.js}

@@ -1,22 +1,23 @@
 import {
   runSkillsCommand
-} from "./cli-7bn406mt.js";
+} from "./cli-stfpr2ct.js";
 import"./cli-qm5b1vck.js";
 import"./cli-rjav0vj1.js";
 import"./cli-hcwdz9sd.js";
 import {
   runPromptsCommand
-} from "./cli-4tg0hkbz.js";
+} from "./cli-k5drmy8r.js";
 import"./cli-mm48br00.js";
 import {
   runHarnessCommand
-} from "./cli-azage7s0.js";
+} from "./cli-s1w5phms.js";
 import"./cli-xq45etg1.js";
 import"./cli-97fnztpy.js";
 import"./cli-cesds766.js";
 import"./cli-qpq84eee.js";
-import"./cli-xddtv3yn.js";
-import"./cli-f1jfrqgf.js";
+import"./cli-5fhqfx04.js";
+import"./cli-e0kbye4s.js";
+import"./cli-9a0a3v13.js";
 import"./cli-0xc5htv7.js";
 import"./cli-t0pb7qbs.js";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.55.41",
+  "version": "1.55.43",
   "description": "CLI for Moda: production monitoring and evals for AI agents.",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-10-18T02:11:16.441Z",
-  "cli_version": "1.55.41",
+  "bundled_at": "2026-10-18T02:56:13.211Z",
+  "cli_version": "1.55.43",
   "skills": [
     {
       "id": "integration-cloudflare-think",

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 3.0.7
+version: 3.0.9
 description: Investigate a production AI agent with the Moda CLI (`moda`) - find where something happened in real traces (traces search, then traces get), check agent health, rank what to fix (investigate, problems), and dig into tool failures, user frustration, and hallucinations. Also prompt registry sync/promote, replays, custom signals, and false-positive marking. Use when the user mentions Moda, production traces or conversations of their agent, agent failures, or asks what to fix.
 ---
 
@@ -60,6 +60,8 @@ Details: `references/output-protocol.md`.
 | Where did X happen / traces about Y | `moda traces search "<words>"` (`--mode=keyword` for ids, error codes, exact strings; `--include-tool-io` for tool inputs/outputs) | `moda traces get <conversation_id> --msg-index=<message_index> --window=3` |
 | Search returned nothing | Read `.warnings` (degraded mode, reason). Try a shorter phrase, `--mode=keyword`, a wider `--time-range` | `moda traces --search="<words>"` |
 | Is the agent healthy? | `moda overview --days-back=7` | `moda investigate` |
+| Did my change make it worse? | `moda overview --compare --since=<deploy time, ISO UTC>` (after the deploy against the same span before it; add `--agent-name=<sub-agent>` for one sub-agent) | `moda overview --series --since=<deploy time>` (per hour up to 2 days, else per day), `moda detections list --family=<f> --compare`, `moda problems get <problem_id> --trend` |
+| Is X trending up? | `moda overview --compare --series --days-back=14` | `moda problems get <problem_id> --trend --days-back=30` (incidents per day) |
 | What to fix first? | `moda investigate` or `moda problems list` (free; both rank the same list the dashboard shows, `data.problemsView` names it) | `moda problems get <problem_id>` (`--view=dream` on a dream-grouped tenant), then `--evidence` / `--traces` |
 | Why is tool T failing? | `moda detections tools` | `moda detections tools <T>` (use each row's `anchor`) |
 | How often is tool T called / what is its schema? | `moda tools list` (every tool: calls, failed calls, success rate; `--sort=failure_rate`) | `moda tools get <T>` (registered schema, observed payload fields, usage over time, top failure categories) |
@@ -72,6 +74,7 @@ Details: `references/output-protocol.md`.
 | Read one whole trace | `moda traces get <id> --all` (pages of up to 500 messages) | `moda traces spans <id>` for raw spans |
 | Read several traces or turns | `moda traces get <id1>@<msg_index> <id2>@<msg_index> ...` (up to 25; or one per line via `--ids-from=-`) | Same for `moda traces spans <id1> <id2> ...` |
 | One user's experience | `moda users`, `moda user <user_id>` | `moda traces search "<words>" --user-id=<id>` |
+| Is this only hurting <segment> (enterprise, new users, ...)? | `moda cohorts list` (the ref of a built-in or saved cohort), then `moda problems list --sort=users --cohort=<ref>` and the same command without `--cohort` | `moda detections list --family=frustration --cohort=<ref>` vs no `--cohort` (totals count traces); `moda cohorts compare <ref> builtin:power_users` for size, health and failure mix |
 | Topic mix | `moda clusters` | `moda cluster-traces <node_id>` |
 | What the agent believed at a turn | `moda traces state <id> --snapshot --msg-index=<n>` | |
 | A synthesized answer | `moda ask "<question>"` only when the user asks: each call is a paid agent run (up to about 200k tokens) | Exit 3 means degraded |

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 |
@@ -54,7 +56,10 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
 | `moda registry template\|validate\|push\|status\|coverage\|log\|show\|prompt` | Register prompts, skills, tools, and agent wiring from one agent-written manifest (`--file`, `--dry-run`, `--live`, `--message`, `--days`); every push is a commit in the Registry history; no repo scan |
-| `moda users` / `moda user <id>` | End users with health/activity (`--page-size=N`, alias `--limit=N`; `--page=N`); one user's profile |
+| `moda users` / `moda user <id>` | End users with health/activity (`--page-size=N`, alias `--limit=N`; `--page=N`; `--cohort=builtin:<key>\|<saved id>`); one user's profile |
+| `moda cohorts list\|get\|fields\|preview\|compare` | User cohorts (built-in and saved): refs and definitions, the definition fields, a member count and sample for an unsaved definition (`--file`/`--definition`), two cohorts side by side (`--days=7\|30\|90`) |
+| `moda cohorts create\|update` | Write: save a cohort (`--name`, `--file`/`--definition`, `--description`, `--pinned`, `--color`) or edit a saved one (`<cohort_id>`, same flags plus `--note`); both take `--dry-run` |
+| `--cohort=<ref>` | Scope `problems list`, `traces list`, `detections list` (emotion/frustration/hallucination per trace, laziness, custom_signal hits), `detections tools` and `clusters` to one cohort (`builtin:<key>` or a saved id from `moda cohorts list`). The summary names the cohort; a warning means the server did not confirm the scope |
 | `moda problems reopen <pid>` | Reopen a Problem marked fixed |
 | `moda signals <create\|update\|activate\|pause\|delete\|examples\|refine\|revise\|proposals\|accept\|reject\|search\|preview>` | Manage custom signals (writes take `--dry-run`; LLM-backed ones are rate-limited per key) |
 | `moda prompts list\|show\|proposals\|usage\|replay-runs\|decide` | Read the prompt registry; merge/reject proposals |

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

@@ -5,7 +5,7 @@ Loaded on demand from the moda-cli skill.
 ### 10. Everything the dashboard does, from the CLI
 
 Every command below needs only an API key, and the tenant comes from the key.
-Writes listed here accept `--dry-run`: it validates the call, prints the exact request (method, endpoint, body) and sends nothing, and its `next_commands` entry is the command that sends it for real (`mutability: write`, `requires_approval: true`). That covers `problems feedback|reopen|link`, `review`, `feedback` and the `signals` writes. `prompts promote|ab|propose` refuse `--dry-run` before sending anything, so run them only when you mean it.
+Writes listed here accept `--dry-run`: it validates the call, prints the exact request (method, endpoint, body) and sends nothing, and its `next_commands` entry is the command that sends it for real (`mutability: write`, `requires_approval: true`). That covers `problems feedback|reopen|link`, `review`, `feedback`, `cohorts create|update` and the `signals` writes. `prompts promote|ab|propose` refuse `--dry-run` before sending anything, so run them only when you mean it.
 
 | Dashboard | CLI |
 |---|---|
@@ -14,7 +14,12 @@ 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) |
-| Users page / user profile | `moda users [--window --cohort --sort --order --health-status]`, `moda user <id>` |
+| 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) |
 | Tool catalog: every tool, its schema and usage | `moda tools list [--sort=calls\|failure_rate\|failures\|traces\|last_seen --search --direction --offset]`, `moda tools get <tool_name>` |
 | Problems list (dream grouping or Book, as the page decides): sort, cohort, page | `moda problems list [--sort=users --cohort=builtin:<key> --offset=N --list-version=V]`; `--view=book\|dream` forces one |
 | Problem page (dream view): severity, incidents with verdicts | `moda problems get <problem_id> --view=dream [--offset=N]` |

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