@xerg/cli 0.3.0 → 0.4.0

package/dist/index.js

@@ -3887,7 +3887,8 @@ function loadPushConfig() {
   if (envKey) {
     return {
       apiKey: envKey,
-      apiUrl: envUrl || DEFAULT_API_URL
+      apiUrl: envUrl || DEFAULT_API_URL,
+      source: "env"
     };
   }
   try {
@@ -3896,7 +3897,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 +3907,8 @@ function loadPushConfig() {
   if (storedToken) {
     return {
       apiKey: storedToken,
-      apiUrl: envUrl || DEFAULT_API_URL
+      apiUrl: envUrl || DEFAULT_API_URL,
+      source: "stored"
     };
   }
   throw new Error(
@@ -5255,6 +5258,348 @@ function cleanupPullResult(pullResult, keepFiles) {
   }
 }
 
+// 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;
+  }
+  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()}.
+`
+  );
+}
+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(
+      `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 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)}
+
+`);
+  }
+  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 });
@@ -5470,121 +5815,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 +6091,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 +6202,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 +6239,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 +6306,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 +6324,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 +6337,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 = {};