@moda-ai/cli 1.55.25 → 1.55.27

package/dist/{production-intelligence-c8e0xw3n.js → production-intelligence-7nqddd4f.js}

@@ -1,6 +1,12 @@
 import {
-  INTELLIGENCE_SCHEMA_VERSION
-} from "./cli-bb7133m7.js";
+  INTELLIGENCE_SCHEMA_VERSION,
+  asNumber,
+  asRecord,
+  asString,
+  contextTarget,
+  frustrationAnchorIndex,
+  frustrationsFromEmotions
+} from "./cli-vdkwkkp5.js";
 import {
   renderMarkdownForTerminal,
   shouldColorTerminalOutput,
@@ -10,25 +16,20 @@ import {
 import {
   callControlAPI,
   callDataAPI
-} from "./cli-9btx12wp.js";
+} from "./cli-pg5qfmqc.js";
 import {
   CliAuthError,
   CliInputError,
   EXIT_DEGRADED,
   EXIT_OK,
+  apiErrorStatus,
   apiKeyHeaders,
-  asNumber,
-  asRecord,
-  asString,
-  contextTarget,
-  frustrationAnchorIndex,
-  frustrationsFromEmotions,
   recordApiRequest,
   resolveApiKey,
   resolveModaBaseUrl,
   safeWriteStderr,
-  shellWord
-} from "./cli-dve50x7p.js";
+  shellArg
+} from "./cli-r5pp7qny.js";
 import"./cli-0v6na3yp.js";
 
 // src/production-intelligence.ts
@@ -406,6 +407,9 @@ var OVERVIEW_SCHEMA_VERSION = "production_overview.v0.1";
 var ASK_SCHEMA_VERSION = "production_ask.v0.1";
 var INVESTIGATION_PROBLEM_LIMIT = 3;
 var INVESTIGATION_PROBLEM_SLOTS = INVESTIGATION_PROBLEM_LIMIT;
+function isAuthFailure(error) {
+  return error instanceof CliAuthError || apiErrorStatus(error) === 401;
+}
 async function runProductionCommand(context) {
   const daysBack = daysBackFlag(context.flags);
   if (context.command === "overview") {
@@ -419,7 +423,8 @@ async function runProductionCommand(context) {
       if (!context.quiet)
         console.log(renderOverviewBriefingHuman(briefing));
     } else {
-      context.output.writeData(briefing, overviewAgentOptions(briefing));
+      const { rawOverview: _rawOverview, ...withoutRaw } = briefing;
+      context.output.writeData(withoutRaw, overviewAgentOptions(briefing));
     }
     return { exitCode: 0 };
   }
@@ -448,7 +453,7 @@ async function runProductionCommand(context) {
       toolName: context.flags.tool
     });
     writeInvestigation(context, investigation);
-    return { exitCode: 0 };
+    return { exitCode: investigation.degraded ? EXIT_DEGRADED : EXIT_OK };
   }
   if (context.command === "investigate") {
     const investigation = await investigateProduction({
@@ -458,7 +463,7 @@ async function runProductionCommand(context) {
       toolName: context.flags.tool
     });
     writeInvestigation(context, investigation);
-    return { exitCode: 0 };
+    return { exitCode: investigation.degraded ? EXIT_DEGRADED : EXIT_OK };
   }
   throw new CliInputError(`Unknown production command '${context.command}'`);
 }
@@ -522,11 +527,18 @@ async function investigateProduction(options) {
     if (result.warning)
       warnings.push(result.warning);
   }
+  const failed = Object.entries(sources).filter(([, result]) => result.status === "unavailable");
+  const authFailure = failed.find(([, result]) => isAuthFailure(result.error));
+  if (authFailure)
+    throw authFailure[1].error;
+  if (failed.length > 0 && failed.length === Object.keys(sources).length)
+    throw failed[0][1].error;
+  const failedSources = failed.map(([key]) => key);
   if (options.toolName && tools.status === "ok" && toolRows(tools.data, options.toolName).every((row) => row.count <= 0)) {
     warnings.push(`No failures found for tool "${options.toolName}" in the last ${options.daysBack} day(s) — the tool may have no failures in this window, or the name may not exist in this tenant. ` + "Run `moda detections tools` to list tools with recorded failures, or widen --days-back.");
   }
   if (options.conversationId) {
-    warnings.push(`Scoped to trace ${options.conversationId} for frustration evidence only; overview and tool failures are tenant-wide. ` + `Open the trace itself with \`moda traces spans ${options.conversationId}\`.`);
+    warnings.push(`Scoped to trace ${options.conversationId} for frustration evidence only; overview and tool failures are tenant-wide. ` + `Open the trace itself with \`moda traces spans ${shellArg(options.conversationId)}\`.`);
   }
   const evidenceRefs = [];
   const findings = [];
