@moda-ai/cli 1.55.18 → 1.55.20

package/dist/cli.js

@@ -5,27 +5,55 @@ import {
 import {
   createCommandContext,
   parseBooleanFlagValue
-} from "./cli-5hq827jt.js";
+} from "./cli-569hj0bj.js";
 import {
+  AuditSchema,
+  COMMAND_FLAG_SPECS,
+  DETECTION_VERDICTS,
+  DetectionReviewSchema,
+  FALSE_POSITIVE_KINDS,
+  FEEDBACK_USAGE,
+  FalsePositiveSchema,
+  PROBLEM_FEEDBACK_ACTIONS,
+  ProblemFeedbackSchema,
+  ProblemImpactSchema,
+  ProblemLinearFileSchema,
+  ProblemsRemainderSchema,
   SIGNALS_MANAGEMENT_SUBCOMMANDS,
+  SIGNAL_LABELS,
+  SignalLabelSchema,
+  StepScoresSchema,
+  UUID_RE,
   assertFlags,
   assertPositionals,
+  buildFeedbackRequest,
+  closestMatches,
+  describeSpecFlags,
+  flagSpecFor,
+  isFeedbackRefFlag,
+  kebabFlag,
+  manifestFlagFields,
+  renderFlagHelp,
   runProblemReopenCommand,
   runSignalsManagementCommand,
   runUserCommand,
   runUsersCommand,
+  schemaShape,
+  specFlagKeys,
+  specFlagNames,
+  subcommandHelpFlags,
   unknownSignalsSubcommandError
-} from "./cli-kg0kz05e.js";
+} from "./cli-cehskjde.js";
 import {
   ApiError,
   callControlAPI,
   callDataAPI
-} from "./cli-c8p69n55.js";
+} from "./cli-rqk6f6n6.js";
 import {
   apiKeyHeaders,
   isPlatformApiKey,
   setPlatformTenantOverride
-} from "./cli-eazeanvt.js";
+} from "./cli-7ea02wca.js";
 import {
   AGENT_ERROR_CODES,
   BATCH_CONCURRENCY,
@@ -50,6 +78,7 @@ import {
   asNumber,
   asRecord,
   asString,
+  attachInputDetails,
   collectBatchTargets,
   compactProblemDossier,
   contextTarget,
@@ -79,441 +108,14 @@ import {
   withFrustrationAnchors,
   withToolFailureAnchors,
   withoutDetectionWindows
-} from "./cli-3ezzeqcy.js";
+} from "./cli-5ke3xe6y.js";
 import {
   __require
 } from "./cli-0v6na3yp.js";
 
 // src/cli.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { z as z2 } from "zod";
-
-// src/schemas.ts
 import { z } from "zod";
-var boolFlag = () => z.preprocess((val) => {
-  const text = String(val).toLowerCase();
-  if (["true", "1", "yes", "on"].includes(text))
-    return true;
-  if (["false", "0", "no", "off"].includes(text))
-    return false;
-  return val;
-}, z.boolean()).optional();
-var DAYS_BACK_MESSAGE = "must be a whole number from 1 to 90 (e.g. --days-back=7)";
-var daysBackFlag = (fallback) => {
-  const days = z.number({ invalid_type_error: DAYS_BACK_MESSAGE }).int(DAYS_BACK_MESSAGE).min(1, DAYS_BACK_MESSAGE).max(90, DAYS_BACK_MESSAGE);
-  return fallback === undefined ? days.optional() : days.default(fallback).optional();
-};
-var ISO_BOUND_MESSAGE = "must be an ISO 8601 date (2026-10-07) or datetime (2026-10-07T14:30:00Z)";
-var ISO_BOUND = /^\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:[Zz]|[+-]\d{2}:?\d{2})?)?$/;
-var isoBoundFlag = () => z.string().trim().regex(ISO_BOUND, ISO_BOUND_MESSAGE).optional();
-var OverviewSchema = z.object({
-  days_back: daysBackFlag(7)
-});
-var ClustersSchema = z.object({
-  parent_id: z.string().optional(),
-  time_range: z.enum(["all", "1h", "3d", "7d", "24h", "30d", "90d"]).default("all").optional(),
-  search: z.string().min(2).max(200).optional(),
-  node_id: z.string().min(1).max(512).optional(),
-  mode: z.enum(["fuzzy", "semantic", "hybrid"]).optional(),
-  limit: z.number().min(1).max(50).optional()
-});
-var ClusterConversationsSchema = z.object({
-  node_id: z.string(),
-  limit: z.number().min(1).max(100).default(10).optional(),
-  offset: z.number().min(0).default(0).optional()
-});
-var ConversationsSchema = z.object({
-  search: z.string().optional(),
-  cluster_id: z.string().optional(),
-  user_id: z.string().optional(),
-  time_range: z.enum(["all", "1h", "3d", "24h", "7d", "30d", "90d"]).default("all").optional(),
-  since: isoBoundFlag(),
-  until: isoBoundFlag(),
-  environment: z.enum(["all", "development", "staging", "production"]).default("all").optional(),
-  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()
-});
-var WorldStateSchema = z.object({
-  conversation_id: z.string(),
-  summary_only: boolFlag(),
-  event_limit: z.number().min(1).max(5000).default(2000).optional(),
-  snapshot: boolFlag(),
-  msg_index: z.number().min(0).max(1e5).optional(),
-  block_index: z.number().min(0).max(1e5).optional(),
-  segment_index: z.number().min(0).max(65535).optional(),
-  replay: boolFlag(),
-  format: z.enum(["frames", "fold-inputs"]).optional(),
-  message_count: z.number().min(1).max(1e6).optional()
-});
-var ContextSchema = z.object({
-  conversation_id: z.string().min(1),
-  msg_index: z.number().int().min(0).optional(),
-  window: z.number().int().min(0).optional(),
-  metadata_only: boolFlag(),
-  all: boolFlag(),
-  from: z.number().int().min(0).optional(),
-  max_messages: z.number().int().min(1).max(5000).optional(),
-  ids_from: z.string().min(1).optional()
-});
-var FrustrationsSchema = z.object({
-  days_back: daysBackFlag(7),
-  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(),
-  user_id: z.string().min(1).max(256).optional(),
-  conversation_id: z.string().min(1).max(256).optional()
-});
-var ToolFailuresSchema = z.object({
-  days_back: daysBackFlag(7)
-});
-var ProblemsSchema = z.object({
-  days_back: daysBackFlag(30),
-  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: daysBackFlag(30),
-  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(),
-  problem_id: z.string().regex(UUID_RE).optional(),
-  run_id: z.string().min(1).max(256).optional(),
-  days_back: z.union([z.literal("all"), z.coerce.number().refine((n) => [1, 3, 7, 30, 90].includes(n), "Use all, 1, 3, 7, 30, or 90 days")]).default(7),
-  mode: z.enum(["metrics", "trend", "evidence", "catalog", "overview", "affected-use-cases", "trace-use-cases"]).default("metrics"),
-  to: z.string().datetime({ precision: 3 }).optional(),
-  cursor: z.string().min(1).optional(),
-  conversation_ids: z.string().transform((value, ctx) => {
-    try {
-      return z.array(z.string().min(1).max(512)).min(1).max(25).parse(JSON.parse(value));
-    } catch {
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Use a JSON array of 1–25 conversation IDs" });
-      return z.NEVER;
-    }
-  }).optional()
-}).refine((p) => p.mode !== "trace-use-cases" || p.problem_id && p.conversation_ids, {
-  message: "Trace use cases require --problem-id and --conversation-ids"
-}).refine((p) => p.node_id || p.problem_id || ["catalog", "overview"].includes(p.mode), {
-  message: "Select --node-id or --problem-id, or use --mode=catalog/overview"
-}).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 = REMAINDER_FAMILIES;
-var PROBLEM_DOORS = ["rubric_match", "local_causal_chain"];
-var ProblemSchema = z.object({
-  id: z.string().min(1),
-  evidence: boolFlag(),
-  reports: boolFlag(),
-  traces: boolFlag(),
-  conversations: boolFlag(),
-  feedback: boolFlag(),
-  full: boolFlag(),
-  limit: z.number().min(1).max(50).optional(),
-  cursor: z.string().optional(),
-  family: z.enum(PROBLEM_FAMILIES).optional(),
-  door: z.enum(PROBLEM_DOORS).optional()
-});
-var PROBLEM_FEEDBACK_ACTIONS = [
-  "mark_fixed",
-  "dismiss",
-  "flag_attribution",
-  "rename"
-];
-var ProblemFeedbackSchema = z.object({
-  id: z.string().min(1),
-  action: z.enum(PROBLEM_FEEDBACK_ACTIONS),
-  reason: z.string().max(2000).optional(),
-  attribution_id: z.string().max(64).optional(),
-  new_name: z.string().max(255).optional(),
-  actor: z.string().max(255).optional()
-});
-var ProblemLinearFileSchema = z.object({
-  id: z.string().min(1),
-  issue: z.string().max(2048).optional(),
-  team_id: z.string().max(255).optional(),
-  title: z.string().optional(),
-  priority: z.preprocess((v) => typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v) : v, z.number().int().min(0).max(4).optional())
-});
-var SignalSchema = z.object({
-  id: z.string().min(1).max(255),
-  detections: boolFlag(),
-  days_back: daysBackFlag(),
-  limit: z.number().min(1).max(20).optional(),
-  offset: z.number().min(0).max(1e4).optional()
-});
-var SIGNAL_LABELS = ["fits", "does_not_fit"];
-var SignalLabelSchema = z.object({
-  id: z.string().min(1).max(255),
-  conversation_id: z.string().min(1).max(255),
-  label: z.enum(SIGNAL_LABELS),
-  note: z.string().max(2000).optional(),
-  msg_index: z.preprocess((v) => typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v) : v, z.number().int().min(0).optional()),
-  msg_dedup_token: z.string().min(1).max(200).optional()
-});
-var DETECTION_VERDICTS = ["correct", "false_positive", "clear"];
-var DetectionReviewSchema = z.object({
-  id: z.string().regex(UUID_RE, "Problem id must be a canonical UUID"),
-  conversation_id: z.string().min(1).max(255),
-  attribution_id: z.string().regex(UUID_RE, "Attribution id must be a UUID"),
-  verdict: z.enum(DETECTION_VERDICTS),
-  note: z.string().max(2000).optional()
-});
-var FALSE_POSITIVE_KINDS = ["problem", "problem-detection", "quote", "tool", "laziness", "hallucination", "custom-signal"];
-var FalsePositiveSchema = z.object({
-  kind: z.enum(FALSE_POSITIVE_KINDS),
-  target: z.string().min(1).max(255),
-  undo: z.boolean(),
-  reason: z.string().max(2000).optional(),
-  conversation_id: z.string().min(1).max(255).optional(),
-  attribution_id: z.string().regex(UUID_RE, "Attribution id must be a UUID").optional(),
-  family: z.string().regex(/^[a-z_]{1,64}$/, "Family must be a lowercase emotion family").optional(),
-  turn: z.preprocess((v) => typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v) : v, z.number().int().min(0).optional()),
-  quote: z.string().min(1).max(4000).optional(),
-  tool: z.string().min(1).max(255).optional(),
-  tool_use_id: z.string().min(1).max(255).optional(),
-  msg_index: z.preprocess((v) => typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v) : v, z.number().int().min(0).optional()),
-  msg_dedup_token: z.string().min(1).max(200).optional()
-}).superRefine((v, ctx) => {
-  const need = (ok, message) => {
-    if (!ok)
-      ctx.addIssue({ code: z.ZodIssueCode.custom, message });
-  };
-  if (v.kind === "problem") {
-    need(UUID_RE.test(v.target), "Problem id must be a canonical UUID");
-    need(!v.undo, "A problem dismissal cannot be undone from the CLI");
-  }
-  if (v.kind === "problem-detection") {
-    need(UUID_RE.test(v.target), "Problem id must be a canonical UUID");
-    need(v.conversation_id, "--conversation-id is required for problem-detection");
-    need(v.attribution_id, "--attribution-id is required for problem-detection");
-  }
-  if (v.kind === "quote") {
-    need(v.family && v.turn !== undefined && v.quote, "--family, --turn and --quote are required for quote (copy them from moda emotions)");
-  }
-  if (v.kind === "tool") {
-    need(v.tool, "--tool is required for tool (the failing tool name)");
-    need(v.tool_use_id || v.msg_index !== undefined, "--tool-use-id or --msg-index is required for tool (from moda tool-failure-detail)");
-  }
-  if (v.kind === "custom-signal") {
-    need(v.conversation_id, "--conversation-id is required for custom-signal");
-  }
-});
-var EMOTION_FAMILIES = [
-  "frustration",
-  "disapproval",
-  "sadness",
-  "confusion",
-  "anxiety",
-  "trust",
-  "positive"
-];
-var EmotionsSchema = z.object({
-  days_back: daysBackFlag(7),
-  limit: z.number().min(1).max(20).default(10).optional(),
-  offset: z.number().min(0).max(1e4).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(),
-  include_window: boolFlag()
-});
-var HallucinationsSchema = z.object({
-  days_back: daysBackFlag(7),
-  limit: z.number().min(1).max(20).default(10).optional(),
-  offset: z.number().min(0).max(1e4).optional(),
-  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: daysBackFlag(7),
-  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.enum(LAZINESS_FAMILIES).optional()
-});
-var StepScoresSchema = z.object({
-  conversation_id: z.string().min(1)
-});
-var TAIL_SIGNALS = ["traces", "conversations", "emotions", "all"];
-var TailSchema = z.object({
-  interval: z.number().min(5).max(3600).default(15).optional(),
-  signal: z.enum(TAIL_SIGNALS).default("traces").optional(),
-  once: boolFlag(),
-  limit: z.number().min(1).max(50).default(20).optional(),
-  max_events: z.number().min(1).max(1e5).optional(),
-  full_scan: boolFlag()
-});
-var ToolFailureDetailSchema = z.object({
-  tool_name: z.string(),
-  subtype: z.string().optional(),
-  days_back: daysBackFlag(7),
-  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({
-  id: z.string().min(1),
-  kind: z.enum(["auto", "trace", "conversation"]).default("auto").optional(),
-  include_raw: boolFlag(),
-  include_bodies: boolFlag(),
-  limit: z.number().min(1).max(1000).default(200).optional(),
-  cursor: z.string().min(1).max(512).optional(),
-  ids_from: z.string().min(1).optional()
-});
-var TIME_RANGES = ["all", "1h", "3d", "7d", "24h", "30d", "90d"];
-var SEARCH_MODES = ["keyword", "semantic", "hybrid"];
-var SearchSchema = z.object({
-  q: z.string().min(1).max(500),
-  mode: z.enum(SEARCH_MODES).default("hybrid").optional(),
-  user_id: z.string().optional(),
-  conversation_id: z.string().min(1).max(256).optional(),
-  time_range: z.enum(TIME_RANGES).default("all").optional(),
-  since: isoBoundFlag(),
-  until: isoBoundFlag(),
-  limit: z.number().min(1).max(100).default(20).optional(),
-  include_tool_io: boolFlag(),
-  offset: z.number().min(0).max(1e4).optional()
-});
-
-// ../../packages/database/src/agent-feedback.ts
-var FEEDBACK_CATEGORIES = [
-  "bad_cluster_label",
-  "mismatched_frustration",
-  "missing_data",
-  "noisy_data",
-  "wrong_tool_failure",
-  "incorrect_loop",
-  "api_quirk",
-  "false_positive_attribution",
-  "misrouted_fix",
-  "harness_bug",
-  "other"
-];
-var FEEDBACK_SEVERITIES = ["info", "low", "medium", "high"];
-var DEFAULT_FEEDBACK_CATEGORY = "other";
-var RAW_FEEDBACK_CATEGORY_MAX = 64;
-function isFeedbackCategory(value) {
-  return typeof value === "string" && FEEDBACK_CATEGORIES.includes(value);
-}
-function normalizeFeedbackCategory(value) {
-  if (value === undefined || value === null || value === "")
-    return { category: DEFAULT_FEEDBACK_CATEGORY };
-  if (isFeedbackCategory(value))
-    return { category: value };
-  const raw = String(value).trim().slice(0, RAW_FEEDBACK_CATEGORY_MAX);
-  return raw ? { category: DEFAULT_FEEDBACK_CATEGORY, raw_category: raw } : { category: DEFAULT_FEEDBACK_CATEGORY };
-}
-
-// src/feedback.ts
-var FEEDBACK_FLAGS = ["category", "severity", "note", "cluster-id", "conversation-id", "run-id", "tool-name"];
-var FEEDBACK_USAGE = `Usage: moda feedback "<note>" [--category=${FEEDBACK_CATEGORIES.join("|")}] ` + `[--severity=${FEEDBACK_SEVERITIES.join("|")}] [--conversation-id=ID] [--cluster-id=ID] ` + "[--tool-name=NAME] [--run-id=ID] [--<name>-id=ID]";
-var NOTE_MAX = 4000;
-var REF_VALUE_MAX = 256;
-var REF_FLAG_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-(?:id|ids|index|token)$/;
-var REF_FLAG_WORDS = new Set(["turn", "tool", "family", "kind"]);
-function isFeedbackRefFlag(flag) {
-  return REF_FLAG_PATTERN.test(flag) || REF_FLAG_WORDS.has(flag);
-}
-function feedbackCategoryHelp(indent = 35, width = 100) {
-  const lines = [];
-  let line = "";
-  FEEDBACK_CATEGORIES.forEach((category, index) => {
-    const piece = index < FEEDBACK_CATEGORIES.length - 1 ? `${category}|` : `${category} (default other)`;
-    if (line && indent + line.length + piece.length > width) {
-      lines.push(line);
-      line = "";
-    }
-    line += piece;
-  });
-  lines.push(line);
-  return lines.join(`
-${" ".repeat(indent)}`);
-}
-function buildFeedbackRequest(positionals, flags, bareFlags) {
-  const isBare = (flag) => bareFlags ? bareFlags.includes(flag) : flags[flag] === "true";
-  const flagNote = flags.note !== undefined && !isBare("note") ? flags.note.trim() : "";
-  const note = [positionals.join(" ").trim(), flagNote].filter(Boolean).join(`
-`);
-  if (note === "")
-    throw new CliInputError("<note> is required", FEEDBACK_USAGE);
-  if (note.length > NOTE_MAX) {
-    throw new CliInputError(`<note> is ${note.length} characters; the limit is ${NOTE_MAX}.`, FEEDBACK_USAGE);
-  }
-  const severity = flags.severity ?? "low";
-  if (!FEEDBACK_SEVERITIES.includes(severity)) {
-    throw new CliInputError(`Invalid --severity '${severity}'. Valid severities: ${FEEDBACK_SEVERITIES.join(", ")}.`, FEEDBACK_USAGE);
-  }
-  const refs = {};
-  for (const [flag, value] of Object.entries(flags)) {
-    if (flag === "category" || flag === "severity" || flag === "note")
-      continue;
-    if (!FEEDBACK_FLAGS.includes(flag) && !isFeedbackRefFlag(flag))
-      continue;
-    const trimmed = value.trim();
-    if (value === "true" || trimmed === "") {
-      throw new CliInputError(`--${flag} needs a value, e.g. --${flag}=<id>.`, FEEDBACK_USAGE);
-    }
-    if (trimmed.length > REF_VALUE_MAX) {
-      throw new CliInputError(`--${flag} is ${trimmed.length} characters; the limit is ${REF_VALUE_MAX}.`, FEEDBACK_USAGE);
-    }
-    refs[flag.replace(/-/g, "_")] = trimmed;
-  }
-  const warnings = [];
-  const { category, raw_category: rawCategory } = normalizeFeedbackCategory(flags.category);
-  if (rawCategory !== undefined) {
-    refs.raw_category = rawCategory;
-    warnings.push(`Unknown category '${rawCategory}': sent as 'other' with refs.raw_category. ` + `Valid categories: ${FEEDBACK_CATEGORIES.join(", ")}.`);
-  }
-  const hint = dedicatedCommandHint(category, rawCategory);
-  if (hint)
-    warnings.push(hint);
-  return { category, severity, note, refs, warnings };
-}
-var MISROUTE_CATEGORIES = new Set(["false_positive_attribution", "misrouted_fix"]);
-var MISROUTE_WORDS = /attribut|misrout|false[\s_-]?positive|wrong[\s_-]?(?:problem|fix)/i;
-function dedicatedCommandHint(category, rawCategory) {
-  if (!MISROUTE_CATEGORIES.has(category) && !(rawCategory && MISROUTE_WORDS.test(rawCategory)))
-    return;
-  return "Feedback is read by the Moda team but does not change the problem. To act on it directly, use " + "`moda problem-feedback <problem_id> --action=flag_attribution --attribution-id=<uuid> --reason=TEXT` (a trace wrongly " + "attributed to a problem), `moda false-positive <kind> <target> --reason=TEXT` (a detection that should not " + "have fired), or `moda fix dismiss <fix_id> --reason=TEXT` (a fix aimed at the wrong problem).";
-}
 
 // src/replays.ts
 var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -713,7 +315,7 @@ var SEARCH_SURFACE_BY_COMMAND = {
   "world-state": "world_state",
   context: "context"
 };
-var SEARCH_MODES2 = ["keyword", "semantic", "hybrid"];
+var SEARCH_MODES = ["keyword", "semantic", "hybrid"];
 function termCount(query2) {
   return query2.trim().split(/\s+/).filter(Boolean).length;
 }
@@ -745,7 +347,7 @@ function buildSearchAdoptionTelemetry(input) {
   }
   if (command === "search") {
     const requested = (flags.mode ?? "").toLowerCase();
-    adoption.search_mode_requested = SEARCH_MODES2.includes(requested) ? requested : "hybrid";
+    adoption.search_mode_requested = SEARCH_MODES.includes(requested) ? requested : "hybrid";
   }
   if (command === "context") {
     adoption.used_msg_index = flags["msg-index"] !== undefined || flags["message-index"] !== undefined ? 1 : 0;
@@ -1598,12 +1200,7 @@ 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." }
-    ],
+    flags: subcommandHelpFlags(COMMAND_FLAG_SPECS.problems.subcommands.remainder),
     examples: ["moda problems remainder", "moda problems remainder --family=emotion --days-back=7"]
   }
 ];
