@moda-ai/cli 1.55.23 → 1.55.25

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

@@ -14,34 +14,34 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `moda auth logout` | Revoke the CLI session server-side, then delete it locally |
 | `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 search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
+| `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 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 |
 | `moda cluster-traces <node_id>` | Traces in a cluster (legacy alias: `moda cluster-conversations`) |
 | `moda traces` | List/filter traces by structured fields (legacy alias: `moda conversations`) |
-| `moda context <conversation_id>` | Windowed message context (max 5 per side); `--msg-index=N` (alias `--message-index`) anchors the window |
-| `moda frustrations` | User frustration detections with evidence (the frustration family of `emotions`, legacy field names) |
-| `moda emotions` | Multi-family emotion detections: frustration, disapproval, sadness, confusion, anxiety, trust, positive (`--family=F`, `--user-id`, `--conversation-id`, limit 1–20) |
-| `moda hallucinations` | Grounding detections: contradicted/verified outputs, rule breakdown (`--kind=contradicted\|verified`, `--conversation-id=ID`) |
-| `moda tool-failures` | Tool failure overview |
-| `moda tool-failure-detail <tool_name>` | Per-tool failure breakdown + examples |
-| `moda problems` | Rank cross-signal Problems by root cause (what to fix first); takes only `--days-back`/`--limit`. Filter by family with `moda problems remainder --family=F` or `moda problem <problem_id> --traces --family=F` |
-| `moda problem <problem_id>` | One Problem: dossier, or `--evidence`/`--reports`/`--traces`/`--feedback` pages (`--conversations` is a legacy alias of `--traces`) (`--limit` 1–50, `--cursor` verbatim keyset token) |
-| `moda problem-feedback <problem_id>` | Write: `--action=mark_fixed\|dismiss\|flag_attribution\|rename`. `--reason` required for flag_attribution, optional for dismiss; `--new-name` for rename; `--attribution-id` (UUID) required for flag_attribution |
-| `moda false-positive <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`; `--undo` removes a mark (not for problem) |
-| `moda false-positives [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 problem <problem_id> --feedback`, detection reviews with `moda detection-reviews <conversation_id>` |
-| `moda laziness` | Laziness detections per trace (`--days-back`, `--limit` 1-50, `--conversation-id`, `--family`) |
-| `moda problem-linear <problem_id>` | The Problem's linked Linear issue (key, state, URL) or `link: null`; needs Linear connected (Integrations → Linear) |
-| `moda problem-linear-file <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 |
-| `moda detection-reviews <conversation_id>` | Problem detections on a trace with review state (`--attribution-id=UUID` narrows to one) |
-| `moda detection-review <problem_id>` | Write: `--conversation-id`, `--attribution-id` (UUID), `--verdict=correct\|false_positive\|clear`, optional `--note` |
+| `moda traces get <conversation_id>` | Windowed message context (max 5 per side); `--msg-index=N` (alias `--message-index`) anchors the window |
+| `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_name>` | Per-tool failure breakdown + examples |
+| `moda problems` | Rank cross-signal Problems by root cause (what to fix first); takes only `--days-back`/`--limit`. Filter by family with `moda problems unexplained --family=F` or `moda problems get <problem_id> --traces --family=F` |
+| `moda problems get <problem_id>` | One Problem: dossier, or `--evidence`/`--reports`/`--traces`/`--feedback` pages (`--conversations` is a legacy alias of `--traces`) (`--limit` 1–50, `--cursor` verbatim keyset token) |
+| `moda problems feedback <problem_id>` | Write: `--action=mark_fixed\|dismiss\|flag_attribution\|rename`. `--reason` required for flag_attribution, optional for dismiss; `--new-name` for rename; `--attribution-id` (UUID) required for flag_attribution |
+| `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 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 |
+| `moda reviews list <conversation_id> --kind=problem-detection` | Problem detections on a trace with review state (`--attribution-id=UUID` narrows to one) |
+| `moda review problem-detection <problem_id>` | Write: `--conversation-id`, `--attribution-id` (UUID), `--verdict=correct\|false_positive\|clear`, optional `--note` |
 | `moda signals` | Custom signals: criteria, status, 7-day judged/matched stats |
 | `moda signal <signal_id>` | One custom signal; `--detections` pages recent hits (`--days-back` 1–90, `--limit` 1–20, `--offset`) |
