@moda-ai/cli 1.55.25 → 1.55.26

package/dist/{doctor-q21mr5ya.js → doctor-w913fj4g.js}

@@ -3,16 +3,16 @@ import {
   promptsDiscoveredCheck,
   runDoctorCommand,
   runStatusCommand
-} from "./cli-mebf5vtr.js";
-import"./cli-0wr3483h.js";
-import"./cli-m805msp6.js";
+} from "./cli-5g1tv80h.js";
+import"./cli-q6f6vrrr.js";
+import"./cli-b4740tnv.js";
 import"./cli-mm48br00.js";
-import"./cli-7xc585hc.js";
+import"./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
+import"./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 export {
   runStatusCommand,

package/dist/{fix-0qdtdz5h.js → fix-crkwdkt4.js}

@@ -2,17 +2,17 @@ import {
   DEFAULT_POLL_INTERVAL_MS,
   DEFAULT_WAIT_TIMEOUT_MS,
   fetchLatestRun
-} from "./cli-m805msp6.js";
+} from "./cli-b4740tnv.js";
 import"./cli-mm48br00.js";
-import"./cli-7xc585hc.js";
+import"./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
+import"./cli-cdrvjva5.js";
 import {
   assertFlags
-} from "./cli-dn91fb56.js";
+} from "./cli-jgfm7w1r.js";
 import {
   callControlAPI
-} from "./cli-9btx12wp.js";
+} from "./cli-jtyvbd8d.js";
 import {
   CliInputError,
   EXIT_DEGRADED,
@@ -21,7 +21,7 @@ import {
   getModaPaths,
   resolveApiTenantId,
   validateConfig
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 
 // src/fix.ts

package/dist/{harness-github-actions-atc5bbkj.js → harness-github-actions-fjhvhgpj.js}

@@ -1,13 +1,13 @@
 import {
   buildSourceSnapshot
-} from "./cli-7xc585hc.js";
+} from "./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
 import {
   recordApiRequest
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 
 // src/harness-github-actions.ts

package/dist/{harness-vzy7n7ea.js → harness-x3e7d68b.js}

@@ -42,12 +42,12 @@ import {
   writeHarnessAnalyzeResult,
   writeHarnessArtifacts,
   writeHumanProgress
-} from "./cli-7xc585hc.js";
+} from "./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
+import"./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 export {
   writeHumanProgress,

package/dist/{index-4b1ybz51.js → index-2kf3fnnb.js}

@@ -1,21 +1,21 @@
 import {
   selectTenantAndCreateKey
-} from "./cli-qycsmxev.js";
-import"./cli-9hc5bg2r.js";
+} from "./cli-k6q8dbpk.js";
+import"./cli-1mbb0ct0.js";
 import {
   buildDoctorReport
-} from "./cli-mebf5vtr.js";
+} from "./cli-5g1tv80h.js";
 import {
   ConnectCodeError,
   connectWithCode,
   loadAuthSession,
   loadToken,
   login
-} from "./cli-0wr3483h.js";
+} from "./cli-q6f6vrrr.js";
 import {
   initPrompts,
   runPromptSync
-} from "./cli-m805msp6.js";
+} from "./cli-b4740tnv.js";
 import"./cli-mm48br00.js";
 import {
   canonicalText,
@@ -35,7 +35,7 @@ import {
   runCodingAgent,
   runHarnessCommand,
   startRemoteAnalyze
-} from "./cli-7xc585hc.js";
+} from "./cli-d577kq6h.js";
 import {
   stripAnsi
 } from "./cli-97fnztpy.js";
@@ -47,12 +47,12 @@ import {
 import {
   agentsMdProblem,
   runSkillSync
-} from "./cli-m0045npe.js";
+} from "./cli-8tfk8qeb.js";
 import {
   createCommandContext
-} from "./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
+} from "./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
 import {
   CliAuthError,
   CliInputError,
@@ -60,7 +60,7 @@ import {
   recordApiRequest,
   resolveIngestUrl,
   resolveModaBaseUrl
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.js";
 import {
   detectAgents,
   installRules,

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

@@ -10,12 +10,13 @@ import {
 import {
   callControlAPI,
   callDataAPI
-} from "./cli-9btx12wp.js";
+} from "./cli-jtyvbd8d.js";
 import {
   CliAuthError,
   CliInputError,
   EXIT_DEGRADED,
   EXIT_OK,
+  apiErrorStatus,
   apiKeyHeaders,
   asNumber,
   asRecord,
@@ -28,7 +29,7 @@ import {
   resolveModaBaseUrl,
   safeWriteStderr,
   shellWord
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.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,6 +527,13 @@ 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.");
   }
@@ -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) {
@@ -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",
@@ -897,6 +924,17 @@ function frustrationFindings(data, daysBack, evidenceRefs) {
     }]
   }];
 }
