@moda-ai/cli 1.38.0 → 1.39.0

package/dist/{harness-n2xgzz31.js → harness-191xt7bq.js}

@@ -42,8 +42,8 @@ import {
   writeHarnessAnalyzeResult,
   writeHarnessArtifacts,
   writeHumanProgress
-} from "./cli-07tv75te.js";
-import"./cli-q79sq80a.js";
+} from "./cli-xsmsjny3.js";
+import"./cli-rp912ypf.js";
 import"./cli-0v6na3yp.js";
 export {
   writeHumanProgress,

package/dist/{harness-github-actions-qz5d22rz.js → harness-github-actions-1qt4sgxd.js}

@@ -1,7 +1,7 @@
 import {
   buildSourceSnapshot
-} from "./cli-07tv75te.js";
-import"./cli-q79sq80a.js";
+} from "./cli-xsmsjny3.js";
+import"./cli-rp912ypf.js";
 import"./cli-0v6na3yp.js";
 
 // src/harness-github-actions.ts

package/dist/{index-hwfe7gs8.js → index-qgc37efj.js}

@@ -3,7 +3,7 @@ import {
   initPrompts,
   runPromptSync,
   runSkillSync
-} from "./cli-3kcy61fr.js";
+} from "./cli-a7ypptsf.js";
 import {
   codingAgentDisplayName,
   describeCodingAgentEvent,
@@ -22,7 +22,7 @@ import {
   runHarnessCommand,
   startRemoteAnalyze,
   stripAnsi
-} from "./cli-07tv75te.js";
+} from "./cli-xsmsjny3.js";
 import {
   bundledSkillsDir,
   installIntegrationSkill,
@@ -34,14 +34,14 @@ import {
 } from "./cli-ssfq84k5.js";
 import {
   selectTenantAndCreateKey
-} from "./cli-k38j2fpq.js";
+} from "./cli-yy8fwg1a.js";
 import {
   ConnectCodeError,
   connectWithCode,
   loadAuthSession,
   loadToken,
   login
-} from "./cli-kegd748v.js";
+} from "./cli-dyeywy9d.js";
 import {
   CliAuthError,
   CliInputError,
@@ -49,7 +49,7 @@ import {
   createCommandContext,
   resolveIngestUrl,
   resolveModaBaseUrl
-} from "./cli-q79sq80a.js";
+} from "./cli-rp912ypf.js";
 import"./cli-0v6na3yp.js";
 
 // src/init/index.ts

package/dist/prompt-source-mcp.js

@@ -5,8 +5,8 @@ import {
   inspectCodeSelectors,
   inspectPythonSelectors,
   safePromptEvidencePath
-} from "./cli-07tv75te.js";
-import"./cli-q79sq80a.js";
+} from "./cli-xsmsjny3.js";
+import"./cli-rp912ypf.js";
 import {
   __commonJS,
   __toESM

package/dist/{provision-64c2n9aw.js → provision-gabtks29.js}

@@ -1,15 +1,15 @@
 import {
   selectTenantAndCreateKey
-} from "./cli-k38j2fpq.js";
+} from "./cli-yy8fwg1a.js";
 import {
   loadAuthSession
-} from "./cli-kegd748v.js";
+} from "./cli-dyeywy9d.js";
 import {
   CliAuthError,
   resolveIngestUrl,
   resolveModaBaseUrl,
   stringOption
-} from "./cli-q79sq80a.js";
+} from "./cli-rp912ypf.js";
 import"./cli-0v6na3yp.js";
 
 // src/provision.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-09-28T05:22:37.701Z",
