@moda-ai/cli 1.9.6 → 1.10.0

package/skills/moda-cli/SKILL.md

@@ -78,6 +78,87 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+## Agent protocol
+
+`moda` is agent-safe: it picks an output mode automatically, signals how much
+to trust an answer through exit codes, and (in agent mode) emits a
+schema-versioned `moda.agent.v1` JSON envelope you can parse instead of
+scraping prose.
+
+### Output mode auto-selection
+
+The mode is resolved in this priority order — first match wins, so you usually
+need no flags at all:
+
+1. **Explicit flags** override everything:
+   - `--agent` — `moda.agent.v1` schema-versioned JSON envelope
+   - `--json` — raw JSON payload (no envelope)
+   - `--agent --stream` — NDJSON stream of `moda.agent_event.v1` events
+   - `--human` — force human prose
+2. **`MODA_FORMAT` env var** — one of `human | json | agent | agent-stream`.
+3. **Agent-environment auto-detect** — if `CLAUDECODE`, `CURSOR`, `CI`, or
+   `MODA_AGENT` is set, default to the agent JSON envelope.
+4. **TTY auto-detect** — if stdout is not a TTY (piped or redirected), default
+   to the agent JSON envelope; an interactive terminal defaults to human prose.
+
+Running `moda` from inside Claude Code / Cursor, in CI, or through a pipe
+already yields agent JSON — no flag required.
+
+### Exit codes
+
+Branch on the exit code; it is stable and cheaper than parsing the payload:
+
+| Exit | Meaning | How to treat it |
+|---|---|---|
+| `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
+| `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
+| `1` | error — bad input, unknown command, or unexpected failure | Read `errors[]` in the envelope. |
+
+### The `moda.agent.v1` envelope
+
+Fields an agent should read:
+
+- `status` — `ok` | `degraded` | `error`.
+- `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>`.
+- `next_commands[]` — suggested follow-up commands (each carries `mutability`
+  and `requires_approval`).
+- `warnings[]`, `errors[]`.
+- `data` — the raw command payload. For `ask`, `data.source` is `cloud` or
+  `local_fallback` and `data.degraded` is a boolean — the canonical in-payload
+  way to detect degradation (in addition to exit code 3).
+
+### Detecting a degraded answer
+
+Treat an answer as degraded if **any** of these hold:
+
+- exit code is `3`, **or**
+- `data.degraded === true` (for `ask`; equivalently `data.source === "local_fallback"`), **or**
+- `status === "degraded"`.
+
+### Schema introspection
+
+```bash
+moda --json-schemas      # print the JSON Schemas for the agent output contract
+```
+
+### Recommended agent usage
+
+```bash
+answer=$(moda ask "what should I fix first?")
+case $? in
+  0) printf 'grounded answer:\n%s\n' "$answer" ;;
+  3) printf 'DEGRADED (local fallback — verify before acting):\n%s\n' "$answer" ;;
+  *) echo "moda ask failed:"; echo "$answer" | jq -r '.errors[].message'; exit 1 ;;
+esac
+
+# Pull the trusted parts straight out of the envelope
+echo "$answer" | jq -r '.summary.text'
+echo "$answer" | jq -r '.evidence_refs[] | "\(.kind)\t\(.label)\t\(.path // "")"'
+```
+
 ## Procedure
 
 Two entry points depending on the question:
@@ -146,6 +227,47 @@ moda overview --days-back=30
 Returns total conversations, trend, frustration rate, tool failure summary,
 top clusters, recent activity.
 
+### 2b. Ask & investigate (production intelligence)
+
+`moda ask` answers a natural-language production/harness question; `moda
+investigate` returns a ranked, evidence-backed list of the issues worth fixing
+first. Both default to the last 7 days (`--days-back=N`, 1–90).
+
+```bash
+moda ask "what should I fix first?"               # grounded answer + evidence
+moda ask "why are refunds failing?" --days-back=30
+moda investigate                                  # ranked findings, last 7d
+moda investigate --days-back=14
+moda overview                                     # health briefing (see §2)
+```
+
+In an agent environment these emit the `moda.agent.v1` envelope (see
+[Agent protocol](#agent-protocol)). For `ask`, branch on the exit code (`0`
+grounded, `3` degraded, `1` error) and read `data.source` /
+`data.degraded` to know whether the answer came from Moda Cloud or a local
+Data API fallback. Abbreviated envelope:
+
+```json
+{
+  "schema_version": "moda.agent.v1",
+  "command": "ask",
+  "status": "degraded",
+  "summary": { "text": "Strongest signal is: lookupCustomer is failing in production.", "confidence": "medium" },
+  "evidence_refs": [
+    { "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 conversation anchors.", "mutability": "read", "requires_approval": false }
+  ],
+  "warnings": ["Cloud ask endpoint unavailable; synthesized answer from local Data API evidence."],
+  "errors": [],
+  "data": { "source": "local_fallback", "degraded": true, "question": "what should I fix first?", "answer": "…", "confidence": "medium" }
+}
+```
+
+`moda investigate` also accepts scoping flags (`--tool`, `--run`,
+`--conversation`, `--loop`) to focus the ranking on one signal.
+
 ### 3. Browse topic clusters
 
 ```bash
@@ -178,6 +300,27 @@ 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` 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`.
+
+### 4b. Audit raw spans/trace (completeness, orphans, duplicates)
+
+```bash
+moda audit <conversation_id|trace_id>         # auto-detects trace vs conversation
+moda audit <trace_id> --kind=trace            # force trace lookup
+moda audit <conversation_id> --include-raw    # attach verbatim raw_event bodies
+```
+
+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 conversation.
+
 ### 5. Frustration analysis
 
 ```bash
@@ -393,6 +536,9 @@ moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}
 ## Validation — how to know it worked
 
 - Every successful command exits 0 and prints valid JSON to stdout.
+- `moda ask` / `moda investigate` may exit `3` (degraded): a real,
+  lower-trust answer synthesized from local evidence — not a failure. Treat
+  exit `1` as the only hard error (see [Agent protocol](#agent-protocol)).
 - Errors print to stderr with non-zero exit. Check stderr before claiming
   success.
 - If the JSON has `"conversations": []` or `"frustrations": []`, the call
@@ -441,6 +587,8 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda init` | Browser auth + provision API key + install agent rules |
 | `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 clusters` | Browse topic cluster hierarchy |
 | `moda cluster-conversations <node_id>` | Conversations in a cluster |
 | `moda conversations` | List/filter conversations by structured fields |