@moda-ai/cli 1.8.1 → 1.9.6

package/dist/auth.js

@@ -312,12 +312,44 @@ export async function authFetch(path, options = {}, authOptions = {}) {
     if (!token) {
         throw new Error('Not authenticated. Run "moda init" to log in.');
     }
-    const url = `${resolveModaBaseUrl()}${path}`;
     const headers = new Headers(options.headers);
     headers.set('Authorization', `Bearer ${token}`);
     if (!headers.has('Content-Type') && options.body) {
         headers.set('Content-Type', 'application/json');
     }
-    return fetch(url, { ...options, headers });
+    const origin = new URL(resolveModaBaseUrl()).origin;
+    let url = `${resolveModaBaseUrl()}${path}`;
+    // Follow redirects manually so EVERY hop is origin-checked, not just the
+    // first. Native `redirect: 'follow'` would silently strip the Authorization
+    // header on a cross-host hop (per the Fetch spec) — the exact failure that
+    // broke moda init (the legacy www → apex 308). Same-host hops keep the header
+    // and are safe to follow; any hop that leaves the Moda origin fails fast with
+    // an actionable error instead of surfacing as a confusing 401.
+    const MAX_REDIRECTS = 5;
+    for (let hop = 0;; hop++) {
+        const response = await fetch(url, { ...options, headers, redirect: 'manual' });
+        if (response.status < 300 || response.status >= 400) {
+            return response;
+        }
+        const location = response.headers.get('location');
+        const target = location ? safeResolveUrl(location, url) : null;
+        if (!target || target.origin !== origin) {
+            throw new Error(`Moda API redirected (${response.status}) to ${location ?? '(unknown)'}. ` +
+                'Cross-host redirects strip Authorization and break moda init. ' +
+                'Use MODA_BASE_URL=https://moda.dev (not www.moda.dev).');
+        }
+        if (hop >= MAX_REDIRECTS) {
+            throw new Error(`Moda API exceeded ${MAX_REDIRECTS} same-host redirects for ${path}.`);
+        }
+        url = target.toString();
+    }
+}
+function safeResolveUrl(location, base) {
+    try {
+        return new URL(location, base);
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=auth.js.map

package/dist/cli.js

@@ -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';
@@ -336,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': {
@@ -411,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)
@@ -444,6 +483,7 @@ export async function runCommand(command, positional, flags, positionals = posit
             if (params.limit)
                 query.set('limit', params.limit.toString());
             const data = await callDataAPI(`/search?${query.toString()}`);
+            recordSearchTelemetry(context, data);
             context.output.writeData(data);
             break;
         }
@@ -1145,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) {
@@ -1163,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/config.d.ts

@@ -27,7 +27,8 @@ export declare function saveCliConfig(update: CliConfig): void;
 export declare function resolveApiKey(options?: ProfileIOOptions): string | undefined;
 /**
  * Resolve the ingest worker base URL used by `moda workspace snapshot`.
- * Env override -> persisted config -> production default.
+ * Env override -> active profile -> legacy config -> production default.
+ * Loopback URLs are rejected unless the active profile is `local`.
  */
 export declare function resolveIngestUrl(options?: ProfileIOOptions): string;
 /**

package/dist/config.js

@@ -1,11 +1,11 @@
 import { readFileSync } from 'node:fs';
-import { DEFAULT_INGEST_URL, PROD_BASE_URL, getLegacyConfigPath, loadLegacyCliConfig, resolveApiKeyFromActiveProfile, resolveBaseUrl, resolveIngestUrlFromActiveProfile, resolveTenantIdFromActiveProfile, syncLegacyConfigToProfile, writeLegacyCliConfig, } from './profiles.js';
+import { DEFAULT_INGEST_URL, PROD_BASE_URL, getLegacyConfigPath, loadLegacyCliConfig, resolveApiKeyFromActiveProfile, resolveBaseUrl, resolveIngestUrl as resolveProfileIngestUrl, resolveTenantIdFromActiveProfile, syncLegacyConfigToProfile, writeLegacyCliConfig, } from './profiles.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = pkg.version;
-// Canonical host is www.moda.dev. The apex `moda.dev` 308-redirects to it, and
+// Canonical host is moda.dev. The www host 308-redirects to the apex, and
 // cross-host redirects strip the Authorization header (fetch/undici), so using
-// the apex breaks `moda init`'s authenticated calls with a 401. Default to the
-// canonical host directly.
+// www breaks `moda init`'s authenticated calls with a 401. Default to the
+// canonical host directly; resolveBaseUrl() also rewrites legacy www URLs.
 export const MODA_BASE_URL = resolveBaseUrl();
 export function loadCliConfig(options = {}) {
     return loadLegacyCliConfig(options);
@@ -38,14 +38,11 @@ export function resolveApiKey(options = {}) {
 }
 /**
  * Resolve the ingest worker base URL used by `moda workspace snapshot`.
- * Env override -> persisted config -> production default.
+ * Env override -> active profile -> legacy config -> production default.
+ * Loopback URLs are rejected unless the active profile is `local`.
  */
 export function resolveIngestUrl(options = {}) {
-    const env = options.env ?? process.env;
-    return (env.MODA_INGEST_URL ||
-        resolveIngestUrlFromActiveProfile(options) ||
-        loadCliConfig(options).ingest_url ||
-        DEFAULT_INGEST_URL);
+    return resolveProfileIngestUrl(options);
 }
 /**
  * Resolve the active tenant id: env override first, then the persisted

package/dist/profiles.d.ts

@@ -1,5 +1,5 @@
 export declare const PROFILE_CONFIG_VERSION = 1;
-export declare const PROD_BASE_URL = "https://www.moda.dev";
+export declare const PROD_BASE_URL = "https://moda.dev";
 export declare const DEFAULT_INGEST_URL = "https://moda-ingest.modas.workers.dev";
 export declare const DEFAULT_PROFILE_NAME = "prod";
 export type ModaEnvironment = 'local' | 'dev' | 'staging' | 'prod';
@@ -71,6 +71,7 @@ export declare function getLegacyConfigPath(options?: ProfileIOOptions): string;
 export declare function loadLegacyCliConfig(options?: ProfileIOOptions): LegacyCliConfig;
 export declare function writeLegacyCliConfig(update: LegacyCliConfig, options?: ProfileIOOptions): LegacyCliConfig;
 export declare function createDefaultProfiles(options?: ProfileIOOptions): Record<string, ModaProfile>;
+export declare function isLoopbackBaseUrl(url: string): boolean;
 export declare function assertValidProfileName(name: string): void;
 export declare function inspectProfileMigrationState(options?: ProfileIOOptions): ProfileMigrationState;
 export declare function loadProfileConfig(options?: ProfileIOOptions): ProfileConfig;
@@ -82,7 +83,14 @@ export declare function syncLegacyConfigToProfile(legacy: LegacyCliConfig, optio
 export declare function secretFilePathFromRef(reference: SecretReference, options?: ProfileIOOptions): string | undefined;
 export declare function resolveSecretReference(reference: SecretReference | undefined, options?: ProfileIOOptions): string | undefined;
 export declare function resolveApiKeyFromActiveProfile(options?: ProfileIOOptions): string | undefined;
+/**
+ * Vercel serves moda.dev as canonical and 308-redirects www to the apex. Node
+ * fetch strips Authorization on cross-host redirects, which breaks moda init
+ * step 3 when the base URL still points at www.
+ */
+export declare function normalizeModaBaseUrl(url: string): string;
 export declare function resolveBaseUrl(options?: ProfileIOOptions): string;
+export declare function resolveIngestUrl(options?: ProfileIOOptions): string;
 export declare function resolveIngestUrlFromActiveProfile(options?: ProfileIOOptions): string | undefined;
 export declare function resolveTenantIdFromActiveProfile(options?: ProfileIOOptions): string | undefined;
 export declare function ensureSecretFilePermissions(path: string, repair?: boolean): SecretFilePermissionStatus;

package/dist/profiles.js

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, normalize, relative } from 'node:path';
 export const PROFILE_CONFIG_VERSION = 1;