-| `moda trace-signals <conversation_id>` | Custom signal hits on one trace |
-| `moda signal-label <signal_id>` | Write: `--conversation-id`, `--label=fits\|does_not_fit` (false positive), optional `--note`, `--msg-index`/`--msg-dedup-token` |
-| `moda world-state <conversation_id>` | Agent memory: slots/threads/events; `--summary-only`; `--snapshot --msg-index=N` (state at a turn); `--replay --message-count=N` (state over time) |
+| `moda detections list --family=custom_signal --conversation-id=<conversation_id>` | Custom signal hits on one trace |
+| `moda review custom-signal <signal_id>` | Write: `--conversation-id`, `--verdict=correct\|false_positive\|clear`, optional `--note`, `--msg-index`/`--msg-dedup-token` |
+| `moda traces state <conversation_id>` | Agent memory: slots/threads/events; `--summary-only`; `--snapshot --msg-index=N` (state at a turn); `--replay --message-count=N` (state over time) |
 | `moda failures` | Tool failures only, ranked (no frustrations or Problems) |
 | `moda tail` | Live tail: one JSON line per new trace/detection (`--signal=traces\|emotions\|all`, legacy alias `--signal=conversations`, `--interval=N`, `--once`, `--max-events=N`). **Emotions caveat:** `/emotions` is ranked by score with no time ordering or cursor, so the tail follows the *highest-scoring* detections rather than everything; each poll emits a `tail_coverage` line with `scanned`/`total`/`coverage_pct`/`complete`. Pass `--full-scan` for a complete window scan (many more requests, capped by the API's offset ceiling of 10000). |
 | `moda feedback "<note>"` | Flag wrong/missing data or CLI quirks to the Moda team |
@@ -51,13 +51,13 @@ Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <com
 | `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 problem-reopen <pid>` | Reopen a Problem marked fixed |
+| `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 |
 | `moda replays sets\|runs\|run\|playouts\|playout` | Replay results: run history, per-seed verdicts, playout transcripts with tool provenance (read-only) |
 | `moda skills list\|show\|policy` / `moda harness list\|show\|versions\|diff` | Skill library and synced harnesses |
 
-`moda search` flags: `--mode=keyword|semantic|hybrid` (default `hybrid`),
+`moda traces search` flags: `--mode=keyword|semantic|hybrid` (default `hybrid`),
 `--user-id`, `--time-range=<range>`, `--limit=N` (1–100, default 20).
 
 There is no flag set common to every command: each command rejects a flag it

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

@@ -5,15 +5,15 @@ 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` (prints the exact request, sends nothing) except `problem-feedback`, `false-positive`, `detection-review`, `signal-label`, `problem-linear-file`, and `prompts promote|ab|propose`. Those refuse `--dry-run` before sending anything, so run them only when you mean it.
+Writes listed here accept `--dry-run` (prints the exact request, sends nothing) except `problems feedback`, `review`, `problems link`, and `prompts promote|ab|propose`. Those refuse `--dry-run` before sending anything, so run them only when you mean it.
 
 | Dashboard | CLI |
 |---|---|
 | Traces list: sort, page | `moda traces --sort=recent\|longest\|slowest --offset=N` |
-| Trace detail: whole transcript | `moda context <id> --all` (ordered, with tool calls/results) |
+| Trace detail: whole transcript | `moda traces get <id> --all` (ordered, with tool calls/results) |
 | Users page / user profile | `moda users [--window --cohort --sort --order --health-status]`, `moda user <id>` |
-| Problems: unexplained remainder | `moda problems remainder [--family=emotion\|tool_failure\|laziness\|… --cursor]` |
-| Reopen a problem marked fixed | `moda problem-reopen <problem_id> --reason="…"` (resolved ones return only via re-detection) |
+| Problems: unexplained remainder | `moda problems unexplained [--family=emotion\|tool_failure\|laziness\|… --cursor]` |
+| Reopen a problem marked fixed | `moda problems reopen <problem_id> --reason="…"` (resolved ones return only via re-detection) |
 | Custom signals: create | `moda signals draft --note="…"`, then `moda signals create --name --description --pass-criteria --fail-criteria [--tool-names=a,b]` or `--file=body.json` |
 | Custom signals: edit, lifecycle | `moda signals update <id> …`, `moda signals activate\|pause\|delete <id>` (delete: drafts only; archiving is dashboard-only) |
 | Custom signals: review & tune | `moda signals examples <id> add\|update\|remove --conversation-id=…`, `refine <id> --request="…"`, `revise <id> --conversation-ids=…`, `proposals <id>`, `accept\|reject <id> <proposal_id>` |

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

@@ -5,11 +5,11 @@ Loaded on demand from the moda-cli skill.
 ### 5. Frustration analysis
 
 ```bash
-moda frustrations                             # last 7 days
-moda frustrations --days-back=14 --limit=20
-moda frustrations --include-window --window=1 --limit=5   # agent output omits windows unless asked
-moda emotions --family=frustration --user-id=<id>        # one end user
-moda emotions --conversation-id=<id>                     # every family, one trace
+moda detections list --family=frustration                             # last 7 days
+moda detections list --family=frustration --days-back=14 --limit=20
+moda detections list --family=frustration --include-window --window=1 --limit=5   # agent output omits windows unless asked
+moda detections list --family=emotion:frustration --user-id=<id>        # one end user
+moda detections list --family=emotion --conversation-id=<id>                     # every family, one trace
 ```
 
 In agent output, `frustrations` and `emotions` rows leave out the embedded
@@ -47,10 +47,10 @@ half-width; `--window=1` ⇒ 3 messages total (anchor ± 1), the canonical
 ### 6. Tool failure investigation
 
 ```bash
-moda tool-failures                            # which tools are breaking
-moda tool-failure-detail <tool_name>          # subtype breakdown + examples
-moda tool-failure-detail search --subtype=dependency.timeout --limit=10   # a value from `subtypes`
-moda tool-failure-detail search --include-window --window=1 --limit=5
+moda detections tools                            # which tools are breaking
+moda detections tools <tool_name>          # subtype breakdown + examples
+moda detections tools search --subtype=dependency.timeout --limit=10   # a value from `subtypes`
+moda detections tools search --include-window --window=1 --limit=5
 ```
 
 Every example row in `tool-failure-detail` output carries a top-level
@@ -63,7 +63,7 @@ directly instead of matching by `tool_use_id` against the trace.
 
 By default each row embeds `conversation`: the anchor ± 2 messages (without
 the duplicate `content_blocks`), plus `context_command`, the exact
-`moda context <conversation_id> --msg-index=<msg_index> --window=2` read for
+`moda traces get <conversation_id> --msg-index=<msg_index> --window=2` read for
 the untrimmed window. `--compact` (same as `--include-window=false` or
 `--no-include-window`) drops `conversation` and keeps the anchor and
 `context_command`.

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

@@ -39,7 +39,7 @@ moda feedback "trace is a refund request, not this problem" \
   `--message-index`); they go into `refs` and let the team reproduce what
   you saw.
 - Feedback does not change the problem itself. To act on a misroute directly,