-  "cli_version": "1.38.0",
+  "bundled_at": "2026-10-05T22:35:48.948Z",
+  "cli_version": "1.39.0",
   "skills": [
     {
       "id": "integration-cloudflare-think",

package/skills/moda-cli/SKILL.md

@@ -39,11 +39,14 @@ Activate this skill when the user wants to:
 - List/filter traces by user, environment, cluster, outcome, or time
 - Manage code-first prompt versions when the user explicitly asks for prompt
   sync, prompt status, or prompt promotion
+- Push their prompts, skills, and tool definitions to Moda without a repo
+  scan — `moda registry push` (section 7b)
 
 **Do not** activate for: writing code that calls the Moda Data API directly
 (use the API docs instead), changing application instrumentation unless the
 user explicitly asks for SDK setup, or modifying prompt registry state unless
-the user specifically asked for `moda prompts sync` or `moda prompts promote`.
+the user specifically asked for `moda prompts sync`, `moda prompts promote`, or
+`moda registry push`.
 
 ## Required inputs
 
@@ -402,6 +405,45 @@ Treat an answer as degraded if **any** of these hold:
 - `data.degraded === true` (for `ask`; equivalently `data.source === "local_fallback"`), **or**
 - `status === "degraded"`.
 
+### Large outputs and unknown flags
+
+- **Byte limit.** In `--agent` mode, envelopes over 200 KB are bounded
+  *without* breaking their shape: long text fields (usually embedded
+  transcripts) are shortened with `… [truncated N chars]`, then trailing list
+  items are dropped. `warnings[]` and `truncation.data` say exactly what was
+  cut (`dropped_items`, `complete: false`). `data` is still normal JSON, so
+  `data.frustrations[0].conversation_id` keeps working. For complete results,
+  page with a smaller `--limit` and `--offset`, or rerun with `--json` (no byte
+  limit).
+- **Unknown flags fail.** A flag the command doesn't take (a typo, or a
+  filter it lacks) exits `1` with the valid flag list and a "did you mean",
+  instead of being silently ignored. Stray arguments on commands that take
+  none fail the same way.
+- **`--dry-run` is only accepted where it's implemented** (`sync`, `registry`,
+  `harness`, `prompts sync`, `skills sync`). Anywhere else it fails **before
+  anything is sent**. It is never silently ignored, so a "preview" can't
+  perform a real write.
+- **Unknown profiles fail.** `--profile=<name>` or `MODA_PROFILE` naming a
+  profile that doesn't exist exits `1` instead of falling back to another
+  profile's key and tenant. Time windows differ by command (below).
+
+#### Time-window flags by command
+
+A command rejects the window flag it doesn't take, and out-of-range values
+fail instead of being clamped.
+
+| Flag | Commands | Allowed values | Default |
+| --- | --- | --- | --- |
+| `--days-back=N` | `overview`, `investigate`, `failures`, `ask`, `frustrations`, `emotions`, `laziness`, `hallucinations`, `tool-failures`, `tool-failure-detail`, `signal --detections` | whole number 1–90 | 7 (`signal`: server default) |
+| `--days-back=N` | `problems`, `problems remainder` | whole number 1–90 | 30 |
+| `--days-back=N` | `problem-impact` | `all`, 1, 3, 7, 30, 90 | 7 |
+| `--time-range=R` | `traces`, `search`, `clusters` | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d` | `all` |
+| `--window=W` | `users`, `user` | `24h`, `7d`, `30d`, `90d` | `30d` |
+
+`--window=N` on `context`, `frustrations --include-window` and
+`tool-failure-detail --include-window` is a message half-width (1–5), not a
+time window.
+
 ### Schema introspection
 
 ```bash
@@ -458,6 +500,17 @@ Flags: `--mode=keyword|semantic|hybrid` (default `hybrid`), `--user-id`,
 `--time-range` (`all|1h|3d|7d|24h|30d|90d`, default `all`), `--limit` (1–100,
 default 20). The query is a positional arg (max 500 chars).
 