@@ -537,12 +549,17 @@ async function investigateProduction(options) {
     findings.push(...problemFindings(problems.data, options.daysBack, evidenceRefs));
   }
   if (findings.length === 0) {
-    findings.push(insufficientDataFinding(overview.data, evidenceRefs));
+    findings.push(failedSources.length > 0 ? incompleteDataFinding(failedSources, Object.keys(sources).length) : insufficientDataFinding(overview.data, evidenceRefs));
   }
   findings.sort(compareFindings);
   const boundedFindings = capFindings(findings, 8, INVESTIGATION_PROBLEM_SLOTS);
   const nextCommands = nextCommandsForFindings(boundedFindings, options.daysBack, !options.failureOnly);
   const summary = summarizeInvestigation(boundedFindings);
+  if (failedSources.length > 0) {
+    summary.text = `Incomplete: could not load ${failedSources.join(", ")}, so findings cover only ${Object.keys(sources).filter((key) => !failedSources.includes(key)).join(", ")}. ${summary.text}`;
+    if (summary.confidence === "high" || summary.confidence === "medium")
+      summary.confidence = "low";
+  }
   if (options.conversationId) {
     summary.text = `${summary.text} (Only frustration evidence is scoped to trace ${options.conversationId}.)`;
   }
@@ -560,7 +577,9 @@ async function investigateProduction(options) {
     evidenceRefs: uniqueEvidenceRefs(evidenceRefs),
     nextCommands,
     warnings,
-    sourceStatus
+    sourceStatus,
+    degraded: failedSources.length > 0,
+    failedSources
   };
 }
 async function askModa(options) {
@@ -592,8 +611,8 @@ async function askModa(options) {
     cwd: options.cwd,
     question: options.question
   });
-  const top = investigation.findings[0];
-  const answer = top ? `Moda Cloud intelligence is not available, so I synthesized this from production evidence. The strongest signal is: ${top.title}. ${top.summary}` : "Moda Cloud intelligence is not available, and the local Data API evidence did not contain a strong production signal.";
+  const top = investigation.findings.find((finding) => finding.kind !== "insufficient_data");
+  const answer = top ? `Moda Cloud intelligence is not available, so I synthesized this from production evidence${investigation.degraded ? ` (${investigation.failedSources.join(", ")} could not be loaded)` : ""}. The strongest signal is: ${top.title}. ${top.summary}` : investigation.degraded ? `Moda Cloud intelligence is not available, and ${investigation.failedSources.join(", ")} could not be loaded, so no answer could be synthesized and no issue is ruled out.` : "Moda Cloud intelligence is not available, and the local Data API evidence did not contain a strong production signal.";
   const confidence = capFallbackConfidence(investigation.summary.confidence);
   const evidenceRefs = investigation.evidenceRefs.slice(0, 12);
   const findings = investigation.findings.slice(0, 5);
@@ -717,9 +736,16 @@ function writeInvestigation(context, investigation) {
   if (context.outputMode === "human") {
     if (!context.quiet)
       console.log(renderInvestigationHuman(investigation));
+    if (investigation.degraded) {
+      safeWriteStderr(`Warning: incomplete result, could not load ${investigation.failedSources.join(", ")}.
+`);
+    }
     return;
   }
-  context.output.writeData(investigation, investigationAgentOptions(investigation));
+  context.output.writeData(investigation, {
+    ...investigationAgentOptions(investigation),
+    ...investigation.degraded ? { status: "degraded" } : {}
+  });
 }
 async function safeData(endpoint) {
   try {
@@ -728,7 +754,8 @@ async function safeData(endpoint) {
     return {
       data: null,
       status: "unavailable",
-      warning: `Could not load ${endpoint}: ${error instanceof Error ? error.message : String(error)}`
+      warning: `Could not load ${endpoint}: ${error instanceof Error ? error.message : String(error)}`,
+      error
     };
   }
 }
@@ -817,7 +844,7 @@ function toolFailureFindings(data, daysBack, hints, evidenceRefs, scopedTool) {
       label: `${name}: ${count} failure(s)${subtype}`,
       endpoint: scopedTool ? `/tool-failures/${encodeURIComponent(name)}?days_back=${daysBack}` : `/tool-failures?days_back=${daysBack}`,
       toolName: name,
-      value: tool.raw
+      value: { tool_name: name, failure_count: count, conversation_count: tool.conversations, ...tool.subtype ? { subtype: tool.subtype } : {} }
     });
     const location = likelyToolLocation(name, hints);
     if (location?.path) {
@@ -845,7 +872,7 @@ function toolFailureFindings(data, daysBack, hints, evidenceRefs, scopedTool) {
         id: `action_tool_detail_${slug(name)}`,
         title: `Inspect ${name} failure examples.`,
         rationale: "Examples include trace anchors and error subtypes.",
-        command: `moda detections tools ${name} --days-back=${daysBack} --include-window`,
+        command: `moda detections tools ${shellArg(name)} --days-back=${daysBack} --include-window`,
         mutability: "read",
         requiresApproval: false
       }]
@@ -874,7 +901,7 @@ function frustrationFindings(data, daysBack, evidenceRefs) {
     label: quote ? `Frustration anchor: "${quote}"` : `${count} frustrated trace(s)`,
     endpoint: investigateFrustrationsEndpoint(daysBack),
     ...conversationId ? { conversationId } : {},
-    value: first ?? summary ?? data
+    value: first ? frustrationEvidenceIds(first, anchorIndex) : { frustrated_count: count, at_risk_count: atRisk }
   });
   return [{
     id: "finding_frustration_rate",
@@ -891,12 +918,23 @@ function frustrationFindings(data, daysBack, evidenceRefs) {
       id: "action_frustration_window",
       title: "Read the frustration window.",
       rationale: "The user quote and nearby turns reveal what confused or blocked the user.",
-      command: conversationId ? `moda traces get ${shellWord(contextTarget(conversationId))}${anchorIndex !== null ? ` --msg-index=${anchorIndex}` : ""} --window=3` : `moda detections list --family=frustration --days-back=${daysBack} --include-window`,
+      command: conversationId ? `moda traces get ${shellArg(contextTarget(conversationId))}${anchorIndex !== null ? ` --msg-index=${anchorIndex}` : ""} --window=3` : `moda detections list --family=frustration --days-back=${daysBack} --include-window`,
       mutability: "read",
       requiresApproval: false
     }]
   }];
 }
+function frustrationEvidenceIds(row, anchorIndex) {
+  const ids = {};
+  for (const key of ["detection_id", "conversation_id", "trace_id", "user_id"]) {
+    const value = asString(row[key]);
+    if (value)
+      ids[key] = value;
+  }
+  if (anchorIndex !== null)
+    ids.msg_index = anchorIndex;
+  return ids;
+}
 function problemRows(data) {
   const record = asRecord(data);
   const rows = [];
@@ -938,7 +976,7 @@ function problemFindings(data, daysBack, evidenceRefs) {
       kind: "problem",
       label: `Problem "${problem.name}" (${trustNote})`,
       endpoint: `/problems?days_back=${daysBack}&limit=${INVESTIGATION_PROBLEM_LIMIT}`,
-      value: problem.raw
+      value: { problem_id: problem.id, lifecycle: problem.lifecycle, trust: problem.trust, affected_conversations: problem.affectedConversations }
     });
     const affected = problem.affectedConversations;
     return {
@@ -956,7 +994,7 @@ function problemFindings(data, daysBack, evidenceRefs) {
         id: `action_problem_${slug(problem.id)}`,
         title: `Open the Problem dossier for ${problem.name}.`,
         rationale: "The dossier has the cause, evidence, affected traces and verification state.",
-        command: `moda problems get ${problem.id}`,
+        command: `moda problems get ${shellArg(problem.id)}`,
         mutability: "read",
         requiresApproval: false
       }]