-  use `moda problem-feedback <problem_id> --action=flag_attribution
-  --attribution-id=<uuid> --reason=TEXT` or `moda false-positive <kind> <target>
+  use `moda problems feedback <problem_id> --action=flag_attribution
+  --attribution-id=<uuid> --reason=TEXT` or `moda review <kind> <target>
   --reason=TEXT`.
 - Never include secrets or full transcripts in the note.

package/skills/moda-cli/references/output-protocol.md

@@ -116,7 +116,7 @@ Fields an agent should read:
 - `summary.text` + `summary.confidence` — the answer and how much to trust it
   (`high | medium | low | unknown`).
 - `evidence_refs[]` — each `{ id, kind, label, path }`. When `path` looks like
-  `conversation/<id>`, open it with `moda context <id>`.
+  `conversation/<id>`, open it with `moda traces get <id>`.
 - `next_commands[]` — suggested follow-up commands (each carries `mutability`
   and `requires_approval`).
 - `warnings[]`, `errors[]`.
@@ -179,7 +179,7 @@ Treat an answer as degraded if **any** of these hold:
   items are dropped from `data`. When rows are dropped, the list's
   `pagination` says what you got (`returned`, `limit`, `next_offset`; a
   `next_cursor` that would skip rows becomes `null`) and `next_commands` has
-  the exact command for the rest (e.g. `moda frustrations --offset=3
+  the exact command for the rest (e.g. `moda detections list --family=frustration --offset=3
   --limit=7`). `truncation.data.full_output_path` (also an `artifacts[]` entry of
   kind `full_output`) is that file; read it in line ranges or with `jq`.
   These files are pruned after 24 hours (`MODA_AGENT_OUTPUT_RETENTION_HOURS`).

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

@@ -43,7 +43,7 @@ Data API fallback. Abbreviated envelope:
     { "id": "tool:lookupCustomer", "kind": "tool_failure", "label": "lookupCustomer: 12 failure(s)", "path": null }
   ],
   "next_commands": [
-    { "command": "moda tool-failure-detail lookupCustomer --days-back=7 --include-window", "purpose": "Inspect tool failure examples and trace anchors.", "mutability": "read", "requires_approval": false }
+    { "command": "moda detections tools lookupCustomer --days-back=7 --include-window", "purpose": "Inspect tool failure examples and trace anchors.", "mutability": "read", "requires_approval": false }
   ],
   "warnings": ["Cloud ask endpoint unavailable; synthesized answer from local Data API evidence."],
   "errors": [],