@@ -1813,6 +1410,23 @@ var agentErrorSchema = {
     message: { type: "string" },
     cause: { type: "string" },
     suggested_commands: { type: "array", items: { type: "string" } },
+    field: { type: "string", description: "input_error: the rejected flag (e.g. --days-back) or argument (e.g. <command>)." },
+    allowed: {
+      type: "array",
+      items: { type: "string" },
+      description: "input_error: accepted values for field (enum members, valid flag names, or command names)."
+    },
+    range: {
+      type: "object",
+      additionalProperties: false,
+      description: "input_error: accepted numeric range for field.",
+      properties: { min: { type: "number" }, max: { type: "number" } }
+    },
+    did_you_mean: {
+      type: "array",
+      items: { type: "string" },
+      description: "input_error: closest valid spellings of the rejected flag or command, best first."
+    },
     input_request: agentInputRequestSchema,
     auth: agentAuthSchema,
     blocking: { type: "boolean" }
@@ -2165,7 +1779,8 @@ function buildManifest(commands) {
       auth: command.auth,
       ...command.authNote ? { auth_note: command.authNote } : {},
       mutability: command.mutability,
-      exit_codes: exitCodesForCommand(command.name)
+      exit_codes: exitCodesForCommand(command.name),
+      ...commandFlagFields(command)
     })),
     concepts: [
       { term: "tenant", meaning: "A Moda organization/workspace that owns data, prompts, skills, and API keys." },
@@ -2197,6 +1812,29 @@ function renderManifestHuman(manifest) {
   ].join(`
 `);
 }