@@ -971,7 +1009,7 @@ function insufficientDataFinding(overview, evidenceRefs) {
       kind: "data_api",
       label: "Overview did not contain actionable production signals",
       endpoint: "/overview",
-      value: overview
+      value: overviewMetrics(overview)
     });
   }
   return {
@@ -995,6 +1033,28 @@ function insufficientDataFinding(overview, evidenceRefs) {
     }]
   };
 }
+function incompleteDataFinding(failedSources, total) {
+  return {
+    id: "finding_incomplete_data",
+    kind: "insufficient_data",
+    title: `Could not check ${failedSources.join(", ")} (${failedSources.length} of ${total} sources failed)`,
+    severity: "info",
+    confidence: "low",
+    impactScore: 10,
+    rankReason: "The sources that loaded show no ranked issue, but the failed ones were not checked.",
+    summary: "This is not evidence that production is healthy; re-run once the failed sources load (see warnings).",
+    evidenceRefIds: [],
+    likelyLocations: [],
+    recommendedActions: [{
+      id: "action_doctor_online",
+      title: "Check connectivity and the API key.",
+      rationale: "Failed reads usually mean a network, server, or credential problem.",
+      command: "moda doctor --online",
+      mutability: "read",
+      requiresApproval: false
+    }]
+  };
+}
 function normalizeCloudAsk(response, question) {
   const record = asRecord(response);
   const answer = asString(record?.answer);

package/dist/{profile-commands-6e2dgv72.js → profile-commands-49yn02yg.js}

@@ -2,7 +2,7 @@ import {
   probeApiKey,
   redactApiKey,
   resolveApiKeyCredential
-} from "./cli-9hc5bg2r.js";
+} from "./cli-ccjfwzqx.js";
 import {
   authFetch,
   clearAuthSession,
@@ -10,7 +10,7 @@ import {
   loadAuthSession,
   login,
   revokeCliSessionToken
-} from "./cli-0wr3483h.js";
+} from "./cli-hmjdgxrn.js";
 import {
   CliInputError,
   DEFAULT_INGEST_URL,
@@ -34,8 +34,9 @@ import {
   saveCliConfig,
   secretFilePathFromRef,
   setActiveProfile,
+  shellArg,
   upsertProfile
-} from "./cli-dve50x7p.js";
+} from "./cli-r5pp7qny.js";
 import"./cli-0v6na3yp.js";
 
 // src/profile-commands.ts
@@ -326,7 +327,7 @@ async function runProfilesCommand(context) {
         default_profile: config.active_profile,
         profiles: Object.values(config.profiles).map((profile) => serializeProfile(profile, effective)),
         migrations: config.migrations
-      }, missing ? { warnings: [`The active profile '${effective}' (from ${source}) does not exist. Create it with \`moda profiles create ${effective}\` or select an existing profile.`] } : undefined);
+      }, missing ? { warnings: [`The active profile '${effective}' (from ${source}) does not exist. Create it with \`moda profiles create ${shellArg(effective)}\` or select an existing profile.`] } : undefined);
       return { exitCode: 0 };
     }
     case "use": {

package/dist/prompt-source-mcp.js

@@ -5,12 +5,12 @@ import {
   inspectCodeSelectors,
   inspectPythonSelectors,
   safePromptEvidencePath
-} from "./cli-7xc585hc.js";
+} from "./cli-qwgct6x7.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-v8q7sd7g.js";
+import"./cli-wzds257x.js";
+import"./cli-pg5qfmqc.js";
+import"./cli-r5pp7qny.js";
 import {
   __commonJS,
   __toESM

package/dist/{prompts-3h5jcjrw.js → prompts-17wyrst6.js}

@@ -11,16 +11,16 @@ import {
   runPromptSync,
   runPromptsCommand,
   writePromptSyncProgress
-} from "./cli-m805msp6.js";
+} from "./cli-q9nsvqqg.js";
 import {
   promptSourceHashPayload
 } from "./cli-mm48br00.js";