-export const PROD_BASE_URL = 'https://www.moda.dev';
+export const PROD_BASE_URL = 'https://moda.dev';
 export const DEFAULT_INGEST_URL = 'https://moda-ingest.modas.workers.dev';
 export const DEFAULT_PROFILE_NAME = 'prod';
 function getEnv(options = {}) {
@@ -93,6 +93,65 @@ export function createDefaultProfiles(options = {}) {
         prod: profileDefaults('prod', 'prod', now),
     };
 }
+function isLoopbackHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host === '[::1]');
+}
+export function isLoopbackBaseUrl(url) {
+    try {
+        return isLoopbackHostname(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function defaultBaseUrlForEnvironment(environment) {
+    if (environment === 'local')
+        return 'http://localhost:3000';
+    if (environment === 'staging')
+        return 'https://staging.moda.dev';
+    return PROD_BASE_URL;
+}
+function defaultIngestUrlForEnvironment(environment) {
+    if (environment === 'local')
+        return 'http://localhost:8787';
+    return DEFAULT_INGEST_URL;
+}
+function environmentAllowsLoopback(environment) {
+    return environment !== 'prod';
+}
+function sanitizeProfileBaseUrl(url, environment) {
+    const normalized = normalizeModaBaseUrl(url);
+    if (environmentAllowsLoopback(environment) || !isLoopbackBaseUrl(normalized)) {
+        return normalized;
+    }
+    return PROD_BASE_URL;
+}
+function sanitizeProfileIngestUrl(url, environment) {
+    if (!url)
+        return url;
+    if (environmentAllowsLoopback(environment) || !isLoopbackBaseUrl(url)) {
+        return url;
+    }
+    return DEFAULT_INGEST_URL;
+}
+function enforceNonLoopbackBaseUrl(url, environment) {
+    return sanitizeProfileBaseUrl(url, environment);
+}
+function enforceNonLoopbackIngestUrl(url, environment) {
+    return sanitizeProfileIngestUrl(url, environment) ?? defaultIngestUrlForEnvironment(environment);
+}
+function activeProfileEnvironment(options) {
+    try {
+        return getActiveProfile(options).environment;
+    }
+    catch {
+        return 'prod';
+    }
+}
 function normalizeEnvironment(value) {
     if (value === 'local' ||
         value === 'dev' ||
@@ -131,8 +190,8 @@ function normalizeProfile(fallbackName, value, options) {
     const defaults = profileDefaults(name, normalizeEnvironment(value.environment), options.now ?? new Date());
     return {
         ...defaults,
-        base_url: optionalString(value.base_url) ?? defaults.base_url,
-        ingest_url: optionalString(value.ingest_url) ?? defaults.ingest_url,
+        base_url: sanitizeProfileBaseUrl(optionalString(value.base_url) ?? defaults.base_url, normalizeEnvironment(value.environment)),
+        ingest_url: sanitizeProfileIngestUrl(optionalString(value.ingest_url) ?? defaults.ingest_url, normalizeEnvironment(value.environment)),
         tenant_id: optionalString(value.tenant_id),
         workspace_id: optionalString(value.workspace_id),
         api_key_ref: normalizeSecretReference(value.api_key_ref),
@@ -170,9 +229,12 @@ function applyLegacyAwareness(config, options) {
     const migration = inspectProfileMigrationState(options);
     const prod = config.profiles.prod;
     if (prod && (legacy.api_key || legacy.ingest_url || legacy.tenant_id)) {
+        const migratedIngestUrl = legacy.ingest_url && !isLoopbackBaseUrl(legacy.ingest_url)
+            ? legacy.ingest_url
+            : prod.ingest_url;
         config.profiles.prod = {
             ...prod,
-            ingest_url: legacy.ingest_url ?? prod.ingest_url,
+            ingest_url: migratedIngestUrl,
             tenant_id: legacy.tenant_id ?? prod.tenant_id,
             api_key_ref: legacy.api_key ? 'legacy:config.api_key' : prod.api_key_ref,
             auth_token_ref: migration.legacy_auth.has_access_token
@@ -343,17 +405,58 @@ export function resolveApiKeyFromActiveProfile(options = {}) {
         return undefined;
     }
 }
+/**
+ * Vercel serves moda.dev as canonical and 308-redirects www to the apex. Node
+ * fetch strips Authorization on cross-host redirects, which breaks moda init
+ * step 3 when the base URL still points at www.
+ */
+export function normalizeModaBaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname === 'www.moda.dev') {
+            parsed.hostname = 'moda.dev';
+            return parsed.toString().replace(/\/$/, '');
+        }
+    }
+    catch {
+        // Not a valid URL; return unchanged and let the caller surface the error.
+    }
+    return url.replace(/\/$/, '');
+}
 export function resolveBaseUrl(options = {}) {
+    const environment = activeProfileEnvironment(options);
     const envBase = optionalString(getEnv(options).MODA_BASE_URL);
-    if (envBase)
-        return envBase;
+    if (envBase) {
+        return enforceNonLoopbackBaseUrl(normalizeModaBaseUrl(envBase), environment);
+    }
     try {
-        return getActiveProfile(options).base_url || PROD_BASE_URL;
+        return enforceNonLoopbackBaseUrl(normalizeModaBaseUrl(getActiveProfile(options).base_url || PROD_BASE_URL), environment);
     }
     catch {
         return PROD_BASE_URL;
     }
 }
+export function resolveIngestUrl(options = {}) {
+    const environment = activeProfileEnvironment(options);
+    const envIngest = optionalString(getEnv(options).MODA_INGEST_URL);
+    if (envIngest) {
+        return enforceNonLoopbackIngestUrl(envIngest, environment);
+    }
+    try {
+        const profileIngest = getActiveProfile(options).ingest_url;
+        if (profileIngest) {
+            return enforceNonLoopbackIngestUrl(profileIngest, environment);
+        }
+    }
+    catch {
+        // Fall through to legacy/default below.
+    }
+    const legacyIngest = optionalString(loadLegacyCliConfig(options).ingest_url);
+    if (legacyIngest) {
+        return enforceNonLoopbackIngestUrl(legacyIngest, environment);
+    }
+    return defaultIngestUrlForEnvironment(environment);
+}
 export function resolveIngestUrlFromActiveProfile(options = {}) {
     try {
         return getActiveProfile(options).ingest_url;

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.1",
+  "version": "1.9.6",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {
@@ -13,8 +13,7 @@
     "!dist/__tests__",
     "hooks/**",
     "skills/**/SKILL.md",
-    "README.md",
-    ".env.example"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

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>`.

package/.env.example

@@ -1,8 +0,0 @@
-# Moda API Key (required)
-# Get this from https://moda.dev/settings
-MODA_API_KEY=moda_sk_...
-
-# Moda Backend URL (optional)
-# Defaults to production: https://moda.dev
-# For local development, override with:
-# MODA_BASE_URL=http://localhost:3001