@moda-ai/cli 1.55.18 → 1.55.20

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

@@ -0,0 +1,176 @@
+# Setup and authentication
+
+Loaded on demand from the moda-cli skill. Run `moda auth --help` for the current subcommands and flags.
+
+## Setup
+
+### First-time install
+
+```bash
+npm install -g @moda-ai/cli
+moda init                       # browser-based auth + key provisioning
+```
+
+Or one-shot via npx without installing:
+
+```bash
+npx -p @moda-ai/cli moda <command>
+```
+
+### Manual key
+
+```bash
+export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
+```
+
+### Headless provisioning (CI / agents): `moda provision`
+
+`moda provision` mints (or reuses) a tenant API key with zero prompts and
+prints a single JSON credentials document to stdout — in every output mode,
+even on an interactive terminal, so it composes directly:
+
+```bash
+KEY=$(moda provision --tenant-id t1 | jq -r .apiKey)
+```
+
+Output shape:
+
+```json
+{
+  "apiKey": "moda_sk_...",
+  "tenantId": "t1",
+  "tenantName": "Acme",
+  "tenantSlug": "acme",
+  "ingestUrl": "https://moda-ingest.modas.workers.dev",
+  "baseUrl": "https://moda.dev",
+  "reused": false
+}
+```
+
+Rules and limitations:
+
+- **Requires an existing CLI session.** Minting a *new* key is control-plane
+  work: with no stored session it exits `4` (`auth_required`) telling you to
+  run `moda auth login` on a machine with a browser first, or to skip
+  provisioning and export `MODA_API_KEY` directly. If you already hold a key,
+  you do not need this command at all — `moda auth login --api-key` gets you
+  to an authenticated state with no browser.
+- **Never prompts, even on a TTY.** A single-tenant account auto-selects;
+  with multiple tenants you must pass `--tenant-id=<id>` (or set
+  `MODA_TENANT_ID`), otherwise it exits `5` (`needs_input`) with per-tenant
+  `resume_flags`.
+- `reused: true` means a previously stored key for that tenant passed a
+  liveness probe and was reused instead of minting a new one (same dedup +
+  idempotent bootstrap machinery as `moda init`).
+- **Does not write `~/.moda/config.json` by default** — headless callers own
+  their credential storage. Pass `--save` to opt into the init-style
+  persistence.
+- `--label=<text>` names the created key (default: machine hostname);
+  `--profile=NAME` scopes the session lookup.
+- stdout carries a live credential — a warning is printed to stderr; never
+  pipe provision stdout into logs.
+
+**When to use which:** `moda init` is the interactive first-time onboarding
+wizard for a repo (harness discovery, skills, prompts, validation);
+`moda provision` is for CI jobs and agents that already have a session and
+just need credentials.
+
+### Auth session inspection and token composition
+
+```bash
+moda auth login                  # browser PKCE sign-in; stores a moda_ct_ session token
+moda auth login --api-key        # NON-INTERACTIVE: validate MODA_API_KEY and save it
+moda auth login --non-interactive # never open a browser; fail if no key is available
+printf %s "$KEY" | moda auth login --api-key-stdin   # key never touches argv
+moda auth login --api-key=<key>  # inline; WARNS, key is visible in argv + shell history
+moda auth logout                 # revoke the session server-side, then delete it locally
+moda auth status                 # both credentials; exit 0 if either is usable, else 4
+moda auth status --online        # additionally probe GET /api/cli/context
+moda auth whoami                 # identity from the session, or from the API key
+moda auth token                  # print the raw bearer token + newline, nothing else
+curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/context
+```
+
+**If you are an agent with `MODA_API_KEY` and no browser, this is the whole
+flow:**
+
+```bash
+moda auth whoami                 # exit 0 + "verified": true means you are authenticated
+```
+
+The API key alone is sufficient for every data command; `moda auth login` is
+only needed for control-plane work (`moda provision`, `moda init`). There are
+two independent credentials and `auth` reports both:
+
+| Credential | Obtained by | Used for |
+| --- | --- | --- |
+| `moda_ct_` session token | `moda auth login` (browser PKCE) | control plane: `provision`, `init`, `auth token` |
+| `moda_sk_` API key | `MODA_API_KEY`, `moda provision`, `moda init` | every data command |
+
+- `moda auth login` opens the browser consent flow at `{MODA_BASE_URL}/auth/cli`
+  with a localhost callback (ports 8432-8435, first free). Approving in the
+  browser hands the CLI a one-time code that it exchanges for a `moda_ct_...`
+  session token (sliding 30-day expiry, renewed automatically in the
+  background while you keep using the CLI). If the browser cannot reach the
+  machine, paste the callback URL or the code shown on the consent page into
+  the terminal.
+- `moda auth logout` revokes the stored `moda_ct_` session server-side
+  (best-effort) and deletes the local credential; legacy sessions are just
+  deleted locally.
+- `moda auth login --api-key` authenticates **without a browser**. Prefer
+  `MODA_API_KEY` (bare `--api-key`) or `--api-key-stdin`; `--api-key=<key>`
+  works but puts the secret in argv and shell history, so it warns. The key is
+  validated against the Data API before anything is written, then saved to
+  `~/.moda/config.json`. A rejected key (401/403) or an unreachable API both
+  fail without persisting. `--non-interactive` is the same path plus a
+  guarantee that no browser opens even when no key is found — it exits with
+  the commands that would mint one.
+- If `MODA_API_KEY` holds a **different** key than the one being saved, the
+  environment still wins afterwards. Login says so instead of reporting a
+  clean success: `"shadowed_by_env": true`, `"effective_credential": "env"`,
+  exit `3`. Unset `MODA_API_KEY` to use the saved credential.
+- `moda auth whoami` reports the browser session when there is one. With no
+  session but a usable API key it reports
+  `{ "credential": "api_key", "apiKeyCredential": { "source": <"env"|"profile"|"config">,
+  "masked": <string>, "verified": <bool> }, "tenant_id": <string|null> }`.
+  `verified: true` means the key was accepted by the API just now. If the API
+  is unreachable the command exits `3` (degraded) with `verified: false`
+  rather than claiming an identity it could not confirm; a rejected key is an
+  error, not a "logged out" state.
+- `moda auth status` reports
+  `{ "loggedIn": <bool>, "authenticated": <bool>, "apiKeyCredential": {...},
+  "profile": <string|null>, "expiresAt": <ISO|null> }`
+  plus `"user": { "email": <string> }` when the stored session carries an
+  email (PKCE `moda_ct_` sessions do; legacy sessions omit it). `loggedIn` is
+  **browser-session only**; `authenticated` is true when *either* credential is
+  usable, and the exit code follows `authenticated` (`0` usable, `4` neither).
+  `apiKeyCredential` is `{ "present": false }` or
+  `{ "present": true, "source": <"env"|"profile"|"config">, "masked": <string>,
+  "tenantId": <string|null> }` — `source: "env"` tells you a `MODA_API_KEY` is
+  shadowing anything on disk. The raw key is never emitted. Exit `4` is an
+  **expected state signal, not an error**: the payload is clean data (no error
+  block, no stderr noise), and no browser is ever opened.
+  Without `--online` there is no network I/O, so `authenticated` means the
+  credential is **present**, not that it still works, and
+  `apiKeyCredential.verified` is `null`. With `--online` the key is probed too:
+  a rejected key gets `verified: false`, stops counting toward `authenticated`,
+  and exits `4`; an unreachable API leaves it counting, so a blip never kills a
+  good credential. With `--online` the payload adds
+  `{ "online": { "reachable": <bool>, "ok": <bool>, "tenantCount": <n> } }`:
+  `reachable: true` means any HTTP response arrived (even a 401/500), `ok`
+  reflects HTTP success, and `tenantCount` is present only when the response
+  was ok and carried a tenants array. A network failure or probe timeout
+  (5 s) yields `reachable: false`; the exit code always follows local session
+  validity only, never the probe.
+- `moda auth token` writes exactly the bare token plus a trailing newline to
+  stdout in **every** output mode — including piped/json/agent, because
+  command substitution is a pipe — so `$(moda auth token)` composes safely
+  with no envelope to strip. When logged out it prints a stderr message and
+  exits `4`; with an explicit `--json` flag it instead prints
+  `{"error":"not_authenticated"}` to stdout (still exit `4`).
+- `moda auth token` prints whichever credential kind is stored. Newer logins
+  store a `moda_ct_...` CLI session token, which authenticates **`/api/cli/*`
+  endpoints only** — it is not accepted by the Data API (`/api/v1/data/*`
+  wants a `moda_sk_...` API key) or other dashboard endpoints. Legacy
+  sessions print the Auth0 bearer token as before.
+- Both respect `--profile=NAME` and `MODA_PROFILE`.

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

