@xerg/cli 0.3.0 → 0.5.0

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
     },
@@ -3887,7 +4056,8 @@ function loadPushConfig() {
   if (envKey) {
     return {
       apiKey: envKey,
-      apiUrl: envUrl || DEFAULT_API_URL
+      apiUrl: envUrl || DEFAULT_API_URL,
+      source: "env"
     };
   }
   try {
@@ -3896,7 +4066,8 @@ function loadPushConfig() {
     if (parsed.apiKey) {
       return {
         apiKey: parsed.apiKey,
-        apiUrl: envUrl || parsed.apiUrl || DEFAULT_API_URL
+        apiUrl: envUrl || parsed.apiUrl || DEFAULT_API_URL,
+        source: "config"
       };
     }
   } catch {
@@ -3905,7 +4076,8 @@ function loadPushConfig() {
   if (storedToken) {
     return {
       apiKey: storedToken,
-      apiUrl: envUrl || DEFAULT_API_URL
+      apiUrl: envUrl || DEFAULT_API_URL,
+      source: "stored"
     };
   }
   throw new Error(
@@ -5131,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)}
@@ -5213,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;
   }
@@ -5255,103 +5424,445 @@ function cleanupPullResult(pullResult, keepFiles) {
   }
 }
 
-// src/commands/doctor.ts
-async function runDoctorCommand(options) {
-  const logger = createCliLogger({ verbose: options.verbose });
-  validateRuntimeOption2(options.runtime);
-  validateCursorUsageCsvOptions2(options);
-  validateHermesLocalOnly2(options);
-  if (options.railway) {
-    logger.verbose("Inspecting Railway audit readiness.");
-    const railwayTarget = buildRailwayTarget2(options);
-    const source = buildRailwaySourceFromFlags({
-      railway: railwayTarget,
-      remoteLogFile: options.remoteLogFile,
-      remoteSessionsDir: options.remoteSessionsDir
-    });
-    const report2 = await runRailwayDoctor({ source, onProgress: logger.verbose });
-    process.stdout.write(`${renderRailwayDoctorReport(report2)}
-`);
-    return;
-  }
-  if (options.remote) {
-    logger.verbose(`Inspecting SSH audit readiness for ${options.remote}.`);
-    const source = buildSourceFromFlags({
-      remote: options.remote,
-      remoteLogFile: options.remoteLogFile,
-      remoteSessionsDir: options.remoteSessionsDir
-    });
-    const report2 = await runRemoteDoctor({ source, onProgress: logger.verbose });
-    process.stdout.write(`${renderRemoteDoctorReport(report2)}
-`);
-    return;
-  }
-  if (options.cursorUsageCsv) {
-    logger.verbose("Inspecting local Cursor usage CSV audit readiness.");
-    logger.verbose(`Using Cursor usage CSV: ${options.cursorUsageCsv}`);
-    const report2 = await doctorCursorUsageCsv({
-      cursorUsageCsv: options.cursorUsageCsv,
-      onProgress: logger.verbose
-    });
-    process.stdout.write(`${renderCursorDoctorReport(report2)}
-`);
+// src/commands/login.ts
+import { styleText } from "util";
+var DEFAULT_AUTH_URL = "https://xerg.ai/dashboard/settings";
+var DEFAULT_API_URL2 = "https://api.xerg.ai";
+var POLL_INTERVAL_MS = 2e3;
+var POLL_TIMEOUT_MS = 3e5;
+async function runLoginCommand() {
+  const existing = loadStoredCredentials();
+  if (existing) {
+    process.stderr.write(
+      `Already logged in. Credentials stored at ${getCredentialsPath()}.
+Run ${colorBold(formatCommand("logout"))} first to re-authenticate.
+`
+    );
     return;
   }
-  logger.verbose(
-    options.runtime ? `Inspecting local ${options.runtime === "hermes" ? "Hermes" : "OpenClaw"} audit readiness.` : "Inspecting local runtime audit readiness."
+  const data = await performDeviceLogin();
+  storeCredentials(data.token);
+  const teamInfo = data.teamName ? ` (team: ${data.teamName})` : "";
+  process.stderr.write(
+    `
+${colorSuccess("Authenticated successfully")}${teamInfo}.
+Credentials saved to ${getCredentialsPath()}.
+`
   );
-  if (options.logFile) {
-    logger.verbose(`Using explicit local log file: ${options.logFile}`);
-  }
-  if (options.sessionsDir) {
-    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
-  }
-  const report = await doctorAgentRuntime({
-    runtime: options.runtime ?? "auto",
-    logFile: options.logFile,
-    sessionsDir: options.sessionsDir,
-    onProgress: logger.verbose
-  });
-  process.stdout.write(`${renderDoctorReport(report, { commandPrefix: options.commandPrefix })}
-`);
 }
-function validateRuntimeOption2(runtime) {
-  if (!runtime) {
-    return;
-  }
-  if (runtime !== "openclaw" && runtime !== "hermes") {
+async function performDeviceLogin() {
+  const apiUrl = process.env.XERG_API_URL || DEFAULT_API_URL2;
+  const deviceCodeUrl = `${apiUrl}/v1/auth/device-code`;
+  let deviceResponse;
+  try {
+    const res = await fetch(deviceCodeUrl, { method: "POST" });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    }
+    deviceResponse = await res.json();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
     throw new Error(
-      `Unsupported runtime "${runtime}". Use --runtime openclaw or --runtime hermes.`
+      `Could not start device auth flow (${msg}).
+
+Alternative: create an API key at ${DEFAULT_AUTH_URL}
+and set XERG_API_KEY in your environment.`
     );
   }
-}
-function validateCursorUsageCsvOptions2(options) {
-  if (!options.cursorUsageCsv) {
-    return;
-  }
-  const conflicts = [
-    options.runtime ? "--runtime" : null,
-    options.logFile ? "--log-file" : null,
-    options.sessionsDir ? "--sessions-dir" : null,
-    options.remote ? "--remote" : null,
-    options.remoteLogFile ? "--remote-log-file" : null,
-    options.remoteSessionsDir ? "--remote-sessions-dir" : null,
-    options.railway ? "--railway" : null,
-    options.railwayProject ? "--project" : null,
-    options.railwayEnvironment ? "--environment" : null,
-    options.railwayService ? "--service" : null
-  ].filter((flag) => flag !== null);
-  if (conflicts.length > 0) {
-    throw new Error(`The --cursor-usage-csv flag cannot be combined with ${conflicts.join(", ")}.`);
-  }
-}
-function validateHermesLocalOnly2(options) {
-  if (options.runtime !== "hermes") {
-    return;
+  const verifyUrl = deviceResponse.verificationUrl || DEFAULT_AUTH_URL;
+  const pollInterval = (deviceResponse.interval || 2) * 1e3;
+  process.stderr.write(
+    `
+Open this URL in your browser to authenticate:
+
+  ${colorBold(verifyUrl)}
+
+`
+  );
+  if (deviceResponse.userCode) {
+    process.stderr.write(`Your code: ${colorBold(deviceResponse.userCode)}
+
+`);
   }
-  const conflicts = [
-    options.remote ? "--remote" : null,
-    options.remoteLogFile ? "--remote-log-file" : null,
+  process.stderr.write("Waiting for authentication...\n");
+  await openBrowser(verifyUrl);
+  const tokenUrl = `${apiUrl}/v1/auth/device-token`;
+  const startTime = Date.now();
+  while (Date.now() - startTime < POLL_TIMEOUT_MS) {
+    await sleep(Math.max(pollInterval, POLL_INTERVAL_MS));
+    try {
+      const res = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ deviceCode: deviceResponse.deviceCode })
+      });
+      if (res.status === 200) {
+        return await res.json();
+      }
+      if (res.status === 428) {
+        continue;
+      }
+      if (res.status === 410) {
+        throw new Error(`Device code expired. Please run \`${formatCommand("login")}\` again.`);
+      }
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body.error || `Unexpected response: HTTP ${res.status}`);
+    } catch (err) {
+      if (err instanceof Error && (err.message.includes("expired") || err.message.includes("Unexpected"))) {
+        throw err;
+      }
+    }
+  }
+  throw new Error(`Authentication timed out. Please run \`${formatCommand("login")}\` again.`);
+}
+async function openBrowser(url) {
+  const { exec } = await import("child_process");
+  const { platform: platform2 } = await import("os");
+  const commands = {
+    darwin: "open",
+    win32: "start",
+    linux: "xdg-open"
+  };
+  const cmd = commands[platform2()];
+  if (!cmd) return;
+  return new Promise((resolve4) => {
+    exec(`${cmd} ${JSON.stringify(url)}`, () => resolve4());
+  });
+}
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+function colorBold(text) {
+  return process.stderr.isTTY ? styleText("bold", text) : text;
+}
+function colorSuccess(text) {
+  return process.stderr.isTTY ? styleText("green", text) : text;
+}
+
+// src/cloud.ts
+function loadPushConfigOrNull() {
+  try {
+    return loadPushConfig();
+  } catch {
+    return null;
+  }
+}
+async function authenticateAndLoadPushConfig() {
+  const data = await performDeviceLogin();
+  storeCredentials(data.token);
+  const teamInfo = data.teamName ? ` (team: ${data.teamName})` : "";
+  process.stderr.write(
+    `
+Authenticated successfully${teamInfo}.
+Credentials saved to ${getCredentialsPath()}.
+`
+  );
+  return loadPushConfig();
+}
+function renderCloudDisclaimer() {
+  return [
+    "Xerg Cloud sync and hosted MCP are optional paid workspace features.",
+    "Local audits and compare stay free, and you can keep using Xerg locally if you skip this step."
+  ].join("\n");
+}
+function renderMcpCredentialSourceMessage(config) {
+  if (config.source === "stored") {
+    return "Using your stored login token. If hosted MCP requires a workspace API key, create one at xerg.ai/dashboard/settings and set XERG_API_KEY.";
+  }
+  return "Using your workspace API key.";
+}
+
+// src/prompts.ts
+import { confirm, select } from "@inquirer/prompts";
+function hasPromptTty() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function promptConfirm(message, defaultValue = true) {
+  return confirm({
+    message,
+    default: defaultValue
+  });
+}
+async function promptSelect(message, choices) {
+  return select({
+    message,
+    choices
+  });
+}
+
+// src/commands/push.ts
+import { readFileSync as readFileSync8 } from "fs";
+async function runPushCommand(options) {
+  const payload = options.file ? loadPayloadFromFile(options.file) : loadLatestCachedAuditPayload();
+  if (options.dryRun) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+    return;
+  }
+  const config = loadPushConfig();
+  const auditId = payload.summary.auditId;
+  process.stderr.write(`Pushing audit ${auditId} to ${config.apiUrl}...
+`);
+  const result = await pushAudit(payload, config);
+  if (result.ok) {
+    process.stderr.write(`Pushed successfully (audit: ${result.auditId}).
+`);
+  } else {
+    const statusInfo = result.status > 0 ? ` (HTTP ${result.status})` : "";
+    throw new Error(`Push failed${statusInfo}: ${result.message}`);
+  }
+}
+function loadPayloadFromFile(filePath) {
+  let raw;
+  try {
+    raw = readFileSync8(filePath, "utf8");
+  } catch {
+    throw new Error(`Cannot read file: ${filePath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`File is not valid JSON: ${filePath}`);
+  }
+  const payload = parsed;
+  if (!payload.version || !payload.summary || !payload.meta) {
+    throw new Error(
+      `File does not look like an AuditPushPayload (missing version, summary, or meta): ${filePath}`
+    );
+  }
+  return payload;
+}
+function loadLatestCachedAuditPayload() {
+  const dbPath = getDefaultDbPath();
+  let summaries;
+  try {
+    summaries = listStoredAuditSummaries(dbPath);
+  } catch {
+    throw new NoDataError(
+      `No local audit database found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
+    );
+  }
+  if (summaries.length === 0) {
+    throw new NoDataError(
+      `No cached audit snapshots found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
+    );
+  }
+  const latest = summaries[0];
+  const meta = buildMeta2(latest);
+  process.stderr.write(
+    `Using most recent cached audit: ${latest.auditId} (${latest.generatedAt})
+`
+  );
+  return toWirePayload(latest, meta);
+}
+function buildMeta2(summary) {
+  const sourceMeta = buildCachedPushSourceMeta(summary);
+  return {
+    cliVersion: getCliVersion(),
+    sourceId: sourceMeta.sourceId,
+    sourceHost: sourceMeta.sourceHost,
+    environment: sourceMeta.environment
+  };
+}
+
+// src/commands/connect.ts
+async function runConnectCommand() {
+  await runConnectFlow();
+}
+async function runConnectFlow(options) {
+  if (!options?.skipDisclaimer) {
+    process.stderr.write(`${renderCloudDisclaimer()}
+`);
+  }
+  let config = loadPushConfigOrNull();
+  if (config) {
+    process.stderr.write("Xerg authentication detected.\n");
+  } else {
+    if (!hasPromptTty()) {
+      process.stderr.write(
+        `No Xerg authentication is configured, and ${formatCommand("connect")} needs an interactive terminal before it can start browser login.
+Run ${formatCommand("login")} from a TTY, or keep using local audits for free.
+`
+      );
+      process.exitCode = 1;
+      return false;
+    }
+    const shouldLogin = await promptConfirm("Sign in to Xerg Cloud now?", true);
+    if (!shouldLogin) {
+      process.stderr.write(
+        "Skipped Xerg Cloud setup. You can keep using local audits and compare without connecting.\n"
+      );
+      return false;
+    }
+    config = await authenticateAndLoadPushConfig();
+  }
+  if (!hasPromptTty()) {
+    if (!options?.auditSummary) {
+      process.stderr.write(
+        `Non-interactive mode skips the push prompt. Run ${formatCommand("push")} when you want to sync a cached audit.
+`
+      );
+    } else {
+      process.stderr.write(
+        `Authentication is ready. Run ${formatCommand("push")} later if you want to sync this audit.
+`
+      );
+    }
+    return true;
+  }
+  const shouldPush = await promptConfirm(
+    options?.auditSummary ? "Push this audit to Xerg Cloud?" : "Push your latest cached audit to Xerg Cloud?",
+    true
+  );
+  if (!shouldPush) {
+    process.stderr.write(
+      options?.auditSummary ? `Skipped push. Run ${formatCommand("push")} later if you want to sync a cached audit.
+` : `Skipped push. Run ${formatCommand("push")} when you want to sync a cached audit.
+`
+    );
+    return true;
+  }
+  const payload = options?.auditSummary ? toWirePayload(options.auditSummary, buildLocalMeta(options.auditSummary)) : loadStandalonePayload();
+  if (!payload) {
+    return true;
+  }
+  await pushResolvedPayload(payload, config ?? loadPushConfig());
+  return true;
+}
+function buildLocalMeta(summary) {
+  const sourceMeta = buildLocalPushSourceMeta(summary.runtime);
+  return {
+    cliVersion: getCliVersion(),
+    sourceId: sourceMeta.sourceId,
+    sourceHost: sourceMeta.sourceHost,
+    environment: sourceMeta.environment
+  };
+}
+function loadStandalonePayload() {
+  try {
+    return loadLatestCachedAuditPayload();
+  } catch (error) {
+    if (error instanceof NoDataError || error instanceof Error && error.name === "NoDataError") {
+      process.stderr.write(
+        `${error instanceof Error ? error.message : "No cached audit snapshots found."}
+`
+      );
+      return null;
+    }
+    throw error;
+  }
+}
+async function pushResolvedPayload(payload, config) {
+  process.stderr.write(`Pushing audit ${payload.summary.auditId} to ${config.apiUrl}...
+`);
+  const result = await pushAudit(payload, config);
+  if (result.ok) {
+    process.stderr.write(`Pushed successfully (audit: ${result.auditId}).
+`);
+    return;
+  }
+  const statusInfo = result.status > 0 ? ` (HTTP ${result.status})` : "";
+  throw new Error(`Push failed${statusInfo}: ${result.message}`);
+}
+
+// src/commands/doctor.ts
+async function runDoctorCommand(options) {
+  const logger = createCliLogger({ verbose: options.verbose });
+  validateRuntimeOption2(options.runtime);
+  validateCursorUsageCsvOptions2(options);
+  validateHermesLocalOnly2(options);
+  if (options.railway) {
+    logger.verbose("Inspecting Railway audit readiness.");
+    const railwayTarget = buildRailwayTarget2(options);
+    const source = buildRailwaySourceFromFlags({
+      railway: railwayTarget,
+      remoteLogFile: options.remoteLogFile,
+      remoteSessionsDir: options.remoteSessionsDir
+    });
+    const report2 = await runRailwayDoctor({ source, onProgress: logger.verbose });
+    process.stdout.write(`${renderRailwayDoctorReport(report2)}
+`);
+    return;
+  }
+  if (options.remote) {
+    logger.verbose(`Inspecting SSH audit readiness for ${options.remote}.`);
+    const source = buildSourceFromFlags({
+      remote: options.remote,
+      remoteLogFile: options.remoteLogFile,
+      remoteSessionsDir: options.remoteSessionsDir
+    });
+    const report2 = await runRemoteDoctor({ source, onProgress: logger.verbose });
+    process.stdout.write(`${renderRemoteDoctorReport(report2)}
+`);
+    return;
+  }
+  if (options.cursorUsageCsv) {
+    logger.verbose("Inspecting local Cursor usage CSV audit readiness.");
+    logger.verbose(`Using Cursor usage CSV: ${options.cursorUsageCsv}`);
+    const report2 = await doctorCursorUsageCsv({
+      cursorUsageCsv: options.cursorUsageCsv,
+      onProgress: logger.verbose
+    });
+    process.stdout.write(`${renderCursorDoctorReport(report2)}
+`);
+    return;
+  }
+  logger.verbose(
+    options.runtime ? `Inspecting local ${options.runtime === "hermes" ? "Hermes" : "OpenClaw"} audit readiness.` : "Inspecting local runtime audit readiness."
+  );
+  if (options.logFile) {
+    logger.verbose(`Using explicit local log file: ${options.logFile}`);
+  }
+  if (options.sessionsDir) {
+    logger.verbose(`Using explicit local sessions directory: ${options.sessionsDir}`);
+  }
+  const report = await doctorAgentRuntime({
+    runtime: options.runtime ?? "auto",
+    logFile: options.logFile,
+    sessionsDir: options.sessionsDir,
+    onProgress: logger.verbose
+  });
+  process.stdout.write(`${renderDoctorReport(report, { commandPrefix: options.commandPrefix })}
+`);
+}
+function validateRuntimeOption2(runtime) {
+  if (!runtime) {
+    return;
+  }
+  if (runtime !== "openclaw" && runtime !== "hermes") {
+    throw new Error(
+      `Unsupported runtime "${runtime}". Use --runtime openclaw or --runtime hermes.`
+    );
+  }
+}
+function validateCursorUsageCsvOptions2(options) {
+  if (!options.cursorUsageCsv) {
+    return;
+  }
+  const conflicts = [
+    options.runtime ? "--runtime" : null,
+    options.logFile ? "--log-file" : null,
+    options.sessionsDir ? "--sessions-dir" : null,
+    options.remote ? "--remote" : null,
+    options.remoteLogFile ? "--remote-log-file" : null,
+    options.remoteSessionsDir ? "--remote-sessions-dir" : null,
+    options.railway ? "--railway" : null,
+    options.railwayProject ? "--project" : null,
+    options.railwayEnvironment ? "--environment" : null,
+    options.railwayService ? "--service" : null
+  ].filter((flag) => flag !== null);
+  if (conflicts.length > 0) {
+    throw new Error(`The --cursor-usage-csv flag cannot be combined with ${conflicts.join(", ")}.`);
+  }
+}
+function validateHermesLocalOnly2(options) {
+  if (options.runtime !== "hermes") {
+    return;
+  }
+  const conflicts = [
+    options.remote ? "--remote" : null,
+    options.remoteLogFile ? "--remote-log-file" : null,
     options.remoteSessionsDir ? "--remote-sessions-dir" : null,
     options.railway ? "--railway" : null,
     options.railwayProject ? "--project" : null,
@@ -5470,121 +5981,269 @@ function renderRailwayDoctorReport(report) {
       );
     }
   }
-  sections.push("", "## Notes", ...report.notes.map((n) => `[railway] ${n}`));
-  return sections.join("\n");
+  sections.push("", "## Notes", ...report.notes.map((n) => `[railway] ${n}`));
+  return sections.join("\n");
+}
+
+// src/commands/mcp-setup.ts
+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";
+async function runMcpSetupCommand() {
+  await runMcpSetupFlow();
+}
+async function runMcpSetupFlow() {
+  let config = loadPushConfigOrNull();
+  if (!config) {
+    process.stderr.write(`${renderCloudDisclaimer()}
+`);
+    process.stderr.write("Hosted MCP requires Xerg Cloud authentication before client setup.\n");
+  }
+  if (!hasPromptTty()) {
+    process.stderr.write(
+      `${formatCommand("mcp-setup")} needs an interactive terminal so it can ask which MCP client you want to configure.
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!config) {
+    const shouldLogin = await promptConfirm("Authenticate with Xerg Cloud now?", true);
+    if (!shouldLogin) {
+      process.stderr.write(
+        `Skipped hosted MCP setup. Run ${formatCommand("mcp-setup")} when you're ready.
+`
+      );
+      return;
+    }
+    config = await authenticateAndLoadPushConfig();
+  }
+  process.stderr.write(`${renderMcpCredentialSourceMessage(config)}
+`);
+  const client = await promptSelect("Which MCP client do you want to configure?", [
+    {
+      name: "Cursor",
+      value: "cursor",
+      description: "Project-scoped or global Cursor MCP config"
+    },
+    {
+      name: "Claude Code",
+      value: "claude-code",
+      description: "Project-scoped Claude Code MCP config"
+    },
+    {
+      name: "Other",
+      value: "other",
+      description: "Print the hosted HTTP MCP snippet for another client"
+    }
+  ]);
+  const snippet = JSON.stringify(buildHostedMcpConfig(config), null, 2);
+  if (client === "cursor") {
+    await handleCursorSetup(snippet, config);
+    return;
+  }
+  process.stdout.write(`${snippet}
+`);
+  if (client === "claude-code") {
+    process.stderr.write(
+      "Add this to `.mcp.json` in your project root, or import the same `mcpServers.xerg` config through Claude Code MCP settings.\n"
+    );
+    return;
+  }
+  process.stderr.write(
+    `Add this as a remote HTTP MCP server in your client. Endpoint: ${HOSTED_MCP_URL}
+`
+  );
+}
+async function handleCursorSetup(snippet, config) {
+  const cursorDir = join8(process.cwd(), ".cursor");
+  const cursorConfigPath = join8(cursorDir, "mcp.json");
+  if (existsSync2(cursorDir)) {
+    const shouldWrite = await promptConfirm(
+      "Write a project-scoped Cursor MCP config to .cursor/mcp.json?",
+      true
+    );
+    if (shouldWrite) {
+      writeCursorConfig(cursorConfigPath, config);
+      process.stderr.write(`Wrote hosted MCP config to ${cursorConfigPath}.
+`);
+      return;
+    }
+  }
+  process.stdout.write(`${snippet}
+`);
+  process.stderr.write(
+    "Add this to `.cursor/mcp.json` for a project-scoped Cursor config, or `~/.cursor/mcp.json` for a global Cursor config.\n"
+  );
+}
+function buildHostedMcpConfig(config) {
+  return {
+    mcpServers: {
+      xerg: {
+        type: "http",
+        url: HOSTED_MCP_URL,
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`
+        }
+      }
+    }
+  };
+}
+function writeCursorConfig(filePath, config) {
+  mkdirSync6(dirname3(filePath), { recursive: true });
+  let parsed = {};
+  if (existsSync2(filePath)) {
+    try {
+      parsed = JSON.parse(readFileSync9(filePath, "utf8"));
+    } catch {
+      throw new Error(`Cursor config is not valid JSON: ${filePath}`);
+    }
+  }
+  const existingServers = parsed.mcpServers;
+  if (existingServers && typeof existingServers !== "object") {
+    throw new Error(`Cursor config has an invalid "mcpServers" value: ${filePath}`);
+  }
+  parsed.mcpServers = {
+    ...existingServers ?? {},
+    xerg: buildHostedMcpConfig(config).mcpServers.xerg
+  };
+  writeFileSync2(filePath, `${JSON.stringify(parsed, null, 2)}
+`);
 }
 
-// src/commands/login.ts
-import { styleText } from "util";
-var DEFAULT_AUTH_URL = "https://xerg.ai/dashboard/settings";
-var DEFAULT_API_URL2 = "https://api.xerg.ai";
-var POLL_INTERVAL_MS = 2e3;
-var POLL_TIMEOUT_MS = 3e5;
-async function runLoginCommand() {
-  const existing = loadStoredCredentials();
-  if (existing) {
+// src/commands/init.ts
+async function runInitCommand() {
+  if (!hasPromptTty()) {
     process.stderr.write(
-      `Already logged in. Credentials stored at ${getCredentialsPath()}.
-Run ${colorBold(formatCommand("logout"))} first to re-authenticate.
+      `${formatCommand("init")} is interactive in this release. Run ${formatCommand("audit")} directly when you need a non-interactive audit.
 `
     );
+    process.exitCode = 1;
+    return;
+  }
+  const candidates = await resolveRuntimeCandidates({ runtime: "auto" });
+  const usable = candidates.filter((candidate) => candidate.usable);
+  if (usable.length === 0) {
+    renderNoDataGuidance();
+    return;
+  }
+  const runtime = await chooseRuntime(usable);
+  if (!runtime) {
     return;
   }
-  const apiUrl = process.env.XERG_API_URL || DEFAULT_API_URL2;
-  const deviceCodeUrl = `${apiUrl}/v1/auth/device-code`;
-  let deviceResponse;
   try {
-    const res = await fetch(deviceCodeUrl, { method: "POST" });
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    const summary = await auditAgentRuntime({
+      runtime,
+      commandPrefix: formatCommand("")
+    });
+    process.stdout.write(`${renderTerminalSummary(summary)}
+`);
+    process.stderr.write(
+      `
+Next: after you make a fix, run ${formatCommand("audit --compare")} to measure the delta.
+`
+    );
+    const existingAuth = loadPushConfigOrNull();
+    process.stderr.write(
+      `${existingAuth ? "Xerg Cloud authentication is already configured. You can optionally push this audit and set up hosted MCP next." : renderCloudDisclaimer()}
+`
+    );
+    const shouldConnect = await promptConfirm("Continue with optional Xerg Cloud setup?", true);
+    if (!shouldConnect) {
+      process.stderr.write(
+        `Skipped Xerg Cloud setup. Run ${formatCommand("connect")} or ${formatCommand("mcp-setup")} whenever you want the hosted follow-up.
+`
+      );
+      return;
     }
-    deviceResponse = await res.json();
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : "Unknown error";
-    throw new Error(
-      `Could not start device auth flow (${msg}).
-
-Alternative: create an API key at ${DEFAULT_AUTH_URL}
-and set XERG_API_KEY in your environment.`
+    const connected = await runConnectFlow({
+      skipDisclaimer: true,
+      auditSummary: summary
+    });
+    if (!connected) {
+      return;
+    }
+    const shouldSetupMcp = await promptConfirm("Set up hosted MCP now?", true);
+    if (!shouldSetupMcp) {
+      process.stderr.write(
+        `Skipped hosted MCP setup. Run ${formatCommand("mcp-setup")} when you're ready.
+`
+      );
+      return;
+    }
+    await runMcpSetupFlow();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    const productName = getRuntimeAdapter(runtime).productName;
+    process.stderr.write(
+      `${[
+        `${productName} audit failed: ${message}`,
+        `Try ${formatCommand(["doctor", "--runtime", runtime])} to inspect the detected paths first.`,
+        `Re-run ${formatCommand("audit --verbose")} for more detail.`
+      ].join("\n")}
+`
     );
+    process.exitCode = 1;
   }
-  const verifyUrl = deviceResponse.verificationUrl || DEFAULT_AUTH_URL;
-  const pollInterval = (deviceResponse.interval || 2) * 1e3;
-  process.stderr.write(
-    `
-Open this URL in your browser to authenticate:
-
-  ${colorBold(verifyUrl)}
-
-`
-  );
-  if (deviceResponse.userCode) {
-    process.stderr.write(`Your code: ${colorBold(deviceResponse.userCode)}
-
+}
+async function chooseRuntime(candidates) {
+  if (candidates.length === 1) {
+    const candidate = candidates[0];
+    process.stderr.write(`${describeCandidate(candidate)}
 `);
-  }
-  process.stderr.write("Waiting for authentication...\n");
-  await openBrowser(verifyUrl);
-  const tokenUrl = `${apiUrl}/v1/auth/device-token`;
-  const startTime = Date.now();
-  while (Date.now() - startTime < POLL_TIMEOUT_MS) {
-    await sleep(Math.max(pollInterval, POLL_INTERVAL_MS));
-    try {
-      const res = await fetch(tokenUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ deviceCode: deviceResponse.deviceCode })
-      });
-      if (res.status === 200) {
-        const data = await res.json();
-        storeCredentials(data.token);
-        const teamInfo = data.teamName ? ` (team: ${data.teamName})` : "";
-        process.stderr.write(
-          `
-${colorSuccess("Authenticated successfully")}${teamInfo}.
-Credentials saved to ${getCredentialsPath()}.
+    const shouldAudit = await promptConfirm(
+      `Run your first ${candidate.adapter.productName} audit now?`,
+      true
+    );
+    if (!shouldAudit) {
+      process.stderr.write(
+        `Skipped the first audit. Run ${formatCommand(["audit", "--runtime", candidate.adapter.runtime])} when you're ready.
 `
-        );
-        return;
-      }
-      if (res.status === 428) {
-        continue;
-      }
-      if (res.status === 410) {
-        throw new Error(`Device code expired. Please run \`${formatCommand("login")}\` again.`);
-      }
-      const body = await res.json().catch(() => ({}));
-      throw new Error(body.error || `Unexpected response: HTTP ${res.status}`);
-    } catch (err) {
-      if (err instanceof Error && (err.message.includes("expired") || err.message.includes("Unexpected"))) {
-        throw err;
-      }
+      );
+      return null;
     }
+    return candidate.adapter.runtime;
   }
-  throw new Error(`Authentication timed out. Please run \`${formatCommand("login")}\` again.`);
-}
-async function openBrowser(url) {
-  const { exec } = await import("child_process");
-  const { platform: platform2 } = await import("os");
-  const commands = {
-    darwin: "open",
-    win32: "start",
-    linux: "xdg-open"
-  };
-  const cmd = commands[platform2()];
-  if (!cmd) return;
-  return new Promise((resolve4) => {
-    exec(`${cmd} ${JSON.stringify(url)}`, () => resolve4());
-  });
+  return promptSelect("Choose the local runtime to audit first.", [
+    ...candidates.map((candidate) => ({
+      name: candidate.adapter.productName,
+      value: candidate.adapter.runtime,
+      description: describeSources(candidate)
+    }))
+  ]);
 }
-function sleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+function describeCandidate(candidate) {
+  return `Found local ${candidate.adapter.productName} data (${describeSources(candidate)}).`;
 }
-function colorBold(text) {
-  return process.stderr.isTTY ? styleText("bold", text) : text;
+function describeSources(candidate) {
+  const kinds = new Set(candidate.sources.map((source) => source.kind));
+  const details = [
+    kinds.has("gateway") ? "gateway logs" : null,
+    kinds.has("sessions") ? "session transcripts" : null
+  ].filter((detail) => detail !== null);
+  return details.join(" and ");
 }
-function colorSuccess(text) {
-  return process.stderr.isTTY ? styleText("green", text) : text;
+function renderNoDataGuidance() {
+  const openclawDefaults = getRuntimeAdapter("openclaw").defaultPaths();
+  const hermesDefaults = getRuntimeAdapter("hermes").defaultPaths();
+  process.stderr.write(
+    `${[
+      "No local OpenClaw or Hermes data was detected in the default locations Xerg checked.",
+      "",
+      "Checked defaults:",
+      `- OpenClaw gateway logs: ${openclawDefaults.gatewayPattern}`,
+      `- OpenClaw session transcripts: ${openclawDefaults.sessionsPattern}`,
+      `- Hermes gateway logs: ${hermesDefaults.gatewayPattern}`,
+      `- Hermes session transcripts: ${hermesDefaults.sessionsPattern}`,
+      "",
+      "Next steps:",
+      `- Local OpenClaw paths: ${formatCommand("audit --runtime openclaw --log-file /path/to/openclaw.log")} or ${formatCommand("audit --runtime openclaw --sessions-dir /path/to/sessions")}`,
+      `- Local Hermes paths: ${formatCommand("audit --runtime hermes --log-file ~/.hermes/logs/agent.log")} or ${formatCommand("audit --runtime hermes --sessions-dir ~/.hermes/sessions")}`,
+      `- Remote OpenClaw only: ${formatCommand("audit --remote user@host")}`,
+      `- Railway OpenClaw only: ${formatCommand("audit --railway")}`
+    ].join("\n")}
+`
+  );
 }
 
 // src/commands/logout.ts
@@ -5598,103 +6257,51 @@ function runLogoutCommand() {
   }
 }
 
-// src/commands/push.ts
-import { readFileSync as readFileSync8 } from "fs";
-async function runPushCommand(options) {
-  const payload = options.file ? loadPayloadFromFile(options.file) : loadPayloadFromCache();
-  if (options.dryRun) {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}
-`);
-    return;
-  }
-  const config = loadPushConfig();
-  const auditId = payload.summary.auditId;
-  process.stderr.write(`Pushing audit ${auditId} to ${config.apiUrl}...
-`);
-  const result = await pushAudit(payload, config);
-  if (result.ok) {
-    process.stderr.write(`Pushed successfully (audit: ${result.auditId}).
-`);
-  } else {
-    const statusInfo = result.status > 0 ? ` (HTTP ${result.status})` : "";
-    throw new Error(`Push failed${statusInfo}: ${result.message}`);
-  }
-}
-function loadPayloadFromFile(filePath) {
-  let raw;
-  try {
-    raw = readFileSync8(filePath, "utf8");
-  } catch {
-    throw new Error(`Cannot read file: ${filePath}`);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`File is not valid JSON: ${filePath}`);
-  }
-  const payload = parsed;
-  if (!payload.version || !payload.summary || !payload.meta) {
-    throw new Error(
-      `File does not look like an AuditPushPayload (missing version, summary, or meta): ${filePath}`
-    );
-  }
-  return payload;
-}
-function loadPayloadFromCache() {
-  const dbPath = getDefaultDbPath();
-  let summaries;
-  try {
-    summaries = listStoredAuditSummaries(dbPath);
-  } catch {
-    throw new NoDataError(
-      `No local audit database found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
-    );
-  }
-  if (summaries.length === 0) {
-    throw new NoDataError(
-      `No cached audit snapshots found. Run \`${formatCommand("audit")}\` first, or use \`${formatCommand("push --file <path>")}\`.`
-    );
-  }
-  const latest = summaries[0];
-  const meta = buildMeta2(latest);
-  process.stderr.write(
-    `Using most recent cached audit: ${latest.auditId} (${latest.generatedAt})
-`
-  );
-  return toWirePayload(latest, meta);
-}
-function buildMeta2(summary) {
-  const sourceMeta = buildCachedPushSourceMeta(summary);
-  return {
-    cliVersion: getCliVersion(),
-    sourceId: sourceMeta.sourceId,
-    sourceHost: sourceMeta.sourceHost,
-    environment: sourceMeta.environment
-  };
-}
-
 // src/help.ts
 function renderRootHelp(version, display) {
   return `${display.name} ${version}
 
-Waste intelligence for OpenClaw and Hermes workflows plus local Cursor usage CSVs.
+Waste intelligence for OpenClaw and Hermes workflows.
 
 Usage:
   ${formatCommand("<command> [options]", display.prefix)}
 
-Commands:
+Getting started:
+  init       Detect local runtimes, run a first audit, and offer optional cloud follow-up.
+
+Audit and inspect:
   audit    Analyze OpenClaw or Hermes logs, or a local Cursor usage CSV.
   doctor   Inspect OpenClaw or Hermes sources, or a local Cursor usage CSV.
+
+Cloud:
+  connect    Authenticate and optionally push your latest audit to Xerg Cloud.
   push     Push a cached audit snapshot to the Xerg API.
   login    Authenticate with the Xerg API via browser.
   logout   Remove stored Xerg API credentials.
+  mcp-setup  Generate hosted MCP client configuration.
 
 Global options:
   -h, --help     Show help
   -v, --version  Show version
 `;
 }
+function renderInitHelp(commandPrefix) {
+  return `${formatCommand("init", commandPrefix)}
+
+Detect local OpenClaw or Hermes runtimes, run a first audit, and offer optional cloud follow-up.
+
+Usage:
+  ${formatCommand("init", commandPrefix)}
+
+Notes:
+  - Interactive only in v1
+  - Uses local runtime auto-detection
+  - Runs a first local audit with snapshot persistence enabled
+  - Offers optional Xerg Cloud connect and hosted MCP setup after a successful audit
+
+  -h, --help                  Show help
+`;
+}
 function renderAuditHelp(commandPrefix) {
   return `${formatCommand("audit", commandPrefix)}
 
@@ -5761,7 +6368,7 @@ Options:
 
 Authentication:
   Set XERG_API_KEY in your environment, add "apiKey" to ~/.xerg/config.json,
-  or run \`${formatCommand("login", commandPrefix)}\` to authenticate via browser.
+  or run \`${formatCommand("connect", commandPrefix)}\` / \`${formatCommand("login", commandPrefix)}\` to authenticate via browser.
   Browser login stores a token at ~/.config/xerg/credentials.json by default.
 `;
 }
@@ -5798,6 +6405,40 @@ Railway options (OpenClaw only):
   -h, --help                  Show help
 `;
 }
+function renderConnectHelp(commandPrefix) {
+  return `${formatCommand("connect", commandPrefix)}
+
+Authenticate with Xerg Cloud and optionally push the latest audit.
+
+Usage:
+  ${formatCommand("connect", commandPrefix)}
+
+Notes:
+  - Shows paid-workspace disclosure before hosted setup
+  - Reuses existing auth from XERG_API_KEY, ~/.xerg/config.json, or stored browser login
+  - Standalone non-interactive mode reports auth status and skips the push prompt
+  - When called after ${formatCommand("init", commandPrefix)}, it can push the in-memory audit directly
+
+  -h, --help                  Show help
+`;
+}
+function renderMcpSetupHelp(commandPrefix) {
+  return `${formatCommand("mcp-setup", commandPrefix)}
+
+Generate hosted MCP client configuration for Cursor, Claude Code, or another MCP client.
+
+Usage:
+  ${formatCommand("mcp-setup", commandPrefix)}
+
+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
+  - Local audits and compare stay available even if you skip hosted MCP setup
+
+  -h, --help                  Show help
+`;
+}
 
 // src/index.ts
 var VERSION = getCliVersion();
@@ -5831,6 +6472,11 @@ async function run() {
     });
     return;
   }
+  if (command === "init") {
+    parseBareCommandOptions(argv.slice(1), renderInitHelp(commandDisplay.prefix), "init");
+    await runInitCommand();
+    return;
+  }
   if (command === "doctor") {
     const options = parseDoctorOptions(argv.slice(1));
     await runDoctorCommand({
@@ -5844,6 +6490,11 @@ async function run() {
     await runPushCommand(options);
     return;
   }
+  if (command === "connect") {
+    parseBareCommandOptions(argv.slice(1), renderConnectHelp(commandDisplay.prefix), "connect");
+    await runConnectCommand();
+    return;
+  }
   if (command === "login") {
     await runLoginCommand();
     return;
@@ -5852,10 +6503,31 @@ async function run() {
     runLogoutCommand();
     return;
   }
+  if (command === "mcp-setup") {
+    parseBareCommandOptions(argv.slice(1), renderMcpSetupHelp(commandDisplay.prefix), "mcp-setup");
+    await runMcpSetupCommand();
+    return;
+  }
   throw new Error(
     `Unknown command "${command}". Run \`${formatCommand("--help", commandDisplay.prefix)}\` to see available commands.`
   );
 }
+function parseBareCommandOptions(raw, helpText, commandName) {
+  const argv2 = expandEqualsArgs(raw);
+  for (const arg of argv2) {
+    switch (arg) {
+      case "--help":
+      case "-h":
+        process.stdout.write(helpText);
+        process.exit(0);
+        break;
+      default:
+        throw new Error(
+          `Unknown ${commandName} option "${arg}". Run \`${formatCommand([commandName, "--help"], commandDisplay.prefix)}\` for usage.`
+        );
+    }
+  }
+}
 function parseAuditOptions(raw) {
   const argv2 = expandEqualsArgs(raw);
   const options = {};