@moda-ai/cli 1.55.19 → 1.55.21

package/skills/moda-cli/references/replays-and-registry.md

@@ -0,0 +1,173 @@
+# Replays and the harness registry
+
+Loaded on demand from the moda-cli skill.
+
+### 7a. Check a replay verdict (`moda replays`)
+
+Use after `prompts ab`, `prompts propose --gate`, or a dashboard replay when
+you need to see *why* an arm passed or failed. Read-only; no replay spend.
+
+```bash
+moda replays sets --json                              # set ids
+moda replays runs <set_id> --limit=5 --json           # newest runs, every status
+moda replays run <set_id> <run_id> --json             # per-case + per-seed verdicts
+moda replays playouts <set_id> <run_id> --json        # one row per case x arm x seed
+moda replays playouts <set_id> <run_id> --case=<case_id> --arm=proposed --seed=1 --transcript --json
+moda replays playout <set_id> <run_id> <playout_id> --json
+```
+
+`run` returns `results[]` (one per case × arm × seed: `pass`, `abstained`,
+`coverageReason`, `score`, `rationale`, `criteria[]`) next to the per-case
+majority in `cases[]`. `arm=prod` is the baseline and `arm=proposed` the
+candidate. An `abstained: true` row is not a verdict: the pair hit a replay
+coverage hole and is excluded from pass counts.
+
+A playout's `transcript.events[]` holds the simulated user and agent messages
+and every tool call with its `input`, the `output` the replay served, and
+`provenance.source`: `replay_runtime` (compiled mock over the case's recorded
+source state), `agent_tool_simulator` (LLM simulator grounded in recorded
+receipts; `simulator.model`), `counterfactual_reconstruction`, or
+`generic_handler`. `provenance.errorSubtype` such as `missing_source_state`
+marks an unservable call. `judge` is the judgement stored with the playout and
+`verdict` the stored eval row (null when `seed` is null, which happens on
+older runs whose graphs cannot be matched to a seed).
+
+Limits: `--transcript` pages at most 10 playouts (`--limit` default 50, max
+200 without it); text and tool JSON are clipped at `--max-chars` (default
+4000, max 32000) and `transcript.truncated.fields` counts the clipped fields.
+Page with `--cursor=<nextCursor>`. Playouts exist only for runs whose
+playouts were captured; `playoutCount: 0` on `run` means there is no
+transcript to read.
+
+### 7b. Register the harness for replays (`moda registry`)
+
+Use when the user wants their prompts, skills, tools, or agent wiring in Moda
+so replays rebuild their harness faithfully, without the GitHub App or `moda
+harness analyze`. **You** are the analyst: read the codebase you already have,
+write one manifest, and push exactly what it lists. Nothing else in the repo is
+uploaded. For a full guided pass (inventory, prompt switching, context,
+attribution, and verification), run `moda registry prompt` and follow the
+brief it prints.
+
+```bash
+moda registry prompt                                # the step-by-step brief for this job
+moda registry template --out=.moda/registry.json   # starter manifest (moda_registry.v2)
+# ...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
+moda registry status                                # what is registered (harness version)
+moda registry coverage --days=7                     # production traces vs the registry
+moda registry log                                   # history: one commit per push
+moda registry show <commit|working>                 # a commit's file diffs / changes since the last push
+```
+
+Every successful `push` records a registry **commit**: the whole registry
+(prompts, tools, skills, agents, harness settings) snapshotted as files, with
+your repo's git SHA, branch, and dirty flag. Pass `--message="..."` to label
+it. The dashboard **Registry** page shows these commits git-style: a log,
+per-file diffs, a file browser, and uncommitted changes made outside a push
+(dashboard edits, MCP discovery, `moda prompts sync`).
+
+Manifest (`moda_registry.v2`; `moda_registry.v1` with only prompts, skills, and
+tools still works; every section optional, ≤500 entries in prompts, skills, and tools):
+
+```json
+{
+  "schema": "moda_registry.v2",
+  "prompts": [
+    { "key": "support.triage", "file": "prompts/triage.md" },
+    { "key": "support.billing", "content": "You handle billing for {{company_name}}..." }
+  ],
+  "skills": [
+    { "key": "refund-policy", "file": ".claude/skills/refund-policy/SKILL.md" }
+  ],
+  "tools": [
+    { "schema": { "name": "lookup_customer", "description": "...",
+      "parameters": { "type": "object", "properties": { "email": { "type": "string" } } } } }
+  ],
+  "runtime": { "framework": "openai-agents", "maxToolRoundsPerTurn": 6, "skillLoading": "tool" },
+  "agents": [
+    { "key": "triage", "entry": true, "prompt": "support.triage",
+      "model": { "id": "openai/gpt-5.1", "temperature": 0.2, "maxTokens": 1024 },
+      "tools": ["lookup_customer"],
+      "handoffs": [{ "to": "billing", "tool": "transfer_to_billing" }],
+      "match": { "agentNames": ["TriageAgent"] } },
+    { "key": "billing", "prompt": "support.billing", "skills": ["refund-policy"] }
+  ],
+  "routing": { "strategy": "handoff", "default": "triage" },
+  "context": [
+    { "key": "company", "variable": "company_name", "source": "static", "value": "Acme" },
+    { "key": "today", "variable": "current_date", "source": "clock", "format": "date" }
+  ]
+}
+```
+
+- **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. Replays load the skills an agent
+  lists in `agents[].skills`, whether or not they are 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`).
+- **Agents:** one per distinct prompt, tool set, or model. Fields: `key`,
+  `name`, `description`, `entry`, `prompt` (prompt key), `model` (`id`,
+  `provider`, `temperature`, `maxTokens`, `topP`, `reasoningEffort`), `tools`
+  (tool names), `skills` (skill keys), `handoffs` (`to`, `tool`,
+  `description`), `subagents` (`agent`, `tool`; the tool must also be in
+  `tools`), `context` (context keys), `maxToolRoundsPerTurn`,
+  `responseSchema`, `match` (`agentNames` as they appear in traces,
+  `promptKeys`).
+- **Routing (prompt switching):** `strategy` is `single`, `handoff`, `router`,
+  `rules`, or `trace_attribute`; `default` is an agent key; put code-level
+  rules in `notes`. Replay runs the agent named on the replayed turn's trace
+  (agent name, then prompt key), else `default`, else the `entry` agent. When
+  the replayed model calls a handoff tool, replay switches to the target
+  agent's prompt, tools, model, and params.
+- **Context:** what the runtime injects. `source` is `static` (with `value`),
+  `clock` (`format`: date, datetime, or iso; replay uses the source
+  conversation's time), or `trace`, `memory`, `retrieval`, `tool`, or
+  `unknown`. Those last ones are reported as unresolved in replay fidelity,
+  never invented. `target` is `prompt_variable` (needs `variable`) or
+  `system_append`.
+- **Runtime:** `framework`, `language`, `maxToolRoundsPerTurn`,
+  `parallelToolCalls`, `history` (`strategy`, `maxMessages`, `maxTokens`),
+  and `skillLoading` (`tool`, `system_prompt`, or `none`).
+- **MCP servers:** `name`, `transport`, `url` or `command`, `tools`, and
+  `description`, with no credentials. List their tools in `tools[]` too.
+- `file` paths are relative to the directory you run the command from and must
+  stay inside it (symlinks included).
+
+**Traces must name the agent.** For per-turn prompt switching, each LLM call
+should carry `gen_ai.agent.name` (or `moda.agent_name`; with the Vercel AI SDK
+use `experimental_telemetry.metadata["moda.agent_name"]`; `agent_name` on
+`/v1/ingest`), set to an agent `key` or one of its `match.agentNames`. It
+should also carry `moda.prompt_key` / `moda.prompt_version_id`. Only add these
+to application code when the user asks for it or approves the diff.
+`moda registry coverage` shows how many recent calls resolve to a registered
+agent, which agent names, prompt keys, and tools are unregistered, and which
+agents were never seen.
+
+`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`).
+The harness sections (`runtime`, `agents`, `routing`, `context`, and
+`mcpServers`) are pushed last, as one versioned document. Re-pushing an
+unchanged one reports `unchanged`. 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. `warnings[]` names agent references to prompts, tools, or skills that
+the manifest doesn't define; they must already exist in Moda. 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.

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

@@ -0,0 +1,180 @@
+# Search, traces, context, and audit
+
+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
+```
+
+Searches trace messages at message grain. Pass `--include-tool-io` to
+also search **tool calls and tool results** (tool name, input arguments, and
+output previews), so it finds where an agent *did* something, not just where
+it talked about it — tool-IO search is opt-in, not the default.
+
+Flags: `--mode=keyword|semantic|hybrid` (default `hybrid`), `--user-id`,
+`--conversation-id` (search inside one trace; no trace fallback),
+`--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).
+
+**Index freshness.** Keyword matches (and hybrid's keyword half) fall back to
+the original messages when the search index returns too few literal matches,
+so recent, Cyrillic and partial-word text is still found. `coverage` reports
+which source served the keyword leg (`keyword_source`) and how far the index
+trails ingestion (`index_freshness`); a warning says so when your
+`--time-range` reaches past the newest indexed message.
+
+**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
+  unless you have a reason not to.
+- `keyword` — exact substring/identifier matches (error codes, tool names,
+  IDs). `score` is the integer match count.
+- `semantic` — meaning-based; finds paraphrases the user never typed
+  verbatim. `score` is cosine similarity.
+
+Each result row carries `conversation_id`, `message_index`, `role`,
+`timestamp`, `snippet`, `score`, and `cluster_id` / `cluster_name`. The
+response also reports `search_mode` — the mode that **actually ran**; a
+`semantic`/`hybrid` request transparently degrades to `keyword` when no
+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`:
+
+```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')
+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"}
+```
+
+### 3. Browse topic clusters
+
+```bash
+moda clusters                                 # root-level
+moda clusters --parent-id=<node_id>           # drill in
+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
+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           # ranked trace search
+```
+
+Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
+(`all|1h|3d|7d|24h|30d|90d`), `--environment`
+(`all|development|staging|production`), `--outcome`, `--limit`, `--offset`.
+
+### 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)
+```
+
+`--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`
+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
+(`--window`, `--metadata-only`, `--all`) apply to every target. Lines may also
+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
+```
+
+A batch returns `data.results: [{ target, ok, data | error }]` in input order,
+plus `succeeded`/`failed` counts. A missing trace is a per-item
+`error.code: "not_found"`, not a failed call; the exit code is 1 only when
+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
+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`.
+
+### 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
+```
+
+Auditing several traces? Batch the ids (positionals or `--ids-from=-|<file>`)
+instead of looping `moda audit`: 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
+trace, so follow each item's `next_commands` for it.
+
+`truncated` / `has_more` at the top level say whether the audit is complete.
+A full `--limit` page of ingest rows, the server's ~3 MB response budget
+(`summary.truncated_reason: "byte_limit"`) or a span cap sets both, and a
+warning plus `next_commands` give the follow-up — usually the `--cursor=` page
+from `next_cursor`; for very large traces audit one OTLP trace at a time
+(`summary.trace_ids`, `--kind=trace`). Prompt/response bodies are omitted by
+default (`{"omitted": true, "original_bytes": N}`); `--include-bodies` keeps
+them, cutting strings over 8 KB to `{"truncated": true, "original_bytes": N,
+"preview": …}`. Ingest rows whose stored payload is too large carry
+`payload_capped: true`: their spans keep ids, hierarchy, timing and types but
+no bodies. A trace too large to audit at all fails fast with an
+`audit_too_large` error whose `suggested_commands` list per-trace audits.
+
+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
+parent is missing) and `duplicate_count` (double-instrumentation — the same
+logical call emitted as >1 span). Each span carries `span_id`, `parent_span_id`,
+`trace_id`, `type` (tool spans included), timing, `prompt`, `response`, and the
+full semconv `attributes`. This is the honest substrate for auditing whether
+Moda captured every LLM/tool call for a trace.

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