@@ -55,7 +55,7 @@ Data API fallback. Abbreviated envelope:
 narrows the tool-failure evidence to one tool, and `--trace` (legacy alias
 `--conversation`) scopes only the frustration evidence (overview, tool
 failures and Problems stay tenant-wide). Its findings include the top 1–3
-Problems from `moda problems`, with `moda problem <id>` as the next command.
+Problems from `moda problems`, with `moda problems get <id>` as the next command.
 `moda failures` is the tool-failures-only view.
 
 After reporting the top behavioral failure and the harness layer it routes to
@@ -73,14 +73,14 @@ Problem, or before hand-editing prompt/skill files in a repo that talks to Moda.
 moda investigate                             # rank tool failures, frustrations,
                                              # and top Problems with evidence
 moda problems                                # cross-signal Problems by root cause
-moda problem <problem_id>                    # compact dossier: what, where, how often
-moda problem <problem_id> --full             # every dossier block (large)
-moda problem <problem_id> --evidence         # attribution rationales and anchors
-moda problem <problem_id> --traces           # affected traces with anchors
-moda tool-failure-detail <tool_name>         # failing calls with surrounding turns
-moda context <conversation_id> --window=3    # the messages around one turn
+moda problems get <problem_id>                    # compact dossier: what, where, how often
+moda problems get <problem_id> --full             # every dossier block (large)
+moda problems get <problem_id> --evidence         # attribution rationales and anchors
+moda problems get <problem_id> --traces           # affected traces with anchors
+moda detections tools <tool_name>         # failing calls with surrounding turns
+moda traces get <conversation_id> --window=3    # the messages around one turn
 # ...propose and make the change, citing the problem/trace ids in the PR...
-moda problem-feedback <problem_id> --action=mark_fixed   # after it ships
+moda problems feedback <problem_id> --action=mark_fixed   # after it ships
 ```
 
 Rules that keep the fix grounded:
@@ -90,7 +90,8 @@ Rules that keep the fix grounded:
 - Cite the Moda problem id and the trace ids you relied on in the PR
   description, so a reviewer can open the same evidence.
 - To test a prompt change against real traffic before shipping it, A/B it with
-  `moda prompts ab --baseline=<path> --candidate=<path> --traces=<ids>` (see
-  section 7).
+  `moda prompts ab --baseline=<path> --candidate=<path> --problem=<problem_id>`
+  (replays the Problem's failing traces from their evidence anchors) or
+  `--traces=<ids>` (see section 7).
 - Mark the Problem fixed only after the change ships. If the issue is detected
-  again, the Problem comes back; `moda problem-reopen` reopens it by hand.
+  again, the Problem comes back; `moda problems reopen` reopens it by hand.

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

@@ -72,7 +72,10 @@ read, they fail (exit 1) with the number and the exact command to re-run with `-
 Only add `--yes` when the user has agreed to that spend. Limits: `--cases`
 default 5, max 100; `--seeds` default 3, max 10; `--traces` at most 100
 (`--traces=conv_id@412` replays that trace from msg_index 412, with the
-earlier turns as history);
+earlier turns as history, and writes its case from the messages around 412);
+`--problem=<problem_id>` picks a Problem's affected traces, each anchored at
+its earliest evidence msg_index, up to
+`--max-cases` (default 10, max 100), and prints them (`problemCases`);
 `--model` / `--assistant-model` must be one of `openai/gpt-5.6-luna`,
 `openai/gpt-4o-mini`, `openai/gpt-4o`, `anthropic/claude-sonnet-4-5`,
 `anthropic/claude-haiku-4-5`, `google/gemini-2.5-flash`,
@@ -80,7 +83,8 @@ earlier turns as history);
 
 `prompts ab --traces=<ids>` builds one case per trace from Moda's distilled
 scenario and success criteria for that trace. A trace Moda cannot distill
