@moda-ai/cli 1.21.0 → 1.22.1

package/README.md

@@ -58,6 +58,9 @@ moda tool-failures                               # Tool failure overview
 moda tool-failure-detail <tool_name>             # Per-tool failure detail
 moda tool-failure-detail <tool_name> --include-window --window=1
 
+moda feedback "cluster label looks wrong"        # Help us improve: flag wrong/missing data
+moda feedback "..." --category=missing_data --conversation-id=<id>
+
 # Prompt management
 moda prompts init                                # Create .moda/prompts.yml
 moda prompts status                              # Read-only local prompt status

package/dist/api-client.d.ts

@@ -14,7 +14,7 @@ export declare class ApiError extends Error {
 export declare class NetworkError extends Error {
     constructor(message: string);
 }
-export declare function callDataAPI(endpoint: string): Promise<unknown>;
+export declare function callDataAPI(endpoint: string, init?: RequestInit, requestOptions?: ModaRequestOptions): Promise<unknown>;
 /**
  * Per-call transport overrides. Used by expensive, long-running, non-idempotent
  * endpoints (e.g. the agent `ask` POST) that need a longer timeout than the

package/dist/api-client.js

@@ -31,10 +31,10 @@ export class NetworkError extends Error {
 function isRetryable(status) {
     return status === 429 || status >= 500;
 }
-export async function callDataAPI(endpoint) {
+export async function callDataAPI(endpoint, init = { method: 'GET' }, requestOptions = {}) {
     apiRequestCount++;
     const url = `${resolveModaBaseUrl()}/api/v1/data${endpoint}`;
-    return callModaAPI(url, { method: 'GET' });
+    return callModaAPI(url, init, {}, requestOptions);
 }
 export async function callControlAPI(endpoint, options = {}, profileOptions = {}, requestOptions = {}) {
     const url = `${resolveModaBaseUrl(profileOptions)}/api${endpoint}`;

package/dist/cli.d.ts

@@ -21,6 +21,12 @@ export declare function flagsToArgs(flags: Record<string, string>, positionalKey
  * reusing this for a command with positionals.
  */
 export declare function buildResumeCommand(command: string, flags: Record<string, string>): string[];
+/**
+ * Coarse caller identity for the feedback body's `agent` field. Same
+ * truthy-env semantics as the agent-environment detection in output.ts;
+ * never sourced from flags, because `--agent` is the output-mode flag.
+ */
+export declare function detectCallerAgent(env: NodeJS.ProcessEnv): string;
 export declare function runCommand(command: string, positional: string | undefined, flags: Record<string, string>, positionals?: string[], context?: CommandContext): Promise<number>;
 interface CommandDispatchResult {
     exitCode: number;

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, SearchSchema, WorldStateSchema, ContextSchema, AuditSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, } from './schemas.js';
+import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, SearchSchema, WorldStateSchema, ContextSchema, AuditSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, FeedbackSchema, FEEDBACK_CATEGORIES, FEEDBACK_SEVERITIES, } from './schemas.js';
 import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
 import { runPromptsCommand } from './prompts.js';
 import { runSkillsCommand } from './skills.js';
@@ -170,6 +170,7 @@ Commands:
   frustrations                     Get user frustration detections
   tool-failures                    Get tool failure overview
   tool-failure-detail <tool_name>  Get per-tool failure detail
+  feedback "<note>"                Flag wrong/missing data or CLI quirks to the Moda team
 
   Prompt management:
   prompts init                     Create .moda/prompts.yml
@@ -235,6 +236,16 @@ 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)
 
+Feedback flags:
+  --category=CAT                   bad_cluster_label|mismatched_frustration|missing_data|noisy_data|
+                                   wrong_tool_failure|incorrect_loop|api_quirk|other (default other)
+  --severity=info|low|medium|high  How bad it is (default low)
+  --conversation-id=ID             Attach the conversation you were looking at
+  --cluster-id=ID                  Attach a cluster node id
+  --tool-name=NAME                 Attach a tool name
+  --run-id=ID                      Attach a run id
+  (set MODA_CLI_TIPS=0 to hide the feedback tip line)
+
 Init flags:
   --yes                            Accept all defaults (non-interactive)
   --analyst=auto|claude|codex|cursor|local-scan
@@ -310,6 +321,7 @@ Examples:
   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 feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=<node_id>
   moda context <conversation_id> --window=3
   moda audit <conversation_id|trace_id>
   moda audit <trace_id> --kind=trace --json
