@moda-ai/cli 1.8.0 → 1.9.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { validateConfig, VERSION, resolveApiKey } from './config.js';
 import { callDataAPI, ApiError, getApiRequestCount, resetApiRequestCount, } from './api-client.js';
-import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, WorldStateSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
+import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, SearchSchema, WorldStateSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
 import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
 import { runPromptsCommand } from './prompts.js';
 // Coding-agent capture (shadow workspace / Shadow Spark / trace hooks) is temporarily
@@ -13,7 +13,7 @@ import { runHarnessCommand } from './harness.js';
 import { runSyncCommand } from './sync.js';
 import { runDoctorCommand, runStatusCommand } from './doctor.js';
 import { CliInputError } from './errors.js';
-import { isTelemetryDisabled, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
+import { buildSearchAdoptionTelemetry, isTelemetryDisabled, SEARCH_MODES, sendCliUsageTelemetry, stripTelemetryFlag, } from './telemetry.js';
 import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
 import { createCommandRegistry } from './command-registry.js';
@@ -137,6 +137,7 @@ Commands:
   clusters                         Browse topic cluster hierarchy
   cluster-conversations <node_id>  List conversations in a cluster
   conversations                    Search and filter conversations
+  search "<query>"                 Search conversation messages (keyword/semantic/hybrid)
   world-state <conversation_id>    Get a conversation's world state (slots/threads/events)
   context <conversation_id>        Get windowed conversation context
   frustrations                     Get user frustration detections
@@ -192,6 +193,12 @@ Conversations flags:
   --user-id=ID                     Filter to a single user
   --environment=ENV                Filter by environment (all|development|staging|production)
 
+Search flags:
+  --mode=keyword|semantic|hybrid   Search mode (default hybrid)
+  --user-id=ID                     Filter to a single user
+  --time-range=RANGE               Time range filter (all|1h|3d|7d|24h|30d|90d)
+  --limit=N                        Maximum results to return (1-100, default 20)
+
 World-state flags:
   --summary-only                   Return segment summaries only (omit the event stream)
   --event-limit=N                  Max world-state events to return (1-5000, default 2000)
@@ -249,6 +256,8 @@ Examples:
   moda conversations --search="error" --limit=5
   moda conversations --world-state="enterprise" --outcome=positive
   moda conversations --world-state="refund,billing" --include-world-state
+  moda search "billing error" --mode=hybrid
+  moda search "refund flow" --mode=semantic --time-range=7d --limit=10
   moda world-state <conversation_id> --summary-only
   moda frustrations --days-back=14 --limit=20
   moda context <conversation_id> --window=3
@@ -327,6 +336,44 @@ async function attachWorldState(rows) {
         }
     }));
 }
