@moda-ai/cli 1.55.23 → 1.55.25

package/dist/cli.js

@@ -5,22 +5,23 @@ import {
 import {
   createCommandContext,
   parseBooleanFlagValue
-} from "./cli-2cggp8ww.js";
+} from "./cli-qvg26twp.js";
 import {
   AuditSchema,
   COMMAND_FLAG_SPECS,
   DETECTION_VERDICTS,
   DetectionReviewSchema,
+  EMOTION_FAMILIES,
   FALSE_POSITIVE_KINDS,
   FEEDBACK_USAGE,
   FalsePositiveSchema,
+  LAZINESS_FAMILIES,
   PROBLEM_FEEDBACK_ACTIONS,
   ProblemFeedbackSchema,
   ProblemImpactSchema,
   ProblemLinearFileSchema,
   ProblemsRemainderSchema,
   SIGNALS_MANAGEMENT_SUBCOMMANDS,
-  SIGNAL_LABELS,
   SignalLabelSchema,
   StepScoresSchema,
   UUID_RE,
@@ -43,12 +44,12 @@ import {
   specFlagNames,
   subcommandHelpFlags,
   unknownSignalsSubcommandError
-} from "./cli-cv3jt1ms.js";
+} from "./cli-dn91fb56.js";
 import {
   ApiError,
   callControlAPI,
   callDataAPI
-} from "./cli-wkmdw40s.js";
+} from "./cli-9btx12wp.js";
 import {
   AGENT_ERROR_CODES,
   BATCH_CONCURRENCY,
@@ -65,6 +66,7 @@ import {
   EXIT_ERROR,
   EXIT_INPUT_REQUIRED,
   EXIT_OK,
+  LEGACY_NAMES,
   MODA_BASE_URL,
   VERSION,
   agentEnvelopeFits,
@@ -75,6 +77,7 @@ import {
   asRecord,
   asString,
   attachInputDetails,
+  canonicalCommandText,
   collectBatchTargets,
   compactProblemDossier,
   contextTarget,
@@ -85,6 +88,7 @@ import {
   frustrationsFromEmotions,
   getApiRequestCount,
   getModaDir,
+  inputDetailsOf,
   isApiLikeError,
   isNetworkLikeError,
   isPlatformApiKey,
@@ -106,7 +110,7 @@ import {
   withFrustrationAnchors,
   withToolFailureAnchors,
   withoutDetectionWindows
-} from "./cli-t3a6eknn.js";
+} from "./cli-dve50x7p.js";
 import {
   __require
 } from "./cli-0v6na3yp.js";
@@ -542,7 +546,10 @@ function buildCliUsageRequest(input) {
       node_version: process.versions.node,
       platform: process.platform,
       arch: process.arch,
-      flags_json: { names: sanitizedFlagNames(input.flags) },
+      flags_json: {
+        names: sanitizedFlagNames(input.flags),
+        ...((alias) => alias ? { legacy_alias: alias } : {})(sanitizeReasonCode(input.legacyAlias?.replace(/ /g, ":"), 64))
+      },
       ...serializeAdoption(input.adoption)
     })
   };
@@ -654,6 +661,540 @@ function printUpdateNotice(options = {}) {
   if (notice)
     console.error(notice);
 }
+// src/command-tree.ts
+var CANONICAL_LEAVES = [
+  {
+    noun: "traces",
+    verb: "list",
+    path: "traces list",
+    args: "",
+    handler: "traces",
+    summary: "List and filter traces (agent runs); --search ranks whole traces",
+    examples: ['moda traces list --search="error" --limit=5', 'moda traces list --world-state="enterprise" --outcome=positive']
+  },
+  {
+    noun: "traces",
+    verb: "search",
+    path: "traces search",
+    args: '"<query>"',
+    handler: "search",
+    summary: "Search trace messages (keyword, semantic, or hybrid)",
+    examples: ['moda traces search "billing error"', 'moda traces search "refund flow" --mode=semantic --time-range=7d --limit=10']
+  },
+  {
+    noun: "traces",
+    verb: "get",
+    path: "traces get",
+    args: "<conversation_id>[@N]...",
+    handler: "context",
+    summary: "Messages around a turn, or the whole trace (--all); up to 25 ids per call",
+    examples: [
+      "moda traces get <conversation_id> --msg-index=40 --window=3",
+      "moda traces get <conversation_id> --all",
+      "moda traces get <id>@12 <id2>@3 --window=2   # batch: up to 25 targets (or --ids-from=-|<file>)"
+    ]
+  },
+  {
+    noun: "traces",
+    verb: "state",
+    path: "traces state",
+    args: "<conversation_id>",
+    handler: "world-state",
+    summary: "A trace's world state (slots, threads, events)",
+    examples: ["moda traces state <conversation_id> --summary-only", "moda traces state <conversation_id> --snapshot --msg-index=12"]
+  },
+  {
+    noun: "traces",
+    verb: "spans",
+    path: "traces spans",
+    args: "<conversation_id|trace_id>...",
+    handler: "audit",
+    summary: "Raw span audit (hierarchy, orphans, duplicates); up to 25 ids per call",
+    examples: ["moda traces spans <conversation_id>", "moda traces spans <trace_id> --kind=trace --include-bodies"]
+  },
+  {
+    noun: "problems",
+    verb: "list",
+    path: "problems list",
+    args: "",
+    handler: "problems",
+    summary: "Rank cross-signal Problems by root cause (what to fix first)",
+    examples: ["moda problems list", "moda problems list --days-back=7 --limit=10"]
+  },
+  {
+    noun: "problems",
+    verb: "get",
+    path: "problems get",
+    args: "<problem_id>",
+    handler: "problem",
+    summary: "One Problem: dossier, or its --evidence/--reports/--traces/--feedback pages",
+    examples: ["moda problems get <problem_id>", "moda problems get <problem_id> --evidence --limit=10", "moda problems get <problem_id> --traces --family=tool_failure"]
+  },
+  {
+    noun: "problems",
+    verb: "unexplained",
+    path: "problems unexplained",
+    args: "",
+    handler: "problems",
+    handlerSubcommand: "remainder",
+    summary: "Signals no Problem explains yet, grouped by family",
+    examples: ["moda problems unexplained --family=emotion --days-back=7"]
+  },
+  {
+    noun: "problems",
+    verb: "impact",
+    path: "problems impact",
+    args: "[<problem_id>]",
+    handler: "problem-impact",
+    summary: "Impact, denominators, recurrence and evidence for a Problem or use case",
+    examples: ["moda problems impact <problem_id> --mode=metrics", "moda problems impact --node-id=node_0 --mode=trend --days-back=30", "moda problems impact --mode=catalog"]
+  },
+  {
+    noun: "problems",
+    verb: "feedback",
+    path: "problems feedback",
+    args: "<problem_id>",
+    handler: "problem-feedback",
+    summary: "Mark a Problem fixed, dismiss it, rename it, or flag a bad attribution",
+    examples: ["moda problems feedback <problem_id> --action=mark_fixed", 'moda problems feedback <problem_id> --action=rename --new-name="Better title"']
+  },
+  {
+    noun: "problems",
+    verb: "reopen",
+    path: "problems reopen",
+    args: "<problem_id>",
+    handler: "problem-reopen",
+    summary: "Reopen a Problem marked fixed",
+    examples: ['moda problems reopen <problem_id> --reason="still happening" --dry-run']
+  },
+  {
+    noun: "problems",
+    verb: "linear",
+    path: "problems linear",
+    args: "<problem_id>",
+    handler: "problem-linear",
+    summary: "Show the Linear issue linked to a Problem",
+    examples: ["moda problems linear <problem_id>"]
+  },
+  {
+    noun: "problems",
+    verb: "link",
+    path: "problems link",
+    args: "<problem_id>",
+    handler: "problem-linear-file",
+    summary: "File a Problem as a Linear issue, or link an existing one with --issue",
+    examples: ["moda problems link <problem_id> --issue=ENG-123", "moda problems link <problem_id> --team-id=<team_id> --priority=2"]
+  },
+  {
+    noun: "detections",
+    verb: "list",
+    path: "detections list",
+    args: "--family=<family>",
+    routes: ["emotions", "frustrations", "laziness", "hallucinations", "tool-failures", "signal", "trace-signals"],
+    summary: "Detections of one family: emotion[:<f>] frustration laziness[:<f>] hallucination tool_failure custom_signal",
+    examples: [
+      "moda detections list --family=frustration --limit=10",
+      "moda detections list --family=emotion:confusion --days-back=14",
+      "moda detections list --family=hallucination --kind=contradicted",
+      "moda detections list --family=custom_signal --signal-id=<signal_id>"
+    ]
+  },
+  {
+    noun: "detections",
+    verb: "tools",
+    path: "detections tools",
+    args: "[<tool_name>]",
+    routes: ["tool-failures", "tool-failure-detail"],
+    summary: "Tool failure leaderboard, or one tool's failure examples",
+    examples: ["moda detections tools --days-back=14", "moda detections tools <tool_name> --limit=3"]
+  },
+  {
+    noun: "review",
+    verb: "",
+    path: "review",
+    args: "<kind> <target>",
+    routes: ["false-positive", "detection-review", "signal-label"],
+    summary: "Review a detection: --verdict=false_positive (default), correct, or clear",
+    examples: [
+      'moda review tool <conversation_id> --tool=send_invoice --tool-use-id=<id> --reason="retried upstream"',
+      "moda review problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=correct",
+      "moda review custom-signal <signal_id> --conversation-id=<id> --verdict=clear"
+    ]
+  },
+  {
+    noun: "reviews",
+    verb: "list",
+    path: "reviews list",
+    args: "[<conversation_id>]",
+    routes: ["false-positives", "detection-reviews"],
+    summary: "False-positive marks and detection reviews (workspace, or one trace)",
+    examples: ["moda reviews list --kind=tool --all", "moda reviews list <conversation_id>", "moda reviews list <conversation_id> --kind=problem-detection"]
+  },
+  {
+    noun: "skills",
+    verb: "push",
+    path: "skills push",
+    args: "",
+    handler: "skills",
+    handlerSubcommand: "sync",
+    summary: "Upload locally authored .claude/skills/**/SKILL.md files to Moda (download: skills pull)",
+    examples: ["moda skills push --dry-run", "moda skills push"]
+  }
+];
+var CANONICAL_NOUNS = ["traces", "problems", "detections", "review", "reviews", "skills"];
+var NOUN_SUMMARIES = {
+  traces: "Traces (agent runs): list, search, read, world state, raw spans",
+  problems: "Problems ranked by root cause, their evidence, impact and lifecycle",
+  detections: "Detections of every family, and the tool failure leaderboard",
+  review: "Mark a detection a false positive, correct, or clear the mark",
+  reviews: "List false-positive marks and detection reviews",
+  skills: "Generate, pull, push, and install agent skills"
+};
+function leafFor(noun, verb) {
+  if (noun === "review")
+    return CANONICAL_LEAVES.find((leaf) => leaf.noun === "review");
+  return CANONICAL_LEAVES.find((leaf) => leaf.noun === noun && leaf.verb === verb);
+}
+function leavesOf(noun) {
+  return CANONICAL_LEAVES.filter((leaf) => leaf.noun === noun);
+}
+function usePath(entry) {
+  return entry.use.replace(/^moda /, "").split(" ").filter((word) => /^[a-z][a-z-]*$/.test(word)).slice(0, entry.canonical.command === "review" ? 1 : 2).join(" ");
+}
+function flagOn(value) {
+  return value !== undefined && value !== "false";
+}
+function legacyNameFor(typed, subcommand, flags) {
+  const byName = (name) => LEGACY_NAMES.find((entry) => entry.legacy === name);
+  if (subcommand !== undefined) {
+    const sub = byName(`${typed} ${subcommand}`);
+    if (sub)
+      return sub;
+  }
+  if (typed === "signal")
+    return flagOn(flags.detections) ? byName("signal --detections") : undefined;
+  if (typed === "problems" || typed === "skills" || typed === "sync")
+    return;
+  return byName(typed);
+}
+function visibleLegacyNames() {
+  return LEGACY_NAMES.filter((entry) => !entry.silent);
+}
+function legacyNamesForPath(path) {
+  return visibleLegacyNames().filter((entry) => usePath(entry) === path).map((entry) => entry.legacy);
+}
+function deprecationMessage(entry) {
+  return `'moda ${entry.legacy}' is a legacy name; use '${entry.use}' (the old name still works).${entry.note ? ` ${entry.note}` : ""}`;
+}
+function canonicalTelemetryForDefault(name, subcommand) {
+  if ((name === "traces" || name === "problems") && subcommand === undefined)
+    return { command: name, subcommand: "list" };
+  return;
+}
+var without = (flags, ...keys) => {
+  const copy = { ...flags };
+  for (const key of keys) {
+    delete copy[key];
+    delete copy[key.replace(/-/g, "_")];
+  }
+  return copy;
+};
+function specFor(command) {
+  const spec = flagSpecFor(command);
+  if (!spec)
+    throw new Error(`No flag spec for routed command '${command}'`);
+  return spec;
+}
+function flagNamesOf(command, ...drop) {
+  return specFlagNames(specFor(command)).filter((name) => !drop.includes(name));
+}
+function inputError(message, usage, reason, details = {}) {
+  return new CliInputError(message, usage, reason, details);
+}
+var DETECTION_FAMILIES = ["emotion", "frustration", "laziness", "hallucination", "tool_failure", "custom_signal"];
+var DETECTION_FAMILY_HANDLERS = {
+  emotion: "emotions",
+  frustration: "frustrations",
+  laziness: "laziness",
+  hallucination: "hallucinations",
+  tool_failure: "tool-failures",
+  custom_signal: "signal"
+};
+var DETECTION_SUBFAMILIES = {
+  emotion: EMOTION_FAMILIES,
+  laziness: LAZINESS_FAMILIES
+};
+var REVIEW_VERDICTS = ["false_positive", "correct", "clear"];
+function detectionFamilyValues() {
+  return DETECTION_FAMILIES.flatMap((family) => [family, ...(DETECTION_SUBFAMILIES[family] ?? []).map((sub) => `${family}:${sub}`)]);
+}
+var DETECTIONS_LIST_USAGE = "Usage: moda detections list --family=emotion[:<family>]|frustration|laziness[:<family>]|hallucination|tool_failure|custom_signal [flags]. See 'moda detections list --help'.";
+function routeDetectionsList(leaf, rest, flags) {
+  const raw = flags.family;
+  if (raw === undefined || raw === "true" || raw === "") {
+    throw inputError("--family is required for 'moda detections list'.", DETECTIONS_LIST_USAGE, "missing_value:family", {
+      field: "--family",
+      allowed: [...DETECTION_FAMILIES],
+      suggestedCommands: ["moda detections list --help"]
+    });
+  }
+  const [base, sub, ...extra] = raw.split(":");
+  if (!DETECTION_FAMILIES.includes(base) || extra.length > 0) {
+    const didYouMean = closestMatches(raw, detectionFamilyValues(), 2);
+    throw inputError(`Unknown detection family '${raw}'.${didYouMean.length ? ` Did you mean ${didYouMean.map((value) => `--family=${value}`).join(" or ")}?` : ""}`, DETECTIONS_LIST_USAGE, "bad_enum:family", { field: "--family", allowed: [...DETECTION_FAMILIES], ...didYouMean.length ? { didYouMean } : {}, suggestedCommands: ["moda detections list --help"] });
+  }
+  const family = base;
+  const subfamilies = DETECTION_SUBFAMILIES[family];
+  if (sub !== undefined && (!subfamilies || !subfamilies.includes(sub))) {
+    const allowed = subfamilies ? subfamilies.map((value) => `${family}:${value}`) : [family];
+    throw inputError(subfamilies ? `Unknown ${family} family '${sub}'.` : `--family=${family} takes no sub-family.`, DETECTIONS_LIST_USAGE, "bad_enum:family", { field: "--family", allowed, didYouMean: closestMatches(raw, allowed, 2), suggestedCommands: [`moda detections list --family=${family} --help`] });
+  }
+  if (rest.length > 0) {
+    throw inputError(`'moda detections list' takes no arguments, but got '${rest.join(" ")}'.`, DETECTIONS_LIST_USAGE, "unexpected_positional");
+  }
+  const label = `detections list --family=${family}`;
+  if (family === "custom_signal") {
+    const signalId = flags["signal-id"];
+    const traceId = flags["conversation-id"];
+    if (signalId === undefined === (traceId === undefined)) {
+      throw inputError(signalId === undefined ? "--family=custom_signal needs --signal-id=<signal_id> (one signal's hits) or --conversation-id=<conversation_id> (every signal hit on one trace)." : "Pass --signal-id or --conversation-id with --family=custom_signal, not both.", DETECTIONS_LIST_USAGE, signalId === undefined ? "missing_value:signal-id" : "flag_conflict", { field: "--signal-id", suggestedCommands: ["moda detections list --family=custom_signal --help", "moda signals"] });
+    }
+    if (signalId !== undefined) {
+      return {
+        leaf,
+        handler: "signal",
+        positionals: [signalId],
+        label,
+        telemetrySubcommand: "list",
+        rewriteFlags: (input) => ({ ...without(input, "family", "signal-id"), detections: "true" }),
+        allowedFlags: ["family", "signal-id", ...flagNamesOf("signal", "detections")],
+        renames: { signal: label }
+      };
+    }
+    return {
+      leaf,
+      handler: "trace-signals",
+      positionals: [traceId],
+      label,
+      telemetrySubcommand: "list",
+      rewriteFlags: (input) => without(input, "family", "conversation-id"),
+      allowedFlags: ["family", "conversation-id"],
+      renames: { "trace-signals": label }
+    };
+  }
+  const handler = DETECTION_FAMILY_HANDLERS[family];
+  return {
+    leaf,
+    handler,
+    positionals: [],
+    label,
+    telemetrySubcommand: "list",
+    rewriteFlags: (input) => ({ ...without(input, "family"), ...sub !== undefined ? { family: sub } : {} }),
+    allowedFlags: ["family", ...flagNamesOf(handler, "family")],
+    ...specFor(handler).flagAliases ? { flagAliases: specFor(handler).flagAliases } : {},
+    renames: { [handler]: label }
+  };
+}
+var REVIEW_USAGE = `Usage: moda review <${FALSE_POSITIVE_KINDS.join("|")}> <target> [--verdict=${REVIEW_VERDICTS.join("|")}] [--reason=TEXT]. See 'moda review --help'.`;
+var REVIEW_FLAG_ALIASES = { note: "reason" };
+function routeReview(leaf, positionals, flags) {
+  const [kind, target, ...extra] = positionals;
+  if (!kind || !FALSE_POSITIVE_KINDS.includes(kind)) {
+    const didYouMean = kind ? closestMatches(kind, FALSE_POSITIVE_KINDS, 2) : [];
+    throw inputError(kind ? `Unknown review kind '${kind}'.${didYouMean.length ? ` Did you mean ${didYouMean.map((value) => `'${value}'`).join(" or ")}?` : ""}` : "<kind> and <target> are required", REVIEW_USAGE, kind ? "bad_enum:kind" : "missing_positional", { field: "<kind>", allowed: [...FALSE_POSITIVE_KINDS], ...didYouMean.length ? { didYouMean } : {}, suggestedCommands: ["moda review --help"] });
+  }
+  if (!target)
+    throw inputError("<kind> and <target> are required", REVIEW_USAGE, "missing_positional", { field: "<target>", suggestedCommands: ["moda review --help"] });
+  if (extra.length > 0)
+    throw inputError(`'moda review' takes <kind> <target>, but also got '${extra.join(" ")}'.`, REVIEW_USAGE, "unexpected_positional");
+  const verdict = flags.verdict ?? "false_positive";
+  if (!REVIEW_VERDICTS.includes(verdict)) {
+    throw inputError(`--verdict must be one of ${REVIEW_VERDICTS.join(", ")}.`, REVIEW_USAGE, "bad_enum:verdict", {
+      field: "--verdict",
+      allowed: [...REVIEW_VERDICTS],
+      didYouMean: closestMatches(verdict, REVIEW_VERDICTS, 1),
+      suggestedCommands: ["moda review --help"]
+    });
+  }
+  const label = `review ${kind}`;
+  const reasonToNote = (input) => {
+    const reason = input.reason ?? input.note;
+    const rest = without(input, "reason", "note", "verdict");
+    return reason !== undefined ? { ...rest, note: reason } : rest;
+  };
+  if (kind === "problem-detection") {
+    return {
+      leaf,
+      handler: "detection-review",
+      positionals: [target],
+      label,
+      telemetrySubcommand: kind,
+      rewriteFlags: (input) => ({ ...reasonToNote(input), verdict }),
+      allowedFlags: ["verdict", ...flagNamesOf("detection-review", "verdict")],
+      flagAliases: { reason: "note" },
+      renames: { "detection-review": label, "false-positive problem-detection": label }
+    };
+  }
+  if (verdict === "correct") {
+    if (kind !== "custom-signal") {
+      throw inputError(`--verdict=correct applies to problem-detection and custom-signal reviews only, not '${kind}'.`, REVIEW_USAGE, "unsupported_verdict", { field: "--verdict", allowed: ["false_positive", "clear"], suggestedCommands: ["moda review --help"] });
+    }
+    return {
+      leaf,
+      handler: "signal-label",
+      positionals: [target],
+      label,
+      telemetrySubcommand: kind,
+      rewriteFlags: (input) => ({ ...reasonToNote(input), label: "fits" }),
+      allowedFlags: ["verdict", ...flagNamesOf("signal-label", "label")],
+      flagAliases: { reason: "note" },
+      renames: { "signal-label": label }
+    };
+  }
+  return {
+    leaf,
+    handler: "false-positive",
+    positionals: [kind, target],
+    label,
+    telemetrySubcommand: kind,
+    rewriteFlags: (input) => {
+      const note = input.note;
+      const rest = without(input, "verdict", "note");
+      return {
+        ...note !== undefined && rest.reason === undefined ? { ...rest, reason: note } : rest,
+        ...verdict === "clear" ? { undo: "true" } : {}
+      };
+    },
+    allowedFlags: ["verdict", ...flagNamesOf("false-positive", "undo")],
+    flagAliases: REVIEW_FLAG_ALIASES,
+    renames: { "false-positive": "review" }
+  };
+}
+var REVIEWS_LIST_USAGE = "Usage: moda reviews list [<conversation_id>] [--kind=quote|tool|laziness|hallucination|custom-signal|problem-detection] [--all] [--limit=N]. See 'moda reviews list --help'.";
+function routeReviewsList(leaf, rest, flags) {
+  if (rest.length > 1)
+    throw inputError(`'moda reviews list' takes at most one <conversation_id>, but got '${rest.join(" ")}'.`, REVIEWS_LIST_USAGE, "unexpected_positional");
+  if (flags.kind === "problem-detection") {
+    if (!rest[0]) {
+      throw inputError("--kind=problem-detection needs a <conversation_id>: detection reviews are read per trace. Nothing was sent.", REVIEWS_LIST_USAGE, "missing_positional", { field: "<conversation_id>", suggestedCommands: ["moda reviews list --help"] });
+    }
+    return {
+      leaf,
+      handler: "detection-reviews",
+      positionals: [rest[0]],
+      label: "reviews list --kind=problem-detection",
+      telemetrySubcommand: "list",
+      rewriteFlags: (input) => without(input, "kind"),
+      allowedFlags: ["kind", ...flagNamesOf("detection-reviews")],
+      renames: { "detection-reviews": "reviews list --kind=problem-detection" }
+    };
+  }
+  return {
+    leaf,
+    handler: "false-positives",
+    positionals: rest,
+    label: "reviews list",
+    telemetrySubcommand: "list",
+    rewriteFlags: (input) => input,
+    allowedFlags: flagNamesOf("false-positives"),
+    renames: { "false-positives": "reviews list", "detection-reviews": "reviews list --kind=problem-detection" }
+  };
+}
+function routeDetectionsTools(leaf, rest) {
+  if (rest.length > 1) {
+    throw inputError(`'moda detections tools' takes at most one <tool_name>, but got '${rest.join(" ")}'.`, "Usage: moda detections tools [<tool_name>] [flags]", "unexpected_positional");
+  }
+  const handler = rest[0] === undefined ? "tool-failures" : "tool-failure-detail";
+  return {
+    leaf,
+    handler,
+    positionals: rest,
+    label: "detections tools",
+    telemetrySubcommand: "tools",
+    rewriteFlags: (input) => input,
+    renames: { [handler]: "detections tools" }
+  };
+}
+function routeProblemsImpact(leaf, rest, flags) {
+  if (rest.length > 1) {
+    throw inputError(`'moda problems impact' takes at most one <problem_id>, but got '${rest.join(" ")}'.`, "Usage: moda problems impact [<problem_id>] [flags]", "unexpected_positional");
+  }
+  if (rest[0] !== undefined && flags["problem-id"] !== undefined && flags["problem-id"] !== rest[0]) {
+    throw inputError("Pass the problem id once: as <problem_id> or --problem-id, not both.", "Usage: moda problems impact [<problem_id>] [flags]", "flag_conflict", { field: "--problem-id" });
+  }
+  const problemId = rest[0];
+  return {
+    leaf,
+    handler: "problem-impact",
+    positionals: [],
+    label: "problems impact",
+    telemetrySubcommand: "impact",
+    rewriteFlags: (input) => problemId !== undefined ? { ...input, "problem-id": problemId } : input,
+    renames: { "problem-impact": "problems impact" }
+  };
+}
+function routeCanonical(command, positionals, flags) {
+  if (command === "review")
+    return routeReview(leafFor("review", undefined), positionals, flags);
+  if (!CANONICAL_NOUNS.includes(command))
+    return;
+  const [verb, ...rest] = positionals;
+  const leaf = verb !== undefined ? leafFor(command, verb) : undefined;
+  if (!leaf) {
+    if (command === "traces" || command === "problems" || command === "skills")
+      return;
+    const verbs = leavesOf(command).map((entry) => entry.verb);
+    const didYouMean = verb ? closestMatches(verb, verbs, 2) : [];
+    throw inputError(verb ? `Unknown ${command} subcommand '${verb}'.${didYouMean.length ? ` Did you mean ${didYouMean.map((name) => `'${name}'`).join(" or ")}?` : ""}` : `'moda ${command}' needs a subcommand: ${verbs.join(", ")}.`, `Usage: ${leavesOf(command).map((entry) => `moda ${entry.path}${entry.args ? ` ${entry.args}` : ""}`).join(" | ")}`, verb ? "unknown_subcommand" : "missing_subcommand", { field: "<subcommand>", allowed: verbs, ...didYouMean.length ? { didYouMean } : {}, suggestedCommands: [`moda ${command} --help`] });
+  }
+  switch (leaf.path) {
+    case "detections list":
+      return routeDetectionsList(leaf, rest, flags);
+    case "detections tools":
+      return routeDetectionsTools(leaf, rest);
+    case "reviews list":
+      return routeReviewsList(leaf, rest, flags);
+    case "problems impact":
+      return routeProblemsImpact(leaf, rest, flags);
+    default: {
+      const handler = leaf.handler;
+      const renameKey = leaf.handlerSubcommand ? `${handler} ${leaf.handlerSubcommand}` : handler;
+      return {
+        leaf,
+        handler,
+        positionals: leaf.handlerSubcommand ? [leaf.handlerSubcommand, ...rest] : rest,
+        rewriteFlags: (input) => input,
+        label: leaf.path,
+        telemetrySubcommand: leaf.verb,
+        renames: { [renameKey]: leaf.path }
+      };
+    }
+  }
+}
+function parseCommandFor(command, verb) {
+  const leaf = verb !== undefined && command !== "review" ? leafFor(command, verb) : undefined;
+  return leaf?.handler ?? command;
+}
+function renameCommands(text, renames) {
+  const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  let result = text;
+  for (const [from, to] of Object.entries(renames).sort((left, right) => right[0].length - left[0].length)) {
+    const verbs = leavesOf(from).flatMap((leaf) => leaf.verb ? [escape(leaf.verb)] : []);
+    const canonical = verbs.length > 0 ? `(?! (?:${verbs.join("|")})(?![\\w-]))` : "";
+    result = result.replace(new RegExp(`moda ${escape(from)}(?![\\w-])${canonical}`, "g"), `moda ${to}`);
+  }
+  return result;
+}
+function leafHandlers(leaf) {
+  return leaf.routes ? [...leaf.routes] : [leaf.handler];
+}
+function leafFlagSpec(leaf) {
+  if (!leaf.handler)
+    return;
+  if (leaf.path === "problems unexplained")
+    return COMMAND_FLAG_SPECS.problems.subcommands.remainder;
+  return flagSpecFor(leaf.handler);
+}
 
 // src/command-registry.ts
 function createCommandRegistry(definitions) {
@@ -887,11 +1428,11 @@ var SKILLS_SUBCOMMAND_HELP = [
     examples: ["moda skills pull", "moda skills pull --status=all"]
   },
   {
-    name: "sync",
-    description: "Upload locally authored .claude/skills/**/SKILL.md files to Moda",
-    usage: "moda skills sync [--dry-run]",
+    name: "push",
+    description: "Upload locally authored .claude/skills/**/SKILL.md files to Moda (legacy name: sync; download is pull)",
+    usage: "moda skills push [--dry-run]",
     flags: [{ name: "--dry-run", description: "Server-side preview; nothing is saved." }],
-    examples: ["moda skills sync --dry-run", "moda skills sync"]
+    examples: ["moda skills push --dry-run", "moda skills push"]
   },
   {
     name: "list",
@@ -1193,15 +1734,6 @@ var HARNESS_SUBCOMMAND_HELP = [
     examples: ["moda harness diff my-harness-key --from=hver_a --to=hver_b"]
   }
 ];
-var PROBLEMS_SUBCOMMAND_HELP = [
-  {
-    name: "remainder",
-    description: "Signals no Problem explains yet, grouped by family (read-only)",
-    usage: "moda problems remainder [--family=<family>] [--days-back=N] [--limit=N] [--cursor=<token>]",
-    flags: subcommandHelpFlags(COMMAND_FLAG_SPECS.problems.subcommands.remainder),
-    examples: ["moda problems remainder", "moda problems remainder --family=emotion --days-back=7"]
-  }
-];
 var FIX_TIMEOUT = { name: "--timeout=<ms>", description: "How long to wait, in milliseconds (max 86400000)." };
 var FIX_POLL = { name: "--poll-interval=<ms>", description: "Polling interval while waiting, in milliseconds." };
 var FIXES_SUBCOMMAND_HELP = [
@@ -1767,27 +2299,42 @@ function buildManifest(commands) {
       "moda.intelligence.v1",
       "production_ask.v0.1"
     ],
-    commands: commands.filter((command) => !command.hidden).map((command) => ({
-      name: command.name,
-      aliases: command.aliases ?? [],
-      summary: command.description,
-      output_modes: command.outputModes,
-      streaming: command.outputModes.includes("agent-stream") || command.outputModes.includes("agent"),
-      examples: command.examples,
-      auth: command.auth,
-      ...command.authNote ? { auth_note: command.authNote } : {},
-      mutability: command.mutability,
-      exit_codes: exitCodesForCommand(command.name),
-      ...commandFlagFields(command)
-    })),
+    commands: commands.filter((command) => !command.hidden).map((command) => {
+      const legacy = legacyEntry(command.name);
+      if (legacy) {
+        return {
+          name: command.name,
+          aliases: command.aliases ?? [],
+          summary: command.description,
+          deprecated_by: legacy
+        };
+      }
+      const deprecatedForms = deprecatedFormsOf(command.name);
+      return {
+        name: command.name,
+        aliases: command.aliases ?? [],
+        summary: command.description,
+        output_modes: command.outputModes,
+        streaming: command.outputModes.includes("agent-stream") || command.outputModes.includes("agent"),
+        examples: command.examples,
+        auth: command.auth,
+        ...command.authNote ? { auth_note: command.authNote } : {},
+        mutability: command.mutability,
+        exit_codes: exitCodesForCommand(command.name),
+        ...commandFlagFields(command, commands),
+        ...treeFields(command.name, commands),
+        ...deprecatedForms.length > 0 ? { deprecated_forms: deprecatedForms } : {}
+      };
+    }),
     concepts: [
       { term: "tenant", meaning: "A Moda organization/workspace that owns data, prompts, skills, and API keys." },
       { term: "profile", meaning: "A named local CLI configuration under ~/.moda that selects environment, tenant, and secret references." },
       { term: "harness", meaning: "Moda’s local graph of runtime agents, prompts, tools, identities, and deployments in a codebase." },
       { term: "harness report", meaning: "A cited analyst artifact under .moda/ that justifies the harness graph before sync." },
       { term: "remote analyze run", meaning: "A Moda-hosted harness analysis tracked in .moda/harness-remote-run.json; fetch its status or result with `moda harness pull`." },
-      { term: "trace", meaning: "The full record of one agent run stored in Moda analytics: every message, tool call, thinking block, and step that shares one `conversation_id` (the trace ID). Formerly called a conversation; `moda conversations` remains a legacy alias of `moda traces`." },
-      { term: "span", meaning: "Raw OTLP span evidence inside one trace (or one OTLP trace_id), exposed by `moda audit`." },
+      { term: "trace", meaning: "The full record of one agent run stored in Moda analytics: every message, tool call, thinking block, and step that shares one `conversation_id` (the trace ID). Formerly called a conversation; `moda conversations` remains a silent alias of `moda traces list`." },
+      { term: "span", meaning: "Raw OTLP span evidence inside one trace (or one OTLP trace_id), exposed by `moda traces spans`." },
+      { term: "legacy name", meaning: "A command name from before the `moda <noun> <verb>` tree (e.g. `moda context`, now `moda traces get`). It still runs; its entry names the canonical form in `deprecated_by`, and agent output carries a warning and `meta.deprecated`." },
       { term: "ingest key", meaning: "A `moda_sk_` API key for SDKs, CI, and Data API calls. Treat it as a secret." },
       { term: "CLI session token", meaning: "A local browser-auth session token used by CLI auth/bootstrap flows, not by application SDKs." },
       { term: "prompt", meaning: "A code-first prompt file tracked by `.moda/prompts.yml` and synced to Moda." },
@@ -1810,7 +2357,11 @@ function renderManifestHuman(manifest) {
   ].join(`
 `);
 }
-function commandFlagFields(command) {
+function commandFlagFields(command, commands) {
+  if (command.name === "review")
+    return leafManifestFields(leafFor("review", undefined), commands);
+  if (command.name === "detections" || command.name === "reviews")
+    return {};
   const spec = flagSpecFor(command.name);
   if (spec)
     return manifestFlagFields(spec);
@@ -1843,51 +2394,174 @@ function exitCodesForCommand(command) {
     return [0, 1, 4, 5, 130];
   return [0, 1, 4, 130];
 }
+function legacyEntry(name) {
+  return visibleLegacyNames().find((entry) => entry.legacy === name)?.use;
+}
+function deprecatedFormsOf(name) {
+  return visibleLegacyNames().filter((entry) => entry.legacy.startsWith(`${name} `)).map((entry) => ({ form: `moda ${entry.legacy}`, use: entry.use }));
+}
+function treeFields(name, commands) {
+  if (!CANONICAL_NOUNS.includes(name) || name === "review")
+    return {};
+  return { subcommands: leavesOf(name).map((leaf) => leafManifestFields(leaf, commands)) };
+}
+function leafMutability(leaf, commands) {
+  const handlers = leafHandlers(leaf);
+  return commands.some((command) => handlers.includes(command.name) && command.mutability === "write") ? "write" : "read";
+}
+function documentedFlags(flags) {
+  return flags.map(documentedFlag);
+}
+function withoutFlags(flags, ...names) {
+  return flags.filter((flag) => !names.includes(flag.name));
+}
+function handlerFlags(command, ...drop) {
+  const spec = flagSpecFor(command);
+  return spec ? withoutFlags(describeSpecFlags(spec), ...drop) : [];
+}
+function leafManifestFields(leaf, commands) {
+  const base = {
+    ...leaf.verb ? { name: leaf.verb } : {},
+    path: `moda ${leaf.path}`,
+    summary: leaf.summary,
+    usage: `moda ${leaf.path}${leaf.args ? ` ${leaf.args}` : ""} [flags]`,
+    aliases: legacyNamesForPath(leaf.path),
+    runs: leafHandlers(leaf),
+    mutability: leafMutability(leaf, commands),
+    examples: leaf.examples
+  };
+  const spec = leafFlagSpec(leaf);
+  if (spec) {
+    const fields = manifestFlagFields({ ...spec, subcommands: undefined });
+    if (leaf.path === "problems impact") {
+      fields.positionals = [{ name: "problem_id", required: false, description: "Same as --problem-id", flag: "--problem-id" }];
+    }
+    return { ...base, ...fields };
+  }
+  switch (leaf.path) {
+    case "skills push":
+      return { ...base, flags: documentedFlags([{ name: "--dry-run", description: "Server-side preview; nothing is saved." }]) };
+    case "detections list":
+      return {
+        ...base,
+        flags: [{
+          name: "--family",
+          type: "enum",
+          enum: [...DETECTION_FAMILIES],
+          required: true,
+          description: "Detection family; emotion and laziness take a sub-family after a colon (emotion:confusion, laziness:stub_body)"
+        }],
+        routes: DETECTION_FAMILIES.flatMap((family) => family === "custom_signal" ? [
+          {
+            when: "--family=custom_signal --signal-id=<signal_id>",
+            runs: ["signal"],
+            flags: [
+              { name: "--signal-id", type: "string", required: true, description: "One signal's recent hits (runs signal <id> --detections)" },
+              ...handlerFlags("signal", "--detections")
+            ]
+          },
+          {
+            when: "--family=custom_signal --conversation-id=<conversation_id>",
+            runs: ["trace-signals"],
+            flags: [{ name: "--conversation-id", type: "string", required: true, description: "Every custom signal hit on one trace (runs trace-signals)" }]
+          }
+        ] : [{
+          when: `--family=${family}`,
+          runs: [DETECTION_FAMILY_HANDLERS[family]],
+          ...DETECTION_SUBFAMILIES[family] ? { subfamilies: DETECTION_SUBFAMILIES[family] } : {},
+          flags: handlerFlags(DETECTION_FAMILY_HANDLERS[family], "--family")
+        }])
+      };
+    case "detections tools":
+      return {
+        ...base,
+        positionals: [{ name: "tool_name", required: false, description: "One tool: its failure examples (without it: the leaderboard)" }],
+        routes: [
+          { when: "no <tool_name>", runs: ["tool-failures"], flags: handlerFlags("tool-failures") },
+          { when: "<tool_name>", runs: ["tool-failure-detail"], flags: handlerFlags("tool-failure-detail") }
+        ]
+      };
+    case "review": {
+      const verdict = { name: "--verdict", type: "enum", enum: [...REVIEW_VERDICTS], default: "false_positive", required: false, description: "What the review says" };
+      const alias = (name, of) => ({ name, type: "string", required: false, description: `Alias of ${of}`, alias_of: of });
+      const falsePositiveFlags = [verdict, ...handlerFlags("false-positive", "--undo"), alias("--note", "--reason")];
+      return {
+        ...base,
+        positionals: [
+          { name: "kind", required: true, enum: ["problem", "problem-detection", "quote", "tool", "laziness", "hallucination", "custom-signal"] },
+          { name: "target", required: true, description: "Problem id (problem, problem-detection), signal id (custom-signal), else the trace ID" }
+        ],
+        flags: falsePositiveFlags,
+        routes: [
+          { when: "problem-detection (any verdict)", runs: ["detection-review"], flags: [verdict, ...handlerFlags("detection-review", "--verdict"), alias("--reason", "--note")] },
+          { when: "custom-signal --verdict=correct", runs: ["signal-label"], flags: [verdict, ...handlerFlags("signal-label", "--label"), alias("--reason", "--note")] },
+          { when: "any other kind or verdict (clear = --undo; problem cannot be cleared; correct is rejected)", runs: ["false-positive"], flags: falsePositiveFlags }
+        ]
+      };
+    }
+    case "reviews list":
+      return {
+        ...base,
+        positionals: [{ name: "conversation_id", required: false, description: "List the marks on one trace instead of the whole workspace" }],
+        flags: [
+          ...handlerFlags("false-positives", "--conversation-id", "--kind"),
+          { name: "--kind", type: "enum", enum: ["quote", "tool", "laziness", "hallucination", "custom-signal", "problem-detection"], required: false, description: "Only this kind of mark (problem-detection needs <conversation_id>)" },
+          { name: "--attribution-id", type: "string", required: false, description: "With --kind=problem-detection: only this detection (UUID)" }
+        ],
+        routes: [
+          { when: "--kind=problem-detection <conversation_id>", runs: ["detection-reviews"] },
+          { when: "otherwise", runs: ["false-positives"] }
+        ]
+      };
+    default:
+      return base;
+  }
+}
 
 // src/cli.ts
 import { fileURLToPath } from "url";
 import { realpathSync } from "fs";
 async function runPromptsCommand(...args) {
-  return (await import("./prompts-p66y7wep.js")).runPromptsCommand(...args);
+  return (await import("./prompts-3h5jcjrw.js")).runPromptsCommand(...args);
 }
 async function runSkillsCommand(...args) {
-  return (await import("./skills-c17gg69y.js")).runSkillsCommand(...args);
+  return (await import("./skills-vq3njc8a.js")).runSkillsCommand(...args);
 }
 async function runFixCommand(...args) {
-  return (await import("./fix-fr48gr0w.js")).runFixCommand(...args);
+  return (await import("./fix-0qdtdz5h.js")).runFixCommand(...args);
 }
 async function runFixesCommand(...args) {
-  return (await import("./fix-fr48gr0w.js")).runFixesCommand(...args);
+  return (await import("./fix-0qdtdz5h.js")).runFixesCommand(...args);
 }
 async function runHarnessCommand(...args) {
-  return (await import("./harness-m63b6s0k.js")).runHarnessCommand(...args);
+  return (await import("./harness-vzy7n7ea.js")).runHarnessCommand(...args);
 }
 async function runSyncCommand(...args) {
-  return (await import("./sync-bne90xvj.js")).runSyncCommand(...args);
+  return (await import("./sync-hq9dpqpr.js")).runSyncCommand(...args);
 }
 async function runRegistryCommand(...args) {
-  return (await import("./registry-n7dsdxmg.js")).runRegistryCommand(...args);
+  return (await import("./registry-s2vdsfw8.js")).runRegistryCommand(...args);
 }
 async function runDoctorCommand(...args) {
-  return (await import("./doctor-snb87jvy.js")).runDoctorCommand(...args);
+  return (await import("./doctor-q21mr5ya.js")).runDoctorCommand(...args);
 }
 async function runStatusCommand(...args) {
-  return (await import("./doctor-snb87jvy.js")).runStatusCommand(...args);
+  return (await import("./doctor-q21mr5ya.js")).runStatusCommand(...args);
 }
 async function runAuthCommand(...args) {
-  return (await import("./profile-commands-548ts402.js")).runAuthCommand(...args);
+  return (await import("./profile-commands-6e2dgv72.js")).runAuthCommand(...args);
 }
 async function runConfigCommand(...args) {
-  return (await import("./profile-commands-548ts402.js")).runConfigCommand(...args);
+  return (await import("./profile-commands-6e2dgv72.js")).runConfigCommand(...args);
 }
 async function runProfilesCommand(...args) {
-  return (await import("./profile-commands-548ts402.js")).runProfilesCommand(...args);
+  return (await import("./profile-commands-6e2dgv72.js")).runProfilesCommand(...args);
 }
 async function runAgentCommand(...args) {
-  return (await import("./agent-f8a1kejk.js")).runAgentCommand(...args);
+  return (await import("./agent-t7dxmpdq.js")).runAgentCommand(...args);
 }
 async function runProductionCommand(...args) {
-  return (await import("./production-intelligence-fwjh572m.js")).runProductionCommand(...args);
+  return (await import("./production-intelligence-c8e0xw3n.js")).runProductionCommand(...args);
 }
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -1904,7 +2578,7 @@ function parseArgs(argv) {
     if (!endOfOptions && arg === "--" && command !== "") {
       endOfOptions = true;
     } else if (!endOfOptions && arg.startsWith("--")) {
-      i = parseFlag(args, i, flags, command === "", bareFlags, command);
+      i = parseFlag(args, i, flags, command === "", bareFlags, parseCommandFor(command, positional));
     } else if (!endOfOptions && command !== "" && /^-[A-Za-z]/.test(arg)) {
       shortFlags.push(arg);
     } else if (command === "") {
@@ -2090,58 +2764,35 @@ function buildResumeCommand(command, flags) {
   ];
 }
 function printHelp() {
-  console.log(`Usage: moda <command> [options]
+  console.log(`Usage: moda <noun> <verb> [args] [flags]
 
 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)
+  find something in traces         moda traces search "<query>"   (whole traces: moda traces list --search=TEXT)
+  read one trace                   moda traces get <conversation_id>   (whole trace: --all)
+  what is broken                   moda overview, then moda problems list
+  tool errors                      moda detections tools, then moda detections tools <tool_name>
+  user emotion and frustration     moda detections list --family=emotion   (or --family=frustration)
+  raw spans for one trace          moda traces spans <conversation_id|trace_id>
+  a detection is wrong             moda review <kind> <target> --reason=TEXT
+  every flag of a command          moda <noun> <verb> --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 question (one paid agent run)
-  search "<query>"                 Search trace messages (keyword/semantic/hybrid)
-  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)
-  hallucinations                   Grounding detections: contradicted/verified outputs
-  laziness                         Laziness detections per trace (repeated calls, premature handoffs, ...)
-  tool-failures                    Tool failure overview
-  tool-failure-detail <tool_name>  Per-tool failure examples
+Traces, Problems, detections and review (moda <noun> --help lists the verbs):
+${canonicalTreeHelpLines().join(`
+`)}
 
-Problems, signals and review:
-  problems                         Rank cross-signal Problems by root cause (what to fix first)
-  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
-  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 it
-  false-positive <kind> <target>   Mark any detection as a false positive
-  false-positives [conv_id]        Current false-positive marks (workspace or one trace)
+Custom signals and feedback:
   signals                          List and manage custom signals
-  signal <signal_id>               One custom signal, or --detections for its recent hits
-  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
+  signal <signal_id>               One custom signal (its hits: moda detections list --family=custom_signal)
   feedback "<note>"                Flag wrong/missing data or CLI quirks to the Moda team
 
 Setup:
@@ -2159,13 +2810,13 @@ 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
+  skills                           Generate skills; pull (download), push (upload), install
   sync                             Sync the harness graph and prompts to Moda Cloud
   registry                         Push prompts, skills, tools and agent wiring from one JSON manifest
 
-Legacy aliases (same behavior): conversations = traces, cluster-conversations = cluster-traces,
-trace = audit, --conversations = --traces, --signal=conversations = --signal=traces.
-<conversation_id> is the trace ID.
+${legacyNamesHelpLine()}
+Silent aliases: conversations = traces list, cluster-conversations = cluster-traces, --conversations = --traces,
+--signal=conversations = --signal=traces. <conversation_id> is the trace ID.
 
 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)
@@ -2250,6 +2901,187 @@ function printSubcommandHelp(parent, entry) {
   console.log(lines.join(`
 `));
 }
+function helpTable(rows) {
+  if (rows.length === 0)
+    return ["  (none besides the global flags below)"];
+  const width = Math.min(34, Math.max(...rows.map((row) => row.name.length)));
+  return rows.map((row) => row.name.length > width ? `  ${row.name}
+  ${" ".repeat(width)}  ${row.description}` : `  ${row.name.padEnd(width)}  ${row.description}`);
+}
+function routedFlagRows(command, drop = []) {
+  const spec = flagSpecFor(command);
+  if (!spec)
+    return [];
+  return subcommandHelpFlags(spec).filter((row) => !drop.some((name) => row.name === name || row.name.startsWith(`${name}=`)));
+}
+function detectionsListHelp(focus) {
+  const lines = ["Families (--family=):"];
+  lines.push(...helpTable(DETECTION_FAMILIES.map((family) => {
+    const subfamilies = DETECTION_SUBFAMILIES[family];
+    const runs = family === "custom_signal" ? "signal --detections / trace-signals" : DETECTION_FAMILY_HANDLERS[family];
+    return {
+      name: subfamilies ? `${family}[:<family>]` : family,
+      description: `runs ${runs}${subfamilies ? `; <family>: ${subfamilies.join(", ")}` : ""}`
+    };
+  })));
+  const base = focus?.split(":")[0];
+  for (const family of DETECTION_FAMILIES.filter((entry) => !base || entry === base)) {
+    lines.push("", `Flags with --family=${family}:`);
+    if (family === "custom_signal") {
+      lines.push(...helpTable([
+        { name: "--signal-id=ID", description: "One signal's recent hits (paged; runs signal <id> --detections)" },
+        ...routedFlagRows("signal", ["--detections"]),
+        { name: "--conversation-id=ID", description: "Instead of --signal-id: every signal hit on one trace (runs trace-signals)" }
+      ]));
+    } else {
+      lines.push(...helpTable(routedFlagRows(DETECTION_FAMILY_HANDLERS[family], ["--family"])));
+    }
+  }
+  return lines;
+}
+function detectionsToolsHelp() {
+  return [
+    "Without <tool_name> (the leaderboard, runs tool-failures):",
+    ...helpTable(routedFlagRows("tool-failures")),
+    "",
+    "With <tool_name> (failure examples, runs tool-failure-detail):",
+    ...helpTable(routedFlagRows("tool-failure-detail", ["--tool-name"]))
+  ];
+}
+function reviewHelp() {
+  return [
+    "Kinds and targets: problem <problem_id>, problem-detection <problem_id>, quote|tool|laziness|hallucination <conversation_id>,",
+    "custom-signal <signal_id>.",
+    "",
+    "Verdicts (--verdict, default false_positive) and what each runs:",
+    "  problem            false_positive: dismiss the Problem (false-positive problem); clear and correct are rejected",
+    "  problem-detection  every verdict: the detection review the dashboard thumbs write (detection-review)",
+    "  custom-signal      false_positive: does_not_fit label; clear: removes the label (false-positive custom-signal);",
+    "                     correct: fits label (signal-label)",
+    "  quote, tool, laziness, hallucination",
+    "                     false_positive or clear (false-positive <kind> [--undo]); correct is rejected",
+    "",
+    "Flags:",
+    ...helpTable([
+      { name: `--verdict=${REVIEW_VERDICTS.join("|")}`, description: "What the review says [default false_positive]" },
+      ...routedFlagRows("false-positive", ["--undo"]),
+      { name: "--note=TEXT", description: "Alias of --reason" }
+    ])
+  ];
+}
+function reviewsListHelp() {
+  return [
+    "Flags:",
+    ...helpTable([
+      ...routedFlagRows("false-positives", ["--kind"]),
+      { name: "--kind=<value>", description: "Only this kind of mark: quote, tool, laziness, hallucination, custom-signal, or problem-detection (needs <conversation_id>; runs detection-reviews)" },
+      { name: "--attribution-id=ID", description: "With --kind=problem-detection: only this detection (UUID)" }
+    ])
+  ];
+}
+function renderLeafHelp(leaf, options = {}) {
+  const lines = [`moda ${leaf.path} — ${leaf.summary}`];
+  if (options.legacy) {
+    lines.push(`'moda ${options.legacy.legacy}' is a legacy name for '${options.legacy.use}'; it still works.${options.legacy.note ? ` ${options.legacy.note}` : ""}`);
+  }
+  const aliases = legacyNamesForPath(leaf.path);
+  if (aliases.length > 0)
+    lines.push(`Legacy names (still work): ${aliases.join(", ")}`);
+  const handlers = leaf.routes ?? [leaf.handler];
+  if (handlers.some((name) => commandRegistry.find(name)?.mutability === "write"))
+    lines.push("This command can mutate state.");
+  const handlerDefinition = leaf.handler ? commandRegistry.find(leaf.handler) : undefined;
+  if (leaf.handler && !leaf.handlerSubcommand) {
+    for (const note of handlerDefinition?.helpNotes ?? [])
+      lines.push("", renameCommands(note, { [leaf.handler]: leaf.path }));
+  }
+  lines.push("", `Usage: moda ${leaf.path}${leaf.args ? ` ${leaf.args}` : ""} [flags]`);
+  const spec = leafFlagSpec(leaf);
+  let ownFlags = [];
+  if (spec) {
+    const body = renderFlagHelp(leaf.path, { ...spec, subcommands: undefined }).slice(1);
+    lines.push(...body.map((line) => renameCommands(line, { [leaf.handler]: leaf.path })));
+    ownFlags = specFlagKeys(spec);
+  } else if (leaf.path === "skills push") {
+    const entry = SKILLS_SUBCOMMAND_HELP.find((subcommand) => subcommand.name === "push");
+    lines.push("", "Flags:", ...helpTable(entry?.flags ?? []));
+  } else if (leaf.path === "detections list") {
+    lines.push("", ...detectionsListHelp(options.focus));
+  } else if (leaf.path === "detections tools") {
+    lines.push("", ...detectionsToolsHelp());
+  } else if (leaf.path === "review") {
+    lines.push("", ...reviewHelp());
+  } else if (leaf.path === "reviews list") {
+    lines.push("", ...reviewsListHelp());
+  }
+  if (leaf.examples.length > 0)
+    lines.push("", "Examples:", ...leaf.examples.map((example) => `  ${example}`));
+  lines.push("", ...globalFlagHelpLines(ownFlags), "Any other flag is rejected.");
+  return lines.join(`
+`);
+}
+function printTreeHelp(parsed) {
+  const { command, positionals, flags } = parsed;
+  if (command === "review") {
+    console.log(renderLeafHelp(leafFor("review", undefined)));
+    return true;
+  }
+  if (CANONICAL_NOUNS.includes(command) && positionals[0] !== undefined) {
+    const leaf2 = leafFor(command, positionals[0]);
+    if (leaf2) {
+      console.log(renderLeafHelp(leaf2, { focus: flags.family }));
+      return true;
+    }
+  }
+  const legacy = legacyNameFor(command, positionals[0], flags);
+  if (!legacy || legacy.silent)
+    return false;
+  const [noun, verb] = usePath(legacy).split(" ");
+  const leaf = leafFor(noun, verb);
+  if (!leaf) {
+    const target = commandRegistry.find(noun);
+    const entry = target?.subcommands?.find((subcommand) => subcommand.name === verb);
+    if (!target || !entry)
+      return false;
+    console.log(`'moda ${legacy.legacy}' is a legacy name for '${legacy.use}'; it still works. ${legacy.note ?? ""}`.trim());
+    printSubcommandHelp(target, entry);
+    return true;
+  }
+  const focus = /--family=([a-z_]+)/.exec(legacy.use)?.[1];
+  console.log(renderLeafHelp(leaf, { legacy, ...focus ? { focus } : {} }));
+  return true;
+}
+function treeSubcommandHelp(noun) {
+  return leavesOf(noun).map((leaf) => ({
+    name: leaf.verb,
+    description: leaf.summary,
+    usage: `moda ${leaf.path}${leaf.args ? ` ${leaf.args}` : ""} [flags]`,
+    examples: [...leaf.examples]
+  }));
+}
+function canonicalTreeHelpLines() {
+  const rows = CANONICAL_LEAVES.filter((leaf) => leaf.noun !== "skills").map((leaf) => {
+    const left = `${leaf.path}${leaf.args ? ` ${leaf.args}` : ""}`;
+    return left.length > 32 ? `  ${left}
+  ${" ".repeat(33)}${leaf.summary}` : `  ${left.padEnd(32)} ${leaf.summary}`;
+  });
+  return rows;
+}
+function legacyNamesHelpLine() {
+  const words = ["Legacy names (still work; `moda <name> --help` shows the new form):", ...visibleLegacyNames().map((entry, index, all) => `${entry.legacy}${index < all.length - 1 ? "," : "."}`)];
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (line && line.length + word.length + 1 > 110) {
+      lines.push(line);
+      line = " ";
+    }
+    line += line ? ` ${word}` : word;
+  }
+  lines.push(line);
+  return lines.join(`
+`);
+}
 async function attachWindows(rows, windowSize) {
   return Promise.all(rows.map(async (row) => {
     const anchor = asRecord(row.anchor);
@@ -2309,7 +3141,7 @@ function withoutRepeatedFrustrationWindow(data) {
   return { ...data, frustrations };
 }
 var NOT_FOUND_HINTS = {
-  trace: 'Find trace ids with: moda search "<text>" or moda traces --search=<text>',
+  trace: 'Find trace ids with: moda traces search "<text>" or moda traces --search=<text>',
   cluster: "List cluster node ids with: moda clusters",
   problem: "List problem ids with: moda problems"
 };
@@ -2323,7 +3155,7 @@ function noWorldStateWarnings(conversationId, isMissing) {
     return;
   return {
     warnings: [
-      `No world state for trace "${conversationId}": the trace may not exist in this tenant, or its world state has not been generated yet. Check the trace exists with: moda context ${shellArg(contextTarget(conversationId))} --metadata-only`
+      `No world state for trace "${conversationId}": the trace may not exist in this tenant, or its world state has not been generated yet. Check the trace exists with: moda traces get ${shellArg(contextTarget(conversationId))} --metadata-only`
     ]
   };
 }
@@ -2363,11 +3195,11 @@ function auditOutput(command, params, data) {
     return { data: auditRecord ? { ...auditRecord, truncated: false, has_more: false, next_cursor: null } : data, options: {} };
   }
   const limit = params.limit ?? AUDIT_DEFAULT_LIMIT;
-  const perTrace = "audit one OTLP trace at a time with `moda audit <trace_id> --kind=trace` (ids in summary.trace_ids)";
+  const perTrace = "audit one OTLP trace at a time with `moda traces spans <trace_id> --kind=trace` (ids in summary.trace_ids)";
   const warnings = [];
   const nextCommands = [];
   const auditFlags = (extra) => [
-    `moda ${command} ${shellArg(params.id)}`,
+    `${canonicalCommandText(`moda ${command}`)} ${shellArg(params.id)}`,
     params.kind && params.kind !== "auto" ? `--kind=${params.kind}` : "",
     params.include_raw === true ? "--include-raw" : "",
     params.include_bodies === true ? "--include-bodies" : "",
@@ -2554,7 +3386,7 @@ async function runTailCommand(params, context) {
         total,
         coverage_pct: coveragePct,
         pages_scanned: pages,
-        detail: `Scanned ${scanned}${total !== null ? ` of ${total}` : ""} detection(s) in the last day${coveragePct !== null ? ` (${coveragePct}%)` : ""}. /emotions is ranked by score with no time ordering or cursor, so this follows the highest-scoring detections and lower-scoring ones may not appear. Use --full-scan for completeness (many more requests, up to the API offset ceiling of 10000), or \`moda emotions --offset=N\` to page manually.`
+        detail: `Scanned ${scanned}${total !== null ? ` of ${total}` : ""} detection(s) in the last day${coveragePct !== null ? ` (${coveragePct}%)` : ""}. /emotions is ranked by score with no time ordering or cursor, so this follows the highest-scoring detections and lower-scoring ones may not appear. Use --full-scan for completeness (many more requests, up to the API offset ceiling of 10000), or \`moda detections list --family=emotion --offset=N\` to page manually.`
       });
     } else if (total !== null) {
       emitMeta({
@@ -2695,8 +3527,8 @@ var WINDOW_FLAG_HINTS = {
 };
 var COMMAND_FLAG_HINTS = {
   problems: {
-    family: "'moda problems' ranks every family together. To filter by family use 'moda problems remainder --family=<family>' (signals no Problem explains yet) or 'moda problem <problem_id> --traces --family=<family>' (one Problem's traces).",
-    cursor: "'moda problems' has no cursor; 'moda problems remainder --cursor=<next_cursor>' pages the unexplained signals."
+    family: "'moda problems' ranks every family together. To filter by family use 'moda problems unexplained --family=<family>' (signals no Problem explains yet) or 'moda problems get <problem_id> --traces --family=<family>' (one Problem's traces).",
+    cursor: "'moda problems' has no cursor; 'moda problems unexplained --cursor=<next_cursor>' pages the unexplained signals."
   }
 };
 function parseCommandFlags(schema, args, command, options = {}) {
@@ -2734,8 +3566,9 @@ function parseCommandFlags(schema, args, command, options = {}) {
       return close ? `Did you mean ${close}?` : "";
     }).filter(Boolean);
     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, "-")}`, {
+    const shown = canonicalCommandText(`moda ${command}`);
+    const helpCommand = `${shown} --help`;
+    throw new CliInputError(`Unknown flag${unknown.length > 1 ? "s" : ""} ${names} for '${shown}'.` + (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)] } : {},
@@ -2761,7 +3594,7 @@ function attachFlagDetails(error, schema, command) {
     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`]
+    suggestedCommands: [`${canonicalCommandText(`moda ${command}`)} --help`]
   });
 }
 function parseSpecFlags(name, args, command = name) {
@@ -2914,7 +3747,7 @@ async function searchFallbackToTraces(params) {
   const describe = literal ? "trace-level keyword matches (each trace contains the words)" : `trace-level ${traceMode}-ranked related traces (they may not contain the exact words; fallback.total is the candidate pool, not a match count)`;
   const nextCommands = [];
   if (first) {
-    nextCommands.push({ command: `moda audit ${first}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
+    nextCommands.push({ command: `moda traces spans ${first}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
   }
   if (hasMore) {
     nextCommands.push({ command: `${tracesCommand} --offset=${nextOffset}`, purpose: "Page through further trace-level results.", mutability: "read", requires_approval: false });
@@ -2936,7 +3769,7 @@ async function searchFallbackToTraces(params) {
         ...hasMore ? { next_offset: nextOffset } : {}
       }
     },
-    warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. Each result is a whole trace, not a message, with no score or message index. Open one with \`moda audit <conversation_id>\` or \`moda context <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
+    warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. Each result is a whole trace, not a message, with no score or message index. Open one with \`moda traces spans <conversation_id>\` or \`moda traces get <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
     nextCommands
   };
 }
@@ -3061,9 +3894,9 @@ function processingDisabledWarning(data, family) {
     `${family === "emotion" ? "Emotion" : "Frustration"} analysis is disabled for this tenant (${setting} = false), ` + "so zero results do NOT mean users are not frustrated. Enable it in Settings → Account → Signal processing; " + "only traces ingested after enabling are analyzed."
   ];
 }
-var CONTEXT_USAGE = "Usage: moda context <conversation_id> [--msg-index=N (alias --message-index)] [--window=0-5 | --metadata-only]";
-var CONTEXT_ALL_USAGE = "Usage: moda context <conversation_id> --all [--from=N] [--max-messages=N]";
-var CONTEXT_BATCH_USAGE = `Usage: moda context <id>[@msg_index] <id>[@msg_index] ... | --ids-from=-|<file> [--window=0-5 | --metadata-only | --all [--from=N] [--max-messages=N]] (max ${BATCH_MAX_TARGETS} targets)`;
+var CONTEXT_USAGE = "Usage: moda traces get <conversation_id> [--msg-index=N (alias --message-index)] [--window=0-5 | --metadata-only]";
+var CONTEXT_ALL_USAGE = "Usage: moda traces get <conversation_id> --all [--from=N] [--max-messages=N]";
+var CONTEXT_BATCH_USAGE = `Usage: moda traces get <id>[@msg_index] <id>[@msg_index] ... | --ids-from=-|<file> [--window=0-5 | --metadata-only | --all [--from=N] [--max-messages=N]] (max ${BATCH_MAX_TARGETS} targets)`;
 var CONTEXT_FLAG_ALIASES = { "message-index": "msg-index" };
 var CONTEXT_MAX_WINDOW = 5;
 var EMPTY_ANCHOR_VALUES = new Set(["", "null", "undefined", "none"]);
@@ -3237,7 +4070,7 @@ async function readFullTranscript(conversationId, opts = {}) {
     if (next !== null) {
       const last = asNumber(returned[returned.length - 1]?.index) ?? next - 1;
       const nextMax = firstMissing !== null ? Math.min(pageSize, Math.max(kept * 2, 50)) : pageSize;
-      const continueWith = `moda context ${shellArg(contextTarget(conversationId))} --all --from=${next} --max-messages=${nextMax}`;
+      const continueWith = `moda traces get ${shellArg(contextTarget(conversationId))} --all --from=${next} --max-messages=${nextMax}`;
       out.push(`Trace has ${total} messages; returned messages ${start}-${last}. ` + (firstMissing !== null ? `Stopped at ${kept} of the ${messages.length} messages read to stay under the agent output byte limit (--json has no limit). ` : "") + `Continue with: ${continueWith}`);
       nextCommands.push({
         command: continueWith,
@@ -3250,7 +4083,7 @@ async function readFullTranscript(conversationId, opts = {}) {
       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 (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).`);
+      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 traces spans <conversation_id> --include-bodies\` (or \`--include-raw\` for the verbatim events).`);
     }
     return {
       data: stripLoneSurrogates({
@@ -3317,7 +4150,7 @@ async function readContextItem(command, params, inputWarnings, fits) {
     const center = asNumber(asRecord(ctxRecord.context)?.center_index) ?? params.msg_index ?? 0;
     const span = Math.min(params.window * 2 + 1, CONTEXT_ALL_MAX_MESSAGES);
     const from = Math.max(0, center - Math.floor((span - 1) / 2));
-    const wide = `moda context ${shellArg(contextTarget(params.conversation_id))} --all --from=${from} --max-messages=${span}`;
+    const wide = `moda traces get ${shellArg(contextTarget(params.conversation_id))} --all --from=${from} --max-messages=${span}`;
     warnings.push(`--window=${params.window} is above the maximum of ${CONTEXT_MAX_WINDOW}, so this shows ±${CONTEXT_MAX_WINDOW} messages. For a wider slice run: ${wide}`);
     nextCommands.push({ command: wide, purpose: `Read ±${params.window} messages around the anchor.`, mutability: "read", requires_approval: false });
   }
@@ -3329,8 +4162,8 @@ async function readContextItem(command, params, inputWarnings, fits) {
     }
   };
 }
-var AUDIT_USAGE = "Usage: moda audit <conversation_id|trace_id> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] [--cursor=<next_cursor>]";
-var AUDIT_BATCH_USAGE = `Usage: moda audit <id> <id> ... | --ids-from=-|<file> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] (max ${BATCH_MAX_TARGETS} targets)`;
+var AUDIT_USAGE = "Usage: moda traces spans <conversation_id|trace_id> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] [--cursor=<next_cursor>]";
+var AUDIT_BATCH_USAGE = `Usage: moda traces spans <id> <id> ... | --ids-from=-|<file> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] (max ${BATCH_MAX_TARGETS} targets)`;
 async function readAuditItem(command, params, budget) {
   const query2 = new URLSearchParams;
   if (params.kind && params.kind !== "auto")
@@ -3443,7 +4276,7 @@ function writeBatchResult(command, context, targets, results, batchWarnings, fla
     const nextCommands = [];
     if (remaining.length > 0) {
       const lines = remaining.map((target) => shellArg(target.raw)).join(" ");
-      const continueWith = [`printf '%s\\n' ${lines} |`, `moda ${command}`, "--ids-from=-", ...renderBatchFlags(flags)].join(" ");
+      const continueWith = [`printf '%s\\n' ${lines} |`, canonicalCommandText(`moda ${command}`), "--ids-from=-", ...renderBatchFlags(flags)].join(" ");
       warnings.push(`Returned ${kept2} of ${targets.length} targets to stay under the agent output byte limit (--json has no limit). Read the other ${remaining.length} with: ${continueWith}`);
       nextCommands.push({
         command: continueWith,
@@ -3652,7 +4485,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "search": {
       if (!positional || positional.trim() === "") {
-        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]');
+        throw new CliInputError("<query> is required", 'Usage: moda traces 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 = parseSpecFlags("search", args, command);
@@ -3708,12 +4541,12 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "world-state": {
       if (!positional) {
-        throw new CliInputError("<conversation_id> is required", "Usage: moda world-state <conversation_id> [--summary-only] [--event-limit=N]");
+        throw new CliInputError("<conversation_id> is required", "Usage: moda traces state <conversation_id> [--summary-only] [--event-limit=N]");
       }
       const args = flagsToArgs(flags, "conversation_id", positional);
       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]]");
+        throw new CliInputError("Choose either --snapshot or --replay, not both.", "Usage: moda traces state <conversation_id> [--snapshot --msg-index=N [--block-index=M] [--segment-index=K]] | [--replay --message-count=N [--format=frames|fold-inputs]]");
       }
       if (params.snapshot === true) {
         const query3 = new URLSearchParams;
@@ -3812,7 +4645,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "tool-failure-detail": {
       if (!positional) {
-        throw new CliInputError("<tool_name> is required", "Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N (1-20, default 5)] [--offset=N] [--compact | --include-window [--window=N]]");
+        throw new CliInputError("<tool_name> is required", "Usage: moda detections tools <tool_name> [--subtype=S] [--days-back=N] [--limit=N (1-20, default 5)] [--offset=N] [--compact | --include-window [--window=N]]");
       }
       const { "no-include-window": noIncludeWindow, ...toolFlags } = flags;
       if (noIncludeWindow !== undefined && noIncludeWindow !== "false") {
@@ -3843,7 +4676,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const subtypeCount = Array.isArray(tfRecord.subtypes) ? tfRecord.subtypes.length : 0;
       const exampleCount = Array.isArray(tfRecord.examples) ? tfRecord.examples.length : 0;
       const warnings = subtypeCount === 0 && exampleCount === 0 ? [
-        `No failures found for tool "${params.tool_name}" in the last ${params.days_back ?? 7} day(s) — the tool may have no failures in this window, or the name may not exist in this tenant. Run \`moda tool-failures\` to list tools with recorded failures, or widen --days-back.`
+        `No failures found for tool "${params.tool_name}" in the last ${params.days_back ?? 7} day(s) — the tool may have no failures in this window, or the name may not exist in this tenant. Run \`moda detections tools\` to list tools with recorded failures, or widen --days-back.`
       ] : [];
       const knownSubtypes = Array.isArray(tfRecord.subtypes) ? tfRecord.subtypes.map((row) => asString(asRecord(row)?.subtype)).filter((value) => Boolean(value)) : [];
       if (params.subtype && knownSubtypes.length > 0 && !knownSubtypes.includes(params.subtype)) {
@@ -3901,7 +4734,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         break;
       }
       if (positional) {
-        throw new CliInputError(`Unknown problems subcommand '${positional}'.`, "Usage: moda problems [--days-back=N] [--limit=N] | moda problems remainder [--family=F] [--days-back=N] [--limit=N] [--cursor=TOKEN]. For one Problem use 'moda problem <id>'.");
+        throw new CliInputError(`Unknown problems subcommand '${positional}'.`, "Usage: moda problems [--days-back=N] [--limit=N] | moda problems unexplained [--family=F] [--days-back=N] [--limit=N] [--cursor=TOKEN]. For one Problem use 'moda problems get <id>'.");
       }
       const args = flagsToArgs(flags);
       const params = parseSpecFlags("problems", args, command);
@@ -3928,7 +4761,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         break;
       }
       if (!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]");
+        throw new CliInputError("<problem_id> is required", "Usage: moda problems get <problem_id> [--full | --evidence|--reports|--traces|--feedback] [--limit=N] [--cursor=TOKEN] [--family=F] [--door=D]");
       }
       const args = flagsToArgs(flags, "id", positional);
       const params = parseSpecFlags("problem", args, command);
@@ -3936,11 +4769,11 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const views = ["evidence", "reports", "conversations", "feedback"].filter((view2) => view2 === "conversations" ? traceView : params[view2] === true);
       if (views.length > 1) {
         const got = views.map((v) => v === "conversations" ? "--traces" : `--${v}`).join(" ");
-        throw new CliInputError(`Choose at most one of --evidence, --reports, --traces, --feedback (got ${got}).`, "Usage: moda problem <problem_id> [--evidence|--reports|--traces|--feedback]");
+        throw new CliInputError(`Choose at most one of --evidence, --reports, --traces, --feedback (got ${got}).`, "Usage: moda problems get <problem_id> [--evidence|--reports|--traces|--feedback]");
       }
       const view = views[0];
       if (view !== undefined && params.full === true) {
-        throw new CliInputError("--full applies to the dossier only; the --evidence/--reports/--traces/--feedback pages are always whole.", "Usage: moda problem <problem_id> [--full] | moda problem <problem_id> --evidence|--reports|--traces|--feedback");
+        throw new CliInputError("--full applies to the dossier only; the --evidence/--reports/--traces/--feedback pages are always whole.", "Usage: moda problems get <problem_id> [--full] | moda problems get <problem_id> --evidence|--reports|--traces|--feedback");
       }
       if (view === undefined) {
         const data2 = await callDataAPI(`/problems/${encodeURIComponent(params.id)}`);
@@ -3963,7 +4796,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       }
       if (!UUID_RE.test(params.id)) {
         const viewFlag = view === "conversations" ? "--traces" : `--${view}`;
-        throw new CliInputError(`${viewFlag} requires a canonical problem UUID; got "${params.id}". Run \`moda problems\` or \`moda problem <id>\` first to resolve the id.`);
+        throw new CliInputError(`${viewFlag} requires a canonical problem UUID; got "${params.id}". Run \`moda problems\` or \`moda problems get <id>\` first to resolve the id.`);
       }
       const query2 = new URLSearchParams;
       if (params.limit)
@@ -3983,7 +4816,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "problem-feedback": {
       if (!positional) {
-        throw new CliInputError("<problem_id> is required", `Usage: moda problem-feedback <problem_id> --action=${PROBLEM_FEEDBACK_ACTIONS.join("|")} [--reason=TEXT] [--attribution-id=UUID] [--new-name=NAME]`);
+        throw new CliInputError("<problem_id> is required", `Usage: moda problems feedback <problem_id> --action=${PROBLEM_FEEDBACK_ACTIONS.join("|")} [--reason=TEXT] [--attribution-id=UUID] [--new-name=NAME]`);
       }
       const params = ProblemFeedbackSchema.parse({
         id: positional,
@@ -4005,7 +4838,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       }
       if (params.action === "flag_attribution") {
         if (params.attribution_id === undefined || params.attribution_id.trim() === "") {
-          throw new CliInputError("--attribution-id=<uuid> is required for --action=flag_attribution. Run `moda problem <problem_id> --evidence` to list attribution ids.");
+          throw new CliInputError("--attribution-id=<uuid> is required for --action=flag_attribution. Run `moda problems get <problem_id> --evidence` to list attribution ids.");
         }
         if (!UUID_RE.test(params.attribution_id)) {
           throw new CliInputError("--attribution-id must be a UUID.");
@@ -4027,7 +4860,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "problem-linear": {
       if (!positional) {
-        throw new CliInputError("<problem_id> is required", "Usage: moda problem-linear <problem_id>");
+        throw new CliInputError("<problem_id> is required", "Usage: moda problems linear <problem_id>");
       }
       if (!UUID_RE.test(positional)) {
         throw new CliInputError(`Problem id must be a canonical UUID; got "${positional}". Run \`moda problems\` to list problems with their canonical ids.`);
@@ -4037,17 +4870,17 @@ async function runCommand(command, positional, flags, positionals = positional ?
       });
       const link = asRecord(data)?.link;
       const summary = describeLinearLink(link);
-      const nextCommands = link ? [] : [`moda problem-linear-file ${positional}`];
+      const nextCommands = link ? [] : [`moda problems link ${positional}`];
       if (context.outputMode === "human" && !context.quiet) {
         safeWriteStderr(link ? `${summary}
-` : `${summary} File one with: moda problem-linear-file ${positional}
+` : `${summary} File one with: moda problems link ${positional}
 `);
       }
       context.output.writeData(data, { summary, nextCommands });
       break;
     }
     case "problem-linear-file": {
-      const usage = "Usage: moda problem-linear-file <problem_id> [--issue=ENG-123|URL] [--team-id=ID] [--title=TEXT] [--priority=0-4]";
+      const usage = "Usage: moda problems link <problem_id> [--issue=ENG-123|URL] [--team-id=ID] [--title=TEXT] [--priority=0-4]";
       if (!positional) {
         throw new CliInputError("<problem_id> is required", usage);
       }
@@ -4126,14 +4959,14 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "trace-signals": {
       if (!positional) {
-        throw new CliInputError("<conversation_id> is required", "Usage: moda trace-signals <conversation_id>");
+        throw new CliInputError("<conversation_id> is required", "Usage: moda detections list --family=custom_signal --conversation-id=<conversation_id>");
       }
       const data = await callDataAPI(`/conversations/${encodeURIComponent(positional)}/custom-signals`);
       context.output.writeData(data);
       break;
     }
     case "signal-label": {
-      const usage = `Usage: moda signal-label <signal_id> --conversation-id=ID --label=${SIGNAL_LABELS.join("|")} [--note=TEXT] [--msg-index=N] [--msg-dedup-token=T]`;
+      const usage = `Usage: moda review custom-signal <signal_id> --conversation-id=ID --verdict=correct|false_positive [--note=TEXT] [--msg-index=N] [--msg-dedup-token=T]`;
       if (!positional) {
         throw new CliInputError("<signal_id> is required", usage);
       }
@@ -4162,7 +4995,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "detection-reviews": {
       if (!positional) {
-        throw new CliInputError("<conversation_id> is required", "Usage: moda detection-reviews <conversation_id> [--attribution-id=UUID]");
+        throw new CliInputError("<conversation_id> is required", "Usage: moda reviews list <conversation_id> --kind=problem-detection [--attribution-id=UUID]");
       }
       const attributionId = flags["attribution-id"];
       if (attributionId !== undefined && !UUID_RE.test(attributionId)) {
@@ -4174,7 +5007,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     case "detection-review": {
-      const usage = `Usage: moda detection-review <problem_id> --conversation-id=ID --attribution-id=UUID --verdict=${DETECTION_VERDICTS.join("|")} [--note=TEXT]`;
+      const usage = `Usage: moda review problem-detection <problem_id> --conversation-id=ID --attribution-id=UUID --verdict=${DETECTION_VERDICTS.join("|")} [--note=TEXT]`;
       if (!positional) {
         throw new CliInputError("<problem_id> is required", usage);
       }
@@ -4201,7 +5034,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     case "false-positive": {
-      const usage = `Usage: moda false-positive <${FALSE_POSITIVE_KINDS.join("|")}> <target> --reason=TEXT [--undo]`;
+      const usage = `Usage: moda review <${FALSE_POSITIVE_KINDS.join("|")}> <target> --reason=TEXT [--undo]`;
       const [kind, target] = positionals;
       if (!kind || !target)
         throw new CliInputError("<kind> and <target> are required", usage);
@@ -4274,7 +5107,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         const query2 = new URLSearchParams;
         if (flags.kind !== undefined) {
           if (flags.kind === "problem" || flags.kind === "problem-detection") {
-            throw new CliInputError(`'moda false-positives' cannot list --kind=${flags.kind}: ${flags.kind === "problem" ? "a dismissed Problem is recorded as Problem feedback" : "a problem-detection false positive is recorded as a detection review on its Problem"}, not in the false-positive log this command reads. Nothing was sent.`, flags.kind === "problem" ? "Read it with 'moda problem <problem_id> --feedback'. --kind for this list takes " + Object.keys(kinds).join("|") + "." : "Read them per trace with 'moda detection-reviews <conversation_id>' or 'moda false-positives <conversation_id>'. --kind for this list takes " + Object.keys(kinds).join("|") + ".", "unsupported_kind");
+            throw new CliInputError(`'moda reviews list' cannot list --kind=${flags.kind}: ${flags.kind === "problem" ? "a dismissed Problem is recorded as Problem feedback" : "a problem-detection false positive is recorded as a detection review on its Problem"}, not in the false-positive log this command reads. Nothing was sent.`, flags.kind === "problem" ? "Read it with 'moda problems get <problem_id> --feedback'. --kind for this list takes " + Object.keys(kinds).join("|") + "." : "Read them per trace with 'moda reviews list <conversation_id> --kind=problem-detection' or 'moda reviews list <conversation_id>'. --kind for this list takes " + Object.keys(kinds).join("|") + ".", "unsupported_kind");
           }
           if (!kinds[flags.kind])
             throw new CliInputError(`--kind must be one of ${Object.keys(kinds).join("|")}`);
@@ -4483,7 +5316,7 @@ function initAgentWriteOptions(result) {
     warnings: [
       ...manualActions.filter((action) => action.reason).map((action) => `${action.title}: ${action.reason}`),
       ...result.promptSync?.status === "failed" ? [`Prompt sync failed: ${result.promptSync.error}. Retry with 'moda prompts sync'.`] : [],
-      ...result.skillSync?.status === "failed" ? [`Skill sync failed: ${result.skillSync.error}. Retry with 'moda skills sync'.`] : [],
+      ...result.skillSync?.status === "failed" ? [`Skill sync failed: ${result.skillSync.error}. Retry with 'moda skills push'.`] : [],
       ...result.skillSync?.warnings ?? [],
       ...(result.skillInstall?.warnings ?? []).map((warning) => `moda-cli skill install: ${warning}`)
     ]
@@ -4501,6 +5334,10 @@ function initArtifactKind(file) {
     return "ci_workflow";
   return "init_artifact";
 }
+async function canonicalNounHandler(context) {
+  const route = routeCanonical(context.command, context.positionals, context.flags);
+  throw new CliInputError(`'moda ${context.command}' was not routed${route ? ` (expected ${route.handler})` : ""}.`, `Run 'moda ${context.command} --help'.`, "unrouted_command");
+}
 var dataApiDefaults = {
   auth: "api-key",
   outputModes: ["human", "json", "agent"],
@@ -4545,7 +5382,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runInit } = await import("./index-nsaph4as.js");
+      const { runInit } = await import("./index-4b1ybz51.js");
       if (context.outputMode === "agent-stream") {
         context.output.writeEvent({
           event: "started",
@@ -4595,7 +5432,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runProvision } = await import("./provision-r9fhrvpw.js");
+      const { runProvision } = await import("./provision-q86phh4a.js");
       return runProvision(context, {
         resumeCommand: buildResumeCommand("provision", context.rawFlags)
       });
@@ -4879,7 +5716,7 @@ var commandRegistry = createCommandRegistry([
   {
     name: "problem-reopen",
     description: "Reopen a problem that was marked fixed (resolved problems return only via re-detection)",
-    examples: ['moda problem-reopen <problem_id> --reason="still happening"', "moda problem-reopen <problem_id> --dry-run"],
+    examples: ['moda problems reopen <problem_id> --reason="still happening"', "moda problems reopen <problem_id> --dry-run"],
     auth: "api-key",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
@@ -5025,21 +5862,23 @@ var commandRegistry = createCommandRegistry([
     name: "traces",
     aliases: ["conversations"],
     telemetryCommand: "conversations",
-    description: "Search and filter traces (agent runs); --search is ranked (hybrid when embeddings exist, else keyword), see total_kind",
+    description: "Traces (agent runs): list (the bare form; --search is ranked), search, get, state, spans",
     examples: [
-      'moda traces --search="error" --limit=5',
-      'moda traces --world-state="enterprise" --outcome=positive',
-      'moda traces --world-state="refund,enterprise" --include-world-state'
+      'moda traces list --search="error" --limit=5',
+      "moda traces get <conversation_id> --msg-index=12 --window=3",
+      'moda traces list --world-state="refund,enterprise" --include-world-state'
     ],
+    subcommands: treeSubcommandHelp("traces"),
+    defaultSubcommand: "list",
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "search",
     description: "Search trace messages (keyword, semantic, or hybrid)",
     examples: [
-      'moda search "billing error"',
-      'moda search "refund flow" --mode=semantic --time-range=7d --limit=10',
-      'moda search "area code" --since=2026-10-07 --until=2026-10-07'
+      'moda traces search "billing error"',
+      'moda traces search "refund flow" --mode=semantic --time-range=7d --limit=10',
+      'moda traces search "area code" --since=2026-10-07 --until=2026-10-07'
     ],
     ...dataApiDefaults
   }),
@@ -5047,8 +5886,8 @@ var commandRegistry = createCommandRegistry([
     name: "world-state",
     description: "Get a trace's world state (slots, threads, events)",
     examples: [
-      "moda world-state <conversation_id>",
-      "moda world-state <conversation_id> --summary-only"
+      "moda traces state <conversation_id>",
+      "moda traces state <conversation_id> --summary-only"
     ],
     ...dataApiDefaults
   }),
@@ -5056,13 +5895,13 @@ var commandRegistry = createCommandRegistry([
     name: "context",
     description: "Get windowed trace context (messages around one turn), or the whole trace with --all",
     examples: [
-      "moda context <conversation_id> --window=3",
-      "moda context <conversation_id> --msg-index=40 --window=0   # --message-index is an alias",
-      "moda context <conversation_id> --metadata-only   # summary + total_messages, no messages",
-      "moda context <conversation_id> --all",
-      "moda context <conversation_id> --all --from=500 --max-messages=500",
-      "moda context <id>@12 <id2>@3 <id3> --window=2   # batch: up to 25 targets, one envelope; id@N anchors at message N",
-      "moda context --ids-from=ids.txt --window=1   # one target per line (id or id@N); --ids-from=- reads stdin"
+      "moda traces get <conversation_id> --window=3",
+      "moda traces get <conversation_id> --msg-index=40 --window=0   # --message-index is an alias",
+      "moda traces get <conversation_id> --metadata-only   # summary + total_messages, no messages",
+      "moda traces get <conversation_id> --all",
+      "moda traces get <conversation_id> --all --from=500 --max-messages=500",
+      "moda traces get <id>@12 <id2>@3 <id3> --window=2   # batch: up to 25 targets, one envelope; id@N anchors at message N",
+      "moda traces get --ids-from=ids.txt --window=1   # one target per line (id or id@N); --ids-from=- reads stdin"
     ],
     ...dataApiDefaults
   }),
@@ -5071,13 +5910,13 @@ var commandRegistry = createCommandRegistry([
     aliases: ["trace"],
     description: "Raw non-deduped span audit for one trace or OTLP trace_id (hierarchy, tool spans, orphans, duplicates)",
     examples: [
-      "moda audit <conversation_id|trace_id>",
-      "moda audit <trace_id> --kind=trace --json",
-      "moda audit <conversation_id> --include-raw",
-      "moda audit <conversation_id> --include-bodies   # keep prompt/response bodies (omitted by default; long strings truncated)",
-      "moda audit <conversation_id> --limit=1000   # ingest rows to read (default 200, max 1000); warns when capped",
-      "moda audit <conversation_id> --cursor=<next_cursor>   # next page of a capped audit",
-      "moda audit <id1> <id2> <id3>   # batch: up to 25 ids, one envelope (or --ids-from=-|<file>)"
+      "moda traces spans <conversation_id|trace_id>",
+      "moda traces spans <trace_id> --kind=trace --json",
+      "moda traces spans <conversation_id> --include-raw",
+      "moda traces spans <conversation_id> --include-bodies   # keep prompt/response bodies (omitted by default; long strings truncated)",
+      "moda traces spans <conversation_id> --limit=1000   # ingest rows to read (default 200, max 1000); warns when capped",
+      "moda traces spans <conversation_id> --cursor=<next_cursor>   # next page of a capped audit",
+      "moda traces spans <id1> <id2> <id3>   # batch: up to 25 ids, one envelope (or --ids-from=-|<file>)"
     ],
     ...dataApiDefaults
   }),
@@ -5085,32 +5924,32 @@ var commandRegistry = createCommandRegistry([
     name: "frustrations",
     description: "User frustration detections: the frustration family of `emotions` (same data as the dashboard), legacy field names",
     examples: [
-      "moda frustrations --days-back=14",
-      "moda frustrations --days-back=14 --include-window   # agent output omits conversation windows unless asked"
+      "moda detections list --family=frustration --days-back=14",
+      "moda detections list --family=frustration --days-back=14 --include-window   # agent output omits conversation windows unless asked"
     ],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "tool-failures",
     description: "Get tool failure overview",
-    examples: ["moda tool-failures --days-back=14"],
+    examples: ["moda detections tools --days-back=14"],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "tool-failure-detail",
     description: "Get per-tool failure detail (each example embeds its anchor ±2 messages)",
     examples: [
-      "moda tool-failure-detail search",
-      "moda tool-failure-detail search --compact   # no embedded conversation (same as --include-window=false)",
-      "moda tool-failure-detail search --include-window --window=3"
+      "moda detections tools search",
+      "moda detections tools search --compact   # no embedded conversation (same as --include-window=false)",
+      "moda detections tools search --include-window --window=3"
     ],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "problems",
     description: "Rank cross-signal Problems by root cause (what to fix first)",
-    examples: ["moda problems", "moda problems --days-back=7 --limit=10", "moda problems remainder --family=emotion"],
-    subcommands: PROBLEMS_SUBCOMMAND_HELP,
+    examples: ["moda problems list", "moda problems list --days-back=7 --limit=10", "moda problems get <problem_id> --evidence", "moda problems unexplained --family=emotion"],
+    subcommands: treeSubcommandHelp("problems"),
     defaultSubcommand: "list",
     ...dataApiDefaults
   }),
@@ -5118,14 +5957,14 @@ var commandRegistry = createCommandRegistry([
     name: "problem-impact",
     description: "Live problem/use-case impact, full analysis denominators, daily recurrence, and paginated evidence",
     examples: [
-      "moda problem-impact --mode=catalog",
-      "moda problem-impact --node-id=node_0 --days-back=all",
-      "moda problem-impact --problem-id=<uuid> --mode=metrics",
-      "moda problem-impact --node-id=node_0 --problem-id=<uuid> --mode=evidence",
-      "moda problem-impact --node-id=node_0 --mode=trend --days-back=30",
-      "moda problem-impact --mode=overview --days-back=7",
-      "moda problem-impact --problem-id=<uuid> --mode=affected-use-cases",
-      `moda problem-impact --problem-id=<uuid> --mode=trace-use-cases --conversation-ids='["trace_id"]'`
+      "moda problems impact --mode=catalog",
+      "moda problems impact --node-id=node_0 --days-back=all",
+      "moda problems impact --problem-id=<uuid> --mode=metrics",
+      "moda problems impact --node-id=node_0 --problem-id=<uuid> --mode=evidence",
+      "moda problems impact --node-id=node_0 --mode=trend --days-back=30",
+      "moda problems impact --mode=overview --days-back=7",
+      "moda problems impact --problem-id=<uuid> --mode=affected-use-cases",
+      `moda problems impact --problem-id=<uuid> --mode=trace-use-cases --conversation-ids='["trace_id"]'`
     ],
     ...dataApiDefaults
   }),
@@ -5133,12 +5972,12 @@ var commandRegistry = createCommandRegistry([
     name: "problem",
     description: "Open one Problem: dossier, or --evidence/--reports/--traces/--feedback pages (--conversations is a legacy alias of --traces)",
     examples: [
-      "moda problem <problem_id>",
-      "moda problem <problem_id> --full   # whole dossier (agent output defaults to a compact one)",
-      "moda problem <problem_id> --evidence --limit=10",
-      "moda problem <problem_id> --reports",
-      "moda problem <problem_id> --traces --family=tool_failure",
-      "moda problem <problem_id> --feedback"
+      "moda problems get <problem_id>",
+      "moda problems get <problem_id> --full   # whole dossier (agent output defaults to a compact one)",
+      "moda problems get <problem_id> --evidence --limit=10",
+      "moda problems get <problem_id> --reports",
+      "moda problems get <problem_id> --traces --family=tool_failure",
+      "moda problems get <problem_id> --feedback"
     ],
     ...dataApiDefaults
   }),
@@ -5146,10 +5985,10 @@ var commandRegistry = createCommandRegistry([
     name: "problem-feedback",
     description: "Submit Problem feedback: mark fixed, dismiss, rename, or flag a bad attribution",
     examples: [
-      "moda problem-feedback <problem_id> --action=mark_fixed",
-      'moda problem-feedback <problem_id> --action=dismiss --reason="not actionable"',
-      'moda problem-feedback <problem_id> --action=rename --new-name="Better title"',
-      'moda problem-feedback <problem_id> --action=flag_attribution --attribution-id=<uuid> --reason="wrong trace"'
+      "moda problems feedback <problem_id> --action=mark_fixed",
+      'moda problems feedback <problem_id> --action=dismiss --reason="not actionable"',
+      'moda problems feedback <problem_id> --action=rename --new-name="Better title"',
+      'moda problems feedback <problem_id> --action=flag_attribution --attribution-id=<uuid> --reason="wrong trace"'
     ],
     ...dataApiDefaults,
     mutability: "write"
@@ -5157,16 +5996,16 @@ var commandRegistry = createCommandRegistry([
   legacyCommand({
     name: "problem-linear",
     description: "Show the Linear issue linked to a Problem (key, state, URL); needs Linear connected (Integrations -> Linear)",
-    examples: ["moda problem-linear <problem_id>"],
+    examples: ["moda problems linear <problem_id>"],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "problem-linear-file",
     description: "File a Problem as a Linear issue in the team's tracker, or link an existing issue with --issue; needs Linear connected (Integrations -> Linear)",
     examples: [
-      "moda problem-linear-file <problem_id>",
-      'moda problem-linear-file <problem_id> --team-id=<team_id> --title="CRM lookups time out" --priority=2',
-      "moda problem-linear-file <problem_id> --issue=ENG-123"
+      "moda problems link <problem_id>",
+      'moda problems link <problem_id> --team-id=<team_id> --title="CRM lookups time out" --priority=2',
+      "moda problems link <problem_id> --issue=ENG-123"
     ],
     ...dataApiDefaults,
     mutability: "write"
@@ -5175,8 +6014,8 @@ var commandRegistry = createCommandRegistry([
     name: "detection-reviews",
     description: "List problem detections on a trace with their review state (correct / false_positive / clear)",
     examples: [
-      "moda detection-reviews <conversation_id>",
-      "moda detection-reviews <conversation_id> --attribution-id=<uuid>"
+      "moda reviews list <conversation_id> --kind=problem-detection",
+      "moda reviews list <conversation_id> --kind=problem-detection --attribution-id=<uuid>"
     ],
     ...dataApiDefaults
   }),
@@ -5184,9 +6023,9 @@ var commandRegistry = createCommandRegistry([
     name: "detection-review",
     description: "Review a problem detection on a trace: mark it correct, a false positive, or clear the review",
     examples: [
-      'moda detection-review <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=false_positive --note="expected retry"',
-      "moda detection-review <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=correct",
-      "moda detection-review <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=clear"
+      'moda review problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=false_positive --note="expected retry"',
+      "moda review problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=correct",
+      "moda review problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --verdict=clear"
     ],
     ...dataApiDefaults,
     mutability: "write"
@@ -5195,17 +6034,17 @@ var commandRegistry = createCommandRegistry([
     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."
+      "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 detections list --family=emotion); 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"',
-      'moda false-positive quote <conversation_id> --family=frustration --turn=3 --quote="this is useless lol" --reason="joking"',
-      'moda false-positive tool <conversation_id> --tool=send_invoice --tool-use-id=<id> --reason="retried upstream"',
-      'moda false-positive laziness <conversation_id> --reason="reload after context reset is expected"',
-      "moda false-positive hallucination <conversation_id> --undo",
-      "moda false-positive custom-signal <signal_id> --conversation-id=<id> --undo",
-      'moda false-positive custom-signal <signal_id> --conversation-id=<id> --reason="refund was approved"'
+      'moda review problem <problem_id> --reason="two unrelated tools"',
+      'moda review problem-detection <problem_id> --conversation-id=<id> --attribution-id=<uuid> --reason="refund was approved"',
+      'moda review quote <conversation_id> --family=frustration --turn=3 --quote="this is useless lol" --reason="joking"',
+      'moda review tool <conversation_id> --tool=send_invoice --tool-use-id=<id> --reason="retried upstream"',
+      'moda review laziness <conversation_id> --reason="reload after context reset is expected"',
+      "moda review hallucination <conversation_id> --verdict=clear",
+      "moda review custom-signal <signal_id> --conversation-id=<id> --verdict=clear",
+      'moda review custom-signal <signal_id> --conversation-id=<id> --reason="refund was approved"'
     ],
     ...dataApiDefaults,
     mutability: "write"
@@ -5214,9 +6053,9 @@ var commandRegistry = createCommandRegistry([
     name: "false-positives",
     description: "List current false-positive marks across the workspace, or on one trace (with problem detection reviews)",
     examples: [
-      "moda false-positives",
-      "moda false-positives --kind=tool --all",
-      "moda false-positives <conversation_id>"
+      "moda reviews list",
+      "moda reviews list --kind=tool --all",
+      "moda reviews list <conversation_id>"
     ],
     ...dataApiDefaults
   }),
@@ -5239,22 +6078,22 @@ var commandRegistry = createCommandRegistry([
     description: "Open one custom signal, or --detections for its recent hits (paged)",
     examples: [
       "moda signal <signal_id>",
-      "moda signal <signal_id> --detections --days-back=30 --limit=20"
+      "moda detections list --family=custom_signal --signal-id=<signal_id> --days-back=30 --limit=20"
     ],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "trace-signals",
     description: "Custom signal hits on one trace",
-    examples: ["moda trace-signals <conversation_id>"],
+    examples: ["moda detections list --family=custom_signal --conversation-id=<conversation_id>"],
     ...dataApiDefaults
   }),
   legacyCommand({
     name: "signal-label",
     description: "Label a trace for a custom signal: fits, or does_not_fit to mark a false positive",
     examples: [
-      'moda signal-label <signal_id> --conversation-id=<id> --label=does_not_fit --note="refund was approved"',
-      "moda signal-label <signal_id> --conversation-id=<id> --label=fits --msg-index=12"
+      'moda review custom-signal <signal_id> --conversation-id=<id> --verdict=false_positive --note="refund was approved"',
+      "moda review custom-signal <signal_id> --conversation-id=<id> --verdict=correct --msg-index=12"
     ],
     ...dataApiDefaults,
     mutability: "write"
@@ -5263,9 +6102,9 @@ var commandRegistry = createCommandRegistry([
     name: "emotions",
     description: "Multi-family emotion detections (frustration, disapproval, sadness, confusion, anxiety, trust, positive)",
     examples: [
-      "moda emotions --days-back=7",
-      "moda emotions --family=confusion --limit=20",
-      "moda emotions --include-window   # keep conversation windows in agent output"
+      "moda detections list --family=emotion --days-back=7",
+      "moda detections list --family=emotion:confusion --limit=20",
+      "moda detections list --family=emotion --include-window   # keep conversation windows in agent output"
     ],
     ...dataApiDefaults
   }),
@@ -5273,8 +6112,8 @@ var commandRegistry = createCommandRegistry([
     name: "laziness",
     description: "Laziness detections per trace: repeated tool calls, premature handoffs, and other lazy patterns",
     examples: [
-      "moda laziness --days-back=30",
-      "moda laziness --conversation-id=<id>"
+      "moda detections list --family=laziness --days-back=30",
+      "moda detections list --family=laziness --conversation-id=<id>"
     ],
     ...dataApiDefaults
   }),
@@ -5282,9 +6121,9 @@ var commandRegistry = createCommandRegistry([
     name: "hallucinations",
     description: "Grounding detections: contradicted/verified outputs with rule breakdown",
     examples: [
-      "moda hallucinations --days-back=30",
-      "moda hallucinations --kind=contradicted --limit=20",
-      "moda hallucinations --conversation-id=<id>"
+      "moda detections list --family=hallucination --days-back=30",
+      "moda detections list --family=hallucination --kind=contradicted --limit=20",
+      "moda detections list --family=hallucination --conversation-id=<id>"
     ],
     ...dataApiDefaults
   }),
@@ -5306,6 +6145,44 @@ var commandRegistry = createCommandRegistry([
     ],
     ...dataApiDefaults
   }),
+  {
+    name: "detections",
+    description: NOUN_SUMMARIES.detections,
+    examples: [...leavesOf("detections").flatMap((leaf) => leaf.examples.slice(0, 2))],
+    subcommands: treeSubcommandHelp("detections"),
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "read",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: canonicalNounHandler
+  },
+  {
+    name: "review",
+    description: NOUN_SUMMARIES.review,
+    examples: [...leafFor("review", undefined)?.examples ?? []],
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "write",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: canonicalNounHandler
+  },
+  {
+    name: "reviews",
+    description: NOUN_SUMMARIES.reviews,
+    examples: [...leavesOf("reviews").flatMap((leaf) => leaf.examples)],
+    subcommands: treeSubcommandHelp("reviews"),
+    auth: "api-key",
+    outputModes: ["human", "json", "agent"],
+    mutability: "read",
+    validateConfigBeforeRun: false,
+    resetApiRequestCountBeforeRun: false,
+    telemetry: "result-and-error",
+    handler: canonicalNounHandler
+  },
   legacyCommand({
     name: "feedback",
     description: "Flag wrong/missing data or CLI quirks to the Moda team",
@@ -5382,11 +6259,13 @@ var commandRegistry = createCommandRegistry([
       {
         name: "ab",
         description: "Run a judged prompt A/B replay experiment",
-        usage: "moda prompts ab --baseline=<path> --candidate=<path> [--traces=<ids>|--set-id=<id>|--auto-generate] [--yes]",
+        usage: "moda prompts ab --baseline=<path> --candidate=<path> [--traces=<ids>|--problem=<problem_id> [--max-cases=<n>]|--set-id=<id>|--auto-generate] [--yes]",
         flags: [
           { name: "--baseline=<path>", description: "Prompt file to treat as the control." },
           { name: "--candidate=<path>", description: "Prompt file to treat as the variant." },
           { name: "--traces=<ids>", description: "Comma-separated trace ids (conversation_id values) to replay, at most 100. Each case uses Moda's distilled scenario and success criteria for the trace; a trace that cannot be distilled falls back to its opening user message with generic criteria, and the run warns. Legacy alias: --conversations=<ids>." },
+          { name: "--problem=<problem_id>", description: "Replay the Problem's failing traces: one case per affected trace, starting at its evidence msg_index (like --traces=<id>@<n>), read from `moda problems get <id> --evidence`, then `--traces` if needed. Prints the traces it chose. Not combinable with --traces, --set-id, --auto-generate, or --cases." },
+          { name: "--max-cases=<n>", description: "With --problem: replay at most this many traces (default 10, max 100)." },
           { name: "--cases=<n>", description: "Cases to auto-generate (default 5, max 100)." },
           { name: "--seeds=<n>", description: "Repeats per case per arm (default 3, max 10)." },
           { name: "--model=<slug>", description: "Assistant model for both arms; must be in the replay allowlist unless --allow-any-model." },
@@ -5394,7 +6273,8 @@ var commandRegistry = createCommandRegistry([
           { name: "--promote", description: "Make this run's replay set the tenant's primary replay set. Off by default, so an ad-hoc A/B never replaces it." }
         ],
         examples: [
-          "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,conv_2",
+          "moda prompts ab --baseline=prompts/agent.prompt.md --candidate=prompts/agent-v2.prompt.md --problem=<problem_id>"
         ]
       },
       {
@@ -5427,18 +6307,18 @@ var commandRegistry = createCommandRegistry([
   }),
   {
     name: "skills",
-    description: "Generate, pull, and sync Moda skills",
+    description: "Generate, pull (download), push (upload), and install Moda skills",
     examples: [
       "moda skills gen",
       "moda skills status",
       "moda skills pull",
-      "moda skills sync",
+      "moda skills push",
       "moda skills install --list",
       "moda skills install integration-node-openai"
     ],
     subcommands: SKILLS_SUBCOMMAND_HELP,
     auth: "api-key",
-    authNote: "install is local; gen, status, pull, sync, list, show, policy, and proposals need the API key.",
+    authNote: "install is local; gen, status, pull, push, list, show, policy, and proposals need the API key.",
     outputModes: ["human", "json", "agent"],
     mutability: "write",
     validateConfigBeforeRun: false,
@@ -5543,44 +6423,45 @@ function cliValidationReason(error) {
   return;
 }
 function printCliError(error) {
+  const safeWriteStderr2 = (text) => safeWriteStderr(canonicalCommandText(text));
   if (error instanceof CliInputError) {
-    safeWriteStderr(`Error: ${error.message}
+    safeWriteStderr2(`Error: ${error.message}
 `);
     if (error.usage)
-      safeWriteStderr(`${error.usage}
+      safeWriteStderr2(`${error.usage}
 `);
   } else if (error instanceof CliAccessError) {
-    safeWriteStderr(`Error: ${error.message}
+    safeWriteStderr2(`Error: ${error.message}
 `);
     if (error.guidance)
-      safeWriteStderr(`${error.guidance}
+      safeWriteStderr2(`${error.guidance}
 `);
   } 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}`;
     });
-    safeWriteStderr(`Validation error:
+    safeWriteStderr2(`Validation error:
 ${[...new Set(issues)].join(`
 `)}
 `);
   } else if (error instanceof ApiError && error.readable) {
-    safeWriteStderr(`${error.message}
+    safeWriteStderr2(`${error.message}
 `);
     if (error.suggestions?.length) {
-      safeWriteStderr(`Try:
+      safeWriteStderr2(`Try:
 ${error.suggestions.map((s) => `  ${s}`).join(`
 `)}
 `);
     }
   } else if (error instanceof ApiError) {
-    safeWriteStderr(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}
+    safeWriteStderr2(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}
 `);
   } else if (error instanceof Error) {
-    safeWriteStderr(`Error: ${error.message}
+    safeWriteStderr2(`Error: ${error.message}
 `);
   } else {
-    safeWriteStderr(`Error: ${String(error)}
+    safeWriteStderr2(`Error: ${String(error)}
 `);
   }
 }
@@ -5602,14 +6483,18 @@ ${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 canonical = (name) => {
+    const legacy = legacyNameFor(name, undefined, {});
+    return legacy ? usePath(legacy) : name;
+  };
+  const matches = [...new Set(closestMatches(command, names).map(canonical))];
   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),
+    allowed: visible.map((entry) => entry.name).filter((name) => !legacyNameFor(name, undefined, {})),
     ...matches.length > 0 ? { didYouMean: matches } : {},
     suggestedCommands: [...matches.map((name) => `moda ${name} --help`), "moda --help"]
   });
@@ -5638,10 +6523,50 @@ async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
       process.env.MODA_PROFILE = previousProfileEnv;
   }
 }
-async function dispatchParsedCommandInner(parsed, startedAt) {
-  const { command, flags } = parsed;
+function usageIdentityFor(parsed, route, legacy, definition) {
+  if (route)
+    return { command: route.leaf.noun, subcommand: route.telemetrySubcommand };
+  if (legacy) {
+    const kind = legacy.legacy === "false-positive" && FALSE_POSITIVE_KINDS.includes(parsed.positional ?? "") ? parsed.positional : undefined;
+    return { ...legacy.canonical, ...kind ? { subcommand: kind } : {}, legacyAlias: legacy.legacy };
+  }
+  return definition ? canonicalTelemetryForDefault(definition.name, parsed.positional) : undefined;
+}
+function rejectedRouteIdentity(parsed) {
+  if (parsed.command === "review") {
+    const kind = FALSE_POSITIVE_KINDS.includes(parsed.positional ?? "") ? parsed.positional : undefined;
+    return { command: "review", ...kind ? { subcommand: kind } : {} };
+  }
+  const leaf = leafFor(parsed.command, parsed.positional);
+  return { command: parsed.command, ...leaf ? { subcommand: leaf.verb } : {} };
+}
+function assertRoutedFlags(route, flags) {
+  if (!route.allowedFlags)
+    return;
+  const shape = z.object(Object.fromEntries(route.allowedFlags.map((flag) => [flag.replace(/-/g, "_"), z.unknown()])));
+  const aliases = new Set(Object.keys(route.flagAliases ?? {}));
+  const args = Object.fromEntries(Object.keys(flags).filter((flag) => !aliases.has(flag.replace(/_/g, "-"))).map((flag) => [flag.replace(/-/g, "_"), true]));
+  parseCommandFlags(shape.passthrough(), args, route.label, route.flagAliases ? { flagAliases: route.flagAliases } : {});
+}
+function renameErrorCommands(error, renames) {
+  if (error instanceof CliInputError) {
+    const details2 = error.details;
+    const renamed = new CliInputError(renameCommands(error.message, renames), error.usage === undefined ? undefined : renameCommands(error.usage, renames), error.reason, details2 ? { ...details2, ...details2.suggestedCommands ? { suggestedCommands: details2.suggestedCommands.map((command) => renameCommands(command, renames)) } : {} } : undefined);
+    const warnings = error.warnings;
+    if (warnings !== undefined)
+      Object.assign(renamed, { warnings });
+    return renamed;
+  }
+  const details = inputDetailsOf(error);
+  if (details?.suggestedCommands && error !== null && typeof error === "object") {
+    attachInputDetails(error, { ...details, suggestedCommands: details.suggestedCommands.map((command) => renameCommands(command, renames)) });
+  }
+  return error;
+}
+async function dispatchParsedCommandInner(typedParsed, startedAt) {
+  const { command, flags } = typedParsed;
   const switchError = normalizeBooleanFlags(flags);
-  const commandFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
+  const typedFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
   const telemetryDisabled = isTelemetryDisabled(flags);
   const updateCheckDisabled = isUpdateCheckDisabled(flags);
   if (command === "--version" || command === "-V" || flags.version === "true") {
@@ -5649,9 +6574,11 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
     return 0;
   }
   if (command === "--help" || command === "-h" || flags.help === "true") {
+    if (command && printTreeHelp(typedParsed))
+      return 0;
     const helpTarget = command && command !== "--help" && command !== "-h" ? commandRegistry.find(command) : undefined;
     if (helpTarget) {
-      const subcommandName = parsed.positional;
+      const subcommandName = typedParsed.positional;
       const subcommandEntry = subcommandName ? helpTarget.subcommands?.find((entry) => entry.name === subcommandName) : undefined;
       if (subcommandEntry) {
         printSubcommandHelp(helpTarget, subcommandEntry);
@@ -5671,62 +6598,117 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
     printHelp();
     return 1;
   }
-  const failEarly = (error, commandDefinition) => {
-    const mode = resolveOutputMode(commandFlags, {
-      isTTY: process.stdout.isTTY,
-      env: process.env
+  let route;
+  let routeError;
+  try {
+    route = routeCanonical(command, typedParsed.positionals, typedFlags);
+  } catch (error) {
+    routeError = error;
+  }
+  const legacy = route || routeError ? undefined : legacyNameFor(command, typedParsed.positional, typedFlags);
+  const parsed = route ? {
+    ...typedParsed,
+    command: route.handler,
+    positional: route.positionals[0],
+    positionals: route.positionals,
+    flags: route.rewriteFlags(flags)
+  } : typedParsed;
+  const commandFlags = route ? route.rewriteFlags(typedFlags) : typedFlags;
+  const outputModeFor = () => resolveOutputMode(typedFlags, {
+    isTTY: process.stdout.isTTY,
+    env: process.env
+  });
+  const reportUsage = (input) => {
+    const { definition: definition2, identity: identity2 } = input;
+    const handlerTelemetry = definition2 ? telemetryCommandName(definition2) : identity2?.command;
+    if (!handlerTelemetry)
+      return;
+    const telemetryProfile = existingFlagProfile(typedFlags);
+    const adoption = buildSearchAdoptionTelemetry({
+      command: handlerTelemetry,
+      positional: parsed.positional,
+      flags: commandFlags,
+      outputMode: input.outputMode,
+      recorded: input.recorded,
+      skillVersion: process.env.MODA_SKILL_VERSION,
+      subcommands: definition2 ? telemetrySubcommandNames(definition2) : [],
+      defaultSubcommand: definition2?.defaultSubcommand
+    });
+    if (identity2 && adoption) {
+      if (identity2.subcommand)
+        adoption.subcommand = identity2.subcommand;
+      else
+        delete adoption.subcommand;
+    }
+    sendCliUsageTelemetry({
+      apiKey: input.apiKey ?? resolveApiKey({ profile: telemetryProfile }),
+      profile: telemetryProfile,
+      command: identity2?.command ?? handlerTelemetry,
+      flags: typedFlags,
+      status: input.status,
+      ...input.error !== undefined ? { errorType: classifyCliError(input.error), validationReason: cliValidationReason(input.error) } : {},
+      exitCode: input.exitCode,
+      durationMs: Date.now() - startedAt,
+      apiRequestCount: input.apiRequestCount,
+      adoption,
+      ...identity2?.legacyAlias ? { legacyAlias: identity2.legacyAlias } : {}
     });
+  };
+  const failEarly = (error, commandDefinition, identity2) => {
+    const mode = outputModeFor();
     const telemetryOptOut = telemetryDisabled || flags["no-telemetry"] !== undefined && flags["no-telemetry"] !== "false";
-    if (commandDefinition && !telemetryOptOut && commandDefinition.telemetry === "result-and-error") {
-      const telemetryCommand2 = telemetryCommandName(commandDefinition);
-      const telemetryProfile = existingFlagProfile(commandFlags);
-      sendCliUsageTelemetry({
-        apiKey: resolveApiKey({ profile: telemetryProfile }),
-        profile: telemetryProfile,
-        command: telemetryCommand2,
-        flags: commandFlags,
+    const reports = commandDefinition ? commandDefinition.telemetry === "result-and-error" : identity2 !== undefined;
+    if (reports && !telemetryOptOut) {
+      reportUsage({
+        definition: commandDefinition,
+        identity: identity2,
         status: "error",
-        errorType: classifyCliError(error),
-        validationReason: cliValidationReason(error),
+        error,
         exitCode: 1,
-        durationMs: Date.now() - startedAt,
         apiRequestCount: 0,
-        adoption: buildSearchAdoptionTelemetry({
-          command: telemetryCommand2,
-          positional: parsed.positional,
-          flags: commandFlags,
-          outputMode: mode,
-          recorded: {},
-          skillVersion: process.env.MODA_SKILL_VERSION,
-          subcommands: telemetrySubcommandNames(commandDefinition),
-          defaultSubcommand: commandDefinition.defaultSubcommand
-        })
+        outputMode: mode,
+        recorded: {}
       });
     }
     if (mode === "agent" || mode === "agent-stream" || mode === "json") {
-      printAgentCliError(command, error, mode);
+      printAgentCliError(route?.leaf.path ?? command, error, mode);
     } else {
       printCliError(error);
     }
     return 1;
   };
-  const definition = commandRegistry.find(command);
+  if (routeError) {
+    if (!(routeError instanceof CliInputError))
+      throw routeError;
+    return failEarly(routeError, undefined, rejectedRouteIdentity(typedParsed));
+  }
+  const definition = commandRegistry.find(parsed.command);
   if (!definition)
     return failEarly(unknownCommandError(command));
+  const identity = usageIdentityFor(typedParsed, route, legacy, definition);
   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);
+    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 ${route?.leaf.path ?? command} --help'.`, "short_flag"), definition, identity);
   }
   if (switchError)
-    return failEarly(switchError, definition);
+    return failEarly(switchError, definition, identity);
+  if (route) {
+    try {
+      assertRoutedFlags(route, typedFlags);
+    } catch (error) {
+      if (!(error instanceof CliInputError))
+        throw error;
+      return failEarly(error, definition, identity);
+    }
+  }
   if (commandFlags.profile === "true" || commandFlags.profile === "") {
-    return failEarly(new CliInputError("--profile needs a value, e.g. --profile=prod.", "List profiles with 'moda profiles list'.", "missing_value:profile"), definition);
+    return failEarly(new CliInputError("--profile needs a value, e.g. --profile=prod.", "List profiles with 'moda profiles list'.", "missing_value:profile"), definition, identity);
   }
   const requestedProfile = commandFlags.profile ?? process.env.MODA_PROFILE?.trim();
   if (requestedProfile && !PROFILE_MANAGING_COMMANDS.has(definition.name)) {
     const known = Object.keys(loadProfileConfig({ env: process.env }).profiles);
     if (!known.includes(requestedProfile)) {
       const source = commandFlags.profile ? `--profile=${requestedProfile}` : `MODA_PROFILE=${requestedProfile}`;
-      return failEarly(new CliInputError(`Moda profile '${requestedProfile}' does not exist (from ${source}), so nothing was run.`, `Known profiles: ${known.join(", ")}. Create it with 'moda profiles create ${requestedProfile}' or fix the name.`, "unknown_profile"), definition);
+      return failEarly(new CliInputError(`Moda profile '${requestedProfile}' does not exist (from ${source}), so nothing was run.`, `Known profiles: ${known.join(", ")}. Create it with 'moda profiles create ${requestedProfile}' or fix the name.`, "unknown_profile"), definition, identity);
     }
     if (commandFlags.profile)
       process.env.MODA_PROFILE = commandFlags.profile;
@@ -5741,47 +6723,45 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
       return latest ? `moda-cli ${VERSION} is out of date (latest ${latest}); commands and flags may differ from the docs. Update: npm install -g @moda-ai/cli@latest` : undefined;
     });
   }
+  const deprecation = legacy && !legacy.silent ? { legacy: `moda ${legacy.legacy}`, use: legacy.use, message: deprecationMessage(legacy) } : undefined;
   const context = createCommandContext(parsed, {
     commandName: definition.name,
     commandFlags,
-    rawFlags: flags,
+    rawFlags: parsed.flags,
     startedAt,
-    outputMode: resolveOutputMode(commandFlags, {
-      isTTY: process.stdout.isTTY,
-      env: process.env
-    })
+    outputMode: outputModeFor(),
+    ...route ? {
+      outputCommand: route.leaf.path,
+      invocation: {
+        command: route.leaf.path,
+        positionals: route.leaf.verb ? typedParsed.positionals.slice(1) : typedParsed.positionals,
+        flags,
+        ...typedParsed.bareFlags ? { bareFlags: typedParsed.bareFlags } : {},
+        routedAs: { command: route.handler, positionals: route.positionals }
+      }
+    } : {},
+    ...deprecation ? { deprecation } : {}
   });
   setActiveContext(context);
-  const telemetryCommand = telemetryCommandName(definition);
-  const telemetrySubcommands = telemetrySubcommandNames(definition);
+  if (deprecation && !context.quiet && (context.outputMode === "human" || context.outputMode === "json")) {
+    safeWriteStderr(`Deprecated: ${deprecation.message}
+`);
+  }
   const needsConfig = typeof definition.validateConfigBeforeRun === "function" ? definition.validateConfigBeforeRun(parsed) : definition.validateConfigBeforeRun;
   if (needsConfig) {
     try {
       validateConfig();
     } catch (error) {
       if (!telemetryDisabled && definition.telemetry === "result-and-error") {
-        const telemetryProfile = existingFlagProfile(commandFlags);
-        sendCliUsageTelemetry({
-          apiKey: resolveApiKey({ profile: telemetryProfile }),
-          profile: telemetryProfile,
-          command: telemetryCommand,
-          flags: commandFlags,
+        reportUsage({
+          definition,
+          identity,
           status: "error",
-          errorType: classifyCliError(error),
-          validationReason: cliValidationReason(error),
+          error,
           exitCode: exitCodeForError(error),
-          durationMs: Date.now() - startedAt,
           apiRequestCount: getApiRequestCount(),
-          adoption: buildSearchAdoptionTelemetry({
-            command: telemetryCommand,
-            positional: parsed.positional,
-            flags: commandFlags,
-            outputMode: context.outputMode,
-            recorded: context.getTelemetryMeta(),
-            skillVersion: process.env.MODA_SKILL_VERSION,
-            subcommands: telemetrySubcommands,
-            defaultSubcommand: definition.defaultSubcommand
-          })
+          outputMode: context.outputMode,
+          recorded: context.getTelemetryMeta()
         });
       }
       if (context.outputMode === "agent" || context.outputMode === "agent-stream" || context.outputMode === "json") {
@@ -5798,26 +6778,15 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
   try {
     const result = await definition.handler(context);
     if (!telemetryDisabled && definition.telemetry !== "none") {
-      const telemetryProfile = existingFlagProfile(commandFlags);
-      sendCliUsageTelemetry({
-        apiKey: result.apiKey ?? resolveApiKey({ profile: telemetryProfile }),
-        profile: telemetryProfile,
-        command: telemetryCommand,
-        flags: commandFlags,
+      reportUsage({
+        definition,
+        identity,
         status: result.exitCode === 0 ? "success" : "error",
         exitCode: result.exitCode,
-        durationMs: Date.now() - startedAt,
+        apiKey: result.apiKey,
         apiRequestCount: getApiRequestCount(),
-        adoption: buildSearchAdoptionTelemetry({
-          command: telemetryCommand,
-          positional: parsed.positional,
-          flags: commandFlags,
-          outputMode: context.outputMode,
-          recorded: context.getTelemetryMeta(),
-          skillVersion: process.env.MODA_SKILL_VERSION,
-          subcommands: telemetrySubcommands,
-          defaultSubcommand: definition.defaultSubcommand
-        })
+        outputMode: context.outputMode,
+        recorded: context.getTelemetryMeta()
       });
     }
     if (!updateCheckDisabled) {
@@ -5825,30 +6794,18 @@ async function dispatchParsedCommandInner(parsed, startedAt) {
     }
     printFeedbackTip(definition.name, context);
     return finishRun(context, { kind: "completed", exitCode: result.exitCode });
-  } catch (error) {
+  } catch (thrown) {
+    const error = route ? renameErrorCommands(thrown, route.renames) : thrown;
     if (!telemetryDisabled && definition.telemetry === "result-and-error") {
-      const telemetryProfile = existingFlagProfile(commandFlags);
-      sendCliUsageTelemetry({
-        apiKey: resolveApiKey({ profile: telemetryProfile }),
-        profile: telemetryProfile,
-        command: telemetryCommand,
-        flags: commandFlags,
+      reportUsage({
+        definition,
+        identity,
         status: "error",
-        errorType: classifyCliError(error),
-        validationReason: cliValidationReason(error),
+        error,
         exitCode: exitCodeForError(error),
-        durationMs: Date.now() - startedAt,
         apiRequestCount: getApiRequestCount(),
-        adoption: buildSearchAdoptionTelemetry({
-          command: telemetryCommand,
-          positional: parsed.positional,
-          flags: commandFlags,
-          outputMode: context.outputMode,
-          recorded: context.getTelemetryMeta(),
-          skillVersion: process.env.MODA_SKILL_VERSION,
-          subcommands: telemetrySubcommands,
-          defaultSubcommand: definition.defaultSubcommand
-        })
+        outputMode: context.outputMode,
+        recorded: context.getTelemetryMeta()
       });
     }
     if (context.outputMode === "agent" || context.outputMode === "agent-stream" || context.outputMode === "json") {