@@ -421,6 +433,21 @@ function recordConversationsTelemetry(context, data) {
         has_more: hasMore === true ? 'yes' : hasMore === false ? 'no' : 'na',
     });
 }
+/**
+ * Coarse caller identity for the feedback body's `agent` field. Same
+ * truthy-env semantics as the agent-environment detection in output.ts;
+ * never sourced from flags, because `--agent` is the output-mode flag.
+ */
+export function detectCallerAgent(env) {
+    const truthy = (value) => value != null && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+    if (truthy(env.CLAUDECODE))
+        return 'claude-code';
+    if (truthy(env.CURSOR))
+        return 'cursor';
+    if (truthy(env.MODA_AGENT) || truthy(env.CI))
+        return 'agent';
+    return 'human';
+}
 export async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
     switch (command) {
         case 'prompts': {
@@ -624,6 +651,54 @@ export async function runCommand(command, positional, flags, positionals = posit
             await printWithOptionalWindows(withToolFailureAnchors(data), 'examples', params.include_window === true, params.window ?? 1, context.output);
             break;
         }
+        case 'feedback': {
+            // Join every positional so an unquoted multi-word note is kept whole
+            // instead of silently truncating to the first word.
+            const note = positionals.join(' ').trim();
+            if (note === '') {
+                throw new CliInputError('<note> is required', `Usage: moda feedback "<note>" [--category=${FEEDBACK_CATEGORIES.join('|')}] [--severity=${FEEDBACK_SEVERITIES.join('|')}] [--conversation-id=ID] [--cluster-id=ID] [--tool-name=NAME] [--run-id=ID]`);
+            }
+            // Raw flag strings, not flagsToArgs: its numeric coercion would turn a
+            // purely numeric id ("--conversation-id=873459") into a number that
+            // FeedbackSchema's z.string() rejects.
+            const params = FeedbackSchema.parse({
+                note,
+                ...(flags.category !== undefined ? { category: flags.category } : {}),
+                ...(flags.severity !== undefined ? { severity: flags.severity } : {}),
+                ...(flags['conversation-id'] !== undefined ? { conversation_id: flags['conversation-id'] } : {}),
+                ...(flags['cluster-id'] !== undefined ? { cluster_id: flags['cluster-id'] } : {}),
+                ...(flags['tool-name'] !== undefined ? { tool_name: flags['tool-name'] } : {}),
+                ...(flags['run-id'] !== undefined ? { run_id: flags['run-id'] } : {}),
+            });
+            const refs = {};
+            if (params.conversation_id)
+                refs.conversation_id = params.conversation_id;
+            if (params.cluster_id)
+                refs.cluster_id = params.cluster_id;
+            if (params.tool_name)
+                refs.tool_name = params.tool_name;
+            if (params.run_id)
+                refs.run_id = params.run_id;
+            const category = params.category ?? 'other';
+            const severity = params.severity ?? 'low';
+            // retries: 0. The backend mints a fresh feedback_id per request and
+            // moda.agent_feedback has no dedup layer, so a retried POST after a
+            // lost response would insert duplicate rows.
+            const data = await callDataAPI('/feedback', {
+                method: 'POST',
+                body: JSON.stringify({
+                    category,
+                    severity,
+                    source: 'cli',
+                    agent: detectCallerAgent(process.env),
+                    cli_version: VERSION,
+                    note: params.note,
+                    ...(Object.keys(refs).length > 0 ? { refs } : {}),
+                }),
+            }, { retries: 0 });
+            context.output.writeData({ submitted: true, category, severity, ...(asRecord(data) ?? {}) }, { summary: 'Feedback submitted. Thank you for helping us improve!' });
+            break;
+        }
         default:
             throw new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
     }
@@ -1036,6 +1111,16 @@ export const commandRegistry = createCommandRegistry([
         examples: ['moda tool-failure-detail search --include-window'],
         ...dataApiDefaults,
     }),
+    legacyCommand({
+        name: 'feedback',
+        description: 'Flag wrong/missing data or CLI quirks to the Moda team',
+        examples: [
+            'moda feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=<node_id>',
+            'moda feedback "search finds nothing for a conversation I can open" --category=missing_data --conversation-id=<id>',
+        ],
+        ...dataApiDefaults,
+        mutability: 'write',
+    }),
     legacyCommand({
         name: 'prompts',
         description: 'Manage prompt versions and labels',
@@ -1111,6 +1196,28 @@ export function printCliError(error) {
         safeWriteStderr(`Error: ${String(error)}\n`);
     }
 }
+/**
+ * Human-TTY twin of the envelope `meta.tip`: one dim stderr line after a
+ * successful command. stderr only (stdout stays machine-readable), TTY only
+ * (pipes/CI stay noise-free), and MODA_CLI_TIPS=0 opts out.
+ */
+function printFeedbackTip(commandName, context) {
+    if (context.outputMode !== 'human' || context.output.quiet)
+        return;
+    if (commandName === 'feedback')
+        return;
+    if (!process.stderr.isTTY)
+        return;
+    // Intentional strict `=== '0'` (NOT the permissive truthy() used by
+    // detectCallerAgent): `MODA_CLI_TIPS=0` is the one documented opt-out form
+    // (manifest env list + docs), so keep this exact-match — don't "fix" it to
+    // match the other guards or it silently changes the published interface.
+    if (process.env.MODA_CLI_TIPS === '0')
+        return;
+    const text = 'Tip: Use `moda feedback "<note>"` to help us improve!';
+    const colorOk = !('NO_COLOR' in process.env) && process.env.TERM !== 'dumb';
+    safeWriteStderr(`\n${colorOk ? `\x1b[2m${text}\x1b[0m` : text}\n`);
+}
 function printAgentCliError(command, error, mode = 'agent') {
     const output = createCliOutput({
         command: command || 'unknown',
@@ -1236,6 +1343,7 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         if (!updateCheckDisabled) {
             printUpdateNotice();
         }
+        printFeedbackTip(definition.name, context);
         return finishRun(context, { kind: 'completed', exitCode: result.exitCode });
     }
     catch (error) {

package/dist/manifest.js

@@ -32,6 +32,7 @@ export function buildManifest(commands) {
             'MODA_AGENT_MAX_OUTPUT_BYTES',
             'MODA_CLI_TELEMETRY',
             'MODA_CLI_UPDATE_CHECK',
+            'MODA_CLI_TIPS',
         ],
         exit_codes: [
             { code: 0, name: 'ok', meaning: 'Command completed successfully.' },

package/dist/output.d.ts

@@ -2,6 +2,14 @@ import { type AgentAuthRequest, type AgentInputRequest } from './errors.js';
 export type CliOutputMode = 'human' | 'json' | 'agent' | 'agent-stream';
 export declare const AGENT_SCHEMA_VERSION = "moda.agent.v1";
 export declare const AGENT_EVENT_SCHEMA_VERSION = "moda.agent_event.v1";
+/**
+ * One-line feedback nudge stamped into every non-feedback success envelope's
+ * `meta.tip` (agents are the CLI's most common callers, and the envelope is
+ * where they actually look). Deliberately conditional wording so agents flag
+ * genuine observations instead of habitually running the command. The
+ * human-TTY twin is printed on stderr by the dispatcher in cli.ts.
+ */
+export declare const FEEDBACK_TIP = "Help us improve! If a result in this response looks wrong or is missing data, flag it: moda feedback \"<describe what looked wrong>\" [--category=...] [--conversation-id=... | --cluster-id=... | --tool-name=...]. Only submit genuine observations.";
 /**
  * Stable process exit codes that an external agent can branch on:
  *   0  ok        — grounded answer from Moda Cloud intelligence.

package/dist/output.js

@@ -3,6 +3,14 @@ import { CliAccessError, CliAuthError, CliCancellationError, CliInputError, CliI
 import { redactDeep } from './redact.js';
 export const AGENT_SCHEMA_VERSION = 'moda.agent.v1';
 export const AGENT_EVENT_SCHEMA_VERSION = 'moda.agent_event.v1';
+/**
+ * One-line feedback nudge stamped into every non-feedback success envelope's
+ * `meta.tip` (agents are the CLI's most common callers, and the envelope is
+ * where they actually look). Deliberately conditional wording so agents flag
+ * genuine observations instead of habitually running the command. The
+ * human-TTY twin is printed on stderr by the dispatcher in cli.ts.
+ */
+export const FEEDBACK_TIP = 'Help us improve! If a result in this response looks wrong or is missing data, flag it: moda feedback "<describe what looked wrong>" [--category=...] [--conversation-id=... | --cluster-id=... | --tool-name=...]. Only submit genuine observations.';
 /**
  * Stable process exit codes that an external agent can branch on:
  *   0  ok        — grounded answer from Moda Cloud intelligence.
@@ -214,6 +222,9 @@ export function createCliOutput(options) {
             meta: {
                 ...(writeOptions.meta ?? {}),
                 run_id: state.runId,
+                // No tip on the feedback command itself; it would point at the
+                // command that just ran.
+                ...(options.command === 'feedback' ? {} : { tip: FEEDBACK_TIP }),
             },
             summary: writeOptions.summary,
             findings: writeOptions.findings,

package/dist/schemas.d.ts

@@ -188,4 +188,38 @@ export declare const SearchSchema: z.ZodObject<{
     user_id?: string | undefined;
     include_tool_io?: boolean | undefined;
 }>;
+export declare const FEEDBACK_CATEGORIES: readonly ["bad_cluster_label", "mismatched_frustration", "missing_data", "noisy_data", "wrong_tool_failure", "incorrect_loop", "api_quirk", "other"];
+export declare const FEEDBACK_SEVERITIES: readonly ["info", "low", "medium", "high"];
+/**
+ * moda feedback "<note>": flag wrong/missing data or CLI quirks to the Moda
+ * team. The handler builds this input from raw flag strings (NOT flagsToArgs,
+ * whose numeric coercion would turn "--conversation-id=873459" into a number
+ * that z.string() rejects). max(4000) on note mirrors the backend
+ * @MaxLength(4000); the capped id fields become the POST body's `refs`.
+ */
+export declare const FeedbackSchema: z.ZodObject<{
+    note: z.ZodString;
+    category: z.ZodOptional<z.ZodDefault<z.ZodEnum<["bad_cluster_label", "mismatched_frustration", "missing_data", "noisy_data", "wrong_tool_failure", "incorrect_loop", "api_quirk", "other"]>>>;
+    severity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["info", "low", "medium", "high"]>>>;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    cluster_id: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    run_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    note: string;
+    run_id?: string | undefined;
+    severity?: "high" | "medium" | "low" | "info" | undefined;
+    category?: "bad_cluster_label" | "mismatched_frustration" | "missing_data" | "noisy_data" | "wrong_tool_failure" | "incorrect_loop" | "api_quirk" | "other" | undefined;
+    conversation_id?: string | undefined;
+    tool_name?: string | undefined;
+    cluster_id?: string | undefined;
+}, {
+    note: string;
+    run_id?: string | undefined;
+    severity?: "high" | "medium" | "low" | "info" | undefined;
+    category?: "bad_cluster_label" | "mismatched_frustration" | "missing_data" | "noisy_data" | "wrong_tool_failure" | "incorrect_loop" | "api_quirk" | "other" | undefined;
+    conversation_id?: string | undefined;
+    tool_name?: string | undefined;
+    cluster_id?: string | undefined;
+}>;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.js

@@ -93,4 +93,34 @@ export const SearchSchema = z.object({
     limit: z.number().min(1).max(100).default(20).optional(),
     include_tool_io: z.boolean().default(false).optional(),
 });
+// Enums mirror the backend FeedbackBodyDto (VALID_FEEDBACK_CATEGORIES /
+// VALID_FEEDBACK_SEVERITIES) so a bad value fails locally instead of
+// round-tripping a 400.
+export const FEEDBACK_CATEGORIES = [
+    'bad_cluster_label',
+    'mismatched_frustration',
+    'missing_data',
+    'noisy_data',
+    'wrong_tool_failure',
+    'incorrect_loop',
+    'api_quirk',
+    'other',
+];
+export const FEEDBACK_SEVERITIES = ['info', 'low', 'medium', 'high'];
+/**
+ * moda feedback "<note>": flag wrong/missing data or CLI quirks to the Moda
+ * team. The handler builds this input from raw flag strings (NOT flagsToArgs,
+ * whose numeric coercion would turn "--conversation-id=873459" into a number
+ * that z.string() rejects). max(4000) on note mirrors the backend
+ * @MaxLength(4000); the capped id fields become the POST body's `refs`.
+ */
+export const FeedbackSchema = z.object({
+    note: z.string().min(1).max(4000),
+    category: z.enum(FEEDBACK_CATEGORIES).default('other').optional(),
+    severity: z.enum(FEEDBACK_SEVERITIES).default('low').optional(),
+    conversation_id: z.string().min(1).max(256).optional(),
+    cluster_id: z.string().min(1).max(256).optional(),
+    tool_name: z.string().min(1).max(256).optional(),
+    run_id: z.string().min(1).max(256).optional(),
+});
 //# sourceMappingURL=schemas.js.map

package/dist/skills.js

@@ -653,7 +653,7 @@ export async function runSkillsCommand(input) {
         return 0;
     }
     if (sub !== 'pull') {
-        throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk|coding-agent] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--replay-set-id=ID] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills status [run-id] | moda skills proposals list [--status=ready_for_pr] | moda skills proposal apply <proposal-id> | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
+        throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--replay-set-id=ID] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills status [run-id] | moda skills proposals list [--status=ready_for_pr] | moda skills proposal apply <proposal-id> | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
     }
     const status = (flags.status ?? 'approved').toLowerCase();
     if (!VALID_STATUSES.has(status)) {
@@ -690,6 +690,11 @@ async function generateSkills(flags) {
         : `${resolveIngestUrl().replace(/\/+$/, '')}/v1/skills/generate`;
     const waitForCompletion = flags.wait === 'true' || flags['wait-for-completion'] === 'true';
     const forceReprocess = flags['force-reprocess'] === 'true';
+    const source = normalizeSkillSource(flags.source);
+    // Soft-deprecate: still accepted so old CLIs don't hard-fail; server returns empty.
+    if (source === 'coding_agent') {
+        console.error('Note: --source=coding-agent is deprecated for skills gen (SDK-only). The run will find no coding-agent sessions; use --source=all or --source=sdk.');
+    }
     const body = compactObject({
         tenant_id: tenantId || undefined,
         max_sessions: parsePositiveInt(flags['max-sessions'], 0),
@@ -699,7 +704,7 @@ async function generateSkills(flags) {
         clustering_run_id: flags['clustering-run-id'] || undefined,
         replay_set_id: flags['replay-set-id'] || flags['eval-set-id'] || undefined,
         run_clustering: flags['no-clustering'] !== 'true',
-        source: normalizeSkillSource(flags.source),
+        source,
         clustering_timeout_seconds: parsePositiveInt(flags['clustering-timeout-seconds'], 7200),
         clustering_poll_seconds: parsePositiveInt(flags['clustering-poll-seconds'], 15),
         max_cluster_pct: parseOptionalFloat(flags['max-cluster-pct']),
@@ -745,6 +750,7 @@ function compactObject(input) {
 }
 function normalizeSkillSource(value) {
     const normalized = (value || 'all').toLowerCase().replace(/-/g, '_');
+    // coding_agent kept for soft-deprecation (empty server result + stderr note).
     if (['all', 'sdk', 'coding_agent'].includes(normalized))
         return normalized;
     return 'all';

package/package.json

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

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-07-12T21:12:37.084Z",
-  "cli_version": "1.21.0",
+  "bundled_at": "2026-07-17T10:36:50.172Z",
+  "cli_version": "1.22.1",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 2.1.0
+version: 2.2.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, 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, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
 ---
 
@@ -680,6 +680,33 @@ done
 moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
 ```
 
+## 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 conversations,
+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 conversations" \
+  --category=bad_cluster_label --cluster-id=<node_id>
+moda feedback "search finds nothing for a conversation 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>
+```
+
+- `<note>` is required (max 4000 chars). Say what looked wrong and why.
+- `--category`: `bad_cluster_label | mismatched_frustration | missing_data |
+  noisy_data | wrong_tool_failure | incorrect_loop | api_quirk | other`
+  (default `other`).
+- `--severity`: `info | low | medium | high` (default `low`).
+- Attach ids when you have them: `--conversation-id`, `--cluster-id`,
+  `--tool-name`, `--run-id`; they let the team reproduce what you saw.
+- Never include secrets or full transcripts in the note.
+
 ## Validation — how to know it worked
 
 - Every successful command exits 0 and prints valid JSON to stdout.
@@ -748,6 +775,7 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda frustrations` | User frustration detections with evidence |
 | `moda tool-failures` | Tool failure overview |
 | `moda tool-failure-detail <tool_name>` | Per-tool failure breakdown + examples |
+| `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 local prompt diff/status |
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |