@xerg/cli 0.4.0 → 0.5.1

package/dist/index.js

@@ -1280,6 +1280,7 @@ function hydrateAuditSummary(summary) {
     opportunityByKind: summary.opportunityByKind?.length > 0 ? summary.opportunityByKind : buildTaxonomyBuckets(summary.findings, "opportunity"),
     spendByDay: summary.spendByDay ?? [],
     wasteByDay: summary.wasteByDay ?? [],
+    recommendations: summary.recommendations ?? [],
     notes: summary.notes ?? [],
     pricingCoverage: summary.pricingCoverage ?? null,
     cursorUsage: summary.cursorUsage ?? null
@@ -1416,6 +1417,7 @@ function buildCursorUsageFindings(runs) {
       summary,
       scope: "global",
       scopeId: "all",
+      scopeLabel: "Cursor usage",
       costImpactUsd: cacheImpactUsd,
       details: {
         cacheReadShare: round3(cacheReadShare),
@@ -1443,6 +1445,7 @@ function buildCursorUsageFindings(runs) {
         summary: `Max mode accounts for ${(maxModeSpendShare * 100).toFixed(0)}% of billed spend across ${maxModeCalls.length} paid row${maxModeCalls.length === 1 ? "" : "s"}. This is a strong candidate for splitting work between premium and standard passes.`,
         scope: "global",
         scopeId: "all",
+        scopeLabel: "Cursor usage",
         costImpactUsd: round3(maxModeSpendUsd * 0.2),
         details: {
           maxModeSpendUsd: round3(maxModeSpendUsd),
@@ -1502,6 +1505,7 @@ function buildFindings(runs) {
         summary: `${retryCandidates.length} failed call${retryCandidates.length === 1 ? "" : "s"} were followed by additional work, making their spend pure retry overhead.`,
         scope: "global",
         scopeId: "all",
+        scopeLabel: "workspace",
         costImpactUsd: round4(retryCost),
         details: {
           failedCallCount: retryCandidates.length
@@ -1529,7 +1533,8 @@ function buildFindings(runs) {
           title: `Workflow "${run2.workflow}" ran beyond efficient loop bounds`,
           summary: `This run reached ${maxIteration} iterations. Xerg treats the spend after iteration 5 as likely loop waste.`,
           scope: "run",
-          scopeId: run2.id,
+          scopeId: run2.workflow,
+          scopeLabel: run2.workflow,
           costImpactUsd: round4(loopCost),
           details: {
             workflow: run2.workflow,
@@ -1566,6 +1571,7 @@ function buildFindings(runs) {
             summary: `Xerg found ${outlierRuns.length} run${outlierRuns.length === 1 ? "" : "s"} in this workflow with input token volume far above the workflow average.`,
             scope: "workflow",
             scopeId: workflow,
+            scopeLabel: workflow,
             costImpactUsd: round4(outlierCost),
             details: {
               workflow,
@@ -1590,6 +1596,7 @@ function buildFindings(runs) {
           summary: "This workflow name looks like a recurring heartbeat or monitoring loop. Review whether the cadence and model tier are justified.",
           scope: "workflow",
           scopeId: workflow,
+          scopeLabel: workflow,
           costImpactUsd: round4(idleCost),
           details: {
             workflow
@@ -1611,6 +1618,7 @@ function buildFindings(runs) {
           summary: "An expensive model is being used on a workflow that looks operationally simple. Treat this as an A/B test candidate, not proven waste.",
           scope: "workflow",
           scopeId: workflow,
+          scopeLabel: workflow,
           costImpactUsd: round4(spend * 0.3),
           details: {
             workflow,
@@ -1703,6 +1711,247 @@ function estimateCostUsd(provider, model, inputTokens, outputTokens) {
   return Number((inputCost + outputCost).toFixed(8));
 }
 
+// ../core/src/recommendations.ts
+var PRIORITY_RANK = {
+  fix_now: 2,
+  test_next: 1,
+  watch: 0
+};
+var CONFIDENCE_RANK = {
+  high: 2,
+  medium: 1,
+  low: 0
+};
+function roundCurrency(value) {
+  return Number(value.toFixed(6));
+}
+function roundPct(value) {
+  return Number(value.toFixed(4));
+}
+function formatScopeLabel(finding) {
+  if (finding.scope === "global") {
+    return "workspace";
+  }
+  return finding.scopeLabel?.trim() || finding.scopeId;
+}
+function normalizeRecommendationScope(finding) {
+  if (finding.scope === "global") {
+    return "workspace";
+  }
+  return "workflow";
+}
+function stableScopeKeyForFinding(finding) {
+  if (finding.scope === "global") {
+    return "workspace";
+  }
+  return finding.scopeId;
+}
+function resolveScopeId(finding, scope) {
+  return scope === "workspace" ? "workspace" : stableScopeKeyForFinding(finding);
+}
+function dedupKeyForFinding(finding) {
+  const scope = normalizeRecommendationScope(finding);
+  return `${finding.kind}:${scope}:${stableScopeKeyForFinding(finding)}`;
+}
+function recommendationIdForFinding(finding, implementationSurface) {
+  const scope = normalizeRecommendationScope(finding);
+  return sha1(
+    `rec:v2:${finding.kind}:${scope}:${stableScopeKeyForFinding(finding)}:${implementationSurface}`
+  );
+}
+function compareRecommendations(left, right) {
+  const priorityDelta = PRIORITY_RANK[right.priorityBucket] - PRIORITY_RANK[left.priorityBucket];
+  if (priorityDelta !== 0) {
+    return priorityDelta;
+  }
+  if (right.estimatedSavingsUsd !== left.estimatedSavingsUsd) {
+    return right.estimatedSavingsUsd - left.estimatedSavingsUsd;
+  }
+  const confidenceDelta = CONFIDENCE_RANK[right.confidence] - CONFIDENCE_RANK[left.confidence];
+  if (confidenceDelta !== 0) {
+    return confidenceDelta;
+  }
+  return left.title.localeCompare(right.title);
+}
+var templatesByKind = {
+  "retry-waste": {
+    priorityBucket: "fix_now",
+    implementationSurface: "retry_policy",
+    category: "structural_efficiency",
+    severity: "high",
+    effort: "low",
+    titleFn: (finding) => `Reduce retry waste in ${formatScopeLabel(finding)}`,
+    summaryFn: (finding) => `${finding.summary} This is confirmed retry overhead, so it is a fix-now issue rather than an experiment.`,
+    whereToChangeFn: (finding) => `Reduce retries or add exponential backoff in the retry wrapper for ${formatScopeLabel(finding)}.`,
+    validationPlanFn: () => "Ship the change, then rerun `xerg audit --compare --push` against the same source. Retry waste should drop materially on the next audit.",
+    actionsFn: () => [
+      "Lower max retry count.",
+      "Add exponential backoff if none exists.",
+      "Log or alert when retries hit the cap."
+    ]
+  },
+  "loop-waste": {
+    priorityBucket: "fix_now",
+    implementationSurface: "loop_guard",
+    category: "structural_efficiency",
+    severity: "high",
+    effort: "medium",
+    titleFn: (finding) => `Cap loop depth in ${formatScopeLabel(finding)}`,
+    summaryFn: (finding) => `${finding.summary} This is confirmed loop waste and should be fixed before chasing lower-confidence opportunities.`,
+    whereToChangeFn: (finding) => `Cap iteration depth or add an early-exit guard in the loop controller for ${formatScopeLabel(finding)}.`,
+    validationPlanFn: () => "Ship the change, then rerun `xerg audit --compare --push`. Loop waste and call volume should fall on the next audit.",
+    actionsFn: () => [
+      "Add a hard iteration cap.",
+      "Add a no-progress exit.",
+      "Emit a warning when the cap is hit."
+    ]
+  },
+  "context-outlier": {
+    priorityBucket: "test_next",
+    implementationSurface: "prompt_builder",
+    category: "context_hygiene",
+    severity: "medium",
+    effort: "medium",
+    titleFn: (finding) => `Trim context in ${formatScopeLabel(finding)}`,
+    summaryFn: (finding) => `${finding.summary} Treat this as a reversible optimization test rather than proven waste.`,
+    whereToChangeFn: (finding) => `Trim input context in the prompt builder for ${formatScopeLabel(finding)}.`,
+    validationPlanFn: () => "Ship the change, then rerun `xerg audit --compare --push`. Input tokens and context-related spend should fall.",
+    actionsFn: () => [
+      "Drop stale context blocks.",
+      "Summarize long histories.",
+      "Cap prompt size for this workflow."
+    ]
+  },
+  "idle-spend": {
+    priorityBucket: "test_next",
+    implementationSurface: "scheduler",
+    category: "cadence_activity",
+    severity: "medium",
+    effort: "low",
+    titleFn: (finding) => `Review cadence for ${formatScopeLabel(finding)}`,
+    summaryFn: (finding) => `${finding.summary} This is usually a scheduling decision, so validate it by lowering or gating activity instead of rewriting the workflow.`,
+    whereToChangeFn: (finding) => `Lower cadence or move to event-driven triggers for ${formatScopeLabel(finding)}.`,
+    validationPlanFn: () => "Ship the change, then rerun `xerg audit --compare --push`. Idle spend per day should drop.",
+    actionsFn: () => [
+      "Reduce poll frequency.",
+      "Gate runs behind a real trigger.",
+      "Disable runs during dead windows."
+    ]
+  },
+  "candidate-downgrade": {
+    priorityBucket: "test_next",
+    implementationSurface: "model_routing",
+    category: "model_fit",
+    severity: "low",
+    effort: "low",
+    titleFn: (finding) => `Evaluate a cheaper model for ${formatScopeLabel(finding)}`,
+    summaryFn: (finding) => `${finding.summary} This is an A/B candidate: spend may fall, but quality needs to be checked before rollout.`,
+    whereToChangeFn: (finding) => `Re-map ${formatScopeLabel(finding)} to a cheaper model in the routing layer.`,
+    validationPlanFn: () => "A/B the cheaper model, then rerun `xerg audit --compare --push`. Confirm spend drops without a quality regression.",
+    actionsFn: () => [
+      "Try a cheaper model on this workflow.",
+      "Compare quality on a labeled sample.",
+      "Roll out if acceptable."
+    ]
+  },
+  "cache-carryover": {
+    priorityBucket: "test_next",
+    implementationSurface: "user_behavior",
+    category: "context_hygiene",
+    severity: "medium",
+    effort: "low",
+    titleFn: () => "Reset or summarize long Cursor chats",
+    summaryFn: (finding) => `${finding.summary} This is about session behavior rather than code structure, so the intervention is to reset context more aggressively.`,
+    whereToChangeFn: () => "Reset or summarize long Cursor chats instead of continuing the same session.",
+    validationPlanFn: () => "Change session behavior, then push a new Cursor usage audit with `--compare --push`. Cache-read share should fall.",
+    actionsFn: () => [
+      "Summarize context into a short recall note.",
+      "Start a fresh chat.",
+      "Carry forward only the recall note and necessary facts."
+    ]
+  },
+  "max-mode-concentration": {
+    priorityBucket: "test_next",
+    implementationSurface: "user_behavior",
+    category: "model_fit",
+    severity: "medium",
+    effort: "low",
+    titleFn: () => "Reserve max mode for the hardest Cursor turns",
+    summaryFn: (finding) => `${finding.summary} The likely fix is changing mode habits or escalation rules, not modifying a prompt builder.`,
+    whereToChangeFn: () => "Reserve max mode for the hardest Cursor turns; default to standard mode.",
+    validationPlanFn: () => "Change your mode defaults, then push a new Cursor usage audit with `--compare --push`. Max-mode spend share should fall.",
+    actionsFn: () => [
+      "Start in standard mode.",
+      "Escalate only when standard fails.",
+      "Review any auto-escalation habit."
+    ]
+  }
+};
+var unknownTemplate = {
+  priorityBucket: "watch",
+  implementationSurface: "other",
+  category: "other",
+  severity: "low",
+  effort: "medium",
+  titleFn: (finding) => `Review ${finding.title}`,
+  summaryFn: (finding) => finding.summary,
+  whereToChangeFn: (finding) => `Review ${formatScopeLabel(finding)} with your operator.`,
+  validationPlanFn: () => "Ship any change, then rerun `xerg audit --compare --push` to confirm impact.",
+  actionsFn: () => [
+    "Investigate the finding details.",
+    "Decide whether to act.",
+    "Re-audit after the change."
+  ]
+};
+function buildSingleRecommendation(summary, finding) {
+  const template = templatesByKind[finding.kind] ?? unknownTemplate;
+  const scope = normalizeRecommendationScope(finding);
+  const scopeId = resolveScopeId(finding, scope);
+  const scopeLabel = formatScopeLabel(finding);
+  const estimatedSavingsPct = summary.totalSpendUsd === 0 ? 0 : roundPct(Math.min(Math.max(finding.costImpactUsd / summary.totalSpendUsd, 0), 1));
+  return {
+    id: recommendationIdForFinding(finding, template.implementationSurface),
+    findingId: finding.id,
+    kind: finding.kind,
+    title: template.titleFn(finding),
+    summary: template.summaryFn(finding),
+    priorityBucket: template.priorityBucket,
+    recommendedOrder: 0,
+    implementationSurface: template.implementationSurface,
+    category: template.category,
+    severity: template.severity,
+    estimatedSavingsUsd: roundCurrency(finding.costImpactUsd),
+    estimatedSavingsPct,
+    confidence: finding.confidence,
+    effort: template.effort,
+    scope,
+    scopeId,
+    scopeLabel,
+    whereToChange: template.whereToChangeFn(finding),
+    validationPlan: template.validationPlanFn(finding),
+    actions: template.actionsFn(finding)
+  };
+}
+function buildRecommendations(summary) {
+  const deduped = /* @__PURE__ */ new Map();
+  for (const finding of summary.findings) {
+    const recommendation = buildSingleRecommendation(summary, finding);
+    const key = dedupKeyForFinding(finding);
+    const existing = deduped.get(key);
+    if (!existing) {
+      deduped.set(key, recommendation);
+      continue;
+    }
+    if (recommendation.estimatedSavingsUsd > existing.estimatedSavingsUsd || recommendation.estimatedSavingsUsd === existing.estimatedSavingsUsd && CONFIDENCE_RANK[recommendation.confidence] > CONFIDENCE_RANK[existing.confidence]) {
+      deduped.set(key, recommendation);
+    }
+  }
+  return [...deduped.values()].sort(compareRecommendations).map((recommendation, index) => ({
+    ...recommendation,
+    recommendedOrder: index + 1
+  }));
+}
+
 // ../core/src/report/timeseries.ts
 function round5(value) {
   return Number(value.toFixed(6));
@@ -1856,7 +2105,7 @@ function buildAuditSummary(input) {
   const generatedAt = isoNow();
   const spendByDay = buildSpendByDay(input.runs);
   const observedDays = buildObservedUtcDayRange(input.runs);
-  return {
+  const summary = {
     auditId: sha1(
       `${generatedAt}:${input.runs.length}:${input.sources.map((source) => source.path).join("|")}`
     ),
@@ -1900,6 +2149,7 @@ function buildAuditSummary(input) {
     spendByDay,
     wasteByDay: buildWasteByDay(input.wasteAttributions, observedDays, wasteSpendUsd),
     findings: input.findings,
+    recommendations: [],
     notes: [
       "Cost per outcome is intentionally unavailable in v0. Xerg is measuring waste intelligence only.",
       "Opportunity findings are directional recommendations, not proven waste."
@@ -1907,6 +2157,8 @@ function buildAuditSummary(input) {
     sourceFiles: input.sources,
     dbPath: input.dbPath
   };
+  summary.recommendations = buildRecommendations(summary);
+  return summary;
 }
 
 // ../core/src/runtime.ts
@@ -3169,109 +3421,6 @@ async function auditCursorUsageCsv(options) {
   return summary;
 }
 
-// ../core/src/recommendations.ts
-var templatesByKind = {
-  "retry-waste": {
-    actionType: "other",
-    titleFn: () => "Add retry backoff or reduce retry attempts",
-    descriptionFn: (f) => `${f.summary} Consider adding exponential backoff or reducing the maximum retry count to eliminate this overhead.`,
-    suggestedChangeFn: (f) => ({
-      strategy: "exponential-backoff",
-      maxRetries: 3,
-      failedCallCount: f.details.failedCallCount
-    })
-  },
-  "loop-waste": {
-    actionType: "other",
-    titleFn: (f) => `Cap iteration depth for ${extractWorkflow(f)}`,
-    descriptionFn: (f) => `${f.summary} Adding an iteration limit or early-exit condition would prevent runaway loops from burning spend.`,
-    suggestedChangeFn: (f) => ({
-      strategy: "iteration-cap",
-      suggestedMaxIterations: 5,
-      observedMaxIteration: f.details.maxIteration
-    })
-  },
-  "context-outlier": {
-    actionType: "prompt-trim",
-    titleFn: (f) => `Trim context for ${extractWorkflow(f)}`,
-    descriptionFn: (f) => `${f.summary} Reducing input token volume to near the workflow baseline would lower cost proportionally.`,
-    suggestedChangeFn: (f) => ({
-      strategy: "context-reduction",
-      averageInputTokens: f.details.averageInputTokens
-    })
-  },
-  "candidate-downgrade": {
-    actionType: "model-switch",
-    titleFn: (f) => `Evaluate cheaper model for ${extractWorkflow(f)}`,
-    descriptionFn: (f) => `${f.summary} This is an A/B test candidate \u2014 try a cheaper model on this workflow and compare quality.`,
-    suggestedChangeFn: () => ({
-      strategy: "model-downgrade",
-      candidates: ["claude-3-haiku", "gpt-4o-mini"]
-    })
-  },
-  "idle-spend": {
-    actionType: "other",
-    titleFn: (f) => `Review cadence for ${extractWorkflow(f)}`,
-    descriptionFn: (f) => `${f.summary} Consider reducing polling frequency or switching to an event-driven approach.`,
-    suggestedChangeFn: () => ({
-      strategy: "cadence-review"
-    })
-  },
-  "cache-carryover": {
-    actionType: "prompt-trim",
-    titleFn: () => "Summarize and reset long Cursor chats",
-    descriptionFn: (f) => `${f.summary} Create a compact recall summary, start a fresh chat, and carry forward only the facts the model actually needs.`,
-    suggestedChangeFn: (f) => ({
-      strategy: "conversation-reset",
-      cacheReadShare: f.details.cacheReadShare,
-      totalCacheReadTokens: f.details.totalCacheReadTokens
-    })
-  },
-  "max-mode-concentration": {
-    actionType: "model-switch",
-    titleFn: () => "Reserve max mode for the hardest Cursor turns",
-    descriptionFn: (f) => `${f.summary} Try a two-pass workflow: standard mode first, then escalate only the prompts that truly need max mode.`,
-    suggestedChangeFn: (f) => ({
-      strategy: "tiered-routing",
-      maxModeSpendShare: f.details.maxModeSpendShare,
-      maxModeCallCount: f.details.maxModeCallCount
-    })
-  }
-};
-function extractWorkflow(finding) {
-  const details = finding.details;
-  return details.workflow || finding.scopeId || "this workflow";
-}
-function buildSingleRecommendation(finding) {
-  const template = templatesByKind[finding.kind];
-  if (template) {
-    return {
-      id: sha1(`rec:${finding.id}:${template.actionType}`),
-      findingId: finding.id,
-      kind: finding.kind,
-      title: template.titleFn(finding),
-      description: template.descriptionFn(finding),
-      estimatedSavingsUsd: finding.costImpactUsd,
-      confidence: finding.confidence,
-      actionType: template.actionType,
-      suggestedChange: template.suggestedChangeFn?.(finding)
-    };
-  }
-  return {
-    id: sha1(`rec:${finding.id}:other`),
-    findingId: finding.id,
-    kind: finding.kind,
-    title: `Review: ${finding.title}`,
-    description: finding.summary,
-    estimatedSavingsUsd: finding.costImpactUsd,
-    confidence: finding.confidence,
-    actionType: "other"
-  };
-}
-function buildRecommendations(summary) {
-  return summary.findings.map(buildSingleRecommendation);
-}
-
 // ../core/src/report/render.ts
 function formatUsd(value) {
   return new Intl.NumberFormat("en-US", {
@@ -3330,16 +3479,6 @@ function renderTaxonomyBlock(summary) {
 function topFinding(summary, classification) {
   return summary.findings.filter((finding) => finding.classification === classification).sort((left, right) => right.costImpactUsd - left.costImpactUsd)[0];
 }
-function topSavingsTest(summary) {
-  return summary.findings.filter((finding) => finding.classification === "opportunity").sort((left, right) => {
-    const leftPriority = left.kind === "candidate-downgrade" ? 1 : 0;
-    const rightPriority = right.kind === "candidate-downgrade" ? 1 : 0;
-    if (leftPriority !== rightPriority) {
-      return rightPriority - leftPriority;
-    }
-    return right.costImpactUsd - left.costImpactUsd;
-  })[0] ?? null;
-}
 function renderFindingList(findings, emptyLabel) {
   if (findings.length === 0) {
     return [`- ${emptyLabel}`];
@@ -3348,6 +3487,33 @@ function renderFindingList(findings, emptyLabel) {
     return `- ${finding.title}: ${formatUsd(finding.costImpactUsd)} (${finding.confidence})`;
   });
 }
+function renderActionQueueRow(label, recommendation) {
+  if (!recommendation) {
+    return [`${label}`, "- none"];
+  }
+  return [
+    label,
+    `- ${recommendation.title} [${recommendation.scopeLabel}]: ${formatUsd(recommendation.estimatedSavingsUsd)} (${recommendation.severity})`
+  ];
+}
+function renderActionQueue(summary) {
+  const fixNow = summary.recommendations.find(
+    (recommendation) => recommendation.priorityBucket === "fix_now"
+  );
+  const testNext = summary.recommendations.find(
+    (recommendation) => recommendation.priorityBucket === "test_next"
+  );
+  const watch = summary.recommendations.find(
+    (recommendation) => recommendation.priorityBucket === "watch"
+  );
+  return [
+    "## Action queue",
+    ...renderActionQueueRow("Fix now", fixNow),
+    ...renderActionQueueRow("Test next", testNext),
+    ...renderActionQueueRow("Watch", watch),
+    "How to validate: `xerg audit --compare --push`"
+  ];
+}
 function describeSpendDelta(delta) {
   return `${delta.key} (${formatUsdDelta(delta.deltaSpendUsd)})`;
 }
@@ -3570,6 +3736,8 @@ function renderCursorTerminalSummary(summary) {
     "## Findings",
     ...renderFindingList(summary.findings, "none detected"),
     "",
+    ...renderActionQueue(summary),
+    "",
     ...renderCursorCompareBlock(summary),
     ...summary.comparison ? [""] : [],
     "## Notes",
@@ -3613,6 +3781,8 @@ function renderCursorMarkdownSummary(summary) {
     ...summary.findings.slice(0, 10).map((finding) => {
       return `- **${finding.title}** (${finding.classification}, ${finding.confidence}) \u2014 ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
     }),
+    "",
+    ...renderActionQueue(summary),
     ...summary.comparison ? ["", ...renderCursorCompareBlock(summary)] : [],
     "",
     "## Notes",
@@ -3627,7 +3797,6 @@ function renderTerminalSummary(summary) {
   const opportunityFindings = summary.findings.filter(
     (finding) => finding.classification === "opportunity"
   );
-  const topSavings = topSavingsTest(summary);
   const topWaste = topFinding(summary, "waste");
   return [
     "# Xerg audit",
@@ -3656,11 +3825,8 @@ function renderTerminalSummary(summary) {
     "## Opportunities",
     ...renderFindingList(opportunityFindings, "none detected"),
     "",
-    "## First savings test",
-    ...topSavings ? [
-      `- Start with ${topSavings.title}: ${formatUsd(topSavings.costImpactUsd)} of potential impact`,
-      `- Why this test first: ${topSavings.summary}`
-    ] : ["- No savings test surfaced yet"],
+    ...renderActionQueue(summary),
+    "",
     ...topWaste ? [`- Confirmed leak to close first: ${topWaste.title}`] : ["- Confirmed leak to close first: none"],
     ...summary.spendByWorkflow[0] ? [`- Workflow to inspect first: ${summary.spendByWorkflow[0].key}`] : ["- Workflow to inspect first: none"],
     "",
@@ -3697,7 +3863,9 @@ function renderMarkdownSummary(summary) {
     "## Findings",
     ...summary.findings.slice(0, 10).map((finding) => {
       return `- **${finding.title}** (${finding.classification}, ${finding.confidence}) \u2014 ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
-    })
+    }),
+    "",
+    ...renderActionQueue(summary)
   ];
   if (summary.comparison) {
     const comparison = summary.comparison;
@@ -3714,7 +3882,7 @@ function renderMarkdownSummary(summary) {
 }
 
 // ../schemas/dist/index.js
-var AUDIT_PUSH_PAYLOAD_VERSION = 1;
+var AUDIT_PUSH_PAYLOAD_VERSION = 2;
 
 // ../core/src/wire.ts
 function toWireFinding(finding) {
@@ -3766,6 +3934,7 @@ function toWirePayload(summary, meta) {
       spendByDay: summary.spendByDay,
       wasteByDay: summary.wasteByDay,
       findings: summary.findings.map(toWireFinding),
+      recommendations: summary.recommendations,
       notes: summary.notes,
       comparison: summary.comparison ? toWireComparison(summary.comparison) : null
     },
@@ -5134,11 +5303,10 @@ ${errorMessages}`);
       summaries.push({ name: source.name, source, summary });
     }
     if (options.json) {
-      const output = summaries.length === 1 ? { ...summaries[0].summary, recommendations: buildRecommendations(summaries[0].summary) } : {
+      const output = summaries.length === 1 ? summaries[0].summary : {
         sources: summaries.map((s) => ({
           name: s.name,
-          ...s.summary,
-          recommendations: buildRecommendations(s.summary)
+          ...s.summary
         }))
       };
       process.stdout.write(`${JSON.stringify(output, null, 2)}
@@ -5216,9 +5384,7 @@ function renderOutput(summary, options) {
     return;
   }
   if (options.json) {
-    const recommendations = buildRecommendations(summary);
-    const output = { ...summary, recommendations };
-    process.stdout.write(`${JSON.stringify(output, null, 2)}
+    process.stdout.write(`${JSON.stringify(summary, null, 2)}
 `);
     return;
   }
@@ -5823,6 +5989,7 @@ function renderRailwayDoctorReport(report) {
 import { existsSync as existsSync2, mkdirSync as mkdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname3, join as join8 } from "path";
 var HOSTED_MCP_URL = "https://mcp.xerg.ai/mcp";
+var MCP_SERVER_NAME = "xerg";
 async function runMcpSetupCommand() {
   await runMcpSetupFlow();
 }
@@ -5865,6 +6032,11 @@ async function runMcpSetupFlow() {
       value: "claude-code",
       description: "Project-scoped Claude Code MCP config"
     },
+    {
+      name: "Codex",
+      value: "codex",
+      description: "Codex config.toml snippet"
+    },
     {
       name: "Other",
       value: "other",
@@ -5876,6 +6048,14 @@ async function runMcpSetupFlow() {
     await handleCursorSetup(snippet, config);
     return;
   }
+  if (client === "codex") {
+    process.stdout.write(`${buildCodexMcpConfig(config)}
+`);
+    process.stderr.write(
+      "Add this to `~/.codex/config.toml`, then restart Codex so it loads the Xerg MCP tools.\n"
+    );
+    return;
+  }
   process.stdout.write(`${snippet}
 `);
   if (client === "claude-code") {
@@ -5913,7 +6093,7 @@ async function handleCursorSetup(snippet, config) {
 function buildHostedMcpConfig(config) {
   return {
     mcpServers: {
-      xerg: {
+      [MCP_SERVER_NAME]: {
         type: "http",
         url: HOSTED_MCP_URL,
         headers: {
@@ -5923,6 +6103,19 @@ function buildHostedMcpConfig(config) {
     }
   };
 }
+function buildCodexMcpConfig(config) {
+  return [
+    `[mcp_servers.${MCP_SERVER_NAME}]`,
+    "enabled = true",
+    `url = ${tomlString(HOSTED_MCP_URL)}`,
+    "",
+    `[mcp_servers.${MCP_SERVER_NAME}.http_headers]`,
+    `Authorization = ${tomlString(`Bearer ${config.apiKey}`)}`
+  ].join("\n");
+}
+function tomlString(value) {
+  return JSON.stringify(value);
+}
 function writeCursorConfig(filePath, config) {
   mkdirSync6(dirname3(filePath), { recursive: true });
   let parsed = {};
@@ -6259,7 +6452,7 @@ Notes:
 function renderMcpSetupHelp(commandPrefix) {
   return `${formatCommand("mcp-setup", commandPrefix)}
 
-Generate hosted MCP client configuration for Cursor, Claude Code, or another MCP client.
+Generate hosted MCP client configuration for Cursor, Claude Code, Codex, or another MCP client.
 
 Usage:
   ${formatCommand("mcp-setup", commandPrefix)}
@@ -6268,6 +6461,7 @@ Notes:
   - Interactive in v1 because client selection is prompt-driven
   - Uses the hosted MCP endpoint at https://mcp.xerg.ai/mcp
   - Can write a project-scoped Cursor config when .cursor/ already exists
+  - Prints a Codex config.toml snippet when Codex is selected
   - Local audits and compare stay available even if you skip hosted MCP setup
 
   -h, --help                  Show help