+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 {
@@ -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-ct2t0bfr.js}

@@ -2,7 +2,7 @@ import {
   probeApiKey,
   redactApiKey,
   resolveApiKeyCredential
-} from "./cli-9hc5bg2r.js";
+} from "./cli-1mbb0ct0.js";
 import {
   authFetch,
   clearAuthSession,
@@ -10,7 +10,7 @@ import {
   loadAuthSession,
   login,
   revokeCliSessionToken
-} from "./cli-0wr3483h.js";
+} from "./cli-q6f6vrrr.js";
 import {
   CliInputError,
   DEFAULT_INGEST_URL,
@@ -35,7 +35,7 @@ import {
   secretFilePathFromRef,
   setActiveProfile,
   upsertProfile
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 
 // src/profile-commands.ts

package/dist/prompt-source-mcp.js

@@ -5,12 +5,12 @@ import {
   inspectCodeSelectors,
   inspectPythonSelectors,
   safePromptEvidencePath
-} from "./cli-7xc585hc.js";
+} from "./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
+import"./cli-sqsjd08w.js";
 import {
   __commonJS,
   __toESM

package/dist/{prompts-3h5jcjrw.js → prompts-92aqqb2k.js}

@@ -11,16 +11,16 @@ import {
   runPromptSync,
   runPromptsCommand,
   writePromptSyncProgress
-} from "./cli-m805msp6.js";
+} from "./cli-b4740tnv.js";
 import {
   promptSourceHashPayload
 } from "./cli-mm48br00.js";
-import"./cli-7xc585hc.js";
+import"./cli-d577kq6h.js";
 import"./cli-97fnztpy.js";
-import"./cli-qvg26twp.js";
-import"./cli-dn91fb56.js";
-import"./cli-9btx12wp.js";
-import"./cli-dve50x7p.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
+import"./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 export {
   writePromptSyncProgress,

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

@@ -1,18 +1,18 @@
 import {
   selectTenantAndCreateKey
-} from "./cli-qycsmxev.js";
-import"./cli-9hc5bg2r.js";
+} from "./cli-k6q8dbpk.js";
+import"./cli-1mbb0ct0.js";
 import {
   loadAuthSession
-} from "./cli-0wr3483h.js";
+} from "./cli-q6f6vrrr.js";
 import {
   stringOption
-} from "./cli-qvg26twp.js";
+} from "./cli-cdrvjva5.js";
 import {
   CliAuthError,
   resolveIngestUrl,
   resolveModaBaseUrl
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.js";
 import"./cli-0v6na3yp.js";
 
 // src/provision.ts

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

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

package/dist/{skills-vq3njc8a.js → skills-2mbsj9bt.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-8tfk8qeb.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
+import"./cli-sqsjd08w.js";
 import"./cli-8dtnwp9r.js";
 import"./cli-0v6na3yp.js";
 export {

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

@@ -1,20 +1,20 @@
 import {
   runPromptsCommand
-} from "./cli-m805msp6.js";
+} from "./cli-b4740tnv.js";
 import"./cli-mm48br00.js";
 import {
   runHarnessCommand
-} from "./cli-7xc585hc.js";
+} from "./cli-d577kq6h.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-8tfk8qeb.js";
+import"./cli-cdrvjva5.js";
+import"./cli-jgfm7w1r.js";
+import"./cli-jtyvbd8d.js";
 import {
   CliInputError
-} from "./cli-dve50x7p.js";
+} from "./cli-sqsjd08w.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.26",
   "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:00:31.183Z",
+  "cli_version": "1.55.26",
   "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).