@mutagent/cli 0.1.198 → 0.1.200

package/dist/bin/cli.js

@@ -728,7 +728,7 @@ var init_sdk_client = __esm(() => {
 // src/bin/cli.ts
 import { Command as Command12 } from "commander";
 import chalk18 from "chalk";
-import { readFileSync as readFileSync9, existsSync as existsSync10 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { join as join12, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -737,8 +737,8 @@ init_config();
 init_sdk_client();
 import { Command } from "commander";
 import chalk4 from "chalk";
-import { existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { join as join6 } from "path";
 
 // src/lib/output.ts
 import chalk from "chalk";
@@ -937,478 +937,923 @@ init_errors();
 
 // src/commands/onboarding.ts
 import chalk2 from "chalk";
-async function runPostOnboarding() {
-  const inquirer = (await import("inquirer")).default;
-  console.log("");
-  console.log(chalk2.bold.cyan("  You are authenticated. What would you like to do next?"));
-  console.log("");
-  const { path: selectedPath } = await inquirer.prompt([{
-    type: "list",
-    name: "path",
-    message: "Choose your path:",
-    choices: [
-      {
-        name: `${chalk2.green("A")} Initialize this project — create .mutagentrc.json + install the CLI skill`,
-        value: "init"
-      },
-      {
-        name: `${chalk2.green("B")} Install a lifecycle tool — helix / diagnostics / evaluator`,
-        value: "install"
-      },
-      {
-        name: `${chalk2.green("C")} Exit — explore the CLI on your own`,
-        value: "exit"
-      }
-    ]
-  }]);
-  console.log("");
-  if (selectedPath === "init") {
-    console.log(chalk2.bold("  Project setup:"));
-    console.log("");
-    console.log(`    1. ${chalk2.green("mutagent init")}`);
-    console.log("       Scaffold .mutagentrc.json and select your workspace");
-    console.log("");
-    console.log(`    2. ${chalk2.green("mutagent skills install")}`);
-    console.log("       Install the MutagenT CLI skill for AI coding agents");
-    console.log("");
-    console.log(`    3. ${chalk2.green("mutagent providers list")}`);
-    console.log("       Confirm an LLM provider is configured");
-    console.log("");
-  } else if (selectedPath === "install") {
-    console.log(chalk2.bold("  Install a lifecycle tool:"));
-    console.log("");
-    console.log(`    ${chalk2.green("mutagent install diagnostics")}   ${chalk2.dim("Root-cause analysis from your traces")}`);
-    console.log(`    ${chalk2.green("mutagent install evaluator")}     ${chalk2.dim("Build trustworthy eval suites")}`);
-    console.log(`    ${chalk2.green("mutagent install helix")}         ${chalk2.dim("The ADL lifecycle conductor")}`);
-    console.log("");
-    console.log(chalk2.dim("  All installs are login-gated. Run `mutagent install --help` for flags."));
-    console.log("");
-  } else {
-    console.log(chalk2.dim("  You can run `mutagent --help` anytime to see available commands."));
-    console.log(chalk2.dim('  Hit a snag? Send feedback: mutagent feedback send "what happened"'));
-    console.log("");
-  }
-}
 
-// src/lib/auth-flow.ts
+// src/lib/rc-config.ts
 init_config();
-init_sdk_client();
-init_errors();
-import inquirer from "inquirer";
-import chalk3 from "chalk";
-import ora from "ora";
+import { join as join4 } from "path";
+import { writeFileSync as writeFileSync2 } from "fs";
 
-// src/lib/browser-auth.ts
-import { hostname, platform } from "os";
-function generateCliToken() {
-  return crypto.randomUUID();
-}
-async function initBrowserAuth(endpoint, cliToken) {
-  const response = await fetch(`${endpoint}/api/auth/cli/init`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      cliToken,
-      hostname: hostname(),
-      platform: platform()
-    })
-  });
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new BrowserAuthError("INIT_FAILED", "Failed to initialize browser auth: " + String(response.status) + " " + errorText);
+// src/lib/framework-detection.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { execSync } from "child_process";
+import { join as join3 } from "path";
+var FRAMEWORK_DETECTION_MAP = {
+  "@mastra/core": {
+    name: "mastra",
+    displayName: "Mastra",
+    npmPackage: "@mastra/core"
+  },
+  "@langchain/langgraph": {
+    name: "langgraph",
+    displayName: "LangGraph",
+    npmPackage: "@langchain/langgraph",
+    mutagentPackage: "@mutagent/langgraph"
+  },
+  langchain: {
+    name: "langchain",
+    displayName: "LangChain",
+    npmPackage: "langchain",
+    mutagentPackage: "@mutagent/langchain"
+  },
+  "@langchain/core": {
+    name: "langchain",
+    displayName: "LangChain",
+    npmPackage: "@langchain/core",
+    mutagentPackage: "@mutagent/langchain"
+  },
+  "@ai-sdk/core": {
+    name: "vercel-ai",
+    displayName: "Vercel AI SDK",
+    npmPackage: "@ai-sdk/core",
+    mutagentPackage: "@mutagent/vercel-ai"
+  },
+  ai: {
+    name: "vercel-ai",
+    displayName: "Vercel AI SDK",
+    npmPackage: "ai",
+    mutagentPackage: "@mutagent/vercel-ai"
+  },
+  "@google/genai": {
+    name: "generic",
+    displayName: "Google GenAI",
+    npmPackage: "@google/genai"
+  },
+  openai: {
+    name: "openai",
+    displayName: "OpenAI SDK",
+    npmPackage: "openai",
+    mutagentPackage: "@mutagent/openai"
   }
-  const data = await response.json();
-  return data;
-}
-async function pollAuthStatus(endpoint, cliToken) {
-  const response = await fetch(`${endpoint}/api/auth/cli/status?token=${encodeURIComponent(cliToken)}`);
-  if (!response.ok) {
-    const errorText = await response.text();
-    throw new BrowserAuthError("POLL_FAILED", "Failed to poll auth status: " + String(response.status) + " " + errorText);
+};
+function detectPackageManager(cwd = process.cwd()) {
+  if (existsSync3(join3(cwd, "bun.lockb")) || existsSync3(join3(cwd, "bun.lock"))) {
+    return "bun";
   }
-  const data = await response.json();
-  return data;
-}
-async function openBrowser(url) {
-  if (process.env.MUTAGENT_TEST_MODE === "true") {
-    console.log(`AUTH_URL:${url}`);
-    return;
+  if (existsSync3(join3(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (existsSync3(join3(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (existsSync3(join3(cwd, "package-lock.json"))) {
+    return "npm";
   }
   try {
-    const { default: open } = await import("open");
-    await open(url);
+    execSync("bun --version", { stdio: "ignore" });
+    return "bun";
   } catch {
-    throw new BrowserAuthError("BROWSER_OPEN_FAILED", `Could not open browser automatically. Please visit: ${url}`);
+    return "npm";
   }
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function getInstallCommand(pm, packages) {
+  const pkgList = packages.join(" ");
+  const commands = {
+    bun: `bun add ${pkgList}`,
+    npm: `npm install ${pkgList}`,
+    yarn: `yarn add ${pkgList}`,
+    pnpm: `pnpm add ${pkgList}`
+  };
+  return commands[pm];
 }
-async function performBrowserAuth(options, onStatusUpdate) {
-  const {
-    endpoint,
-    timeout = 300000,
-    pollInterval = 2000,
-    skipBrowserOpen = false
-  } = options;
-  const cliToken = generateCliToken();
-  onStatusUpdate?.("Initializing browser authentication...");
-  const initResponse = await initBrowserAuth(endpoint, cliToken);
-  const { authUrl } = initResponse;
-  if (!skipBrowserOpen) {
-    onStatusUpdate?.("Opening browser for authentication...");
-    try {
-      await openBrowser(authUrl);
-    } catch (error) {
-      if (error instanceof BrowserAuthError && error.code === "BROWSER_OPEN_FAILED") {
-        onStatusUpdate?.(error.message);
-      } else {
-        throw error;
-      }
-    }
+function detectFrameworkFromPackageJson(cwd = process.cwd()) {
+  const pkgPath = join3(cwd, "package.json");
+  if (!existsSync3(pkgPath)) {
+    return null;
   }
-  console.log("");
-  console.log("  Open this URL to authenticate:");
-  console.log("");
-  console.log("  " + authUrl);
-  console.log("");
-  onStatusUpdate?.("Waiting for browser authentication...");
-  const startTime = Date.now();
-  while (Date.now() - startTime < timeout) {
-    await sleep(pollInterval);
-    const status = await pollAuthStatus(endpoint, cliToken);
-    switch (status.status) {
-      case "pending":
-        continue;
-      case "completed":
-        if (!status.apiKey || !status.workspaceId || !status.workspaceName || !status.organizationId || !status.organizationName) {
-          throw new BrowserAuthError("INCOMPLETE_RESPONSE", "Server returned incomplete auth response");
-        }
-        return {
-          apiKey: status.apiKey,
-          workspaceId: status.workspaceId,
-          workspaceName: status.workspaceName,
-          organizationId: status.organizationId,
-          organizationName: status.organizationName,
-          expiresAt: status.expiresAt
-        };
-      case "expired":
-        throw new BrowserAuthError("AUTH_EXPIRED", "Browser authentication expired. Please try again.");
-      case "denied":
-        throw new BrowserAuthError("AUTH_DENIED", status.error ?? "Browser authentication was denied.");
-      case "not_found":
-        throw new BrowserAuthError("TOKEN_NOT_FOUND", "Authentication token not found. Please try again.");
-      default:
-        throw new BrowserAuthError("UNKNOWN_STATUS", "Unknown auth status: " + String(status.status));
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+  } catch {
+    return null;
+  }
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies
+  };
+  for (const [depName, framework] of Object.entries(FRAMEWORK_DETECTION_MAP)) {
+    if (depName in allDeps) {
+      return framework;
     }
   }
-  throw new BrowserAuthError("AUTH_TIMEOUT", "Browser authentication timed out after 5 minutes. Please try again.");
+  return null;
+}
+function hasRcConfig(cwd = process.cwd()) {
+  return existsSync3(join3(cwd, ".mutagentrc.json"));
 }
 
-class BrowserAuthError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "BrowserAuthError";
-    this.code = code;
-  }
-  getSuggestion() {
-    switch (this.code) {
-      case "INIT_FAILED":
-        return "Check your endpoint configuration and network connection.";
-      case "POLL_FAILED":
-        return "Check your network connection and try again.";
-      case "BROWSER_OPEN_FAILED":
-        return "Copy the URL above and open it manually in your browser.";
-      case "AUTH_EXPIRED":
-      case "AUTH_TIMEOUT":
-        return 'Run "mutagent auth login" again to restart authentication.';
-      case "AUTH_DENIED":
-        return "Ensure you have access to the workspace and try again.";
-      case "TOKEN_NOT_FOUND":
-      case "INCOMPLETE_RESPONSE":
-      case "UNKNOWN_STATUS":
-        return "Please try again. If the issue persists, contact support.";
-      default:
-        return "Please try again.";
-    }
+// src/lib/rc-config.ts
+function writeRcConfig(config, cwd = process.cwd()) {
+  const rcPath = join4(cwd, ".mutagentrc.json");
+  writeFileSync2(rcPath, JSON.stringify(config, null, 2) + `
+`);
+}
+function scaffoldRcConfig(cwd = process.cwd(), deps = {}) {
+  const load = deps.loadConfig ?? loadConfig;
+  const hasRc = deps.hasRcConfig ?? hasRcConfig;
+  const write = deps.writeRcConfig ?? writeRcConfig;
+  const cfg = load();
+  const rcConfig = {
+    endpoint: cfg.endpoint ?? "https://api.mutagent.io",
+    ...cfg.defaultWorkspace ? { defaultWorkspace: cfg.defaultWorkspace } : {},
+    ...cfg.defaultOrganization ? { defaultOrganization: cfg.defaultOrganization } : {}
+  };
+  if (hasRc(cwd)) {
+    return { created: false, alreadyPresent: true, config: rcConfig };
   }
+  write(rcConfig, cwd);
+  return { created: true, alreadyPresent: false, config: rcConfig };
 }
 
-// src/lib/auth-flow.ts
-async function performLoginAction(opts) {
-  const { isJson, output } = opts;
-  const wasFirstLogin = !hasCredentials();
-  const envApiKey = process.env.MUTAGENT_API_KEY;
-  const endpoint = process.env.MUTAGENT_ENDPOINT ?? opts.endpoint;
-  if (envApiKey) {
-    return loginWithExistingKey(envApiKey, endpoint, output, wasFirstLogin);
-  }
-  const isNonInteractive = opts.nonInteractive === true || process.env.MUTAGENT_NON_INTERACTIVE === "true" || process.env.CI === "true" || !process.stdin.isTTY;
-  if (isJson && !opts.browser && isNonInteractive) {
-    throw new MutagentError("INTERACTIVE_REQUIRED", "No API key provided. Set MUTAGENT_API_KEY env var or add --browser for browser auth.", "Run: export MUTAGENT_API_KEY=<key> or mutagent login --browser --non-interactive");
+// src/lib/installer.ts
+init_errors();
+init_config();
+import { spawn as spawn2 } from "child_process";
+
+// src/lib/installer-helix.ts
+init_errors();
+init_config();
+import { spawn } from "child_process";
+import { createHash } from "crypto";
+import { homedir as homedir2 } from "os";
+import { join as join5 } from "path";
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+async function installHelix(opts, deps = {}) {
+  const auth = (deps.resolveAuth ?? defaultResolveAuth)();
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const descriptor = await fetchDescriptor(fetchImpl, auth, opts.version);
+  const baseDir = deps.homeDir ?? join5(homedir2(), ".mutagent", "helix");
+  const versionDir = join5(baseDir, descriptor.version);
+  mkdirSync2(versionDir, { recursive: true });
+  const tgzPath = join5(versionDir, `helix-plugin-${descriptor.version}.tgz`);
+  const tmpPath = `${tgzPath}.${String(process.pid)}.${String(Date.now())}.part`;
+  const download = deps.download ?? defaultDownload;
+  await download(descriptor.url, tmpPath);
+  const sha256 = deps.sha256 ?? defaultSha256;
+  const actual = (await sha256(tmpPath)).toLowerCase();
+  const expected = descriptor.sha256.toLowerCase();
+  if (actual !== expected) {
+    safeRm(tmpPath);
+    throw new MutagentError("INTEGRITY_ERROR", `Downloaded helix plugin failed sha256 verification (expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…).`, "The download may be corrupt or tampered with. Retry: mutagent install helix");
   }
-  if (!isNonInteractive && wasFirstLogin) {
-    console.log(`
-` + chalk3.bold.cyan("  Welcome to MutagenT CLI!") + `
-`);
-    console.log(`  No credentials found. Please authenticate to continue.
-`);
+  renameSync(tmpPath, tgzPath);
+  const extract = deps.extract ?? defaultExtract;
+  await extract(tgzPath, versionDir);
+  const locateInitBin = deps.locateInitBin ?? defaultLocateInitBin;
+  const binPath = await locateInitBin(versionDir);
+  const initArgs = ["init", "--harness", opts.harness];
+  if (opts.global)
+    initArgs.push("--global");
+  const runInit = deps.runInit ?? defaultRunInit;
+  const code = await runInit(binPath, initArgs, process.cwd());
+  if (code !== 0) {
+    throw new MutagentError("INSTALL_FAILED", `helix plugin init exited with code ${String(code)}.`, "Re-run: mutagent install helix — or run the plugin init manually and report the error.");
   }
-  let useBrowserAuth = opts.browser === true;
-  if (!useBrowserAuth && isNonInteractive) {
-    output.info("Non-interactive environment detected. Using browser authentication.");
-    useBrowserAuth = true;
+  await postTelemetry(fetchImpl, auth, {
+    pkg: "helix",
+    version: descriptor.version,
+    harness: opts.harness,
+    cliVersion: deps.cliVersion ?? readCliVersion()
+  });
+  return { version: descriptor.version };
+}
+async function fetchDescriptor(fetchImpl, auth, version) {
+  if (!auth.apiKey) {
+    throw new MutagentError("AUTH_REQUIRED", "Authentication required to install helix.", "Run: mutagent login");
   }
-  if (!useBrowserAuth) {
-    const methodAnswer = await inquirer.prompt([
-      {
-        type: "list",
-        name: "method",
-        message: "How would you like to authenticate?",
-        choices: [
-          { name: "Login (opens browser)", value: "browser" },
-          { name: "API Key (paste existing key)", value: "apiKey" }
-        ]
-      }
-    ]);
-    useBrowserAuth = methodAnswer.method === "browser";
+  const url = `${auth.apiBase}/api/helix/plugin/download?version=${encodeURIComponent(version)}`;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: "GET",
+      headers: { "x-api-key": auth.apiKey, ...auth.headers }
+    });
+  } catch {
+    throw new MutagentError("SERVER_UNAVAILABLE", "Could not reach the MutagenT plugin broker.", "Check your network connection or verify the endpoint with: mutagent config show");
   }
-  if (useBrowserAuth) {
-    return loginWithBrowser(endpoint, output, wasFirstLogin);
+  if (res.status === 401) {
+    throw new MutagentError("AUTH_REQUIRED", "The plugin broker rejected your credentials.", "Re-authenticate: mutagent login");
   }
-  return loginWithPastedKey(endpoint, output, wasFirstLogin);
+  if (!res.ok) {
+    const detail = await readErrorMessage(res);
+    throw new MutagentError("INSTALL_FAILED", `Plugin broker returned ${String(res.status)}.${detail ? ` ${detail}` : ""}`, "Verify the requested version exists, then retry: mutagent install helix");
+  }
+  const raw = await res.json();
+  if (!isBrokerResponse(raw)) {
+    throw new MutagentError("INSTALL_FAILED", "Plugin broker returned a malformed response (missing version/sha256/url).", "Retry: mutagent install helix — if it persists, report it.");
+  }
+  return raw;
 }
-function buildLoginJsonResponse(result) {
-  return {
-    success: true,
-    authenticated: result.authenticated,
-    endpoint: result.endpoint,
-    workspace: result.workspace,
-    organization: result.organization,
-    _directive: {
-      instruction: "Verify workspace. Run: mutagent workspaces list --json",
-      next: ["mutagent workspaces list --json", "mutagent usage --json"]
-    }
-  };
+async function postTelemetry(fetchImpl, auth, event) {
+  if (!auth.apiKey)
+    return;
+  try {
+    await fetchImpl(`${auth.apiBase}/api/helix/installs`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": auth.apiKey,
+        ...auth.headers
+      },
+      body: JSON.stringify(event)
+    });
+  } catch {}
 }
-async function loginWithExistingKey(apiKey, endpoint, output, wasFirstLogin) {
-  output.info("Validating API key...");
-  const isValid = await validateApiKey(apiKey, endpoint);
-  if (!isValid) {
-    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+function defaultResolveAuth() {
+  const apiKey = getApiKey();
+  const config = loadConfig();
+  const apiBase = config.endpoint ?? "https://api.mutagent.io";
+  const headers = {};
+  if (config.defaultWorkspace)
+    headers["x-workspace-id"] = config.defaultWorkspace;
+  if (config.defaultOrganization)
+    headers["x-organization-id"] = config.defaultOrganization;
+  return { apiBase, apiKey, headers };
+}
+async function defaultDownload(url, destPath) {
+  let res;
+  try {
+    res = await globalThis.fetch(url);
+  } catch {
+    throw new MutagentError("SERVER_UNAVAILABLE", "Failed to download the helix plugin from storage.", "Check your network connection and retry: mutagent install helix");
   }
-  const orgs = await fetchOrganizations(apiKey, endpoint);
-  let orgId;
-  let orgName;
-  let wsId;
-  let wsName;
-  if (orgs.length >= 1 && orgs[0]) {
-    orgId = orgs[0].id;
-    orgName = orgs[0].name;
-    const workspaces = await fetchWorkspaces(apiKey, endpoint, orgId);
-    const defaultWs = workspaces.find((w) => w.isDefault) ?? workspaces[0];
-    if (defaultWs) {
-      wsId = defaultWs.id;
-      wsName = defaultWs.name;
-    }
+  if (!res.ok) {
+    throw new MutagentError("INSTALL_FAILED", `Plugin download failed with status ${String(res.status)}.`, "The signed URL may have expired — retry: mutagent install helix");
   }
-  saveFullCredentials({
-    apiKey,
-    endpoint,
-    workspaceId: wsId,
-    organizationId: orgId
-  });
-  return {
-    authenticated: true,
-    apiKey,
-    endpoint,
-    workspace: wsId ? { id: wsId, name: wsName } : null,
-    organization: orgId ? { id: orgId, name: orgName } : null,
-    wasFirstLogin
-  };
+  const bytes = Buffer.from(await res.arrayBuffer());
+  writeFileSync3(destPath, bytes);
 }
-async function loginWithBrowser(endpoint, output, wasFirstLogin) {
-  const spinner = ora({ text: "Opening browser for authentication...", spinner: "dots" });
-  try {
-    spinner.start();
-    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000 }, (message) => {
-      spinner.text = message;
+async function defaultSha256(filePath) {
+  return Promise.resolve(createHash("sha256").update(readFileSync4(filePath)).digest("hex"));
+}
+function defaultExtract(tgzPath, destDir) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("tar", ["-xzf", tgzPath, "-C", destDir], {
+      stdio: ["ignore", "ignore", "pipe"]
     });
-    spinner.succeed("Authenticated successfully!");
-    saveFullCredentials({
-      apiKey: result.apiKey,
-      endpoint,
-      workspaceId: result.workspaceId,
-      organizationId: result.organizationId,
-      expiresAt: result.expiresAt
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
     });
-    if (result.workspaceName)
-      output.info(`Workspace: ${result.workspaceName}`);
-    if (result.organizationName)
-      output.info(`Organization: ${result.organizationName}`);
-    return {
-      authenticated: true,
-      apiKey: result.apiKey,
-      endpoint,
-      workspace: result.workspaceId ? { id: result.workspaceId, name: result.workspaceName } : null,
-      organization: result.organizationId ? { id: result.organizationId, name: result.organizationName } : null,
-      wasFirstLogin
-    };
-  } catch (error) {
-    spinner.fail("Authentication failed");
-    if (error instanceof BrowserAuthError) {
-      throw new MutagentError(error.code, error.message, error.getSuggestion());
-    }
-    throw error;
-  }
+    child.on("error", (err) => {
+      reject(new MutagentError("INSTALL_FAILED", `Failed to extract the helix plugin: ${err.message}`, 'Ensure "tar" is installed and available on your PATH.'));
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new MutagentError("INSTALL_FAILED", `Extracting the helix plugin failed (tar exit ${String(code ?? 1)}).${stderr ? ` ${stderr.trim().slice(0, 200)}` : ""}`, "The downloaded archive may be corrupt — retry: mutagent install helix"));
+      }
+    });
+  });
 }
-async function loginWithPastedKey(initialEndpoint, output, wasFirstLogin) {
-  const answers = await inquirer.prompt([
-    {
-      type: "input",
-      name: "endpoint",
-      message: "MutagenT endpoint:",
-      default: initialEndpoint
-    },
-    {
-      type: "password",
-      name: "apiKey",
-      message: "API Key:",
-      mask: "*",
-      validate: (input) => input.length > 0 || "API key is required"
-    }
-  ]);
-  const apiKey = answers.apiKey;
-  const endpoint = answers.endpoint;
-  output.info("Validating API key...");
-  const isValid = await validateApiKey(apiKey, endpoint);
-  if (!isValid) {
-    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+function defaultLocateInitBin(extractedDir) {
+  const pkgDir = existsSync4(join5(extractedDir, "package", "package.json")) ? join5(extractedDir, "package") : extractedDir;
+  const pkgJsonPath = join5(pkgDir, "package.json");
+  if (!existsSync4(pkgJsonPath)) {
+    return Promise.reject(new MutagentError("INSTALL_FAILED", "Could not find package.json in the extracted helix plugin.", "The archive layout is unexpected — retry or report: mutagent install helix"));
   }
-  let selectedOrgId;
-  let selectedOrgName;
-  let selectedWsId;
-  let selectedWsName;
-  const orgs = await fetchOrganizations(apiKey, endpoint);
-  if (orgs.length === 1 && orgs[0]) {
-    selectedOrgId = orgs[0].id;
-    selectedOrgName = orgs[0].name;
-  } else if (orgs.length > 1) {
-    const orgAnswer = await inquirer.prompt([
-      {
-        type: "list",
-        name: "orgId",
-        message: "Select organization:",
-        choices: orgs.map((o) => ({ name: o.name, value: o.id }))
-      }
-    ]);
-    selectedOrgId = orgAnswer.orgId;
-    selectedOrgName = orgs.find((o) => o.id === selectedOrgId)?.name;
+  const raw = JSON.parse(readFileSync4(pkgJsonPath, "utf-8"));
+  const binRel = resolveBinField(raw);
+  if (!binRel) {
+    return Promise.reject(new MutagentError("INSTALL_FAILED", "The helix plugin package.json declares no runnable bin.", "The plugin package is malformed — report: mutagent install helix"));
   }
-  if (selectedOrgId) {
-    const workspaces = await fetchWorkspaces(apiKey, endpoint, selectedOrgId);
-    const defaultWs = workspaces.find((w) => w.isDefault);
-    if (workspaces.length === 1 && workspaces[0]) {
-      selectedWsId = workspaces[0].id;
-      selectedWsName = workspaces[0].name;
-    } else if (defaultWs) {
-      selectedWsId = defaultWs.id;
-      selectedWsName = defaultWs.name;
-    } else if (workspaces.length > 1) {
-      const wsAnswer = await inquirer.prompt([
-        {
-          type: "list",
-          name: "wsId",
-          message: "Select workspace:",
-          choices: workspaces.map((w) => ({
-            name: w.name + (w.isDefault ? " (default)" : ""),
-            value: w.id
-          }))
-        }
-      ]);
-      selectedWsId = wsAnswer.wsId;
-      selectedWsName = workspaces.find((w) => w.id === selectedWsId)?.name;
+  const binPath = join5(pkgDir, binRel);
+  if (!existsSync4(binPath)) {
+    return Promise.reject(new MutagentError("INSTALL_FAILED", `The helix plugin bin was not found at ${binRel}.`, "The plugin package is incomplete — report: mutagent install helix"));
+  }
+  return Promise.resolve(binPath);
+}
+function defaultRunInit(binPath, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("node", [binPath, ...args], { cwd, stdio: "inherit" });
+    child.on("error", (err) => {
+      reject(new MutagentError("INSTALL_FAILED", `Failed to run the helix plugin init: ${err.message}`, 'Ensure "node" is installed and available on your PATH.'));
+    });
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
+function resolveBinField(pkg) {
+  if (!pkg || typeof pkg !== "object")
+    return;
+  const bin = pkg.bin;
+  if (typeof bin === "string")
+    return bin;
+  if (bin && typeof bin === "object") {
+    const entries = bin;
+    const preferred = entries["mutagent-helix"];
+    if (typeof preferred === "string")
+      return preferred;
+    for (const value of Object.values(entries)) {
+      if (typeof value === "string")
+        return value;
     }
   }
-  saveFullCredentials({
-    apiKey,
-    endpoint,
-    workspaceId: selectedWsId,
-    organizationId: selectedOrgId
+  return;
+}
+function isBrokerResponse(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return typeof v.version === "string" && typeof v.sha256 === "string" && typeof v.url === "string";
+}
+async function readErrorMessage(res) {
+  try {
+    const body = await res.json();
+    if (body && typeof body === "object") {
+      const b = body;
+      if (typeof b.message === "string")
+        return b.message;
+      if (typeof b.error === "string")
+        return b.error;
+    }
+  } catch {}
+  return;
+}
+function readCliVersion() {
+  if (process.env.CLI_VERSION)
+    return process.env.CLI_VERSION;
+  return "unknown";
+}
+function safeRm(path) {
+  try {
+    rmSync(path, { force: true });
+  } catch {}
+}
+
+// src/lib/installer.ts
+var VALID_PACKAGES = ["helix", "diagnostics", "evaluator"];
+var VALID_HARNESSES = ["claude-code", "codex", "omp"];
+var VERSION_MATRIX = {
+  helix: "latest",
+  diagnostics: "latest",
+  evaluator: "latest"
+};
+var NPM_PACKAGES = {
+  diagnostics: "@mutagent/diagnostics",
+  evaluator: "@mutagent/evaluator"
+};
+var defaultRunner = (cmd, args) => new Promise((resolve, reject) => {
+  const child = spawn2(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString("utf-8");
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString("utf-8");
   });
+  child.on("error", (err) => {
+    reject(new MutagentError("INSTALL_FAILED", `Failed to run ${cmd}: ${err.message}`, `Ensure "${cmd}" is installed and available on your PATH.`));
+  });
+  child.on("close", (code) => {
+    resolve({ code: code ?? 1, stdout, stderr });
+  });
+});
+function isValidPackage(pkg) {
+  return VALID_PACKAGES.includes(pkg);
+}
+function isValidHarness(harness) {
+  return VALID_HARNESSES.includes(harness);
+}
+async function installPackage(pkg, opts, deps = {}) {
+  const isAuthed = deps.isAuthed ?? hasCredentials;
+  if (!isAuthed()) {
+    throw new MutagentError("AUTH_REQUIRED", `Authentication required to install ${pkg}.`, "Run: mutagent login");
+  }
+  if (!isValidPackage(pkg)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `Unknown package "${pkg}". Valid: ${VALID_PACKAGES.join(", ")}`, "Run: mutagent install --help");
+  }
+  if (!isValidHarness(opts.harness)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `Unknown harness "${opts.harness}". Valid: ${VALID_HARNESSES.join(", ")}`, "Run: mutagent install --help");
+  }
+  const version = opts.version ?? VERSION_MATRIX[pkg];
+  if (pkg === "helix") {
+    const { version: resolved } = await installHelix({ harness: opts.harness, global: opts.global, version }, deps.helix ?? {});
+    return {
+      package: pkg,
+      version: resolved,
+      harness: opts.harness,
+      global: opts.global
+    };
+  }
+  const npmPackage = NPM_PACKAGES[pkg];
+  const args = ["install", "-g", `${npmPackage}@${version}`];
+  const runner = deps.runner ?? defaultRunner;
+  const result = await runner("npm", args);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim();
+    throw new MutagentError("INSTALL_FAILED", `npm failed to install ${npmPackage}@${version} (exit ${String(result.code)}).${detail ? ` ${detail.slice(0, 200)}` : ""}`, "Verify the package and version exist and that you have permission for a global npm install.");
+  }
   return {
-    authenticated: true,
-    apiKey,
-    endpoint,
-    workspace: selectedWsId ? { id: selectedWsId, name: selectedWsName } : null,
-    organization: selectedOrgId ? { id: selectedOrgId, name: selectedOrgName } : null,
-    wasFirstLogin
+    package: pkg,
+    version,
+    harness: opts.harness,
+    global: opts.global,
+    command: `npm ${args.join(" ")}`
   };
 }
 
-// src/commands/auth.ts
-function createAuthCommand() {
-  const auth = new Command("auth").description("Authenticate with MutagenT platform").addHelpText("after", `
-Examples:
-  ${chalk4.dim("$")} mutagent auth login
-  ${chalk4.dim("$")} mutagent auth login --browser
-  ${chalk4.dim("$")} mutagent auth status
-  ${chalk4.dim("$")} mutagent auth logout
-    `);
-  auth.command("login").description("Authenticate and store API key").option("--browser", "Force browser-based authentication").option("--non-interactive", "Disable interactive prompts (auto-selects browser auth)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
-Examples:
-  ${chalk4.dim("$")} mutagent auth login                    ${chalk4.dim("# Interactive (choose method)")}
-  ${chalk4.dim("$")} mutagent auth login --browser          ${chalk4.dim("# Browser OAuth flow")}
-  ${chalk4.dim("$")} mutagent auth login --non-interactive  ${chalk4.dim("# Auto browser flow (AI agents)")}
-
-${chalk4.dim("Note: this command is an alias for `mutagent login`.")}
-${chalk4.dim("See `mutagent login --help` for full documentation.")}
-    `).action(async (options) => {
-    const isJson = getJsonFlag(auth);
-    const output = new OutputFormatter(isJson ? "json" : "table");
+// src/commands/onboarding.ts
+init_errors();
+var ONBOARDING_CHOICES = [
+  { name: "1) Install Helix — the Agent Development Life Cycle Orchestrator (ADLC)", value: "helix" },
+  { name: "2) Exit — explore the CLI on your own", value: "exit" }
+];
+async function defaultSelectAction(choices) {
+  const inquirer = (await import("inquirer")).default;
+  const { action } = await inquirer.prompt([{
+    type: "list",
+    name: "action",
+    message: "What would you like to do next?",
+    choices,
+    default: "helix"
+  }]);
+  return action;
+}
+async function runPostOnboarding(deps = {}) {
+  const cwd = deps.cwd ?? process.cwd();
+  const scaffold = deps.scaffoldRcConfig ?? scaffoldRcConfig;
+  const select = deps.selectAction ?? defaultSelectAction;
+  const install = deps.installPackage ?? installPackage;
+  console.log("");
+  console.log(chalk2.bold.cyan("  You are authenticated."));
+  console.log("");
+  const rc = scaffold(cwd);
+  if (rc.alreadyPresent) {
+    console.log(`  ${chalk2.green("✓")} .mutagentrc.json already present`);
+  } else {
+    console.log(`  ${chalk2.green("✓")} Created .mutagentrc.json`);
+  }
+  console.log("");
+  const action = await select(ONBOARDING_CHOICES);
+  console.log("");
+  if (action === "helix") {
+    console.log(chalk2.bold("  Installing Helix…"));
+    console.log(chalk2.dim("  Downloading + verifying the plugin, then writing .claude/ + .codex/"));
+    console.log("");
     try {
-      const result = await performLoginAction({
-        endpoint: options.endpoint,
-        browser: options.browser,
-        nonInteractive: options.nonInteractive,
-        isJson,
-        output
-      });
-      if (isJson) {
-        output.output(buildLoginJsonResponse(result));
-      } else {
-        output.success("Authenticated successfully");
-        if (result.organization?.name)
-          output.info(`Organization: ${result.organization.name}`);
-        if (result.workspace?.name)
-          output.info(`Workspace: ${result.workspace.name}`);
-        output.info(`Endpoint: ${result.endpoint}`);
-        output.info("Next: mutagent workspaces list --json");
-      }
-      if (result.wasFirstLogin && process.stdin.isTTY && !isJson) {
-        await runPostOnboarding();
-      }
+      await install("helix", { harness: "claude-code", global: true });
+      console.log("");
+      console.log(`  ${chalk2.green("✓")} Helix ready — run ${chalk2.cyan("*help")} inside your agent`);
+      console.log("");
     } catch (error) {
+      console.log("");
       if (error instanceof MutagentError) {
-        output.error(error.message);
-        process.exit(error.exitCode);
+        console.error(`  ${chalk2.red("✗")} Helix install failed: ${error.message}`);
+        if (error.suggestion)
+          console.error(`  ${chalk2.yellow("→")} ${error.suggestion}`);
+      } else {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`  ${chalk2.red("✗")} Helix install failed: ${message}`);
       }
-      throw error;
+      console.error("");
+      process.exitCode = 1;
     }
-  });
-  auth.command("status").description("Check authentication status").addHelpText("after", `
-Examples:
-  ${chalk4.dim("$")} mutagent auth status
-  ${chalk4.dim("$")} mutagent auth status --json
-    `).action(async () => {
-    const isJson = getJsonFlag(auth);
-    const output = new OutputFormatter(isJson ? "json" : "table");
-    const apiKey = getApiKey();
-    const config = loadConfig();
-    const endpoint = config.endpoint ?? "https://api.mutagent.io";
-    if (!apiKey) {
-      if (isJson) {
+  } else {
+    console.log(chalk2.dim(`  Run ${chalk2.cyan("mutagent --help")} to explore the CLI.`));
+    console.log(chalk2.dim('  Hit a snag? Send feedback: mutagent feedback send "what happened"'));
+    console.log("");
+  }
+}
+
+// src/lib/auth-flow.ts
+init_config();
+init_sdk_client();
+init_errors();
+import inquirer from "inquirer";
+import chalk3 from "chalk";
+import ora from "ora";
+
+// src/lib/browser-auth.ts
+import { hostname, platform } from "os";
+function generateCliToken() {
+  return crypto.randomUUID();
+}
+async function initBrowserAuth(endpoint, cliToken) {
+  const response = await fetch(`${endpoint}/api/auth/cli/init`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      cliToken,
+      hostname: hostname(),
+      platform: platform()
+    })
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new BrowserAuthError("INIT_FAILED", "Failed to initialize browser auth: " + String(response.status) + " " + errorText);
+  }
+  const data = await response.json();
+  return data;
+}
+async function pollAuthStatus(endpoint, cliToken) {
+  const response = await fetch(`${endpoint}/api/auth/cli/status?token=${encodeURIComponent(cliToken)}`);
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new BrowserAuthError("POLL_FAILED", "Failed to poll auth status: " + String(response.status) + " " + errorText);
+  }
+  const data = await response.json();
+  return data;
+}
+async function openBrowser(url) {
+  if (process.env.MUTAGENT_TEST_MODE === "true") {
+    console.log(`AUTH_URL:${url}`);
+    return;
+  }
+  try {
+    const { default: open } = await import("open");
+    await open(url);
+  } catch {
+    throw new BrowserAuthError("BROWSER_OPEN_FAILED", `Could not open browser automatically. Please visit: ${url}`);
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function performBrowserAuth(options, onStatusUpdate) {
+  const {
+    endpoint,
+    timeout = 300000,
+    pollInterval = 2000,
+    skipBrowserOpen = false
+  } = options;
+  const cliToken = generateCliToken();
+  onStatusUpdate?.("Initializing browser authentication...");
+  const initResponse = await initBrowserAuth(endpoint, cliToken);
+  const { authUrl } = initResponse;
+  if (!skipBrowserOpen) {
+    onStatusUpdate?.("Opening browser for authentication...");
+    try {
+      await openBrowser(authUrl);
+    } catch (error) {
+      if (error instanceof BrowserAuthError && error.code === "BROWSER_OPEN_FAILED") {
+        onStatusUpdate?.(error.message);
+      } else {
+        throw error;
+      }
+    }
+  }
+  console.log("");
+  console.log("  Open this URL to authenticate:");
+  console.log("");
+  console.log("  " + authUrl);
+  console.log("");
+  onStatusUpdate?.("Waiting for browser authentication...");
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    await sleep(pollInterval);
+    const status = await pollAuthStatus(endpoint, cliToken);
+    switch (status.status) {
+      case "pending":
+        continue;
+      case "completed":
+        if (!status.apiKey || !status.workspaceId || !status.workspaceName || !status.organizationId || !status.organizationName) {
+          throw new BrowserAuthError("INCOMPLETE_RESPONSE", "Server returned incomplete auth response");
+        }
+        return {
+          apiKey: status.apiKey,
+          workspaceId: status.workspaceId,
+          workspaceName: status.workspaceName,
+          organizationId: status.organizationId,
+          organizationName: status.organizationName,
+          expiresAt: status.expiresAt
+        };
+      case "expired":
+        throw new BrowserAuthError("AUTH_EXPIRED", "Browser authentication expired. Please try again.");
+      case "denied":
+        throw new BrowserAuthError("AUTH_DENIED", status.error ?? "Browser authentication was denied.");
+      case "not_found":
+        throw new BrowserAuthError("TOKEN_NOT_FOUND", "Authentication token not found. Please try again.");
+      default:
+        throw new BrowserAuthError("UNKNOWN_STATUS", "Unknown auth status: " + String(status.status));
+    }
+  }
+  throw new BrowserAuthError("AUTH_TIMEOUT", "Browser authentication timed out after 5 minutes. Please try again.");
+}
+
+class BrowserAuthError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BrowserAuthError";
+    this.code = code;
+  }
+  getSuggestion() {
+    switch (this.code) {
+      case "INIT_FAILED":
+        return "Check your endpoint configuration and network connection.";
+      case "POLL_FAILED":
+        return "Check your network connection and try again.";
+      case "BROWSER_OPEN_FAILED":
+        return "Copy the URL above and open it manually in your browser.";
+      case "AUTH_EXPIRED":
+      case "AUTH_TIMEOUT":
+        return 'Run "mutagent auth login" again to restart authentication.';
+      case "AUTH_DENIED":
+        return "Ensure you have access to the workspace and try again.";
+      case "TOKEN_NOT_FOUND":
+      case "INCOMPLETE_RESPONSE":
+      case "UNKNOWN_STATUS":
+        return "Please try again. If the issue persists, contact support.";
+      default:
+        return "Please try again.";
+    }
+  }
+}
+
+// src/lib/auth-flow.ts
+async function performLoginAction(opts) {
+  const { isJson, output } = opts;
+  const wasFirstLogin = !hasCredentials();
+  const envApiKey = process.env.MUTAGENT_API_KEY;
+  const endpoint = process.env.MUTAGENT_ENDPOINT ?? opts.endpoint;
+  if (envApiKey) {
+    return loginWithExistingKey(envApiKey, endpoint, output, wasFirstLogin);
+  }
+  const isNonInteractive = opts.nonInteractive === true || process.env.MUTAGENT_NON_INTERACTIVE === "true" || process.env.CI === "true" || !process.stdin.isTTY;
+  if (isJson && !opts.browser && isNonInteractive) {
+    throw new MutagentError("INTERACTIVE_REQUIRED", "No API key provided. Set MUTAGENT_API_KEY env var or add --browser for browser auth.", "Run: export MUTAGENT_API_KEY=<key> or mutagent login --browser --non-interactive");
+  }
+  if (!isNonInteractive && wasFirstLogin) {
+    console.log(`
+` + chalk3.bold.cyan("  Welcome to MutagenT CLI!") + `
+`);
+    console.log(`  No credentials found. Please authenticate to continue.
+`);
+  }
+  let useBrowserAuth = opts.browser === true;
+  if (!useBrowserAuth && isNonInteractive) {
+    output.info("Non-interactive environment detected. Using browser authentication.");
+    useBrowserAuth = true;
+  }
+  if (!useBrowserAuth) {
+    const methodAnswer = await inquirer.prompt([
+      {
+        type: "list",
+        name: "method",
+        message: "How would you like to authenticate?",
+        choices: [
+          { name: "Login (opens browser)", value: "browser" },
+          { name: "API Key (paste existing key)", value: "apiKey" }
+        ]
+      }
+    ]);
+    useBrowserAuth = methodAnswer.method === "browser";
+  }
+  if (useBrowserAuth) {
+    return loginWithBrowser(endpoint, output, wasFirstLogin);
+  }
+  return loginWithPastedKey(endpoint, output, wasFirstLogin);
+}
+function buildLoginJsonResponse(result) {
+  return {
+    success: true,
+    authenticated: result.authenticated,
+    endpoint: result.endpoint,
+    workspace: result.workspace,
+    organization: result.organization,
+    _directive: {
+      instruction: "Verify workspace. Run: mutagent workspaces list --json",
+      next: ["mutagent workspaces list --json", "mutagent usage --json"]
+    }
+  };
+}
+async function loginWithExistingKey(apiKey, endpoint, output, wasFirstLogin) {
+  output.info("Validating API key...");
+  const isValid = await validateApiKey(apiKey, endpoint);
+  if (!isValid) {
+    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+  }
+  const orgs = await fetchOrganizations(apiKey, endpoint);
+  let orgId;
+  let orgName;
+  let wsId;
+  let wsName;
+  if (orgs.length >= 1 && orgs[0]) {
+    orgId = orgs[0].id;
+    orgName = orgs[0].name;
+    const workspaces = await fetchWorkspaces(apiKey, endpoint, orgId);
+    const defaultWs = workspaces.find((w) => w.isDefault) ?? workspaces[0];
+    if (defaultWs) {
+      wsId = defaultWs.id;
+      wsName = defaultWs.name;
+    }
+  }
+  saveFullCredentials({
+    apiKey,
+    endpoint,
+    workspaceId: wsId,
+    organizationId: orgId
+  });
+  return {
+    authenticated: true,
+    apiKey,
+    endpoint,
+    workspace: wsId ? { id: wsId, name: wsName } : null,
+    organization: orgId ? { id: orgId, name: orgName } : null,
+    wasFirstLogin
+  };
+}
+async function loginWithBrowser(endpoint, output, wasFirstLogin) {
+  const spinner = ora({ text: "Opening browser for authentication...", spinner: "dots" });
+  try {
+    spinner.start();
+    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000 }, (message) => {
+      spinner.text = message;
+    });
+    spinner.succeed("Authenticated successfully!");
+    saveFullCredentials({
+      apiKey: result.apiKey,
+      endpoint,
+      workspaceId: result.workspaceId,
+      organizationId: result.organizationId,
+      expiresAt: result.expiresAt
+    });
+    if (result.workspaceName)
+      output.info(`Workspace: ${result.workspaceName}`);
+    if (result.organizationName)
+      output.info(`Organization: ${result.organizationName}`);
+    return {
+      authenticated: true,
+      apiKey: result.apiKey,
+      endpoint,
+      workspace: result.workspaceId ? { id: result.workspaceId, name: result.workspaceName } : null,
+      organization: result.organizationId ? { id: result.organizationId, name: result.organizationName } : null,
+      wasFirstLogin
+    };
+  } catch (error) {
+    spinner.fail("Authentication failed");
+    if (error instanceof BrowserAuthError) {
+      throw new MutagentError(error.code, error.message, error.getSuggestion());
+    }
+    throw error;
+  }
+}
+async function loginWithPastedKey(initialEndpoint, output, wasFirstLogin) {
+  const answers = await inquirer.prompt([
+    {
+      type: "input",
+      name: "endpoint",
+      message: "MutagenT endpoint:",
+      default: initialEndpoint
+    },
+    {
+      type: "password",
+      name: "apiKey",
+      message: "API Key:",
+      mask: "*",
+      validate: (input) => input.length > 0 || "API key is required"
+    }
+  ]);
+  const apiKey = answers.apiKey;
+  const endpoint = answers.endpoint;
+  output.info("Validating API key...");
+  const isValid = await validateApiKey(apiKey, endpoint);
+  if (!isValid) {
+    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+  }
+  let selectedOrgId;
+  let selectedOrgName;
+  let selectedWsId;
+  let selectedWsName;
+  const orgs = await fetchOrganizations(apiKey, endpoint);
+  if (orgs.length === 1 && orgs[0]) {
+    selectedOrgId = orgs[0].id;
+    selectedOrgName = orgs[0].name;
+  } else if (orgs.length > 1) {
+    const orgAnswer = await inquirer.prompt([
+      {
+        type: "list",
+        name: "orgId",
+        message: "Select organization:",
+        choices: orgs.map((o) => ({ name: o.name, value: o.id }))
+      }
+    ]);
+    selectedOrgId = orgAnswer.orgId;
+    selectedOrgName = orgs.find((o) => o.id === selectedOrgId)?.name;
+  }
+  if (selectedOrgId) {
+    const workspaces = await fetchWorkspaces(apiKey, endpoint, selectedOrgId);
+    const defaultWs = workspaces.find((w) => w.isDefault);
+    if (workspaces.length === 1 && workspaces[0]) {
+      selectedWsId = workspaces[0].id;
+      selectedWsName = workspaces[0].name;
+    } else if (defaultWs) {
+      selectedWsId = defaultWs.id;
+      selectedWsName = defaultWs.name;
+    } else if (workspaces.length > 1) {
+      const wsAnswer = await inquirer.prompt([
+        {
+          type: "list",
+          name: "wsId",
+          message: "Select workspace:",
+          choices: workspaces.map((w) => ({
+            name: w.name + (w.isDefault ? " (default)" : ""),
+            value: w.id
+          }))
+        }
+      ]);
+      selectedWsId = wsAnswer.wsId;
+      selectedWsName = workspaces.find((w) => w.id === selectedWsId)?.name;
+    }
+  }
+  saveFullCredentials({
+    apiKey,
+    endpoint,
+    workspaceId: selectedWsId,
+    organizationId: selectedOrgId
+  });
+  return {
+    authenticated: true,
+    apiKey,
+    endpoint,
+    workspace: selectedWsId ? { id: selectedWsId, name: selectedWsName } : null,
+    organization: selectedOrgId ? { id: selectedOrgId, name: selectedOrgName } : null,
+    wasFirstLogin
+  };
+}
+
+// src/commands/auth.ts
+function createAuthCommand() {
+  const auth = new Command("auth").description("Authenticate with MutagenT platform").addHelpText("after", `
+Examples:
+  ${chalk4.dim("$")} mutagent auth login
+  ${chalk4.dim("$")} mutagent auth login --browser
+  ${chalk4.dim("$")} mutagent auth status
+  ${chalk4.dim("$")} mutagent auth logout
+    `);
+  auth.command("login").description("Authenticate and store API key").option("--browser", "Force browser-based authentication").option("--non-interactive", "Disable interactive prompts (auto-selects browser auth)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
+Examples:
+  ${chalk4.dim("$")} mutagent auth login                    ${chalk4.dim("# Interactive (choose method)")}
+  ${chalk4.dim("$")} mutagent auth login --browser          ${chalk4.dim("# Browser OAuth flow")}
+  ${chalk4.dim("$")} mutagent auth login --non-interactive  ${chalk4.dim("# Auto browser flow (AI agents)")}
+
+${chalk4.dim("Note: this command is an alias for `mutagent login`.")}
+${chalk4.dim("See `mutagent login --help` for full documentation.")}
+    `).action(async (options) => {
+    const isJson = getJsonFlag(auth);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const result = await performLoginAction({
+        endpoint: options.endpoint,
+        browser: options.browser,
+        nonInteractive: options.nonInteractive,
+        isJson,
+        output
+      });
+      if (isJson) {
+        output.output(buildLoginJsonResponse(result));
+      } else {
+        output.success("Authenticated successfully");
+        if (result.organization?.name)
+          output.info(`Organization: ${result.organization.name}`);
+        if (result.workspace?.name)
+          output.info(`Workspace: ${result.workspace.name}`);
+        output.info(`Endpoint: ${result.endpoint}`);
+        output.info("Next: mutagent workspaces list --json");
+      }
+      if (result.wasFirstLogin && process.stdin.isTTY && !isJson) {
+        await runPostOnboarding();
+      }
+    } catch (error) {
+      if (error instanceof MutagentError) {
+        output.error(error.message);
+        process.exit(error.exitCode);
+      }
+      throw error;
+    }
+  });
+  auth.command("status").description("Check authentication status").addHelpText("after", `
+Examples:
+  ${chalk4.dim("$")} mutagent auth status
+  ${chalk4.dim("$")} mutagent auth status --json
+    `).action(async () => {
+    const isJson = getJsonFlag(auth);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    const apiKey = getApiKey();
+    const config = loadConfig();
+    const endpoint = config.endpoint ?? "https://api.mutagent.io";
+    if (!apiKey) {
+      if (isJson) {
         output.output({ authenticated: false, message: "Not authenticated" });
       } else {
         output.error("Not authenticated");
@@ -1418,7 +1863,7 @@ Examples:
     }
     const isValid = await validateApiKey(apiKey, endpoint);
     const cwd = process.cwd();
-    const hasOnboarding = existsSync3(join3(cwd, ".mutagentrc.json"));
+    const hasOnboarding = existsSync5(join6(cwd, ".mutagentrc.json"));
     if (isJson) {
       const statusResult = {
         authenticated: isValid,
@@ -2305,142 +2750,25 @@ Available Models:`));
           if (result.error) {
             console.log(chalk11.red(`Error: ${result.error}`));
           }
-        }
-      }
-    } catch (error) {
-      handleError(error, isJson);
-    }
-  });
-  registerAddCommand(providers);
-  registerUpdateCommand(providers);
-  registerDeleteCommand(providers);
-  return providers;
-}
-
-// src/commands/init.ts
-init_config();
-import { Command as Command6 } from "commander";
-import inquirer2 from "inquirer";
-import chalk12 from "chalk";
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { execSync as execSync2 } from "child_process";
-import { join as join5 } from "path";
-init_errors();
-
-// src/lib/framework-detection.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
-import { execSync } from "child_process";
-import { join as join4 } from "path";
-var FRAMEWORK_DETECTION_MAP = {
-  "@mastra/core": {
-    name: "mastra",
-    displayName: "Mastra",
-    npmPackage: "@mastra/core"
-  },
-  "@langchain/langgraph": {
-    name: "langgraph",
-    displayName: "LangGraph",
-    npmPackage: "@langchain/langgraph",
-    mutagentPackage: "@mutagent/langgraph"
-  },
-  langchain: {
-    name: "langchain",
-    displayName: "LangChain",
-    npmPackage: "langchain",
-    mutagentPackage: "@mutagent/langchain"
-  },
-  "@langchain/core": {
-    name: "langchain",
-    displayName: "LangChain",
-    npmPackage: "@langchain/core",
-    mutagentPackage: "@mutagent/langchain"
-  },
-  "@ai-sdk/core": {
-    name: "vercel-ai",
-    displayName: "Vercel AI SDK",
-    npmPackage: "@ai-sdk/core",
-    mutagentPackage: "@mutagent/vercel-ai"
-  },
-  ai: {
-    name: "vercel-ai",
-    displayName: "Vercel AI SDK",
-    npmPackage: "ai",
-    mutagentPackage: "@mutagent/vercel-ai"
-  },
-  "@google/genai": {
-    name: "generic",
-    displayName: "Google GenAI",
-    npmPackage: "@google/genai"
-  },
-  openai: {
-    name: "openai",
-    displayName: "OpenAI SDK",
-    npmPackage: "openai",
-    mutagentPackage: "@mutagent/openai"
-  }
-};
-function detectPackageManager(cwd = process.cwd()) {
-  if (existsSync4(join4(cwd, "bun.lockb")) || existsSync4(join4(cwd, "bun.lock"))) {
-    return "bun";
-  }
-  if (existsSync4(join4(cwd, "pnpm-lock.yaml"))) {
-    return "pnpm";
-  }
-  if (existsSync4(join4(cwd, "yarn.lock"))) {
-    return "yarn";
-  }
-  if (existsSync4(join4(cwd, "package-lock.json"))) {
-    return "npm";
-  }
-  try {
-    execSync("bun --version", { stdio: "ignore" });
-    return "bun";
-  } catch {
-    return "npm";
-  }
-}
-function getInstallCommand(pm, packages) {
-  const pkgList = packages.join(" ");
-  const commands = {
-    bun: `bun add ${pkgList}`,
-    npm: `npm install ${pkgList}`,
-    yarn: `yarn add ${pkgList}`,
-    pnpm: `pnpm add ${pkgList}`
-  };
-  return commands[pm];
-}
-function detectFrameworkFromPackageJson(cwd = process.cwd()) {
-  const pkgPath = join4(cwd, "package.json");
-  if (!existsSync4(pkgPath)) {
-    return null;
-  }
-  let pkg;
-  try {
-    pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
-  } catch {
-    return null;
-  }
-  const allDeps = {
-    ...pkg.dependencies,
-    ...pkg.devDependencies
-  };
-  for (const [depName, framework] of Object.entries(FRAMEWORK_DETECTION_MAP)) {
-    if (depName in allDeps) {
-      return framework;
+        }
+      }
+    } catch (error) {
+      handleError(error, isJson);
     }
-  }
-  return null;
-}
-function hasRcConfig(cwd = process.cwd()) {
-  return existsSync4(join4(cwd, ".mutagentrc.json"));
+  });
+  registerAddCommand(providers);
+  registerUpdateCommand(providers);
+  registerDeleteCommand(providers);
+  return providers;
 }
 
 // src/commands/init.ts
-function writeRcConfig(config, cwd = process.cwd()) {
-  const rcPath = join5(cwd, ".mutagentrc.json");
-  writeFileSync2(rcPath, JSON.stringify(config, null, 2) + `
-`);
-}
+init_config();
+import { Command as Command6 } from "commander";
+import inquirer2 from "inquirer";
+import chalk12 from "chalk";
+import { execSync as execSync2 } from "child_process";
+init_errors();
 function createInitCommand() {
   const init = new Command6("init").description("Initialize MutagenT in your project").option("--non-interactive", "Skip interactive prompts (defaults to CLI-only mode)").addHelpText("after", `
 Examples:
@@ -2631,9 +2959,8 @@ Modes:
         }
         console.log("");
         output.info("Next steps:");
-        output.info("  1. Run: mutagent skills install  (install the CLI skill for AI agents)");
-        output.info(`  2. Add MutagenT tracing to your ${confirmedFramework.name} code via ${confirmedFramework.mutagentPackage}`);
-        output.info("  3. Run: mutagent providers list  (confirm an LLM provider is configured)");
+        output.info(`  1. Add MutagenT tracing to your ${confirmedFramework.name} code via ${confirmedFramework.mutagentPackage}`);
+        output.info("  2. Run: mutagent providers list  (confirm an LLM provider is configured)");
       } else {
         writeRcConfig(rcConfig, cwd);
         output.success("Created .mutagentrc.json");
@@ -2653,60 +2980,9 @@ Modes:
           }
         }
       }
-      const skillPath = join5(cwd, ".claude/skills/mutagent-cli/SKILL.md");
-      const skillInstalled = existsSync5(skillPath);
-      if (!isNonInteractive && !skillInstalled) {
-        const { installSkill } = await inquirer2.prompt([{
-          type: "confirm",
-          name: "installSkill",
-          message: "Install MutagenT skill for Claude Code? (Teaches AI agents how to use the CLI)",
-          default: true
-        }]);
-        if (installSkill) {
-          try {
-            const skillDir = join5(cwd, ".claude/skills/mutagent-cli");
-            if (!existsSync5(skillDir)) {
-              mkdirSync2(skillDir, { recursive: true });
-            }
-            execSync2("node " + join5(cwd, "node_modules/.bin/mutagent") + " skills install", {
-              cwd,
-              stdio: "ignore"
-            });
-            output.success("Installed MutagenT CLI skill for Claude Code");
-          } catch {
-            output.info("Install skill manually: mutagent skills install");
-          }
-        }
-      }
       const initDirective = {
-        instruction: skillInstalled ? "Verify workspace. Run: mutagent workspaces list --json" : [
-          "MANDATORY: Ask the user whether they want to install the MutagenT CLI skill and Claude Code hooks.",
-          "Use your AskUserQuestion tool to present the following choices:",
-          "1. Install skill + hooks (Recommended) — Installs the CLI skill AND configures Claude Code session telemetry hooks",
-          "2. Install skill only — Installs the CLI skill (teaches AI agents to use MutagenT CLI)",
-          "3. Skip — Do not install",
-          "",
-          "If the user picks option 1, run BOTH commands:",
-          "  mutagent skills install --json",
-          "  mutagent hooks install --json",
-          "",
-          "If the user picks option 2, run only: mutagent skills install --json",
-          "",
-          "After skill/hooks install, verify workspace: mutagent workspaces list --json"
-        ].join(`
-`),
-        next: ["mutagent workspaces list --json", "mutagent providers list --json"],
-        ...!skillInstalled ? {
-          askUserQuestions: [{
-            question: "Would you like to install the MutagenT CLI skill and Claude Code hooks?",
-            options: [
-              { label: "Install skill + hooks (Recommended)", description: "Installs the CLI skill AND configures Claude Code session telemetry hooks" },
-              { label: "Install skill only", description: "Installs the CLI skill (teaches AI agents to use MutagenT CLI)" },
-              { label: "Skip", description: "Do not install" }
-            ],
-            multiSelect: false
-          }]
-        } : {}
+        instruction: "Verify workspace. Run: mutagent workspaces list --json",
+        next: ["mutagent workspaces list --json", "mutagent providers list --json"]
       };
       const summary = {
         success: true,
@@ -2716,7 +2992,6 @@ Modes:
         framework: confirmedFramework?.name ?? null,
         authenticated,
         workspaceValidation: workspaceValidation ?? null,
-        skillInstalled: skillInstalled || existsSync5(skillPath),
         _directive: initDirective
       };
       output.output(summary);
@@ -2730,8 +3005,8 @@ Modes:
 // src/commands/skills.ts
 import { Command as Command7 } from "commander";
 import chalk13 from "chalk";
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
-import { dirname, join as join6 } from "path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { dirname, join as join7 } from "path";
 import { execSync as execSync3 } from "child_process";
 
 // src/generated/skill-content.ts
@@ -3386,7 +3661,7 @@ that teaches coding agents how to use the MutagenT CLI effectively.
     const isJson = parentCmd ? getJsonFlag(parentCmd) : false;
     const output = new OutputFormatter(isJson ? "json" : "table");
     const repoRoot = findRepoRoot();
-    const skillDir = join6(repoRoot, SKILL_DIR);
+    const skillDir = join7(repoRoot, SKILL_DIR);
     const files = getSkillFiles();
     const writtenFiles = [];
     let totalBytes = 0;
@@ -3398,7 +3673,7 @@ that teaches coding agents how to use the MutagenT CLI effectively.
       return a.localeCompare(b);
     });
     for (const relPath of sortedKeys) {
-      const destPath = join6(skillDir, relPath);
+      const destPath = join7(skillDir, relPath);
       const parentDir = dirname(destPath);
       if (!existsSync6(parentDir)) {
         mkdirSync3(parentDir, { recursive: true });
@@ -3407,7 +3682,7 @@ that teaches coding agents how to use the MutagenT CLI effectively.
       const finalContent = raw.endsWith(`
 `) ? raw : `${raw}
 `;
-      writeFileSync3(destPath, finalContent, "utf-8");
+      writeFileSync4(destPath, finalContent, "utf-8");
       writtenFiles.push({ path: destPath, bytes: finalContent.length });
       totalBytes += finalContent.length;
     }
@@ -3510,18 +3785,18 @@ import { Command as Command9 } from "commander";
 import { randomUUID } from "crypto";
 
 // src/commands/hooks/state.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, renameSync, unlinkSync, existsSync as existsSync7 } from "fs";
-import { join as join7 } from "path";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync5, renameSync as renameSync2, unlinkSync, existsSync as existsSync7 } from "fs";
+import { join as join8 } from "path";
 import { tmpdir } from "os";
 function stateFilePath(sessionId) {
-  return join7(tmpdir(), `mutagent-hook-${sessionId}.json`);
+  return join8(tmpdir(), `mutagent-hook-${sessionId}.json`);
 }
 function readState(sessionId) {
   const path = stateFilePath(sessionId);
   if (!existsSync7(path))
     return null;
   try {
-    const raw = JSON.parse(readFileSync4(path, "utf-8"));
+    const raw = JSON.parse(readFileSync5(path, "utf-8"));
     if (!Array.isArray(raw.parentStack)) {
       raw.parentStack = [];
     }
@@ -3536,8 +3811,8 @@ function readState(sessionId) {
 function writeState(sessionId, state) {
   const path = stateFilePath(sessionId);
   const tmpPath = `${path}.${process.pid.toString()}.tmp`;
-  writeFileSync4(tmpPath, JSON.stringify(state), "utf-8");
-  renameSync(tmpPath, path);
+  writeFileSync5(tmpPath, JSON.stringify(state), "utf-8");
+  renameSync2(tmpPath, path);
 }
 function deleteState(sessionId) {
   const path = stateFilePath(sessionId);
@@ -4165,863 +4440,563 @@ async function handlePostToolUseFailure() {
   }
   const errorPayload = serializePayload(reason);
   await sendBatchTrace([
-    {
-      traceId,
-      sessionId,
-      name: "Claude Code Session",
-      source: "sdk",
-      startTime,
-      status: "running",
-      spans: [
-        {
-          spanId: matchedSpanId,
-          name: toolName,
-          kind: "tool",
-          startTime: matchedSpanStart,
-          endTime: now,
-          status: "error",
-          ...errorPayload !== undefined ? { output: errorPayload } : {}
-        }
-      ]
-    }
-  ]);
-}
-
-// src/commands/hooks/install.ts
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync5, existsSync as existsSync8, mkdirSync as mkdirSync4 } from "fs";
-import { join as join8 } from "path";
-
-class SettingsParseError extends Error {
-  settingsPath;
-  backupPath;
-  constructor(settingsPath, backupPath, cause) {
-    super(`settings.local.json contains unparseable JSON.
-` + `  Original file backed up to: ${backupPath}
-` + `  To recover: restore from backup, fix JSON syntax, then re-run ` + `\`mutagent hooks install\``);
-    this.settingsPath = settingsPath;
-    this.backupPath = backupPath;
-    this.name = "SettingsParseError";
-    if (cause instanceof Error)
-      this.cause = cause;
-  }
-}
-var V1_MIGRATIONS = {
-  Stop: ["mutagent hooks claude-code session-end"]
-};
-var MUTAGENT_HOOKS = {
-  SessionStart: [{ matcher: "startup", hooks: [{ type: "command", command: "mutagent hooks claude-code session-start" }] }],
-  PreToolUse: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code pre-tool-use" }] }],
-  PostToolUse: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-tool-use" }] }],
-  Stop: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code stop" }] }],
-  SessionEnd: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code session-end" }] }],
-  UserPromptSubmit: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code user-prompt-submit" }] }],
-  SubagentStart: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code subagent-start" }] }],
-  SubagentStop: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code subagent-stop" }] }],
-  PreCompact: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code pre-compact" }] }],
-  PostCompact: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-compact" }] }],
-  PostToolUseFailure: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-tool-use-failure" }] }]
-};
-function hasCommand(matchers, command) {
-  return matchers.some((m) => m.hooks.some((h) => h.command === command));
-}
-function migrateV1Hooks(settings) {
-  const migrated = [];
-  if (!settings.hooks)
-    return migrated;
-  for (const [event, commandsToRemove] of Object.entries(V1_MIGRATIONS)) {
-    const matchers = settings.hooks[event];
-    if (!matchers)
-      continue;
-    const filtered = matchers.map((matcher) => {
-      const keptHooks = matcher.hooks.filter((h) => {
-        if (commandsToRemove.includes(h.command)) {
-          migrated.push({ event, command: h.command });
-          return false;
-        }
-        return true;
-      });
-      return keptHooks.length > 0 ? { ...matcher, hooks: keptHooks } : null;
-    }).filter(Boolean);
-    if (filtered.length === 0) {
-      delete settings.hooks[event];
-    } else {
-      settings.hooks[event] = filtered;
-    }
-  }
-  return migrated;
-}
-function installHooks(cwd) {
-  const claudeDir = join8(cwd, ".claude");
-  const settingsPath = join8(claudeDir, "settings.local.json");
-  const existed = existsSync8(settingsPath);
-  let settings = {};
-  if (existed) {
-    const raw = readFileSync5(settingsPath, "utf-8");
-    try {
-      settings = JSON.parse(raw);
-    } catch (err) {
-      const backupPath = `${settingsPath}.bak.${new Date().toISOString().replace(/:/g, "-")}`;
-      writeFileSync5(backupPath, raw, "utf-8");
-      throw new SettingsParseError(settingsPath, backupPath, err);
-    }
-  }
-  const added = [];
-  const alreadyPresent = [];
-  const migrated = migrateV1Hooks(settings);
-  for (const [event, newMatchers] of Object.entries(MUTAGENT_HOOKS)) {
-    if (!newMatchers)
-      continue;
-    settings.hooks ??= {};
-    settings.hooks[event] ??= [];
-    const existing = settings.hooks[event];
-    for (const matcher of newMatchers) {
-      for (const hook of matcher.hooks) {
-        if (hasCommand(existing, hook.command)) {
-          alreadyPresent.push(hook.command);
-        } else {
-          const newMatcher = {
-            ...matcher.matcher !== undefined ? { matcher: matcher.matcher } : {},
-            hooks: [hook]
-          };
-          existing.push(newMatcher);
-          added.push(hook.command);
-        }
-      }
-    }
-  }
-  let userWarning;
-  if (added.length > 0 || migrated.length > 0) {
-    if (!existsSync8(claudeDir)) {
-      mkdirSync4(claudeDir, { recursive: true });
-    }
-    writeFileSync5(settingsPath, JSON.stringify(settings, null, 2) + `
-`, "utf-8");
-  }
-  if (added.length > 0) {
-    const addedList = added.map((cmd) => {
-      const parts = cmd.split(" ");
-      return parts[parts.length - 1] ?? cmd;
-    }).join(", ");
-    userWarning = `MutagenT hooks installed into .claude/settings.local.json
-` + `  Added: ${addedList}
-` + `  This file was modified. Review with: git diff .claude/settings.local.json
-` + `  (To remove hooks, edit .claude/settings.local.json and delete the mutagent entries)`;
-  }
-  return { settingsPath, existed, added, alreadyPresent, migrated, userWarning };
-}
-
-// src/commands/hooks/index.ts
-function createHooksCommand() {
-  const hooks = new Command9("hooks").description("Hook handlers for AI coding assistants").addHelpText("after", `
-Claude Code Session Telemetry:
-  Sends lightweight session activity to the MutagenT traces API for observability.
-
-  Install by adding to .claude/settings.local.json:
-
-  {
-    "hooks": {
-      "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
-      "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
-      "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
-      "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}],
-      "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code user-prompt-submit"}]}],
-      "SubagentStart": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-start"}]}],
-      "SubagentStop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-stop"}]}],
-      "PreCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-compact"}]}],
-      "PostCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-compact"}]}],
-      "PostToolUseFailure": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use-failure"}]}]
-    }
-  }
-
-  Or run: mutagent hooks install
-    `);
-  hooks.command("install").description("Install MutagenT hooks into .claude/settings.local.json (safe merge — never overwrites existing hooks)").option("--cwd <dir>", "Target directory (defaults to cwd)", process.cwd()).addHelpText("after", `
-Reads existing .claude/settings.local.json (if present) and deep-merges
-MutagenT telemetry hooks into each event array (all 10 events). Skips any
-hook already present (checked by command string) so running this multiple
-times is safe.
-    `).action((opts) => {
-    const targetDir = opts.cwd ?? process.cwd();
-    const isJson = Boolean(opts.json);
-    let result;
-    try {
-      result = installHooks(targetDir);
-    } catch (err) {
-      if (err instanceof SettingsParseError) {
-        if (isJson) {
-          process.stdout.write(JSON.stringify({
-            success: false,
-            error: err.message,
-            backupPath: err.backupPath,
-            settingsPath: err.settingsPath
-          }) + `
-`);
-        } else {
-          process.stderr.write(`[mutagent hooks install] ERROR: ${err.message}
-`);
-        }
-        process.exit(1);
-      }
-      throw err;
-    }
-    for (const { event, command } of result.migrated) {
-      process.stderr.write(`[mutagent hooks install] ⚠️  Migrated v1 hook: removed '${event} → ${command}' (v2 wires this as 'SessionEnd')
-`);
-    }
-    if (result.added.length === 0 && result.alreadyPresent.length === 0) {
-      process.stdout.write(JSON.stringify({
-        success: true,
-        settingsPath: result.settingsPath,
-        added: [],
-        alreadyPresent: [],
-        message: "No hooks to install."
-      }) + `
-`);
-      return;
-    }
-    if (result.userWarning) {
-      if (isJson) {} else {
-        process.stderr.write(`⚠ ${result.userWarning}
-`);
-      }
-    }
-    const jsonResponse = {
-      success: true,
-      settingsPath: result.settingsPath,
-      existed: result.existed,
-      added: result.added,
-      alreadyPresent: result.alreadyPresent,
-      message: result.added.length > 0 ? `Installed ${String(result.added.length)} hook(s). ${String(result.alreadyPresent.length)} already present.` : `All hooks already present (${String(result.alreadyPresent.length)}).`
-    };
-    if (result.userWarning && isJson) {
-      jsonResponse.warnings = [result.userWarning];
+    {
+      traceId,
+      sessionId,
+      name: "Claude Code Session",
+      source: "sdk",
+      startTime,
+      status: "running",
+      spans: [
+        {
+          spanId: matchedSpanId,
+          name: toolName,
+          kind: "tool",
+          startTime: matchedSpanStart,
+          endTime: now,
+          status: "error",
+          ...errorPayload !== undefined ? { output: errorPayload } : {}
+        }
+      ]
     }
-    process.stdout.write(JSON.stringify(jsonResponse) + `
-`);
-  });
-  const claudeCode = hooks.command("claude-code").description("Claude Code session telemetry");
-  claudeCode.command("session-start").description("Handle session start event").action(async () => {
-    await safeExecute(handleSessionStart);
-  });
-  claudeCode.command("session-end").description("Handle session end event").action(async () => {
-    await safeExecute(handleSessionEnd);
-  });
-  claudeCode.command("pre-tool-use").description("Handle pre-tool-use event").action(async () => {
-    await safeExecute(handlePreToolUse);
-  });
-  claudeCode.command("post-tool-use").description("Handle post-tool-use event").action(async () => {
-    await safeExecute(handlePostToolUse);
-  });
-  claudeCode.command("user-prompt-submit").description("Handle user prompt submit event (creates turn span)").action(async () => {
-    await safeExecute(handleUserPromptSubmit);
-  });
-  claudeCode.command("stop").description("Handle stop event (closes current turn span)").action(async () => {
-    await safeExecute(handleStop);
-  });
-  claudeCode.command("subagent-start").description("Handle subagent start event (creates nested agent span)").action(async () => {
-    await safeExecute(handleSubagentStart);
-  });
-  claudeCode.command("subagent-stop").description("Handle subagent stop event (closes subagent span)").action(async () => {
-    await safeExecute(handleSubagentStop);
-  });
-  claudeCode.command("pre-compact").description("Handle pre-compact event (opens compaction span)").action(async () => {
-    await safeExecute(handlePreCompact);
-  });
-  claudeCode.command("post-compact").description("Handle post-compact event (closes compaction span with summary)").action(async () => {
-    await safeExecute(handlePostCompact);
-  });
-  claudeCode.command("post-tool-use-failure").description("Handle post-tool-use-failure event (closes failed span with error status)").action(async () => {
-    await safeExecute(handlePostToolUseFailure);
-  });
-  return hooks;
+  ]);
 }
 
-// src/commands/feedback.ts
-import { Command as Command10 } from "commander";
-import chalk16 from "chalk";
-import { type as osType, release as osRelease } from "os";
-import { readFileSync as readFileSync7 } from "fs";
-import { join as join10, dirname as dirname2 } from "path";
-import { fileURLToPath } from "url";
-init_errors();
-init_config();
-
-// src/lib/transcript.ts
-init_errors();
-import { homedir as osHomedir } from "os";
+// src/commands/hooks/install.ts
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync4 } from "fs";
 import { join as join9 } from "path";
-import {
-  existsSync as fsExistsSync,
-  statSync as fsStatSync,
-  readFileSync as readFileSync6,
-  readdirSync,
-  openSync,
-  readSync,
-  closeSync
-} from "fs";
-import chalk15 from "chalk";
-var TAIL_BYTES = 200000;
-function defaultReadTail(path, tailBytes) {
-  const { size } = fsStatSync(path);
-  if (size <= tailBytes) {
-    return { content: readFileSync6(path, "utf-8"), truncated: false };
-  }
-  const fd = openSync(path, "r");
-  try {
-    const buf = Buffer.alloc(tailBytes);
-    readSync(fd, buf, 0, tailBytes, size - tailBytes);
-    return { content: buf.toString("utf-8"), truncated: true };
-  } finally {
-    closeSync(fd);
+
+class SettingsParseError extends Error {
+  settingsPath;
+  backupPath;
+  constructor(settingsPath, backupPath, cause) {
+    super(`settings.local.json contains unparseable JSON.
+` + `  Original file backed up to: ${backupPath}
+` + `  To recover: restore from backup, fix JSON syntax, then re-run ` + `\`mutagent hooks install\``);
+    this.settingsPath = settingsPath;
+    this.backupPath = backupPath;
+    this.name = "SettingsParseError";
+    if (cause instanceof Error)
+      this.cause = cause;
   }
 }
-function defaultScan(dir) {
-  if (!fsExistsSync(dir))
-    return [];
-  const out = [];
-  const walk = (current) => {
-    let entries;
-    try {
-      entries = readdirSync(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = join9(current, entry.name);
-      if (entry.isDirectory())
-        walk(full);
-      else if (entry.isFile() && entry.name.endsWith(".jsonl"))
-        out.push(full);
-    }
-  };
-  walk(dir);
-  return out;
-}
-function buildSources(env, home) {
-  const ompBase = env.PI_CODING_AGENT_DIR ?? join9(home, ".omp", "agent");
-  return [
-    { harness: "claude-code", dir: join9(home, ".claude", "projects") },
-    { harness: "codex", dir: join9(home, ".codex", "sessions") },
-    { harness: "omp", dir: join9(ompBase, "sessions") }
-  ];
+var V1_MIGRATIONS = {
+  Stop: ["mutagent hooks claude-code session-end"]
+};
+var MUTAGENT_HOOKS = {
+  SessionStart: [{ matcher: "startup", hooks: [{ type: "command", command: "mutagent hooks claude-code session-start" }] }],
+  PreToolUse: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code pre-tool-use" }] }],
+  PostToolUse: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-tool-use" }] }],
+  Stop: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code stop" }] }],
+  SessionEnd: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code session-end" }] }],
+  UserPromptSubmit: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code user-prompt-submit" }] }],
+  SubagentStart: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code subagent-start" }] }],
+  SubagentStop: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code subagent-stop" }] }],
+  PreCompact: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code pre-compact" }] }],
+  PostCompact: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-compact" }] }],
+  PostToolUseFailure: [{ hooks: [{ type: "command", command: "mutagent hooks claude-code post-tool-use-failure" }] }]
+};
+function hasCommand(matchers, command) {
+  return matchers.some((m) => m.hooks.some((h) => h.command === command));
 }
-function resolveTranscript(attach, deps = {}) {
-  const env = deps.env ?? process.env;
-  const home = (deps.homedir ?? osHomedir)();
-  const existsSync9 = deps.existsSync ?? fsExistsSync;
-  const statSync = deps.statSync ?? fsStatSync;
-  const scan = deps.scan ?? defaultScan;
-  const readTail = deps.readTail ?? defaultReadTail;
-  const warn = deps.warn ?? ((message) => {
-    console.error(message);
-  });
-  if (attach === undefined || attach === false)
-    return null;
-  if (typeof attach === "string" && attach.length > 0) {
-    if (!existsSync9(attach)) {
-      throw new MutagentError("INVALID_ARGUMENTS", `Transcript file not found: ${attach}`, `Verify the path exists: ls -la "${attach}"
-Or omit the path to auto-detect the newest coding-agent session.`);
-    }
-    const { content: content2, truncated: truncated2 } = readTail(attach, TAIL_BYTES);
-    return { harness: "unknown", sourcePath: attach, tailBytes: TAIL_BYTES, truncated: truncated2, content: content2 };
-  }
-  let newest = null;
-  for (const src of buildSources(env, home)) {
-    for (const file of scan(src.dir)) {
-      const { mtimeMs } = statSync(file);
-      if (!newest || mtimeMs > newest.mtimeMs) {
-        newest = { harness: src.harness, path: file, mtimeMs };
-      }
+function migrateV1Hooks(settings) {
+  const migrated = [];
+  if (!settings.hooks)
+    return migrated;
+  for (const [event, commandsToRemove] of Object.entries(V1_MIGRATIONS)) {
+    const matchers = settings.hooks[event];
+    if (!matchers)
+      continue;
+    const filtered = matchers.map((matcher) => {
+      const keptHooks = matcher.hooks.filter((h) => {
+        if (commandsToRemove.includes(h.command)) {
+          migrated.push({ event, command: h.command });
+          return false;
+        }
+        return true;
+      });
+      return keptHooks.length > 0 ? { ...matcher, hooks: keptHooks } : null;
+    }).filter(Boolean);
+    if (filtered.length === 0) {
+      delete settings.hooks[event];
+    } else {
+      settings.hooks[event] = filtered;
     }
   }
-  if (!newest) {
-    warn(chalk15.yellow("⚠ No coding-agent transcript found; sending feedback without one."));
-    return null;
-  }
-  const { content, truncated } = readTail(newest.path, TAIL_BYTES);
-  return {
-    harness: newest.harness,
-    sourcePath: newest.path,
-    tailBytes: TAIL_BYTES,
-    truncated,
-    content
-  };
+  return migrated;
 }
-
-// src/commands/feedback.ts
-var MAX_FEEDBACK_LENGTH = 1e4;
-var VALID_STAGES = ["spec", "build", "evaluate", "diagnose", "optimize"];
-function getCliVersion() {
-  if (process.env.CLI_VERSION)
-    return process.env.CLI_VERSION;
-  try {
-    const __dirname2 = dirname2(fileURLToPath(import.meta.url));
-    const pkgPath = join10(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync7(pkgPath, "utf-8"));
-    return pkg.version ?? "0.1.1";
-  } catch {
-    return "0.1.1";
+function installHooks(cwd) {
+  const claudeDir = join9(cwd, ".claude");
+  const settingsPath = join9(claudeDir, "settings.local.json");
+  const existed = existsSync8(settingsPath);
+  let settings = {};
+  if (existed) {
+    const raw = readFileSync6(settingsPath, "utf-8");
+    try {
+      settings = JSON.parse(raw);
+    } catch (err) {
+      const backupPath = `${settingsPath}.bak.${new Date().toISOString().replace(/:/g, "-")}`;
+      writeFileSync6(backupPath, raw, "utf-8");
+      throw new SettingsParseError(settingsPath, backupPath, err);
+    }
   }
-}
-function parseCategory(input) {
-  if (input === "cli" || input === "helix")
-    return { category: input };
-  if (input.startsWith("stage:")) {
-    const stage = input.slice("stage:".length);
-    if (VALID_STAGES.includes(stage)) {
-      return { category: input };
+  const added = [];
+  const alreadyPresent = [];
+  const migrated = migrateV1Hooks(settings);
+  for (const [event, newMatchers] of Object.entries(MUTAGENT_HOOKS)) {
+    if (!newMatchers)
+      continue;
+    settings.hooks ??= {};
+    settings.hooks[event] ??= [];
+    const existing = settings.hooks[event];
+    for (const matcher of newMatchers) {
+      for (const hook of matcher.hooks) {
+        if (hasCommand(existing, hook.command)) {
+          alreadyPresent.push(hook.command);
+        } else {
+          const newMatcher = {
+            ...matcher.matcher !== undefined ? { matcher: matcher.matcher } : {},
+            hooks: [hook]
+          };
+          existing.push(newMatcher);
+          added.push(hook.command);
+        }
+      }
     }
-    throw new MutagentError("INVALID_ARGUMENTS", `Invalid stage: "${stage}". Must be one of: ${VALID_STAGES.join(", ")}.`, `Use --category stage:<${VALID_STAGES.join("|")}> (e.g. --category stage:evaluate).`);
-  }
-  throw new MutagentError("INVALID_ARGUMENTS", `Invalid category: "${input}". Must be 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'.`, "Run: mutagent feedback send --help");
-}
-function buildAutoContext(harness) {
-  return {
-    harness,
-    cliVersion: getCliVersion(),
-    platform: process.platform,
-    os: `${osType()} ${osRelease()}`,
-    nodeVersion: process.version
-  };
-}
-async function postToServer(payload, endpoint, apiKey, workspaceId, organizationId) {
-  const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": apiKey
-  };
-  if (workspaceId)
-    headers["x-workspace-id"] = workspaceId;
-  if (organizationId)
-    headers["x-organization-id"] = organizationId;
-  let response;
-  try {
-    response = await fetch(`${endpoint}/api/feedback`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(payload)
-    });
-  } catch {
-    throw new MutagentError("SERVER_UNAVAILABLE", "Server unavailable. Try again later.", "Check your network connection or verify the server endpoint with: mutagent config show");
   }
-  if (response.ok) {
-    return await response.json();
+  let userWarning;
+  if (added.length > 0 || migrated.length > 0) {
+    if (!existsSync8(claudeDir)) {
+      mkdirSync4(claudeDir, { recursive: true });
+    }
+    writeFileSync6(settingsPath, JSON.stringify(settings, null, 2) + `
+`, "utf-8");
   }
-  let errorMessage = `Server returned ${String(response.status)}`;
-  try {
-    const body = await response.json();
-    errorMessage = body.message ?? body.error ?? errorMessage;
-  } catch {}
-  if (response.status === 401) {
-    throw new MutagentError("AUTH_REQUIRED", errorMessage, "Authenticate first: mutagent auth login");
+  if (added.length > 0) {
+    const addedList = added.map((cmd) => {
+      const parts = cmd.split(" ");
+      return parts[parts.length - 1] ?? cmd;
+    }).join(", ");
+    userWarning = `MutagenT hooks installed into .claude/settings.local.json
+` + `  Added: ${addedList}
+` + `  This file was modified. Review with: git diff .claude/settings.local.json
+` + `  (To remove hooks, edit .claude/settings.local.json and delete the mutagent entries)`;
   }
-  throw new MutagentError("API_ERROR", errorMessage, `Server responded with status ${String(response.status)}. Check your configuration with: mutagent config show`);
-}
-function buildPayload(feedback, category, title, session, transcript) {
-  const feedbackV2 = {
-    category,
-    feedback,
-    context: buildAutoContext(transcript?.harness ?? "unknown")
-  };
-  if (title)
-    feedbackV2.title = title;
-  if (transcript)
-    feedbackV2.transcript = transcript;
-  const payload = { message: feedback, context: { feedbackV2 } };
-  if (session)
-    payload.sessionId = session;
-  return payload;
-}
-function createFeedbackCommand() {
-  const feedback = new Command10("feedback").description("Send product feedback to MutagenT").addHelpText("after", `
-${chalk16.bold("Examples:")}
-  ${chalk16.cyan('mutagent feedback send "Optimizer results were great"')}
-  ${chalk16.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
-  ${chalk16.cyan('mutagent feedback send "CLI crashed on export" --category cli --attach-transcript --json')}
-
-${chalk16.yellow("AI Agent (MANDATORY):")}
-  ALWAYS use --json: mutagent feedback send "..." --category cli --json
-  Attach the coding-agent session with --attach-transcript (auto-detects the newest session).
-    `).action(() => {
-    feedback.help();
-  });
-  registerFeedbackSend(feedback);
-  return feedback;
+  return { settingsPath, existed, added, alreadyPresent, migrated, userWarning };
 }
-function registerFeedbackSend(feedback) {
-  feedback.command("send").description("Send product feedback about the MutagenT platform or CLI").argument("<feedback>", "The feedback body (content), max 10000 characters").option("--title <string>", "Optional 5–8 word summary of the session timeline").option("--category <value>", `Feedback category: 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'`, "cli").option("--session <id>", "Link this feedback to a session id (maps to server sessionId)").option("--attach-transcript [path]", "Attach the coding-agent session JSONL. Bare = auto-detect newest; or pass an explicit path.").addHelpText("after", `
-${chalk16.bold("Arguments & flags:")}
-  ${chalk16.bold("<feedback>")}              Feedback body / content (required, ≤10000 chars)
-  ${chalk16.bold("--title <string>")}        Optional 5–8 word summary of the session timeline
-  ${chalk16.bold("--category <value>")}      ${chalk16.bold("cli")} (default) | ${chalk16.bold("helix")} | ${chalk16.bold("stage:<")}${VALID_STAGES.join("|")}${chalk16.bold(">")}
-                          ${chalk16.dim("stage = the lifecycle skill (evaluator/diagnostics live under stage:*)")}
-  ${chalk16.bold("--session <id>")}          Link feedback to a session id (server sessionId)
-  ${chalk16.bold("--attach-transcript")} ${chalk16.dim("[path]")}  Attach the coding-agent session JSONL (bare = auto-detect newest)
-  ${chalk16.bold("--json")}                  Structured output (MANDATORY for AI agents)
 
-${chalk16.bold("Examples:")}
-  ${chalk16.dim("$")} mutagent feedback send "The setup flow could show progress better"
-  ${chalk16.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
-  ${chalk16.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
-  ${chalk16.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
-  ${chalk16.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
+// src/commands/hooks/index.ts
+function createHooksCommand() {
+  const hooks = new Command9("hooks").description("Hook handlers for AI coding assistants").addHelpText("after", `
+Claude Code Session Telemetry:
+  Sends lightweight session activity to the MutagenT traces API for observability.
 
-${chalk16.bold("Category:")}
-  ${chalk16.bold("cli")}            Feedback about the CLI itself (default)
-  ${chalk16.bold("helix")}          Feedback about Helix
-  ${chalk16.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
+  Install by adding to .claude/settings.local.json:
 
-${chalk16.bold("Transcript (--attach-transcript):")}
-  Uploads your coding-agent SESSION JSONL as context (raw last-200KB tail) — a
-  SEPARATE artifact from the feedback body. Bare flag auto-detects the newest
-  session across claude-code, codex, and omp; explicit path overrides.
+  {
+    "hooks": {
+      "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
+      "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
+      "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
+      "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}],
+      "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code user-prompt-submit"}]}],
+      "SubagentStart": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-start"}]}],
+      "SubagentStop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-stop"}]}],
+      "PreCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-compact"}]}],
+      "PostCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-compact"}]}],
+      "PostToolUseFailure": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use-failure"}]}]
+    }
+  }
 
-${chalk16.yellow("AI Agent (MANDATORY):")}
-  ALWAYS use --json: mutagent feedback send "..." --json
-  Auto-captured context (harness, CLI version, platform, OS, node version) is included automatically.
-    `).action(async (feedbackBody, options) => {
-    const isJson = getJsonFlag(feedback);
-    const output = new OutputFormatter(isJson ? "json" : "table");
+  Or run: mutagent hooks install
+    `);
+  hooks.command("install").description("Install MutagenT hooks into .claude/settings.local.json (safe merge — never overwrites existing hooks)").option("--cwd <dir>", "Target directory (defaults to cwd)", process.cwd()).addHelpText("after", `
+Reads existing .claude/settings.local.json (if present) and deep-merges
+MutagenT telemetry hooks into each event array (all 10 events). Skips any
+hook already present (checked by command string) so running this multiple
+times is safe.
+    `).action((opts) => {
+    const targetDir = opts.cwd ?? process.cwd();
+    const isJson = Boolean(opts.json);
+    let result;
     try {
-      if (feedbackBody.length > MAX_FEEDBACK_LENGTH) {
-        throw new MutagentError("INVALID_ARGUMENTS", `Feedback exceeds ${String(MAX_FEEDBACK_LENGTH)} characters (${String(feedbackBody.length)}).`, "Shorten the message.");
-      }
-      const { category } = parseCategory(options.category);
-      const apiKey = getApiKey();
-      if (!apiKey) {
-        throw new MutagentError("AUTH_REQUIRED", "Authentication required to send feedback.", `Authenticate first: mutagent auth login
-Or set an API key: mutagent config set apiKey <key>`);
+      result = installHooks(targetDir);
+    } catch (err) {
+      if (err instanceof SettingsParseError) {
+        if (isJson) {
+          process.stdout.write(JSON.stringify({
+            success: false,
+            error: err.message,
+            backupPath: err.backupPath,
+            settingsPath: err.settingsPath
+          }) + `
+`);
+        } else {
+          process.stderr.write(`[mutagent hooks install] ERROR: ${err.message}
+`);
+        }
+        process.exit(1);
       }
-      const transcript = resolveTranscript(options.attachTranscript);
-      const payload = buildPayload(feedbackBody, category, options.title, options.session, transcript);
-      const config = loadConfig();
-      const endpoint = config.endpoint ?? "https://api.mutagent.io";
-      const result = await postToServer(payload, endpoint, apiKey, config.defaultWorkspace, config.defaultOrganization);
-      if (isJson) {
-        output.output({
-          success: true,
-          id: result.id,
-          category,
-          title: options.title,
-          sessionId: options.session,
-          transcriptAttached: transcript !== null,
-          _links: {
-            send: "mutagent feedback send <feedback> [--title <s>] [--category cli|helix|stage:<x>] [--session <id>] [--attach-transcript [path]]"
-          }
-        });
-      } else {
-        const suffix = transcript ? ` + transcript (${String(TAIL_BYTES)}B tail${transcript.truncated ? ", truncated" : ""})` : "";
-        output.success(`Feedback sent! (${category})${suffix}`);
+      throw err;
+    }
+    for (const { event, command } of result.migrated) {
+      process.stderr.write(`[mutagent hooks install] ⚠️  Migrated v1 hook: removed '${event} → ${command}' (v2 wires this as 'SessionEnd')
+`);
+    }
+    if (result.added.length === 0 && result.alreadyPresent.length === 0) {
+      process.stdout.write(JSON.stringify({
+        success: true,
+        settingsPath: result.settingsPath,
+        added: [],
+        alreadyPresent: [],
+        message: "No hooks to install."
+      }) + `
+`);
+      return;
+    }
+    if (result.userWarning) {
+      if (isJson) {} else {
+        process.stderr.write(`⚠ ${result.userWarning}
+`);
       }
-    } catch (error) {
-      handleError(error, isJson);
     }
+    const jsonResponse = {
+      success: true,
+      settingsPath: result.settingsPath,
+      existed: result.existed,
+      added: result.added,
+      alreadyPresent: result.alreadyPresent,
+      message: result.added.length > 0 ? `Installed ${String(result.added.length)} hook(s). ${String(result.alreadyPresent.length)} already present.` : `All hooks already present (${String(result.alreadyPresent.length)}).`
+    };
+    if (result.userWarning && isJson) {
+      jsonResponse.warnings = [result.userWarning];
+    }
+    process.stdout.write(JSON.stringify(jsonResponse) + `
+`);
+  });
+  const claudeCode = hooks.command("claude-code").description("Claude Code session telemetry");
+  claudeCode.command("session-start").description("Handle session start event").action(async () => {
+    await safeExecute(handleSessionStart);
+  });
+  claudeCode.command("session-end").description("Handle session end event").action(async () => {
+    await safeExecute(handleSessionEnd);
+  });
+  claudeCode.command("pre-tool-use").description("Handle pre-tool-use event").action(async () => {
+    await safeExecute(handlePreToolUse);
+  });
+  claudeCode.command("post-tool-use").description("Handle post-tool-use event").action(async () => {
+    await safeExecute(handlePostToolUse);
+  });
+  claudeCode.command("user-prompt-submit").description("Handle user prompt submit event (creates turn span)").action(async () => {
+    await safeExecute(handleUserPromptSubmit);
+  });
+  claudeCode.command("stop").description("Handle stop event (closes current turn span)").action(async () => {
+    await safeExecute(handleStop);
+  });
+  claudeCode.command("subagent-start").description("Handle subagent start event (creates nested agent span)").action(async () => {
+    await safeExecute(handleSubagentStart);
+  });
+  claudeCode.command("subagent-stop").description("Handle subagent stop event (closes subagent span)").action(async () => {
+    await safeExecute(handleSubagentStop);
+  });
+  claudeCode.command("pre-compact").description("Handle pre-compact event (opens compaction span)").action(async () => {
+    await safeExecute(handlePreCompact);
+  });
+  claudeCode.command("post-compact").description("Handle post-compact event (closes compaction span with summary)").action(async () => {
+    await safeExecute(handlePostCompact);
+  });
+  claudeCode.command("post-tool-use-failure").description("Handle post-tool-use-failure event (closes failed span with error status)").action(async () => {
+    await safeExecute(handlePostToolUseFailure);
   });
+  return hooks;
 }
 
-// src/commands/install/index.ts
-import { Command as Command11 } from "commander";
-import chalk17 from "chalk";
-init_errors();
-
-// src/lib/installer.ts
+// src/commands/feedback.ts
+import { Command as Command10 } from "commander";
+import chalk16 from "chalk";
+import { type as osType, release as osRelease } from "os";
+import { readFileSync as readFileSync8 } from "fs";
+import { join as join11, dirname as dirname2 } from "path";
+import { fileURLToPath } from "url";
 init_errors();
 init_config();
-import { spawn as spawn2 } from "child_process";
 
-// src/lib/installer-helix.ts
+// src/lib/transcript.ts
 init_errors();
-init_config();
-import { spawn } from "child_process";
-import { createHash } from "crypto";
-import { homedir as homedir2 } from "os";
-import { join as join11 } from "path";
+import { homedir as osHomedir } from "os";
+import { join as join10 } from "path";
 import {
-  existsSync as existsSync9,
-  mkdirSync as mkdirSync5,
-  readFileSync as readFileSync8,
-  renameSync as renameSync2,
-  rmSync,
-  writeFileSync as writeFileSync6
+  existsSync as fsExistsSync,
+  statSync as fsStatSync,
+  readFileSync as readFileSync7,
+  readdirSync,
+  openSync,
+  readSync,
+  closeSync
 } from "fs";
-async function installHelix(opts, deps = {}) {
-  const auth = (deps.resolveAuth ?? defaultResolveAuth)();
-  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
-  const descriptor = await fetchDescriptor(fetchImpl, auth, opts.version);
-  const baseDir = deps.homeDir ?? join11(homedir2(), ".mutagent", "helix");
-  const versionDir = join11(baseDir, descriptor.version);
-  mkdirSync5(versionDir, { recursive: true });
-  const tgzPath = join11(versionDir, `helix-plugin-${descriptor.version}.tgz`);
-  const tmpPath = `${tgzPath}.${String(process.pid)}.${String(Date.now())}.part`;
-  const download = deps.download ?? defaultDownload;
-  await download(descriptor.url, tmpPath);
-  const sha256 = deps.sha256 ?? defaultSha256;
-  const actual = (await sha256(tmpPath)).toLowerCase();
-  const expected = descriptor.sha256.toLowerCase();
-  if (actual !== expected) {
-    safeRm(tmpPath);
-    throw new MutagentError("INTEGRITY_ERROR", `Downloaded helix plugin failed sha256 verification (expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…).`, "The download may be corrupt or tampered with. Retry: mutagent install helix");
-  }
-  renameSync2(tmpPath, tgzPath);
-  const extract = deps.extract ?? defaultExtract;
-  await extract(tgzPath, versionDir);
-  const locateInitBin = deps.locateInitBin ?? defaultLocateInitBin;
-  const binPath = await locateInitBin(versionDir);
-  const initArgs = ["init", "--harness", opts.harness];
-  if (opts.global)
-    initArgs.push("--global");
-  const runInit = deps.runInit ?? defaultRunInit;
-  const code = await runInit(binPath, initArgs, process.cwd());
-  if (code !== 0) {
-    throw new MutagentError("INSTALL_FAILED", `helix plugin init exited with code ${String(code)}.`, "Re-run: mutagent install helix — or run the plugin init manually and report the error.");
-  }
-  await postTelemetry(fetchImpl, auth, {
-    pkg: "helix",
-    version: descriptor.version,
-    harness: opts.harness,
-    cliVersion: deps.cliVersion ?? readCliVersion()
-  });
-  return { version: descriptor.version };
-}
-async function fetchDescriptor(fetchImpl, auth, version) {
-  if (!auth.apiKey) {
-    throw new MutagentError("AUTH_REQUIRED", "Authentication required to install helix.", "Run: mutagent login");
-  }
-  const url = `${auth.apiBase}/api/helix/plugin/download?version=${encodeURIComponent(version)}`;
-  let res;
-  try {
-    res = await fetchImpl(url, {
-      method: "GET",
-      headers: { "x-api-key": auth.apiKey, ...auth.headers }
-    });
-  } catch {
-    throw new MutagentError("SERVER_UNAVAILABLE", "Could not reach the MutagenT plugin broker.", "Check your network connection or verify the endpoint with: mutagent config show");
-  }
-  if (res.status === 401) {
-    throw new MutagentError("AUTH_REQUIRED", "The plugin broker rejected your credentials.", "Re-authenticate: mutagent login");
-  }
-  if (!res.ok) {
-    const detail = await readErrorMessage(res);
-    throw new MutagentError("INSTALL_FAILED", `Plugin broker returned ${String(res.status)}.${detail ? ` ${detail}` : ""}`, "Verify the requested version exists, then retry: mutagent install helix");
-  }
-  const raw = await res.json();
-  if (!isBrokerResponse(raw)) {
-    throw new MutagentError("INSTALL_FAILED", "Plugin broker returned a malformed response (missing version/sha256/url).", "Retry: mutagent install helix — if it persists, report it.");
+import chalk15 from "chalk";
+var TAIL_BYTES = 200000;
+function defaultReadTail(path, tailBytes) {
+  const { size } = fsStatSync(path);
+  if (size <= tailBytes) {
+    return { content: readFileSync7(path, "utf-8"), truncated: false };
   }
-  return raw;
-}
-async function postTelemetry(fetchImpl, auth, event) {
-  if (!auth.apiKey)
-    return;
-  try {
-    await fetchImpl(`${auth.apiBase}/api/helix/installs`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": auth.apiKey,
-        ...auth.headers
-      },
-      body: JSON.stringify(event)
-    });
-  } catch {}
-}
-function defaultResolveAuth() {
-  const apiKey = getApiKey();
-  const config = loadConfig();
-  const apiBase = config.endpoint ?? "https://api.mutagent.io";
-  const headers = {};
-  if (config.defaultWorkspace)
-    headers["x-workspace-id"] = config.defaultWorkspace;
-  if (config.defaultOrganization)
-    headers["x-organization-id"] = config.defaultOrganization;
-  return { apiBase, apiKey, headers };
-}
-async function defaultDownload(url, destPath) {
-  let res;
+  const fd = openSync(path, "r");
   try {
-    res = await globalThis.fetch(url);
-  } catch {
-    throw new MutagentError("SERVER_UNAVAILABLE", "Failed to download the helix plugin from storage.", "Check your network connection and retry: mutagent install helix");
-  }
-  if (!res.ok) {
-    throw new MutagentError("INSTALL_FAILED", `Plugin download failed with status ${String(res.status)}.`, "The signed URL may have expired — retry: mutagent install helix");
+    const buf = Buffer.alloc(tailBytes);
+    readSync(fd, buf, 0, tailBytes, size - tailBytes);
+    return { content: buf.toString("utf-8"), truncated: true };
+  } finally {
+    closeSync(fd);
   }
-  const bytes = Buffer.from(await res.arrayBuffer());
-  writeFileSync6(destPath, bytes);
-}
-async function defaultSha256(filePath) {
-  return Promise.resolve(createHash("sha256").update(readFileSync8(filePath)).digest("hex"));
 }
-function defaultExtract(tgzPath, destDir) {
-  return new Promise((resolve, reject) => {
-    const child = spawn("tar", ["-xzf", tgzPath, "-C", destDir], {
-      stdio: ["ignore", "ignore", "pipe"]
-    });
-    let stderr = "";
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString("utf-8");
-    });
-    child.on("error", (err) => {
-      reject(new MutagentError("INSTALL_FAILED", `Failed to extract the helix plugin: ${err.message}`, 'Ensure "tar" is installed and available on your PATH.'));
-    });
-    child.on("close", (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(new MutagentError("INSTALL_FAILED", `Extracting the helix plugin failed (tar exit ${String(code ?? 1)}).${stderr ? ` ${stderr.trim().slice(0, 200)}` : ""}`, "The downloaded archive may be corrupt — retry: mutagent install helix"));
-      }
-    });
-  });
+function defaultScan(dir) {
+  if (!fsExistsSync(dir))
+    return [];
+  const out = [];
+  const walk = (current) => {
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join10(current, entry.name);
+      if (entry.isDirectory())
+        walk(full);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+        out.push(full);
+    }
+  };
+  walk(dir);
+  return out;
 }
-function defaultLocateInitBin(extractedDir) {
-  const pkgDir = existsSync9(join11(extractedDir, "package", "package.json")) ? join11(extractedDir, "package") : extractedDir;
-  const pkgJsonPath = join11(pkgDir, "package.json");
-  if (!existsSync9(pkgJsonPath)) {
-    return Promise.reject(new MutagentError("INSTALL_FAILED", "Could not find package.json in the extracted helix plugin.", "The archive layout is unexpected — retry or report: mutagent install helix"));
-  }
-  const raw = JSON.parse(readFileSync8(pkgJsonPath, "utf-8"));
-  const binRel = resolveBinField(raw);
-  if (!binRel) {
-    return Promise.reject(new MutagentError("INSTALL_FAILED", "The helix plugin package.json declares no runnable bin.", "The plugin package is malformed — report: mutagent install helix"));
-  }
-  const binPath = join11(pkgDir, binRel);
-  if (!existsSync9(binPath)) {
-    return Promise.reject(new MutagentError("INSTALL_FAILED", `The helix plugin bin was not found at ${binRel}.`, "The plugin package is incomplete — report: mutagent install helix"));
-  }
-  return Promise.resolve(binPath);
+function buildSources(env, home) {
+  const ompBase = env.PI_CODING_AGENT_DIR ?? join10(home, ".omp", "agent");
+  return [
+    { harness: "claude-code", dir: join10(home, ".claude", "projects") },
+    { harness: "codex", dir: join10(home, ".codex", "sessions") },
+    { harness: "omp", dir: join10(ompBase, "sessions") }
+  ];
 }
-function defaultRunInit(binPath, args, cwd) {
-  return new Promise((resolve, reject) => {
-    const child = spawn("node", [binPath, ...args], { cwd, stdio: "inherit" });
-    child.on("error", (err) => {
-      reject(new MutagentError("INSTALL_FAILED", `Failed to run the helix plugin init: ${err.message}`, 'Ensure "node" is installed and available on your PATH.'));
-    });
-    child.on("close", (code) => {
-      resolve(code ?? 1);
-    });
+function resolveTranscript(attach, deps = {}) {
+  const env = deps.env ?? process.env;
+  const home = (deps.homedir ?? osHomedir)();
+  const existsSync9 = deps.existsSync ?? fsExistsSync;
+  const statSync = deps.statSync ?? fsStatSync;
+  const scan = deps.scan ?? defaultScan;
+  const readTail = deps.readTail ?? defaultReadTail;
+  const warn = deps.warn ?? ((message) => {
+    console.error(message);
   });
-}
-function resolveBinField(pkg) {
-  if (!pkg || typeof pkg !== "object")
-    return;
-  const bin = pkg.bin;
-  if (typeof bin === "string")
-    return bin;
-  if (bin && typeof bin === "object") {
-    const entries = bin;
-    const preferred = entries["mutagent-helix"];
-    if (typeof preferred === "string")
-      return preferred;
-    for (const value of Object.values(entries)) {
-      if (typeof value === "string")
-        return value;
+  if (attach === undefined || attach === false)
+    return null;
+  if (typeof attach === "string" && attach.length > 0) {
+    if (!existsSync9(attach)) {
+      throw new MutagentError("INVALID_ARGUMENTS", `Transcript file not found: ${attach}`, `Verify the path exists: ls -la "${attach}"
+Or omit the path to auto-detect the newest coding-agent session.`);
     }
+    const { content: content2, truncated: truncated2 } = readTail(attach, TAIL_BYTES);
+    return { harness: "unknown", sourcePath: attach, tailBytes: TAIL_BYTES, truncated: truncated2, content: content2 };
   }
-  return;
-}
-function isBrokerResponse(value) {
-  if (!value || typeof value !== "object")
-    return false;
-  const v = value;
-  return typeof v.version === "string" && typeof v.sha256 === "string" && typeof v.url === "string";
-}
-async function readErrorMessage(res) {
-  try {
-    const body = await res.json();
-    if (body && typeof body === "object") {
-      const b = body;
-      if (typeof b.message === "string")
-        return b.message;
-      if (typeof b.error === "string")
-        return b.error;
+  let newest = null;
+  for (const src of buildSources(env, home)) {
+    for (const file of scan(src.dir)) {
+      const { mtimeMs } = statSync(file);
+      if (!newest || mtimeMs > newest.mtimeMs) {
+        newest = { harness: src.harness, path: file, mtimeMs };
+      }
     }
-  } catch {}
-  return;
+  }
+  if (!newest) {
+    warn(chalk15.yellow("⚠ No coding-agent transcript found; sending feedback without one."));
+    return null;
+  }
+  const { content, truncated } = readTail(newest.path, TAIL_BYTES);
+  return {
+    harness: newest.harness,
+    sourcePath: newest.path,
+    tailBytes: TAIL_BYTES,
+    truncated,
+    content
+  };
 }
-function readCliVersion() {
+
+// src/commands/feedback.ts
+var MAX_FEEDBACK_LENGTH = 1e4;
+var VALID_STAGES = ["spec", "build", "evaluate", "diagnose", "optimize"];
+function getCliVersion() {
   if (process.env.CLI_VERSION)
     return process.env.CLI_VERSION;
-  return "unknown";
-}
-function safeRm(path) {
   try {
-    rmSync(path, { force: true });
-  } catch {}
+    const __dirname2 = dirname2(fileURLToPath(import.meta.url));
+    const pkgPath = join11(__dirname2, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    return pkg.version ?? "0.1.1";
+  } catch {
+    return "0.1.1";
+  }
 }
-
-// src/lib/installer.ts
-var VALID_PACKAGES = ["helix", "diagnostics", "evaluator"];
-var VALID_HARNESSES = ["claude-code", "codex", "omp"];
-var VERSION_MATRIX = {
-  helix: "latest",
-  diagnostics: "latest",
-  evaluator: "latest"
-};
-var NPM_PACKAGES = {
-  diagnostics: "@mutagent/diagnostics",
-  evaluator: "@mutagent/evaluator"
-};
-var defaultRunner = (cmd, args) => new Promise((resolve, reject) => {
-  const child = spawn2(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
-  let stdout = "";
-  let stderr = "";
-  child.stdout.on("data", (chunk) => {
-    stdout += chunk.toString("utf-8");
-  });
-  child.stderr.on("data", (chunk) => {
-    stderr += chunk.toString("utf-8");
-  });
-  child.on("error", (err) => {
-    reject(new MutagentError("INSTALL_FAILED", `Failed to run ${cmd}: ${err.message}`, `Ensure "${cmd}" is installed and available on your PATH.`));
-  });
-  child.on("close", (code) => {
-    resolve({ code: code ?? 1, stdout, stderr });
-  });
-});
-function isValidPackage(pkg) {
-  return VALID_PACKAGES.includes(pkg);
+function parseCategory(input) {
+  if (input === "cli" || input === "helix")
+    return { category: input };
+  if (input.startsWith("stage:")) {
+    const stage = input.slice("stage:".length);
+    if (VALID_STAGES.includes(stage)) {
+      return { category: input };
+    }
+    throw new MutagentError("INVALID_ARGUMENTS", `Invalid stage: "${stage}". Must be one of: ${VALID_STAGES.join(", ")}.`, `Use --category stage:<${VALID_STAGES.join("|")}> (e.g. --category stage:evaluate).`);
+  }
+  throw new MutagentError("INVALID_ARGUMENTS", `Invalid category: "${input}". Must be 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'.`, "Run: mutagent feedback send --help");
 }
-function isValidHarness(harness) {
-  return VALID_HARNESSES.includes(harness);
+function buildAutoContext(harness) {
+  return {
+    harness,
+    cliVersion: getCliVersion(),
+    platform: process.platform,
+    os: `${osType()} ${osRelease()}`,
+    nodeVersion: process.version
+  };
 }
-async function installPackage(pkg, opts, deps = {}) {
-  const isAuthed = deps.isAuthed ?? hasCredentials;
-  if (!isAuthed()) {
-    throw new MutagentError("AUTH_REQUIRED", `Authentication required to install ${pkg}.`, "Run: mutagent login");
-  }
-  if (!isValidPackage(pkg)) {
-    throw new MutagentError("INVALID_ARGUMENTS", `Unknown package "${pkg}". Valid: ${VALID_PACKAGES.join(", ")}`, "Run: mutagent install --help");
-  }
-  if (!isValidHarness(opts.harness)) {
-    throw new MutagentError("INVALID_ARGUMENTS", `Unknown harness "${opts.harness}". Valid: ${VALID_HARNESSES.join(", ")}`, "Run: mutagent install --help");
+async function postToServer(payload, endpoint, apiKey, workspaceId, organizationId) {
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": apiKey
+  };
+  if (workspaceId)
+    headers["x-workspace-id"] = workspaceId;
+  if (organizationId)
+    headers["x-organization-id"] = organizationId;
+  let response;
+  try {
+    response = await fetch(`${endpoint}/api/feedback`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload)
+    });
+  } catch {
+    throw new MutagentError("SERVER_UNAVAILABLE", "Server unavailable. Try again later.", "Check your network connection or verify the server endpoint with: mutagent config show");
   }
-  const version = opts.version ?? VERSION_MATRIX[pkg];
-  if (pkg === "helix") {
-    const { version: resolved } = await installHelix({ harness: opts.harness, global: opts.global, version }, deps.helix ?? {});
-    return {
-      package: pkg,
-      version: resolved,
-      harness: opts.harness,
-      global: opts.global
-    };
+  if (response.ok) {
+    return await response.json();
   }
-  const npmPackage = NPM_PACKAGES[pkg];
-  const args = ["install", "-g", `${npmPackage}@${version}`];
-  const runner = deps.runner ?? defaultRunner;
-  const result = await runner("npm", args);
-  if (result.code !== 0) {
-    const detail = result.stderr.trim();
-    throw new MutagentError("INSTALL_FAILED", `npm failed to install ${npmPackage}@${version} (exit ${String(result.code)}).${detail ? ` ${detail.slice(0, 200)}` : ""}`, "Verify the package and version exist and that you have permission for a global npm install.");
+  let errorMessage = `Server returned ${String(response.status)}`;
+  try {
+    const body = await response.json();
+    errorMessage = body.message ?? body.error ?? errorMessage;
+  } catch {}
+  if (response.status === 401) {
+    throw new MutagentError("AUTH_REQUIRED", errorMessage, "Authenticate first: mutagent auth login");
   }
-  return {
-    package: pkg,
-    version,
-    harness: opts.harness,
-    global: opts.global,
-    command: `npm ${args.join(" ")}`
+  throw new MutagentError("API_ERROR", errorMessage, `Server responded with status ${String(response.status)}. Check your configuration with: mutagent config show`);
+}
+function buildPayload(feedback, category, title, session, transcript) {
+  const feedbackV2 = {
+    category,
+    feedback,
+    context: buildAutoContext(transcript?.harness ?? "unknown")
   };
+  if (title)
+    feedbackV2.title = title;
+  if (transcript)
+    feedbackV2.transcript = transcript;
+  const payload = { message: feedback, context: { feedbackV2 } };
+  if (session)
+    payload.sessionId = session;
+  return payload;
+}
+function createFeedbackCommand() {
+  const feedback = new Command10("feedback").description("Send product feedback to MutagenT").addHelpText("after", `
+${chalk16.bold("Examples:")}
+  ${chalk16.cyan('mutagent feedback send "Optimizer results were great"')}
+  ${chalk16.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
+  ${chalk16.cyan('mutagent feedback send "CLI crashed on export" --category cli --attach-transcript --json')}
+
+${chalk16.yellow("AI Agent (MANDATORY):")}
+  ALWAYS use --json: mutagent feedback send "..." --category cli --json
+  Attach the coding-agent session with --attach-transcript (auto-detects the newest session).
+    `).action(() => {
+    feedback.help();
+  });
+  registerFeedbackSend(feedback);
+  return feedback;
+}
+function registerFeedbackSend(feedback) {
+  feedback.command("send").description("Send product feedback about the MutagenT platform or CLI").argument("<feedback>", "The feedback body (content), max 10000 characters").option("--title <string>", "Optional 5–8 word summary of the session timeline").option("--category <value>", `Feedback category: 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'`, "cli").option("--session <id>", "Link this feedback to a session id (maps to server sessionId)").option("--attach-transcript [path]", "Attach the coding-agent session JSONL. Bare = auto-detect newest; or pass an explicit path.").addHelpText("after", `
+${chalk16.bold("Arguments & flags:")}
+  ${chalk16.bold("<feedback>")}              Feedback body / content (required, ≤10000 chars)
+  ${chalk16.bold("--title <string>")}        Optional 5–8 word summary of the session timeline
+  ${chalk16.bold("--category <value>")}      ${chalk16.bold("cli")} (default) | ${chalk16.bold("helix")} | ${chalk16.bold("stage:<")}${VALID_STAGES.join("|")}${chalk16.bold(">")}
+                          ${chalk16.dim("stage = the lifecycle skill (evaluator/diagnostics live under stage:*)")}
+  ${chalk16.bold("--session <id>")}          Link feedback to a session id (server sessionId)
+  ${chalk16.bold("--attach-transcript")} ${chalk16.dim("[path]")}  Attach the coding-agent session JSONL (bare = auto-detect newest)
+  ${chalk16.bold("--json")}                  Structured output (MANDATORY for AI agents)
+
+${chalk16.bold("Examples:")}
+  ${chalk16.dim("$")} mutagent feedback send "The setup flow could show progress better"
+  ${chalk16.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
+  ${chalk16.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
+  ${chalk16.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
+  ${chalk16.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
+
+${chalk16.bold("Category:")}
+  ${chalk16.bold("cli")}            Feedback about the CLI itself (default)
+  ${chalk16.bold("helix")}          Feedback about Helix
+  ${chalk16.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
+
+${chalk16.bold("Transcript (--attach-transcript):")}
+  Uploads your coding-agent SESSION JSONL as context (raw last-200KB tail) — a
+  SEPARATE artifact from the feedback body. Bare flag auto-detects the newest
+  session across claude-code, codex, and omp; explicit path overrides.
+
+${chalk16.yellow("AI Agent (MANDATORY):")}
+  ALWAYS use --json: mutagent feedback send "..." --json
+  Auto-captured context (harness, CLI version, platform, OS, node version) is included automatically.
+    `).action(async (feedbackBody, options) => {
+    const isJson = getJsonFlag(feedback);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      if (feedbackBody.length > MAX_FEEDBACK_LENGTH) {
+        throw new MutagentError("INVALID_ARGUMENTS", `Feedback exceeds ${String(MAX_FEEDBACK_LENGTH)} characters (${String(feedbackBody.length)}).`, "Shorten the message.");
+      }
+      const { category } = parseCategory(options.category);
+      const apiKey = getApiKey();
+      if (!apiKey) {
+        throw new MutagentError("AUTH_REQUIRED", "Authentication required to send feedback.", `Authenticate first: mutagent auth login
+Or set an API key: mutagent config set apiKey <key>`);
+      }
+      const transcript = resolveTranscript(options.attachTranscript);
+      const payload = buildPayload(feedbackBody, category, options.title, options.session, transcript);
+      const config = loadConfig();
+      const endpoint = config.endpoint ?? "https://api.mutagent.io";
+      const result = await postToServer(payload, endpoint, apiKey, config.defaultWorkspace, config.defaultOrganization);
+      if (isJson) {
+        output.output({
+          success: true,
+          id: result.id,
+          category,
+          title: options.title,
+          sessionId: options.session,
+          transcriptAttached: transcript !== null,
+          _links: {
+            send: "mutagent feedback send <feedback> [--title <s>] [--category cli|helix|stage:<x>] [--session <id>] [--attach-transcript [path]]"
+          }
+        });
+      } else {
+        const suffix = transcript ? ` + transcript (${String(TAIL_BYTES)}B tail${transcript.truncated ? ", truncated" : ""})` : "";
+        output.success(`Feedback sent! (${category})${suffix}`);
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
 }
 
 // src/commands/install/index.ts
+import { Command as Command11 } from "commander";
+import chalk17 from "chalk";
+init_errors();
 function createInstallCommand(deps) {
   const install = new Command11("install").description("Install a MutagenT package (helix, diagnostics, evaluator)").argument("<package>", `Package to install: ${VALID_PACKAGES.join(", ")}`).option("--harness <harness>", `Target harness: ${VALID_HARNESSES.join(", ")}`, "claude-code").option("--global", "Install globally", true).option("--version <version>", "Package version to install (default: latest)").addHelpText("after", `
 ${chalk17.bold("Arguments & flags:")}
@@ -5039,7 +5014,7 @@ ${chalk17.bold("Examples:")}
   ${chalk17.dim("$")} mutagent install diagnostics --harness codex --json
 
 ${chalk17.bold("Packages:")}
-  ${chalk17.bold("helix")}        ${chalk17.green("(available)")} — the ADL conductor. Downloaded from a private
+  ${chalk17.bold("helix")}        ${chalk17.green("(available)")} — the ADLC (Agent Development Life Cycle Orchestrator). Downloaded from a private
                  registry via a login-brokered signed URL, sha256-verified, then
                  initialized into your project. No static secret ships in the CLI.
   ${chalk17.bold("diagnostics")}  Public npm package @mutagent/diagnostics ${chalk17.green("(available)")}
@@ -5097,12 +5072,12 @@ program.name("mutagent").description(`MutagenT CLI - command-line client for the
 });
 program.addHelpText("after", `
 ${chalk18.bold.cyan("WORKFLOWS:")}
-  ${chalk18.bold("Setup")}                mutagent login  →  mutagent init  →  mutagent skills install
-  ${chalk18.bold("Lifecycle Tools")}      mutagent install <diagnostics|evaluator>  ${chalk18.dim("(login-gated; helix pending #1191)")}
+  ${chalk18.bold("Setup")}                mutagent login  →  mutagent init
+  ${chalk18.bold("Lifecycle Tools")}      mutagent install <helix|diagnostics|evaluator>  ${chalk18.dim("(login-gated)")}
   ${chalk18.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk18.dim("[--session <id>] [--attach-transcript]")}
 
 ${chalk18.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk18.cyan(".claude/skills/mutagent-cli/SKILL.md")} ${chalk18.dim("(install via")} ${chalk18.cyan("mutagent skills install")}${chalk18.dim(")")}
+${chalk18.cyan(".claude/skills/mutagent-cli/SKILL.md")}
 
 ${chalk18.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
   export MUTAGENT_API_KEY=mt_...  ${chalk18.dim("or")}  --api-key mt_...
@@ -5119,11 +5094,10 @@ ${chalk18.yellow("Command Navigation:")}
   mutagent providers list --json        ${chalk18.dim("List configured BYOK providers")}
   mutagent providers list --models      ${chalk18.dim("See available models per provider")}
 
-  mutagent install diagnostics          ${chalk18.dim("Install diagnostics from npm (login-gated)")}
+  mutagent install helix                ${chalk18.dim("Install the ADL lifecycle conductor (login-gated)")}
   mutagent install evaluator --version 1.2.3  ${chalk18.dim("Pin a version")}
-  mutagent install --help               ${chalk18.dim("helix (pending #1191) | diagnostics | evaluator")}
+  mutagent install --help               ${chalk18.dim("helix | diagnostics | evaluator")}
 
-  mutagent skills install               ${chalk18.dim("Install the MutagenT CLI skill for AI agents")}
   mutagent hooks --help                 ${chalk18.dim("Hook setup for Claude Code session telemetry upload")}
 
 ${chalk18.bold.red("Report Issues:")}
@@ -5143,7 +5117,6 @@ ${chalk18.yellow("Directive System:")}
   ${chalk18.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
 
 ${chalk18.yellow("AI Agent Rules (MANDATORY for coding agents):")}
-  0. If .claude/skills/mutagent-cli/SKILL.md does not exist, run mutagent skills install first
   1. Login (two paths):
      - CI / fully automated: export MUTAGENT_API_KEY=mt_... then mutagent login --json
      - Helping a user onboard: mutagent login --browser --json
@@ -5196,15 +5169,7 @@ program.addCommand(createUsageCommand());
 program.addCommand(createHooksCommand());
 program.addCommand(createInstallCommand());
 program.addCommand(createFeedbackCommand());
-var isInteractive = process.stdin.isTTY && !rawArgs.includes("--json") && process.env.CI !== "true";
-var isSkillCommand = rawArgs[0] === "skills" || rawArgs[0] === "hooks";
-if (isInteractive && !isSkillCommand) {
-  const skillPath = join12(process.cwd(), ".claude/skills/mutagent-cli/SKILL.md");
-  if (!existsSync10(skillPath)) {
-    console.log(chalk18.dim("MutagenT SKILL not installed. Install it for AI agent support? Run:"), chalk18.cyan("mutagent skills install"));
-  }
-}
 program.parse();
 
-//# debugId=9CA84168C389E42C64756E2164756E21
+//# debugId=31350670A929169C64756E2164756E21
 //# sourceMappingURL=cli.js.map