@moda-ai/cli 1.37.0 → 1.39.0

package/dist/cli.js

@@ -8,11 +8,13 @@ import {
   runPromptsCommand,
   runSkillsCommand,
   runStatusCommand
-} from "./cli-ert1sbbt.js";
+} from "./cli-a7ypptsf.js";
 import {
   ApiError,
   HARNESS_REPORT_APPROVAL_PATH,
   HARNESS_REPORT_PATH,
+  SIGNALS_MANAGEMENT_SUBCOMMANDS,
+  assertFlags,
   callControlAPI,
   callDataAPI,
   getApiRequestCount,
@@ -24,12 +26,17 @@ import {
   renderMarkdownForTerminal,
   resetApiRequestCount,
   runHarnessCommand,
+  runProblemReopenCommand,
+  runSignalsManagementCommand,
+  runUserCommand,
+  runUsersCommand,
   shouldColorTerminalOutput,
   stripAnsi,
   summarizeHarness,
   terminalStyles,
+  unknownSignalsSubcommandError,
   validateHarnessReport
-} from "./cli-07tv75te.js";
+} from "./cli-xsmsjny3.js";
 import"./cli-ssfq84k5.js";
 import {
   authFetch,
@@ -38,7 +45,7 @@ import {
   loadAuthSession,
   login,
   revokeCliSessionToken
-} from "./cli-strngwn3.js";
+} from "./cli-dyeywy9d.js";
 import {
   AGENT_ERROR_CODES,
   CliAccessError,
@@ -56,10 +63,12 @@ import {
   MODA_BASE_URL,
   PROD_BASE_URL,
   VERSION,
+  agentEnvelopeFits,
   assertValidProfileName,
   clearStoredApiKeyCredentials,
   createCliOutput,
   createCommandContext,
+  describeBaseUrlSource,
   embeddedTenantIdFromApiKey,
   ensureSecretFilePermissions,
   getActiveProfile,
@@ -70,6 +79,7 @@ import {
   loadProfileConfig,
   resolveApiKey,
   resolveApiKeyFromActiveProfile,
+  resolveApiTenantId,
   resolveIngestUrl,
   resolveModaBaseUrl,
   resolveOutputMode,
@@ -84,7 +94,7 @@ import {
   validateConfig,
   wasOutputCancelled,
   writeSecretJsonFile
-} from "./cli-q79sq80a.js";
+} from "./cli-rp912ypf.js";
 import {
   __require
 } from "./cli-0v6na3yp.js";
@@ -121,6 +131,7 @@ var ConversationsSchema = z.object({
   world_state: z.string().max(200).optional(),
   outcome: z.enum(["any", "positive", "negative"]).default("any").optional(),
   include_world_state: boolFlag(),
+  sort: z.enum(["recent", "longest", "slowest"]).optional(),
   limit: z.number().min(1).max(100).default(20).optional(),
   offset: z.number().min(0).default(0).optional()
 });
@@ -139,14 +150,19 @@ var WorldStateSchema = z.object({
 var ContextSchema = z.object({
   conversation_id: z.string(),
   msg_index: z.number().min(0).optional(),
-  window: z.number().min(1).max(5).default(2).optional()
+  window: z.number().min(1).max(5).default(2).optional(),
+  all: boolFlag(),
+  from: z.number().int().min(0).optional(),
+  max_messages: z.number().int().min(1).max(5000).optional()
 });
 var FrustrationsSchema = z.object({
   days_back: z.number().min(1).max(90).default(7).optional(),
   limit: z.number().min(1).max(20).default(10).optional(),
   offset: z.number().min(0).default(0).optional(),
   include_window: boolFlag(),
-  window: z.number().min(1).max(5).default(1).optional()
+  window: z.number().min(1).max(5).default(1).optional(),
+  user_id: z.string().min(1).max(256).optional(),
+  conversation_id: z.string().min(1).max(256).optional()
 });
 var ToolFailuresSchema = z.object({
   days_back: z.number().min(1).max(90).default(7).optional()
@@ -155,6 +171,21 @@ var ProblemsSchema = z.object({
   days_back: z.number().min(1).max(90).default(30).optional(),
   limit: z.number().min(1).max(25).default(25).optional()
 });
+var REMAINDER_FAMILIES = [
+  "tool_failure",
+  "emotion",
+  "laziness",
+  "hallucination",
+  "prm_dip",
+  "custom_signal",
+  "conversation_reader"
+];
+var ProblemsRemainderSchema = z.object({
+  days_back: z.number().min(1).max(90).default(30).optional(),
+  limit: z.number().min(1).max(25).default(25).optional(),
+  family: z.enum(REMAINDER_FAMILIES).optional(),
+  cursor: z.string().min(1).max(4096).optional()
+});
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var ProblemImpactSchema = z.object({
   node_id: z.string().min(1).max(256).optional(),
@@ -179,13 +210,7 @@ var ProblemImpactSchema = z.object({
 }).refine((p) => !p.cursor || p.mode === "evidence" && p.to && p.run_id, {
   message: "An evidence cursor requires --mode=evidence, --to, and --run-id from the previous response"
 });
-var PROBLEM_FAMILIES = [
-  "tool_failure",
-  "emotion",
-  "laziness",
-  "hallucination",
-  "prm_dip"
-];
+var PROBLEM_FAMILIES = REMAINDER_FAMILIES;
 var PROBLEM_DOORS = ["rubric_match", "local_causal_chain"];
 var ProblemSchema = z.object({
   id: z.string().min(1),
@@ -286,6 +311,7 @@ var FalsePositiveSchema = z.object({
 });
 var EMOTION_FAMILIES = [
   "frustration",
+  "disapproval",
   "sadness",
   "confusion",
   "anxiety",
@@ -296,7 +322,9 @@ var EmotionsSchema = z.object({
   days_back: z.number().min(1).max(90).default(7).optional(),
   limit: z.number().min(1).max(20).default(10).optional(),
   offset: z.number().min(0).max(1e4).optional(),
-  family: z.enum(EMOTION_FAMILIES).optional()
+  family: z.enum(EMOTION_FAMILIES).optional(),
+  user_id: z.string().min(1).max(256).optional(),
+  conversation_id: z.string().min(1).max(256).optional()
 });
 var HallucinationsSchema = z.object({
   days_back: z.number().min(1).max(90).default(7).optional(),
@@ -305,12 +333,33 @@ var HallucinationsSchema = z.object({
   conversation_id: z.string().max(200).optional(),
   kind: z.enum(["contradicted", "verified"]).optional()
 });
+var LAZINESS_FAMILIES = [
+  "omission_comment",
+  "omission_phrase",
+  "stub_body",
+  "refusal_prefix",
+  "deflection",
+  "data_quality_truncation",
+  "promise_no_delivery",
+  "capability_refusal_here",
+  "capability_refusal_verb",
+  "error_admission",
+  "irreversibility",
+  "stall_recheck",
+  "diy_handoff",
+  "tool_selection",
+  "completion",
+  "code_artifact",
+  "repeated_tool_call",
+  "target_overshoot",
+  "data_regression"
+];
 var LazinessSchema = z.object({
   days_back: z.number().min(1).max(90).default(7).optional(),
   limit: z.number().min(1).max(50).default(10).optional(),
   offset: z.number().min(0).max(1e4).optional(),
   conversation_id: z.string().max(200).optional(),
-  family: z.string().regex(/^[a-z_]{1,64}$/, "Family must be a lowercase laziness family").optional()
+  family: z.enum(LAZINESS_FAMILIES).optional()
 });
 var StepScoresSchema = z.object({
   conversation_id: z.string().min(1)
@@ -331,6 +380,7 @@ var ToolFailureDetailSchema = z.object({
   limit: z.number().min(1).max(20).default(5).optional(),
   offset: z.number().min(0).default(0).optional(),
   include_window: boolFlag(),
+  compact: boolFlag(),
   window: z.number().min(1).max(5).default(1).optional()
 });
 var AuditSchema = z.object({
@@ -347,7 +397,8 @@ var SearchSchema = z.object({
   user_id: z.string().optional(),
   time_range: z.enum(TIME_RANGES).default("all").optional(),
   limit: z.number().min(1).max(100).default(20).optional(),
-  include_tool_io: boolFlag()
+  include_tool_io: boolFlag(),
+  offset: z.number().min(0).max(1e4).optional()
 });
 var FEEDBACK_CATEGORIES = [
   "bad_cluster_label",
@@ -383,21 +434,27 @@ function asString(value) {
 function asNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function frustrationAnchorIndex(row) {
+  if (!row)
+    return null;
+  const userQuotes = Array.isArray(row.user_quotes) ? row.user_quotes : [];
+  const firstQuote = asRecord(userQuotes[0]);
+  const resolved = asNumber(firstQuote?.msg_index) ?? asNumber(row.anchor_msg_index);
+  if (resolved !== null)
+    return resolved;
+  const keyTurns = Array.isArray(row.key_turns) ? row.key_turns : [];
+  const firstTurn = keyTurns.find((t) => typeof t === "number");
+  if (firstTurn !== undefined)
+    return firstTurn;
+  return asNumber(firstQuote?.turn);
+}
 function buildFrustrationAnchor(row) {
   const conversation_id = asString(row.conversation_id) ?? "";
   const userQuotes = Array.isArray(row.user_quotes) ? row.user_quotes : [];
   const firstQuote = asRecord(userQuotes[0]);
   const keyTurnsRaw = Array.isArray(row.key_turns) ? row.key_turns : [];
   const all_turns = keyTurnsRaw.filter((t) => typeof t === "number");
-  let msg_index = null;
-  if (all_turns.length > 0) {
-    msg_index = all_turns[0];
-  }
-  if (msg_index === null && firstQuote) {
-    const turn = asNumber(firstQuote.turn);
-    if (turn !== null)
-      msg_index = turn;
-  }
+  const msg_index = frustrationAnchorIndex(row);
   let signal = null;
   let quote_preview = null;
   if (firstQuote) {
@@ -431,6 +488,43 @@ function buildToolFailureAnchor(row, toolName) {
     no_anchor: msg_index === null
   };
 }
+function frustrationsFromEmotions(response) {
+  if (!Array.isArray(response.detections) || Array.isArray(response.frustrations))
+    return response;
+  const summary = asRecord(response.summary) ?? {};
+  const pagination = asRecord(response.pagination) ?? {};
+  const byFamily = asRecord(summary.by_family) ?? {};
+  const totalAnalyzed = asNumber(summary.conversations_analyzed) ?? 0;
+  const frustrated = asNumber(byFamily.frustration) ?? 0;
+  const frustrations = response.detections.map((item) => asRecord(item)).filter((row) => row !== null && (row.family === undefined || row.family === "frustration")).map(({ conversation_context, score, is_detected, ...row }) => ({
+    ...row,
+    is_frustrated: is_detected === true,
+    frustration_score: score,
+    target: row.elicitor === "bot" || row.elicitor === "external" ? row.elicitor : "ambiguous",
+    conversation: conversation_context ?? null
+  }));
+  const atRisk = asNumber(pagination.at_risk) ?? Math.max(0, (asNumber(pagination.total) ?? 0) - frustrated);
+  const signalBreakdown = {};
+  for (const item of Array.isArray(response.signal_breakdown) ? response.signal_breakdown : []) {
+    const row = asRecord(item);
+    if (row?.family === "frustration" && typeof row.signal === "string") {
+      signalBreakdown[row.signal] = asNumber(row.count) ?? 0;
+    }
+  }
+  const { detections: _detections, ...rest } = response;
+  return {
+    ...rest,
+    summary: {
+      total_analyzed: totalAnalyzed,
+      frustrated_count: frustrated,
+      at_risk_count: atRisk,
+      frustration_rate_pct: totalAnalyzed > 0 ? Math.round(frustrated / totalAnalyzed * 1000) / 10 : 0
+    },
+    signal_breakdown: signalBreakdown,
+    frustrations,
+    source: "emotion_detections"
+  };
+}
 function withFrustrationAnchors(response) {
   if (!Array.isArray(response.frustrations))
     return response;
@@ -443,6 +537,76 @@ function withFrustrationAnchors(response) {
   });
   return { ...response, frustrations };
 }
+var TOOL_FAILURE_TEXT_LIMIT = 300;
+var TOOL_FAILURE_CONTEXT_RADIUS = 2;
+function shellWord(value) {
+  return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function trimFailureWindow(value, radius, fallbackCenter) {
+  const conv = asRecord(value);
+  if (!conv)
+    return value ?? null;
+  const { coverage: _coverage, context, ...convRest } = conv;
+  const ctx = asRecord(context);
+  if (!ctx)
+    return convRest;
+  const center = asNumber(ctx.center_index) ?? fallbackCenter;
+  const messages = (Array.isArray(ctx.messages) ? ctx.messages : []).map((message) => asRecord(message)).filter((message) => {
+    const index = asNumber(message?.index);
+    return message !== null && (center === null || index === null || Math.abs(index - center) <= radius);
+  }).map(({ content_blocks, ...message }) => {
+    const covered = typeof message.content === "string" && message.content.length > 0 || Array.isArray(message.tool_calls) && message.tool_calls.length > 0 || Array.isArray(message.tool_results) && message.tool_results.length > 0;
+    return covered || content_blocks === undefined ? message : { ...message, content_blocks };
+  });
+  const indexes = messages.map((message) => asNumber(message.index)).filter((index) => index !== null);
+  return {
+    ...convRest,
+    context: {
+      ...ctx,
+      ...indexes.length > 0 ? { from_index: Math.min(...indexes), to_index: Math.max(...indexes) } : {},
+      messages
+    }
+  };
+}
+function trimToolFailureConversations(response, opts) {
+  if (!Array.isArray(response.examples))
+    return response;
+  const examples = response.examples.map((item) => {
+    const row = asRecord(item);
+    if (!row)
+      return item;
+    const { conversation, window, ...rest } = row;
+    const conversationId = asString(row.conversation_id);
+    const msgIndex = asNumber(asRecord(row.anchor)?.msg_index) ?? asNumber(row.msg_index);
+    return {
+      ...rest,
+      ...conversationId && msgIndex !== null ? { context_command: `moda context ${shellWord(conversationId)} --msg-index=${msgIndex} --window=${TOOL_FAILURE_CONTEXT_RADIUS}` } : {},
+      ...opts.drop ? {} : { conversation: trimFailureWindow(conversation, TOOL_FAILURE_CONTEXT_RADIUS, msgIndex) },
+      ..."window" in row ? { window: trimFailureWindow(window, opts.windowRadius ?? TOOL_FAILURE_CONTEXT_RADIUS, msgIndex) } : {}
+    };
+  });
+  return { ...response, examples };
+}
+function compactToolFailureExamples(response, maxChars = TOOL_FAILURE_TEXT_LIMIT) {
+  if (!Array.isArray(response.examples))
+    return { data: response, truncated: 0 };
+  let truncated = 0;
+  const cap = (value) => {
+    if (typeof value === "string") {
+      if (value.length <= maxChars)
+        return value;
+      truncated += 1;
+      return `${value.slice(0, maxChars)}… [truncated ${value.length - maxChars} chars]`;
+    }
+    if (Array.isArray(value))
+      return value.map(cap);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, cap(child)]));
+    }
+    return value;
+  };
+  return { data: { ...response, examples: response.examples.map(cap) }, truncated };
+}
 function withToolFailureAnchors(response) {
   if (!Array.isArray(response.examples))
     return response;
@@ -482,8 +646,11 @@ import {
   openSync,
   readFileSync,
   realpathSync,
+  renameSync,
+  writeFileSync,
   writeSync
 } from "node:fs";
+import { createHash } from "node:crypto";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 var O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
 var ADVANCE_TIMEOUT_MS = 300000;
@@ -495,22 +662,60 @@ var DRIVE_PASS_INTERVAL_MS = 20000;
 var DRIVE_LIST_LIMIT = 100;
 var DRIVE_LIST_MAX_PAGES = 10;
 var DRAFT_BATCH_LIMIT_MAX = 25;
+var DRAFT_BATCH_LIMIT_DEFAULT = 5;
+var DRIVE_MAX_FIXES_DEFAULT = 3;
+var DRIVE_MAX_FIXES_MAX = 10;
+var VERIFY_COOLDOWN_MS = 10 * 60 * 1000;
+var REGATE_COOLDOWN_STATUSES = new Set(["VERIFIED", "GATE_FAILED", "GATE_INCONCLUSIVE"]);
 var DRAFT_BATCH_TIMEOUT_MS = 300000;
 var ADVANCING_STATUSES = new Set(["DRAFT", "SCOPING", "PROPOSING", "PROPOSED", "GATING"]);
 var FIX_USAGE = [
   "Usage: moda fixes [--status=S] [--limit=N] [--cursor=TOKEN]",
-  "       moda fixes draft-batch [--limit=N]           (N is 1-25, default 10)",
-  "       moda fixes drive [--status=S] [--timeout=ms] [--pass-interval=ms]",
+  "       moda fixes draft-batch [--limit=N]           (N is 1-25, default 5)",
+  "       moda fixes drive [--status=S] [--max-fixes=N] [--timeout=ms] [--pass-interval=ms]  (N is 1-10, default 3)",
   "       moda fix <fix_id> [--packet] [--wait]",
   "       moda fix start <problem_id> [--type=auto|prompt] [--wait] [--timeout=ms]",
-  "       moda fix verify <fix_id> [--prompt-file=PATH] [--no-wait] [--timeout=ms]",
+  "       moda fix verify <fix_id> [--prompt-file=PATH] [--no-wait] [--timeout=ms] [--yes]",
   "       moda fix checkout <fix_id>",
   "       moda fix submit <fix_id> --pr | --local-ref=<branch>",
   "       moda fix mark-applied <fix_id> [--note=TEXT]",
   "       moda fix dismiss <fix_id> --reason=TEXT"
 ].join(`
 `);
+var FIXES_SUBCOMMAND_FLAGS = {
+  list: ["cursor", "limit", "status"],
+  "draft-batch": ["limit"],
+  drive: ["status", "timeout", "pass-interval", "max-fixes"]
+};
+var FIX_SUBCOMMAND_FLAGS = {
+  detail: ["packet", "timeout", "wait", "poll-interval"],
+  start: ["timeout", "type", "wait", "poll-interval", "problem-id"],
+  verify: ["timeout", "wait", "fix-id", "no-wait", "poll-interval", "prompt-file"],
+  checkout: ["fix-id"],
+  submit: ["pr", "fix-id", "local-ref"],
+  "mark-applied": ["note", "fix-id"],
+  dismiss: ["reason", "fix-id"]
+};
+function assertWaitFlags(flags) {
+  const maxByFlag = {
+    timeout: MAX_WAIT_TIMEOUT_MS,
+    "poll-interval": MAX_POLL_INTERVAL_MS,
+    "pass-interval": MAX_POLL_INTERVAL_MS
+  };
+  for (const [name, max] of Object.entries(maxByFlag)) {
+    const raw = flags[name];
+    if (raw === undefined)
+      continue;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw.trim()) || !Number.isSafeInteger(value) || value < 1 || value > max) {
+      throw new CliInputError(`--${name}=${raw} must be a whole number of milliseconds between 1 and ${max}, so nothing was sent.`, FIX_USAGE);
+    }
+  }
+}
 async function runFixesCommand(context) {
+  const fixesSub = context.positional && FIXES_SUBCOMMAND_FLAGS[context.positional] ? context.positional : "list";
+  assertFlags(fixesSub === "list" ? "fixes" : `fixes ${fixesSub}`, context.flags, [...FIXES_SUBCOMMAND_FLAGS[fixesSub], "tenant-id"]);
+  assertWaitFlags(context.flags);
   validateConfig();
   const profileOptions = profileOptionsFor(context);
   const tenantId = requireTenantId(context.flags, profileOptions);
@@ -564,8 +769,8 @@ async function runFixesCommand(context) {
   return EXIT_OK;
 }
 async function runFixesDraftBatch(context, profileOptions, tenantId) {
-  const usage = "Usage: moda fixes draft-batch [--limit=N]  (N is 1-25, default 10)";
-  let limit;
+  const usage = "Usage: moda fixes draft-batch [--limit=N]  (N is 1-25, default 5)";
+  let limit = DRAFT_BATCH_LIMIT_DEFAULT;
   if (context.flags.limit) {
     const parsed = Number(context.flags.limit);
     if (!Number.isInteger(parsed) || parsed < 1 || parsed > DRAFT_BATCH_LIMIT_MAX) {
@@ -573,7 +778,7 @@ async function runFixesDraftBatch(context, profileOptions, tenantId) {
     }
     limit = parsed;
   }
-  const result = await callControlAPI(`${fixesBase(tenantId)}/draft-batch`, { method: "POST", body: JSON.stringify(limit !== undefined ? { limit } : {}) }, profileOptions, { timeoutMs: DRAFT_BATCH_TIMEOUT_MS, retries: 0 });
+  const result = await callControlAPI(`${fixesBase(tenantId)}/draft-batch`, { method: "POST", body: JSON.stringify({ limit }) }, profileOptions, { timeoutMs: DRAFT_BATCH_TIMEOUT_MS, retries: 0 });
   const drafted = result.drafted ?? [];
   const skipped = result.skipped ?? [];
   if (context.outputMode === "human") {
@@ -618,10 +823,53 @@ async function runFixesDraftBatch(context, profileOptions, tenantId) {
   });
   return EXIT_OK;
 }
+function driveStatePath(tenantId, profileOptions) {
+  const safeTenant = tenantId.replace(/[^A-Za-z0-9_-]/g, "_");
+  return join(getModaPaths(profileOptions).dir, `fixes-drive-last.${safeTenant}.json`);
+}
+function lastDrivenTimes(tenantId, profileOptions) {
+  try {
+    const raw = JSON.parse(readFileSync(driveStatePath(tenantId, profileOptions), "utf8"));
+    if (Array.isArray(raw)) {
+      return new Map(raw.filter((id) => typeof id === "string").map((id) => [id, Date.now()]));
+    }
+    const out = new Map;
+    for (const [id, at] of Object.entries(raw ?? {})) {
+      if (typeof at === "number" && Number.isFinite(at))
+        out.set(id, at);
+    }
+    return out;
+  } catch {
+    return new Map;
+  }
+}
+function recordDrivenFixIds(tenantId, ids, previous, profileOptions) {
+  try {
+    const now = Date.now();
+    const merged = new Map(previous);
+    for (const id of ids)
+      merged.set(id, now);
+    const entries = [...merged.entries()].sort((left, right) => right[1] - left[1]).slice(0, 500);
+    const path = driveStatePath(tenantId, profileOptions);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${now}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(Object.fromEntries(entries))}
+`, { mode: 384 });
+    renameSync(tmp, path);
+  } catch {}
+}
 async function runFixesDrive(context, profileOptions, tenantId) {
   const timeoutMs = parsePositiveInt(context.flags.timeout, DEFAULT_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS);
   const passIntervalMs = parsePositiveInt(context.flags["pass-interval"], DRIVE_PASS_INTERVAL_MS, MAX_POLL_INTERVAL_MS);
   const deadline = Date.now() + timeoutMs;
+  let maxFixes = DRIVE_MAX_FIXES_DEFAULT;
+  if (context.flags["max-fixes"] !== undefined) {
+    const parsed = Number(context.flags["max-fixes"]);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > DRIVE_MAX_FIXES_MAX) {
+      throw new CliInputError(`--max-fixes must be an integer between 1 and ${DRIVE_MAX_FIXES_MAX} (got ${context.flags["max-fixes"]}) — each driven fix can run hundreds of replay playouts`, FIX_USAGE);
+    }
+    maxFixes = parsed;
+  }
   const statusFilter = (context.flags.status ?? "").trim().toUpperCase();
   if (statusFilter && !ADVANCING_STATUSES.has(statusFilter)) {
     throw new CliInputError(`--status must be one of the advancing statuses (${[...ADVANCING_STATUSES].join(", ")}) — a resting fix has nothing to drive (got ${context.flags.status})`, FIX_USAGE);
@@ -669,10 +917,27 @@ async function runFixesDrive(context, profileOptions, tenantId) {
     }
   }
   const tracked = new Map;
-  for (const fix of snapshot) {
-    if (ADVANCING_STATUSES.has(fix.status) && !isRestingProposed(fix)) {
+  const skipped = [];
+  const advancing = snapshot.filter((fix) => ADVANCING_STATUSES.has(fix.status) && !isRestingProposed(fix));
+  const drivenAt = lastDrivenTimes(tenantId, profileOptions);
+  const rankOf = new Map(advancing.map((fix, index) => [fix.id, index]));
+  const byLeastRecent = [...advancing].sort((left, right) => {
+    const leftAt = drivenAt.get(left.id) ?? -1;
+    const rightAt = drivenAt.get(right.id) ?? -1;
+    return leftAt !== rightAt ? leftAt - rightAt : (rankOf.get(left.id) ?? 0) - (rankOf.get(right.id) ?? 0);
+  });
+  const picked = new Set(byLeastRecent.slice(0, maxFixes).map((fix) => fix.id));
+  for (const fix of advancing) {
+    if (picked.has(fix.id))
       tracked.set(fix.id, fix);
-    }
+    else
+      skipped.push(fix);
+  }
+  recordDrivenFixIds(tenantId, [...picked], drivenAt, profileOptions);
+  const gatingCount = [...tracked.values()].filter((fix) => fix.status === "GATING").length;
+  if (skipped.length > 0) {
+    coverageTruncated = true;
+    snapshotWarnings.push(`Drove ${tracked.size} fix(es) (--max-fixes=${maxFixes}; ${gatingCount} already gating; least-recently-driven first); skipped ${skipped.length} advancing fix(es): ${skipped.map((fix) => `MODA-FIX-${fix.shortRef}`).join(", ")}. Re-run \`moda fixes drive\` to drive the next ones.`);
   }
   if (tracked.size === 0) {
     context.output.writeData({
@@ -753,6 +1018,7 @@ async function runFixesDrive(context, profileOptions, tenantId) {
     statusReason: fix.statusReason ?? null
   }));
   const stragglers = [...tracked.values()].filter((fix) => !isRested(fix));
+  const skippedRefs = skipped.map((fix) => fix.shortRef);
   const warnings = [
     ...snapshotWarnings,
     ...[...errors.entries()].map(([fixId, message]) => {
@@ -779,7 +1045,9 @@ ${coverageTruncated ? `Rested all ${tracked.size} scanned fix(es)` : `All ${trac
     rested: restedCount,
     stragglers: stragglers.map((fix) => fix.shortRef),
     timedOut,
-    coverageTruncated
+    coverageTruncated,
+    maxFixes,
+    skipped: skippedRefs
   }, {
     ...degraded ? { status: "degraded" } : {},
     summary: {
@@ -788,27 +1056,38 @@ ${coverageTruncated ? `Rested all ${tracked.size} scanned fix(es)` : `All ${trac
     },
     ...warnings.length > 0 ? { warnings } : {},
     nextCommands: [
-      timedOut ? {
+      ...timedOut ? [{
         command: "moda fixes drive",
         purpose: "Resume driving the stragglers — advance-on-poll picks up where it left off.",
         mutability: "write",
         requires_approval: false
-      } : coverageTruncated ? {
-        command: !scanTruncated ? "moda fixes drive" : statusFilter ? "moda fix <fix_id> --wait" : "moda fixes drive --status=SCOPING",
-        purpose: !scanTruncated ? "The queue was re-ranked mid-page — re-run to pick up any fix that shifted past the boundary." : statusFilter ? `Status ${statusFilter} overflows the scan window — advance the older fixes individually.` : "Drive each advancing status separately to reach fixes outside the unfiltered scan window.",
-        mutability: "write",
-        requires_approval: false
-      } : {
+      }] : coverageTruncated ? [
+        ...skipped.length > 0 || !scanTruncated ? [{
+          command: "moda fixes drive",
+          purpose: skipped.length > 0 ? `Drive the next ${Math.min(skipped.length, maxFixes)} of the ${skipped.length} skipped fix(es) (--max-fixes spend cap).` : "The queue was re-ranked mid-page — re-run to pick up any fix that shifted past the boundary.",
+          mutability: "write",
+          requires_approval: false
+        }] : [],
+        ...scanTruncated ? [{
+          command: statusFilter ? "moda fix <fix_id> --wait" : "moda fixes drive --status=SCOPING",
+          purpose: statusFilter ? `Status ${statusFilter} overflows the scan window — advance the older fixes individually.` : "Drive each advancing status separately to reach fixes outside the unfiltered scan window.",
+          mutability: "write",
+          requires_approval: false
+        }] : []
+      ] : [{
         command: "moda fixes",
         purpose: "Review where every fix landed (VERIFIED fixes are ready to deliver).",
         mutability: "read",
         requires_approval: false
-      }
+      }]
     ]
   });
   return degraded ? EXIT_DEGRADED : EXIT_OK;
 }
 async function runFixCommand(context) {
+  const fixSub = context.positional && FIX_SUBCOMMAND_FLAGS[context.positional] ? context.positional : "detail";
+  assertFlags(fixSub === "detail" ? "fix" : `fix ${fixSub}`, context.flags, [...FIX_SUBCOMMAND_FLAGS[fixSub], "tenant-id"]);
+  assertWaitFlags(context.flags);
   validateConfig();
   const profileOptions = profileOptionsFor(context);
   const tenantId = requireTenantId(context.flags, profileOptions);
@@ -916,6 +1195,10 @@ async function runFixVerify(context, profileOptions, tenantId) {
       throw new CliInputError("--prompt-file content is shorter than 40 characters — refusing to gate a truncated candidate");
     }
   }
+  const candidateHash = candidateContent === undefined ? undefined : sha256(candidateContent.trim());
+  if (!context.yes) {
+    await assertRegateCooldown(tenantId, fixId, context, profileOptions, candidateHash);
+  }
   const enqueue = await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}/verify`, { method: "POST", body: JSON.stringify(candidateContent ? { candidateContent } : {}) }, profileOptions, { timeoutMs: 120000, retries: 0 });
   const noWait = context.flags.wait === "false" || context.flags["no-wait"] === "true";
   if (noWait) {
@@ -1267,7 +1550,7 @@ function profileOptionsFor(context) {
   return { profile: context.profile, env: context.env };
 }
 function requireTenantId(flags, profileOptions) {
-  const tenantId = flags["tenant-id"] || resolveTenantId(profileOptions);
+  const tenantId = flags["tenant-id"] || resolveApiTenantId(profileOptions);
   if (!tenantId) {
     throw new CliInputError("Missing tenant id. Run `moda init` or pass --tenant-id=<id>.");
   }
@@ -1276,6 +1559,29 @@ function requireTenantId(flags, profileOptions) {
 function fixesBase(tenantId) {
   return `/tenants/${encodeURIComponent(tenantId)}/fixes`;
 }
+async function assertRegateCooldown(tenantId, fixId, context, profileOptions, candidateHash) {
+  const current = await getFix(tenantId, fixId, profileOptions);
+  if (candidateHash && current.candidateRef?.contentSha256 !== candidateHash)
+    return;
+  const gate = current.gateResult ?? null;
+  if (!REGATE_COOLDOWN_STATUSES.has(current.status) || !gate?.verdict || gate.pending)
+    return;
+  const landedAt = typeof gate.completedAt === "string" ? Date.parse(gate.completedAt) : Number.NaN;
+  if (Number.isNaN(landedAt))
+    return;
+  const ageMs = Date.now() - landedAt;
+  if (ageMs >= VERIFY_COOLDOWN_MS)
+    return;
+  const waitMin = Math.ceil((VERIFY_COOLDOWN_MS - ageMs) / 60000);
+  const rerun = ["moda", "fix", "verify", fixId, ...Object.entries(context.flags).filter(([key]) => key !== "yes" && key !== "fix-id").map(([key, value]) => value === "true" ? `--${key}` : `--${key}=${shellQuote(value)}`), "--yes"].join(" ");
+  throw new CliInputError(`MODA-FIX-${current.shortRef} was gated ${Math.max(0, Math.floor(ageMs / 60000))} min ago (verdict ${gate.verdict}); re-gating within 10 minutes re-runs the replay. Nothing was sent.`, `Wait ~${waitMin} min, or re-run with --yes to gate now: ${rerun}`);
+}
+function sha256(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function shellQuote(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
 async function getFix(tenantId, fixId, profileOptions) {
   return await callControlAPI(`${fixesBase(tenantId)}/${encodeURIComponent(fixId)}`, { method: "GET" }, profileOptions);
 }
@@ -1753,6 +2059,443 @@ async function runSyncCommand(context) {
   throw new CliInputError(`Unknown sync resource '${resource}'.`, "Usage: moda sync [harness|prompts|skills] [--dry-run] [--profile=NAME]");
 }
 
+// src/registry.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, realpathSync as realpathSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, relative, resolve as resolve2 } from "node:path";
+var REGISTRY_SCHEMA = "moda_registry.v1";
+var DEFAULT_REGISTRY_PATH = ".moda/registry.json";
+var SKILL_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+var MAX_ITEMS_PER_SECTION = 500;
+var REGISTRY_TEMPLATE = {
+  schema: REGISTRY_SCHEMA,
+  prompts: [
+    {
+      key: "support.triage",
+      name: "Support triage system prompt",
+      description: "Routes inbound support messages",
+      content: "You are a support triage agent. Classify the request and ...",
+      sourcePath: "src/agents/triage/prompt.ts"
+    },
+    {
+      key: "support.reply",
+      file: "prompts/reply.md"
+    }
+  ],
+  skills: [
+    {
+      key: "refund-policy",
+      description: "How to process refund requests",
+      skillMd: `---
+name: refund-policy
+description: How to process refund requests
+---
+
+# Refund policy
+...`
+    }
+  ],
+  tools: [
+    {
+      schema: {
+        name: "lookup_customer",
+        description: "Find a customer by email",
+        parameters: {
+          type: "object",
+          properties: { email: { type: "string" } },
+          required: ["email"]
+        }
+      }
+    }
+  ]
+};
+var REGISTRY_SUBCOMMAND_FLAGS = {
+  template: ["out", "dry-run"],
+  validate: ["file", "manifest"],
+  push: ["file", "manifest", "live", "dry-run"]
+};
+async function runRegistryCommand(context) {
+  const subcommand = context.positionals[0] ?? "push";
+  assertFlags(`registry ${subcommand}`, context.flags, REGISTRY_SUBCOMMAND_FLAGS[subcommand] ?? []);
+  switch (subcommand) {
+    case "template":
+      return writeTemplate(context);
+    case "validate": {
+      const registry = loadRegistry(context);
+      context.output.writeData({
+        schema: REGISTRY_SCHEMA,
+        manifest: displayPath(context, registry.manifestPath),
+        valid: true,
+        counts: countsOf(registry)
+      });
+      return { exitCode: 0 };
+    }
+    case "push":
+      return pushRegistry(context);
+    default:
+      throw new CliInputError(`Unknown registry command '${subcommand}'.`, "Usage: moda registry template|validate|push [--file=.moda/registry.json] [--dry-run] [--live]");
+  }
+}
+function writeTemplate(context) {
+  const out = context.flags.out;
+  if (out === "true") {
+    throw new CliInputError("Missing output path for --out.", "Usage: moda registry template --out=.moda/registry.json");
+  }
+  if (!out) {
+    context.output.writeData(REGISTRY_TEMPLATE);
+    return { exitCode: 0 };
+  }
+  const target = resolve2(context.cwd, out);
+  if (existsSync2(target) && !context.yes) {
+    throw new CliInputError(`${out} already exists; refusing to overwrite.`, "Pass --yes to overwrite it.");
+  }
+  if (!context.dryRun) {
+    mkdirSync2(dirname2(target), { recursive: true });
+    writeFileSync2(target, `${JSON.stringify(REGISTRY_TEMPLATE, null, 2)}
+`);
+  }
+  context.output.writeData({ written: context.dryRun ? [] : [displayPath(context, target)], dryRun: context.dryRun });
+  return { exitCode: 0 };
+}
+async function pushRegistry(context) {
+  const registry = loadRegistry(context);
+  const profileOptions = { profile: context.profile, env: context.env };
+  const hasKey = Boolean(resolveApiKey(profileOptions));
+  if (!hasKey && !context.dryRun) {
+    throw new CliInputError("No Moda API key found for registry push.", "Set MODA_API_KEY, run `moda auth login --api-key=<key>`, or select a profile with an API key.");
+  }
+  const sections = [];
+  const push = async (section, endpoint, count, body) => {
+    if (count === 0) {
+      sections.push({ section, status: "skipped", count, endpoint });
+      return;
+    }
+    if (context.dryRun && !hasKey) {
+      sections.push({ section, status: "validated", count, endpoint });
+      return;
+    }
+    try {
+      const response = await callControlAPI(endpoint, { method: "POST", body: JSON.stringify({ ...body, ...context.dryRun ? { dryRun: true } : {} }) }, profileOptions);
+      sections.push({ section, status: context.dryRun ? "dry_run" : "synced", count, endpoint, response });
+    } catch (error) {
+      sections.push({
+        section,
+        status: "error",
+        count,
+        endpoint,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  };
+  await push("prompts", "/prompts/sync", registry.prompts.length, { prompts: registry.prompts });
+  await push("skills", "/skills/sync", registry.skills.length, { skills: registry.skills });
+  await push("tools", "/tool-definitions/sync", registry.tools.length, { tools: registry.tools });
+  const failed = sections.filter((section) => section.status === "error");
+  if (context.outputMode === "human" && !context.quiet) {
+    for (const section of sections) {
+      const detail = section.status === "error" ? ` — ${section.error}` : describeActions(section.response);
+      console.error(`  ${section.section}: ${section.status} (${section.count})${detail}`);
+    }
+  }
+  context.output.writeData({
+    schema: REGISTRY_SCHEMA,
+    manifest: displayPath(context, registry.manifestPath),
+    dryRun: context.dryRun,
+    counts: countsOf(registry),
+    sections
+  }, {
+    status: failed.length > 0 ? "error" : "success",
+    ...failed.length > 0 ? {
+      errors: failed.map((section) => ({
+        code: "registry_section_failed",
+        message: `${section.section}: ${section.error}`,
+        blocking: false
+      }))
+    } : {}
+  });
+  return { exitCode: failed.length > 0 ? 1 : 0 };
+}
+function describeActions(response) {
+  const synced = isRecord(response) && Array.isArray(response.synced) ? response.synced : [];
+  const counts = new Map;
+  for (const item of synced) {
+    if (!isRecord(item))
+      continue;
+    const action = typeof item.action === "string" ? `${item.action}${typeof item.reason === "string" ? ` (${item.reason})` : ""}` : item.changed === false ? "unchanged" : item.policyChanged === true && item.changed === true ? "changed (live setting)" : item.changed === true ? "changed" : "synced";
+    counts.set(action, (counts.get(action) ?? 0) + 1);
+  }
+  return counts.size > 0 ? ` — ${[...counts].map(([action, count]) => `${count} ${action}`).join(", ")}` : "";
+}
+function loadRegistry(context) {
+  const fileFlag = context.flags.file ?? context.flags.manifest;
+  if (fileFlag === "true") {
+    throw new CliInputError("Missing path for --file.", "Usage: moda registry push --file=.moda/registry.json");
+  }
+  const manifestPath = resolve2(context.cwd, fileFlag ?? DEFAULT_REGISTRY_PATH);
+  if (!existsSync2(manifestPath)) {
+    throw new CliInputError(`Registry manifest not found: ${fileFlag ?? DEFAULT_REGISTRY_PATH}`, "Create one with `moda registry template --out=.moda/registry.json`, fill it in, then rerun.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(manifestPath, "utf8"));
+  } catch (error) {
+    throw new CliInputError(`Registry manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return resolveRegistry(parsed, {
+    manifestPath,
+    cwd: context.cwd,
+    forceLive: context.flags.live === "true"
+  });
+}
+var PROMPT_FIELDS = {
+  key: "string",
+  name: "string",
+  description: "string",
+  category: "string",
+  content: "string",
+  systemPrompt: "string",
+  messages: "array",
+  variables: "array",
+  variablesSchema: "object",
+  modelConfig: "object",
+  toolRefs: "array",
+  responseSchema: "object",
+  sourcePath: "string",
+  file: "string"
+};
+var SKILL_FIELDS = {
+  key: "string",
+  name: "string",
+  description: "string",
+  skillMd: "string",
+  sourcePath: "string",
+  file: "string",
+  live: "boolean"
+};
+var TOOL_FIELDS = {
+  name: "string",
+  description: "string",
+  schema: "object",
+  isActive: "boolean"
+};
+var MAX_SKILL_KEY_LENGTH = 256;
+var MAX_SKILL_BYTES = 1e6;
+function checkFields(label, item, spec, errors) {
+  for (const [key, value] of Object.entries(item)) {
+    const expected = spec[key];
+    if (!expected) {
+      errors.push(`${label}: unknown field "${key}" (allowed: ${Object.keys(spec).join(", ")})`);
+      continue;
+    }
+    const actual = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+    if (actual !== expected)
+      errors.push(`${label}.${key} must be ${expected === "array" || expected === "object" ? "an" : "a"} ${expected} (got ${actual})`);
+  }
+}
+function resolveRegistry(input, options) {
+  const errors = [];
+  if (!isRecord(input)) {
+    throw new CliInputError("Registry manifest must be a JSON object with prompts, skills, and/or tools arrays.");
+  }
+  if (input.schema !== undefined && input.schema !== REGISTRY_SCHEMA) {
+    errors.push(`schema must be "${REGISTRY_SCHEMA}" (got ${JSON.stringify(input.schema)})`);
+  }
+  const known = new Set(["schema", "prompts", "skills", "tools"]);
+  for (const key of Object.keys(input)) {
+    if (!known.has(key))
+      errors.push(`unknown top-level field "${key}"`);
+  }
+  const readRef = (label, file) => {
+    if (typeof file !== "string" || file.trim() === "") {
+      errors.push(`${label}.file must be a non-empty string`);
+      return;
+    }
+    const target = resolve2(options.cwd, file);
+    if (!isInside(options.cwd, target)) {
+      errors.push(`${label}.file "${file}" resolves outside the project directory`);
+      return;
+    }
+    if (!existsSync2(target)) {
+      errors.push(`${label}.file "${file}" does not exist`);
+      return;
+    }
+    if (!isInside(realpathSync2(options.cwd), realpathSync2(target))) {
+      errors.push(`${label}.file "${file}" is a symlink to outside the project directory`);
+      return;
+    }
+    if (!statSync(target).isFile()) {
+      errors.push(`${label}.file "${file}" is not a file`);
+      return;
+    }
+    return readFileSync2(target, "utf8");
+  };
+  const sourcePathFor = (file) => relative(options.cwd, resolve2(options.cwd, file)).split("\\").join("/");
+  const prompts = arrayOf(input.prompts, "prompts", errors).map((raw, index) => {
+    const label = `prompts[${index}]`;
+    if (!isRecord(raw)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+    checkFields(label, raw, PROMPT_FIELDS, errors);
+    const { file, ...rest } = raw;
+    if (!nonEmptyString(rest.key))
+      errors.push(`${label}.key is required`);
+    const prompt = { ...rest };
+    if (file !== undefined) {
+      if (rest.content !== undefined)
+        errors.push(`${label}: set content or file, not both`);
+      const content = readRef(label, file);
+      if (content !== undefined)
+        prompt.content = content;
+      if (typeof file === "string" && !prompt.sourcePath)
+        prompt.sourcePath = sourcePathFor(file);
+    }
+    if (!nonEmptyString(prompt.content) && !nonEmptyString(prompt.systemPrompt) && !(Array.isArray(prompt.messages) && prompt.messages.length > 0)) {
+      errors.push(`${label}: one of content, file, systemPrompt, or messages is required`);
+    }
+    return prompt;
+  });
+  const skills = arrayOf(input.skills, "skills", errors).map((raw, index) => {
+    const label = `skills[${index}]`;
+    if (!isRecord(raw)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+    checkFields(label, raw, SKILL_FIELDS, errors);
+    const skill = raw;
+    if (!nonEmptyString(skill.key)) {
+      errors.push(`${label}.key is required`);
+    } else if (!SKILL_KEY_PATTERN.test(skill.key)) {
+      errors.push(`${label}.key "${skill.key}" may only contain letters, digits, "_" and "-"`);
+    } else if (skill.key.length > MAX_SKILL_KEY_LENGTH) {
+      errors.push(`${label}.key must be ${MAX_SKILL_KEY_LENGTH} characters or fewer`);
+    }
+    let skillMd = skill.skillMd;
+    let sourcePath = skill.sourcePath;
+    if (skill.file !== undefined) {
+      if (skill.skillMd !== undefined)
+        errors.push(`${label}: set skillMd or file, not both`);
+      skillMd = readRef(label, skill.file);
+      if (typeof skill.file === "string" && !sourcePath)
+        sourcePath = sourcePathFor(skill.file);
+    }
+    if (!nonEmptyString(skillMd)) {
+      errors.push(`${label}: skillMd or file is required`);
+    } else if (Buffer.byteLength(skillMd, "utf8") > MAX_SKILL_BYTES) {
+      errors.push(`${label}: skill content exceeds ${MAX_SKILL_BYTES} bytes`);
+    }
+    if (skill.live !== undefined && typeof skill.live !== "boolean")
+      errors.push(`${label}.live must be a boolean`);
+    const live = options.forceLive || skill.live === true;
+    return {
+      key: skill.key,
+      ...skill.name !== undefined ? { name: skill.name } : {},
+      ...skill.description !== undefined ? { description: skill.description } : {},
+      skillMd: skillMd ?? "",
+      ...sourcePath !== undefined ? { sourcePath } : {},
+      ...live ? { surfacePolicy: "include" } : skill.live === false ? { surfacePolicy: "local_only" } : {}
+    };
+  });
+  const toolNames = new Set;
+  const tools = arrayOf(input.tools, "tools", errors).map((raw, index) => {
+    const label = `tools[${index}]`;
+    if (!isRecord(raw) || !isRecord(raw.schema)) {
+      errors.push(`${label}.schema must be an object (OpenAI function schema)`);
+      return;
+    }
+    checkFields(label, raw, TOOL_FIELDS, errors);
+    const tool = raw;
+    const inner = tool.schema.type === "function" && isRecord(tool.schema.function) ? tool.schema.function : tool.schema;
+    const schemaName = typeof inner.name === "string" ? inner.name.trim() : undefined;
+    const name = (typeof tool.name === "string" ? tool.name.trim() : "") || schemaName;
+    if (typeof tool.name === "string" && tool.name.trim() && schemaName && tool.name.trim() !== schemaName) {
+      errors.push(`${label}: name "${tool.name}" does not match schema.name "${schemaName}"`);
+    }
+    if (!nonEmptyString(name)) {
+      errors.push(`${label}: name or schema.name is required`);
+    } else if (toolNames.has(name)) {
+      errors.push(`${label}: duplicate tool name "${name}"`);
+    } else {
+      toolNames.add(name);
+    }
+    if (inner.name !== undefined && typeof inner.name !== "string")
+      errors.push(`${label}: schema.name must be a string`);
+    if (inner.description !== undefined && typeof inner.description !== "string") {
+      errors.push(`${label}: schema.description must be a string`);
+    }
+    if (inner.parameters !== undefined) {
+      if (!isRecord(inner.parameters) || inner.parameters.type !== "object") {
+        errors.push(`${label}: schema.parameters.type must be "object"`);
+      } else if (inner.parameters.properties !== undefined && !isRecord(inner.parameters.properties)) {
+        errors.push(`${label}: schema.parameters.properties must be an object`);
+      }
+    }
+    return tool;
+  });
+  const promptKeys = new Set;
+  for (const prompt of prompts) {
+    if (prompt && nonEmptyString(prompt.key)) {
+      if (promptKeys.has(prompt.key))
+        errors.push(`duplicate prompt key "${prompt.key}"`);
+      promptKeys.add(prompt.key);
+    }
+  }
+  const skillKeys = new Set;
+  for (const skill of skills) {
+    if (skill && nonEmptyString(skill.key)) {
+      if (skillKeys.has(skill.key))
+        errors.push(`duplicate skill key "${skill.key}"`);
+      skillKeys.add(skill.key);
+    }
+  }
+  if (errors.length > 0) {
+    throw new CliInputError(`Registry manifest is invalid:
+  - ${errors.join(`
+  - `)}`, "Fix the manifest and rerun `moda registry validate`. See `moda registry template` for the format.");
+  }
+  const resolved = {
+    manifestPath: options.manifestPath,
+    prompts: prompts.filter(isDefined),
+    skills: skills.filter(isDefined),
+    tools: tools.filter(isDefined)
+  };
+  if (resolved.prompts.length + resolved.skills.length + resolved.tools.length === 0) {
+    throw new CliInputError("Registry manifest has no prompts, skills, or tools to push.");
+  }
+  return resolved;
+}
+function arrayOf(value, label, errors) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array`);
+    return [];
+  }
+  if (value.length > MAX_ITEMS_PER_SECTION) {
+    errors.push(`${label} has ${value.length} entries; the limit is ${MAX_ITEMS_PER_SECTION} per push`);
+  }
+  return value;
+}
+function countsOf(registry) {
+  return { prompts: registry.prompts.length, skills: registry.skills.length, tools: registry.tools.length };
+}
+function displayPath(context, path) {
+  const rel = relative(context.cwd, path);
+  return rel && !rel.startsWith("..") && !isAbsolute2(rel) ? rel.split("\\").join("/") : path;
+}
+function isInside(root, target) {
+  const rel = relative(resolve2(root), target);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function isDefined(value) {
+  return value !== undefined;
+}
+
 // src/telemetry.ts
 import { randomUUID } from "node:crypto";
 var TELEMETRY_TIMEOUT_MS = 500;
@@ -1897,7 +2640,7 @@ async function sendCliUsageTelemetry(input) {
 }
 
 // src/update-check.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join2 } from "node:path";
 var UPDATE_CHECK_FLAG = "no-update-check";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -1916,7 +2659,7 @@ function cachePath(options = {}) {
 }
 function readCache(options = {}) {
   try {
-    const parsed = JSON.parse(readFileSync2(cachePath(options), "utf8"));
+    const parsed = JSON.parse(readFileSync3(cachePath(options), "utf8"));
     if (parsed && typeof parsed === "object" && typeof parsed.checked_at === "number" && typeof parsed.latest === "string") {
       return parsed;
     }
@@ -1925,8 +2668,8 @@ function readCache(options = {}) {
 }
 function writeCache(cache, options = {}) {
   try {
-    mkdirSync2(getModaDir(options), { recursive: true });
-    writeFileSync(cachePath(options), `${JSON.stringify(cache, null, 2)}
+    mkdirSync3(getModaDir(options), { recursive: true });
+    writeFileSync3(cachePath(options), `${JSON.stringify(cache, null, 2)}
 `, "utf8");
   } catch {}
 }
@@ -2003,6 +2746,597 @@ function createCommandRegistry(definitions) {
   };
 }
 
+// src/subcommand-help.ts
+var DRY_RUN = { name: "--dry-run", description: "Print the exact request and send nothing." };
+var TENANT_ID = { name: "--tenant-id=<id>", description: "Tenant to act on; must match the API key's tenant (default: the key's)." };
+var SIGNAL_FIELD_FLAGS = [
+  { name: "--name=<text>", description: "Signal name." },
+  { name: "--description=<text>", description: "What the signal catches." },
+  { name: "--pass-criteria=<text>", description: "When a trace passes (the judge reads this)." },
+  { name: "--fail-criteria=<text>", description: "When a trace fails (the judge reads this)." },
+  { name: "--polarity=violation|expectation", description: "Whether a hit is something that should not happen, or something that should." },
+  { name: "--locus=agent|tool_output|user_input", description: "Where in the trace the judge looks." },
+  { name: "--tool-names=a,b", description: "Scope: only traces that call these tools." },
+  { name: "--keyword-hints=a,b", description: "Scope: keywords that make a trace a candidate." },
+  { name: "--use-case-id=<id>", description: "Scope: one use case (cluster id)." },
+  { name: "--message-types=user,assistant,tool_input,tool_output", description: "Scope: message types the judge reads." },
+  { name: "--note=<text>", description: "Free-text note stored with the signal." },
+  { name: "--file=<body.json>", description: "JSON request body; flags given on the command line override its fields." }
+];
+var SIGNALS_SUBCOMMAND_HELP = [
+  {
+    name: "draft",
+    description: "AI-draft name and criteria from a plain description (one LLM call; nothing is saved)",
+    usage: 'moda signals draft --note="<what to catch>" [--file=<body.json>] [--dry-run]',
+    flags: [
+      { name: "--note=<text>", description: "Required. What the signal should catch." },
+      { name: "--file=<body.json>", description: "JSON request body (e.g. with seed/answers); --note overrides its note." },
+      DRY_RUN,
+      TENANT_ID
+    ],
+    examples: ['moda signals draft --note="agent promises a refund it cannot issue"']
+  },
+  {
+    name: "create",
+    description: "Create a custom signal (starts as a draft; activate it to run)",
+    usage: "moda signals create --name=<text> --description=<text> --pass-criteria=<text> --fail-criteria=<text> [scope flags] [--file=<body.json>] [--dry-run]",
+    flags: [...SIGNAL_FIELD_FLAGS, DRY_RUN, TENANT_ID],
+    examples: [
+      'moda signals create --name="Refund promise" --description="…" --pass-criteria="…" --fail-criteria="…" --dry-run',
+      "moda signals create --file=signal.json"
+    ]
+  },
+  {
+    name: "update",
+    description: "Edit a signal's fields (pass at least one field flag or --file)",
+    usage: "moda signals update <signal_id> [field flags] [--file=<body.json>] [--dry-run]",
+    flags: [...SIGNAL_FIELD_FLAGS, DRY_RUN, TENANT_ID],
+    examples: ['moda signals update <signal_id> --fail-criteria="…" --dry-run']
+  },
+  {
+    name: "activate",
+    description: "Start running a signal on new traces",
+    usage: "moda signals activate <signal_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals activate <signal_id>"]
+  },
+  {
+    name: "pause",
+    description: "Stop running a signal (keeps it and its detections)",
+    usage: "moda signals pause <signal_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals pause <signal_id>"]
+  },
+  {
+    name: "delete",
+    description: "Delete a draft signal (drafts only; archiving a live signal is dashboard-only, use pause)",
+    usage: "moda signals delete <signal_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals delete <signal_id> --dry-run"]
+  },
+  {
+    name: "examples",
+    description: "Add, relabel, or remove a labelled example trace on a signal",
+    usage: "moda signals examples <signal_id> add|update|remove --conversation-id=<id> [flags] [--dry-run]",
+    flags: [
+      { name: "--conversation-id=<id>", description: "Required. The trace (conversation_id) the example points at." },
+      { name: "--label=fits|does_not_fit", description: "add: required. update: optional new label." },
+      { name: "--note=<text>", description: "add/update: why the trace fits or not." },
+      { name: "--msg-index=<n>", description: "add: anchor message index in the trace." },
+      { name: "--msg-dedup-token=<token>", description: "add: stable anchor message token (preferred over --msg-index)." },
+      { name: "--criteria=pass|fail", description: "add: which criteria the example illustrates." },
+      { name: "--verdict=accept|reject", description: "add: your verdict on a proposed match." },
+      { name: "--blurb=<text>", description: "update: replace the example summary." },
+      DRY_RUN,
+      TENANT_ID
+    ],
+    examples: [
+      'moda signals examples <signal_id> add --conversation-id=<id> --label=does_not_fit --note="refund was approved"',
+      "moda signals examples <signal_id> remove --conversation-id=<id>"
+    ]
+  },
+  {
+    name: "refine",
+    description: "Propose a criteria edit from a plain request (one LLM call; review with `proposals`)",
+    usage: 'moda signals refine <signal_id> --request="<change>" [--dry-run]',
+    flags: [
+      { name: "--request=<text>", description: "Required, 1-2000 characters. The change you want." },
+      DRY_RUN,
+      TENANT_ID
+    ],
+    examples: ['moda signals refine <signal_id> --request="ignore refunds the agent escalates to a human"']
+  },
+  {
+    name: "revise",
+    description: "Re-derive criteria from labelled example traces (LLM call; rate-limited)",
+    usage: "moda signals revise <signal_id> --conversation-ids=a,b [--dry-run]",
+    flags: [
+      { name: "--conversation-ids=a,b", description: "Required. Labelled traces to learn from." },
+      DRY_RUN,
+      TENANT_ID
+    ],
+    examples: ["moda signals revise <signal_id> --conversation-ids=conv_1,conv_2"]
+  },
+  {
+    name: "proposals",
+    description: "List pending criteria proposals for a signal (read-only)",
+    usage: "moda signals proposals <signal_id>",
+    flags: [TENANT_ID],
+    examples: ["moda signals proposals <signal_id>"]
+  },
+  {
+    name: "accept",
+    description: "Apply a criteria proposal to the signal",
+    usage: "moda signals accept <signal_id> <proposal_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals accept <signal_id> <proposal_id>"]
+  },
+  {
+    name: "reject",
+    description: "Discard a criteria proposal",
+    usage: "moda signals reject <signal_id> <proposal_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals reject <signal_id> <proposal_id>"]
+  },
+  {
+    name: "search",
+    description: "Search recent traces for matches with the judge (up to ~1,000 judge calls; one search per signal at a time)",
+    usage: "moda signals search <signal_id> [--mode=wizard|full] [--exclude-conversation-ids=a,b] [--dry-run]",
+    flags: [
+      { name: "--mode=wizard|full", description: "full (default): the whole search. wizard: stops at about 6 matches (at most ~42 traces judged), for labelling." },
+      { name: "--exclude-conversation-ids=a,b", description: "Traces to skip (e.g. already labelled)." },
+      DRY_RUN,
+      TENANT_ID
+    ],
+    examples: ["moda signals search <signal_id> --mode=wizard"]
+  },
+  {
+    name: "search-status",
+    description: "Poll a signal search (read-only)",
+    usage: "moda signals search-status <signal_id> <search_id>",
+    flags: [TENANT_ID],
+    examples: ["moda signals search-status <signal_id> <search_id>"]
+  },
+  {
+    name: "search-stop",
+    description: "Stop a running signal search",
+    usage: "moda signals search-stop <signal_id> <search_id> [--dry-run]",
+    flags: [DRY_RUN, TENANT_ID],
+    examples: ["moda signals search-stop <signal_id> <search_id>"]
+  },
+  {
+    name: "preview",
+    description: "Run a deterministic (non-judge) detector over recent traces and show what it matches; saves nothing",
+    usage: "moda signals preview --file=<detector.json> [--conversation-ids=a,b] [--max-examples=N]",
+    flags: [
+      {
+        name: "--file=<detector.json>",
+        description: 'Required. JSON {"detector":{"type":…,"config":{…}},"scope"?:{…}}. Types: rule, tool_call, routing, metric, all ' + '(judge detectors preview through `search`). Rule config: {"pattern":"<JS regex>","flags":"i","target":"assistant|user|any|tool_input|tool_output"}; ' + 'regex flags go in "flags" (i, m, s, u), not inline like (?i).'
+      },
+      { name: "--conversation-ids=a,b", description: "Check these traces (at most 200) instead of the recent sample; every match comes back." },
+      { name: "--max-examples=<n>", description: "Examples returned from the recent sample (1-50, default 5)." },
+      TENANT_ID
+    ],
+    examples: [
+      `echo '{"detector":{"type":"rule","config":{"pattern":"cancel(l)?ed","flags":"i","target":"assistant"}}}' > detector.json`,
+      "moda signals preview --file=detector.json --max-examples=10",
+      `echo '{"detector":{"type":"tool_call","config":{"toolName":"lookupCustomer","condition":"errors"}}}' > detector.json`
+    ]
+  }
+];
+var SKILLS_SUBCOMMAND_HELP = [
+  {
+    name: "gen",
+    description: "Generate skills from production traces (paid: clustering + LLM distillation; no dry-run)",
+    usage: "moda skills gen [--source=all|sdk] [--max-sessions=N] [--lookback-hours=N] [--max-traces=N] [--improvement-rounds=1-3] [--start-at=ISO] [--end-at=ISO] [--replay] [--replay-set-id=ID] [--wait]",
+    flags: [
+      { name: "--source=all|sdk", description: "Which traces to learn from (default all)." },
+      { name: "--max-sessions=<n>", description: "Sessions to process (server default 200). Must be 1 or more." },
+      { name: "--lookback-hours=<n>", description: "Window to read (server default 720 = 30 days). Must be 1 or more." },
+      { name: "--start-at=<iso>, --end-at=<iso>", description: "Explicit window instead of --lookback-hours." },
+      { name: "--max-traces=<n>", description: "Cap on cluster traces loaded for distillation." },
+      { name: "--improve-candidates", description: "Run improvement rounds on candidate skills." },
+      { name: "--improvement-rounds=<1-3>", description: "Improvement rounds (default 2, max 3)." },
+      { name: "--replay", description: "Replay candidates against a replay set (extra paid playouts)." },
+      { name: "--replay-set-id=<id>", description: "Replay set for --replay." },
+      { name: "--reprocess-segments", description: "Re-segment sessions that were already processed." },
+      { name: "--force-reprocess", description: "Reprocess everything in the window (implies --reprocess-segments)." },
+      { name: "--no-clustering", description: "Skip clustering; reuse --clustering-run-id." },
+      { name: "--clustering-run-id=<id>", description: "Use an existing clustering run." },
+      { name: "--wait", description: "Wait for the run to finish instead of returning once it is accepted." },
+      TENANT_ID
+    ],
+    examples: ["moda skills gen", "moda skills gen --lookback-hours=168 --max-sessions=50 --wait"]
+  },
+  {
+    name: "status",
+    description: "Show a skill generation run (default: the latest) and its events",
+    usage: "moda skills status [<run_id>] [--run-id=<id>]",
+    examples: ["moda skills status", "moda skills status <run_id>"]
+  },
+  {
+    name: "pull",
+    description: "Write generated skills into the detected coding agents' skill directories",
+    usage: "moda skills pull [--status=approved|proposed|all]",
+    flags: [{ name: "--status=approved|proposed|all", description: "Which skills to pull (default approved)." }],
+    examples: ["moda skills pull", "moda skills pull --status=all"]
+  },
+  {
+    name: "sync",
+    description: "Upload locally authored .claude/skills/**/SKILL.md files to Moda",
+    usage: "moda skills sync [--dry-run]",
+    flags: [{ name: "--dry-run", description: "Server-side preview; nothing is saved." }],
+    examples: ["moda skills sync --dry-run", "moda skills sync"]
+  },
+  {
+    name: "list",
+    description: "List the tenant's skills (the dashboard skill library; read-only)",
+    usage: "moda skills list",
+    examples: ["moda skills list"]
+  },
+  {
+    name: "show",
+    description: "Show one skill with its content (read-only)",
+    usage: "moda skills show <key_or_id>",
+    examples: ["moda skills show refund-policy"]
+  },
+  {
+    name: "policy",
+    description: "Switch a skill between live (served to agents) and local-only",
+    usage: "moda skills policy <key_or_id> --live|--local [--dry-run]",
+    flags: [
+      { name: "--live", description: "Include the skill in the served skill surface." },
+      { name: "--local", description: "Keep the skill local-only (not served)." },
+      DRY_RUN
+    ],
+    examples: ["moda skills policy refund-policy --live --dry-run"]
+  },
+  {
+    name: "proposals",
+    description: "List skill improvement proposals (read-only)",
+    usage: "moda skills proposals list [--status=ready_for_pr|all] [--generation-run-id=<id>]",
+    flags: [
+      { name: "--status=<status>", description: "Proposal status to list (default ready_for_pr; all for every status)." },
+      { name: "--generation-run-id=<id>", description: "Only proposals from one generation run." },
+      TENANT_ID
+    ],
+    examples: ["moda skills proposals list"]
+  },
+  {
+    name: "proposal",
+    description: "Apply a skill proposal: write its SKILL.md locally and acknowledge it on the server",
+    usage: "moda skills proposal apply <proposal_id>",
+    flags: [TENANT_ID],
+    examples: ["moda skills proposal apply <proposal_id>"]
+  },
+  {
+    name: "install",
+    description: "Install bundled integration guides into .claude/skills (offline; no API key)",
+    usage: "moda skills install [--list] <id...>",
+    flags: [{ name: "--list", description: "List the bundled guides." }],
+    examples: ["moda skills install --list", "moda skills install integration-node-openai"]
+  }
+];
+var PROMPTS_REGISTRY_SUBCOMMAND_HELP = [
+  {
+    name: "list",
+    description: "List the tenant's registered prompts (read-only)",
+    usage: "moda prompts list [--label=prod|staging|dev|unlabeled] [--search=<text>]",
+    flags: [
+      { name: "--label=<label>", description: "Only prompts with this label set (prod, staging, dev), or unlabeled ones." },
+      { name: "--search=<text>", description: "Case-insensitive match on key, name, and description." }
+    ],
+    examples: ["moda prompts list", "moda prompts list --label=prod"]
+  },
+  {
+    name: "show",
+    description: "Show one prompt with its versions and labels (read-only)",
+    usage: "moda prompts show <key_or_id>",
+    examples: ["moda prompts show support.triage"]
+  },
+  {
+    name: "proposals",
+    description: "List revision proposals for a prompt (read-only)",
+    usage: "moda prompts proposals <key_or_id>",
+    examples: ["moda prompts proposals support.triage"]
+  },
+  {
+    name: "usage",
+    description: "Per-version call, trace, and token counts for a prompt from traces (read-only)",
+    usage: "moda prompts usage <key_or_id>",
+    examples: ["moda prompts usage support.triage"]
+  },
+  {
+    name: "replay-runs",
+    description: "List replay (A/B) runs for a prompt (read-only)",
+    usage: "moda prompts replay-runs <key_or_id>",
+    examples: ["moda prompts replay-runs support.triage"]
+  },
+  {
+    name: "decide",
+    description: "Merge, reject, or reopen a prompt revision proposal",
+    usage: "moda prompts decide <key_or_id> <proposal_id> --action=merge|reject|reopen [--dry-run]",
+    flags: [
+      { name: "--action=merge|reject|reopen", description: "Required. The decision." },
+      DRY_RUN
+    ],
+    examples: ["moda prompts decide support.triage <proposal_id> --action=merge --dry-run"]
+  }
+];
+var HARNESS_PATH_FLAG = { name: "--path=<dir>", description: "Project root to read (default: the current directory)." };
+var HARNESS_REPORT_FLAG = { name: "--report=<path>", description: "Harness report to use (default .moda/harness-report.json)." };
+var HARNESS_SUBCOMMAND_HELP = [
+  {
+    name: "scan",
+    description: "Deterministic local scan; writes .moda/harness.json (local, no API key)",
+    usage: "moda harness scan [--path=<dir>] [--summary] [--dry-run] [--yes]",
+    flags: [
+      HARNESS_PATH_FLAG,
+      { name: "--summary", description: "Also write .moda/HARNESS.md." },
+      { name: "--dry-run", description: "Scan and print; write nothing." },
+      { name: "--yes", description: "Approve a broad scan without the prompt." }
+    ],
+    examples: ["moda harness scan", "moda harness scan --path=services/agent --dry-run"]
+  },
+  {
+    name: "sync",
+    description: "Upload the harness graph (an approved report, or a fresh local scan) to Moda Cloud",
+    usage: "moda harness sync [--from-report=<path>] [--path=<dir>] [--summary] [--allow-no-agents] [--dry-run]",
+    flags: [
+      { name: "--from-report=<path>", description: "Sync an approved harness report (see `harness approve`). Without it, syncs a fresh local scan." },
+      HARNESS_PATH_FLAG,
+      { name: "--summary", description: "Also write .moda/HARNESS.md." },
+      { name: "--allow-no-agents", description: "Sync a graph with no runtime agents (normally refused)." },
+      { name: "--dry-run", description: "Server-side preview with the same graph hash and changed flag the real sync would report; writes nothing." },
+      { name: "--tenant-id=<id>", description: "Tenant to record on the graph (default: the configured tenant)." }
+    ],
+    examples: [
+      "moda harness sync --dry-run",
+      "moda harness sync --from-report .moda/harness-report.json"
+    ]
+  },
+  {
+    name: "delete",
+    description: "Permanently delete a synced harness and all its versions from Moda Cloud",
+    usage: "moda harness delete <harness_id_or_key> [--yes] [--dry-run]",
+    flags: [
+      { name: "--yes", description: "Confirm the deletion (required outside an interactive terminal)." },
+      { name: "--dry-run", description: "Print what would be deleted; send nothing." }
+    ],
+    examples: ["moda harness delete my-harness-key --dry-run", "moda harness delete my-harness-key --yes"]
+  },
+  {
+    name: "analyze",
+    description: "Run Moda Analyst to produce a cited harness report (experimental; the GitHub App analyzes automatically)",
+    usage: "moda harness analyze --experimental [--remote | --analyst=local-scan|claude|codex|cursor|auto] [--concern=prompts] [--path=<dir>] [--summary] [--dry-run] [--yes]",
+    flags: [
+      { name: "--experimental", description: "Required to run the CLI analyze (or set MODA_HARNESS_ANALYZE_CLI=1)." },
+      { name: "--remote", description: "Run the analysis Moda-hosted (paid); fetch the result with `harness pull`." },
+      { name: "--local, --no-remote", description: "Force a local run even when MODA_HARNESS_REMOTE is set." },
+      { name: "--analyst=<adapter>", description: "local-scan (no LLM), claude, codex, cursor, or auto (an installed coding agent)." },
+      { name: "--analyst-model=<model>", description: "Model for the local coding-agent analyst." },
+      { name: "--shards=<n>", description: "Remote: split the analysis across n shards." },
+      { name: "--concern=prompts", description: "Narrow the analysis to prompts (local coding-agent analyst only)." },
+      { name: "--github-actions", description: "Run inside GitHub Actions with OIDC (no API key on the runner)." },
+      HARNESS_PATH_FLAG,
+      { name: "--summary", description: "Also write markdown summaries." },
+      { name: "--dry-run", description: "Analyze and print; write nothing." },
+      { name: "--yes", description: "Approve a broad scan without the prompt." }
+    ],
+    examples: ["moda harness analyze --experimental --summary", "moda harness analyze --experimental --remote"]
+  },
+  {
+    name: "pull",
+    description: "Fetch a Moda-hosted analysis run once; write its report when complete",
+    usage: "moda harness pull [--run-id=<id>] [--sync]",
+    flags: [
+      { name: "--run-id=<id>", description: "Run to fetch (default: the one in .moda/harness-remote-run.json)." },
+      { name: "--sync", description: "When complete, approve the report and sync it (like `moda init`)." }
+    ],
+    examples: ["moda harness pull", "moda harness pull --sync"]
+  },
+  {
+    name: "validate-report",
+    description: "Validate a harness report against the code and write the validation result (local)",
+    usage: "moda harness validate-report [<report_path>] [--report=<path>] [--dry-run]",
+    flags: [HARNESS_REPORT_FLAG, { name: "--dry-run", description: "Validate only; write nothing." }],
+    examples: ["moda harness validate-report"]
+  },
+  {
+    name: "approve",
+    description: "Record your approval of a validated harness report so `sync --from-report` will upload it (local)",
+    usage: "moda harness approve [<report_path>] [--report=<path>] [--yes]",
+    flags: [HARNESS_REPORT_FLAG, { name: "--yes", description: "Approve without the interactive prompt." }],
+    examples: ["moda harness approve --yes"]
+  },
+  {
+    name: "candidates",
+    description: "Static pre-pass listing likely agents, prompts, and tools (local; no LLM, no network)",
+    usage: "moda harness candidates [--path=<dir>] [--out=<file>] [--dry-run] [--yes]",
+    flags: [
+      HARNESS_PATH_FLAG,
+      { name: "--out=<file>", description: "Also write the candidates report to a file." },
+      { name: "--dry-run", description: "Do not write --out." },
+      { name: "--yes", description: "Approve a broad scan without the prompt." }
+    ],
+    examples: ["moda harness candidates --out=.moda/candidates.json"]
+  },
+  {
+    name: "agents",
+    description: "List runtime agents and families from .moda/harness.json (or a live scan) (local)",
+    usage: "moda harness agents [--path=<dir>]",
+    flags: [HARNESS_PATH_FLAG],
+    examples: ["moda harness agents"]
+  },
+  {
+    name: "graph",
+    description: "Print the full local harness graph (local)",
+    usage: "moda harness graph [--path=<dir>]",
+    flags: [HARNESS_PATH_FLAG],
+    examples: ["moda harness graph --json"]
+  },
+  {
+    name: "explain",
+    description: "Explain the harness, or one runtime agent (local)",
+    usage: "moda harness explain [--agent-id=<id>] [--path=<dir>]",
+    flags: [
+      { name: "--agent-id=<id>, --agent=<id>", description: "Explain one runtime agent (ids from `harness agents`)." },
+      HARNESS_PATH_FLAG
+    ],
+    examples: ["moda harness explain", "moda harness explain --agent-id=agent_support"]
+  },
+  {
+    name: "write-summary",
+    description: "Write .moda/HARNESS.md from the local harness graph (local)",
+    usage: "moda harness write-summary [--path=<dir>]",
+    flags: [HARNESS_PATH_FLAG],
+    examples: ["moda harness write-summary"]
+  },
+  {
+    name: "status",
+    description: "Local harness state: graph hash, last sync, and whether the graph changed since (local)",
+    usage: "moda harness status [--path=<dir>]",
+    flags: [HARNESS_PATH_FLAG],
+    examples: ["moda harness status"]
+  },
+  {
+    name: "list",
+    description: "List the tenant's synced harnesses (read-only)",
+    usage: "moda harness list [--limit=N] [--offset=N]",
+    flags: [
+      { name: "--limit=<n>", description: "Page size." },
+      { name: "--offset=<n>", description: "Rows to skip." }
+    ],
+    examples: ["moda harness list"]
+  },
+  {
+    name: "show",
+    description: "Show one synced harness, at its current or a given version (read-only)",
+    usage: "moda harness show <harness_id_or_key> [--version=<version_id>]",
+    flags: [{ name: "--version=<version_id>", description: "Show this version instead of the current one." }],
+    examples: ["moda harness show my-harness-key"]
+  },
+  {
+    name: "versions",
+    description: "List a synced harness's versions (read-only)",
+    usage: "moda harness versions <harness_id_or_key> [--limit=N] [--offset=N]",
+    flags: [
+      { name: "--limit=<n>", description: "Page size." },
+      { name: "--offset=<n>", description: "Rows to skip." }
+    ],
+    examples: ["moda harness versions my-harness-key"]
+  },
+  {
+    name: "diff",
+    description: "Diff two versions of a synced harness (default: the latest against its parent) (read-only)",
+    usage: "moda harness diff <harness_id_or_key> [--from=<version_id>] [--to=<version_id>]",
+    flags: [
+      { name: "--from=<version_id>", description: "Older version." },
+      { name: "--to=<version_id>", description: "Newer version." }
+    ],
+    examples: ["moda harness diff my-harness-key --from=hver_a --to=hver_b"]
+  }
+];
+var PROBLEMS_SUBCOMMAND_HELP = [
+  {
+    name: "remainder",
+    description: "Signals no Problem explains yet, grouped by family (read-only)",
+    usage: "moda problems remainder [--family=<family>] [--days-back=N] [--limit=N] [--cursor=<token>]",
+    flags: [
+      { name: "--family=<family>", description: "One of tool_failure, emotion, laziness, hallucination, prm_dip, custom_signal, conversation_reader (frustration is under emotion)." },
+      { name: "--days-back=<n>", description: "Window in days, 1-90 (default 30)." },
+      { name: "--limit=<n>", description: "Groups per page, 1-25 (default 25)." },
+      { name: "--cursor=<token>", description: "The next_cursor from the previous page, verbatim." }
+    ],
+    examples: ["moda problems remainder", "moda problems remainder --family=emotion --days-back=7"]
+  }
+];
+var FIX_TIMEOUT = { name: "--timeout=<ms>", description: "How long to wait, in milliseconds (max 86400000)." };
+var FIX_POLL = { name: "--poll-interval=<ms>", description: "Polling interval while waiting, in milliseconds." };
+var FIXES_SUBCOMMAND_HELP = [
+  {
+    name: "draft-batch",
+    description: "Draft Fixes for the top unfixed Problems (no LLM call itself; spend happens when they are driven)",
+    usage: "moda fixes draft-batch [--limit=N]",
+    flags: [{ name: "--limit=N", description: "How many Problems to draft for (1-25, default 5)." }, TENANT_ID],
+    examples: ["moda fixes draft-batch --limit=3"]
+  },
+  {
+    name: "drive",
+    description: "Advance active Fixes through scoping, proposing, and gating (paid: each fix runs LLM calls and replay playouts)",
+    usage: "moda fixes drive [--status=S] [--max-fixes=N] [--timeout=ms] [--pass-interval=ms]",
+    flags: [
+      { name: "--max-fixes=N", description: "Spend cap: advance at most N fixes this run (1-10, default 3). GATING fixes count too; each run takes the least-recently-driven fixes first, so re-runs reach every fix." },
+      { name: "--status=S", description: "Only drive fixes in this status." },
+      FIX_TIMEOUT,
+      { name: "--pass-interval=<ms>", description: "Pause between passes, in milliseconds." },
+      TENANT_ID
+    ],
+    examples: ["moda fixes drive", "moda fixes drive --max-fixes=1 --status=SCOPING"]
+  }
+];
+var FIX_SUBCOMMAND_HELP = [
+  {
+    name: "start",
+    description: "Start a Fix for a Problem (paid: scoping, a proposal, and a replay gate)",
+    usage: "moda fix start <problem_id> [--type=auto|prompt] [--wait] [--timeout=ms]",
+    flags: [
+      { name: "--type=auto|prompt", description: "Fix type (default auto)." },
+      { name: "--wait", description: "Wait for the gate verdict." },
+      FIX_TIMEOUT,
+      FIX_POLL,
+      TENANT_ID
+    ],
+    examples: ["moda fix start <problem_id> --wait"]
+  },
+  {
+    name: "verify",
+    description: "Re-gate a Fix, optionally with a new candidate prompt (paid: replay playouts)",
+    usage: "moda fix verify <fix_id> [--prompt-file=PATH] [--no-wait] [--timeout=ms] [--yes]",
+    flags: [
+      { name: "--prompt-file=PATH", description: "Candidate prompt to gate. New content skips the 10-minute re-gate cooldown; unchanged content does not." },
+      { name: "--no-wait", description: "Return once the gate is enqueued." },
+      { name: "--yes", description: "Re-gate inside the 10-minute cooldown anyway." },
+      FIX_TIMEOUT,
+      FIX_POLL,
+      TENANT_ID
+    ],
+    examples: ["moda fix verify <fix_id> --prompt-file=prompts/agent.prompt.md"]
+  },
+  {
+    name: "checkout",
+    description: "Write the Fix's candidate into your working tree",
+    usage: "moda fix checkout <fix_id>",
+    flags: [TENANT_ID],
+    examples: ["moda fix checkout <fix_id>"]
+  },
+  {
+    name: "submit",
+    description: "Open a PR for a verified Fix, or record a local branch",
+    usage: "moda fix submit <fix_id> --pr | --local-ref=<branch>",
+    flags: [
+      { name: "--pr", description: "Open a pull request." },
+      { name: "--local-ref=<branch>", description: "Record a branch you pushed yourself." },
+      TENANT_ID
+    ],
+    examples: ["moda fix submit <fix_id> --pr"]
+  },
+  {
+    name: "mark-applied",
+    description: "Mark a Fix as applied outside Moda",
+    usage: "moda fix mark-applied <fix_id> [--note=TEXT]",
+    flags: [{ name: "--note=TEXT", description: "Where or how it was applied." }, TENANT_ID],
+    examples: ['moda fix mark-applied <fix_id> --note="tool description updated in our agent config"']
+  },
+  {
+    name: "dismiss",
+    description: "Dismiss a Fix (no dry-run mode)",
+    usage: "moda fix dismiss <fix_id> --reason=TEXT",
+    flags: [{ name: "--reason=TEXT", description: "Required. Why it is dismissed." }, TENANT_ID],
+    examples: ['moda fix dismiss <fix_id> --reason="not actionable"']
+  }
+];
+
 // src/intelligence-schema.ts
 var INTELLIGENCE_SCHEMA_VERSION = "moda.intelligence.v1";
 var provenanceSchema = { type: "string", enum: ["measured", "inferred"] };
@@ -2534,15 +3868,9 @@ async function probeApiKey(key, options = {}) {
 }
 
 // src/keys.ts
-import { createHash } from "node:crypto";
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
 import { join as join3 } from "node:path";
-var KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS = {
-  list: "GET /api/cli/keys?profile=<profile>",
-  create: "POST /api/cli/keys",
-  rotate: "POST /api/cli/keys/<key_id>/rotate",
-  revoke: "POST /api/cli/keys/<key_id>/revoke"
-};
 function keySecretRef(profile, keyId) {
   assertValidProfileName(profile);
   assertSafeKeyId(keyId);
@@ -2608,9 +3936,9 @@ function keyDescriptorStorePath(options = {}) {
 function loadLocalKeyDescriptors(options = {}) {
   const path = keyDescriptorStorePath(options);
   try {
-    if (!existsSync2(path))
+    if (!existsSync3(path))
       return [];
-    const parsed = JSON.parse(readFileSync3(path, "utf8"));
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return [];
     }
@@ -2648,7 +3976,7 @@ function upsertLocalKeyDescriptor(descriptor, options = {}) {
   return next;
 }
 function stableKeyId(profile, name, now) {
-  const hash = createHash("sha256").update(`${profile}\x00${name}\x00${now.toISOString()}`).digest("hex").slice(0, 12);
+  const hash = createHash2("sha256").update(`${profile}\x00${name}\x00${now.toISOString()}`).digest("hex").slice(0, 12);
   return `key_${hash}`;
 }
 function assertSafeKeyId(keyId) {
@@ -2937,11 +4265,15 @@ async function runProfilesCommand(context) {
   switch (subcommand(context)) {
     case "list": {
       const config = loadProfileConfig({ env: context.env });
+      const { name: effective, source } = effectiveProfile(context, config.active_profile);
+      const missing = !config.profiles[effective];
       context.output.writeData({
-        active_profile: config.active_profile,
-        profiles: Object.values(config.profiles).map((profile) => serializeProfile(profile, config.active_profile)),
+        active_profile: effective,
+        active_profile_source: source,
+        default_profile: config.active_profile,
+        profiles: Object.values(config.profiles).map((profile) => serializeProfile(profile, effective)),
         migrations: config.migrations
-      });
+      }, missing ? { warnings: [`The active profile '${effective}' (from ${source}) does not exist. Create it with \`moda profiles create ${effective}\` or select an existing profile.`] } : undefined);
       return { exitCode: 0 };
     }
     case "use": {
@@ -3011,36 +4343,55 @@ async function runProfilesCommand(context) {
       throw unknownSubcommandError("profiles", subcommand(context), ["list", "use", "create", "doctor"]);
   }
 }
+function effectiveProfile(context, storedDefault) {
+  const envProfile = context.env.MODA_PROFILE?.trim();
+  if (context.profile)
+    return { name: context.profile, source: "flag" };
+  if (envProfile)
+    return { name: envProfile, source: "env:MODA_PROFILE" };
+  return { name: storedDefault, source: "config" };
+}
 async function runConfigCommand(context) {
   if (subcommand(context) !== "show") {
     throw unknownSubcommandError("config", subcommand(context), ["show"]);
   }
   const config = loadProfileConfig({ env: context.env });
   const profile = getActiveProfile({ profile: context.profile, env: context.env });
+  const options = { profile: profile.name, env: context.env };
+  const envProfile = context.env.MODA_PROFILE?.trim();
+  const apiKey = resolveApiKey(options);
+  const baseUrl = resolveModaBaseUrl(options);
   context.output.writeData({
     moda_dir: getModaPaths({ env: context.env }).dir,
     active_profile: profile.name,
-    profile: serializeProfile(profile, config.active_profile),
+    active_profile_source: context.profile ? "flag" : envProfile ? "env:MODA_PROFILE" : "config",
+    default_profile: config.active_profile,
+    profile: serializeProfile(profile, profile.name),
     resolved: {
-      api_key: redactSecret(resolveApiKeyFromActiveProfile({ profile: profile.name, env: context.env })),
-      base_url: profile.base_url,
-      ingest_url: profile.ingest_url,
-      tenant_id: profile.tenant_id,
+      api_key: redactSecret(apiKey),
+      api_key_source: context.env.MODA_API_KEY ? "env:MODA_API_KEY" : profile.api_key_ref === "legacy:config.api_key" && apiKey ? "legacy_config" : resolveApiKeyFromActiveProfile(options) ? "profile" : apiKey ? "legacy_config" : "none",
+      base_url: baseUrl,
+      base_url_source: describeBaseUrlSource(options),
+      ingest_url: resolveIngestUrl(options),
+      tenant_id: resolveApiTenantId(options),
       workspace_id: profile.workspace_id
     },
     migrations: config.migrations
   });
   return { exitCode: 0 };
 }
+var KEYS_LOCAL_ONLY_NOTE = "moda keys manages local key descriptors in ~/.moda only; it does not list or change your tenant's server-side API keys (see Settings → Ingestion keys in the dashboard).";
 async function runKeysCommand(context) {
   switch (subcommand(context)) {
     case "list": {
-      const profile = context.profile ?? loadProfileConfig({ env: context.env }).active_profile;
+      const profile = context.profile ?? (context.env.MODA_PROFILE?.trim() || undefined) ?? loadProfileConfig({ env: context.env }).active_profile;
       const keys = loadLocalKeyDescriptors({ env: context.env }).filter((key) => !profile || key.profile === profile);
       context.output.writeData({
+        scope: "local_descriptors",
         profile,
-        keys,
-        endpoint_requirements: KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS
+        keys
+      }, {
+        warnings: [KEYS_LOCAL_ONLY_NOTE]
       });
       return { exitCode: 0 };
     }
@@ -3061,7 +4412,9 @@ async function runKeysCommand(context) {
       context.output.writeData({
         key: descriptor,
         secret_path: secretPath,
-        endpoint_requirements: KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS.create
+        scope: "local_descriptors"
+      }, {
+        warnings: [KEYS_LOCAL_ONLY_NOTE]
       });
       return { exitCode: 0 };
     }
@@ -3069,7 +4422,7 @@ async function runKeysCommand(context) {
     case "revoke": {
       const action = subcommand(context);
       const keyId = requirePositional(context, 1, `Usage: moda keys ${action} <key_id>`);
-      throw new CliInputError(`moda keys ${action} is waiting on Moda Cloud key lifecycle support for ${keyId}.`, `Required endpoint: ${KEY_LIFECYCLE_ENDPOINT_REQUIREMENTS[action]}`);
+      throw new CliInputError(`moda keys ${action} is not supported: the CLI cannot ${action} server-side API keys (${keyId} was not changed).`, "Manage API keys in the dashboard at Settings → Ingestion keys.");
     }
     default:
       throw unknownSubcommandError("keys", subcommand(context), ["list", "create", "rotate", "revoke"]);
@@ -3077,8 +4430,8 @@ async function runKeysCommand(context) {
 }
 
 // src/agent.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4, statSync } from "node:fs";
-import { join as join4, relative, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
+import { join as join4, relative as relative2, resolve as resolve3 } from "node:path";
 var MODA_DIR = ".moda";
 var HARNESS_PATH = join4(MODA_DIR, "harness.json");
 var HARNESS_REPORT_MARKDOWN_PATH = join4(MODA_DIR, "HARNESS_REPORT.md");
@@ -3093,25 +4446,8 @@ async function runAgentCommand(context) {
       return { exitCode: 0 };
     }
     case "investigate": {
-      const loaded = await buildAgentContext(context);
-      const question = context.positionals.slice(1).join(" ").trim() || context.flags.question;
-      context.output.writeData({
-        schemaVersion: "agent_investigation.v0.1",
-        generatedAt: loaded.payload.generatedAt,
-        mode: "local",
-        question: question || null,
-        status: loaded.payload.doctor.status,
-        findings: loaded.payload.doctor.topFindings,
-        recommendedActions: loaded.payload.recommendedActions,
-        evidenceRefs: loaded.payload.evidenceRefs,
-        limitations: [
-          ...loaded.payload.limitations,
-          "Production investigation is not yet implemented in P08; use P09/cloud commands for production-rooted analysis once shipped."
-        ]
-      }, agentWriteOptions(loaded, {
-        summary: summarizeAgentContext(loaded.payload, "investigation")
-      }));
-      return { exitCode: 0 };
+      const passthrough = Object.entries(context.flags).filter(([key]) => ["days-back", "tool", "trace", "conversation"].includes(key)).map(([key, value]) => `--${key}=${value}`);
+      throw new CliInputError("'moda agent investigate' has been removed. Use 'moda investigate' for the ranked production investigation.", `Run: ${["moda investigate", ...passthrough].join(" ")} (flags: --days-back, --tool, --trace). For local readiness use 'moda agent context'.`);
     }
     case "next-action":
     case "next-actions": {
@@ -3161,7 +4497,7 @@ async function runAgentCommand(context) {
       return { exitCode: 0 };
     }
     default:
-      throw new CliInputError(`Unknown agent subcommand '${subcommand2}'`, "Usage: moda agent context|investigate|next-action|evidence");
+      throw new CliInputError(`Unknown agent subcommand '${subcommand2}'`, "Usage: moda agent context|next-action|evidence (for production issues use moda investigate)");
   }
 }
 async function buildAgentContext(context) {
@@ -3263,17 +4599,17 @@ function summarizeAgentContext(payload, noun) {
 }
 function readHarnessGraphIfPresent(cwd) {
   const path = join4(cwd, HARNESS_PATH);
-  if (!existsSync3(path))
+  if (!existsSync4(path))
     return;
   try {
-    return JSON.parse(readFileSync4(path, "utf8"));
+    return JSON.parse(readFileSync5(path, "utf8"));
   } catch {
     return;
   }
 }
 function readHarnessReportState(cwd) {
   const path = join4(cwd, HARNESS_REPORT_PATH);
-  if (!existsSync3(path)) {
+  if (!existsSync4(path)) {
     return {
       state: {
         path: HARNESS_REPORT_PATH,
@@ -3318,10 +4654,10 @@ function readHarnessReportState(cwd) {
 }
 function readApproval(cwd) {
   const path = join4(cwd, HARNESS_REPORT_APPROVAL_PATH);
-  if (!existsSync3(path))
+  if (!existsSync4(path))
     return;
   try {
-    return JSON.parse(readFileSync4(path, "utf8"));
+    return JSON.parse(readFileSync5(path, "utf8"));
   } catch {
     return;
   }
@@ -3399,7 +4735,7 @@ function existingArtifacts(cwd) {
     [HARNESS_SUMMARY_PATH, "harness_summary", "Human-readable harness graph summary."],
     [join4(MODA_DIR, "sync-state.json"), "sync_state", "Last local harness sync state."],
     [join4(MODA_DIR, "prompts.yml"), "prompt_manifest", "Local prompt discovery manifest."]
-  ].flatMap(([path, kind, description]) => existsSync3(join4(cwd, path)) ? [{ path, kind, description }] : []);
+  ].flatMap(([path, kind, description]) => existsSync4(join4(cwd, path)) ? [{ path, kind, description }] : []);
 }
 function expandEvidenceRef(ref, loaded, cwd) {
   if (ref.startsWith("doctor:")) {
@@ -3480,9 +4816,9 @@ function readCitationExcerpt(cwd, citation) {
   if (!citation.path || citation.type !== "file" && citation.type !== "generated_doc")
     return citation.excerpt;
   const absolute = safeResolve(cwd, citation.path);
-  if (!absolute || !existsSync3(absolute))
+  if (!absolute || !existsSync4(absolute))
     return citation.excerpt;
-  const text = readFileSync4(absolute, "utf8");
+  const text = readFileSync5(absolute, "utf8");
   if (citation.line && citation.line > 0) {
     return text.split(/\r?\n/)[citation.line - 1]?.slice(0, 1000) ?? citation.excerpt;
   }
@@ -3493,10 +4829,10 @@ function readBoundedModaArtifact(cwd, artifactPath) {
     throw new CliInputError(`Artifact '${artifactPath}' is outside .moda and cannot be expanded directly.`, "Use a citation evidence ref for source-file evidence.");
   }
   const absolute = safeResolve(cwd, artifactPath);
-  if (!absolute || !existsSync3(absolute))
+  if (!absolute || !existsSync4(absolute))
     throw missingEvidence(`artifact:${artifactPath}`);
-  const size = statSync(absolute).size;
-  const text = readFileSync4(absolute, "utf8");
+  const size = statSync2(absolute).size;
+  const text = readFileSync5(absolute, "utf8");
   return {
     path: artifactPath,
     bytes: size,
@@ -3505,8 +4841,8 @@ function readBoundedModaArtifact(cwd, artifactPath) {
   };
 }
 function safeResolve(cwd, path) {
-  const absolute = resolve2(cwd, path);
-  const rel = relative(cwd, absolute);
+  const absolute = resolve3(cwd, path);
+  const rel = relative2(cwd, absolute);
   if (rel.startsWith("..") || rel === ".." || rel.startsWith("/"))
     return;
   return absolute;
@@ -3539,29 +4875,25 @@ function purposeForCommand(command) {
 }
 
 // src/production-intelligence.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync6 } from "node:fs";
 import { join as join5 } from "node:path";
 
 // src/ask-stream.ts
 class AskStreamError extends Error {
   elapsedMs;
   toolEvents;
+  accepted;
   constructor(message) {
     super(message);
     this.name = "AskStreamError";
   }
 }
-var SUBSTANTIAL_STREAM_PROGRESS_MS = 60000;
-var SUBSTANTIAL_STREAM_TOOL_EVENTS = 5;
-function streamFallbackNotice(error) {
-  if (!(error instanceof AskStreamError))
-    return null;
-  const elapsedMs = error.elapsedMs ?? 0;
-  const toolEvents = error.toolEvents ?? 0;
-  if (elapsedMs < SUBSTANTIAL_STREAM_PROGRESS_MS && toolEvents <= SUBSTANTIAL_STREAM_TOOL_EVENTS) {
-    return null;
-  }
-  return `stream interrupted after ${Math.round(elapsedMs / 1000)}s; ` + "retrying via buffered request — this may take another minute or two.";
+function canFallBackToBufferedAsk(error) {
+  return error instanceof AskStreamError && error.accepted !== true;
+}
+function askStreamInterruptedError(error) {
+  const secs = Math.round((error.elapsedMs ?? 0) / 1000);
+  return new Error(`The live ask stream dropped ${secs}s into a run the server had already accepted (${error.message}). ` + "Not re-running it, to avoid paying for a second agent run; the run may still complete server-side. " + 'Retry with `moda ask "<question>" --no-stream` in a minute (the buffered path has no live progress but survives drops).');
 }
 
 class SseParser {
@@ -3677,6 +5009,7 @@ class AskStreamCollector {
   lastPhase;
   toolNames = new Map;
   toolEvents = 0;
+  events = 0;
   constructor(onProgress = () => {}) {
     this.onProgress = onProgress;
   }
@@ -3687,6 +5020,7 @@ class AskStreamCollector {
     if (!event || typeof event !== "object" || typeof event.type !== "string") {
       throw new AskStreamError("stream emitted a frame without an event type");
     }
+    this.events += 1;
     switch (event.type) {
       case "phase": {
         const phase = typeof event.phase === "string" ? event.phase : "";
@@ -3752,6 +5086,9 @@ class AskStreamCollector {
   isTerminal() {
     return this.terminal;
   }
+  get eventCount() {
+    return this.events;
+  }
   get toolEventCount() {
     return this.toolEvents;
   }
@@ -3848,6 +5185,7 @@ async function streamAsk(options) {
   const collector = new AskStreamCollector(onProgress);
   const ticker = new IdleTicker(onProgress);
   ticker.start();
+  let accepted = false;
   try {
     const fetchImpl = options.fetchImpl ?? fetch;
     let response;
@@ -3877,6 +5215,7 @@ async function streamAsk(options) {
     if (!contentType.includes("text/event-stream")) {
       throw new AskStreamError(`stream endpoint returned unexpected content type '${contentType || "unknown"}'`);
     }
+    accepted = true;
     if (!response.body) {
       throw new AskStreamError("stream response had no body");
     }
@@ -3893,6 +5232,8 @@ async function streamAsk(options) {
         error.elapsedMs = Date.now() - startedAt;
       if (error.toolEvents === undefined)
         error.toolEvents = collector.toolEventCount;
+      if (error.accepted === undefined)
+        error.accepted = accepted || collector.eventCount > 0;
     }
     throw error;
   } finally {
@@ -3905,8 +5246,10 @@ async function streamAsk(options) {
 var INVESTIGATION_SCHEMA_VERSION = "production_investigation.v0.1";
 var OVERVIEW_SCHEMA_VERSION = "production_overview.v0.1";
 var ASK_SCHEMA_VERSION = "production_ask.v0.1";
+var INVESTIGATION_PROBLEM_LIMIT = 3;
+var INVESTIGATION_PROBLEM_SLOTS = INVESTIGATION_PROBLEM_LIMIT;
 async function runProductionCommand(context) {
-  const daysBack = numberFlag(context.flags, "days-back", 7);
+  const daysBack = daysBackFlag(context.flags);
   if (context.command === "overview") {
     const briefing = await loadOverviewBriefing({ daysBack, cwd: context.cwd });
     if (context.flags.raw === "true") {
@@ -3925,7 +5268,7 @@ async function runProductionCommand(context) {
   if (context.command === "ask") {
     const question = context.positionals.join(" ").trim();
     if (!question) {
-      throw new CliInputError("<question> is required", 'Usage: moda ask "what should I fix first?" [--days-back=N]');
+      throw new CliInputError("<question> is required", 'Usage: moda ask "what should I fix first?" [--days-back=N] [--no-stream]');
     }
     const result = await askModaForContext(context, question, daysBack);
     if (context.outputMode === "human") {
@@ -4006,30 +5349,45 @@ async function investigateProduction(options) {
   const hints = loadHarnessHints(options.cwd);
   const overviewEndpoint = `/overview?days_back=${options.daysBack}`;
   const toolEndpoint = options.toolName ? `/tool-failures/${encodeURIComponent(options.toolName)}?days_back=${options.daysBack}&limit=5` : `/tool-failures?days_back=${options.daysBack}`;
-  const frustrationsEndpoint = `/frustrations?days_back=${options.daysBack}&limit=5`;
-  const [overview, tools, frustrations] = await Promise.all([
+  const frustrationsEndpoint = `/emotions?family=frustration&days_back=${options.daysBack}&limit=5${options.conversationId ? `&conversation_id=${encodeURIComponent(options.conversationId)}` : ""}`;
+  const problemsEndpoint = `/problems?days_back=${options.daysBack}&limit=${INVESTIGATION_PROBLEM_LIMIT}`;
+  const skipped = { data: null, status: "ok" };
+  const [overview, tools, frustrations, problems] = await Promise.all([
     safeData(overviewEndpoint),
     safeData(toolEndpoint),
-    safeData(frustrationsEndpoint)
+    options.failureOnly ? Promise.resolve(skipped) : safeData(frustrationsEndpoint),
+    options.failureOnly ? Promise.resolve(skipped) : safeData(problemsEndpoint)
   ]);
-  for (const [key, result] of Object.entries({ overview, tools, frustrations })) {
+  const sources = options.failureOnly ? { overview, tools } : { overview, tools, frustrations, problems };
+  for (const [key, result] of Object.entries(sources)) {
     sourceStatus[key] = result.status;
     if (result.warning)
       warnings.push(result.warning);
   }
+  if (options.toolName && tools.status === "ok" && toolRows(tools.data, options.toolName).every((row) => row.count <= 0)) {
+    warnings.push(`No failures found for tool "${options.toolName}" in the last ${options.daysBack} day(s) — the tool may have no failures in this window, or the name may not exist in this tenant. ` + "Run `moda tool-failures` to list tools with recorded failures, or widen --days-back.");
+  }
+  if (options.conversationId) {
+    warnings.push(`Scoped to trace ${options.conversationId} for frustration evidence only; overview and tool failures are tenant-wide. ` + `Open the trace itself with \`moda audit ${options.conversationId}\`.`);
+  }
   const evidenceRefs = [];
   const findings = [];
   addOverviewEvidence(overview.data, overviewEndpoint, evidenceRefs);
   findings.push(...toolFailureFindings(tools.data, options.daysBack, hints, evidenceRefs, options.toolName));
   if (!options.failureOnly) {
     findings.push(...frustrationFindings(frustrations.data, options.daysBack, evidenceRefs));
+    findings.push(...problemFindings(problems.data, options.daysBack, evidenceRefs));
   }
   if (findings.length === 0) {
     findings.push(insufficientDataFinding(overview.data, evidenceRefs));
   }
   findings.sort(compareFindings);
-  const boundedFindings = findings.slice(0, 8);
-  const nextCommands = nextCommandsForFindings(boundedFindings, options.daysBack);
+  const boundedFindings = capFindings(findings, 8, INVESTIGATION_PROBLEM_SLOTS);
+  const nextCommands = nextCommandsForFindings(boundedFindings, options.daysBack, !options.failureOnly);
+  const summary = summarizeInvestigation(boundedFindings);
+  if (options.conversationId) {
+    summary.text = `${summary.text} (Only frustration evidence is scoped to trace ${options.conversationId}.)`;
+  }
   return {
     schemaVersion: INVESTIGATION_SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
@@ -4039,7 +5397,7 @@ async function investigateProduction(options) {
       ...options.toolName ? { toolName: options.toolName } : {},
       ...options.question ? { question: options.question } : {}
     },
-    summary: summarizeInvestigation(boundedFindings),
+    summary,
     findings: boundedFindings,
     evidenceRefs: uniqueEvidenceRefs(evidenceRefs),
     nextCommands,
@@ -4140,11 +5498,10 @@ async function askModaForContext(context, question, daysBack) {
     } catch (error) {
       if (error instanceof CliAuthError)
         throw error;
-      const notice = streamFallbackNotice(error);
-      if (notice) {
-        safeWriteStderr(`[moda] ${notice}
-`);
-      } else if (context.verbose) {
+      if (error instanceof AskStreamError && !canFallBackToBufferedAsk(error)) {
+        throw askStreamInterruptedError(error);
+      }
+      if (context.verbose) {
         safeWriteStderr(`[moda] live progress unavailable (${error instanceof Error ? error.message : String(error)}); using buffered ask.
 `);
       }
@@ -4330,7 +5687,7 @@ function toolFailureFindings(data, daysBack, hints, evidenceRefs, scopedTool) {
         id: `action_tool_detail_${slug(name)}`,
         title: `Inspect ${name} failure examples.`,
         rationale: "Examples include trace anchors and error subtypes.",
-        command: `moda tool-failure-detail ${name} --include-window`,
+        command: `moda tool-failure-detail ${name} --days-back=${daysBack} --include-window`,
         mutability: "read",
         requiresApproval: false
       }]
@@ -4338,6 +5695,7 @@ function toolFailureFindings(data, daysBack, hints, evidenceRefs, scopedTool) {
   });
 }
 function frustrationFindings(data, daysBack, evidenceRefs) {
+  data = frustrationsFromEmotions(asRecord(data) ?? {});
   const summary = asRecord(valueAt(data, ["summary"]));
   const frustrations = Array.isArray(valueAt(data, ["frustrations"])) ? valueAt(data, ["frustrations"]) : [];
   const count = numberValue(summary?.frustrated_count) || frustrations.length;
@@ -4347,12 +5705,13 @@ function frustrationFindings(data, daysBack, evidenceRefs) {
   const first = asRecord(frustrations[0]);
   const conversationId = asString(first?.conversation_id);
   const quote = firstQuote(first);
+  const anchorIndex = frustrationAnchorIndex(first);
   const evidenceId = conversationId ? `frustration:${conversationId}` : "frustration:summary";
   evidenceRefs.push({
     id: evidenceId,
     kind: "frustration",
     label: quote ? `Frustration anchor: "${quote}"` : `${count} frustrated trace(s)`,
-    endpoint: `/frustrations?days_back=${daysBack}&limit=5`,
+    endpoint: `/emotions?family=frustration&days_back=${daysBack}&limit=5`,
     ...conversationId ? { conversationId } : {},
     value: first ?? summary ?? data
   });
@@ -4371,12 +5730,78 @@ function frustrationFindings(data, daysBack, evidenceRefs) {
       id: "action_frustration_window",
       title: "Read the frustration window.",
       rationale: "The user quote and nearby turns reveal what confused or blocked the user.",
-      command: conversationId ? `moda context ${conversationId} --window=3` : `moda frustrations --days-back=${daysBack} --include-window`,
+      command: conversationId ? `moda context ${conversationId}${anchorIndex !== null ? ` --msg-index=${anchorIndex}` : ""} --window=3` : `moda frustrations --days-back=${daysBack} --include-window`,
       mutability: "read",
       requiresApproval: false
     }]
   }];
 }
+function problemRows(data) {
+  const record = asRecord(data);
+  const rows = [];
+  const push = (items, trust) => {
+    if (!Array.isArray(items))
+      return;
+    for (const item of items) {
+      const row = asRecord(item);
+      const id = asString(row?.problem_id);
+      if (!row || !id)
+        continue;
+      const lifecycle = asString(row.lifecycle) ?? "open";
+      if (lifecycle === "resolved")
+        continue;
+      rows.push({
+        id,
+        name: asString(row.display_name) || id,
+        cause: asString(row.cause_statement) || asString(row.display_description) || undefined,
+        lifecycle,
+        trust,
+        verification: asString(row.verification_status) ?? undefined,
+        affectedConversations: numberValue(row.affected_conversations) || numberValue(asRecord(row.evidence_support)?.attribution_count),
+        raw: row
+      });
+    }
+  };
+  push(record?.problems, "trusted");
+  push(record?.untrusted, "untrusted");
+  push(record?.emerging, "emerging");
+  return rows.slice(0, INVESTIGATION_PROBLEM_LIMIT);
+}
+function problemFindings(data, daysBack, evidenceRefs) {
+  return problemRows(data).map((problem, index) => {
+    const evidenceId = `problem:${problem.id}`;
+    const trusted = problem.trust === "trusted";
+    const trustNote = trusted ? "verified" : problem.trust === "emerging" ? "emerging, not yet ranked" : `untrusted (${problem.verification ?? "unverified"})`;
+    evidenceRefs.push({
+      id: evidenceId,
+      kind: "problem",
+      label: `Problem "${problem.name}" (${trustNote})`,
+      endpoint: `/problems?days_back=${daysBack}&limit=${INVESTIGATION_PROBLEM_LIMIT}`,
+      value: problem.raw
+    });
+    const affected = problem.affectedConversations;
+    return {
+      id: `finding_problem_${slug(problem.id)}`,
+      kind: "problem",
+      title: `Problem: ${problem.name}`,
+      severity: trusted ? affected >= 10 ? "critical" : "high" : "medium",
+      confidence: trusted ? "high" : "low",
+      impactScore: (trusted ? 100 : 60) + Math.min(affected, 25) - index,
+      rankReason: trusted ? `Rank #${index + 1} verified Problem in \`moda problems\`${affected > 0 ? `, affecting ${affected} trace(s)` : ""}.` : `Listed by \`moda problems\` as ${trustNote}; treat the cause as a hypothesis.`,
+      summary: problem.cause ? `${problem.cause}${problem.lifecycle !== "open" ? ` (${problem.lifecycle})` : ""}` : `Problem ${problem.id} is ${problem.lifecycle} in the last ${daysBack} day(s).`,
+      evidenceRefIds: [evidenceId],
+      likelyLocations: [],
+      recommendedActions: [{
+        id: `action_problem_${slug(problem.id)}`,
+        title: `Open the Problem dossier for ${problem.name}.`,
+        rationale: "The dossier has the cause, evidence, affected traces and verification state.",
+        command: `moda problem ${problem.id}`,
+        mutability: "read",
+        requiresApproval: false
+      }]
+    };
+  });
+}
 function insufficientDataFinding(overview, evidenceRefs) {
   const evidenceId = "overview:data";
   if (!evidenceRefs.some((ref) => ref.id === evidenceId)) {
@@ -4879,11 +6304,14 @@ function toolRows(data, scopedTool) {
   const directToolName = asString(record?.tool_name) ?? scopedTool;
   const examples = Array.isArray(record?.examples) ? record.examples : [];
   if (directToolName) {
+    const subtypes = (Array.isArray(record?.subtypes) ? record.subtypes : []).map((item) => asRecord(item)).filter((item) => item !== null && item !== undefined);
+    const subtypeTotal = subtypes.reduce((sum, item) => sum + numberValue(item.count), 0);
+    const top = [...subtypes].sort((left, right) => numberValue(right.count) - numberValue(left.count))[0];
     return [{
       name: directToolName,
-      count: numberValue(record?.failure_count) || numberValue(record?.total_failures) || examples.length,
-      conversations: numberValue(record?.failed_conversations) || numberValue(record?.conversation_count) || examples.length,
-      subtype: asString(record?.top_error_subtype) ?? asString(record?.error_subtype) ?? undefined,
+      count: numberValue(record?.failure_count) || numberValue(record?.total_failures) || numberValue(asRecord(record?.pagination)?.total) || subtypeTotal || examples.length,
+      conversations: numberValue(record?.failed_conversations) || numberValue(record?.conversation_count) || Math.max(0, ...subtypes.map((item) => numberValue(item.conversation_count))) || examples.length,
+      subtype: asString(record?.top_error_subtype) ?? asString(record?.error_subtype) ?? asString(top?.subtype) ?? undefined,
       raw: data
     }];
   }
@@ -4961,11 +6389,11 @@ function loadHarnessHints(cwd) {
     entrypointPaths: []
   };
   const harnessPath = join5(cwd, ".moda", "harness.json");
-  if (!existsSync4(harnessPath))
+  if (!existsSync5(harnessPath))
     return hints;
   hints.reportPath = ".moda/harness.json";
   try {
-    const parsed = JSON.parse(readFileSync5(harnessPath, "utf8"));
+    const parsed = JSON.parse(readFileSync6(harnessPath, "utf8"));
     const graph = asRecord(parsed);
     const artifacts = Array.isArray(graph?.artifacts) ? graph.artifacts : [];
     for (const item of artifacts) {
@@ -4994,10 +6422,10 @@ function loadHarnessHints(cwd) {
 }
 function localHarnessSummary(cwd) {
   const path = join5(cwd, ".moda", "harness.json");
-  if (!existsSync4(path))
+  if (!existsSync5(path))
     return null;
   try {
-    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    const parsed = JSON.parse(readFileSync6(path, "utf8"));
     return {
       harnessId: parsed.harnessId,
       graphHash: parsed.graphHash,
@@ -5009,7 +6437,7 @@ function localHarnessSummary(cwd) {
 }
 function localSyncBrief(cwd, relativePath, label) {
   const path = join5(cwd, relativePath);
-  if (!existsSync4(path)) {
+  if (!existsSync5(path)) {
     return { status: "missing", summary: `${label} state not found`, path: relativePath };
   }
   return { status: "present", summary: `${label} state exists locally`, path: relativePath };
@@ -5017,7 +6445,7 @@ function localSyncBrief(cwd, relativePath, label) {
 function localSkillBrief(cwd) {
   const claudeSkill = join5(cwd, ".claude", "skills");
   const cursorRules = join5(cwd, ".cursor", "rules");
-  if (existsSync4(claudeSkill) || existsSync4(cursorRules)) {
+  if (existsSync5(claudeSkill) || existsSync5(cursorRules)) {
     return { status: "present", summary: "Local agent skill/rule directory exists" };
   }
   return { status: "missing", summary: "No local agent skill/rule directory found" };
@@ -5035,11 +6463,35 @@ function summarizeInvestigation(findings) {
     confidence: top.confidence
   };
 }
-function nextCommandsForFindings(findings, daysBack) {
-  const commands = findings.flatMap((finding) => finding.recommendedActions.map((action) => action.command)).filter(Boolean);
-  commands.push(`moda overview --days-back=${daysBack}`);
-  commands.push("moda doctor --online");
-  return [...new Set(commands)].slice(0, 8);
+function nextCommandsForFindings(findings, daysBack, includeProblems = false) {
+  const limit = 8;
+  const primary = [...new Set(findings.map((finding) => finding.recommendedActions[0]?.command).filter(Boolean))];
+  const generic = [
+    ...includeProblems ? [`moda problems --days-back=${daysBack}`] : [],
+    `moda overview --days-back=${daysBack}`,
+    "moda doctor --online"
+  ];
+  const secondary = findings.flatMap((finding) => finding.recommendedActions.slice(1).map((action) => action.command)).filter(Boolean);
+  const keep = new Set(primary);
+  for (const command of [...generic, ...secondary]) {
+    if (keep.size >= Math.max(limit, primary.length))
+      break;
+    keep.add(command);
+  }
+  const ordered = [
+    ...findings.flatMap((finding) => finding.recommendedActions.map((action) => action.command)).filter(Boolean),
+    ...generic
+  ];
+  return [...new Set(ordered)].filter((command) => keep.has(command));
+}
+function capFindings(sorted, limit, problemSlots) {
+  const reserved = [
+    ...sorted.filter((finding) => finding.kind === "problem").slice(0, problemSlots),
+    ...sorted.filter((finding) => finding.kind === "frustration").slice(0, 1)
+  ];
+  const others = sorted.filter((finding) => !reserved.includes(finding)).slice(0, limit - reserved.length);
+  const kept = new Set([...reserved, ...others]);
+  return sorted.filter((finding) => kept.has(finding));
 }
 function compareFindings(a, b) {
   const severityDelta = severityWeight(b.severity) - severityWeight(a.severity);
@@ -5132,12 +6584,15 @@ function numberValue(value) {
   }
   return 0;
 }
-function numberFlag(flags, key, fallback) {
-  const raw = flags[key];
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed) || parsed < 1)
+function daysBackFlag(flags, fallback = 7) {
+  const raw = flags["days-back"];
+  if (raw === undefined)
     return fallback;
-  return Math.min(Math.floor(parsed), 90);
+  const parsed = Number(raw);
+  if (raw.trim() === "" || raw === "true" || !Number.isInteger(parsed) || parsed < 1 || parsed > 90) {
+    throw new CliInputError(`--days-back must be a whole number from 1 to 90; got '${raw}'.`, "Nothing was run. Example: --days-back=7 (the default).");
+  }
+  return parsed;
 }
 function normalizeConfidence(value) {
   if (value === "high" || value === "medium" || value === "low" || value === "unknown")
@@ -5148,7 +6603,7 @@ function capFallbackConfidence(confidence) {
   return confidence === "high" ? "medium" : confidence;
 }
 function evidenceKind(value) {
-  if (value === "data_api" || value === "tool_failure" || value === "frustration" || value === "harness" || value === "ask")
+  if (value === "data_api" || value === "tool_failure" || value === "frustration" || value === "problem" || value === "harness" || value === "ask")
     return value;
   return "ask";
 }
@@ -5164,6 +6619,10 @@ function purposeForCommand2(command) {
     return "Open the ranked production investigation.";
   if (command.startsWith("moda tool-failure-detail"))
     return "Inspect tool failure examples and trace anchors.";
+  if (command.startsWith("moda problems"))
+    return "List the ranked Problems.";
+  if (command.startsWith("moda problem "))
+    return "Open the Problem dossier.";
   if (command.startsWith("moda context"))
     return "Read the relevant trace window.";
   if (command.startsWith("moda doctor"))
@@ -5290,6 +6749,7 @@ function buildManifest(commands) {
       streaming: command.outputModes.includes("agent-stream") || command.outputModes.includes("agent"),
       examples: command.examples,
       auth: command.auth,
+      ...command.authNote ? { auth_note: command.authNote } : {},
       mutability: command.mutability,
       exit_codes: exitCodesForCommand(command.name)
     })),
@@ -5338,18 +6798,24 @@ function exitCodesForCommand(command) {
 
 // src/cli.ts
 import { fileURLToPath } from "url";
-import { realpathSync as realpathSync2 } from "fs";
+import { realpathSync as realpathSync3 } from "fs";
 function parseArgs(argv) {
   const args = argv.slice(2);
   let command = "";
   const flags = {};
   const positionals = [];
+  const shortFlags = [];
   let positional;
   let i = 0;
+  let endOfOptions = false;
   while (i < args.length) {
     const arg = args[i];
-    if (arg.startsWith("--")) {
+    if (!endOfOptions && arg === "--" && command !== "") {
+      endOfOptions = true;
+    } else if (!endOfOptions && arg.startsWith("--")) {
       i = parseFlag(args, i, flags, command === "");
+    } else if (!endOfOptions && command !== "" && /^-[A-Za-z]/.test(arg)) {
+      shortFlags.push(arg);
     } else if (command === "") {
       command = arg;
     } else if (positional === undefined) {
@@ -5360,8 +6826,10 @@ function parseArgs(argv) {
     }
     i++;
   }
-  return { command, positional, positionals, flags };
+  return { command, positional, positionals, flags, ...shortFlags.length > 0 ? { shortFlags } : {} };
 }
+var DRY_RUN_TRUE = new Set(["true", "yes", "1", "on"]);
+var DRY_RUN_FALSE = new Set(["false", "no", "0", "off"]);
 var GLOBAL_BOOLEAN_FLAGS = new Set([
   "agent",
   "json",
@@ -5450,7 +6918,7 @@ Commands:
   profiles use <name>              Switch active Moda profile
   profiles create <name>           Create or update a local Moda profile
   profiles doctor [name]           Validate a local Moda profile
-  keys list                        List local key descriptors
+  keys list                        List local key descriptors (not server-side API keys)
   keys create                      Create a local key descriptor
   config show                      Show resolved Moda config
   harness analyze                  Produce a cited structured harness report
@@ -5461,14 +6929,14 @@ Commands:
   harness candidates               Static (no-LLM) harness candidate pre-pass with file:line citations
   harness sync                     Sync the local harness graph to Moda Cloud
   harness delete <id-or-key>       Permanently delete a synced harness from Moda Cloud
+  harness list|show|versions|diff  List synced harnesses, show one, its versions, or a version diff
   harness agents                   List detected runtime agents and families
   harness explain                  Explain the discovered harness graph
   agent context                    Emit local Moda context for coding agents
-  agent investigate                Diagnose local Moda readiness for agents
   agent next-action                Emit prioritized next commands for agents
   agent evidence <ref>             Expand one evidence reference
-  investigate                      Rank production issues with evidence
-  failures                         Show production failures worth fixing first
+  investigate                      Rank production issues (tool failures, frustrations, top Problems)
+  failures                         Tool failures only, ranked (no frustrations or Problems)
   ask "question"                   Ask Moda a production/harness question
   sync                             Sync the local harness graph to Moda Cloud
   sync harness                     Sync the local harness graph to Moda Cloud
@@ -5480,20 +6948,25 @@ Commands:
   clusters                         Browse topic cluster hierarchy
   cluster-traces <node_id>         List traces in a cluster
   traces                           Search and filter traces (agent runs)
+  traces --sort=longest            Sort traces: recent (default), longest, slowest
   search "<query>"                 Search trace messages (keyword/semantic/hybrid)
   world-state <conversation_id>    Get a trace's world state (slots/threads/events)
   context <conversation_id>        Get windowed trace context
+  context <conversation_id> --all  Whole transcript in order (first 500; --from=N --max-messages=N to continue)
   audit <conversation_id|trace_id> Raw span audit (spans, hierarchy, orphans, duplicates)
-  frustrations                     Get user frustration detections (legacy single-family; see emotions)
-  emotions                         Multi-family emotion detections (frustration, sadness, confusion, anxiety, trust, positive)
+  frustrations                     Frustration detections (same data as emotions --family=frustration)
+  emotions                         Multi-family emotion detections (frustration, disapproval, sadness, confusion, anxiety, trust, positive)
   hallucinations                   Grounding detections: contradicted/verified outputs with rule breakdown
   laziness                         Laziness detections per trace (repeated calls, premature handoffs, ...)
   tool-failures                    Get tool failure overview
-  tool-failure-detail <tool_name>  Get per-tool failure detail
+  tool-failure-detail <tool_name>  Get per-tool failure detail (--limit=N examples, 1-20, default 5;
+                                   long example text is cut to 300 chars)
   problems                         Rank cross-signal Problems by root cause (what to fix first)
+  problems remainder               Signals no Problem explains yet (--family, --cursor)
   problem-impact                   Live problem/use-case impact (--node-id, --problem-id, --mode, --days-back)
   problem <problem_id>             Open one Problem: dossier, or --evidence/--reports/--traces/--feedback
   problem-feedback <problem_id>    Mark a Problem fixed, dismiss, rename, or flag a bad attribution
+  problem-reopen <problem_id>      Reopen a Problem marked fixed (--reason)
   false-positive <kind> <target>   Mark any detection as a false positive, optional --reason (problem, problem-detection, quote, tool, laziness, hallucination, custom-signal)
   false-positives [conv_id]        Current false-positive marks: all (--kind, --all, --limit) or one trace
   problem-linear <problem_id>      Show the Linear issue linked to a Problem (key, state, URL)
@@ -5502,6 +6975,10 @@ Commands:
   detection-review <problem_id>    Mark a problem detection correct, a false positive, or clear the review
   signals                          List custom signals (name, criteria, status, 7-day stats)
   signal <signal_id>               One custom signal, or --detections for its recent hits
+  signals create|update|activate|pause|delete ...
+                                   Manage custom signals (also draft, examples, refine, revise,
+                                   proposals, accept, reject, search, preview); writes take --dry-run
+  users / user <user_id>           End users with health and activity (the dashboard Users page)
   trace-signals <conversation_id>  Custom signal hits on one trace
   signal-label <signal_id>         Label a trace fits / does_not_fit (false positive) for a signal
   step-scores <conversation_id>    Graph-PRM step scores (per-segment curves, first bad step, rollup)
@@ -5515,9 +6992,11 @@ Commands:
   Prompt management:
   prompts init                     Create .moda/prompts.yml
   prompts status                   Show local prompt changes
-  prompts diff                     Show local prompt changes
+  prompts diff                     Only changed/new/deleted prompts since last sync
   prompts sync                     Analyze prompt sources and upload versions
   prompts sync --watch             Upload again when prompt files change
+  prompts list|show|proposals|usage|replay-runs|decide
+                                   Read the prompt registry; decide merges/rejects a proposal
   prompts promote <key>            Move a dev/staging/prod label
   prompts ab                       Run a judged prompt A/B replay experiment
   prompts propose                  Revise a prompt from a run's failures (--gate to auto-A/B, --promote-on-win)
@@ -5530,15 +7009,19 @@ Commands:
   skills pull --status=proposed    Include not-yet-promoted skills (default: approved)
   skills sync                      Push local .claude/skills/**/SKILL.md up to Moda
   skills sync --dry-run            Show what would be pushed without writing
+  skills list|show|policy          List pushed skills, show one, or set --live/--local
+  registry push                    Push prompts, skills, and tools from one JSON manifest
 
   Fixes (a fix with proof):
   fixes                            Ranked Fix queue (--status=S --limit=N --cursor=TOKEN)
   fixes draft-batch                Campaign mode: batch-draft fixes for the top-ranked problems
-                                   (--limit=N, 1-25, default 10 — batches cap at 25: LLM spend guard)
+                                   (--limit=N, 1-25, default 5 — batches cap at 25: LLM spend guard)
   fixes drive                      Round-robin one advance per active fix per pass until all rest
                                    (--status=S narrows the server-side scan window to one advancing
-                                   status, --timeout=ms default 2h, --pass-interval=ms default 20s;
-                                   exit 3 when the timeout lapses with fixes still advancing)
+                                   status, --max-fixes=N 1-10 default 3 fixes per run (rest skipped;
+                                   GATING fixes count toward N; least-recently-driven first),
+                                   --timeout=ms default 2h, --pass-interval=ms default 20s;
+                                   exit 3 when the timeout lapses, fixes were skipped, or still advancing)
   fix <fix_id>                     One Fix: status + gate result; --packet prints moda.fix_packet.v1
                                    (tool/skill candidates are also written under .moda/fixes/<ref>/);
                                    --wait drives a still-running pipeline to rest
@@ -5546,6 +7029,7 @@ Commands:
                                    scope -> propose -> gate and prints the packet
   fix verify <fix_id>              Re-gate on the frozen holdout; --prompt-file=P gates local content
                                    (exit 0 pass / 1 fail with per-case findings / 3 degraded-inconclusive)
+                                   Refuses a re-gate within 10 min of the last verdict unless --yes
   fix checkout <fix_id>            Write the candidate at its target source path (never runs git)
   fix submit <fix_id>              Deliver: --pr opens a draft PR | --local-ref=<branch> records your branch
   fix mark-applied <fix_id>        Confirm a candidate you applied in your own stack (--note=TEXT);
@@ -5581,7 +7065,7 @@ Output auto-detection (no flags needed):
   --no-update-check                Skip the daily new-version check (or MODA_CLI_UPDATE_CHECK=0)
 
 Traces flags:
-  --search=TEXT                    Substring match on the trace summary
+  --search=TEXT                    Ranked trace search (hybrid when embeddings exist, else keyword)
   --world-state=KEYWORDS           Match world-state content (slots + durable profile); comma = AND
   --outcome=any|positive|negative  Filter by trace outcome (trajectory + frustration)
   --include-world-state            Attach each result's world-state summary
@@ -5604,12 +7088,12 @@ World-state flags:
   --message-count=N                Number of frames to fold (frames mode)
 
 Emotions flags:
-  --family=F                       frustration|sadness|confusion|anxiety|trust|positive
+  --family=F                       frustration|disapproval|sadness|confusion|anxiety|trust|positive
   --days-back=N --limit=N          Window 1-90 (default 7); page size 1-20 (default 10)
   --offset=N                       Skip N detections (0-10000)
 
 Laziness flags:
-  --family=F                       Narrow to one laziness family
+  --family=F                       One laziness family (e.g. omission_phrase, stub_body, deflection, completion, tool_selection)
   --conversation-id=ID             One trace's detections
   --days-back=N --limit=N          Window 1-90 (default 7); page size 1-50 (default 10)
 
@@ -5622,7 +7106,7 @@ Problem flags (moda problem <id>):
   --evidence|--reports|--traces|--feedback
                                    Open one sub-resource page (at most one)
   --limit=N --cursor=TOKEN         Keyset paging (1-50; pass next_cursor back verbatim)
-  --family=F --door=D              Filter --traces (families: tool_failure|emotion|laziness|hallucination|prm_dip)
+  --family=F --door=D              Filter --traces (families: tool_failure|emotion|laziness|hallucination|prm_dip|custom_signal|conversation_reader)
 
 Problem-feedback flags:
   --action=A                       mark_fixed|dismiss|flag_attribution|rename (required)
@@ -5721,6 +7205,8 @@ Init flags:
   --no-sdk-integrate               Skip SDK integration (alias: --no-sdk-guide)
   --verification-id=ID             Tag the SDK integration's test trace with this id
                                    (the onb_ id from the Moda onboarding page)
+  --connect-code=CODE              Sign in with the one-time mcc_ code from the Moda
+                                   onboarding page instead of the browser (10 min, single use)
   --ci-cd                          Create GitHub Actions Moda validation workflow
   --no-ci-cd                       Skip CI/CD workflow creation
   --autosync                       Create GitHub Actions workflow to sync prompts + skills to Moda on push to main
@@ -5829,6 +7315,9 @@ function printCommandHelp(definition) {
   if (definition.mutability === "write") {
     lines.push("This command can mutate state.");
   }
+  for (const note of definition.helpNotes ?? []) {
+    lines.push("", note);
+  }
   if (definition.subcommands && definition.subcommands.length > 0) {
     lines.push("", "Subcommands:");
     const width = Math.max(...definition.subcommands.map((entry) => entry.name.length));
@@ -5884,7 +7373,8 @@ async function attachWindows(rows, windowSize) {
     }
     const conversation = asRecord(row.conversation);
     const embedded = conversation ? embeddedWindowSize(conversation) : null;
-    if (conversation && embedded !== null && embedded >= windowSize) {
+    const embeddedCenter = asNumber(asRecord(conversation?.context)?.center_index);
+    if (conversation && embedded !== null && embedded >= windowSize && embeddedCenter === msg_index) {
       return { ...row, window: conversation };
     }
     try {
@@ -5899,15 +7389,18 @@ async function attachWindows(rows, windowSize) {
     }
   }));
 }
-async function printWithOptionalWindows(enriched, listKey, includeWindow, windowSize, output, warnings) {
-  const writeOptions = warnings && warnings.length > 0 ? { warnings } : undefined;
-  if (!includeWindow) {
-    output.writeData(enriched, writeOptions);
-    return;
+var TOOL_FAILURE_DETAIL_DEFAULT_LIMIT = 5;
+var TOOL_FAILURE_AGENT_SUBTYPES = 20;
+async function printWithOptionalWindows(enriched, listKey, includeWindow, windowSize, output, warnings, finalize) {
+  const allWarnings = [...warnings ?? []];
+  let data = enriched;
+  if (includeWindow) {
+    const list = Array.isArray(enriched[listKey]) ? enriched[listKey] : [];
+    data = { ...enriched, [listKey]: await attachWindows(list, windowSize) };
   }
-  const list = Array.isArray(enriched[listKey]) ? enriched[listKey] : [];
-  const withWindows = await attachWindows(list, windowSize);
-  output.writeData({ ...enriched, [listKey]: withWindows }, writeOptions);
+  if (finalize)
+    data = finalize(data, allWarnings);
+  output.writeData(data, allWarnings.length > 0 ? { warnings: allWarnings } : undefined);
 }
 function notFoundWarning(entity, id, isMissing) {
   if (!isMissing)
@@ -5916,6 +7409,23 @@ function notFoundWarning(entity, id, isMissing) {
     `No ${entity} found for id "${id}" — it may not exist in this tenant (the Data API returns an empty result rather than an error for unknown ids).`
   ];
 }
+var AUDIT_DEFAULT_LIMIT = 200;
+var AUDIT_MAX_LIMIT = 1000;
+function auditCapStatus(data, limit) {
+  const record = asRecord(data);
+  if (!record)
+    return null;
+  const summary = asRecord(record.summary) ?? {};
+  const rows = (asNumber(summary.ingest_rows) ?? (Array.isArray(record.ingest) ? record.ingest.length : 0)) + (asNumber(record.parse_errors) ?? 0);
+  const spans = asNumber(summary.total_spans) ?? (Array.isArray(record.spans) ? record.spans.length : 0);
+  const hasMore = record.has_more === true || summary.has_more === true;
+  const spansCapped = summary.truncated === true || record.truncated === true;
+  const serverSaid = typeof record.has_more === "boolean" || typeof summary.has_more === "boolean";
+  const rowsCapped = hasMore || !serverSaid && rows >= limit;
+  if (!rowsCapped && !spansCapped)
+    return null;
+  return { rowsCapped, spansCapped, hasMoreKnown: hasMore, rows, spans };
+}
 var TAIL_SEEN_MAX = 5000;
 var EMOTIONS_TAIL_PAGE_SIZE = 20;
 var EMOTIONS_TAIL_MAX_PAGES = 25;
@@ -6097,7 +7607,7 @@ async function runTailCommand(params, context) {
       break;
     if (params.max_events !== undefined && emitted >= params.max_events)
       break;
-    await new Promise((resolve3) => setTimeout(resolve3, intervalMs));
+    await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
   }
 }
 async function attachWorldState(rows) {
@@ -6195,7 +7705,435 @@ function linearApiError(error) {
   }
   return error;
 }
+var GLOBAL_FLAG_NAMES = new Set([
+  ...[...GLOBAL_BOOLEAN_FLAGS].filter((flag2) => flag2 !== "dry-run"),
+  "profile",
+  "progress",
+  "no-stream",
+  "format",
+  "no-telemetry",
+  "no-update-check"
+]);
+var OVERVIEW_PRODUCTION_FLAGS = ["raw"];
+var WINDOW_FLAG_HINTS = {
+  days_back: "This command takes --time-range (e.g. --time-range=7d), not --days-back.",
+  time_range: "This command takes --days-back=N (1-90), not --time-range."
+};
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1;i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1;j <= b.length; j++) {
+      const current = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length];
+}
+function schemaFlagKeys(schema) {
+  let current = schema;
+  while (current instanceof z2.ZodEffects)
+    current = current.innerType();
+  return current instanceof z2.ZodObject ? Object.keys(current.shape) : [];
+}
+function parseCommandFlags(schema, args, command, options = {}) {
+  const schemaKeys = schemaFlagKeys(schema);
+  const known = new Set([
+    ...schemaKeys,
+    ...[...GLOBAL_FLAG_NAMES, ...options.extraFlags ?? []].map((flag2) => flag2.replace(/-/g, "_"))
+  ]);
+  const unknown = Object.keys(args).filter((key) => !known.has(key));
+  if (unknown.includes("dry_run")) {
+    throw new CliInputError(`'moda ${command}' has no dry-run mode, so nothing was sent.`, `Remove --dry-run to run it for real. Commands with a real dry-run: sync, registry push, harness sync/delete, prompts sync/decide, skills sync/policy, signals <write subcommands>, problem-reopen.`);
+  }
+  if (unknown.length > 0) {
+    const flagKeys = schemaKeys.filter((key) => key !== options.positionalKey);
+    const valid = flagKeys.map((key) => `--${key.replace(/_/g, "-")}`);
+    const hints = unknown.map((key) => {
+      const windowAlternative = key === "days_back" ? "time_range" : key === "time_range" ? "days_back" : undefined;
+      if (windowAlternative && WINDOW_FLAG_HINTS[key] && flagKeys.includes(windowAlternative))
+        return WINDOW_FLAG_HINTS[key];
+      if (windowAlternative)
+        return `This command has no time-window flag.`;
+      const close = flagKeys.map((candidate) => ({ candidate, distance: editDistance(key, candidate) })).filter(({ distance }) => distance <= 2).sort((left, right) => left.distance - right.distance)[0];
+      return close ? `Did you mean --${close.candidate.replace(/_/g, "-")}?` : "";
+    }).filter(Boolean);
+    const names = unknown.map((key) => `--${key.replace(/_/g, "-")}`).join(", ");
+    throw new CliInputError(`Unknown flag${unknown.length > 1 ? "s" : ""} ${names} for 'moda ${command}'.`, [...hints, `Valid flags: ${valid.join(", ") || "(none)"}. Run 'moda ${command} --help'.`].join(" "));
+  }
+  return schema.parse(args);
+}
+function withStringIdFlags(args, flags) {
+  for (const flag2 of ["user-id", "conversation-id"]) {
+    if (flags[flag2] !== undefined)
+      args[flag2.replace(/-/g, "_")] = flags[flag2];
+  }
+  return args;
+}
+function shellArg(value) {
+  if (/^[A-Za-z0-9_.,:@%+\/=-]+$/.test(value))
+    return value;
+  if (!/["$`\\!]/.test(value))
+    return `"${value}"`;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function searchFallbackToTraces(params) {
+  const limit = Math.min(params.limit ?? 20, 100);
+  const offset = params.offset ?? 0;
+  const query = new URLSearchParams;
+  query.set("search", params.q);
+  if (params.user_id)
+    query.set("user_id", params.user_id);
+  if (params.time_range)
+    query.set("time_range", params.time_range);
+  query.set("limit", String(limit));
+  if (offset > 0)
+    query.set("offset", String(offset));
+  const tracesCommand = [
+    `moda traces --search=${shellArg(params.q)}`,
+    params.user_id ? `--user-id=${shellArg(params.user_id)}` : "",
+    params.time_range ? `--time-range=${shellArg(params.time_range)}` : "",
+    `--limit=${limit}`
+  ].filter(Boolean).join(" ");
+  let traces;
+  try {
+    traces = asRecord(await callDataAPI(`/conversations?${query.toString()}`)) ?? {};
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      kind: "notice",
+      warning: `Message-level search returned 0 results, and the trace-level fallback failed (${reason}). ` + "Zero results here does NOT mean the topic never came up. Retry, or run the trace search directly.",
+      nextCommands: [{ command: tracesCommand, purpose: "Retry the trace-level search directly.", mutability: "read", requires_approval: false }]
+    };
+  }
+  const rows = Array.isArray(traces.conversations) ? traces.conversations.map(asRecord).filter(isDefinedRecord) : [];
+  if (rows.length === 0)
+    return;
+  const pagination = asRecord(traces.pagination);
+  const total = asNumber(pagination?.total) ?? rows.length;
+  const nextOffset = offset + rows.length;
+  const hasMore = pagination?.has_more === true || (asNumber(pagination?.total) ?? 0) > nextOffset;
+  const traceMode = asString(traces.search_mode) ?? "keyword";
+  const literal = traceMode === "keyword";
+  if (params.mode === "keyword" && !literal) {
+    return {
+      kind: "notice",
+      warning: `Message-level keyword search returned 0 results. Trace-level search is only available ${traceMode}-ranked here ` + `(results may not contain the exact words), so none are substituted for --mode=keyword. ` + "Zero results here does NOT mean the words never appear; the message index may be incomplete.",
+      nextCommands: [{ command: tracesCommand, purpose: "See ranked trace-level results instead.", mutability: "read", requires_approval: false }]
+    };
+  }
+  const results = rows.map((row) => ({
+    match_grain: "trace",
+    conversation_id: row.conversation_id,
+    summary: row.summary ?? null,
+    message_count: row.message_count ?? null,
+    first_timestamp: row.first_timestamp ?? null,
+    last_timestamp: row.last_timestamp ?? null
+  }));
+  const first = asString(rows[0].conversation_id);
+  const describe = literal ? "trace-level keyword matches (each trace contains the words)" : `trace-level ${traceMode}-ranked related traces (they may not contain the exact words; fallback.total is the candidate pool, not a match count)`;
+  const nextCommands = [];
+  if (first) {
+    nextCommands.push({ command: `moda audit ${first}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
+  }
+  if (hasMore) {
+    nextCommands.push({ command: `${tracesCommand} --offset=${nextOffset}`, purpose: "Page through further trace-level results.", mutability: "read", requires_approval: false });
+  }
+  return {
+    kind: "results",
+    hasMore,
+    data: {
+      results,
+      fallback: {
+        source: "traces_search",
+        reason: "message_index_empty",
+        grain: "trace",
+        search_mode: traceMode,
+        total,
+        total_kind: literal ? "matches" : "candidate_pool",
+        has_more: hasMore,
+        ...offset > 0 ? { offset } : {},
+        ...hasMore ? { next_offset: nextOffset } : {}
+      }
+    },
+    warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. ` + `Each result is a whole trace, not a message, with no score or message index. ` + `Open one with \`moda audit <conversation_id>\` or \`moda context <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
+    nextCommands
+  };
+}
+function capProblemsBlocks(data, limit) {
+  const truncated = {};
+  const payload = { ...data };
+  if (Array.isArray(data.emerging) && data.emerging.length > limit) {
+    truncated.emerging = data.emerging.length - limit;
+    payload.emerging = data.emerging.slice(0, limit);
+  }
+  const hierarchy = asRecord(data.hierarchy);
+  if (hierarchy && Array.isArray(hierarchy.macros) && hierarchy.macros.length > limit) {
+    truncated.hierarchy_macros = hierarchy.macros.length - limit;
+    payload.hierarchy = { ...hierarchy, macros: hierarchy.macros.slice(0, limit) };
+  }
+  return Object.keys(truncated).length > 0 ? { payload, truncated } : { payload };
+}
+function serverWarnings(data) {
+  const list = data?.warnings;
+  return Array.isArray(list) ? list.filter((item) => typeof item === "string") : [];
+}
+function isDefinedRecord(value) {
+  return value !== undefined && value !== null;
+}
+var HAND_PARSED_COMMAND_FLAGS = {
+  investigate: ["days-back", "tool", "trace", "conversation"],
+  failures: ["days-back", "tool"],
+  ask: ["days-back", "stream"],
+  "step-scores": [],
+  "trace-signals": [],
+  signals: [],
+  "problem-feedback": ["action", "actor", "reason", "attribution-id", "new-name"],
+  "problem-linear": [],
+  "problem-linear-file": ["issue", "priority", "title", "team-id"],
+  "signal-label": ["label", "note", "conversation-id", "msg-dedup-token", "msg-index"],
+  "detection-reviews": ["attribution-id"],
+  "detection-review": ["note", "verdict", "attribution-id", "conversation-id"],
+  "false-positive": [
+    "family",
+    "quote",
+    "reason",
+    "tool",
+    "turn",
+    "undo",
+    "attribution-id",
+    "conversation-id",
+    "msg-dedup-token",
+    "msg-index",
+    "tool-use-id"
+  ],
+  "false-positives": ["all", "kind", "limit"],
+  feedback: ["category", "severity", "cluster-id", "conversation-id", "run-id", "tool-name"],
+  "problem-impact": ["mode", "node-id", "problem-id", "run-id", "to", "cursor", "conversation-ids", "days-back"]
+};
+var NO_POSITIONAL_COMMANDS = new Set([
+  "overview",
+  "investigate",
+  "failures",
+  "signals",
+  "emotions",
+  "frustrations",
+  "laziness",
+  "hallucinations",
+  "tool-failures",
+  "traces",
+  "conversations",
+  "clusters",
+  "tail",
+  "problem-impact"
+]);
+function assertHandParsedFlags(command, flags, positionals) {
+  if (command === "signals" && positionals[0]) {
+    if (SIGNALS_MANAGEMENT_SUBCOMMANDS.has(positionals[0]))
+      return;
+    throw unknownSignalsSubcommandError(positionals[0], positionals.slice(1));
+  }
+  if (NO_POSITIONAL_COMMANDS.has(command) && positionals.length > 0) {
+    throw new CliInputError(`'moda ${command}' takes no arguments, but got '${positionals.join(" ")}'.`, `Nothing was run. See 'moda ${command} --help' for its flags.`);
+  }
+  const allowed = HAND_PARSED_COMMAND_FLAGS[command];
+  if (!allowed)
+    return;
+  const shape = z2.object(Object.fromEntries(allowed.map((flag2) => [flag2.replace(/-/g, "_"), z2.unknown()])));
+  const args = Object.fromEntries(Object.keys(flags).map((flag2) => [flag2.replace(/-/g, "_"), true]));
+  parseCommandFlags(shape.passthrough(), args, command);
+}
+var PROFILE_MANAGING_COMMANDS = new Set(["profiles", "auth", "init", "provision", "status", "config", "keys", "manifest", "agent", "doctor"]);
+async function runProblemsRemainder(flags, context) {
+  const params = parseCommandFlags(ProblemsRemainderSchema, flagsToArgs(flags), "problems remainder");
+  const query = new URLSearchParams;
+  if (params.days_back)
+    query.set("days_back", params.days_back.toString());
+  if (params.limit)
+    query.set("limit", params.limit.toString());
+  if (params.family)
+    query.set("family", params.family);
+  if (params.cursor)
+    query.set("cursor", params.cursor);
+  const queryString = query.toString() ? `?${query.toString()}` : "";
+  context.output.writeData(await callDataAPI(`/problems/remainder${queryString}`));
+}
+function processingDisabledWarning(data, family) {
+  const processing = asRecord(asRecord(data)?.processing);
+  const label = family === "emotion" ? "Emotion" : "Frustration";
+  if (processing?.enabled === null) {
+    return [`Could not confirm whether ${family} analysis is enabled for this tenant, so treat zero results with caution.`];
+  }
+  if (processing?.enabled !== false)
+    return [];
+  if (asString(processing.reason) === "dogfood_tenant") {
+    return [`${label} analysis is skipped for this internal (dogfood) tenant, so zero results do NOT mean users are not frustrated.`];
+  }
+  const setting = asString(processing.setting) ?? "signals.frustration";
+  return [
+    `${family === "emotion" ? "Emotion" : "Frustration"} analysis is disabled for this tenant (${setting} = false), ` + "so zero results do NOT mean users are not frustrated. Enable it in Settings → Account → Signal processing; " + "only traces ingested after enabling are analyzed."
+  ];
+}
+var FULL_TRANSCRIPT_DEFAULT_MAX_MESSAGES = 500;
+var CONTEXT_RANGE_PAGE_SIZE = 200;
+var LEGACY_WINDOW_MAX_MESSAGES = 100;
+var CONTEXT_MESSAGE_TRUNCATE_CHARS = 500;
+var LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g;
+function stripLoneSurrogates(value) {
+  if (typeof value === "string")
+    return value.replace(LONE_SURROGATE, "");
+  if (Array.isArray(value))
+    return value.map(stripLoneSurrogates);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, stripLoneSurrogates(v)]));
+  }
+  return value;
+}
+function isUnknownRangeParamsError(error) {
+  const e = error;
+  if (e?.statusCode !== 400)
+    return false;
+  const text = `${typeof e.responseBody === "string" ? e.responseBody : ""} ${typeof e.message === "string" ? e.message : ""}`;
+  return /property (from|count) should not exist/i.test(text);
+}
+function pageMessages(page) {
+  const messages = asRecord(page.context)?.messages ?? page.messages;
+  return (Array.isArray(messages) ? messages : []).map((m) => asRecord(m) ?? {});
+}
+async function readFullTranscript(conversationId, opts = {}) {
+  const start = opts.from ?? 0;
+  const requested = opts.maxMessages ?? FULL_TRANSCRIPT_DEFAULT_MAX_MESSAGES;
+  const path = `/conversations/${encodeURIComponent(conversationId)}/context`;
+  const warnings = [];
+  const messages = [];
+  let total = 0;
+  let summary = null;
+  let ordering;
+  let nextFrom = null;
+  let legacy = false;
+  let cursor = start;
+  for (;; ) {
+    const count = Math.min(CONTEXT_RANGE_PAGE_SIZE, requested - messages.length);
+    let page;
+    try {
+      page = asRecord(await callDataAPI(`${path}?from=${cursor}&count=${count}`)) ?? {};
+    } catch (error) {
+      if (cursor === start && isUnknownRangeParamsError(error)) {
+        legacy = true;
+        break;
+      }
+      throw error;
+    }
+    if (cursor === start) {
+      total = asNumber(page.total_messages) ?? 0;
+      summary = page.summary ?? null;
+      ordering = asRecord(page.ordering) ?? undefined;
+    }
+    const batch = pageMessages(page);
+    messages.push(...batch);
+    const next = asNumber(page.next_from);
+    nextFrom = page.has_more === true && next !== null && next !== undefined && next > cursor ? next : null;
+    if (nextFrom === null || batch.length === 0 || messages.length >= requested)
+      break;
+    cursor = nextFrom;
+  }
+  if (legacy) {
+    const limit = Math.min(requested, LEGACY_WINDOW_MAX_MESSAGES);
+    const window = 5;
+    const span = window * 2 + 1;
+    const byIndex = new Map;
+    for (let center = start + window;; center += span) {
+      const page = asRecord(await callDataAPI(`${path}?msg_index=${center}&window=${window}`)) ?? {};
+      if (center === start + window) {
+        total = asNumber(page.total_messages) ?? 0;
+        summary = page.summary ?? null;
+      }
+      for (const message of pageMessages(page)) {
+        const index = asNumber(message.index);
+        if (index !== null && index !== undefined && index >= start && index < start + limit)
+          byIndex.set(index, message);
+      }
+      if (center + window + 1 >= Math.min(total, start + limit))
+        break;
+    }
+    messages.push(...[...byIndex.entries()].sort(([a], [b]) => a - b).map(([, message]) => message));
+    const end = start + messages.length;
+    nextFrom = end < total && messages.length > 0 ? end : null;
+    warnings.push(`This Moda server has no range reads for context (older backend), so --all fell back to windowed paging ` + `and stopped at ${LEGACY_WINDOW_MAX_MESSAGES} messages to keep it cheap.`);
+  }
+  const pageSize = legacy ? LEGACY_WINDOW_MAX_MESSAGES : requested;
+  const tied = asNumber(ordering?.tied_timestamp_messages) ?? 0;
+  const synthetic = asNumber(ordering?.synthetic_timestamp_messages) ?? 0;
+  const atCap = (value) => {
+    const text = typeof value === "string" ? value : value === undefined || value === null ? "" : JSON.stringify(value);
+    return text.length >= CONTEXT_MESSAGE_TRUNCATE_CHARS;
+  };
+  const isTruncated = (record) => {
+    const toolCalls = Array.isArray(record.tool_calls) ? record.tool_calls : [];
+    const toolResults = Array.isArray(record.tool_results) ? record.tool_results : [];
+    return atCap(record.content) || toolCalls.some((call) => atCap(asRecord(call)?.input)) || toolResults.some((result) => atCap(asRecord(result)?.content));
+  };
+  const build = (kept) => {
+    const returned = messages.slice(0, kept);
+    const out = [...notFoundWarning("trace", conversationId, total === 0), ...warnings];
+    if (total > 0 && start >= total) {
+      out.push(`--from=${start} is past the end of this trace (${total} messages, indexes 0-${total - 1}).`);
+    }
+    const nextCommands = [];
+    const firstMissing = kept < messages.length ? asNumber(messages[kept]?.index) ?? start + kept : null;
+    const next = firstMissing ?? nextFrom;
+    if (next !== null) {
+      const last = asNumber(returned[returned.length - 1]?.index) ?? next - 1;
+      const nextMax = firstMissing !== null ? Math.min(pageSize, Math.max(kept * 2, 50)) : pageSize;
+      const continueWith = `moda context ${shellArg(conversationId)} --all --from=${next} --max-messages=${nextMax}`;
+      out.push(`Trace has ${total} messages; returned messages ${start}-${last}. ` + (firstMissing !== null ? `Stopped at ${kept} of the ${messages.length} messages read to stay under the agent output byte limit (--json has no limit). ` : "") + `Continue with: ${continueWith}`);
+      nextCommands.push({
+        command: continueWith,
+        purpose: `Read the next messages of this trace, starting at message ${next}.`,
+        mutability: "read",
+        requires_approval: false
+      });
+    }
+    if (tied > 0 || synthetic > 0) {
+      out.push(`Message order may not be chronological: ${tied} of ${total} messages share a timestamp with another message ` + `(ordered by id, not time)${synthetic > 0 ? ` and ${synthetic} carry a synthetic pre-2022 timestamp` : ""}.`);
+    }
+    if (returned.some(isTruncated)) {
+      out.push(`Message text, tool-call inputs and tool results longer than ${CONTEXT_MESSAGE_TRUNCATE_CHARS} characters are truncated by the context endpoint. ` + "For full raw content (prompts, tool arguments/results) use `moda audit <conversation_id> --include-raw`.");
+    }
+    return {
+      data: stripLoneSurrogates({
+        conversation_id: conversationId,
+        total_messages: total,
+        from: start,
+        returned: returned.length,
+        has_more: next !== null,
+        next_from: next,
+        summary,
+        ...ordering ? { ordering } : {},
+        messages: returned
+      }),
+      warnings: out,
+      nextCommands
+    };
+  };
+  const full = build(messages.length);
+  if (!opts.fits || messages.length <= 1 || opts.fits(full))
+    return full;
+  let low = 1;
+  let high = messages.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (opts.fits(build(mid)))
+      low = mid;
+    else
+      high = mid - 1;
+  }
+  return build(low);
+}
 async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
+  assertHandParsedFlags(command, flags, positionals);
   switch (command) {
     case "prompts": {
       await runPromptsCommand(context);
@@ -6203,7 +8141,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "overview": {
       const args = flagsToArgs(flags);
-      OverviewSchema.parse(args);
+      parseCommandFlags(OverviewSchema, args, command, { extraFlags: OVERVIEW_PRODUCTION_FLAGS });
       return (await runProductionCommand(context)).exitCode;
     }
     case "investigate":
@@ -6213,7 +8151,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "clusters": {
       const args = flagsToArgs(flags);
-      const params = ClustersSchema.parse(args);
+      const params = parseCommandFlags(ClustersSchema, args, command);
       if (params.search !== undefined || params.node_id !== undefined) {
         const query2 = new URLSearchParams;
         if (params.search !== undefined)
@@ -6247,7 +8185,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<node_id> is required", "Usage: moda cluster-traces <node_id> [--limit=N] [--offset=N]");
       }
       const args = flagsToArgs(flags, "node_id", positional);
-      const params = ClusterConversationsSchema.parse(args);
+      const params = parseCommandFlags(ClusterConversationsSchema, args, command, { positionalKey: "node_id" });
       const query = new URLSearchParams;
       if (params.limit)
         query.set("limit", params.limit.toString());
@@ -6262,8 +8200,8 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "traces":
     case "conversations": {
-      const args = flagsToArgs(flags);
-      const params = ConversationsSchema.parse(args);
+      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const params = parseCommandFlags(ConversationsSchema, args, command);
       const query = new URLSearchParams;
       if (params.search)
         query.set("search", params.search);
@@ -6279,20 +8217,40 @@ async function runCommand(command, positional, flags, positionals = positional ?
         query.set("world_state", params.world_state);
       if (params.outcome && params.outcome !== "any")
         query.set("outcome", params.outcome);
+      if (params.sort)
+        query.set("sort_by", params.sort);
       if (params.limit)
         query.set("limit", params.limit.toString());
       if (params.offset !== undefined)
         query.set("offset", params.offset.toString());
       const queryString = query.toString() ? `?${query.toString()}` : "";
-      const data = await callDataAPI(`/conversations${queryString}`);
-      recordConversationsTelemetry(context, data);
+      const raw = await callDataAPI(`/conversations${queryString}`);
+      recordConversationsTelemetry(context, raw);
+      const searchWarnings = [];
+      let data = raw;
+      const rawRecord = asRecord(raw);
+      if (params.search && rawRecord) {
+        const traceMode = asString(rawRecord.search_mode) ?? "keyword";
+        const literal = traceMode === "keyword";
+        data = { ...rawRecord, total_kind: literal ? "matches" : "candidate_pool" };
+        if (!literal) {
+          searchWarnings.push(`--search ran ${traceMode}-ranked: results are related traces that may not contain "${params.search}", and pagination.total is the candidate pool, not a match count.`);
+        }
+      }
+      if (params.sort === "slowest") {
+        const rows = asRecord(data)?.conversations;
+        if (Array.isArray(rows) && rows.length > 0 && rows.every((row) => asRecord(row)?.duration_ms == null)) {
+          searchWarnings.push("--sort=slowest: no trace in this page has a known duration (synthetic timestamps), so the order is not by duration. Use --sort=longest (message count) instead.");
+        }
+      }
+      const writeOptions = searchWarnings.length > 0 ? { warnings: searchWarnings } : undefined;
       if (params.include_world_state === true) {
         const enriched = asRecord(data) ?? {};
         const list = Array.isArray(enriched.conversations) ? enriched.conversations : [];
         const withState = await attachWorldState(list);
-        context.output.writeData({ ...enriched, conversations: withState });
+        context.output.writeData({ ...enriched, conversations: withState }, writeOptions);
       } else {
-        context.output.writeData(data);
+        context.output.writeData(data, writeOptions);
       }
       break;
     }
@@ -6300,8 +8258,8 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (!positional || positional.trim() === "") {
         throw new CliInputError("<query> is required", 'Usage: moda search "<query>" [--mode=keyword|semantic|hybrid] [--user-id=ID] [--time-range=RANGE] [--include-tool-io] [--limit=N]');
       }
-      const args = flagsToArgs(flags, "q", positional);
-      const params = SearchSchema.parse(args);
+      const args = withStringIdFlags(flagsToArgs(flags, "q", positional), flags);
+      const params = parseCommandFlags(SearchSchema, args, command, { positionalKey: "q" });
       const query = new URLSearchParams;
       query.set("q", params.q);
       if (params.mode)
@@ -6325,6 +8283,30 @@ async function runCommand(command, positional, flags, positionals = positional ?
       } else if (params.mode && actualMode && actualMode !== params.mode && params.mode !== "hybrid") {
         warnings.push(`Search ran in ${actualMode} mode instead of the requested ${params.mode} mode.`);
       }
+      const results = Array.isArray(searchRecord.results) ? searchRecord.results : [];
+      if (results.length > 0 && (params.offset ?? 0) > 0) {
+        warnings.push(`--offset=${params.offset} was not applied: message-level search is not pageable (it returns the top --limit hits). ` + "--offset only pages the trace-level fallback. Narrow with --time-range/--user-id or raise --limit instead.");
+      }
+      if (results.length === 0) {
+        const fallback = await searchFallbackToTraces({ ...params, offset: params.offset });
+        if (fallback?.kind === "notice") {
+          warnings.push(fallback.warning);
+          context.output.writeData(data, { warnings, nextCommands: fallback.nextCommands });
+          break;
+        }
+        if (fallback?.kind === "results") {
+          warnings.push(fallback.warning);
+          const fallbackResults = fallback.data.results;
+          const merged = {
+            ...searchRecord,
+            ...fallback.data,
+            pagination: { ...asRecord(searchRecord.pagination) ?? {}, returned: fallbackResults.length, has_more: fallback.hasMore }
+          };
+          recordSearchTelemetry(context, merged);
+          context.output.writeData(merged, { warnings, nextCommands: fallback.nextCommands });
+          break;
+        }
+      }
       context.output.writeData(data, warnings.length > 0 ? { warnings } : undefined);
       break;
     }
@@ -6333,7 +8315,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<conversation_id> is required", "Usage: moda world-state <conversation_id> [--summary-only] [--event-limit=N]");
       }
       const args = flagsToArgs(flags, "conversation_id", positional);
-      const params = WorldStateSchema.parse(args);
+      const params = parseCommandFlags(WorldStateSchema, args, command, { positionalKey: "conversation_id" });
       if (params.snapshot === true && params.replay === true) {
         throw new CliInputError("Choose either --snapshot or --replay, not both.", "Usage: moda world-state <conversation_id> [--snapshot --msg-index=N [--block-index=M] [--segment-index=K]] | [--replay --message-count=N [--format=frames|fold-inputs]]");
       }
@@ -6382,7 +8364,26 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<conversation_id> is required", "Usage: moda context <conversation_id> [--msg-index=N] [--window=N]");
       }
       const args = flagsToArgs(flags, "conversation_id", positional);
-      const params = ContextSchema.parse(args);
+      const params = parseCommandFlags(ContextSchema, args, command, { positionalKey: "conversation_id" });
+      if (params.all === true) {
+        if (params.msg_index !== undefined || flags.window !== undefined) {
+          throw new CliInputError("--all reads the whole trace; drop --msg-index/--window.", "Usage: moda context <conversation_id> --all [--from=N] [--max-messages=N]");
+        }
+        const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
+        const full = await readFullTranscript(params.conversation_id, {
+          from: params.from,
+          maxMessages: params.max_messages,
+          fits: agentMode ? (page) => agentEnvelopeFits(command, page.data, { warnings: page.warnings, nextCommands: page.nextCommands }) : undefined
+        });
+        context.output.writeData(full.data, {
+          ...full.warnings.length > 0 ? { warnings: full.warnings } : {},
+          ...full.nextCommands.length > 0 ? { nextCommands: full.nextCommands } : {}
+        });
+        break;
+      }
+      if (params.from !== undefined || params.max_messages !== undefined) {
+        throw new CliInputError("--from and --max-messages page the whole trace and need --all.", "Usage: moda context <conversation_id> --all [--from=N] [--max-messages=N]");
+      }
       const query = new URLSearchParams;
       if (params.msg_index !== undefined)
         query.set("msg_index", params.msg_index.toString());
@@ -6401,7 +8402,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<conversation_id|trace_id> is required", "Usage: moda audit <conversation_id|trace_id> [--kind=auto|trace|conversation] [--include-raw] [--limit=N]");
       }
       const args = flagsToArgs(flags, "id", positional);
-      const params = AuditSchema.parse(args);
+      const params = parseCommandFlags(AuditSchema, args, command, { positionalKey: "id" });
       const query = new URLSearchParams;
       if (params.kind && params.kind !== "auto")
         query.set("kind", params.kind);
@@ -6411,12 +8412,37 @@ async function runCommand(command, positional, flags, positionals = positional ?
         query.set("limit", params.limit.toString());
       const queryString = query.toString() ? `?${query.toString()}` : "";
       const data = await callDataAPI(`/audit/${encodeURIComponent(params.id)}${queryString}`);
-      context.output.writeData(data);
+      const capped = auditCapStatus(data, params.limit ?? AUDIT_DEFAULT_LIMIT);
+      const auditRecord = asRecord(data);
+      if (!capped || !auditRecord) {
+        context.output.writeData(auditRecord ? { ...auditRecord, truncated: false, has_more: false } : data);
+        break;
+      }
+      const limit = params.limit ?? AUDIT_DEFAULT_LIMIT;
+      const perTrace = "audit one OTLP trace at a time with `moda audit <trace_id> --kind=trace` (ids in summary.trace_ids)";
+      const warnings = [];
+      const nextCommands = [];
+      if (capped.rowsCapped) {
+        const bigger = Math.min(AUDIT_MAX_LIMIT, limit * 5);
+        warnings.push(`Spans were capped: read ${capped.rows} ingest row(s), the --limit=${limit} maximum, so this trace ${capped.hasMoreKnown ? "has" : "may have"} more spans than the ${capped.spans} shown. ` + (limit < AUDIT_MAX_LIMIT ? `Rerun with --limit=${bigger} (max ${AUDIT_MAX_LIMIT}), or ${perTrace}.` : `${perTrace[0].toUpperCase()}${perTrace.slice(1)}.`));
+        if (limit < AUDIT_MAX_LIMIT) {
+          const rerun = [
+            `moda ${command} ${shellArg(params.id)}`,
+            params.kind && params.kind !== "auto" ? `--kind=${params.kind}` : "",
+            params.include_raw === true ? "--include-raw" : "",
+            `--limit=${bigger}`
+          ].filter(Boolean).join(" ");
+          nextCommands.push({ command: rerun, purpose: "Read more ingest rows of this trace.", mutability: "read", requires_approval: false });
+        }
+      } else {
+        warnings.push(`Spans were capped: the server returned ${capped.spans} span(s) and marked the response truncated. ${perTrace[0].toUpperCase()}${perTrace.slice(1)}.`);
+      }
+      context.output.writeData({ ...auditRecord, truncated: true, has_more: capped.rowsCapped }, { warnings, ...nextCommands.length > 0 ? { nextCommands } : {} });
       break;
     }
     case "frustrations": {
-      const args = flagsToArgs(flags);
-      const params = FrustrationsSchema.parse(args);
+      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const params = parseCommandFlags(FrustrationsSchema, args, command);
       const query = new URLSearchParams;
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
@@ -6424,14 +8450,18 @@ async function runCommand(command, positional, flags, positionals = positional ?
         query.set("limit", params.limit.toString());
       if (params.offset !== undefined)
         query.set("offset", params.offset.toString());
-      const queryString = query.toString() ? `?${query.toString()}` : "";
-      const data = await callDataAPI(`/frustrations${queryString}`);
-      await printWithOptionalWindows(withFrustrationAnchors(data), "frustrations", params.include_window === true, params.window ?? 1, context.output);
+      if (params.user_id)
+        query.set("user_id", params.user_id);
+      if (params.conversation_id)
+        query.set("conversation_id", params.conversation_id);
+      query.set("family", "frustration");
+      const data = frustrationsFromEmotions(await callDataAPI(`/emotions?${query.toString()}`));
+      await printWithOptionalWindows(withFrustrationAnchors(data), "frustrations", params.include_window === true, params.window ?? 1, context.output, processingDisabledWarning(data, "frustration"));
       break;
     }
     case "tool-failures": {
       const args = flagsToArgs(flags);
-      const params = ToolFailuresSchema.parse(args);
+      const params = parseCommandFlags(ToolFailuresSchema, args, command);
       const queryString = params.days_back ? `?days_back=${params.days_back}` : "";
       const data = await callDataAPI(`/tool-failures${queryString}`);
       context.output.writeData(data);
@@ -6439,17 +8469,27 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "tool-failure-detail": {
       if (!positional) {
-        throw new CliInputError("<tool_name> is required", "Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N] [--offset=N]");
+        throw new CliInputError("<tool_name> is required", "Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N (1-20, default 5)] [--offset=N] [--compact | --include-window [--window=N]]");
+      }
+      const { "no-include-window": noIncludeWindow, ...toolFlags } = flags;
+      if (noIncludeWindow !== undefined && noIncludeWindow !== "false") {
+        if (toolFlags["include-window"] !== undefined && toolFlags["include-window"] !== "false") {
+          throw new CliInputError("Choose either --include-window or --no-include-window, not both.");
+        }
+        toolFlags["include-window"] = "false";
+      }
+      const args = flagsToArgs(toolFlags, "tool_name", positional);
+      const params = parseCommandFlags(ToolFailureDetailSchema, args, command, { positionalKey: "tool_name" });
+      const dropConversation = params.compact === true || params.include_window === false;
+      if (params.compact === true && params.include_window === true) {
+        throw new CliInputError("--compact drops the conversation window; drop --include-window, or drop --compact.");
       }
-      const args = flagsToArgs(flags, "tool_name", positional);
-      const params = ToolFailureDetailSchema.parse(args);
       const query = new URLSearchParams;
       if (params.subtype)
         query.set("subtype", params.subtype);
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
-      if (params.limit)
-        query.set("limit", params.limit.toString());
+      query.set("limit", (params.limit ?? TOOL_FAILURE_DETAIL_DEFAULT_LIMIT).toString());
       if (params.offset !== undefined)
         query.set("offset", params.offset.toString());
       const queryString = query.toString() ? `?${query.toString()}` : "";
@@ -6460,7 +8500,28 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const warnings = subtypeCount === 0 && exampleCount === 0 ? [
         `No failures found for tool "${params.tool_name}" in the last ${params.days_back ?? 7} day(s) — the tool may have no failures in this window, or the name may not exist in this tenant. Run \`moda tool-failures\` to list tools with recorded failures, or widen --days-back.`
       ] : [];
-      await printWithOptionalWindows(withToolFailureAnchors(data), "examples", params.include_window === true, params.window ?? 1, context.output, warnings);
+      const knownSubtypes = Array.isArray(tfRecord.subtypes) ? tfRecord.subtypes.map((row) => asString(asRecord(row)?.subtype)).filter((value) => Boolean(value)) : [];
+      if (params.subtype && knownSubtypes.length > 0 && !knownSubtypes.includes(params.subtype)) {
+        warnings.push(`--subtype=${params.subtype} is not a failure subtype of "${params.tool_name}" in this window, so no examples matched. ` + `Valid subtypes: ${knownSubtypes.slice(0, 10).join(", ")}${knownSubtypes.length > 10 ? `, … (${knownSubtypes.length - 10} more in \`subtypes\`)` : ""}.`);
+      }
+      await printWithOptionalWindows(withToolFailureAnchors(data), "examples", params.include_window === true, params.window ?? 1, context.output, warnings, (payload, out) => {
+        let trimmed = trimToolFailureConversations(payload, {
+          drop: dropConversation || params.include_window === true,
+          windowRadius: params.window ?? 1
+        });
+        const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
+        const subtypes = Array.isArray(trimmed.subtypes) ? trimmed.subtypes : [];
+        if (agentMode && subtypes.length > TOOL_FAILURE_AGENT_SUBTYPES) {
+          const ranked = [...subtypes].sort((a, b) => (asNumber(asRecord(b)?.count) ?? 0) - (asNumber(asRecord(a)?.count) ?? 0));
+          trimmed = { ...trimmed, subtypes: ranked.slice(0, TOOL_FAILURE_AGENT_SUBTYPES), subtypes_total: subtypes.length };
+          out.push(`Showing the ${TOOL_FAILURE_AGENT_SUBTYPES} most frequent of ${subtypes.length} failure subtypes; --json lists all of them.`);
+        }
+        const { data: compacted, truncated } = compactToolFailureExamples(trimmed);
+        if (truncated > 0) {
+          out.push(`${truncated} long text field(s) in examples were cut to ${TOOL_FAILURE_TEXT_LIMIT} characters to keep this output small. For the full text, run each example's \`context_command\` (\`moda context <conversation_id> --msg-index=<msg_index>\`).`);
+        }
+        return compacted;
+      });
       break;
     }
     case "problem-impact": {
@@ -6489,12 +8550,20 @@ async function runCommand(command, positional, flags, positionals = positional ?
         link.set("useCase", params.node_id);
       const problem = asString(data.problemId) || params.problem_id;
       const path = problem ? `/dashboard/problems/${encodeURIComponent(problem)}` : params.node_id ? `/dashboard/use-cases/${encodeURIComponent(params.node_id)}` : "/dashboard/use-cases";
-      context.output.writeData({ ...data, dashboard_url: `${resolveModaBaseUrl()}${path}?${link}` });
+      const impactWarnings = serverWarnings(data);
+      context.output.writeData({ ...data, dashboard_url: `${resolveModaBaseUrl()}${path}?${link}` }, impactWarnings.length > 0 ? { warnings: impactWarnings } : undefined);
       break;
     }
     case "problems": {
+      if (positional === "remainder") {
+        await runProblemsRemainder(flags, context);
+        break;
+      }
+      if (positional) {
+        throw new CliInputError(`Unknown problems subcommand '${positional}'.`, "Usage: moda problems [--days-back=N] [--limit=N] | moda problems remainder [--family=F] [--days-back=N] [--limit=N] [--cursor=TOKEN]. For one Problem use 'moda problem <id>'.");
+      }
       const args = flagsToArgs(flags);
-      const params = ProblemsSchema.parse(args);
+      const params = parseCommandFlags(ProblemsSchema, args, command);
       const query = new URLSearchParams;
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
@@ -6502,19 +8571,26 @@ async function runCommand(command, positional, flags, positionals = positional ?
         query.set("limit", params.limit.toString());
       const queryString = query.toString() ? `?${query.toString()}` : "";
       const data = await callDataAPI(`/problems${queryString}`);
+      const { payload, truncated } = capProblemsBlocks(asRecord(data) ?? {}, params.limit ?? 25);
       const withLink = {
-        ...asRecord(data) ?? {},
+        ...payload,
+        ...truncated ? { truncated } : {},
         dashboard_url: `${MODA_BASE_URL}/dashboard/problems`
       };
-      context.output.writeData(withLink);
+      const warnings = [...serverWarnings(payload), ...truncated ? [`--limit=${params.limit ?? 25} also capped ${Object.entries(truncated).map(([block, count]) => `${block} (${count} more)`).join(", ")}; raise --limit (max 25) or open dashboard_url for the rest.`] : []];
+      context.output.writeData(withLink, warnings.length > 0 ? { warnings } : undefined);
       break;
     }
     case "problem": {
+      if (positional === "remainder") {
+        await runProblemsRemainder(flags, context);
+        break;
+      }
       if (!positional) {
         throw new CliInputError("<problem_id> is required", "Usage: moda problem <problem_id> [--evidence|--reports|--traces|--feedback] [--limit=N] [--cursor=TOKEN] [--family=F] [--door=D]");
       }
       const args = flagsToArgs(flags, "id", positional);
-      const params = ProblemSchema.parse(args);
+      const params = parseCommandFlags(ProblemSchema, args, command, { positionalKey: "id" });
       const traceView = params.traces === true || params.conversations === true;
       const views = ["evidence", "reports", "conversations", "feedback"].filter((view2) => view2 === "conversations" ? traceView : params[view2] === true);
       if (views.length > 1) {
@@ -6662,6 +8738,9 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     case "signals": {
+      if (positional && SIGNALS_MANAGEMENT_SUBCOMMANDS.has(positional)) {
+        return (await runSignalsManagementCommand(positional, context)).exitCode;
+      }
       const data = await callDataAPI("/custom-signals");
       context.output.writeData(data);
       break;
@@ -6672,7 +8751,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       }
       const args = flagsToArgs(flags, "id", positional);
       args.id = positional;
-      const params = SignalSchema.parse(args);
+      const params = parseCommandFlags(SignalSchema, args, command, { positionalKey: "id" });
       const id = encodeURIComponent(params.id);
       if (params.detections !== true) {
         const data2 = await callDataAPI(`/custom-signals/${id}`);
@@ -6861,8 +8940,8 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     case "emotions": {
-      const args = flagsToArgs(flags);
-      const params = EmotionsSchema.parse(args);
+      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const params = parseCommandFlags(EmotionsSchema, args, command);
       const query = new URLSearchParams;
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
@@ -6872,9 +8951,14 @@ async function runCommand(command, positional, flags, positionals = positional ?
         query.set("offset", params.offset.toString());
       if (params.family)
         query.set("family", params.family);
+      if (params.user_id)
+        query.set("user_id", params.user_id);
+      if (params.conversation_id)
+        query.set("conversation_id", params.conversation_id);
       const queryString = query.toString() ? `?${query.toString()}` : "";
       const data = await callDataAPI(`/emotions${queryString}`);
-      context.output.writeData(data);
+      const processingWarnings = processingDisabledWarning(data, "emotion");
+      context.output.writeData(data, processingWarnings.length > 0 ? { warnings: processingWarnings } : undefined);
       break;
     }
     case "laziness": {
@@ -6882,7 +8966,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (flags["conversation-id"] !== undefined) {
         args.conversation_id = flags["conversation-id"];
       }
-      const params = LazinessSchema.parse(args);
+      const params = parseCommandFlags(LazinessSchema, args, command);
       const query = new URLSearchParams;
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
@@ -6904,7 +8988,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (flags["conversation-id"] !== undefined) {
         args.conversation_id = flags["conversation-id"];
       }
-      const params = HallucinationsSchema.parse(args);
+      const params = parseCommandFlags(HallucinationsSchema, args, command);
       const query = new URLSearchParams;
       if (params.days_back)
         query.set("days_back", params.days_back.toString());
@@ -6938,7 +9022,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "tail": {
       const args = flagsToArgs(flags);
-      const params = TailSchema.parse(args);
+      const params = parseCommandFlags(TailSchema, args, command);
       await runTailCommand(params, context);
       break;
     }
@@ -7084,7 +9168,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result",
     handler: async (context) => {
-      const { runInit } = await import("./index-vmmfya6b.js");
+      const { runInit } = await import("./index-qgc37efj.js");
       if (context.outputMode === "agent-stream") {
         context.output.writeEvent({
           event: "started",
@@ -7125,7 +9209,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runProvision } = await import("./provision-spwn5t41.js");
+      const { runProvision } = await import("./provision-gabtks29.js");
       return runProvision(context, {
         resumeCommand: buildResumeCommand("provision", context.rawFlags)
       });
@@ -7267,6 +9351,7 @@ var commandRegistry = createCommandRegistry([
     description: "Diagnose local Moda setup and data flow",
     examples: ["moda doctor", "moda doctor --json", "moda doctor --offline"],
     auth: "none",
+    authNote: "Offline by default; --online checks the API key and data flow.",
     outputModes: ["human", "json", "agent"],
     mutability: "read",
     validateConfigBeforeRun: false,
@@ -7300,7 +9385,7 @@ var commandRegistry = createCommandRegistry([
   },
   {
     name: "keys",
-    description: "Manage local key descriptors and cloud key lifecycle requirements",
+    description: "Local key descriptors in ~/.moda only (not your server-side API keys; manage those in the dashboard)",
     examples: ["moda keys list", "moda keys create --name=local-dev"],
     auth: "none",
     outputModes: ["human", "json", "agent"],
@@ -7322,7 +9407,9 @@ var commandRegistry = createCommandRegistry([
       "moda harness delete my-harness-key --yes",
       "moda harness explain --agent=agent_support"
     ],
-    auth: "none",
+    subcommands: HARNESS_SUBCOMMAND_HELP,
+    auth: "api-key",
+    authNote: "sync, list, show, versions, diff, delete, pull, and analyze need the API key; scan, explain, agents, graph, approve, and validate-report are local.",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,
@@ -7332,10 +9419,9 @@ var commandRegistry = createCommandRegistry([
   },
   {
     name: "agent",
-    description: "Agent-native Moda context, investigations, next actions, and evidence",
+    description: "Agent-native local Moda context, next actions, and evidence (production investigation: moda investigate)",
     examples: [
       "moda agent context",
-      "moda agent investigate",
       "moda agent next-action",
       "moda agent evidence doctor:api_key_resolves"
     ],
@@ -7355,7 +9441,7 @@ var commandRegistry = createCommandRegistry([
       "moda sync harness --from-report .moda/harness-report.json",
       "moda sync prompts"
     ],
-    auth: "none",
+    auth: "api-key",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,
@@ -7363,6 +9449,92 @@ var commandRegistry = createCommandRegistry([
     telemetry: "none",
     handler: runSyncCommand
   },
+  {
+    name: "users",
+    description: "List end users with health, frustration and activity (the dashboard Users page)",
+    examples: [
+      "moda users --window=30d --sort=health_score --order=asc",
+      "moda users --cohort=frustrated --min-conversations=3"
+    ],
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "read",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: runUsersCommand
+  },
+  {
+    name: "user",
+    description: "One end user's profile: health, traits, frustration trajectory, activity",
+    examples: ["moda user u-123 --window=30d"],
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "read",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: runUserCommand
+  },
+  {
+    name: "problem-reopen",
+    description: "Reopen a problem that was marked fixed (resolved problems return only via re-detection)",
+    examples: ['moda problem-reopen <problem_id> --reason="still happening"', "moda problem-reopen <problem_id> --dry-run"],
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "write",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: runProblemReopenCommand
+  },
+  {
+    name: "registry",
+    description: "Push prompts, skills, and tools to Moda from one agent-written JSON manifest (no repo scan)",
+    examples: [
+      "moda registry template --out=.moda/registry.json",
+      "moda registry validate",
+      "moda registry push --dry-run",
+      "moda registry push --file=.moda/registry.json"
+    ],
+    subcommands: [
+      {
+        name: "template",
+        description: "Print (or write with --out) an example moda_registry.v1 manifest",
+        usage: "moda registry template [--out=<path>] [--yes]",
+        flags: [
+          { name: "--out=<path>", description: "Write the template to a file instead of stdout (refuses to overwrite without --yes)." }
+        ],
+        examples: ["moda registry template --out=.moda/registry.json"]
+      },
+      {
+        name: "validate",
+        description: "Validate a manifest locally without contacting Moda",
+        usage: "moda registry validate [--file=<path>]",
+        flags: [{ name: "--file=<path>", description: "Manifest path (default .moda/registry.json)." }],
+        examples: ["moda registry validate --file=.moda/registry.json"]
+      },
+      {
+        name: "push",
+        description: "Upload the manifest's prompts, skills, and tools to the API key's tenant",
+        usage: "moda registry push [--file=<path>] [--dry-run] [--live]",
+        flags: [
+          { name: "--file=<path>", description: "Manifest path (default .moda/registry.json)." },
+          { name: "--dry-run", description: "Server-side preview; nothing is written. Without an API key, validates locally only." },
+          { name: "--live", description: "Mark every pushed skill live (included in the served skill surface)." }
+        ],
+        examples: ["moda registry push --dry-run", "moda registry push --live"]
+      }
+    ],
+    auth: "api-key",
+    authNote: "template and validate are local; push needs the API key (push --dry-run without a key validates locally only).",
+    outputModes: ["human", "json", "agent"],
+    mutability: "write",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "none",
+    handler: runRegistryCommand
+  },
   legacyCommand({
     name: "overview",
     description: "Harness health briefing from production data",
@@ -7371,25 +9543,32 @@ var commandRegistry = createCommandRegistry([
   }),
   legacyCommand({
     name: "investigate",
-    description: "Rank production issues with evidence and next commands",
+    description: "Rank production issues (tool failures, frustrations, top Problems) with evidence and next commands. --trace scopes only the frustration evidence.",
     examples: ["moda investigate", "moda investigate --tool lookupCustomer"],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "failures",
-    description: "Show production failures worth fixing first",
+    description: "Tool failures only, ranked with evidence (no frustrations or Problems; use investigate or problems for those)",
     examples: ["moda failures", "moda failures --tool lookupCustomer"],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "ask",
-    description: "Ask Moda a production intelligence question",
+    description: "Ask Moda a production intelligence question (one paid agent run per question)",
     examples: [
       'moda ask "what should I fix first?"',
       'moda ask "what should I fix first?" --no-stream',
+      'moda ask "what changed this week?" --days-back=7',
       'moda --agent ask "why did this run fail?"'
     ],
-    ...dataApiDefaults
+    helpNotes: [
+      "Cost: each question starts one agent run on Moda (LLM calls, up to about 200k tokens). Re-asking the same question pays again.",
+      "Streaming: in a terminal, ask streams live progress. If the stream fails before the server accepts the run, ask retries once on the buffered endpoint. If it drops after the server accepted the run, ask does NOT re-run the question (that would pay for a second run): it fails, and the run may still finish server-side. Retry later with --no-stream.",
+      "Flags: --days-back=N (window for the evidence), --no-stream (buffered request, no live progress; --json and --agent never stream)."
+    ],
+    ...dataApiDefaults,
+    mutability: "write"
   }),
   legacyCommand({
     name: "clusters",
@@ -7409,7 +9588,7 @@ var commandRegistry = createCommandRegistry([
     name: "traces",
     aliases: ["conversations"],
     telemetryCommand: "conversations",
-    description: "Search and filter traces (agent runs)",
+    description: "Search and filter traces (agent runs); --search is ranked (hybrid when embeddings exist, else keyword), see total_kind",
     examples: [
       'moda traces --search="error" --limit=5',
       'moda traces --world-state="enterprise" --outcome=positive',
@@ -7437,8 +9616,12 @@ var commandRegistry = createCommandRegistry([
   }),
   legacyCommand({
     name: "context",
-    description: "Get windowed trace context (messages around one turn)",
-    examples: ["moda context <conversation_id> --window=3"],
+    description: "Get windowed trace context (messages around one turn), or the whole trace with --all",
+    examples: [
+      "moda context <conversation_id> --window=3",
+      "moda context <conversation_id> --all",
+      "moda context <conversation_id> --all --from=500 --max-messages=500"
+    ],
     ...dataApiDefaults
   }),
   legacyCommand({
@@ -7448,13 +9631,14 @@ var commandRegistry = createCommandRegistry([
     examples: [
       "moda audit <conversation_id|trace_id>",
       "moda audit <trace_id> --kind=trace --json",
-      "moda audit <conversation_id> --include-raw"
+      "moda audit <conversation_id> --include-raw",
+      "moda audit <conversation_id> --limit=1000   # ingest rows to read (default 200, max 1000); warns when capped"
     ],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "frustrations",
-    description: "Get user frustration detections",
+    description: "User frustration detections: the frustration family of `emotions` (same data as the dashboard), legacy field names",
     examples: ["moda frustrations --days-back=14 --include-window"],
     ...dataApiDefaults
   }),
@@ -7466,14 +9650,19 @@ var commandRegistry = createCommandRegistry([
   }),
   legacyCommand({
     name: "tool-failure-detail",
-    description: "Get per-tool failure detail",
-    examples: ["moda tool-failure-detail search --include-window"],
+    description: "Get per-tool failure detail (each example embeds its anchor ±2 messages, long text cut to 300 chars)",
+    examples: [
+      "moda tool-failure-detail search",
+      "moda tool-failure-detail search --compact   # no embedded conversation (same as --include-window=false)",
+      "moda tool-failure-detail search --include-window --window=3"
+    ],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "problems",
     description: "Rank cross-signal Problems by root cause (what to fix first)",
-    examples: ["moda problems", "moda problems --days-back=7 --limit=10"],
+    examples: ["moda problems", "moda problems --days-back=7 --limit=10", "moda problems remainder --family=emotion"],
+    subcommands: PROBLEMS_SUBCOMMAND_HELP,
     ...dataApiDefaults
   }),
   legacyCommand({
@@ -7580,9 +9769,16 @@ var commandRegistry = createCommandRegistry([
   }),
   legacyCommand({
     name: "signals",
-    description: "List custom signals with criteria, status, and 7-day judged/matched stats",
-    examples: ["moda signals"],
-    ...dataApiDefaults
+    description: "List and manage custom signals (create, update, activate/pause/delete, examples, refine, proposals, search)",
+    examples: [
+      "moda signals",
+      'moda signals draft --note="agent promises a refund it cannot issue"',
+      'moda signals create --name="Refund promise" --description=… --pass-criteria=… --fail-criteria=… --dry-run',
+      "moda signals activate <signal_id>"
+    ],
+    subcommands: SIGNALS_SUBCOMMAND_HELP,
+    ...dataApiDefaults,
+    mutability: "write"
   }),
   legacyCommand({
     name: "signal",
@@ -7611,7 +9807,7 @@ var commandRegistry = createCommandRegistry([
   }),
   legacyCommand({
     name: "emotions",
-    description: "Multi-family emotion detections (frustration, sadness, confusion, anxiety, trust, positive)",
+    description: "Multi-family emotion detections (frustration, disapproval, sadness, confusion, anxiety, trust, positive)",
     examples: [
       "moda emotions --days-back=7",
       "moda emotions --family=confusion --limit=20"
@@ -7684,7 +9880,7 @@ var commandRegistry = createCommandRegistry([
       },
       {
         name: "diff",
-        description: "Alias of status: show local prompt changes",
+        description: "Only the prompts that changed, are new, or were deleted since the last sync (hash-level; status lists all)",
         usage: "moda prompts diff",
         examples: ["moda prompts diff"]
       },
@@ -7716,11 +9912,15 @@ var commandRegistry = createCommandRegistry([
       {
         name: "ab",
         description: "Run a judged prompt A/B replay experiment",
-        usage: "moda prompts ab --baseline=<path> --candidate=<path> --traces=<ids>",
+        usage: "moda prompts ab --baseline=<path> --candidate=<path> [--traces=<ids>|--set-id=<id>|--auto-generate] [--yes]",
         flags: [
           { name: "--baseline=<path>", description: "Prompt file to treat as the control." },
           { name: "--candidate=<path>", description: "Prompt file to treat as the variant." },
-          { name: "--traces=<ids>", description: "Comma-separated trace ids (conversation_id values) to replay. Legacy alias: --conversations=<ids>." }
+          { name: "--traces=<ids>", description: "Comma-separated trace ids (conversation_id values) to replay, at most 100. Legacy alias: --conversations=<ids>." },
+          { name: "--cases=<n>", description: "Cases to auto-generate (default 5, max 100)." },
+          { name: "--seeds=<n>", description: "Repeats per case per arm (default 3, max 10)." },
+          { name: "--model=<slug>", description: "Assistant model for both arms; must be in the replay allowlist unless --allow-any-model." },
+          { name: "--yes", description: "Confirm a run above 200 planned playouts (cases x seeds x 2 arms), or one whose case count is unknown." }
         ],
         examples: [
           "moda prompts ab --baseline=prompts/agent.prompt.md --candidate=prompts/agent-v2.prompt.md --traces=conv_1,conv_2"
@@ -7728,14 +9928,23 @@ var commandRegistry = createCommandRegistry([
       },
       {
         name: "propose",
-        description: "Revise a prompt from a run's failures",
-        usage: "moda prompts propose [--gate] [--promote-on-win]",
+        description: "Revise a prompt from a run's failures (one LLM call; --gate adds paid replays)",
+        usage: "moda prompts propose --prompt-key=<key> --from-run=<run_id> --set-id=<replay_set_id> [--max-dossiers=N] [--model=<slug>] [--out=<path>] [--gate [--seeds=N] [--yes]] [--promote-on-win]",
         flags: [
-          { name: "--gate", description: "Automatically A/B the proposed revision." },
+          { name: "--prompt-key=<key>", description: "Required. Registered prompt to revise." },
+          { name: "--from-run=<run_id>", description: "Required. The `prompts ab` run whose failures drive the revision." },
+          { name: "--set-id=<replay_set_id>", description: "Required. The replay set that run used; --gate replays all of it. A set that does not exist fails before anything is sent." },
+          { name: "--max-dossiers=<n>", description: "Failure dossiers to revise from (default 8, max 16)." },
+          { name: "--model=<slug>", description: "Revision model (replay allowlist unless --allow-any-model)." },
+          { name: "--out=<path>", description: "Write the candidate prompt to this file." },
+          { name: "--seeds=<n>", description: "Gate: repeats per case per arm (default 3, max 10)." },
+          { name: "--gate", description: "Automatically A/B the proposed revision over the full --set-id (planned playouts = cases x seeds x 2; above 200 needs --yes)." },
+          { name: "--yes", description: "Confirm a gate above 200 planned playouts, or one whose case count is unknown." },
           { name: "--promote-on-win", description: "Promote the candidate if it wins the gate." }
         ],
-        examples: ["moda prompts propose --gate --promote-on-win"]
-      }
+        examples: ["moda prompts propose --prompt-key=support.triage --from-run=<run_id> --set-id=<set_id> --gate --promote-on-win"]
+      },
+      ...PROMPTS_REGISTRY_SUBCOMMAND_HELP
     ],
     auth: "api-key",
     outputModes: ["human", "json", "agent"],
@@ -7755,7 +9964,9 @@ var commandRegistry = createCommandRegistry([
       "moda skills install --list",
       "moda skills install integration-node-openai"
     ],
-    auth: "none",
+    subcommands: SKILLS_SUBCOMMAND_HELP,
+    auth: "api-key",
+    authNote: "install is local; gen, status, pull, sync, list, show, policy, and proposals need the API key.",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,
@@ -7771,13 +9982,14 @@ var commandRegistry = createCommandRegistry([
     examples: [
       "moda fixes",
       "moda fixes --status=VERIFIED",
-      "moda fixes draft-batch --limit=10",
+      "moda fixes draft-batch --limit=5",
       "moda fixes drive",
       "moda fixes drive --status=SCOPING"
     ],
-    auth: "none",
+    auth: "api-key",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
+    subcommands: FIXES_SUBCOMMAND_HELP,
     validateConfigBeforeRun: false,
     resetApiRequestCountBeforeRun: false,
     telemetry: "result",
@@ -7788,6 +10000,7 @@ var commandRegistry = createCommandRegistry([
   {
     name: "fix",
     description: 'Draft, verify, check out, submit, and dismiss Fixes ("a fix with proof")',
+    subcommands: FIX_SUBCOMMAND_HELP,
     examples: [
       "moda fix start <problem_id> --wait",
       "moda fix <fix_id> --packet",
@@ -7797,7 +10010,7 @@ var commandRegistry = createCommandRegistry([
       'moda fix mark-applied <fix_id> --note="tool description updated in our agent config"',
       'moda fix dismiss <fix_id> --reason="not actionable"'
     ],
-    auth: "none",
+    auth: "api-key",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,
@@ -7876,6 +10089,17 @@ function printAgentCliError(command, error, mode = "agent") {
   output.writeError(error);
 }
 async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
+  const previousProfileEnv = process.env.MODA_PROFILE;
+  try {
+    return await dispatchParsedCommandInner(parsed, startedAt);
+  } finally {
+    if (previousProfileEnv === undefined)
+      delete process.env.MODA_PROFILE;
+    else
+      process.env.MODA_PROFILE = previousProfileEnv;
+  }
+}
+async function dispatchParsedCommandInner(parsed, startedAt) {
   const { command, flags } = parsed;
   const commandFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
   const telemetryDisabled = isTelemetryDisabled(flags);
@@ -7907,19 +10131,50 @@ async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     printHelp();
     return 1;
   }
-  const definition = commandRegistry.find(command);
-  if (!definition) {
-    const error = new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
+  const failEarly = (error) => {
     const mode = resolveOutputMode(commandFlags, {
       isTTY: process.stdout.isTTY,
       env: process.env
     });
-    if (mode === "agent" || mode === "agent-stream") {
+    if (mode === "agent" || mode === "agent-stream" || mode === "json") {
       printAgentCliError(command, error, mode);
     } else {
       printCliError(error);
     }
     return 1;
+  };
+  const definition = commandRegistry.find(command);
+  if (!definition) {
+    return failEarly(new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.'));
+  }
+  if (parsed.shortFlags?.length) {
+    return failEarly(new CliInputError(`Short options are not supported (${parsed.shortFlags.join(", ")}), so nothing was run.`, `Use the long form, e.g. --dry-run, --json, --quiet. See 'moda ${command} --help'.`));
+  }
+  for (const target of [flags, commandFlags]) {
+    const raw = target["dry-run"];
+    if (raw === undefined)
+      continue;
+    const value = raw.trim().toLowerCase();
+    if (DRY_RUN_TRUE.has(value))
+      target["dry-run"] = "true";
+    else if (DRY_RUN_FALSE.has(value))
+      delete target["dry-run"];
+    else {
+      return failEarly(new CliInputError(`--dry-run=${raw} is not a yes/no value, so nothing was run.`, "Pass --dry-run (or --dry-run=true) to preview, or omit it to run for real."));
+    }
+  }
+  if (commandFlags.profile === "true" || commandFlags.profile === "") {
+    return failEarly(new CliInputError("--profile needs a value, e.g. --profile=prod.", "List profiles with 'moda profiles list'."));
+  }
+  const requestedProfile = commandFlags.profile ?? process.env.MODA_PROFILE?.trim();
+  if (requestedProfile && !PROFILE_MANAGING_COMMANDS.has(definition.name)) {
+    const known = Object.keys(loadProfileConfig({ env: process.env }).profiles);
+    if (!known.includes(requestedProfile)) {
+      const source = commandFlags.profile ? `--profile=${requestedProfile}` : `MODA_PROFILE=${requestedProfile}`;
+      return failEarly(new CliInputError(`Moda profile '${requestedProfile}' does not exist (from ${source}), so nothing was run.`, `Known profiles: ${known.join(", ")}. Create it with 'moda profiles create ${requestedProfile}' or fix the name.`));
+    }
+    if (commandFlags.profile)
+      process.env.MODA_PROFILE = commandFlags.profile;
   }
   if (definition.name === "agent" && commandFlags.json !== "true") {
     commandFlags.agent = "true";
@@ -8061,7 +10316,7 @@ function installSignalHandlers() {
 async function main() {
   process.exitCode = await dispatchParsedCommand(parseArgs(process.argv));
 }
-var isMain = process.argv[1] && fileURLToPath(import.meta.url) === realpathSync2(process.argv[1]);
+var isMain = process.argv[1] && fileURLToPath(import.meta.url) === realpathSync3(process.argv[1]);
 if (isMain) {
   installSignalHandlers();
   main().catch((error) => {
@@ -8071,9 +10326,11 @@ if (isMain) {
 }
 export {
   telemetryCommandName,
+  stripLoneSurrogates,
   runCommand,
   resolveTailSignal,
   printCliError,
+  parseCommandFlags,
   parseArgs,
   initFlagsForContext,
   flagsToArgs,
@@ -8082,7 +10339,11 @@ export {
   describeLinearLink,
   commandRegistry,
   classifyCliError,
+  capProblemsBlocks,
   buildResumeCommand,
+  auditCapStatus,
   TAIL_LIMITS,
+  LEGACY_WINDOW_MAX_MESSAGES,
+  FULL_TRANSCRIPT_DEFAULT_MAX_MESSAGES,
   CliInputError
 };