+**Fallback.** If message-level search finds nothing but whole traces match
+(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
+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
+itself fails, you get a warning, not a silent empty result. Either way, zero
+results does not prove the topic never came up.
+
 Choosing a mode:
 
 - `hybrid` (default) — best general recall; fuses keyword + semantic. Use it
@@ -525,7 +578,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 --include-window", "purpose": "Inspect tool failure examples and trace anchors.", "mutability": "read", "requires_approval": false }
+    { "command": "moda tool-failure-detail 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": [],
@@ -533,8 +586,12 @@ Data API fallback. Abbreviated envelope:
 }
 ```
 
-`moda investigate` also accepts scoping flags (`--tool`, `--run`,
-`--trace`; legacy alias `--conversation`) to focus the ranking on one signal.
+`moda investigate` also accepts `--days-back=N` and scoping flags: `--tool`
+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.
+`moda failures` is the tool-failures-only view.
 
 After reporting the top behavioral failure and the harness layer it routes to
 (prompt, tool, skill, eval, or memory), close with one line: the Moda team
@@ -552,13 +609,16 @@ 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 is a
-plain keyword filter over trace text.
+search by meaning (use `moda 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;
+`matches` means a literal keyword match set.
 
 ```bash
 moda traces --user-id=<id> --time-range=7d
 moda traces --cluster-id=<node_id> --environment=production
-moda traces --search="timeout" --limit=20           # keyword filter only
+moda traces --search="timeout" --limit=20           # ranked trace search
 ```
 
 Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
@@ -571,8 +631,13 @@ Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
 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> --all          # whole trace in order, first 500 messages
+moda context <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.
+
 `moda context` is turn-windowed (≤5 turns, deduped, no tool spans). 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`.
@@ -583,8 +648,14 @@ tool calls, prompt/response bodies, and `gen_ai.*` attributes — use `moda audi
 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> --limit=1000     # ingest rows to read (default 200, max 1000)
 ```
 
+`truncated` / `has_more` at the top level say whether the audit is complete.
+A full `--limit` page of ingest rows (or a server span cap) sets both, and a
+warning plus `next_commands` give the rerun; for very large traces audit one
+OTLP trace at a time (`summary.trace_ids`, `--kind=trace`).
+
 Returns the raw, NON-deduped span set from the Layer-0 store (`events_raw`), so
 nothing is collapsed. Use it to verify capture completeness: the `summary` gives
 `total_spans`, `by_type` (llm/tool/agent/…), plus `orphan_count` (spans whose
@@ -600,8 +671,19 @@ Moda captured every LLM/tool call for a trace.
 moda frustrations                             # last 7 days
 moda frustrations --days-back=14 --limit=20
 moda frustrations --include-window --window=1 --limit=5
+moda emotions --family=frustration --user-id=<id>        # one end user
+moda emotions --conversation-id=<id>                     # every family, one trace
 ```
 
+`--user-id` and `--conversation-id` work on `emotions` and `frustrations`, and
+scope *every* figure: summary, breakdown, list and total. `--limit` is 1–20 on
+both, and on `hallucinations` and `tool-failure-detail`. Page with `--offset`.
+`frustrations` reads the same data as `emotions --family=frustration` and the
+dashboard, in the legacy field names: `frustrated_count` = `by_family.frustration`
+(detected traces), `total_analyzed` = `conversations_analyzed`. In `emotions`,
+`pagination.total` counts detected **plus** at-risk rows (`is_detected: false`,
+`risk_score` >= 0.5); use `pagination.detected` / `pagination.at_risk` for the split.
+
 Each result includes an inline trace snippet, user quotes, trajectory,
 signal breakdown (exasperation, profanity, anger, sarcasm, giving_up, insult),
 and primary cause.
@@ -626,7 +708,7 @@ half-width; `--window=1` ⇒ 3 messages total (anchor ± 1), the canonical
 ```bash
 moda tool-failures                            # which tools are breaking
 moda tool-failure-detail <tool_name>          # subtype breakdown + examples
-moda tool-failure-detail search --subtype=SEARCH_NO_RESULTS --limit=10
+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
 ```
 
@@ -638,9 +720,22 @@ tool call — reference `anchor.conversation_id` and `anchor.msg_index`
 directly instead of matching by `tool_use_id` against the trace.
 `no_anchor: true` means no anchor could be derived.
 
-Pass `--include-window` to attach a `window` field per row with the message
-slice centered on the anchor. `--window=N` (1–5, default `1`) is the
-half-width; `--window=1` ⇒ 3 messages total (anchor ± 1).
+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
+the untrimmed window. `--compact` (same as `--include-window=false` or
+`--no-include-window`) drops `conversation` and keeps the anchor and
+`context_command`.
+
+Pass `--include-window` to attach a `window` field per row (instead of
+`conversation`) with the message slice centered on the anchor. `--window=N`
+(1–5, default `1`) is the half-width; `--window=1` ⇒ 3 messages total
+(anchor ± 1).
+
+Examples default to `--limit=5` (max 20). Strings inside `examples[]` longer
+than 300 characters are cut, and a warning says so; read the full text with
+the row's `context_command`. Agent output lists the 20 most frequent
+`subtypes` (`subtypes_total` has the full count); `--json` lists all.
 
 ### 7. Prompt management
 
@@ -649,7 +744,7 @@ Use these only when working on the code-first prompt registry.
 ```bash
 moda prompts init                               # create .moda/prompts.yml
 moda prompts status                             # read-only local status
-moda prompts diff                               # read-only local diff/status
+moda prompts diff                               # only changed/new/deleted since last sync
 moda prompts sync                               # upload changed prompt versions
 moda prompts sync --watch                       # sync when local prompt hashes change
 moda prompts promote support.triage --label=prod --version=pver_abc123
@@ -659,6 +754,17 @@ moda prompts promote support.triage --label=prod --version=pver_abc123
 `.moda/prompts.lock.json`. `promote` moves a remote `dev`, `staging`, or
 `prod` label to an existing version.
 
+`prompts ab` and `prompts propose --gate` run paid replays. Before sending
+anything they compute planned playouts (cases × seeds × 2 arms) and print it
+(`plannedPlayouts`). Above 200, or when an existing set's case count can't be
+read, they fail (exit 1) with the number and the exact command to re-run with `--yes`.
+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;
+`--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`,
+`google/gemini-2.5-pro` unless you pass `--allow-any-model`.
+
 Runtime code should render synced prompts through the SDK:
 
 ```typescript
@@ -677,6 +783,74 @@ Do not copy prompt text from the dashboard into source code. The repo prompt
 files are the source of truth; the dashboard is for visibility, usage, labels,
 and future evals.
 
+### 7b. Push prompts, skills, and tools without a repo scan (`moda registry`)
+
+Use when the user wants their prompts, skills, and tools visible in Moda but
+cannot (or does not want to) connect the GitHub App or run `moda harness
+analyze`. This fills the prompt, skill, and tool registries only. It does not
+create the harness graph (agents and how they connect), which still comes from
+`moda harness analyze`, the GitHub App, or an approved report via
+`moda harness sync --from-report`. **You** are the analyst: read the codebase you already have access
+to, write one manifest, and push exactly what it lists. Nothing else in the
+repo is uploaded.
+
+```bash
+moda registry template --out=.moda/registry.json   # starter manifest
+# ...fill in .moda/registry.json from the codebase...
+moda registry validate                              # local only, no network
+moda registry push --dry-run                        # server-side preview, writes nothing
+moda registry push                                  # upload
+```
+
+Manifest (`moda_registry.v1`; every section optional, ≤500 entries each):
+
+```json
+{
+  "schema": "moda_registry.v1",
+  "prompts": [
+    { "key": "support.triage", "name": "Triage", "description": "...",
+      "content": "You are ...", "sourcePath": "src/agents/triage.ts" },
+    { "key": "support.reply", "file": "prompts/reply.md" }
+  ],
+  "skills": [
+    { "key": "refund-policy", "description": "...", "file": ".claude/skills/refund-policy/SKILL.md" }
+  ],
+  "tools": [
+    { "schema": { "name": "lookup_customer", "description": "...",
+      "parameters": { "type": "object", "properties": { "email": { "type": "string" } } } } }
+  ]
+}
+```
+
+- **Prompts:** `key` plus one of `content`, `file`, `systemPrompt`, or
+  `messages`. Optional `name`, `description`, `category`, `variables`,
+  `modelConfig`, `toolRefs`, `responseSchema`, `sourcePath`. Use the key the
+  runtime passes to `Moda.prompt(key)` when there is one. Copy each prompt's
+  text **verbatim**: for templated prompts, keep the template string, not a
+  rendered example. Re-pushing the same text is a no-op; changed text adds a
+  new version.
+- **Skills:** `key` (letters, digits, `_`, `-`) plus `skillMd` or `file` (full
+  SKILL.md). Pushed skills are *local* by default. Set `"live": true`, or pass
+  `--live`, to include them in the served skill surface. Leaving `live` out
+  never demotes a skill that is already live.
+- **Tools:** an OpenAI function `schema` (a wrapped
+  `{"type":"function","function":{...}}` is accepted), plus optional
+  `isActive`. Copy names and parameter schemas exactly as the agent registers
+  them with the model. Tools are upserted by name and never overwrite
+  MCP-server-managed tools (those report `skipped`).
+- `file` paths are relative to the directory you run the command from and must
+  stay inside it (symlinks included).
+
+`push` needs an API key. `push --dry-run` without one only validates locally
+(status `validated`). Each section goes to its own endpoint and reports
+`sections[].status` (`synced`, `dry_run`, `validated`, `skipped`, or `error`).
+If any section fails, `push` exits `1`, lists the failures in `errors[]`, and
+still pushes the other sections. The whole manifest is validated before any
+request, with every error listed at once. Unknown fields and wrong types are
+rejected, matching what the server accepts. Skill keys are stricter than the
+server (letters, digits, `_`, `-`) because they double as `.claude/skills/<key>/`
+directory names.
+
 ### 8. Fixing detected Problems (`moda fix` — a fix with proof)
 
 Moda turns detected Problems into **Fixes**: a routed candidate change plus a
@@ -716,6 +890,16 @@ moda fix mark-applied <fix_id> --note="…"    # tool/skill/no-PR path: confirm
 moda fix dismiss <fix_id> --reason="why"     # reject (feeds problem feedback)
 ```
 
+Every gate replays the holdout, so `moda fix verify` refuses to re-gate a fix
+whose last verdict landed less than 10 minutes ago (`gateResult.completedAt`;
+verdicts without that stamp have no cooldown) and sends nothing. The error
+shows the exact command with `--yes` to gate anyway. Pass `--yes` only when you
+changed the candidate since that verdict. `moda fixes drive` advances at most
+`--max-fixes` fixes per run (default 3, max 10; fixes already `GATING` count
+toward the cap; each run takes the least-recently-driven fixes first), lists the rest in
+`data.skipped`, and exits 3 until a re-run has driven them. `moda fixes
+draft-batch` drafts 5 fixes unless you pass `--limit` (max 25).
+
 **`moda fix verify` exit codes are the contract — branch on them:**
 
 | Exit | Meaning | How to treat it |
@@ -824,6 +1008,32 @@ moda detection-review <problem_id> --conversation-id=<id> \
 `moda problem <problem_id> --evidence`. Prefer `detection-review` over
 `problem-feedback --action=flag_attribution` for a single wrong detection.
 
+### 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`, `prompts promote|ab|propose`, and `fix`/`fixes`. 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) |
+| 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) |
+| 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>` |
+| Custom signals: find matches | `moda signals search <id>`, `search-status <id> <search_id>`, `search-stop <id> <search_id>`, `preview --file=detector.json` |
+| Prompts registry | `moda prompts list [--label --search]`, `show <key>`, `proposals <key>`, `usage <key>`, `replay-runs <key>`, `decide <key> <proposal_id> --action=merge\|reject\|reopen` |
+| Skills library | `moda skills list`, `show <key>`, `policy <key> --live\|--local` |
+| Harness pages | `moda harness list`, `show <id>`, `versions <id>`, `diff <id> --from=… --to=…` |
+| Fixes inbox | `moda fixes`, `moda fix <id>`, `fix start <problem_id>`, `fix dismiss` … |
+
+Not available to API keys on purpose (a human does these in the dashboard):
+members/invites/roles, API-key minting, billing, provider credentials,
+OAuth connections (Slack/Linear/GitHub), alert rules that message people,
+and archiving an active custom signal (pause it, or delete a draft).
+
 ## Common workflow recipes
 
 ### Find where something happened (search → context)
@@ -878,17 +1088,20 @@ moda cluster-traces <node_id>
 
 ### One-liner chains with jq
 
+Pass `--json` when piping: piped output otherwise defaults to the agent
+envelope, where the payload sits under `.data`.
+
 ```bash
 # Pull primary causes of recent frustrations