+function commandFlagFields(command) {
+  const spec = flagSpecFor(command.name);
+  if (spec)
+    return manifestFlagFields(spec);
+  if (command.documentedFlags?.length) {
+    return { flags: command.documentedFlags.map(documentedFlag) };
+  }
+  return {
+    flags_help: command.subcommands?.length ? `moda ${command.name} <subcommand> --help` : `moda ${command.name} --help`
+  };
+}
+function documentedFlag(flag) {
+  const [name, value] = flag.name.split("=", 2);
+  const values = value?.split("|");
+  const type = value === undefined ? "boolean" : values && values.length > 1 && values.every((entry) => /^[a-z0-9_-]+$/.test(entry)) ? "enum" : "string";
+  return {
+    name,
+    type,
+    ...type === "enum" ? { enum: values } : {},
+    description: flag.description,
+    required: false
+  };
+}
 function event(name, when, terminal, deprecated = false) {
   return { name, event_version: 1, when, terminal, ...deprecated ? { deprecated: true } : {} };
 }
@@ -2212,46 +1850,46 @@ function exitCodesForCommand(command) {
 import { fileURLToPath } from "url";
 import { realpathSync } from "fs";
 async function runPromptsCommand(...args) {
-  return (await import("./prompts-2r756vtd.js")).runPromptsCommand(...args);
+  return (await import("./prompts-1tkhrxkq.js")).runPromptsCommand(...args);
 }
 async function runSkillsCommand(...args) {
-  return (await import("./skills-fed17et3.js")).runSkillsCommand(...args);
+  return (await import("./skills-br82cpt7.js")).runSkillsCommand(...args);
 }
 async function runFixCommand(...args) {
-  return (await import("./fix-q8er8egx.js")).runFixCommand(...args);
+  return (await import("./fix-9fmy6p2x.js")).runFixCommand(...args);
 }
 async function runFixesCommand(...args) {
-  return (await import("./fix-q8er8egx.js")).runFixesCommand(...args);
+  return (await import("./fix-9fmy6p2x.js")).runFixesCommand(...args);
 }
 async function runHarnessCommand(...args) {
-  return (await import("./harness-v9s0k9s7.js")).runHarnessCommand(...args);
+  return (await import("./harness-xvg6ws6x.js")).runHarnessCommand(...args);
 }
 async function runSyncCommand(...args) {
-  return (await import("./sync-r4tncne4.js")).runSyncCommand(...args);
+  return (await import("./sync-25vn78je.js")).runSyncCommand(...args);
 }
 async function runRegistryCommand(...args) {
-  return (await import("./registry-5v63ga01.js")).runRegistryCommand(...args);
+  return (await import("./registry-atqyb5fa.js")).runRegistryCommand(...args);
 }
 async function runDoctorCommand(...args) {
-  return (await import("./doctor-kg0yq1wf.js")).runDoctorCommand(...args);
+  return (await import("./doctor-mx6jf435.js")).runDoctorCommand(...args);
 }
 async function runStatusCommand(...args) {
-  return (await import("./doctor-kg0yq1wf.js")).runStatusCommand(...args);
+  return (await import("./doctor-mx6jf435.js")).runStatusCommand(...args);
 }
 async function runAuthCommand(...args) {
-  return (await import("./profile-commands-88sdwzbg.js")).runAuthCommand(...args);
+  return (await import("./profile-commands-kmmd9y86.js")).runAuthCommand(...args);
 }
 async function runConfigCommand(...args) {
-  return (await import("./profile-commands-88sdwzbg.js")).runConfigCommand(...args);
+  return (await import("./profile-commands-kmmd9y86.js")).runConfigCommand(...args);
 }
 async function runProfilesCommand(...args) {
-  return (await import("./profile-commands-88sdwzbg.js")).runProfilesCommand(...args);
+  return (await import("./profile-commands-kmmd9y86.js")).runProfilesCommand(...args);
 }
 async function runAgentCommand(...args) {
-  return (await import("./agent-cha3kg9d.js")).runAgentCommand(...args);
+  return (await import("./agent-mj622k8s.js")).runAgentCommand(...args);
 }
 async function runProductionCommand(...args) {
-  return (await import("./production-intelligence-k36jsvqx.js")).runProductionCommand(...args);
+  return (await import("./production-intelligence-dbe9dmc5.js")).runProductionCommand(...args);
 }
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -2456,403 +2094,101 @@ function buildResumeCommand(command, flags) {
 function printHelp() {
   console.log(`Usage: moda <command> [options]
 
-Commands:
-  init                             Set up Moda in your project
-  provision                        Headless tenant + API key provisioning (JSON credentials on stdout)
-  status                           Show concise local Moda setup status
-  manifest                         Describe the CLI machine protocol and commands
-  doctor                           Diagnose local Moda setup and data flow
-  auth login                       Authenticate with Moda (browser)
-  auth login --api-key             Non-interactive: validate MODA_API_KEY (or --api-key=<key>) and save it
-  auth status                      Show auth state for both credentials (exit 4 when neither is usable); --online probes the API
-  auth token                       Print the raw bearer token for $(moda auth token)
-  auth api-key                     Print the saved API key for $(moda auth api-key)
-  auth logout                      Clear cached Moda auth
-  auth whoami                      Show the authenticated Moda identity (session or API key)
-  profiles list                    List local Moda profiles
-  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
-  config show                      Show resolved Moda config
-  harness analyze                  Produce a cited structured harness report
-  harness pull                     Fetch a server-side analyze run (status, or result when done)
-  harness validate-report          Validate .moda/harness-report.json citations
-  harness approve                  Approve a validated harness report for sync
-  harness scan                     Discover local runtime agents and write .moda/harness.json
-  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 register [name]          Bundle this repo for Replay Environments and upload it (--dry-run to review)
-  harness registration list|status List registrations, or show one with what Moda still needs
-  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 next-action                Emit prioritized next commands for agents
-  agent evidence <ref>             Expand one evidence reference
+Start here (goal -> command):
+  find something in traces         moda search "<query>"   (whole traces: moda traces --search=TEXT)
+  read one trace                   moda context <conversation_id>   (whole trace: --all)
+  what is broken                   moda overview, then moda problems
+  tool errors                      moda tool-failures, then moda tool-failure-detail <tool_name>
+  user emotion and frustration     moda emotions
+  raw spans for one trace          moda audit <conversation_id|trace_id>
+  every flag of a command          moda <command> --help   (all commands and flags: moda manifest --json)
+
+Production data:
+  overview                         Harness health briefing with production signals
   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
-  sync prompts                     Sync prompt versions to Moda Cloud
-  doctor --json                    Emit structured diagnostic checks
-  status --json                    Emit concise setup state
-  manifest --json                  Emit the CLI machine protocol manifest
-  overview                         Harness health briefing with production signals
-  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
+  ask "<question>"                 Ask Moda a production question (one paid agent run)
   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 (--metadata-only: summary + counts only)
-  context <conversation_id> --all  Whole transcript in order (first 500; --from=N --max-messages=N to continue)
+  traces                           Search and filter traces (agent runs)
+  context <conversation_id>        Messages around one turn, or the whole trace with --all
   context <id>[@N] <id>[@N] ...    Batch: up to 25 traces in one call (or --ids-from=-|<file>)
   audit <conversation_id|trace_id> Raw span audit (spans, hierarchy, orphans, duplicates)
   audit <id> <id> ...              Batch audit: up to 25 ids in one call (or --ids-from=-|<file>)
+  world-state <conversation_id>    A trace's world state (slots, threads, events)
+  clusters                         Browse or search topic clusters
+  cluster-traces <node_id>         List traces in a cluster
+  users / user <user_id>           End users with health and activity (the dashboard Users page)
+  tail                             Live-tail new traces/detections as NDJSON (one line per item)
+
+Detections:
+  emotions                         Emotion detections (frustration, disapproval, confusion, ...)
   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
+  hallucinations                   Grounding detections: contradicted/verified outputs
   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 (--limit=N examples, 1-20, default 5)
+  tool-failures                    Tool failure overview
+  tool-failure-detail <tool_name>  Per-tool failure examples
+
+Problems, signals and review:
   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 <problem_id>             One Problem: dossier, or its evidence/reports/traces/feedback
+  problem-impact                   Live problem/use-case impact, trend and evidence
   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)
-  problem-linear-file <problem_id> File a Problem as a Linear issue, or link an existing one (--issue)
+  problem-reopen <problem_id>      Reopen a Problem marked fixed
+  problem-linear <problem_id>      Show the Linear issue linked to a Problem
+  problem-linear-file <problem_id> File a Problem as a Linear issue, or link an existing one
   detection-reviews <conv_id>      Problem detections on a trace with their review state
-  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)
+  detection-review <problem_id>    Mark a problem detection correct, a false positive, or clear it
+  false-positive <kind> <target>   Mark any detection as a false positive
+  false-positives [conv_id]        Current false-positive marks (workspace or one trace)
+  signals                          List and manage custom signals
   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
-  tail                             Live-tail new traces/detections as NDJSON (one line per item)
   feedback "<note>"                Flag wrong/missing data or CLI quirks to the Moda team
 
-  Legacy aliases (same behavior): conversations = traces,
-  cluster-conversations = cluster-traces, --conversations = --traces,
-  --signal=conversations = --signal=traces. <conversation_id> is the trace ID.
-
-  Prompt management:
-  prompts init                     Create .moda/prompts.yml (version 2: prompt_paths + sources)
-  prompts status                   Show local prompt changes; warns on globs that match nothing
-  prompts diff                     Only changed/new/deleted prompts since last sync
-  prompts migrate [--dry-run]      Rewrite a version 1 .moda/prompts.yml to version 2
-  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)
-
-  Replays (read-only results):
-  replays sets                     List replay sets
-  replays runs <set_id>            Run history for a set (every status)
-  replays run <set_id> <run_id>    One run: per-case and per-seed verdicts, playout count
-  replays playouts <set_id> <run_id>
-                                   Playouts per case/arm/seed (--transcript inlines messages and tool calls)
-  replays playout <set_id> <run_id> <playout_id>
-                                   One playout transcript
-
-  Skills:
-  skills gen                       Kick off tenant-wide skill generation
-  skills status [run-id]           Show a generation run's status, outcome, and recent events (default: latest run)
-  skills pull                      Pull tenant-generated skills into .claude/skills (and .cursor/rules)
-  skills install <id...>           Install bundled integration guides into .claude/skills (--list to browse)
-  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, tools, and agent wiring from one JSON manifest
-
-Options:
-  --help                           Show this help message
-  --version                        Show version number
-  --json-schemas                   Print JSON Schemas for the agent output contract
-
-Common flags (a command rejects any it does not take; see 'moda <command> --help'):
-  --days-back=N                    Whole days to look back, 1-90 (overview, problems, emotions, laziness, tool-failures, ...)
-  --time-range=RANGE               Window for traces, search, clusters instead (all|1h|3d|7d|24h|30d|90d)
-  --limit=N                        Maximum results to return (users: alias of --page-size)
-  --offset=N                       Number of results to skip (paged lists)
-  --profile=NAME                   Use a named local Moda profile
-  --json                           Emit machine-readable JSON
-  --agent                          Emit schema-versioned agent JSON
-  --stream                         With --agent, emit NDJSON agent events
-  --human                          Force human prose (overrides auto-detection)
-  --no-stream                      Disable live ask progress (buffered request)
-
-Output auto-detection (no flags needed):
-  Piped/redirected stdout, CI, or an agent env (CLAUDECODE/CURSOR/MODA_AGENT)
-  => schema-versioned agent JSON. An interactive terminal => human prose.
-  Override with the flags above or MODA_FORMAT=human|json|agent|agent-stream.
-  Exit codes: 0 ok, 1 error (errors[0].code says which, e.g. not_found), 3 degraded (local fallback),
-  4 auth required (no key or key rejected), 5 input required, 130 cancelled.
-  --dry-run                        Show the planned mutation when supported
-  --yes                            Accept explicit automation defaults
-  --tui                            Force the human analyst dashboard when supported
-  --no-tui                         Show raw analyst stream instead of dashboard
-  --no-update-check                Skip the daily new-version check (or MODA_CLI_UPDATE_CHECK=0)
-
-Traces flags:
-  --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
-  --user-id=ID                     Filter to a single user
-  --environment=ENV                Filter by environment (all|development|staging|production)
-  --since=DATE --until=DATE        Absolute UTC bounds: ISO date or datetime, inclusive; a date --until covers that whole day
-
-Search flags:
-  --mode=keyword|semantic|hybrid   Search mode (default hybrid)
-  --user-id=ID                     Filter to a single user
-  --conversation-id=ID             Search inside one trace only
-  --time-range=RANGE               Time range filter (all|1h|3d|7d|24h|30d|90d)
-  --since=DATE --until=DATE        Absolute UTC bounds: ISO date or datetime, inclusive; a date --until covers that whole day
-  --limit=N                        Maximum results to return (1-100, default 20)
-
-World-state flags:
-  --summary-only                   Return segment summaries only (omit the event stream)
-  --event-limit=N                  Max world-state events to return (1-5000, default 2000)
-  --snapshot                       Folded slots at an exact tick (what the agent believed at that turn)
-  --msg-index=N --block-index=M    Snapshot tick (defaults 0; --segment-index=K scopes to a segment)
-  --replay                         State-over-time replay; frames mode REQUIRES --message-count=N
-  --format=frames|fold-inputs      Replay format (default frames)
-  --message-count=N                Number of frames to fold (frames mode)
-
-Emotions flags:
-  --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)
-  --include-window                 Keep each detection's conversation window in agent output
-                                   (also frustrations; omitted by default, use context_command)
-
-Laziness flags:
-  --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)
-
-Hallucinations flags:
-  --kind=contradicted|verified     Narrow the detections list
-  --conversation-id=ID             Scope summary + list to one trace ID
-  --days-back=N --limit=N          Window 1-90 (default 7); page size 1-20 (default 10)
-
-Problem flags (moda problem <id>):
-  --full                           Whole dossier in agent output (default there: header, summary,
-                                   top 5 evidence anchors, report titles)
-  --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|custom_signal|conversation_reader)
-
-Problem-feedback flags:
-  --action=A                       mark_fixed|dismiss|flag_attribution|rename (required)
-  --reason=TEXT                    Required for flag_attribution; optional for dismiss
-  --attribution-id=UUID            Required for flag_attribution (ids come from problem --evidence)
-  --new-name=NAME                  Required for rename
-
-False-positive flags (moda false-positive <kind> <target>):
-  --reason=TEXT                    Why it is wrong (optional)
-  --undo                           Remove an earlier mark (every kind except problem)
-  problem <problem_id>             Dismiss the problem: hidden at once, logged for review, folded into reconcile
-  problem-detection <problem_id>   One detection on a trace; needs --conversation-id and --attribution-id; teaches the problem
-  quote <conversation_id>          A user quote; needs --family, --turn and --quote (from moda emotions); audit only
-  tool <conversation_id>           One failing tool call; needs --tool and --tool-use-id (or --msg-index); audit only
-  laziness <conversation_id>       Laziness on that trace; audit only
-  hallucination <conversation_id>  Hallucinations on that trace; audit only
-  custom-signal <signal_id>        A hit on that trace (--conversation-id); saved as does_not_fit, a labelled counterexample for the signal
-
-Problem-linear-file flags (needs Linear connected: Integrations -> Linear):
-  --issue=ENG-123|URL              Link an existing Linear issue instead of filing a new one
-  --team-id=ID                     File into this Linear team (default: the integration's default team)
-  --title=TEXT                     Issue title (default: the Problem's name)
-  --priority=N                     0 none, 1 urgent, 2 high, 3 medium, 4 low
-                                   --issue excludes --team-id/--title/--priority
-
-Detection-review flags (moda detection-review <problem_id>):
-  --conversation-id=ID             Trace the detection is on (required)
-  --attribution-id=UUID            Detection id (from problem --evidence or detection-reviews; required)
-  --verdict=V                      correct|false_positive|clear (required; clear undoes a review)
-  --note=TEXT                      Why (optional; kept with the review)
-
-Signal flags:
-  --detections                     moda signal <id>: list recent hits instead of the summary
-  --days-back=N --limit=N --offset=N
-                                   Hits window 1-90 (default 7); page size 1-20 (default 10)
-
-Signal-label flags (moda signal-label <signal_id>):
-  --conversation-id=ID             Trace to label (required)
-  --label=fits|does_not_fit        does_not_fit marks a false positive and retracts the hit (required)
-  --note=TEXT                      Why (recommended for does_not_fit)
-  --msg-index=N --msg-dedup-token=T
-                                   Anchor message (from the hit's anchor_msg_index / anchor_dedup_token)
-
-Tail flags:
-  --signal=S                       traces|emotions|all (default traces)
-  --interval=N                     Poll every N seconds (5-3600, default 15)
-  --once                           One poll, then exit (baseline page)
-  --limit=N --max-events=N         Page size per poll; stop after N stdout records
-                                   (metadata included; a slot is reserved for the
-                                   emotions coverage record, which falls back to
-                                   stderr if the bound leaves no room)
-  --full-scan                      Emotions: scan the whole window instead of the
-                                   top-scoring prefix (many more requests). /emotions
-                                   is score-ranked with no cursor, so the default
-                                   follows the highest-scoring detections and emits a
-                                   tail_coverage line stating exactly what it saw.
-
-Clusters search flags:
-  --search="query"                 Find clusters by name/meaning (task-cluster search)
-  --node-id=ID                     Deterministically resolve one cluster node (deep link)
-  --mode=fuzzy|semantic|hybrid     Cluster search mode (default hybrid)
-
-Feedback flags:
-  --category=CAT                   ${feedbackCategoryHelp()}
-                                   An unknown category is sent as other (with refs.raw_category)
-  --severity=info|low|medium|high  How bad it is (default low)
-  --note=TEXT                      The note, if not given as the positional argument
-  --conversation-id=ID             Attach the trace ID you were looking at
-  --cluster-id=ID                  Attach a cluster node id
-  --tool-name=NAME                 Attach a tool name
-  --run-id=ID                      Attach a run id
-  --<name>-id=ID                   Any other id (--problem-id, --fix-id, --attribution-id,
-                                   --trace-id, --span-id, --message-index, ...) goes into refs
-  (set MODA_CLI_TIPS=0 to hide the feedback tip line)
-
-Init flags:
-  --yes                            Accept all defaults (non-interactive)
-  --analyst=auto|claude|codex|cursor|local-scan
-                                   Choose harness analyst adapter
-  --analyst-model=MODEL            Model for the claude analyst (default: sonnet;
-                                   "default" = the claude CLI's own default;
-                                   env: MODA_HARNESS_ANALYST_MODEL)
-  --assist=none                    Disable agent fallback for prompt discovery
-  --concern=topology|tools|prompts|evals
-                                   Harness analyze: restrict the pass to one
-                                   concern (whole repo, one report scope); an
-                                   orchestrator merges the per-concern reports
-                                   (env: MODA_HARNESS_CONCERN, flag wins)
-  --allow-no-agents                Allow harness sync to push a graph with zero
-                                   runtime agents despite detected LLM usage
-  --remote                         Run harness analysis server-side (Moda-hosted,
-                                   the default): upload a safe source snapshot; no
-                                   local coding agent required
-  --local                          Run harness analysis with a LOCAL coding agent
-                                   instead of server-side (opt out of remote)
-  --tui                            Show full-screen analyst dashboard in human TTYs
-  --no-tui                         Show raw external analyst output
-  --sdk-integrate                  Run your coding agent to install the Moda SDK and instrument LLM calls
-  --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
-  --no-autosync                    Skip autosync workflow creation
-  --harness-rescan                 Create GitHub Actions workflow to re-scan the harness and sync it to Moda on push to main
-  --no-harness-rescan              Skip harness rescan workflow creation
-  --harness-rescan-paths=GLOBS     Comma-separated path globs that scope which pushes trigger the
-                                   harness rescan workflow (implies --harness-rescan)
-  --offline                        Run final validation offline (skip the online telemetry check)
+Setup:
+  init                             Set up Moda in your project
+  provision                        Headless tenant + API key provisioning (JSON credentials on stdout)
+  auth                             Log in (browser or --api-key), status, token, whoami, logout
+  status                           Show concise local Moda setup status
+  doctor                           Diagnose local Moda setup and data flow
+  profiles                         List, switch, create and check local profiles
+  config                           Show resolved Moda config
+  manifest                         The CLI machine contract: commands, flags, events, exit codes
+  agent                            Context, next actions and evidence for coding agents
 
-Provision flags (headless; requires an existing "moda auth login" session):
-  --tenant-id=ID                   Organization to provision (required with multiple
-                                   organizations; MODA_TENANT_ID env is also honored,
-                                   flag wins). Never prompts, even on a TTY.
-  --label=TEXT                     API key label (default: machine hostname)
-  --save                           Also persist the key to ~/.moda/config.json
-                                   (default: print only; headless callers own storage)
+Groups with their own subcommands (run 'moda <group> --help'):
+  harness                          Analyze, scan, validate, approve, sync and register the agent harness
+  prompts                          Code-first prompt versions: init, status, sync, promote, A/B, propose
+  replays                          Replay results: sets, runs, playouts and transcripts
+  skills                           Generate, pull, install and sync agent skills
+  sync                             Sync the harness graph and prompts to Moda Cloud
+  registry                         Push prompts, skills, tools and agent wiring from one JSON manifest
 
-Examples:
-  moda init
-  moda auth login --api-key=$MODA_API_KEY
-  moda auth whoami
-  moda provision --tenant-id=<org-id>
-  moda status
-  moda manifest --json
-  moda doctor --json
-  moda profiles list
-  moda profiles use staging
-  moda config show --profile=prod
-  moda harness analyze --experimental --summary
-  moda harness analyze --experimental --remote
-  moda harness analyze --experimental --analyst=claude --tui
-  moda harness analyze --experimental --analyst=claude --no-tui
-  moda harness analyze --experimental --analyst=claude --summary
-  moda harness analyze --experimental --analyst=local-scan --summary
-  moda harness pull --sync
-  moda harness validate-report
-  moda harness approve --yes
-  moda harness sync --from-report .moda/harness-report.json
-  moda harness delete my-harness-key --yes
-  moda --agent doctor
-  moda agent context
-  moda agent next-action
-  moda agent evidence doctor:api_key_resolves
-  moda investigate
-  moda failures
-  moda ask "what should I fix first?"
-  moda sync --dry-run
-  moda sync harness --profile=prod
-  moda harness scan --json
-  moda harness candidates --out=.moda/harness-candidates.json
-  moda harness explain --agent=agent_support
-  moda init --ci-cd
-  moda init --autosync
-  moda init --harness-rescan --harness-rescan-paths='src/agents/**'
-  moda overview --days-back=30
-  moda clusters --time-range=7d
-  moda traces --search="error" --limit=5
-  moda traces --world-state="enterprise" --outcome=positive
-  moda traces --world-state="refund,billing" --include-world-state
-  moda search "billing error" --mode=hybrid
-  moda search "refund flow" --mode=semantic --time-range=7d --limit=10
-  moda world-state <conversation_id> --summary-only
-  moda world-state <conversation_id> --snapshot --msg-index=42
-  moda world-state <conversation_id> --replay --message-count=50
-  moda clusters --search="billing disputes"
-  moda emotions --family=confusion --days-back=14
-  moda hallucinations --kind=contradicted
-  moda problems --days-back=7
-  moda problem <problem_id> --evidence --limit=10
-  moda problem-feedback <problem_id> --action=mark_fixed
-  moda problem-linear <problem_id>
-  moda problem-linear-file <problem_id> --priority=2
-  moda detection-reviews <conversation_id>
-  moda detection-review <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=false_positive --note="expected retry"
-  moda signals
-  moda signal <signal_id> --detections --days-back=30
-  moda signal-label <signal_id> --conversation-id=<id> --label=does_not_fit --note="refund was approved"
-  moda tail --signal=all --interval=30
-  moda frustrations --days-back=14 --limit=20
-  moda feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=<node_id>
-  moda context <conversation_id> --window=3
-  moda audit <conversation_id|trace_id>
-  moda audit <trace_id> --kind=trace --json
-  moda prompts status
-  moda prompts sync
-  moda prompts promote support.triage --label=prod --version=pver_abc123
-  moda prompts ab --baseline=prompts/agent.prompt.md --candidate=prompts/agent-v2.prompt.md --traces=conv_1,conv_2
-  moda prompts ab --baseline=prompts/agent.prompt.md --candidate=prompts/agent-v2.prompt.md --traces=conv_1@412   # replay from msg 412
-  moda skills pull
+Legacy aliases (same behavior): conversations = traces, cluster-conversations = cluster-traces,
+trace = audit, --conversations = --traces, --signal=conversations = --signal=traces.
+<conversation_id> is the trace ID.
 
-Run \`moda <command> --help\` for a command's subcommands, and
-\`moda <command> <subcommand> --help\` for that subcommand's flags
-(e.g. \`moda auth login --help\`).`);
+Output: piped stdout, CI or an agent env (CLAUDECODE/CURSOR/MODA_AGENT) => agent JSON; a terminal => prose.
+  --json | --agent [--stream] | --human  Force an output mode (or MODA_FORMAT=human|json|agent|agent-stream)
+  --profile=NAME --quiet --no-update-check --version --json-schemas
+Exit codes: 0 ok, 1 error (errors[0].code says which), 3 degraded, 4 auth required, 5 input required, 130 cancelled.
+A command rejects any flag it does not take; the error lists errors[0].allowed and errors[0].did_you_mean.`);
+}
+function globalFlagHelpLines(commandFlags = []) {
+  const own = new Set(commandFlags.map((key) => kebabFlag(key).slice(2)));
+  const flags = [...GLOBAL_FLAG_NAMES].filter((flag) => flag !== "help" && !own.has(flag)).map((flag) => flag === "profile" ? "--profile=NAME" : flag === "format" ? "--format=ndjson" : `--${flag}`);
+  const lines = [];
+  let line = "Global flags (every command):";
+  for (const flag of flags) {
+    if (line.length + flag.length + 1 > 100) {
+      lines.push(line);
+      line = " ";
+    }
+    line += ` ${flag}`;
+  }
+  lines.push(line);
+  return lines;
 }
 function printCommandHelp(definition) {
   const lines = [];
@@ -2866,6 +2202,17 @@ function printCommandHelp(definition) {
   for (const note of definition.helpNotes ?? []) {
     lines.push("", note);
   }
+  const flagSpec = flagSpecFor(definition.name);
+  if (flagSpec) {
+    lines.push("", ...renderFlagHelp(definition.name, flagSpec));
+  } else if (definition.documentedFlags && definition.documentedFlags.length > 0) {
+    lines.push("", "Flags:");
+    const width = Math.min(34, Math.max(...definition.documentedFlags.map((flag) => flag.name.length)));
+    for (const flag of definition.documentedFlags) {
+      lines.push(flag.name.length > width ? `  ${flag.name}
+  ${" ".repeat(width)}  ${flag.description}` : `  ${flag.name.padEnd(width)}  ${flag.description}`);
+    }
+  }
   if (definition.subcommands && definition.subcommands.length > 0) {
     lines.push("", "Subcommands:");
     const width = Math.max(...definition.subcommands.map((entry) => entry.name.length));
@@ -2880,7 +2227,7 @@ function printCommandHelp(definition) {
       lines.push(`  ${example}`);
     }
   }
-  lines.push("", "Run 'moda --help' for the full command list and the output flags every command", "takes (--json, --agent, --human, --profile). Window and paging flags (--days-back,", "--time-range, --limit, --offset) differ by command; an unsupported one is rejected.");
+  lines.push("", ...globalFlagHelpLines(flagSpec ? specFlagKeys(flagSpec) : []), flagSpec ? "Any other flag is rejected." : "Run 'moda --help' for the command list.");
   console.log(lines.join(`
 `));
 }
@@ -3263,7 +2610,7 @@ function recordSearchTelemetry(context, data) {
   const pagination = asRecord(record.pagination);
   const hasMore = pagination?.has_more;
   context.recordTelemetry({
-    search_mode_effective: SEARCH_MODES2.includes(effective) ? effective : undefined,
+    search_mode_effective: SEARCH_MODES.includes(effective) ? effective : undefined,
     result_count: results.length,
     has_more: hasMore === true ? "yes" : hasMore === false ? "no" : "na",
     ...typeof record.degrade_reason === "string" && record.degrade_reason ? { degrade_reason: record.degrade_reason.slice(0, 64) } : {}
@@ -3344,7 +2691,6 @@ var GLOBAL_FLAG_NAMES = new Set([
   "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."
@@ -3355,27 +2701,8 @@ var COMMAND_FLAG_HINTS = {
     cursor: "'moda problems' has no cursor; 'moda problems remainder --cursor=<next_cursor>' pages the unexplained signals."
   }
 };
-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 schemaKeys = Object.keys(schemaShape(schema));
   const known = new Set([
     ...schemaKeys,
     ...[...GLOBAL_FLAG_NAMES, ...options.extraFlags ?? []].map((flag) => flag.replace(/-/g, "_"))
@@ -3385,24 +2712,70 @@ function parseCommandFlags(schema, args, command, options = {}) {
     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/register, prompts sync/decide, skills sync/policy, signals <write subcommands>, problem-reopen.`, "unsupported_dry_run");
   }
   if (unknown.length > 0) {
-    const flagKeys = schemaKeys.filter((key) => key !== options.positionalKey);
-    const valid = flagKeys.map((key) => `--${key.replace(/_/g, "-")}`);
+    const flagKeys = [
+      ...schemaKeys.filter((key) => key !== options.positionalKey),
+      ...(options.extraFlags ?? []).map((flag) => flag.replace(/-/g, "_"))
+    ];
+    const valid = flagKeys.map(kebabFlag);
+    const candidates = [...valid, ...Object.keys(options.flagAliases ?? {}).map((alias) => `--${alias}`)];
+    const didYouMean = [];
     const hints = unknown.map((key) => {
       const commandHint = COMMAND_FLAG_HINTS[command]?.[key];
       if (commandHint)
         return commandHint;
       const windowAlternative = key === "days_back" ? "time_range" : key === "time_range" ? "days_back" : undefined;
-      if (windowAlternative && WINDOW_FLAG_HINTS[key] && flagKeys.includes(windowAlternative))
+      if (windowAlternative && WINDOW_FLAG_HINTS[key] && flagKeys.includes(windowAlternative)) {
+        didYouMean.push(kebabFlag(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, "-")}?` : "";
+      const close = closestMatches(kebabFlag(key), candidates, 1)[0];
+      if (close)
+        didYouMean.push(close);
+      return close ? `Did you mean ${close}?` : "";
     }).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(" "), `unknown_flag:${unknown[0].replace(/_/g, "-")}`);
+    const names = unknown.map(kebabFlag).join(", ");
+    const helpCommand = `moda ${command} --help`;
+    throw new CliInputError(`Unknown flag${unknown.length > 1 ? "s" : ""} ${names} for 'moda ${command}'.` + (didYouMean.length > 0 ? ` Did you mean ${didYouMean.join(", ")}?` : ""), [...hints, `Valid flags: ${valid.join(", ") || "(none)"}. Run '${helpCommand}'.`].join(" "), `unknown_flag:${unknown[0].replace(/_/g, "-")}`, {
+      field: kebabFlag(unknown[0]),
+      allowed: valid,
+      ...didYouMean.length > 0 ? { didYouMean: [...new Set(didYouMean)] } : {},
+      suggestedCommands: [helpCommand]
+    });
   }
-  return schema.parse(args);
+  try {
+    return schema.parse(args);
+  } catch (error) {
+    if (error instanceof z.ZodError)
+      attachFlagDetails(error, schema, command);
+    throw error;
+  }
+}
+function attachFlagDetails(error, schema, command) {
+  const key = error.issues[0]?.path[0];
+  if (typeof key !== "string")
+    return;
+  const field = describeSpecFlags({ schema }).find((flag) => flag.name === kebabFlag(key));
+  if (!field)
+    return;
+  attachInputDetails(error, {
+    field: field.name,
+    ...field.enum ? { allowed: field.enum } : {},
+    ...field.min !== undefined || field.max !== undefined ? { range: { ...field.min !== undefined ? { min: field.min } : {}, ...field.max !== undefined ? { max: field.max } : {} } } : {},
+    suggestedCommands: [`moda ${command} --help`]
+  });
+}
+function parseSpecFlags(name, args, command = name) {
+  return parseCommandFlags(COMMAND_FLAG_SPECS[name].schema, args, command, specParseOptions(COMMAND_FLAG_SPECS[name]));
+}
+function specParseOptions(spec) {
+  const positional = spec.positionals?.find((entry) => entry.key && !entry.alsoFlag);
+  return {
+    extraFlags: Object.keys(spec.extra?.shape ?? {}),
+    ...positional?.key ? { positionalKey: positional.key } : {},
+    ...spec.flagAliases ? { flagAliases: spec.flagAliases } : {}
+  };
 }
 function withStringIdFlags(args, flags) {
   for (const flag of ["user-id", "conversation-id"]) {
@@ -3590,36 +2963,12 @@ function serverWarnings(data) {
 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: FEEDBACK_FLAGS,
-  "problem-impact": ["mode", "node-id", "problem-id", "run-id", "to", "cursor", "conversation-ids", "days-back"]
-};
+function handParsedFlags(command) {
+  const spec = flagSpecFor(command);
+  if (!spec?.handParsed || ["users", "user", "problem-reopen"].includes(command))
+    return;
+  return { spec, allowed: specFlagNames(spec) };
+}
 var NO_POSITIONAL_COMMANDS = new Set([
   "overview",
   "investigate",
@@ -3645,18 +2994,18 @@ function assertHandParsedFlags(command, flags, positionals) {
   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)
+  const hand = handParsedFlags(command);
+  if (!hand)
     return;
-  const checked = command === "feedback" ? Object.keys(flags).filter((flag) => !isFeedbackRefFlag(flag)) : Object.keys(flags);
-  const shape = z2.object(Object.fromEntries(allowed.map((flag) => [flag.replace(/-/g, "_"), z2.unknown()])));
+  const checked = hand.spec.idRefFlags ? Object.keys(flags).filter((flag) => !isFeedbackRefFlag(flag)) : Object.keys(flags);
+  const shape = z.object(Object.fromEntries(hand.allowed.map((flag) => [flag.replace(/-/g, "_"), z.unknown()])));
   const args = Object.fromEntries(checked.map((flag) => [flag.replace(/-/g, "_"), true]));
   try {
-    parseCommandFlags(shape.passthrough(), args, command);
+    parseCommandFlags(shape.passthrough(), args, command, { flagAliases: hand.spec.flagAliases });
   } catch (error) {
     if (command !== "feedback" || !(error instanceof CliInputError))
       throw error;
-    throw new CliInputError(/nothing was sent/i.test(error.message) ? error.message : `${error.message} Nothing was sent.`, `${error.usage ?? ""} Id flags (--<name>-id=ID) are attached as refs; put other detail in the note. ${FEEDBACK_USAGE}`.trim(), error.reason);
+    throw new CliInputError(/nothing was sent/i.test(error.message) ? error.message : `${error.message} Nothing was sent.`, `${error.usage ?? ""} Id flags (--<name>-id=ID) are attached as refs; put other detail in the note. ${FEEDBACK_USAGE}`.trim(), error.reason, error.details);
   }
 }
 function normalizeBooleanFlags(target) {
@@ -3679,7 +3028,7 @@ function normalizeBooleanFlags(target) {
 }
 var PROFILE_MANAGING_COMMANDS = new Set(["profiles", "auth", "init", "provision", "status", "config", "manifest", "agent", "doctor"]);
 async function runProblemsRemainder(flags, context) {
-  const params = parseCommandFlags(ProblemsRemainderSchema, flagsToArgs(flags), "problems remainder");
+  const params = parseCommandFlags(ProblemsRemainderSchema, flagsToArgs(flags), "problems remainder", specParseOptions(COMMAND_FLAG_SPECS.problems.subcommands.remainder));
   const query2 = new URLSearchParams;
   if (params.days_back)
     query2.set("days_back", params.days_back.toString());
@@ -3744,7 +3093,7 @@ function parseContextRequest(positional, rawFlags) {
     warnings.push(`--msg-index had no value (${JSON.stringify(msgIndex)}), so the window is centered on the middle of the trace. Trace-level search hits have no message_index; pass one only when the hit has it.`);
   }
   const args = { ...flagsToArgs(flags), conversation_id: conversationId };
-  const params = parseCommandFlags(ContextSchema, args, "context", { positionalKey: "conversation_id" });
+  const params = parseSpecFlags("context", args);
   if (params.metadata_only === true && params.window !== undefined) {
     throw new CliInputError("--metadata-only reads no messages, so it cannot be combined with --window; drop --window.", CONTEXT_USAGE, "flag_conflict");
   }
@@ -3896,8 +3245,8 @@ async function readFullTranscript(conversationId, opts = {}) {
     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 content (prompts, tool arguments/results) use \`moda audit <conversation_id> --include-bodies\` (or \`--include-raw\` for the verbatim events).`);
+    if (legacy && returned.some(isTruncated)) {
+      out.push(`This Moda server is older and truncates message text, tool-call inputs and tool results longer than ${CONTEXT_MESSAGE_TRUNCATE_CHARS} characters. For full content (prompts, tool arguments/results) use \`moda audit <conversation_id> --include-bodies\` (or \`--include-raw\` for the verbatim events).`);
     }
     return {
       data: stripLoneSurrogates({
@@ -4180,7 +3529,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "overview": {
       const args = flagsToArgs(flags);
-      parseCommandFlags(OverviewSchema, args, command, { extraFlags: OVERVIEW_PRODUCTION_FLAGS });
+      parseSpecFlags("overview", args, command);
       return (await runProductionCommand(context)).exitCode;
     }
     case "investigate":
@@ -4190,7 +3539,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "clusters": {
       const args = flagsToArgs(flags);
-      const params = parseCommandFlags(ClustersSchema, args, command);
+      const params = parseSpecFlags("clusters", args, command);
       if (params.search !== undefined || params.node_id !== undefined) {
         const query3 = new URLSearchParams;
         if (params.search !== undefined)
@@ -4224,7 +3573,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 = parseCommandFlags(ClusterConversationsSchema, args, command, { positionalKey: "node_id" });
+      const params = parseSpecFlags("cluster-traces", args, command);
       const query2 = new URLSearchParams;
       if (params.limit)
         query2.set("limit", params.limit.toString());
@@ -4240,7 +3589,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     case "traces":
     case "conversations": {
       const args = withStringIdFlags(flagsToArgs(flags), flags);
-      const params = parseCommandFlags(ConversationsSchema, args, command);
+      const params = parseSpecFlags("traces", args, command);
       const query2 = new URLSearchParams;
       if (params.search)
         query2.set("search", params.search);
@@ -4302,7 +3651,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<query> is required", 'Usage: moda search "<query>" [--mode=keyword|semantic|hybrid] [--user-id=ID] [--conversation-id=ID] [--time-range=RANGE] [--since=DATE] [--until=DATE] [--include-tool-io] [--limit=N]');
       }
       const args = withStringIdFlags(flagsToArgs(flags, "q", positional), flags);
-      const params = parseCommandFlags(SearchSchema, args, command, { positionalKey: "q" });
+      const params = parseSpecFlags("search", args, command);
       const query2 = new URLSearchParams;
       query2.set("q", params.q);
       if (params.mode)
@@ -4358,7 +3707,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 = parseCommandFlags(WorldStateSchema, args, command, { positionalKey: "conversation_id" });
+      const params = parseSpecFlags("world-state", args, command);
       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]]");
       }
@@ -4416,7 +3765,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<conversation_id|trace_id> is required", AUDIT_USAGE);
       }
       const args = flagsToArgs(flags, "id", positional);
-      const params = parseCommandFlags(AuditSchema, args, command, { positionalKey: "id" });
+      const params = parseSpecFlags("audit", args, command);
       const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
       const page = await readAuditItem(command, params, agentMode ? {
         maxBytes: Math.max(AUDIT_MIN_PAGE_BYTES, agentMaxOutputBytes() - AUDIT_AGENT_RESERVE_BYTES),
@@ -4427,7 +3776,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "frustrations": {
       const args = withStringIdFlags(flagsToArgs(flags), flags);
-      const params = parseCommandFlags(FrustrationsSchema, args, command);
+      const params = parseSpecFlags("frustrations", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
         query2.set("days_back", params.days_back.toString());
@@ -4449,7 +3798,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "tool-failures": {
       const args = flagsToArgs(flags);
-      const params = parseCommandFlags(ToolFailuresSchema, args, command);
+      const params = parseSpecFlags("tool-failures", args, command);
       const queryString = params.days_back ? `?days_back=${params.days_back}` : "";
       const data = await callDataAPI(`/tool-failures${queryString}`);
       context.output.writeData(data);
@@ -4467,7 +3816,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         toolFlags["include-window"] = "false";
       }
       const args = flagsToArgs(toolFlags, "tool_name", positional);
-      const params = parseCommandFlags(ToolFailureDetailSchema, args, command, { positionalKey: "tool_name" });
+      const params = parseSpecFlags("tool-failure-detail", args, command);
       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.");
@@ -4547,7 +3896,7 @@ async function runCommand(command, positional, flags, positionals = 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 = parseCommandFlags(ProblemsSchema, args, command);
+      const params = parseSpecFlags("problems", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
         query2.set("days_back", params.days_back.toString());
@@ -4574,7 +3923,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         throw new CliInputError("<problem_id> is required", "Usage: moda problem <problem_id> [--full | --evidence|--reports|--traces|--feedback] [--limit=N] [--cursor=TOKEN] [--family=F] [--door=D]");
       }
       const args = flagsToArgs(flags, "id", positional);
-      const params = parseCommandFlags(ProblemSchema, args, command, { positionalKey: "id" });
+      const params = parseSpecFlags("problem", args, command);
       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) {
@@ -4748,7 +4097,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       }
       const args = flagsToArgs(flags, "id", positional);
       args.id = positional;
-      const params = parseCommandFlags(SignalSchema, args, command, { positionalKey: "id" });
+      const params = parseSpecFlags("signal", args, command);
       const id = encodeURIComponent(params.id);
       if (params.detections !== true) {
         const data2 = await callDataAPI(`/custom-signals/${id}`);
@@ -4941,7 +4290,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "emotions": {
       const args = withStringIdFlags(flagsToArgs(flags), flags);
-      const params = parseCommandFlags(EmotionsSchema, args, command);
+      const params = parseSpecFlags("emotions", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
         query2.set("days_back", params.days_back.toString());
@@ -4969,7 +4318,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (flags["conversation-id"] !== undefined) {
         args.conversation_id = flags["conversation-id"];
       }
-      const params = parseCommandFlags(LazinessSchema, args, command);
+      const params = parseSpecFlags("laziness", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
         query2.set("days_back", params.days_back.toString());
@@ -4991,7 +4340,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (flags["conversation-id"] !== undefined) {
         args.conversation_id = flags["conversation-id"];
       }
-      const params = parseCommandFlags(HallucinationsSchema, args, command);
+      const params = parseSpecFlags("hallucinations", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
         query2.set("days_back", params.days_back.toString());
@@ -5025,7 +4374,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "tail": {
       const args = flagsToArgs(flags);
-      const params = parseCommandFlags(TailSchema, args, command);
+      const params = parseSpecFlags("tail", args, command);
       await runTailCommand(params, context);
       break;
     }
@@ -5050,7 +4399,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     default:
-      throw new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
+      throw unknownCommandError(command);
   }
   return 0;
 }
@@ -5153,6 +4502,30 @@ var commandRegistry = createCommandRegistry([
     name: "init",
     description: "Set up Moda in your project",
     examples: ["moda init", "moda init --sdk-integrate", "moda init --ci-cd", "moda init --autosync", "moda init --harness-rescan"],
+    documentedFlags: [
+      { name: "--yes", description: "Accept all defaults (non-interactive)" },
+      { name: "--analyst=auto|claude|codex|cursor|local-scan", description: "Choose the harness analyst adapter" },
+      { name: "--analyst-model=MODEL", description: 'Model for the claude analyst (default sonnet; "default" = the claude CLI default; env MODA_HARNESS_ANALYST_MODEL)' },
+      { name: "--assist=none", description: "Disable agent fallback for prompt discovery" },
+      { name: "--concern=topology|tools|prompts|evals", description: "Harness analyze: restrict the pass to one concern (env MODA_HARNESS_CONCERN, flag wins)" },
+      { name: "--allow-no-agents", description: "Allow harness sync to push a graph with zero runtime agents despite detected LLM usage" },
+      { name: "--remote", description: "Run harness analysis server-side (the default): upload a safe source snapshot" },
+      { name: "--local", description: "Run harness analysis with a local coding agent instead of server-side" },
+      { name: "--tui", description: "Show the full-screen analyst dashboard in human TTYs" },
+      { name: "--no-tui", description: "Show raw external analyst output" },
+      { name: "--sdk-integrate", description: "Run your coding agent to install the Moda SDK and instrument LLM calls" },
+      { name: "--no-sdk-integrate", description: "Skip SDK integration (alias: --no-sdk-guide)" },
+      { name: "--verification-id=ID", description: "Tag the SDK integration's test trace with this id (the onb_ id from the onboarding page)" },
+      { name: "--connect-code=CODE", description: "Sign in with the one-time mcc_ code from the onboarding page instead of the browser (10 min, single use)" },
+      { name: "--ci-cd", description: "Create the GitHub Actions Moda validation workflow" },
+      { name: "--no-ci-cd", description: "Skip CI/CD workflow creation" },
+      { name: "--autosync", description: "Create a GitHub Actions workflow that syncs prompts + skills to Moda on push to main" },
+      { name: "--no-autosync", description: "Skip autosync workflow creation" },
+      { name: "--harness-rescan", description: "Create a GitHub Actions workflow that re-scans the harness and syncs it on push to main" },
+      { name: "--no-harness-rescan", description: "Skip harness rescan workflow creation" },
+      { name: "--harness-rescan-paths=GLOBS", description: "Comma-separated path globs that scope which pushes trigger the rescan (implies --harness-rescan)" },
+      { name: "--offline", description: "Run final validation offline (skip the online telemetry check)" }
+    ],
     auth: "none",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
@@ -5160,7 +4533,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runInit } = await import("./index-7zqa7t5c.js");
+      const { runInit } = await import("./index-ewqbpnwz.js");
       if (context.outputMode === "agent-stream") {
         context.output.writeEvent({
           event: "started",
@@ -5194,6 +4567,12 @@ var commandRegistry = createCommandRegistry([
       "moda provision --tenant-id=<org-id> --label=ci-runner --save",
       "KEY=$(moda provision --tenant-id <org-id> | jq -r .apiKey)"
     ],
+    helpNotes: ['Headless: requires an existing "moda auth login" session and never prompts, even on a TTY.'],
+    documentedFlags: [
+      { name: "--tenant-id=ID", description: "Organization to provision (required with multiple organizations; MODA_TENANT_ID is also honored, flag wins)" },
+      { name: "--label=TEXT", description: "API key label (default: machine hostname)" },
+      { name: "--save", description: "Also persist the key to ~/.moda/config.json (default: print only; headless callers own storage)" }
+    ],
     auth: "none",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
@@ -5201,7 +4580,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runProvision } = await import("./provision-n3r7yway.js");
+      const { runProvision } = await import("./provision-wzttap58.js");
       return runProvision(context, {
         resumeCommand: buildResumeCommand("provision", context.rawFlags)
       });
@@ -5800,6 +5179,9 @@ var commandRegistry = createCommandRegistry([
   legacyCommand({
     name: "false-positive",
     description: "Flag a detection as a false positive with a reason: problem, problem-detection, quote, tool, laziness, hallucination, or custom-signal",
+    helpNotes: [
+      "Kinds: problem <problem_id> dismisses the Problem (hidden at once, logged for review); problem-detection <problem_id> marks one detection on a trace (needs --conversation-id and --attribution-id); quote <conversation_id> needs --family, --turn and --quote (from moda emotions); tool <conversation_id> needs --tool and --tool-use-id or --msg-index; laziness and hallucination <conversation_id> mark that trace; custom-signal <signal_id> needs --conversation-id and is saved as a does_not_fit label. quote, tool, laziness and hallucination marks are audit-only."
+    ],
     examples: [
       'moda false-positive problem <problem_id> --reason="two unrelated tools"',
       'moda false-positive problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --reason="refund was approved"',
@@ -5917,6 +5299,9 @@ var commandRegistry = createCommandRegistry([
       'moda feedback "search finds nothing for a trace I can open" --category=missing_data --conversation-id=<id>',
       'moda feedback "trace is about refunds, not this problem" --category=false_positive_attribution --problem-id=<id> --conversation-id=<id>'
     ],
+    helpNotes: [
+      "Any other id flag (--problem-id, --fix-id, --attribution-id, --trace-id, --span-id, --message-index, ...) is attached as a ref. Set MODA_CLI_TIPS=0 to hide the feedback tip line."
+    ],
     ...dataApiDefaults,
     mutability: "write"
   }),
@@ -6116,7 +5501,7 @@ function classifyCliError(error) {
     return "auth_error";
   if (error instanceof ApiError && error.statusCode === 403)
     return "access_error";
-  if (error instanceof z2.ZodError || error instanceof CliInputError || error instanceof CliInputRequiredError) {
+  if (error instanceof z.ZodError || error instanceof CliInputError || error instanceof CliInputRequiredError) {
     return "validation_error";
   }
   if (error instanceof ApiError || isApiLikeError(error)) {
@@ -6128,7 +5513,7 @@ function classifyCliError(error) {
   return "unknown_error";
 }
 function cliValidationReason(error) {
-  if (error instanceof z2.ZodError) {
+  if (error instanceof z.ZodError) {
     const issue = error.issues[0];
     if (!issue)
       return "zod";
@@ -6155,7 +5540,7 @@ function printCliError(error) {
     if (error.guidance)
       safeWriteStderr(`${error.guidance}
 `);
-  } else if (error instanceof z2.ZodError) {
+  } else if (error instanceof z.ZodError) {
     const issues = error.errors.map((e) => {
       const field = e.path.length ? e.path.join(".") : "input";
       return `  ${field}: ${e.message}`;
@@ -6199,6 +5584,21 @@ function printFeedbackTip(commandName, context) {
 ${colorOk ? `\x1B[2m${text}\x1B[0m` : text}
 `);
 }
+function unknownCommandError(command) {
+  const visible = commandRegistry.all().filter((entry) => !entry.hidden);
+  const names = visible.flatMap((entry) => [entry.name, ...entry.aliases ?? []]);
+  const matches = closestMatches(command, names);
+  const suggestion = matches.length > 0 ? ` Did you mean ${matches.map((name) => `'${name}'`).join(" or ")}?` : "";
+  return new CliInputError(`Unknown command '${command}'.${suggestion}`, [
+    ...matches.map((name) => `\`moda ${name} --help\``),
+    "Run `moda --help` for the command list."
+  ].join(" "), "unknown_command", {
+    field: "<command>",
+    allowed: visible.map((entry) => entry.name),
+    ...matches.length > 0 ? { didYouMean: matches } : {},
+    suggestedCommands: [...matches.map((name) => `moda ${name} --help`), "moda --help"]
+  });
+}
 function printAgentCliError(command, error, mode = "agent") {
   const output = createCliOutput({
     command: command || "unknown",
@@ -6296,9 +5696,8 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
     return 1;
   };
   const definition = commandRegistry.find(command);
-  if (!definition) {
-    return failEarly(new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.'));
-  }
+  if (!definition)
+    return failEarly(unknownCommandError(command));
   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'.`, "short_flag"), definition);
   }
@@ -6485,6 +5884,7 @@ if (isMain) {
   });
 }
 export {
+  unknownCommandError,
   telemetrySubcommandNames,
   telemetryCommandName,
   stripLoneSurrogates,
@@ -6499,6 +5899,7 @@ export {
   parseArgs,
   normalizeBooleanFlags,
   initFlagsForContext,
+  globalFlagHelpLines,
   flagsToArgs,
   dispatchParsedCommand,
   detectCallerAgent,