-import"./cli-7xc585hc.js";
+import"./cli-qwgct6x7.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-v8q7sd7g.js";
+import"./cli-wzds257x.js";
+import"./cli-pg5qfmqc.js";
+import"./cli-r5pp7qny.js";
 import"./cli-0v6na3yp.js";
 export {
   writePromptSyncProgress,

package/dist/{provision-q86phh4a.js → provision-bc3h68e1.js}

@@ -1,18 +1,18 @@
 import {
   selectTenantAndCreateKey
-} from "./cli-qycsmxev.js";
-import"./cli-9hc5bg2r.js";
+} from "./cli-0pkc8jhg.js";
+import"./cli-ccjfwzqx.js";
 import {
   loadAuthSession
-} from "./cli-0wr3483h.js";
+} from "./cli-hmjdgxrn.js";
 import {
   stringOption
-} from "./cli-qvg26twp.js";
+} from "./cli-v8q7sd7g.js";
 import {
   CliAuthError,
   resolveIngestUrl,
   resolveModaBaseUrl
-} from "./cli-dve50x7p.js";
+} from "./cli-r5pp7qny.js";
 import"./cli-0v6na3yp.js";
 
 // src/provision.ts

package/dist/{registry-s2vdsfw8.js → registry-fpzhjznj.js}

@@ -1,14 +1,14 @@
 import {
   assertFlags
-} from "./cli-dn91fb56.js";
+} from "./cli-wzds257x.js";
 import {
   callControlAPI
-} from "./cli-9btx12wp.js";
+} from "./cli-pg5qfmqc.js";
 import {
   CliInputError,
   explicitOutputMode,
   resolveApiKey
-} from "./cli-dve50x7p.js";
+} from "./cli-r5pp7qny.js";
 import"./cli-0v6na3yp.js";
 
 // src/registry.ts

package/dist/{skills-vq3njc8a.js → skills-ccdbqghj.js}

@@ -3,11 +3,11 @@ import {
   pullSkills,
   runSkillSync,
   runSkillsCommand
-} from "./cli-m0045npe.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+} from "./cli-6et4z504.js";
+import"./cli-v8q7sd7g.js";
+import"./cli-wzds257x.js";
+import"./cli-pg5qfmqc.js";
+import"./cli-r5pp7qny.js";
 import"./cli-8dtnwp9r.js";
 import"./cli-0v6na3yp.js";
 export {

package/dist/{sync-hq9dpqpr.js → sync-hkxce5zh.js}

@@ -1,20 +1,20 @@
 import {
   runPromptsCommand
-} from "./cli-m805msp6.js";
+} from "./cli-q9nsvqqg.js";
 import"./cli-mm48br00.js";
 import {
   runHarnessCommand
-} from "./cli-7xc585hc.js";
+} from "./cli-qwgct6x7.js";
 import"./cli-97fnztpy.js";
 import {
   runSkillsCommand
-} from "./cli-m0045npe.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
+} from "./cli-6et4z504.js";
+import"./cli-v8q7sd7g.js";
+import"./cli-wzds257x.js";
+import"./cli-pg5qfmqc.js";
 import {
   CliInputError
-} from "./cli-dve50x7p.js";
+} from "./cli-r5pp7qny.js";
 import"./cli-8dtnwp9r.js";
 import"./cli-0v6na3yp.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.55.25",
+  "version": "1.55.27",
   "description": "CLI for Moda: production monitoring and evals for AI agents.",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-10-15T20:30:38.730Z",