+/**
+ * Record response-derived search telemetry from a `/search` payload. The
+ * endpoint returns the effective `search_mode` (which may differ from the
+ * requested mode after a degrade) plus a first-class `pagination.has_more`
+ * (the service fetches a candidate pool larger than the page, so this is a real
+ * signal — not a fragile "page filled the limit" heuristic).
+ */
+function recordSearchTelemetry(context, data) {
+    const record = asRecord(data);
+    if (!record)
+        return;
+    const results = Array.isArray(record.results) ? record.results : [];
+    const effective = typeof record.search_mode === 'string'
+        ? record.search_mode.toLowerCase()
+        : undefined;
+    const pagination = asRecord(record.pagination);
+    const hasMore = pagination?.has_more;
+    context.recordTelemetry({
+        search_mode_effective: SEARCH_MODES.includes(effective)
+            ? effective
+            : undefined,
+        result_count: results.length,
+        has_more: hasMore === true ? 'yes' : hasMore === false ? 'no' : 'na',
+    });
+}
+/** Record response-derived telemetry from a `/conversations` list payload. */
+function recordConversationsTelemetry(context, data) {
+    const record = asRecord(data);
+    if (!record)
+        return;
+    const list = Array.isArray(record.conversations) ? record.conversations : [];
+    const pagination = asRecord(record.pagination);
+    const hasMore = pagination?.has_more;
+    context.recordTelemetry({
+        result_count: list.length,
+        has_more: hasMore === true ? 'yes' : hasMore === false ? 'no' : 'na',
+    });
+}
 export async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
     switch (command) {
         case 'prompts': {
@@ -402,6 +449,7 @@ export async function runCommand(command, positional, flags, positionals = posit
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/conversations${queryString}`);
+            recordConversationsTelemetry(context, data);
             if (params.include_world_state === true) {
                 const enriched = asRecord(data) ?? {};
                 const list = Array.isArray(enriched.conversations)
@@ -415,6 +463,30 @@ export async function runCommand(command, positional, flags, positionals = posit
             }
             break;
         }
+        case 'search': {
+            // Positional query mirrors world-state/context/cluster-conversations:
+            // reject an empty/whitespace query with the shared CLI input error before
+            // it reaches the schema (which also guards via q.min(1)).
+            if (!positional || positional.trim() === '') {
+                throw new CliInputError('<query> is required', 'Usage: moda search "<query>" [--mode=keyword|semantic|hybrid] [--user-id=ID] [--time-range=RANGE] [--limit=N]');
+            }
+            const args = flagsToArgs(flags, 'q', positional);
+            const params = SearchSchema.parse(args);
+            const query = new URLSearchParams();
+            query.set('q', params.q);
+            if (params.mode)
+                query.set('mode', params.mode);
+            if (params.user_id)
+                query.set('user_id', params.user_id);
+            if (params.time_range)
+                query.set('time_range', params.time_range);
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            const data = await callDataAPI(`/search?${query.toString()}`);
+            recordSearchTelemetry(context, data);
+            context.output.writeData(data);
+            break;
+        }
         case 'world-state': {
             if (!positional) {
                 throw new CliInputError('<conversation_id> is required', 'Usage: moda world-state <conversation_id> [--summary-only] [--event-limit=N]');
@@ -856,6 +928,15 @@ export const commandRegistry = createCommandRegistry([
         ],
         ...dataApiDefaults,
     }),
+    legacyCommand({
+        name: 'search',
+        description: 'Search conversation messages (keyword, semantic, or hybrid)',
+        examples: [
+            'moda search "billing error"',
+            'moda search "refund flow" --mode=semantic --time-range=7d --limit=10',
+        ],
+        ...dataApiDefaults,
+    }),
     legacyCommand({
         name: 'world-state',
         description: "Get a conversation's world state (slots, threads, events)",
@@ -1104,6 +1185,14 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 exitCode: result.exitCode,
                 durationMs: Date.now() - startedAt,
                 apiRequestCount: getApiRequestCount(),
+                adoption: buildSearchAdoptionTelemetry({
+                    command: definition.name,
+                    positional: parsed.positional,
+                    flags: commandFlags,
+                    outputMode: context.outputMode,
+                    recorded: context.getTelemetryMeta(),
+                    skillVersion: process.env.MODA_SKILL_VERSION,
+                }),
             });
         }
         if (!updateCheckDisabled) {
@@ -1122,6 +1211,14 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
                 exitCode: 1,
                 durationMs: Date.now() - startedAt,
                 apiRequestCount: getApiRequestCount(),
+                adoption: buildSearchAdoptionTelemetry({
+                    command: definition.name,
+                    positional: parsed.positional,
+                    flags: commandFlags,
+                    outputMode: context.outputMode,
+                    recorded: context.getTelemetryMeta(),
+                    skillVersion: process.env.MODA_SKILL_VERSION,
+                }),
             });
         }
         if (context.outputMode === 'agent' || context.outputMode === 'agent-stream') {

package/dist/command-context.d.ts

@@ -5,6 +5,17 @@ export interface CommandContextInput {
     positionals: string[];
     flags: Record<string, string>;
 }
+/**
+ * Response-derived telemetry a handler can surface back to the dispatcher after
+ * the API call completes. Static fields (surface, requested mode, query length,
+ * etc.) are derived from the command + flags in the dispatcher and don't belong
+ * here — only values that require the runtime response are recorded.
+ */
+export interface CommandTelemetryMeta {
+    search_mode_effective?: 'na' | 'keyword' | 'semantic' | 'hybrid';
+    result_count?: number;
+    has_more?: 'na' | 'no' | 'yes';
+}
 export interface CommandContext {
     command: string;
     positional: string | undefined;
@@ -22,6 +33,10 @@ export interface CommandContext {
     quiet: boolean;
     verbose: boolean;
     interactive: boolean;
+    /** Merge response-derived telemetry; safe to call multiple times. */
+    recordTelemetry(meta: Partial<CommandTelemetryMeta>): void;
+    /** Snapshot of telemetry recorded so far by the handler. */
+    getTelemetryMeta(): CommandTelemetryMeta;
 }
 export declare function createCommandContext(input: CommandContextInput, options?: {
     commandName?: string;

package/dist/command-context.js

@@ -12,6 +12,7 @@ export function createCommandContext(input, options = {}) {
         !flagEnabled(flags, 'yes') &&
         process.stdin.isTTY === true &&
         process.stderr.isTTY === true;
+    const telemetryMeta = {};
     return {
         command: options.commandName ?? input.command,
         positional: input.positional,
@@ -33,6 +34,12 @@ export function createCommandContext(input, options = {}) {
         quiet,
         verbose: flagEnabled(flags, 'verbose'),
         interactive,
+        recordTelemetry(meta) {
+            Object.assign(telemetryMeta, meta);
+        },
+        getTelemetryMeta() {
+            return telemetryMeta;
+        },
     };
 }
 //# sourceMappingURL=command-context.js.map

package/dist/schemas.d.ts

@@ -141,6 +141,30 @@ export declare const ToolFailureDetailSchema: z.ZodObject<{
     include_window?: unknown;
     subtype?: string | undefined;
 }>;
+/**
+ * moda search "<query>" — keyword/semantic/hybrid search across conversation
+ * messages. `q` arrives as a positional arg; the runCommand handler rejects an
+ * empty/whitespace query before parsing, and min(1) guards the schema path too.
+ */
+export declare const SearchSchema: z.ZodObject<{
+    q: z.ZodString;
+    mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["keyword", "semantic", "hybrid"]>>>;
+    user_id: z.ZodOptional<z.ZodString>;
+    time_range: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "1h", "3d", "7d", "24h", "30d", "90d"]>>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    q: string;
+    mode?: "keyword" | "semantic" | "hybrid" | undefined;
+    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
+    limit?: number | undefined;
+    user_id?: string | undefined;
+}, {
+    q: string;
+    mode?: "keyword" | "semantic" | "hybrid" | undefined;
+    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
+    limit?: number | undefined;
+    user_id?: string | undefined;
+}>;
 /** moda workflows — recurring workflow catalog (read from agent_job_classes). */
 export declare const WorkflowsSchema: z.ZodObject<{
     time_range: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "1h", "3d", "7d", "24h", "30d", "90d"]>>>;

package/dist/schemas.js

@@ -76,6 +76,19 @@ export const ToolFailureDetailSchema = z.object({
 // `moda workflows` lists the catalog; `moda runs` lists executions.
 const RUN_OUTCOMES = ['running', 'succeeded', 'partial', 'failed', 'loop', 'abandoned', 'unknown'];
 const TIME_RANGES = ['all', '1h', '3d', '7d', '24h', '30d', '90d'];
+const SEARCH_MODES = ['keyword', 'semantic', 'hybrid'];
+/**
+ * moda search "<query>" — keyword/semantic/hybrid search across conversation
+ * messages. `q` arrives as a positional arg; the runCommand handler rejects an
+ * empty/whitespace query before parsing, and min(1) guards the schema path too.
+ */
+export const SearchSchema = z.object({
+    q: z.string().min(1).max(500),
+    mode: z.enum(SEARCH_MODES).default('hybrid').optional(),
+    user_id: z.string().optional(),
+    time_range: z.enum(TIME_RANGES).default('all').optional(),
+    limit: z.number().min(1).max(100).default(20).optional(),
+});
 /** moda workflows — recurring workflow catalog (read from agent_job_classes). */
 export const WorkflowsSchema = z.object({
     time_range: z.enum(TIME_RANGES).default('all').optional(),

package/dist/telemetry.d.ts

@@ -1,5 +1,28 @@
+import type { CliOutputMode } from './output.js';
+import type { CommandTelemetryMeta } from './command-context.js';
 export type TelemetryStatus = 'success' | 'error';
 export type TelemetryErrorType = 'validation_error' | 'api_error' | 'network_error' | 'unknown_error';
+export type SearchSurface = 'none' | 'conversation' | 'world_state' | 'cluster' | 'message' | 'context';
+export type SearchMode = 'na' | 'keyword' | 'semantic' | 'hybrid';
+export type Tristate = 'na' | 'no' | 'yes';
+/**
+ * Phase 6 search-adoption telemetry. Every field is optional and the backend
+ * defaults absent values, so it is always safe to omit a field we can't derive.
+ */
+export interface SearchAdoptionTelemetry {
+    output_mode?: CliOutputMode;
+    subcommand?: string;
+    search_surface?: SearchSurface;
+    search_mode_requested?: SearchMode;
+    search_mode_effective?: SearchMode;
+    query_length?: number;
+    query_term_count?: number;
+    result_count?: number;
+    zero_result?: Tristate;
+    has_more?: Tristate;
+    used_msg_index?: 0 | 1;
+    skill_version?: string;
+}
 export interface CliUsageTelemetryInput {
     apiKey: string | undefined;
     command: string;
@@ -9,7 +32,22 @@ export interface CliUsageTelemetryInput {
     exitCode: number;
     durationMs: number;
     apiRequestCount: number;
+    adoption?: SearchAdoptionTelemetry;
 }
+export declare const SEARCH_MODES: readonly SearchMode[];
+/**
+ * Derive the search-adoption telemetry for a command. Static fields come from
+ * the command name + flags; response-derived fields (effective mode, result
+ * count, has_more) are read from whatever the handler recorded on the context.
+ */
+export declare function buildSearchAdoptionTelemetry(input: {
+    command: string;
+    positional: string | undefined;
+    flags: Record<string, string>;
+    outputMode: CliOutputMode;
+    recorded: CommandTelemetryMeta;
+    skillVersion?: string;
+}): SearchAdoptionTelemetry;
 export declare function stripTelemetryFlag(flags: Record<string, string>): Record<string, string>;
 export declare function isTelemetryDisabled(flags: Record<string, string>): boolean;
 export declare function getInvocationId(): string;

package/dist/telemetry.js

@@ -3,6 +3,109 @@ import { VERSION, resolveModaBaseUrl } from './config.js';
 const TELEMETRY_TIMEOUT_MS = 500;
 const INVOCATION_ID = randomUUID();
 const TELEMETRY_FLAG = 'no-telemetry';
+const SEARCH_SURFACE_BY_COMMAND = {
+    search: 'message',
+    conversations: 'conversation',
+    clusters: 'cluster',
+    'cluster-conversations': 'cluster',
+    'world-state': 'world_state',
+    context: 'context',
+};
+export const SEARCH_MODES = ['keyword', 'semantic', 'hybrid'];
+function termCount(query) {
+    return query.trim().split(/\s+/).filter(Boolean).length;
+}
+function clampInt(value, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+/**
+ * Derive the search-adoption telemetry for a command. Static fields come from
+ * the command name + flags; response-derived fields (effective mode, result
+ * count, has_more) are read from whatever the handler recorded on the context.
+ */
+export function buildSearchAdoptionTelemetry(input) {
+    const { command, positional, flags, outputMode, recorded } = input;
+    const adoption = {
+        output_mode: outputMode,
+        search_surface: SEARCH_SURFACE_BY_COMMAND[command] ?? 'none',
+    };
+    // The query lives in the positional for `moda search`, but in `--search` for
+    // the conversations list surface.
+    let queryText;
+    if (command === 'search')
+        queryText = positional;
+    else if (command === 'conversations')
+        queryText = flags.search;
+    // Trim before measuring both dimensions so query_length and query_term_count
+    // describe the same (trimmed) query the backend actually sees.
+    const trimmedQuery = queryText?.trim() ?? '';
+    if (trimmedQuery !== '') {
+        adoption.query_length = trimmedQuery.length;
+        adoption.query_term_count = termCount(trimmedQuery);
+    }
+    // search_mode is only meaningful for the message-grain search command.
+    if (command === 'search') {
+        const requested = (flags.mode ?? '').toLowerCase();
+        adoption.search_mode_requested = SEARCH_MODES.includes(requested)
+            ? requested
+            : 'hybrid'; // mirrors SearchSchema's default
+    }
+    // used_msg_index only applies to the conversation context surface.
+    if (command === 'context') {
+        adoption.used_msg_index = flags['msg-index'] !== undefined ? 1 : 0;
+    }
+    if (recorded.search_mode_effective) {
+        adoption.search_mode_effective = recorded.search_mode_effective;
+    }
+    if (typeof recorded.result_count === 'number') {
+        adoption.result_count = recorded.result_count;
+        adoption.zero_result = recorded.result_count === 0 ? 'yes' : 'no';
+    }
+    if (recorded.has_more)
+        adoption.has_more = recorded.has_more;
+    const skill = input.skillVersion?.trim();
+    if (skill)
+        adoption.skill_version = skill.slice(0, 64);
+    return adoption;
+}
+function serializeAdoption(adoption) {
+    if (!adoption)
+        return {};
+    const out = {};
+    if (adoption.output_mode)
+        out.output_mode = adoption.output_mode;
+    if (adoption.subcommand)
+        out.subcommand = adoption.subcommand.slice(0, 64);
+    if (adoption.search_surface)
+        out.search_surface = adoption.search_surface;
+    if (adoption.search_mode_requested) {
+        out.search_mode_requested = adoption.search_mode_requested;
+    }
+    if (adoption.search_mode_effective) {
+        out.search_mode_effective = adoption.search_mode_effective;
+    }
+    const queryLength = clampInt(adoption.query_length, 0, 2000);
+    if (queryLength !== undefined)
+        out.query_length = queryLength;
+    const queryTermCount = clampInt(adoption.query_term_count, 0, 200);
+    if (queryTermCount !== undefined)
+        out.query_term_count = queryTermCount;
+    const resultCount = clampInt(adoption.result_count, 0, 100_000);
+    if (resultCount !== undefined)
+        out.result_count = resultCount;
+    if (adoption.zero_result)
+        out.zero_result = adoption.zero_result;
+    if (adoption.has_more)
+        out.has_more = adoption.has_more;
+    if (adoption.used_msg_index !== undefined) {
+        out.used_msg_index = adoption.used_msg_index ? 1 : 0;
+    }
+    if (adoption.skill_version)
+        out.skill_version = adoption.skill_version.slice(0, 64);
+    return out;
+}
 export function stripTelemetryFlag(flags) {
     const { [TELEMETRY_FLAG]: _drop, ...rest } = flags;
     return rest;
@@ -49,6 +152,7 @@ export async function sendCliUsageTelemetry(input) {
                 platform: process.platform,
                 arch: process.arch,
                 flags_json: { names: sanitizedFlagNames(input.flags) },
+                ...serializeAdoption(input.adoption),
             }),
             signal: controller.signal,
         });

package/package.json

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

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: moda-cli
-description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — overview KPIs, topic clusters, conversation search, message context, user frustration detections, tool failures, agent jobs, recurring workflows, active loop detections, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, or wants to investigate how their AI agent is performing.
+version: 2.0.0
+description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — semantic/keyword/hybrid message search, overview KPIs, topic clusters, message context, user frustration detections, tool failures, agent jobs, recurring workflows, active loop detections, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
 ---
 
 # Moda CLI
@@ -13,15 +14,26 @@ filter. Analytics commands are read-only. Prompt management includes both
 read-only commands (`prompts status`, `prompts diff`) and commands that sync
 or promote remote state (`prompts sync`, `prompts promote`).
 
+**`moda search` is the primary way to find anything by content.** It runs
+message-grain semantic, keyword, or hybrid retrieval across every message —
+including tool calls and tool results — and returns ranked snippets with
+direct anchors (`conversation_id` + `message_index`) you can hand straight to
+`moda context`. Reach for it first whenever the question is "where did X
+happen?" or "find conversations/tool calls about Y". Use `moda conversations`
+only when you need to *list/filter* by structured fields (cluster, user,
+environment, outcome), not to search by meaning.
+
 ## When to use
 
 Activate this skill when the user wants to:
 
+- **Find conversations or tool calls about a topic, error, or behavior**
+  (semantic/keyword/hybrid search) — start with `moda search`
 - Inspect agent health: conversation volume, frustration rate, tool failures
 - Debug a specific frustrated conversation
 - Investigate which tools are failing and why
 - Browse conversation topics (clusters)
-- Search conversations by content, user, environment, or time range
+- List/filter conversations 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
 
@@ -41,6 +53,9 @@ Optional:
 
 - `MODA_BASE_URL` defaults to `https://moda.dev`; override only for
   self-hosted or staging.
+- `MODA_SKILL_VERSION` — export to `2.0.0` so search-adoption telemetry can
+  attribute usage to this skill version. Set it once per session:
+  `export MODA_SKILL_VERSION=2.0.0`.
 
 ## Setup
 
@@ -65,10 +80,63 @@ export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 
 ## Procedure
 
-Default investigation pattern: **broad → narrow → context**. Always start with
-`moda overview` to ground subsequent calls in real numbers.
+Two entry points depending on the question:
+
+- **"Find / where did X happen?"** → start with `moda search` (semantic,
+  keyword, or hybrid retrieval over every message), then `moda context` on the
+  returned anchors.
+- **"How healthy is the agent overall?"** → start with `moda overview`, then
+  drill down (clusters → conversations → context).
+
+Default investigation pattern for content questions: **search → context**.
+For health questions: **broad → narrow → context**.
+
+### 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>
+```
+
+Searches conversation messages at message grain, **including tool calls and
+tool results** (tool name, input arguments, and output previews are embedded),
+so it finds where an agent *did* something, not just where it talked about it.
+
+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).
+
+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`:
 
-### 1. Overview (always start here)
+```bash
+# Find, then read the exact turn
+hit=$(moda search "double charge" --limit=1 | jq -r '.results[0]')
+cid=$(echo "$hit" | jq -r '.conversation_id')
+idx=$(echo "$hit" | jq -r '.message_index')
+moda context "$cid" --msg-index="$idx"
+```
+
+### 2. Overview (start here for health questions)
 
 ```bash
 moda overview                        # last 7 days
@@ -78,7 +146,7 @@ moda overview --days-back=30
 Returns total conversations, trend, frustration rate, tool failure summary,
 top clusters, recent activity.
 
-### 2. Browse topic clusters
+### 3. Browse topic clusters
 
 ```bash
 moda clusters                                 # root-level
@@ -86,15 +154,21 @@ moda clusters --parent-id=<node_id>           # drill in
 moda cluster-conversations <node_id>          # conversations in cluster
 ```
 
-### 3. Search conversations
+### 3b. List / filter conversations (structured, not semantic)
+
+Use `moda conversations` 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 conversation text.
 
 ```bash
-export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
+moda conversations --user-id=<id> --time-range=7d
+moda conversations --cluster-id=<node_id> --environment=production
+moda conversations --search="timeout" --limit=20    # keyword filter only
 ```
 
 Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
 (`all|1h|3d|7d|24h|30d|90d`), `--environment`
-(`all|development|staging|production`), `--limit`, `--offset`.
+(`all|development|staging|production`), `--outcome`, `--limit`, `--offset`.
 
 ### 4. Read a single conversation
 
@@ -238,6 +312,22 @@ and future evals.
 
 ## Common workflow recipes
 
+### Find where something happened (search → context)
+
+```bash
+# Semantic: find the moment a user expressed an intent, in their own words
+moda search "user wants to cancel subscription" --mode=semantic --limit=5 \
+  | jq -r '.results[] | "\(.conversation_id) @\(.message_index)  \(.snippet)"'
+
+# Keyword: locate every tool call/result mentioning an exact identifier
+moda search "stripe.refunds.create" --mode=keyword --limit=10
+
+# Search, then open the top hit at the exact turn
+moda search "rate limit exceeded" --limit=1 \
+  | jq -r '.results[0] | "\(.conversation_id) \(.message_index)"' \
+  | xargs -n2 sh -c 'moda context "$0" --msg-index="$1"'
+```
+
 ### Daily health check
 
 ```bash
@@ -332,6 +422,14 @@ A flag value didn't match the schema. Check enums (`time_range` must be
 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**
+First widen `--time-range` (default is `all`, so an empty result usually means
+the phrasing, not the window). If the response `search_mode` came back
+`keyword` for a `semantic`/`hybrid` request, the embedding provider was
+unreachable and search degraded — retry, or fall back to `--mode=keyword` with
+exact identifiers. 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>`.
@@ -341,10 +439,11 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | Command | Purpose |
 |---|---|
 | `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 clusters` | Browse topic cluster hierarchy |
 | `moda cluster-conversations <node_id>` | Conversations in a cluster |
-| `moda conversations` | Search/filter conversations |
+| `moda conversations` | List/filter conversations by structured fields |
 | `moda context <conversation_id>` | Windowed message context (max 5 per side) |
 | `moda frustrations` | User frustration detections with evidence |
 | `moda tool-failures` | Tool failure overview |
@@ -359,6 +458,9 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |
 | `moda prompts promote <key>` | Move a remote prompt label |
 
+`moda search` flags: `--mode=keyword|semantic|hybrid` (default `hybrid`),
+`--user-id`, `--time-range=<range>`, `--limit=N` (1–100, default 20).
+
 Common flags across most commands: `--days-back=N` (1–90), `--limit=N`,
 `--offset=N`, `--time-range=<range>`. Runs commands also accept
 `--outcome=<outcome>`, `--class-id=<workflow_class_id>`, and `--user-id=<id>`.