-falls back to its opening user message with three generic criteria (which long
+falls back to its opening user message (for `id@N`, the user message leading
+into N) with three generic criteria (which long
 traces pass easily); the run warns and lists it under `caseSources.fallback`.
 `prompts ab` never makes its replay set the tenant's primary set unless you
 pass `--promote`.

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

@@ -8,43 +8,43 @@ Loaded on demand from the moda-cli skill.
 
 ```bash
 # Semantic: find the moment a user expressed an intent, in their own words
-moda search "user wants to cancel subscription" --mode=semantic --limit=5 --json \
+moda traces search "user wants to cancel subscription" --mode=semantic --limit=5 --json \
   | jq -r '.results[] | "\(.conversation_id) @\(.message_index)  \(.snippet)"'
 
 # Keyword: locate every tool call/result mentioning an exact identifier
-moda search "stripe.refunds.create" --mode=keyword --limit=10
+moda traces search "stripe.refunds.create" --mode=keyword --limit=10
 
 # Search, then open the top message-level hit at the exact turn (skips
 # trace-level fallback hits, which have no message_index)
-moda search "rate limit exceeded" --limit=5 --json \
+moda traces search "rate limit exceeded" --limit=5 --json \
   | jq -r 'first(.results[] | select(.message_index != null)) | "\(.conversation_id) \(.message_index)"' \
-  | xargs -r -n2 sh -c 'moda context "$0" --msg-index="$1"'
+  | xargs -r -n2 sh -c 'moda traces get "$0" --msg-index="$1"'
 ```
 
 ### Daily health check
 
 ```bash
 moda overview --days-back=1
-moda frustrations --days-back=1 --limit=5
-moda tool-failures --days-back=1
+moda detections list --family=frustration --days-back=1 --limit=5
+moda detections tools --days-back=1
 ```
 
 ### Debug a frustrated user
 
 ```bash
-moda frustrations --days-back=7 --limit=10
+moda detections list --family=frustration --days-back=7 --limit=10
 # Each row has an anchor: {conversation_id, msg_index}. Open that turn
 # (without --msg-index, context centers on the middle of the trace):
-moda context <anchor.conversation_id> --msg-index=<anchor.msg_index> --window=3
+moda traces get <anchor.conversation_id> --msg-index=<anchor.msg_index> --window=3
 ```
 
 ### Diagnose a flaky tool
 
 ```bash
-moda tool-failures
-moda tool-failure-detail <tool_name>
+moda detections tools
+moda detections tools <tool_name>
 # Pick an example conversation_id from the output
-moda context <conversation_id>
+moda traces get <conversation_id>
 ```
 
 ### Explore what users are doing
@@ -62,13 +62,13 @@ envelope, where the payload sits under `.data`.
 
 ```bash
 # Pull primary causes of recent frustrations
-moda frustrations --days-back=7 --json | jq -r '.frustrations[].primary_cause'
+moda detections list --family=frustration --days-back=7 --json | jq -r '.frustrations[].primary_cause'
 
 # Get trace IDs for a search and fetch context for all of them in one call
 moda traces --search="timeout" --limit=3 --json \
   | jq -r '.conversations[].conversation_id' \
-  | moda context --ids-from=-
+  | moda traces get --ids-from=-
 
 # Tool failure leaderboard
-moda tool-failures --json | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
+moda detections tools --json | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
 ```

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

@@ -5,12 +5,12 @@ Loaded on demand from the moda-cli skill.
 ### 1. Search messages (primary content-discovery path)
 
 ```bash
-moda search "refund flow timeout"                       # hybrid (default)
-moda search "customer asked for a refund" --mode=semantic
-moda search "SEARCH_NO_RESULTS" --mode=keyword
-moda search "checkout error" --time-range=7d --limit=10
-moda search "stripe.charges.create failed" --user-id=<id>
-moda search "Иван" --conversation-id=<id> --mode=keyword   # inside one trace
+moda traces search "refund flow timeout"                       # hybrid (default)
+moda traces search "customer asked for a refund" --mode=semantic
+moda traces search "SEARCH_NO_RESULTS" --mode=keyword
+moda traces search "checkout error" --time-range=7d --limit=10
+moda traces search "stripe.charges.create failed" --user-id=<id>
+moda traces search "Иван" --conversation-id=<id> --mode=keyword   # inside one trace
 ```
 
 Searches trace messages at message grain. Pass `--include-tool-io` to
@@ -34,7 +34,7 @@ trails ingestion (`index_freshness`); a warning says so when your
 (same as `moda traces --search`), those traces come back in `results` with
 `match_grain: "trace"`, plus `fallback.source: "traces_search"` and a warning.
 These rows have no score or message index. Open one with
-`moda audit <conversation_id>` or `moda context <conversation_id>` to find the
+`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
@@ -58,16 +58,16 @@ embedding provider is reachable, so check it before trusting semantic ranking.
 `score` scales differ per mode (see above) — branch on `search_mode`, never
 compare scores across modes.
 
-Hand the anchors straight to `moda context`:
+Hand the anchors straight to `moda traces get`:
 
 ```bash
 # Find, then read the exact turn. --json prints the bare payload; piped output
 # without it is the agent envelope, where results sit under .data.results.
-hit=$(moda search "double charge" --limit=1 --json | jq -c '.results[0] // empty')
+hit=$(moda traces search "double charge" --limit=1 --json | jq -c '.results[0] // empty')
 cid=$(echo "$hit" | jq -r '.conversation_id')
 # Trace-level fallback hits (match_grain: "trace") have no message_index.
 idx=$(echo "$hit" | jq -r '.message_index // empty')
-moda context "$cid" ${idx:+--msg-index="$idx"}
+moda traces get "$cid" ${idx:+--msg-index="$idx"}
 ```
 
 ### 3. Browse topic clusters
@@ -81,7 +81,7 @@ moda cluster-traces <node_id>                 # traces in cluster
 ### 3b. List / filter traces (structured, not semantic)
 
 Use `moda traces` to enumerate or filter by structured fields — not to
-search by meaning (use `moda search` for that). The `--search` flag here
+search by meaning (use `moda traces search` for that). The `--search` flag here
 ranks whole traces: hybrid (keyword + semantic) when embeddings exist, else
 keyword. Check `total_kind`: `candidate_pool` means results are related traces
 that may not contain the words and `pagination.total` is not a match count;
@@ -100,19 +100,19 @@ Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
 ### 4. Read a single trace
 
 ```bash
-moda context <conversation_id>                # default window around middle
-moda context <conversation_id> --msg-index=5  # center on message 5
-moda context <conversation_id> --window=3     # 3 messages each side (max 5)
-moda context <conversation_id> --msg-index=40 --window=0  # just message 40 + total_messages
-moda context <conversation_id> --metadata-only  # summary + total_messages, no messages
-moda context <conversation_id> --all          # whole trace in order, first 500 messages
-moda context <conversation_id> --all --from=500 --max-messages=500  # continue (max 5000)
+moda traces get <conversation_id>                # default window around middle
+moda traces get <conversation_id> --msg-index=5  # center on message 5
+moda traces get <conversation_id> --window=3     # 3 messages each side (max 5)
+moda traces get <conversation_id> --msg-index=40 --window=0  # just message 40 + total_messages
+moda traces get <conversation_id> --metadata-only  # summary + total_messages, no messages
+moda traces get <conversation_id> --all          # whole trace in order, first 500 messages
+moda traces get <conversation_id> --all --from=500 --max-messages=500  # continue (max 5000)
 ```
 
 `--all` returns `has_more`/`next_from`; when it stops at the cap, the warning
 prints the exact `--from` command to continue.
 
-**Several traces? Batch them in one call instead of looping `moda context`
+**Several traces? Batch them in one call instead of looping `moda traces get`
 per id.** Pass up to 25 targets as positionals or one per line with
 `--ids-from=-` (stdin) or `--ids-from=<file>`. A target is `<id>` or
 `<id>@<msg_index>` (the anchor; ids may contain `:`), and the shared flags
@@ -121,8 +121,8 @@ be JSON (`{"id":"...","msg_index":N}`), the only spelling for an id that itself
 ends in `@<digits>`.
 
 ```bash
-moda context telegram:8565459080@12 linq:c6f88988-aa@3 web:conv-9 --window=2
-printf '%s\n' telegram:8565459080@12 web:conv-9 | moda context --ids-from=- --window=1
+moda traces get telegram:8565459080@12 linq:c6f88988-aa@3 web:conv-9 --window=2
+printf '%s\n' telegram:8565459080@12 web:conv-9 | moda traces get --ids-from=- --window=1
 ```
 
 A batch returns `data.results: [{ target, ok, data | error }]` in input order,
@@ -132,29 +132,29 @@ every target failed. When the agent byte budget would overflow, the items that
 fit are returned and `remaining_targets` plus a `next_commands` entry read the
 rest. One positional id keeps the single-trace output above.
 
-`moda context` returns messages whole, with their tool calls and results. An
+`moda traces get` returns messages whole, with their tool calls and results. An
 older Moda server cuts message text, tool inputs, and tool results at 500
 characters; the response warns when that server is in use.
 `--window` is at most 5 messages per side. For the raw,
 complete picture of what was captured — every span, the parent/child hierarchy,
-tool calls, prompt/response bodies, and `gen_ai.*` attributes — use `moda audit`.
+tool calls, prompt/response bodies, and `gen_ai.*` attributes — use `moda traces spans`.
 
 ### 4b. Audit raw spans (completeness, orphans, duplicates)
 
 ```bash
-moda audit <conversation_id|trace_id>         # auto-detects OTLP trace_id vs trace ID (conversation_id)
-moda audit <trace_id> --kind=trace            # force OTLP trace_id lookup
-moda audit <conversation_id> --include-raw    # attach verbatim raw_event bodies
-moda audit <conversation_id> --include-bodies # keep prompt/response/attribute bodies
-moda audit <conversation_id> --limit=1000     # ingest rows to read (default 200, max 1000)
-moda audit <conversation_id> --cursor=<next_cursor>  # next page of a capped audit
-moda audit <id1> <id2> <id3>                  # batch: up to 25 ids, one envelope
+moda traces spans <conversation_id|trace_id>         # auto-detects OTLP trace_id vs trace ID (conversation_id)
+moda traces spans <trace_id> --kind=trace            # force OTLP trace_id lookup
+moda traces spans <conversation_id> --include-raw    # attach verbatim raw_event bodies
+moda traces spans <conversation_id> --include-bodies # keep prompt/response/attribute bodies
+moda traces spans <conversation_id> --limit=1000     # ingest rows to read (default 200, max 1000)
+moda traces spans <conversation_id> --cursor=<next_cursor>  # next page of a capped audit
+moda traces spans <id1> <id2> <id3>                  # batch: up to 25 ids, one envelope
 ```
 
 Auditing several traces? Batch the ids (positionals or `--ids-from=-|<file>`)
-instead of looping `moda audit`: the result is `data.results: [{ target, ok,
+instead of looping `moda traces spans`: the result is `data.results: [{ target, ok,
 data | error }]` with the same per-item errors and byte-budget rules as batch
-`moda context`. Ids are taken verbatim (no `@` anchors); `--cursor` pages one
+`moda traces get`. Ids are taken verbatim (no `@` anchors); `--cursor` pages one
 trace, so follow each item's `next_commands` for it.
 
 `truncated` / `has_more` at the top level say whether the audit is complete.

package/skills/moda-cli/references/signals-and-false-positives.md

@@ -7,23 +7,23 @@ Loaded on demand from the moda-cli skill.
 **Mark anything as a false positive with one command.** `--reason` (why the
 detection is wrong) is optional but recommended; marks are logged for Moda's review.
 A marked item disappears from every list and count (`moda problems`,
-`hallucinations`, `laziness`, `tool-failures`, problem evidence, the dashboard);
-`--undo` brings it back.
+`detections list`, `detections tools`, problem evidence, the dashboard);
+`--verdict=clear` brings it back.
 
 ```bash
-moda false-positive problem <problem_id> --reason="two unrelated tools"   # dismiss: hidden at once
-moda false-positive problem-detection <problem_id> --conversation-id=<id> \
+moda review problem <problem_id> --reason="two unrelated tools"   # dismiss: hidden at once
+moda review problem-detection <problem_id> --conversation-id=<id> \
   --attribution-id=<uuid> --reason="refund was approved"                  # one piece of evidence
-moda false-positive quote <conversation_id> --family=frustration --turn=3 \
+moda review quote <conversation_id> --family=frustration --turn=3 \
   --quote="this is useless lol" --reason="user was joking"               # one user quote
-moda false-positive tool <conversation_id> --tool=send_invoice \
+moda review tool <conversation_id> --tool=send_invoice \
   --tool-use-id=<tool_use_id> --reason="retried upstream"               # one failing tool call
-moda false-positive laziness <conversation_id> --reason="reload is expected"
-moda false-positive hallucination <conversation_id> --reason="price came from the tool result"
-moda false-positive custom-signal <signal_id> --conversation-id=<id> --reason="refund was approved"
-moda false-positive laziness <conversation_id> --undo                    # remove a mark (any kind but problem)
-moda false-positives                                                     # every current mark (--kind=tool, --all, --limit)
-moda false-positives <conversation_id>                                   # marks + problem reviews on a trace
+moda review laziness <conversation_id> --reason="reload is expected"
+moda review hallucination <conversation_id> --reason="price came from the tool result"
+moda review custom-signal <signal_id> --conversation-id=<id> --reason="refund was approved"
+moda review laziness <conversation_id> --verdict=clear                    # remove a mark (any kind but problem)
+moda reviews list                                                     # every current mark (--kind=tool, --all, --limit)
+moda reviews list <conversation_id>                                   # marks + problem reviews on a trace
 ```
 
 What each flag does downstream:
@@ -36,12 +36,12 @@ What each flag does downstream:
 | `quote`, `tool`, `laziness`, `hallucination` | Audit only: recorded for review, never fed back to the detectors |
 
 Find targets with the read commands: `--family`, `--turn` and `--quote` verbatim
-from a `user_quotes` entry in `moda emotions`; a failing call's `tool_use_id` (or `msg_index` when it has none) from
-`moda tool-failure-detail <tool_name>`;
-laziness traces from `moda laziness`; hallucination traces from
-`moda hallucinations`; custom-signal hits from `moda trace-signals` or
-`moda signal <id> --detections`; problem evidence ids from
-`moda problem <id> --evidence`.
+from a `user_quotes` entry in `moda detections list --family=emotion`; a failing call's `tool_use_id` (or `msg_index` when it has none) from
+`moda detections tools <tool_name>`;
+laziness traces from `moda detections list --family=laziness`; hallucination traces from
+`moda detections list --family=hallucination`; custom-signal hits from `moda detections list --family=custom_signal` or
+`moda detections list --family=custom_signal --signal-id=<id>`; problem evidence ids from
+`moda problems get <id> --evidence`.
 
 **Custom signals** are tenant-defined behaviors (pass/fail criteria) judged on
 every trace. Read them, then label hits so each signal has labelled examples:
@@ -49,9 +49,9 @@ every trace. Read them, then label hits so each signal has labelled examples:
 ```bash
 moda signals                                          # every signal: criteria, status, 7-day judged/matched
 moda signal <signal_id>                               # one signal's summary
-moda signal <signal_id> --detections --days-back=30   # recent hits (limit 1–20, --offset to page)
-moda trace-signals <conversation_id>                  # signal hits on one trace
-moda signal-label <signal_id> --conversation-id=<id> --label=does_not_fit \
+moda detections list --family=custom_signal --signal-id=<signal_id> --days-back=30   # recent hits (limit 1–20, --offset to page)
+moda detections list --family=custom_signal --conversation-id=<conversation_id>                  # signal hits on one trace
+moda review custom-signal <signal_id> --conversation-id=<id> --verdict=false_positive \
   --note="refund was approved" --msg-index=<anchor_msg_index>
 ```
 
@@ -62,18 +62,18 @@ message, and always give a `--note` when rejecting. Labels are throttled to 10
 per minute per API key and are never retried automatically.
 
 **Problem detections** (the dashboard's flag on problem evidence) are reviewed with
-`detection-review`. A `false_positive` drops the detection out of
-`moda problem <id> --evidence` and is fed back to the problem reader; `clear`
+`moda review problem-detection`. A `false_positive` drops the detection out of
+`moda problems get <id> --evidence` and is fed back to the problem reader; `clear`
 undoes an earlier review.
 
 ```bash
-moda detection-reviews <conversation_id>              # problem detections on a trace + review state
-moda detection-review <problem_id> --conversation-id=<id> \
+moda reviews list <conversation_id> --kind=problem-detection              # problem detections on a trace + review state
+moda review problem-detection <problem_id> --conversation-id=<id> \
   --attribution-id=<uuid> --verdict=false_positive --note="retry was expected"
-moda detection-review <problem_id> --conversation-id=<id> \
+moda review problem-detection <problem_id> --conversation-id=<id> \
   --attribution-id=<uuid> --verdict=clear             # undo
 ```
 
-`attribution_id` comes from `moda detection-reviews <conversation_id>` or
-`moda problem <problem_id> --evidence`. Prefer `detection-review` over
-`problem-feedback --action=flag_attribution` for a single wrong detection.
+`attribution_id` comes from `moda reviews list <conversation_id> --kind=problem-detection` or
+`moda problems get <problem_id> --evidence`. Prefer `review problem-detection` over
+`problems feedback --action=flag_attribution` for a single wrong detection.

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

@@ -14,9 +14,9 @@ Loaded on demand from the moda-cli skill.
   mode prints prose to stderr. Check the exit code before claiming success.
 - An unknown trace, problem, or cluster id exits 1 with
   `errors[0].code: "not_found"`; it is not an empty success.
-- `moda world-state` returns success with a warning when state is missing.
+- `moda traces state` returns success with a warning when state is missing.
   This can mean an unknown trace or a real trace without generated state.
-  Use `moda context <id> --metadata-only` to check whether the trace exists.
+  Use `moda traces get <id> --metadata-only` to check whether the trace exists.
 - If the JSON has `"conversations": []` or `"frustrations": []`, the call
   worked but the time window is empty. Widen the window once
   (`--days-back` on detection commands, `--time-range` on `traces`,
@@ -36,7 +36,7 @@ save it with `moda auth login --api-key`.
 **`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`).
-`errors[0].cause` names the listing command: `moda search`/`moda traces`,
+`errors[0].cause` names the listing command: `moda traces search`/`moda traces`,
 `moda problems`, `moda clusters`. A tool name with no failures in the window
 returns an empty result with a warning instead.
 
@@ -52,7 +52,7 @@ warning that gives the `--all` command for a wider slice.
 Widen the window: try `--days-back=30` or `--time-range=30d`. Confirm with
 `moda overview` that data exists in the tenant at all.
 
-**`moda search` returns nothing, or semantic feels like keyword**
+**`moda traces search` returns nothing, or semantic feels like keyword**
 The default `--time-range` is `all`, so an empty result usually means the
 phrasing, not the window: try a shorter phrase or the exact identifier with
 `--mode=keyword`, and add `--include-tool-io` for strings that only appear in