-moda frustrations --days-back=7 | jq -r '.frustrations[].primary_cause'
+moda frustrations --days-back=7 --json | jq -r '.frustrations[].primary_cause'
 
 # Get trace IDs for a search and fetch context for each
-for id in $(moda traces --search="timeout" --limit=3 | jq -r '.conversations[].id'); do
+for id in $(moda traces --search="timeout" --limit=3 --json | jq -r '.conversations[].conversation_id'); do
   moda context "$id"
 done
 
 # Tool failure leaderboard
-moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
+moda tool-failures --json | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
 ```
 
 ## Feedback: help us improve
@@ -981,13 +1194,13 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda 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 with evidence + next commands |
+| `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) |
-| `moda frustrations` | User frustration detections with evidence (legacy single-family; prefer `emotions`) |
-| `moda emotions` | Multi-family emotion detections: frustration, sadness, confusion, anxiety, trust, positive (`--family=F`, limit 1–20) |
+| `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 |
@@ -1007,13 +1220,19 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda signal-label <signal_id>` | Write: `--conversation-id`, `--label=fits\|does_not_fit` (false positive), optional `--note`, `--msg-index`/`--msg-dedup-token` |
 | `moda step-scores <conversation_id>` | Graph-PRM step scores: per-segment curves, first bad step, rollup |
 | `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 failures` | Production failures worth fixing first |
+| `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 |
 | `moda prompts status` | Read-only local prompt status |
-| `moda prompts diff` | Read-only local prompt diff/status |
+| `moda prompts diff` | Read-only: only prompts changed/new/deleted since last sync (hash-level, not a text diff) |
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
+| `moda registry template\|validate\|push` | Push prompts, skills, and tools from one agent-written manifest (`--file`, `--dry-run`, `--live`); no repo scan |
+| `moda users` / `moda user <id>` | End users with health/activity; one user's profile |
+| `moda problem-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 skills list\|show\|policy` / `moda harness list\|show\|versions\|diff` | Skill library and synced harnesses |
 | `moda fixes` | Ranked queue of Fixes ("a fix with proof"); `--status=S`, `--limit=N`, `--cursor=TOKEN` |
 | `moda fix <fix_id>` | One Fix: status + gate result; `--packet` prints `moda.fix_packet.v1` and writes tool/skill candidates under `.moda/fixes/<ref>/`; `--wait` drives a running pipeline to rest |
 | `moda fix start <problem_id>` | Draft a Fix from a Problem (`--type=auto\|prompt`); `--wait` drives scope → propose → gate |