-  "cli_version": "1.55.25",
+  "bundled_at": "2026-10-15T21:22:44.784Z",
+  "cli_version": "1.55.27",
   "skills": [
     {
       "id": "integration-cloudflare-think",

package/skills/moda-cli/SKILL.md

@@ -95,7 +95,10 @@ More: `references/production-intelligence.md`.
   indexes when you report.
 - Never run writes (`problems feedback`, `review`,
   `signals create|update|...`, `prompts sync|promote|ab`, `registry push`)
-  unless the user asked. Use `--dry-run` where a command offers it.
+  unless the user asked. Preview with `--dry-run` (every write except
+  `prompts promote|ab|propose` takes it): it validates and applies nothing.
+  Most writes print the exact request and a `next_commands` entry that runs
+  it for real (see `references/output-protocol.md`).
 - An empty result in a window means "nothing in that window". Widen the window
   once before saying something never happened.
 - Batch reads instead of looping one id per call: `moda traces get` and

package/skills/moda-cli/references/dashboard-parity.md

@@ -5,7 +5,7 @@ Loaded on demand from the moda-cli skill.
 ### 10. Everything the dashboard does, from the CLI
 
 Every command below needs only an API key, and the tenant comes from the key.
-Writes listed here accept `--dry-run` (prints the exact request, sends nothing) except `problems feedback`, `review`, `problems link`, and `prompts promote|ab|propose`. Those refuse `--dry-run` before sending anything, so run them only when you mean it.
+Writes listed here accept `--dry-run`: it validates the call, prints the exact request (method, endpoint, body) and sends nothing, and its `next_commands` entry is the command that sends it for real (`mutability: write`, `requires_approval: true`). That covers `problems feedback|reopen|link`, `review`, `feedback` and the `signals` writes. `prompts promote|ab|propose` refuse `--dry-run` before sending anything, so run them only when you mean it.
 
 | Dashboard | CLI |
 |---|---|

package/skills/moda-cli/references/output-protocol.md

@@ -40,7 +40,7 @@ Branch on the exit code; it is stable and cheaper than parsing the payload:
 |---|---|---|
 | `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
 | `1` | error — bad input, unknown id (`not_found`), access denied, API/network failure | Read `errors[0].code`; retry only `network_error` / 5xx `api_error`. For `not_found`, find a valid id first (the `cause` names the command). |
-| `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
+| `3` | degraded — Moda Cloud was unavailable and the answer was synthesized from local Data API evidence (`ask`), or some sources failed to load (`investigate`/`failures`, named in `data.failedSources`) | Answer is present but lower-trust or partial; verify before acting, and never read a partial result as "no issues". |
 | `4` | auth required — no API key, or the API rejected it (HTTP 401) | Set `MODA_API_KEY` or run the `login_command` from the `auth` payload (`moda auth login --api-key`), then re-run. |
 | `5` | input required — a choice is needed that the non-interactive run could not answer | Pick a choice from the `input_request` payload and re-invoke the same command with that choice's `resume_flags` appended. |
 | `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
@@ -195,17 +195,42 @@ Treat an answer as degraded if **any** of these hold:
   that text stays whole, and the error message says whether `data` is whole
   or bounded with its complete copy at `truncation.data.full_output_path`.
   You can also page with a smaller `--limit` and
-  `--offset`, or rerun with `--json` (no byte limit).
+  `--offset`, or rerun with `--json` (no byte limit). Commands that read
+  per-row extras (`--include-window`, `--include-world-state`, batch reads)
+  stop reading once the budget is spent; rows they did not enrich carry
+  `window_skipped` / `world_state_skipped: "agent_output_budget"`.
+- **`--json` is compact when piped.** `--json` prints one line of JSON when
+  stdout is not a terminal (indented on a terminal); `--pretty` indents it
+  anyway. `--json` prints the payload as read: `--profile` is stamped only on
+  the agent envelope's generated commands (`next_commands`, `*_command`
+  fields), never on trace content.
 - **Unknown flags fail.** A flag the command doesn't take (a typo, or a
   filter it lacks) exits `1` with the valid flag list and a "did you mean",
-  instead of being silently ignored. Stray arguments on commands that take
-  none fail the same way.
-- **`--dry-run` is only accepted where it's implemented** (for example
-  `registry push`, `harness sync|delete|register`, `prompts sync|decide`,
-  `skills sync|policy`, `signals` write subcommands, `problem-reopen`;
-  `moda <command> --help` says whether a command takes it). Anywhere else it fails **before
-  anything is sent**. It is never silently ignored, so a "preview" can't
-  perform a real write.
+  instead of being silently ignored. So does a flag the chosen mode would
+  not send (`moda signal <id> --limit=3` without `--detections`).
+- **`--days-back` and `--days_back` are the same flag.** Every flag is read
+  under its kebab-case name whichever spelling you type.
+- **A value flag needs a value.** `--user-id` with nothing after it (often an
+  empty shell variable) exits `1` naming the flag instead of sending the
+  string "true". Switches such as `--include-tool-io` stay bare.
+- **Numbers are plain decimal integers.** `--limit=0x10`, `--limit=1e1` and
+  `--limit=2.5` fail; text flags keep their text (`--search=404` searches
+  for "404").
+- **Extra words fail.** A command that takes one id rejects a second word
+  instead of ignoring it. Free text joins every word: `moda traces search
+  refund not processed` searches "refund not processed" (same for `ask` and
+  `feedback`).
+- **Writes take `--dry-run`** (`prompts promote|ab|propose` excepted).
+  - `problems feedback|reopen|link`, `review`, `feedback`, `signals` writes
+    and `skills policy` validate fully, send nothing, and return
+    `data.planned` (method, endpoint, body) plus a `next_commands` entry
+    that runs the write for real (`requires_approval: true`).
+  - `registry push`, `harness sync|delete|register`, `prompts sync|decide`
+    and `skills sync` return their own preview. Some ask the server to
+    compute it (`skills sync --dry-run` sends the local skills marked
+    `dryRun: true`), but none of them applies a change.
+  - A read refuses `--dry-run` **before anything is sent**, so a "preview"
+    can't perform a real write.
 - **Unknown profiles fail.** `--profile=<name>` or `MODA_PROFILE` naming a
   profile that doesn't exist exits `1` instead of falling back to another
   profile's key and tenant. Time windows differ by command (below).

package/skills/moda-cli/references/search-and-traces.md

@@ -110,7 +110,16 @@ moda traces get <conversation_id> --all --from=500 --max-messages=500  # continu
 ```
 
 `--all` returns `has_more`/`next_from`; when it stops at the cap, the warning
-prints the exact `--from` command to continue.
+prints the exact `--from` command to continue. In agent output `--all` reads
+only about what fits the byte budget (a ~50-message first page), so
+`returned` can be well under `--max-messages`; follow `next_from`.
+
+A window over the agent byte budget is cut around its anchor, never past it:
+the requested message is always returned, the rest are kept nearest-first on
+both sides, `context.from_index`/`to_index` describe what was returned
+(`requested_from_index`/`requested_to_index` and `omitted_for_byte_limit`
+what was asked for), and `next_commands` has an `--all --from` command for
+each side that lost messages.
 
 **Several traces? Batch them in one call instead of looping `moda traces get`
 per id.** Pass up to 25 targets as positionals or one per line with
@@ -130,7 +139,9 @@ plus `succeeded`/`failed` counts. A missing trace is a per-item
 `error.code: "not_found"`, not a failed call; the exit code is 1 only when
 every target failed. When the agent byte budget would overflow, the items that
 fit are returned and `remaining_targets` plus a `next_commands` entry read the
-rest. One positional id keeps the single-trace output above.
+rest. Agent output stops reading targets once the budget is spent, so the
+targets it names were not read yet (nothing is read and then dropped). One
+positional id keeps the single-trace output above.
 
 `moda traces get` returns messages whole, with their tool calls and results. An
 older Moda server cuts message text, tool inputs, and tool results at 500
@@ -148,6 +159,7 @@ moda traces spans <conversation_id> --include-raw    # attach verbatim raw_event
 moda traces spans <conversation_id> --include-bodies # keep prompt/response/attribute bodies
 moda traces spans <conversation_id> --limit=1000     # ingest rows to read (default 200, max 1000)
 moda traces spans <conversation_id> --cursor=<next_cursor>  # next page of a capped audit
+moda traces spans <conversation_id> --cursor=<c> --span-offset=N  # rest of a page cut for the agent budget
 moda traces spans <id1> <id2> <id3>                  # batch: up to 25 ids, one envelope
 ```
 
@@ -162,6 +174,12 @@ A full `--limit` page of ingest rows, the server's ~3 MB response budget
 (`summary.truncated_reason: "byte_limit"`) or a span cap sets both, and a
 warning plus `next_commands` give the follow-up — usually the `--cursor=` page
 from `next_cursor`; for very large traces audit one OTLP trace at a time
+(see below). In agent output a page over the byte budget (the server's
+smallest page, 32 KiB, is over the 24,000-byte default) keeps the most spans
+that fit: `span_offset`/`next_span_offset`/`page_spans` say which,
+`next_cursor` is `null` until the last spans of the page are read, and
+`next_commands` has the `--span-offset=N` command that reads the rest of the
+same page. Following `next_commands` never skips a span;
 (`summary.trace_ids`, `--kind=trace`). Prompt/response bodies are omitted by
 default (`{"omitted": true, "original_bytes": N}`); `--include-bodies` keeps
 them, cutting strings over 8 KB to `{"truncated": true, "original_bytes": N,