@@ -0,0 +1,79 @@
+# Custom signals and false positives
+
+Loaded on demand from the moda-cli skill.
+
+### 9. Custom signals and false positives
+
+**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.
+
+```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> \
+  --attribution-id=<uuid> --reason="refund was approved"                  # one piece of evidence
+moda false-positive 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 \
+  --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
+```
+
+What each flag does downstream:
+
+| Kind | Effect |
+|---|---|
+| `problem` | Dismisses the problem: it leaves `moda problems` and the dashboard at once, and the reason is folded into the next reconcile. Cannot be undone from the CLI |
+| `problem-detection` | Drops that evidence from the problem and teaches the problem reader (same as `detection-review --verdict=false_positive`) |
+| `custom-signal` | Saved as a `does_not_fit` label with the reason, a labelled counterexample for the signal, and the live match is retracted (same as `signal-label`). `--undo` removes the label |
+| `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`.
+
+**Custom signals** are tenant-defined behaviors (pass/fail criteria) judged on
+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 \
+  --note="refund was approved" --msg-index=<anchor_msg_index>
+```
+
+`--label=does_not_fit` marks a hit a **false positive** and retracts the live
+match; `--label=fits` confirms it. Pass the hit's `anchor_msg_index` (or
+`--msg-dedup-token=<anchor_dedup_token>`) so the example points at the right
+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`
+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> \
+  --attribution-id=<uuid> --verdict=false_positive --note="retry was expected"
+moda detection-review <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.

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