@@ -0,0 +1,74 @@
+# All commands at a glance
+
+Loaded on demand from the moda-cli skill. This table can lag the CLI: `moda <command> --help` is authoritative for flags, types, ranges, and defaults.
+
+## Reference: all commands at a glance
+
+| Command | Purpose |
+|---|---|
+| `moda init` | Browser auth + provision API key + install agent rules |
+| `moda provision` | Headless tenant + API key provisioning; single JSON credentials doc on stdout (exit `4` without a session, `5` when `--tenant-id` is needed) |
+| `moda auth login` | Browser PKCE sign-in; stores a revocable `moda_ct_` session token |
+| `moda auth login --api-key` | Non-interactive: validate `MODA_API_KEY` (or `--api-key=<key>`) and save it; never opens a browser |
+| `moda auth whoami` | Authenticated identity from the session, or from the API key when there is no session |
+| `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 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 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 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: 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\|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 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`),
+`--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
+does not take, and the error lists the flags it does. For the time window see
+[Time-window flags by command](output-protocol.md#time-window-flags-by-command) (`--days-back`
+on most detection commands, `--time-range` on `traces`/`search`/`clusters`,
+`--window` on `users`/`user`); `--limit`/`--offset` exist only on paged list
+commands (`moda <command> --help` shows them). Boolean flags take `true`/`false`
+and also `1`/`0`, `yes`/`no`, `on`/`off`.
+`frustrations` and `tool-failure-detail` additionally accept
+`--include-window` (attach a `window` slice per row) and `--window=N` (1–5,
+default `1`; half-width, so `--window=1` ⇒ 3 messages). `emotions` accepts
+`--include-window` to keep each detection's `conversation_context` in agent
+output. `problem <id>` accepts `--full` for the whole dossier in agent output.

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

@@ -0,0 +1,29 @@
+# Dashboard parity
+
+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.
+
+| 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` |
+| Replays: run detail, playout transcripts | `moda replays runs <set_id>`, `run <set_id> <run_id>`, `playouts <set_id> <run_id> [--case --arm --seed --transcript]`, `playout <set_id> <run_id> <playout_id>` |
+| 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=…` |
+
+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).

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

@@ -0,0 +1,79 @@
+# Detections: frustrations, emotions, tool failures
+
+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
+```
+
+In agent output, `frustrations` and `emotions` rows leave out the embedded
+conversation window (most of each row) unless you pass `--include-window`;
+each row keeps `anchor` and a `context_command` to read the turns around it.
+
+`--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.
+
+Every row carries a top-level `anchor` block:
+`{ kind: 'frustration', conversation_id, msg_index, signal, quote_preview,
+all_turns, no_anchor }`. `msg_index` is the 0-indexed turn where the
+frustration fired, derived from `key_turns[0]` (the same turn the API centers
+the embedded window on), falling back to `user_quotes[0].turn` when
+`key_turns` is empty — reference `anchor.conversation_id` and
+`anchor.msg_index` directly instead of digging into `user_quotes` to locate
+the moment.
+`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), the canonical
+"three lines" view.
+
+### 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
+```
+
+Every example row in `tool-failure-detail` output carries a top-level
+`anchor` block:
+`{ kind: 'tool_failure', conversation_id, msg_index, tool_name, tool_use_id,
+error_subtype, no_anchor }`. `msg_index` is the 0-indexed turn of the failing
+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.
+
+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). Example text is returned whole; if
+the agent envelope goes over its byte limit, whole trailing examples are
+dropped and `truncation.data.full_output_path` holds every example. Agent output lists the 20 most frequent
+`subtypes` (`subtypes_total` has the full count); `--json` lists all.

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

@@ -0,0 +1,45 @@
+# Feedback
+
+Loaded on demand from the moda-cli skill.
+
+## Feedback: help us improve
+
+Successful agent envelopes carry a `meta.tip` reminding you of this. When a
+response looks wrong (a cluster label that doesn't match its traces,
+a frustration whose causes don't match the transcript, an empty result that
+should not be empty, an API quirk), flag it with `moda feedback`. The Moda
+team reads these to fix data quality issues. Only submit genuine
+observations; never run the command with placeholder text.
+
+```bash
+moda feedback "cluster 'billing' is mostly refund traces" \
+  --category=bad_cluster_label --cluster-id=<node_id>
+moda feedback "search finds nothing for a trace I can open" \
+  --category=missing_data --conversation-id=<id>
+moda feedback "a cancelled call is counted as a tool failure" \
+  --category=wrong_tool_failure --tool-name=<tool>
+moda feedback "trace is a refund request, not this problem" \
+  --category=false_positive_attribution --problem-id=<id> --conversation-id=<id>
+```
+
+- `<note>` is required (max 4000 chars), as the argument or `--note=TEXT`.
+  Say what looked wrong and why.
+- `--category`: `bad_cluster_label | mismatched_frustration | missing_data |
+  noisy_data | wrong_tool_failure | incorrect_loop | api_quirk |
+  false_positive_attribution | misrouted_fix | harness_bug | other`
+  (default `other`). Use `false_positive_attribution` when a trace is
+  attributed to the wrong problem, `misrouted_fix` when a fix targets the
+  wrong problem or file, and `harness_bug` for a bug in the agent harness
+  Moda analysed. An unknown category is still sent, as `other` with
+  `refs.raw_category`, and a warning lists the valid ones.
+- `--severity`: `info | low | medium | high` (default `low`).
+- Attach ids when you have them: `--conversation-id`, `--cluster-id`,
+  `--tool-name`, `--run-id`, or any other `--<name>-id` (`--problem-id`,
+  `--fix-id`, `--attribution-id`, `--trace-id`, `--span-id`,
+  `--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>
+  --reason=TEXT`.
+- Never include secrets or full transcripts in the note.