@@ -0,0 +1,65 @@
+# Validation and troubleshooting
+
+Loaded on demand from the moda-cli skill.
+
+## Validation — how to know it worked
+
+- Every successful command exits 0 and prints valid JSON to stdout.
+- `moda ask` may exit `3` (degraded): a real, lower-trust answer synthesized
+  from local evidence — not a failure (`investigate`/`failures` always exit
+  `0` on success). Treat exit `1` as the only hard error (see
+  [Agent protocol](output-protocol.md#agent-protocol)).
+- Errors exit non-zero. In agent/JSON mode the error envelope is printed to
+  stdout (`status: "error"`, `errors[0].code`), even with `--quiet`; human
+  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.
+  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.
+- 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`,
+  `search`, `clusters`) before concluding "no data".
+
+## Troubleshooting
+
+**`No Moda API key found` (exit 4, `auth_required`)**
+Have the user export `MODA_API_KEY` (keys: [moda.dev/settings](https://moda.dev/settings)),
+or save one with `moda auth login --api-key`. `moda init` is the interactive
+setup wizard; do not run it unprompted.
+
+**`The Moda API rejected the API key (HTTP 401)` (exit 4, `auth_required`)**
+The key is invalid, revoked, or for another environment. Get a new key and
+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`,
+`moda problems`, `moda clusters`. A tool name with no failures in the window
+returns an empty result with a warning instead.
+
+**`Validation error:`**
+A flag value didn't match the schema. Check enums (`time_range` must be
+`1h|24h|3d|7d|30d|90d|all`, not `"7 days"`) and numeric ranges
+(`days_back` is 1–90). `--window` is 1–5 on `frustrations` and
+`tool-failure-detail`; on `context` a larger value is clamped to 5 with a
+warning that gives the `--all` command for a wider slice.
+`moda <command> --help` lists every flag with its range.
+
+**Empty results**
+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**
+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
+tool inputs or outputs. When a `semantic`/`hybrid` request was served as
+`keyword`, the envelope's `warnings` say so and why; retry or rephrase. For meaning-based queries prefer `--mode=semantic`; for
+exact error codes, tool names, or IDs prefer `--mode=keyword`.
+
+**`moda: command not found`**
+Either install globally (`npm install -g @moda-ai/cli`) or invoke through
+npx: `npx -p @moda-ai/cli moda <command>`.