githits 0.4.6 → 0.4.8

package/dist/cli.js

@@ -51,11 +51,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-f16s86ze.js";
+} from "./shared/chunk-6hq1gf0g.js";
 import {
   __require,
   version
-} from "./shared/chunk-a1hzwt2m.js";
+} from "./shared/chunk-wyphcypv.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -331,6 +331,7 @@ var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
   dim: "\x1B[2m",
+  italic: "\x1B[3m",
   green: "\x1B[32m",
   yellow: "\x1B[33m",
   blue: "\x1B[34m",
@@ -338,6 +339,20 @@ var colors = {
   cyan: "\x1B[36m",
   red: "\x1B[31m"
 };
+var brandColors = {
+  primary: {
+    hex: "#FF72BE",
+    rgb: [255, 114, 190],
+    ansi256: 205,
+    ansi16: "magenta"
+  },
+  secondary: {
+    hex: "#FF872F",
+    rgb: [255, 135, 47],
+    ansi256: 208,
+    ansi16: "yellow"
+  }
+};
 function shouldUseColors(noColor) {
   if (noColor)
     return false;
@@ -350,6 +365,32 @@ function colorize(text, color, useColors) {
     return text;
   return `${colors[color]}${text}${colors.reset}`;
 }
+function getColorDepth() {
+  const stream = process.stdout;
+  return stream.getColorDepth?.() ?? 1;
+}
+function foregroundColorCode(color, colorDepth) {
+  if (colorDepth >= 24) {
+    const [red, green, blue] = color.rgb;
+    return `\x1B[38;2;${red};${green};${blue}m`;
+  }
+  if (colorDepth >= 8) {
+    return `\x1B[38;5;${color.ansi256}m`;
+  }
+  return colors[color.ansi16];
+}
+function colorizeTerminal(text, color, useColors, options = {}) {
+  if (!useColors)
+    return text;
+  const colorDepth = options.colorDepth ?? getColorDepth();
+  if (colorDepth <= 1)
+    return text;
+  const prefix = `${options.bold ? colors.bold : ""}${options.dim ? colors.dim : ""}${foregroundColorCode(color, colorDepth)}`;
+  return `${prefix}${text}${colors.reset}`;
+}
+function colorizeBrand(text, colorName, useColors, options) {
+  return colorizeTerminal(text, brandColors[colorName], useColors, options);
+}
 function success(text, useColors) {
   const checkmark = useColors ? `${colors.green}✓${colors.reset}` : "✓";
   return `${checkmark} ${text}`;
@@ -5963,7 +6004,7 @@ auth.storage = "file". File storage is plaintext on disk.
 Use --no-browser in environments without a display (CI, SSH sessions)
 to get a URL you can open on another device.`;
 function registerLoginCommand(program) {
-  program.command("login").summary("Authenticate with your GitHits account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).option("--force", "Re-authenticate even if already logged in").action(async (options) => {
+  program.command("login").summary("Sign in to your GitHits account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).option("--force", "Re-authenticate even if already logged in").action(async (options) => {
     const deps = await createAuthCommandDependencies();
     await loginAction(options, deps);
   });
@@ -6105,6 +6146,61 @@ function getPostLoginContinuationMessage(command) {
       return;
   }
 }
+// src/shared/spinner.ts
+var SPINNER_FRAMES = ["|", "/", "-", "\\"];
+var FRAME_INTERVAL_MS = 80;
+var MESSAGE_INTERVAL_MS = 2000;
+function startSpinner(message, enabled = true, runtime = {}) {
+  const stdoutIsTTY = runtime.stdoutIsTTY ?? process.stdout.isTTY;
+  const stderrIsTTY = runtime.stderrIsTTY ?? process.stderr.isTTY;
+  const writeStderr = runtime.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+  if (!enabled || !stdoutIsTTY || !stderrIsTTY) {
+    return { stop: () => {} };
+  }
+  const messages = typeof message === "string" ? [message] : message;
+  const framesPerMessage = Math.round(MESSAGE_INTERVAL_MS / FRAME_INTERVAL_MS);
+  const useColors = runtime.useColors ?? process.env.NO_COLOR === undefined;
+  let frame = 0;
+  const render = () => {
+    const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? "|";
+    const label = messages[Math.floor(frame / framesPerMessage) % messages.length] ?? "";
+    frame += 1;
+    writeStderr(`\r\x1B[2K${colorizeBrand(glyph, "primary", useColors)} ${label}`);
+  };
+  render();
+  const interval = setInterval(render, FRAME_INTERVAL_MS);
+  return {
+    stop: () => {
+      clearInterval(interval);
+      writeStderr("\r\x1B[2K");
+    }
+  };
+}
+// src/shared/spinner-messages.ts
+var SPINNER_MESSAGES = {
+  example: [
+    "Searching real implementations...",
+    "Exploring open-source code...",
+    "Finding production patterns...",
+    "Grounding results..."
+  ],
+  search: [
+    "Exploring repositories...",
+    "Tracing symbols...",
+    "Inspecting dependencies...",
+    "Scanning source code..."
+  ],
+  code: [
+    "Inspecting source code...",
+    "Resolving symbols...",
+    "Reading dependency internals..."
+  ],
+  docs: [
+    "Reading documentation...",
+    "Resolving references...",
+    "Collecting package docs..."
+  ]
+};
 // src/shared/unified-search-request.ts
 var DEFAULT_UNIFIED_SEARCH_LIMIT = 10;
 function buildUnifiedSearchParams(input) {
@@ -6595,7 +6691,30 @@ function labelsDiverge(input) {
   const served = input.servedTarget;
   if (!served)
     return false;
-  return Boolean(input.freshTarget && input.freshTarget !== served);
+  return Boolean(input.freshTarget && canonicalTargetLabel(input.freshTarget) !== canonicalTargetLabel(served));
+}
+function canonicalTargetLabel(label) {
+  const parsed = parsePackageVersionLabel(label);
+  if (!parsed)
+    return label;
+  const version2 = parsed.version.replace(/^v(?=\d)/i, "");
+  return `${parsed.registry.toLowerCase()}:${parsed.packageName}@${version2}`;
+}
+function parsePackageVersionLabel(label) {
+  const registryEnd = label.indexOf(":");
+  if (registryEnd <= 0)
+    return;
+  const versionStart = label.lastIndexOf("@");
+  if (versionStart <= registryEnd + 1)
+    return;
+  const version2 = label.slice(versionStart + 1);
+  if (!version2)
+    return;
+  return {
+    registry: label.slice(0, registryEnd),
+    packageName: label.slice(registryEnd + 1, versionStart),
+    version: version2
+  };
 }
 function warningForEntry(entry) {
   const reasons = [];
@@ -7650,7 +7769,8 @@ async function pkgFilesAction(firstArg, secondArg, options, deps) {
       limit,
       waitTimeoutMs: wait
     });
-    const result = await deps.codeNavigationService.listFiles(build.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.code, !options.json);
+    const result = await deps.codeNavigationService.listFiles(build.params).finally(() => spinner.stop());
     const payload = buildListFilesSuccessPayload(result, {
       registry: target.registry ? toPkgseerRegistryLowercase(target.registry) : undefined,
       name: target.packageName,
@@ -7786,7 +7906,8 @@ async function pkgGrepAction(first, second, third, options, deps) {
       symbolFields: options.symbolField,
       waitTimeoutMs: wait
     });
-    const result = await deps.codeNavigationService.grepRepo(build.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.code, !options.json);
+    const result = await deps.codeNavigationService.grepRepo(build.params).finally(() => spinner.stop());
     const payload = buildGrepRepoSuccessPayload(result, {
       registry: target.registry ? toPkgseerRegistryLowercase(target.registry) : undefined,
       name: target.packageName,
@@ -7880,7 +8001,7 @@ grep run. --symbol-field hydrates enclosing symbol metadata (appears under each
 match in --verbose output; full payload in --json).`;
 function registerCodeGrepCommand(pkgCommand) {
   return pkgCommand.command("grep").summary("Deterministic text grep over indexed dependency source").description(PKG_GREP_DESCRIPTION).argument("[spec-or-pattern]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the pattern.").argument("[pattern-or-prefix]", "Spec mode: the pattern. Repo mode: optional path-prefix.").argument("[path-prefix]", "Spec mode only: optional path-prefix. Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (defaults to the repo default branch)").option("--git-ref <ref>", "Optional tag, commit, branch, or HEAD for --repo-url.").option("--path <path>", "Exact file path to grep").option("--glob <glob>", "Glob scope (repeatable)", collectRepeatable2, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable2, []).option("--regex", "Interpret the pattern as RE2 regex").option("--case-sensitive", "Enable ASCII case-sensitive matching").option("-C, --context <n>", "Context lines before and after each match (0-10)").option("-B, --before-context <n>", "Context lines before each match (0-10)").option("-A, --after-context <n>", "Context lines after each match (0-10)").option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--limit <n>", "Max matches to return on this page (1-1000, default 50)").option("--per-file-limit <n>", "Cap matches per file within this page (0-1000, 0 = unlimited)").option("--cursor <cursor>", "Opaque nextCursor from a previous grep result").option("--symbol-field <field>", `Repeatable; surfaces in --json and under each --verbose match. ${GREP_REPO_SYMBOL_FIELDS_NOTE}`, collectRepeatable2, []).option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render grouped output with file headers").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, arg3, options) => {
-    const { createContainer: createContainer2 } = await import("./shared/chunk-2fdxv7pe.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-681avsyw.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -7990,7 +8111,8 @@ async function pkgReadAction(firstArg, secondArg, options, deps) {
       endLine: range.endLine,
       waitTimeoutMs: wait
     });
-    const result = await deps.codeNavigationService.readFile(build.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.code, !options.json);
+    const result = await deps.codeNavigationService.readFile(build.params).finally(() => spinner.stop());
     const payload = buildReadFileSuccessPayload(result, {
       registry: target.registry ? toPkgseerRegistryLowercase(target.registry) : undefined,
       name: target.packageName,
@@ -8131,7 +8253,7 @@ async function registerCodeCommandGroup(program, options = {}) {
   if (!registration.shouldRegister) {
     return;
   }
-  const codeCommand = program.command("code").summary("Source-level operations on indexed dependencies").description("List files, read files, and grep substrings inside indexed dependency source. Every command accepts either `<spec>` (registry:name[@version]) or `--repo-url <url> [--git-ref <ref>]`. Omitted package versions use the latest release; omitted repo refs use the default-branch intent. For package-level metadata use `githits pkg`.");
+  const codeCommand = program.command("code").summary("Inspect dependency source code and symbols").description("List files, read files, and grep substrings inside indexed dependency source. Every command accepts either `<spec>` (registry:name[@version]) or `--repo-url <url> [--git-ref <ref>]`. Omitted package versions use the latest release; omitted repo refs use the default-branch intent. For package-level metadata use `githits pkg`.");
   registerCodeFilesCommand(codeCommand);
   registerCodeReadCommand(codeCommand);
   registerCodeGrepCommand(codeCommand);
@@ -8152,7 +8274,8 @@ async function docsListAction(spec, options, deps) {
       limit,
       after: options.after
     });
-    const result = await deps.packageIntelligenceService.listPackageDocs(build.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.docs, !options.json);
+    const result = await deps.packageIntelligenceService.listPackageDocs(build.params).finally(() => spinner.stop());
     const payload = buildListPackageDocsSuccessPayload(result, {
       limitExplicit: build.limitExplicit,
       afterExplicit: build.afterExplicit,
@@ -8222,7 +8345,8 @@ async function docsReadAction(pageId, options, deps) {
     }
     const range = options.lines ? parseLinesOption(options.lines) : undefined;
     const build = buildReadPackageDocParams({ pageId });
-    const result = await deps.packageIntelligenceService.readPackageDoc(build.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.docs, !options.json);
+    const result = await deps.packageIntelligenceService.readPackageDoc(build.params).finally(() => spinner.stop());
     const payload = buildReadPackageDocSuccessPayload(result, build.params.pageId, range);
     if (options.json) {
       console.log(JSON.stringify(payload));
@@ -8275,7 +8399,7 @@ async function registerDocsCommandGroup(program, options = {}) {
   if (!registration.shouldRegister) {
     return;
   }
-  const docsCommand = program.command("docs").summary("Browse and read mixed package documentation").description("Browse and read package documentation across hosted docs and repository-backed docs. Docs are mixed by default; entries are source-badged and repo-backed pages also expose exact file follow-up metadata.");
+  const docsCommand = program.command("docs").summary("Browse and read package documentation").description("Browse and read package documentation across hosted docs and repository-backed docs. Docs are mixed by default; entries are source-badged and repo-backed pages also expose exact file follow-up metadata.");
   registerDocsListCommand(docsCommand);
   registerDocsReadCommand(docsCommand);
 }
@@ -8288,12 +8412,13 @@ async function exampleAction(query, options, deps) {
   }
   requireAuth(deps);
   try {
+    const spinner = startSpinner(SPINNER_MESSAGES.example, !options.json);
     const result = await deps.githitsService.search({
       query,
       language: options.lang,
       licenseMode: options.license,
       includeExplanation: options.explain
-    });
+    }).finally(() => spinner.stop());
     if (options.json) {
       const solutionId = extractSolutionId(result);
       const payload = solutionId ? { result, solution_id: solutionId } : { result };
@@ -8328,7 +8453,7 @@ Examples:
   githits example "react hooks patterns" -l typescript --explain
   githits example "react hooks patterns" -l typescript --json`;
 function registerExampleCommand(program) {
-  program.command("example").summary("Get code examples from global open source").description(EXAMPLE_DESCRIPTION).argument("<query>", "Natural language example-search query").option("-l, --lang <language>", "Optional programming language; omitted values are inferred by GitHits").addOption(new Option("--license <mode>", "License filter mode").choices(["strict", "yolo", "custom"]).default(undefined)).option("--explain", "Include AI-generated explanation").option("--json", "Output as JSON for piping").action(async (query, options) => {
+  program.command("example").summary("Find real-world implementations from open-source code").description(EXAMPLE_DESCRIPTION).argument("<query>", "Natural language example-search query").option("-l, --lang <language>", "Optional programming language; omitted values are inferred by GitHits").addOption(new Option("--license <mode>", "License filter mode").choices(["strict", "yolo", "custom"]).default(undefined)).option("--explain", "Include AI-generated explanation").option("--json", "Output as JSON for piping").action(async (query, options) => {
     try {
       const deps = await loadContainer();
       await exampleAction(query, options, deps);
@@ -8340,7 +8465,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-2fdxv7pe.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-681avsyw.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -8388,7 +8513,7 @@ Examples:
   githits feedback --accept --tool code_grep -m "regex is fast on npm:lodash"
   githits feedback --reject --tool search -m "missing kotlin support"`;
 function registerFeedbackCommand(program) {
-  program.command("feedback").summary("Submit feedback on a tool result or the GitHits experience").description(FEEDBACK_DESCRIPTION).argument("[solution_id]", "Solution ID from a prior 'githits example' result (omit for generic feedback)").addOption(new Option2("--accept", "Mark as helpful").conflicts("reject")).addOption(new Option2("--reject", "Mark as unhelpful").conflicts("accept")).option("-m, --message <text>", "Feedback explanation").option("--tool <name>", "Command or MCP tool name being rated").option("--json", "Output as JSON for piping").action(async (solutionId, options) => {
+  program.command("feedback").summary("Submit feedback about GitHits results or experience").description(FEEDBACK_DESCRIPTION).argument("[solution_id]", "Solution ID from a prior 'githits example' result (omit for generic feedback)").addOption(new Option2("--accept", "Mark as helpful").conflicts("reject")).addOption(new Option2("--reject", "Mark as unhelpful").conflicts("accept")).option("-m, --message <text>", "Feedback explanation").option("--tool <name>", "Command or MCP tool name being rated").option("--json", "Output as JSON for piping").action(async (solutionId, options) => {
     try {
       const deps = await createContainer();
       await feedbackAction(solutionId, options, deps);
@@ -8404,11 +8529,21 @@ import {
   parse as parseJsonc,
   printParseErrorCode
 } from "jsonc-parser";
+import {
+  isMap,
+  isScalar,
+  parseDocument,
+  parse as parseYaml,
+  stringify as stringifyYaml
+} from "yaml";
+function normalizeConfigContent(content) {
+  if (content.charCodeAt(0) === 65279) {
+    return content.slice(1);
+  }
+  return content;
+}
 function parseConfigObject(content) {
-  let normalizedContent = content;
-  if (normalizedContent.charCodeAt(0) === 65279) {
-    normalizedContent = normalizedContent.slice(1);
-  }
+  const normalizedContent = normalizeConfigContent(content);
   const trimmed = normalizedContent.trim();
   if (trimmed === "") {
     return {
@@ -8456,6 +8591,221 @@ function parseConfigObject(content) {
     };
   }
 }
+function parseYamlConfigObject(content) {
+  const normalizedContent = normalizeConfigContent(content);
+  if (normalizedContent.trim() === "") {
+    return { value: {} };
+  }
+  try {
+    const parsed = parseYaml(normalizedContent);
+    if (parsed === null || parsed === undefined) {
+      return { value: {} };
+    }
+    if (!isPlainObject(parsed)) {
+      return { error: "Config file root is not a YAML object" };
+    }
+    return { value: parsed };
+  } catch (err) {
+    return {
+      error: `Invalid YAML: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function formatYamlError(error2) {
+  if (error2 instanceof Error) {
+    return error2.message;
+  }
+  return String(error2);
+}
+function parseYamlConfigDocument(content) {
+  const normalizedContent = normalizeConfigContent(content);
+  const source = normalizedContent.trim() === "" ? `{}
+` : normalizedContent;
+  let doc;
+  try {
+    doc = parseDocument(source);
+  } catch (err) {
+    return {
+      status: "error",
+      error: `Invalid YAML: ${formatYamlError(err)}`
+    };
+  }
+  if (doc.errors.length > 0) {
+    const firstError = doc.errors[0];
+    return {
+      status: "error",
+      error: `Invalid YAML: ${formatYamlError(firstError)}`
+    };
+  }
+  const contents = doc.contents;
+  if (!contents || !isMap(contents)) {
+    return {
+      status: "error",
+      error: "Config file root is not a YAML object"
+    };
+  }
+  return {
+    status: "ok",
+    doc,
+    root: contents
+  };
+}
+function toYamlConfigShapeError(serversKey) {
+  return `"${serversKey}" is not a YAML object`;
+}
+function toYamlKeyString(key) {
+  if (typeof key === "string") {
+    return key;
+  }
+  if (!isScalar(key) || typeof key.value !== "string") {
+    return null;
+  }
+  return key.value;
+}
+function getYamlMatchingServerKeys(serversMap, serverName) {
+  const normalizedTarget = serverName.toLowerCase();
+  return serversMap.items.map((pair) => toYamlKeyString(pair.key)).filter((key) => typeof key === "string" && key.toLowerCase() === normalizedTarget);
+}
+function yamlNodeToJsValue(value) {
+  if (typeof value === "object" && value !== null && "toJSON" in value && typeof value.toJSON === "function") {
+    return value.toJSON();
+  }
+  return value;
+}
+function createEmptyYamlMapNode() {
+  const map = parseDocument(`{}
+`).contents;
+  if (!map || !isMap(map)) {
+    throw new Error("Failed to initialize YAML object node");
+  }
+  return map;
+}
+function ensureYamlServersMapForSetup(root, serversKey) {
+  const existingServers = root.get(serversKey, true);
+  if (existingServers === undefined || existingServers === null || isScalar(existingServers) && existingServers.value === null) {
+    root.set(serversKey, createEmptyYamlMapNode());
+    const initializedServers = root.get(serversKey, true);
+    if (!initializedServers || !isMap(initializedServers)) {
+      return {
+        status: "error",
+        error: toYamlConfigShapeError(serversKey)
+      };
+    }
+    return {
+      status: "ok",
+      serversMap: initializedServers
+    };
+  }
+  if (!isMap(existingServers)) {
+    return {
+      status: "error",
+      error: toYamlConfigShapeError(serversKey)
+    };
+  }
+  return {
+    status: "ok",
+    serversMap: existingServers
+  };
+}
+function getYamlServersMapForUninstall(root, serversKey) {
+  const existingServers = root.get(serversKey, true);
+  if (existingServers === undefined || existingServers === null || isScalar(existingServers) && existingServers.value === null) {
+    return { status: "not_configured" };
+  }
+  if (!isMap(existingServers)) {
+    return {
+      status: "error",
+      error: toYamlConfigShapeError(serversKey)
+    };
+  }
+  return {
+    status: "ok",
+    serversMap: existingServers
+  };
+}
+function renderYamlDocument(doc) {
+  const rendered = doc.toString();
+  return rendered.endsWith(`
+`) ? rendered : `${rendered}
+`;
+}
+function mergeYamlServerConfig(existingContent, serversKey, serverName, serverConfig) {
+  const parsed = parseYamlConfigDocument(existingContent);
+  if (parsed.status === "error") {
+    return { status: "parse_error", error: parsed.error };
+  }
+  const serversResult = ensureYamlServersMapForSetup(parsed.root, serversKey);
+  if (serversResult.status !== "ok") {
+    return {
+      status: "parse_error",
+      error: serversResult.status === "error" ? serversResult.error : toYamlConfigShapeError(serversKey)
+    };
+  }
+  const { serversMap } = serversResult;
+  const matchingKeys = getYamlMatchingServerKeys(serversMap, serverName);
+  if (matchingKeys.length === 1 && matchingKeys[0] === serverName) {
+    const existingValue = yamlNodeToJsValue(serversMap.get(serverName, true));
+    if (isEquivalentConfiguredValue(existingValue, serverConfig)) {
+      return { status: "already_configured" };
+    }
+  }
+  for (const key of matchingKeys) {
+    serversMap.delete(key);
+  }
+  const hadExisting = matchingKeys.length > 0;
+  serversMap.set(serverName, serverConfig);
+  return {
+    status: hadExisting ? "updated" : "added",
+    content: renderYamlDocument(parsed.doc)
+  };
+}
+function removeYamlServerConfig(existingContent, serversKey, serverName) {
+  const parsed = parseYamlConfigDocument(existingContent);
+  if (parsed.status === "error") {
+    return { status: "parse_error", error: parsed.error };
+  }
+  const serversResult = getYamlServersMapForUninstall(parsed.root, serversKey);
+  if (serversResult.status === "not_configured") {
+    return { status: "not_configured" };
+  }
+  if (serversResult.status === "error") {
+    return {
+      status: "parse_error",
+      error: serversResult.error
+    };
+  }
+  const matchingKeys = getYamlMatchingServerKeys(serversResult.serversMap, serverName);
+  if (matchingKeys.length === 0) {
+    return { status: "not_configured" };
+  }
+  for (const key of matchingKeys) {
+    serversResult.serversMap.delete(key);
+  }
+  return {
+    status: "removed",
+    content: renderYamlDocument(parsed.doc)
+  };
+}
+function parseConfigObjectForFormat(content, format = "json") {
+  if (format === "yaml") {
+    return parseYamlConfigObject(content);
+  }
+  const parsed = parseConfigObject(content);
+  if (parsed.format === "invalid") {
+    return { error: parsed.error };
+  }
+  return { value: parsed.value };
+}
+function renderConfigObjectForFormat(config, format = "json") {
+  if (format === "yaml") {
+    const rendered = stringifyYaml(config);
+    return rendered.endsWith(`
+`) ? rendered : `${rendered}
+`;
+  }
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8563,9 +8913,12 @@ function getMatchingServerKeys(servers, serverName) {
   const normalizedTarget = serverName.toLowerCase();
   return Object.keys(servers).filter((key) => key.toLowerCase() === normalizedTarget);
 }
-function mergeServerConfig(existingContent, serversKey, serverName, serverConfig) {
-  const parsedConfig = parseConfigObject(existingContent);
-  if (parsedConfig.format === "invalid") {
+function mergeServerConfig(existingContent, serversKey, serverName, serverConfig, format = "json") {
+  if (format === "yaml") {
+    return mergeYamlServerConfig(existingContent, serversKey, serverName, serverConfig);
+  }
+  const parsedConfig = parseConfigObjectForFormat(existingContent, format);
+  if ("error" in parsedConfig) {
     return {
       status: "parse_error",
       error: parsedConfig.error
@@ -8594,13 +8947,15 @@ function mergeServerConfig(existingContent, serversKey, serverName, serverConfig
   serversObj[serverName] = serverConfig;
   return {
     status: hadExisting ? "updated" : "added",
-    content: `${JSON.stringify(config, null, 2)}
-`
+    content: renderConfigObjectForFormat(config, format)
   };
 }
-function removeServerConfig(existingContent, serversKey, serverName) {
-  const parsedConfig = parseConfigObject(existingContent);
-  if (parsedConfig.format === "invalid") {
+function removeServerConfig(existingContent, serversKey, serverName, format = "json") {
+  if (format === "yaml") {
+    return removeYamlServerConfig(existingContent, serversKey, serverName);
+  }
+  const parsedConfig = parseConfigObjectForFormat(existingContent, format);
+  if ("error" in parsedConfig) {
     return {
       status: "parse_error",
       error: parsedConfig.error
@@ -8627,24 +8982,9 @@ function removeServerConfig(existingContent, serversKey, serverName) {
   }
   return {
     status: "removed",
-    content: `${JSON.stringify(config, null, 2)}
-`
+    content: renderConfigObjectForFormat(config, format)
   };
 }
-function formatSetupPreview(config) {
-  if (config.method === "composite") {
-    return config.steps.map((step) => formatSetupPreview(step)).join(`
-`);
-  }
-  if (config.method === "cli") {
-    return config.commands.map((cmd) => `Will run: ${cmd.command} ${cmd.args.join(" ")}`).join(`
-`);
-  }
-  const snippet = JSON.stringify({ [config.serverName]: config.serverConfig }, null, 2);
-  return `Will add to ${config.configPath}:
-
-${snippet}`;
-}
 function formatUninstallPreview(config) {
   if (config.method === "composite") {
     return config.steps.map(({ step }) => formatUninstallPreview(step)).join(`
@@ -8659,8 +8999,8 @@ function formatUninstallPreview(config) {
 async function isAlreadyConfigured(config, fs) {
   try {
     const content = await fs.readFile(config.configPath);
-    const parsedConfig = parseConfigObject(content);
-    if (parsedConfig.format === "invalid") {
+    const parsedConfig = parseConfigObjectForFormat(content, config.format);
+    if ("error" in parsedConfig) {
       return false;
     }
     const parsed = parsedConfig.value;
@@ -8681,21 +9021,21 @@ async function isAlreadyConfigured(config, fs) {
 async function getConfigUninstallCheckStatus(config, fs) {
   try {
     const content = await fs.readFile(config.configPath);
-    const parsedConfig = parseConfigObject(content);
-    if (parsedConfig.format === "invalid") {
+    const parsedConfig = parseConfigObjectForFormat(content, config.format);
+    if ("error" in parsedConfig) {
       return {
         status: "failed",
         message: `Cannot parse ${config.configPath}: ${parsedConfig.error}. File left unchanged.`
       };
     }
     const servers = parsedConfig.value[config.serversKey];
-    if (servers === undefined) {
+    if (servers === undefined || servers === null) {
       return { status: "not_configured" };
     }
     if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
       return {
         status: "failed",
-        message: `Cannot parse ${config.configPath}: "${config.serversKey}" is not a JSON object. File left unchanged.`
+        message: `Cannot parse ${config.configPath}: "${config.serversKey}" is not a ${config.format === "yaml" ? "YAML" : "JSON"} object. File left unchanged.`
       };
     }
     const hasEntry = getMatchingServerKeys(servers, config.serverName).length > 0;
@@ -8954,7 +9294,7 @@ async function executeConfigFileSetup(setup, fs) {
         };
       }
     }
-    const result = mergeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.serverConfig);
+    const result = mergeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.serverConfig, setup.format);
     if (result.status === "already_configured") {
       return {
         status: "already_configured",
@@ -9019,7 +9359,7 @@ async function executeConfigFileUninstall(setup, fs) {
         message: `Cannot read ${setup.configPath}: ${err instanceof Error ? err.message : String(err)}`
       };
     }
-    const result = removeServerConfig(existingContent, setup.serversKey, setup.serverName);
+    const result = removeServerConfig(existingContent, setup.serversKey, setup.serverName, setup.format);
     if (result.status === "not_configured") {
       return {
         status: "not_configured",
@@ -9107,6 +9447,16 @@ function getPiAgentDir(fs) {
 function getPiMcpConfigPath(fs) {
   return fs.joinPath(getPiAgentDir(fs), "mcp.json");
 }
+function getHermesHomeDir(fs) {
+  const configuredDir = process.env.HERMES_HOME?.trim();
+  if (configuredDir) {
+    return expandHomePath(fs, configuredDir);
+  }
+  return fs.joinPath(fs.getHomeDir(), ".hermes");
+}
+function getHermesConfigPath(fs) {
+  return fs.joinPath(getHermesHomeDir(fs), "config.yaml");
+}
 function getOpenCodeDesktopDetectPaths(fs) {
   const userDataRoot = getUserDataRoot(fs);
   return [
@@ -9501,6 +9851,25 @@ var openCode = {
     }
   })
 };
+var hermesAgent = {
+  name: "Hermes Agent",
+  id: "hermes-agent",
+  detectionMethod: "hybrid",
+  setupMethod: "config-file",
+  detectPaths: (fs) => [getHermesHomeDir(fs)],
+  detectBinary: async (exec) => isExecutableAvailable(exec, "hermes-agent"),
+  getSetupConfig: (fs) => ({
+    method: "config-file",
+    format: "yaml",
+    configPath: getHermesConfigPath(fs),
+    serversKey: "mcp_servers",
+    serverName: GITHITS_SERVER_NAME,
+    serverConfig: {
+      command: GITHITS_MCP_COMMAND,
+      args: [...GITHITS_MCP_ARGS]
+    }
+  })
+};
 var agentDefinitions = [
   claudeCode,
   cursor,
@@ -9512,91 +9881,108 @@ var agentDefinitions = [
   pi,
   geminiCli,
   googleAntigravity,
-  openCode
+  openCode,
+  hermesAgent
 ];
-async function scanAgents(definitions, fs, execService) {
-  const result = {
-    needsSetup: [],
-    alreadyConfigured: [],
-    notDetected: []
-  };
-  for (const agent of definitions) {
-    let detected = false;
-    let setupContext;
-    if (agent.detectCommand) {
-      try {
-        const resolvedCommand = await agent.detectCommand(execService, fs);
-        if (resolvedCommand) {
-          detected = true;
-          setupContext = { command: resolvedCommand.command };
-        }
-      } catch {
-        detected = false;
+async function scanSingleAgent(agent, fs, execService) {
+  let detected = false;
+  let setupContext;
+  if (agent.detectCommand) {
+    try {
+      const resolvedCommand = await agent.detectCommand(execService, fs);
+      if (resolvedCommand) {
+        detected = true;
+        setupContext = { command: resolvedCommand.command };
+      }
+    } catch {
+      detected = false;
+    }
+  } else if (agent.detectionMethod === "binary" && agent.detectBinary) {
+    try {
+      detected = await agent.detectBinary(execService);
+    } catch {
+      detected = false;
+    }
+  } else if (agent.detectionMethod === "path" && agent.detectPaths) {
+    const paths = agent.detectPaths(fs);
+    for (const path of paths) {
+      if (await fs.isDirectory(path)) {
+        detected = true;
+        break;
       }
-    } else if (agent.detectionMethod === "binary" && agent.detectBinary) {
+    }
+  } else if (agent.detectionMethod === "hybrid") {
+    let binaryDetected = false;
+    let pathDetected = false;
+    if (agent.detectBinary) {
       try {
-        detected = await agent.detectBinary(execService);
+        binaryDetected = await agent.detectBinary(execService);
       } catch {
-        detected = false;
+        binaryDetected = false;
       }
-    } else if (agent.detectionMethod === "path" && agent.detectPaths) {
+    }
+    if (!binaryDetected && agent.detectPaths) {
       const paths = agent.detectPaths(fs);
       for (const path of paths) {
         if (await fs.isDirectory(path)) {
-          detected = true;
+          pathDetected = true;
           break;
         }
       }
-    } else if (agent.detectionMethod === "hybrid") {
-      let binaryDetected = false;
-      let pathDetected = false;
-      if (agent.detectBinary) {
-        try {
-          binaryDetected = await agent.detectBinary(execService);
-        } catch {
-          binaryDetected = false;
-        }
-      }
-      if (!binaryDetected && agent.detectPaths) {
-        const paths = agent.detectPaths(fs);
-        for (const path of paths) {
-          if (await fs.isDirectory(path)) {
-            pathDetected = true;
-            break;
-          }
-        }
-      }
-      detected = binaryDetected || pathDetected;
     }
-    if (!detected) {
-      result.notDetected.push(agent);
-      continue;
+    detected = binaryDetected || pathDetected;
+  }
+  if (!detected) {
+    return { status: "not_detected", agent };
+  }
+  const config = agent.getSetupConfig(fs, setupContext);
+  const scannedAgent = {
+    ...agent,
+    resolvedSetupConfig: config,
+    resolvedSetupContext: setupContext
+  };
+  if (agent.id === "gemini-cli" && config.method === "cli") {
+    if (!config.checkCommand) {
+      return { status: "needs_setup", agent: scannedAgent };
+    }
+    const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
+    let configured = checkStatus === "configured";
+    if (!configured && checkStatus === "probe_failed") {
+      configured = await isGeminiExtensionInstalledFromFilesystem(fs);
     }
-    const config = agent.getSetupConfig(fs, setupContext);
-    const scannedAgent = {
-      ...agent,
-      resolvedSetupConfig: config,
-      resolvedSetupContext: setupContext
+    return {
+      status: configured ? "already_configured" : "needs_setup",
+      agent: scannedAgent
     };
-    if (agent.id === "gemini-cli" && config.method === "cli") {
-      if (config.checkCommand) {
-        const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
-        let configured = checkStatus === "configured";
-        if (!configured && checkStatus === "probe_failed") {
-          configured = await isGeminiExtensionInstalledFromFilesystem(fs);
-        }
-        if (configured) {
-          result.alreadyConfigured.push(scannedAgent);
-        } else {
-          result.needsSetup.push(scannedAgent);
-        }
-      } else {
-        result.needsSetup.push(scannedAgent);
-      }
-    } else if (await isSetupAlreadyConfigured(config, fs, execService)) {
-      result.alreadyConfigured.push(scannedAgent);
+  }
+  if (await isSetupAlreadyConfigured(config, fs, execService)) {
+    return { status: "already_configured", agent: scannedAgent };
+  }
+  return { status: "needs_setup", agent: scannedAgent };
+}
+async function scanAgents(definitions, fs, execService, options = {}) {
+  const result = {
+    needsSetup: [],
+    alreadyConfigured: [],
+    notDetected: []
+  };
+  let completed = 0;
+  const outcomes = await Promise.all(definitions.map((agent) => scanSingleAgent(agent, fs, execService).then((outcome) => {
+    completed += 1;
+    options.onProgress?.({
+      completed,
+      total: definitions.length,
+      agent: outcome.agent
+    });
+    return outcome;
+  })));
+  for (const outcome of outcomes) {
+    if (outcome.status === "already_configured") {
+      result.alreadyConfigured.push(outcome.agent);
+    } else if (outcome.status === "needs_setup") {
+      result.needsSetup.push(outcome.agent);
     } else {
-      result.needsSetup.push(scannedAgent);
+      result.notDetected.push(outcome.agent);
     }
   }
   return result;
@@ -9606,6 +9992,17 @@ class ExitPromptError extends Error {
   name = "ExitPromptError";
 }
 // src/commands/init/init.ts
+function createInitLoginOutput() {
+  return {
+    write: (message) => {
+      const lines = message.replace(/\n$/, "").split(`
+`);
+      for (const line of lines) {
+        console.log(line.length > 0 ? `    ${line}` : "");
+      }
+    }
+  };
+}
 function getResolvedSetupConfig(agent, fileSystemService) {
   return agent.resolvedSetupConfig ?? agent.getSetupConfig(fileSystemService, agent.resolvedSetupContext);
 }
@@ -9620,62 +10017,859 @@ function getPiConfigFileUninstall(agent, fileSystemService) {
   const configStep = uninstallConfig.steps.map(({ step }) => step).find((step) => step.method === "config-file");
   return configStep ?? null;
 }
+function formatCommand(command, useColors) {
+  return colorizeBrand(command, "secondary", useColors, { bold: true });
+}
+var AGENT_SAFE_CLI = "npx -y githits@latest";
+var AGENT_DETECT_COMMAND = `${AGENT_SAFE_CLI} init --detect-agents`;
+var AGENT_INSTALL_COMMAND = `${AGENT_SAFE_CLI} init --install-agents`;
+var AGENT_LOGIN_COMMAND = `${AGENT_SAFE_CLI} login`;
+var AGENT_LOGIN_NO_BROWSER_COMMAND = `${AGENT_SAFE_CLI} login --no-browser`;
+var AGENTIC_INIT_YES_WARNING = "Do not run `githits init -y` or `githits init --yes` unless the user explicitly asks to configure every detected tool.";
+var AGENTIC_INIT_VERIFY_INSTRUCTION = "After a successful --install-agents run, verify with --detect-agents --json instead of running init again.";
+var AGENTIC_INIT_JSON_VERIFY_INSTRUCTION = "Do not run init again after a successful --install-agents run; verify with --detect-agents --json instead.";
 function printReadyNextSteps() {
-  console.log("  Setup complete. You're ready to use GitHits.");
+  console.log("  GitHits is now connected to your coding agents.");
+  console.log();
+  console.log("  Here are some examples of the new abilities that your agent just got:");
+  console.log();
+  console.log("  • Find usage examples");
+  console.log("      -> “Find a real example of using Azure Speech SDK TranscribeDefinition”");
+  console.log();
+  console.log("  • Search, grep, list files, and read exact lines in any repo or package to gather information");
+  console.log("      -> “How does Next.js implement route prefetching internally?”");
+  console.log();
+  console.log("  • Inspect dependency versions, changelogs, and upgrade changes");
+  console.log("      -> “What changed between pydantic-ai 1.95 and 1.99?”");
   console.log();
-  console.log("  Try a quick code example search:");
-  console.log('    npx githits@latest example "How do I use useEffect cleanup?"');
+  console.log("  Open a new coding agent session and try out one of the above.");
   console.log();
-  console.log("  Or ask your agent to explore a real codebase:");
-  console.log("    Use GitHits to inspect postgres/postgres and explain how the query planner selects join strategies.");
+  console.log('  In your normal workflow, your agent will call GitHits automatically depending on the task, but you can prompt it to use GitHits explicitly by adding "use GitHits".');
+  console.log();
+  console.log("  See docs for more use cases and trigger guides: https://docs.githits.com");
 }
-async function verifyAgentConfigured(agent, fileSystemService, execService) {
-  const postCheck = await scanAgents([agent], fileSystemService, execService);
-  if (postCheck.alreadyConfigured.some((a) => a.id === agent.id)) {
-    return { ok: true };
-  }
-  if (postCheck.needsSetup.some((a) => a.id === agent.id)) {
-    return {
-      ok: false,
-      message: `${agent.name} verification failed: not configured after setup.`
-    };
-  }
-  return {
-    ok: false,
-    message: `${agent.name} verification failed: agent not detected after setup.`
-  };
+function printAuthRequiredNextSteps(useColors) {
+  console.log("  GitHits MCP is configured, but sign-in is still needed.");
+  console.log();
+  console.log("  Sign in when you're ready:");
+  console.log(`    ${formatCommand("npx githits@latest login", useColors)}`);
 }
-async function verifyAgentUnconfigured(agent, fileSystemService, execService) {
-  const postCheck = await scanAgents([agent], fileSystemService, execService);
-  if (postCheck.needsSetup.some((a) => a.id === agent.id)) {
-    return { ok: true };
-  }
-  if (postCheck.notDetected.some((a) => a.id === agent.id)) {
-    return {
-      ok: false,
-      message: `${agent.name} verification failed: agent was not detected after uninstall, so removal could not be confirmed.`
-    };
-  }
-  return {
-    ok: false,
-    message: `${agent.name} verification failed: still configured after uninstall.`
-  };
+function printAuthNotCheckedNextSteps(useColors) {
+  console.log("  GitHits MCP is configured. Sign-in was not checked.");
+  console.log();
+  console.log("  If your agent asks you to sign in, run:");
+  console.log(`    ${formatCommand("npx githits@latest login", useColors)}`);
 }
-async function inspectSetupForUninstall(agent, config, fileSystemService, execService) {
-  if (config.method === "config-file") {
-    const check = await getConfigUninstallCheckStatus(config, fileSystemService);
-    if (check.status === "configured")
-      return "configured";
-    if (check.status === "not_configured")
-      return "not_configured";
-    return { status: "failed", message: check.message };
-  }
-  if (config.method === "cli") {
-    if (!config.checkCommand) {
-      return {
-        status: "failed",
-        message: `${agent.name} does not have a verified uninstall check command.`
-      };
+function printAgenticLoginInstructions(useColors) {
+  console.log("  Authentication is still required before agents can use GitHits.");
+  console.log();
+  console.log("  Agent instruction:");
+  console.log();
+  console.log("  Ask the user:");
+  console.log(`    "GitHits needs to open a browser sign-in page. The sign-in happens in your browser, not in this chat or terminal. I will not see or handle your credentials. Should I run \`${AGENT_LOGIN_COMMAND}\` now?"`);
+  console.log();
+  console.log("  If the user approves, run:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_COMMAND, useColors)}`);
+  console.log();
+  console.log("  If the browser cannot open, run:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_NO_BROWSER_COMMAND, useColors)}`);
+}
+function printAgenticAlreadyAuthenticated() {
+  console.log("  GitHits MCP is installed and you are already signed in.");
+  console.log();
+  console.log("  Open a new coding agent session so it reloads MCP config.");
+}
+function printAgenticAuthNotChecked(useColors) {
+  console.log("  GitHits MCP is installed. Sign-in status was not checked.");
+  console.log();
+  console.log("  If the user is not already signed in, ask before running:");
+  console.log(`    ${formatCommand(AGENT_LOGIN_COMMAND, useColors)}`);
+}
+function printNonInteractiveInitGuidance(useColors) {
+  console.log("  This setup is interactive. Because this session is non-interactive, no changes were made.");
+  console.log();
+  console.log("  If you are an AI coding agent helping a user install GitHits:");
+  console.log();
+  console.log("  1. Run:");
+  console.log(`     ${formatCommand(AGENT_DETECT_COMMAND, useColors)}`);
+  console.log();
+  console.log("  2. Show the detected tools to the user.");
+  console.log();
+  console.log("  3. Ask which tools should receive the GitHits MCP server.");
+  console.log();
+  console.log("  4. Only after approval, run:");
+  console.log(`     ${formatCommand(`${AGENT_INSTALL_COMMAND} <ids>`, useColors)}`);
+  console.log();
+  console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+  console.log(`  ${AGENTIC_INIT_VERIFY_INSTRUCTION}`);
+}
+function printNonInteractiveYesRejected(useColors) {
+  console.error("Non-interactive `githits init --yes` is not supported because it can configure tools without explicit per-tool approval.");
+  console.error();
+  console.error("Use the agent-safe staged flow instead:");
+  console.error(`  ${formatCommand(AGENT_DETECT_COMMAND, useColors)}`);
+  console.error(`  ${formatCommand(`${AGENT_INSTALL_COMMAND} <ids>`, useColors)}`);
+  process.exitCode = 1;
+}
+var GITHITS_ASCII_LOGO = String.raw`
+   ____ _ _   _   _ _ _       
+  / ___(_) |_| | | (_) |_ ___ 
+ | |  _| | __| |_| | | __/ __|
+ | |_| | | |_|  _  | | |_\__ \
+  \____|_|\__|_| |_|_|\__|___/
+`;
+var LOGO_GRADIENT = [
+  {
+    until: 13,
+    color: {
+      hex: "#FF4FAE",
+      rgb: [255, 79, 174],
+      ansi256: 205,
+      ansi16: "magenta"
+    }
+  },
+  {
+    until: 19,
+    color: {
+      hex: "#FF5D8E",
+      rgb: [255, 93, 142],
+      ansi256: 204,
+      ansi16: "magenta"
+    }
+  },
+  {
+    until: 21,
+    color: {
+      hex: "#FF6B6F",
+      rgb: [255, 107, 111],
+      ansi256: 203,
+      ansi16: "red"
+    }
+  },
+  {
+    until: 25,
+    color: { hex: "#FF794F", rgb: [255, 121, 79], ansi256: 209, ansi16: "red" }
+  },
+  {
+    until: 30,
+    color: {
+      hex: "#FF872F",
+      rgb: [255, 135, 47],
+      ansi256: 208,
+      ansi16: "yellow"
+    }
+  }
+];
+function colorizeLogo(logo, useColors) {
+  if (!useColors) {
+    return logo;
+  }
+  return logo.split(`
+`).map((line) => {
+    if (line.length === 0) {
+      return line;
+    }
+    let cursor2 = 0;
+    let colored = "";
+    for (const { until, color } of LOGO_GRADIENT) {
+      if (cursor2 >= line.length) {
+        break;
+      }
+      colored += colorizeTerminal(line.slice(cursor2, until), color, useColors);
+      cursor2 = until;
+    }
+    return cursor2 < line.length ? colored + line.slice(cursor2) : colored;
+  }).join(`
+`);
+}
+var INIT_INTENT_CHOICES = [
+  {
+    name: "Connect GitHits to my agent (Recommended)",
+    value: "mcp",
+    description: "Install the local GitHits MCP server for your coding agents. Allows agents to seamlessly use GitHits."
+  },
+  {
+    name: "Use Agent Skills instead",
+    value: "skills",
+    description: "Use Skills instead of the local MCP server."
+  },
+  {
+    name: "Exit",
+    value: "later",
+    description: "Leave setup without making changes."
+  }
+];
+var AUTH_RECOVERY_CHOICES = [
+  { name: "Retry sign in", value: "retry" },
+  {
+    name: "Configure MCP without signing in",
+    value: "continue_without_auth",
+    description: "Your agent will ask you to sign in before using GitHits."
+  },
+  { name: "Cancel setup", value: "cancel" }
+];
+var AUTH_START_CHOICES = [
+  {
+    name: "Sign in now",
+    value: "sign_in",
+    description: "Open your browser and connect this CLI to GitHits."
+  },
+  {
+    name: "Skip for now",
+    value: "skip",
+    description: "Finish MCP setup and sign in later with `githits login`."
+  },
+  { name: "Cancel setup", value: "cancel" }
+];
+function printSection(index, title, useColors) {
+  console.log();
+  console.log(`  ${colorizeBrand(`${index}. ${title}`, "primary", useColors, { bold: true })}`);
+  console.log(`  ${colorize("-".repeat(title.length + 3), "dim", useColors)}`);
+}
+function printTask(status, label, detail, useColors) {
+  const suffix = detail ? `  ${colorize(detail, "dim", useColors)}` : "";
+  if (status === "success") {
+    console.log(`    ${success(label, useColors)}${suffix}`);
+  } else if (status === "failed") {
+    console.log(`    ${error(label, useColors)}${suffix}`);
+  } else if (status === "warning") {
+    console.log(`    ${warning(label, useColors)}${suffix}`);
+  } else {
+    console.log(`    ${colorize("○", "dim", useColors)} ${label}${suffix}`);
+  }
+}
+function printInitIntro(useColors) {
+  console.log(colorizeLogo(GITHITS_ASCII_LOGO, useColors));
+  console.log("  Your agent can only read your local codebase.");
+  console.log();
+  console.log("  GitHits lets it navigate the open-source code your app depends on.");
+  console.log();
+  console.log(`  ${colorizeBrand("With GitHits, your agent can:", "primary", useColors)}`);
+  console.log("  • Find implementation examples from open-source code, issues, discussions, and pull requests");
+  console.log("  • Search, grep, list files, and read exact lines in any repo or package");
+  console.log("  • Inspect dependency internals, versions, changelogs, and upgrade changes");
+  console.log("  • Access package documentation");
+  console.log();
+  console.log("  No cloning or local indexing required. GitHits handles everything automatically.");
+  console.log();
+  console.log("  Works with Cursor, Claude Code, Codex, OpenCode, Pi, VS Code, Windsurf, and more.");
+  console.log();
+  console.log("  More info: https://docs.githits.com");
+  console.log();
+}
+function printSkillsInstructions(useColors) {
+  console.log(`
+  Install GitHits Agent Skills:`);
+  console.log();
+  console.log(`    ${formatCommand("npx skills add githits-com/githits-cli", useColors)}`);
+  console.log();
+  console.log("  During setup, choose where you want to enable GitHits.");
+  console.log();
+  console.log("  IMPORTANT: Use either Agent Skills or the local MCP server in the same");
+  console.log("  coding tool, not both.");
+  console.log();
+  console.log("  Then sign in so your agent can use GitHits:");
+  console.log();
+  console.log(`    ${formatCommand("npx githits@latest login", useColors)}`);
+  console.log();
+}
+function startSafeInitScan(fileSystemService, execService, onProgress) {
+  return scanAgents(agentDefinitions, fileSystemService, execService, {
+    onProgress
+  }).then((scan) => ({ ok: true, scan })).catch((error2) => ({
+    ok: false,
+    error: error2 instanceof Error ? error2 : new Error(String(error2))
+  }));
+}
+function createScanProgressReporter(useColors) {
+  if (!process.stdout.isTTY) {
+    return { onProgress: () => {}, finish: () => {} };
+  }
+  let wrote = false;
+  return {
+    onProgress: (progress) => {
+      const width = 20;
+      const filled = Math.round(progress.completed / progress.total * width);
+      const bar = `${colorizeBrand("#".repeat(filled), "primary", useColors)}${"-".repeat(width - filled)}`;
+      const line = `  Scanning tools [${bar}] ${progress.completed}/${progress.total} ${progress.agent.name}`;
+      process.stdout.write(`\r\x1B[2K${line}`);
+      wrote = true;
+    },
+    finish: () => {
+      if (wrote) {
+        process.stdout.write("\r\x1B[2K");
+      }
+    }
+  };
+}
+function createInstallTaskReporter(useColors) {
+  if (!process.stdout.isTTY) {
+    return {
+      start: (label) => {
+        printTask("skipped", label, "installing...", useColors);
+        return () => {};
+      }
+    };
+  }
+  const frames = ["-", "\\", "|", "/"];
+  return {
+    start: (label) => {
+      let frame = 0;
+      const render = () => {
+        const spinner = colorizeBrand(frames[frame % frames.length] ?? "-", "primary", useColors);
+        frame += 1;
+        process.stdout.write(`\r\x1B[2K    ${spinner} ${label}  installing...`);
+      };
+      render();
+      const interval = setInterval(render, 80);
+      return () => {
+        clearInterval(interval);
+        process.stdout.write("\r\x1B[2K");
+      };
+    }
+  };
+}
+async function unwrapSafeScan(scanPromise) {
+  const result = await scanPromise;
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.scan;
+}
+function formatAgentNames(agents) {
+  if (agents.length === 0)
+    return "none";
+  if (agents.length === 1)
+    return agents[0]?.name ?? "unknown";
+  if (agents.length === 2) {
+    return `${agents[0]?.name ?? "unknown"} and ${agents[1]?.name ?? "unknown"}`;
+  }
+  const names = agents.map((agent) => agent.name);
+  return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+}
+function buildInitAgentChoices(scan) {
+  return [
+    ...scan.needsSetup.map((agent) => ({
+      name: `${agent.name} (detected)`,
+      value: agent,
+      checked: true
+    })),
+    ...scan.alreadyConfigured.map((agent) => ({
+      name: `${agent.name} (already configured)`,
+      value: agent,
+      disabled: "already configured"
+    }))
+  ];
+}
+function printScanSummary(scan, useColors) {
+  const detected = scan.needsSetup.length + scan.alreadyConfigured.length;
+  for (const agent of scan.alreadyConfigured) {
+    printTask("success", agent.name, "already configured", useColors);
+  }
+  for (const agent of scan.needsSetup) {
+    printTask("warning", agent.name, "needs setup", useColors);
+  }
+  if (scan.notDetected.length > 0) {
+    printTask("skipped", `${scan.notDetected.length} supported tool${scan.notDetected.length !== 1 ? "s" : ""} not found`, formatAgentNames(scan.notDetected), useColors);
+  }
+  if (detected > 0) {
+    console.log();
+    console.log(`    Found ${detected} supported tool${detected !== 1 ? "s" : ""}.`);
+  }
+}
+function buildStagedAgentEntries(scan) {
+  const statuses = new Map;
+  for (const agent of scan.needsSetup)
+    statuses.set(agent.id, "needs_setup");
+  for (const agent of scan.alreadyConfigured) {
+    statuses.set(agent.id, "already_configured");
+  }
+  for (const agent of scan.notDetected)
+    statuses.set(agent.id, "not_detected");
+  return agentDefinitions.map((agent) => ({
+    id: agent.id,
+    name: agent.name,
+    status: statuses.get(agent.id) ?? "not_detected"
+  }));
+}
+function printAgenticDetectSummary(scan, useColors) {
+  const entries = buildStagedAgentEntries(scan);
+  const detected = entries.filter((entry) => entry.status !== "not_detected");
+  const installable = entries.filter((entry) => entry.status === "needs_setup");
+  const notDetected = entries.filter((entry) => entry.status === "not_detected");
+  console.log("Detected supported tools:");
+  console.log();
+  if (detected.length === 0) {
+    console.log("  None detected.");
+  } else {
+    console.log("  ID                 Tool                  Status");
+    for (const entry of detected) {
+      console.log(`  ${entry.id.padEnd(18)} ${entry.name.padEnd(21)} ${entry.status.replace("_", " ")}`);
+    }
+  }
+  console.log();
+  console.log("Not detected:");
+  console.log(`  ${notDetected.length > 0 ? notDetected.map((entry) => entry.id).join(", ") : "none"}`);
+  console.log();
+  if (detected.length === 0) {
+    console.log("No supported AI coding tools detected.");
+    console.log();
+    console.log("Next step for agents:");
+    console.log("  Tell the user to install a supported coding tool, then run detection again.");
+    return;
+  }
+  if (installable.length === 0) {
+    console.log("No detected tools need setup.");
+    console.log();
+    console.log("Next step for agents:");
+    console.log("  Tell the user that GitHits is already configured for detected tools.");
+    console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+    console.log("  Do not run init again as a verification step.");
+    return;
+  }
+  const installableIds = installable.map((entry) => entry.id);
+  console.log("Next step for agents:");
+  console.log();
+  console.log("  Ask the user:");
+  console.log(`    "GitHits can be installed for ${installable.map((entry) => entry.name).join(", ")}. Which should I configure?"`);
+  console.log();
+  console.log("  If the user approves all detected tools needing setup, run:");
+  console.log(`    ${formatCommand(`${AGENT_INSTALL_COMMAND} ${installableIds.join(",")}`, useColors)}`);
+  console.log();
+  console.log(`  ${AGENTIC_INIT_YES_WARNING}`);
+  console.log(`  ${AGENTIC_INIT_VERIFY_INSTRUCTION}`);
+}
+function printAgenticDetectJson(scan) {
+  const entries = buildStagedAgentEntries(scan);
+  const installableIds = entries.filter((entry) => entry.status === "needs_setup").map((entry) => entry.id);
+  console.log(JSON.stringify({
+    mode: "detect-agents",
+    agents: entries,
+    installableIds,
+    suggestedCommand: installableIds.length > 0 ? `${AGENT_INSTALL_COMMAND} ${installableIds.join(",")}` : null,
+    instructions: [
+      "Show detected tools to the user.",
+      "Ask which tools should receive the GitHits MCP server.",
+      "Only run --install-agents with user-approved IDs.",
+      AGENTIC_INIT_YES_WARNING,
+      AGENTIC_INIT_JSON_VERIFY_INSTRUCTION
+    ]
+  }, null, 2));
+}
+function getStagedModeCount(options) {
+  return [
+    options.detectAgents === true,
+    options.installAgents !== undefined
+  ].filter(Boolean).length;
+}
+function failInitArgument(message, json) {
+  if (json) {
+    console.error(JSON.stringify({ error: message, code: "INVALID_ARGUMENT" }));
+  } else {
+    console.error(message);
+  }
+  process.exitCode = 1;
+}
+function validateInitModeOptions(options) {
+  const stagedModeCount = getStagedModeCount(options);
+  if (stagedModeCount > 1) {
+    failInitArgument("Use only one staged init mode: --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  if (options.yes && stagedModeCount > 0) {
+    failInitArgument("--yes cannot be combined with --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  if (options.json && stagedModeCount === 0) {
+    failInitArgument("--json is only supported with --detect-agents or --install-agents.", options.json);
+    return false;
+  }
+  return true;
+}
+function parseAgentIdList(value) {
+  if (!value)
+    return [];
+  const ids = value.split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+  return [...new Set(ids)];
+}
+function findAgentsByIds(scan, ids) {
+  const detected = [...scan.needsSetup, ...scan.alreadyConfigured];
+  return ids.map((id) => detected.find((agent) => agent.id === id)).filter((agent) => Boolean(agent));
+}
+function validateInstallAgentIds(scan, ids) {
+  const supportedIds = new Set(agentDefinitions.map((agent) => agent.id));
+  const detectedIds = [...scan.needsSetup, ...scan.alreadyConfigured].map((agent) => agent.id);
+  const detectedIdSet = new Set(detectedIds);
+  if (ids.length === 0) {
+    return {
+      ok: false,
+      message: detectedIds.length > 0 ? `Provide at least one agent ID. Detected IDs: ${detectedIds.join(", ")}.` : "Provide at least one agent ID. No supported agents are currently detected.",
+      detectedIds
+    };
+  }
+  const unknown = ids.filter((id) => !supportedIds.has(id));
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      message: `Unsupported agent ID${unknown.length !== 1 ? "s" : ""}: ${unknown.join(", ")}.`,
+      detectedIds
+    };
+  }
+  const undetected = ids.filter((id) => !detectedIdSet.has(id));
+  if (undetected.length > 0) {
+    return {
+      ok: false,
+      message: `Agent ID${undetected.length !== 1 ? "s" : ""} not detected: ${undetected.join(", ")}. Detected IDs: ${detectedIds.length > 0 ? detectedIds.join(", ") : "none"}.`,
+      detectedIds
+    };
+  }
+  return { ok: true };
+}
+function printInstallValidationFailure(failure, json) {
+  if (json) {
+    console.error(JSON.stringify({
+      error: failure.message,
+      code: "INVALID_ARGUMENT",
+      detectedIds: failure.detectedIds
+    }));
+  } else {
+    console.error(failure.message);
+  }
+  process.exitCode = 1;
+}
+function hasUsableInstallOutcome(outcomes) {
+  return outcomes.some((outcome) => outcome.status === "success" || outcome.status === "already_configured");
+}
+async function getStagedInstallAuthStatus(createLoginDeps) {
+  if (!createLoginDeps)
+    return "not_checked";
+  try {
+    const loginDeps = await createLoginDeps();
+    if (typeof loginDeps.hasValidToken === "boolean") {
+      return loginDeps.hasValidToken ? "authenticated" : "required";
+    }
+    const tokens = await loginDeps.authStorage.loadTokens(loginDeps.mcpUrl);
+    const expired = tokens?.expiresAt ? new Date(tokens.expiresAt) < new Date : false;
+    return tokens && !expired ? "authenticated" : "required";
+  } catch {
+    return "not_checked";
+  }
+}
+function buildAgenticInstallAuthPayload(authStatus) {
+  if (authStatus === "authenticated") {
+    return { required: false, status: "authenticated" };
+  }
+  if (authStatus === "required") {
+    return {
+      required: true,
+      status: "required",
+      command: AGENT_LOGIN_COMMAND,
+      noBrowserCommand: AGENT_LOGIN_NO_BROWSER_COMMAND
+    };
+  }
+  return {
+    required: null,
+    status: "not_checked",
+    command: AGENT_LOGIN_COMMAND,
+    noBrowserCommand: AGENT_LOGIN_NO_BROWSER_COMMAND
+  };
+}
+function buildAgenticInstallInstructions(authStatus) {
+  if (authStatus === "authenticated") {
+    return ["Open a new coding agent session so it reloads MCP config."];
+  }
+  if (authStatus === "required") {
+    return [
+      `Ask the user before running ${AGENT_LOGIN_COMMAND}.`,
+      "Browser sign-in happens outside chat and terminal input.",
+      "Do not ask the user to paste passwords, tokens, cookies, or OAuth codes into chat."
+    ];
+  }
+  return [
+    "Sign-in status was not checked.",
+    `If the user is not already signed in, ask before running ${AGENT_LOGIN_COMMAND}.`
+  ];
+}
+function printAgenticInstallJson(outcomes, authStatus) {
+  const canAuthenticate = hasUsableInstallOutcome(outcomes);
+  console.log(JSON.stringify({
+    mode: "install-agents",
+    outcomes,
+    auth: canAuthenticate ? buildAgenticInstallAuthPayload(authStatus) : {
+      required: false,
+      status: "not_applicable",
+      reason: "Fix installation errors before starting sign-in."
+    },
+    instructions: canAuthenticate ? buildAgenticInstallInstructions(authStatus) : ["Fix installation errors before asking the user to sign in."]
+  }, null, 2));
+}
+async function runDetectAgentsMode(options, fileSystemService, execService, useColors) {
+  const scan = await scanAgents(agentDefinitions, fileSystemService, execService);
+  if (options.json) {
+    printAgenticDetectJson(scan);
+    return;
+  }
+  printAgenticDetectSummary(scan, useColors);
+}
+async function runInstallAgentsMode(options, fileSystemService, execService, createLoginDeps, useColors) {
+  const requestedIds = parseAgentIdList(options.installAgents);
+  const scan = await scanAgents(agentDefinitions, fileSystemService, execService);
+  const validation = validateInstallAgentIds(scan, requestedIds);
+  if (!validation.ok) {
+    printInstallValidationFailure(validation, options.json);
+    return;
+  }
+  const agents = findAgentsByIds(scan, requestedIds);
+  if (!options.json) {
+    console.log("Installing GitHits MCP:");
+    console.log();
+  }
+  const outcomes = await installSelectedAgents(agents, scan, fileSystemService, execService, useColors, !options.json);
+  const failed = outcomes.filter((outcome) => outcome.status === "failed");
+  const canAuthenticate = hasUsableInstallOutcome(outcomes);
+  const authStatus = canAuthenticate ? await getStagedInstallAuthStatus(createLoginDeps) : "not_checked";
+  if (failed.length > 0) {
+    process.exitCode = 1;
+  }
+  if (options.json) {
+    printAgenticInstallJson(outcomes, authStatus);
+    return;
+  }
+  console.log();
+  if (failed.length === 0) {
+    console.log("GitHits MCP installation complete.");
+  } else {
+    console.log("GitHits MCP installation completed with errors.");
+    for (const outcome of failed) {
+      console.log(`  ${outcome.name}: ${outcome.message ?? "Unknown error"}`);
+    }
+  }
+  console.log();
+  if (canAuthenticate) {
+    if (authStatus === "authenticated") {
+      printAgenticAlreadyAuthenticated();
+    } else if (authStatus === "required") {
+      printAgenticLoginInstructions(useColors);
+    } else {
+      printAgenticAuthNotChecked(useColors);
+    }
+  } else {
+    console.log("Fix installation errors before starting sign-in.");
+  }
+  console.log();
+}
+function printAuthExplanation() {
+  console.log("    GitHits authentication is required before your agent can use GitHits tools.");
+  console.log();
+  console.log("    We'll open your browser to connect your account.");
+  console.log("    Credentials are stored securely in your OS keychain.");
+  console.log();
+  console.log("    No API keys or secrets are written into your MCP config.");
+  console.log();
+}
+async function runInitAuthentication(options, promptService, createLoginDeps, useColors) {
+  if (options.skipLogin) {
+    console.log(`  Skipping authentication (--skip-login).
+`);
+    return "skipped";
+  }
+  if (!createLoginDeps) {
+    printTask("warning", "Sign-in unavailable", "sign in later with `githits login`", useColors);
+    return "unavailable";
+  }
+  while (true) {
+    let loginResult;
+    try {
+      const loginDeps = await createLoginDeps();
+      if (loginDeps.hasValidToken) {
+        printTask("success", "Already signed in", undefined, useColors);
+        return "authenticated";
+      }
+      printAuthExplanation();
+      if (!options.yes) {
+        let authChoice;
+        try {
+          authChoice = await promptService.select("  Continue with browser sign-in?", AUTH_START_CHOICES, "sign_in");
+        } catch (err) {
+          if (err instanceof ExitPromptError) {
+            console.log(`
+  Setup cancelled.
+`);
+            return "cancelled";
+          }
+          throw err;
+        }
+        if (authChoice === "skip") {
+          printTask("warning", "Sign-in skipped", "your agent will ask you to sign in later", useColors);
+          return "skipped";
+        }
+        if (authChoice === "cancel") {
+          console.log("\n  Setup cancelled. Run `githits login` to authenticate.\n");
+          return "cancelled";
+        }
+      }
+      loginResult = await loginFlow({}, loginDeps, createInitLoginOutput());
+    } catch (error2) {
+      const msg = error2 instanceof Error ? error2.message : String(error2);
+      loginResult = { status: "failed", message: msg };
+    }
+    if (loginResult.status === "already_authenticated") {
+      printTask("success", "Already signed in", undefined, useColors);
+      return "authenticated";
+    }
+    if (loginResult.status === "success") {
+      printTask("success", "Signed in successfully", undefined, useColors);
+      return "authenticated";
+    }
+    console.log(`    ${warning(`Login failed: ${loginResult.message}`, useColors)}
+`);
+    printAuthRecoveryHint(useColors);
+    if (options.yes) {
+      console.log(`    Continuing without authentication...
+`);
+      return "failed_continue";
+    }
+    let choice;
+    try {
+      choice = await promptService.select("  Authentication failed. What would you like to do?", AUTH_RECOVERY_CHOICES, "retry");
+    } catch (err) {
+      if (err instanceof ExitPromptError) {
+        console.log(`
+  Setup cancelled.
+`);
+        return "cancelled";
+      }
+      throw err;
+    }
+    if (choice === "retry") {
+      console.log();
+      continue;
+    }
+    if (choice === "cancel") {
+      console.log("\n  Setup cancelled. Run `githits login` to authenticate.\n");
+      return "cancelled";
+    }
+    console.log(`    Continuing without authentication...
+`);
+    return "failed_continue";
+  }
+}
+function shouldPrintReady(authStatus) {
+  return authStatus === "authenticated";
+}
+function printPostSetupNextSteps(authStatus, useColors) {
+  printSection(5, shouldPrintReady(authStatus) ? "Ready" : "Next Steps", useColors);
+  if (shouldPrintReady(authStatus)) {
+    printReadyNextSteps();
+  } else if (authStatus === "failed_continue") {
+    printAuthRequiredNextSteps(useColors);
+  } else {
+    printAuthNotCheckedNextSteps(useColors);
+  }
+}
+async function verifyAgentConfigured(agent, fileSystemService, execService) {
+  const postCheck = await scanAgents([agent], fileSystemService, execService);
+  if (postCheck.alreadyConfigured.some((a) => a.id === agent.id)) {
+    return { ok: true };
+  }
+  if (postCheck.needsSetup.some((a) => a.id === agent.id)) {
+    return {
+      ok: false,
+      message: `${agent.name} verification failed: not configured after setup.`
+    };
+  }
+  return {
+    ok: false,
+    message: `${agent.name} verification failed: agent not detected after setup.`
+  };
+}
+async function executeAgentSetupWithVerification(agent, fileSystemService, execService) {
+  const config = getResolvedSetupConfig(agent, fileSystemService);
+  let result = config.method === "cli" ? await executeCliSetup(config, execService) : config.method === "config-file" ? await executeConfigFileSetup(config, fileSystemService) : await executeCompositeSetup(config, fileSystemService, execService);
+  if (result.status === "success" || result.status === "already_configured") {
+    const verification = await verifyAgentConfigured(agent, fileSystemService, execService);
+    if (!verification.ok) {
+      result = {
+        status: "failed",
+        message: agent.id === "gemini-cli" ? "Gemini installation did not complete. Retry, or run: gemini extensions install --consent https://github.com/githits-com/githits-cli" : verification.message ?? `${agent.name} verification failed after setup.`
+      };
+    }
+  }
+  return result;
+}
+async function installSelectedAgents(agents, scan, fileSystemService, execService, useColors, printResults) {
+  const alreadyConfiguredIds = new Set(scan.alreadyConfigured.map((agent) => agent.id));
+  const outcomes = [];
+  const installTasks = createInstallTaskReporter(useColors);
+  for (const agent of agents) {
+    if (alreadyConfiguredIds.has(agent.id)) {
+      outcomes.push({
+        id: agent.id,
+        name: agent.name,
+        status: "already_configured"
+      });
+      if (printResults) {
+        printTask("warning", agent.name, "already configured", useColors);
+      }
+      continue;
+    }
+    const finishTask = printResults ? installTasks.start(agent.name) : () => {};
+    let result;
+    try {
+      result = await executeAgentSetupWithVerification(agent, fileSystemService, execService);
+    } finally {
+      finishTask();
+    }
+    outcomes.push({
+      id: agent.id,
+      name: agent.name,
+      status: result.status,
+      message: result.status === "failed" ? result.message : undefined
+    });
+    if (!printResults) {
+      continue;
+    }
+    if (result.status === "success") {
+      printTask("success", agent.name, "configured and verified", useColors);
+    } else if (result.status === "already_configured") {
+      printTask("warning", agent.name, "already configured", useColors);
+    } else {
+      printTask("failed", agent.name, result.message, useColors);
+    }
+  }
+  return outcomes;
+}
+async function verifyAgentUnconfigured(agent, fileSystemService, execService) {
+  const postCheck = await scanAgents([agent], fileSystemService, execService);
+  if (postCheck.needsSetup.some((a) => a.id === agent.id)) {
+    return { ok: true };
+  }
+  if (postCheck.notDetected.some((a) => a.id === agent.id)) {
+    return {
+      ok: false,
+      message: `${agent.name} verification failed: agent was not detected after uninstall, so removal could not be confirmed.`
+    };
+  }
+  return {
+    ok: false,
+    message: `${agent.name} verification failed: still configured after uninstall.`
+  };
+}
+async function inspectSetupForUninstall(agent, config, fileSystemService, execService) {
+  if (config.method === "config-file") {
+    const check = await getConfigUninstallCheckStatus(config, fileSystemService);
+    if (check.status === "configured")
+      return "configured";
+    if (check.status === "not_configured")
+      return "not_configured";
+    return { status: "failed", message: check.message };
+  }
+  if (config.method === "cli") {
+    if (!config.checkCommand) {
+      return {
+        status: "failed",
+        message: `${agent.name} does not have a verified uninstall check command.`
+      };
     }
     const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
     if (checkStatus === "configured")
@@ -9764,166 +10958,120 @@ async function scanAgentsForUninstall(fileSystemService, execService) {
 async function initAction(options, deps) {
   const useColors = shouldUseColors();
   const { fileSystemService, promptService, execService, createLoginDeps } = deps;
-  let continuedWithoutAuth = false;
-  console.log(`
-  ${colorize("GitHits", "bold", useColors)} — Set up MCP server for your coding agents
-`);
-  if (!options.skipLogin && createLoginDeps) {
-    console.log(`  Checking authentication...
-`);
-    let loginResult;
-    try {
-      const loginDeps = await createLoginDeps();
-      loginResult = loginDeps.hasValidToken ? { status: "already_authenticated", message: "Already logged in." } : await loginFlow({}, loginDeps);
-    } catch (error2) {
-      const msg = error2 instanceof Error ? error2.message : String(error2);
-      loginResult = { status: "failed", message: msg };
-    }
-    if (loginResult.status === "already_authenticated") {
-      console.log(`    ${success("Already authenticated", useColors)}
-`);
-    } else if (loginResult.status === "success") {
-      console.log(`    ${success("Logged in successfully", useColors)}
-`);
-    } else {
-      console.log(`    ${warning(`Login failed: ${loginResult.message}`, useColors)}
-`);
-      printAuthRecoveryHint();
-      if (!options.yes) {
-        try {
-          const choice = await promptService.confirm3("Continue without authentication?");
-          if (choice === "no") {
-            console.log("\n  Setup cancelled. Run `githits login` to authenticate.\n");
-            return;
-          }
-        } catch (err) {
-          if (err instanceof ExitPromptError) {
-            console.log(`
-  Setup cancelled.
-`);
-            return;
-          }
-          throw err;
-        }
-      }
-      continuedWithoutAuth = true;
-      console.log(`    Continuing without authentication...
-`);
-    }
-  }
-  console.log(`  Scanning for available agents...
-`);
-  const scan = await scanAgents(agentDefinitions, fileSystemService, execService);
-  for (const agent of scan.alreadyConfigured) {
-    console.log(`    ${success(`${agent.name} — already configured`, useColors)}`);
-  }
-  for (const agent of scan.needsSetup) {
-    console.log(`    ${colorize(`● ${agent.name} — needs setup`, "cyan", useColors)}`);
+  const isInteractive = deps.isInteractive ?? true;
+  if (!validateInitModeOptions(options)) {
+    return;
   }
-  for (const agent of scan.notDetected) {
-    console.log(`    ${colorize(`${agent.name} — not detected`, "dim", useColors)}`);
+  if (options.detectAgents) {
+    await runDetectAgentsMode(options, fileSystemService, execService, useColors);
+    return;
   }
-  console.log();
-  if (scan.needsSetup.length === 0 && scan.alreadyConfigured.length === 0) {
-    console.log(`  No coding agents detected. Install an agent and try again.
-`);
+  if (options.installAgents !== undefined) {
+    await runInstallAgentsMode(options, fileSystemService, execService, createLoginDeps, useColors);
     return;
   }
-  if (scan.needsSetup.length === 0) {
-    if (continuedWithoutAuth) {
-      console.log("  MCP is already configured, but authentication is still required.");
-      console.log("  Run `githits login` before using GitHits tools.\n");
+  printInitIntro(useColors);
+  if (!isInteractive) {
+    if (options.yes) {
+      printNonInteractiveYesRejected(useColors);
       return;
     }
-    console.log("  All detected agents are already configured.");
-    printReadyNextSteps();
+    printNonInteractiveInitGuidance(useColors);
     console.log();
     return;
   }
-  const toSetup = scan.needsSetup;
-  const outcomes = [];
-  let alwaysMode = options.yes ?? false;
-  for (const agent of toSetup) {
-    console.log(`  Setting up ${colorize(agent.name, "bold", useColors)}...
-`);
-    const config = agent.resolvedSetupConfig ?? agent.getSetupConfig(fileSystemService);
-    const preview2 = formatSetupPreview(config);
-    for (const line of preview2.split(`
-`)) {
-      console.log(`    ${line}`);
-    }
-    console.log();
-    if (!alwaysMode) {
-      let choice;
-      try {
-        choice = await promptService.confirm3("Proceed?");
-      } catch (err) {
-        if (err instanceof ExitPromptError) {
-          console.log(`
-  Setup cancelled.
+  if (!options.yes) {
+    let intent;
+    try {
+      intent = await promptService.select("  What do you want to do?", INIT_INTENT_CHOICES, "mcp");
+    } catch (err) {
+      if (err instanceof ExitPromptError) {
+        console.log(`
+  Setup cancelled. No changes made.
 `);
-          return;
-        }
-        throw err;
-      }
-      if (choice === "no") {
-        outcomes.push({ id: agent.id, name: agent.name, status: "skipped" });
-        console.log();
-        continue;
-      }
-      if (choice === "always") {
-        alwaysMode = true;
+        return;
       }
+      throw err;
     }
-    let result = config.method === "cli" ? await executeCliSetup(config, execService) : config.method === "config-file" ? await executeConfigFileSetup(config, fileSystemService) : await executeCompositeSetup(config, fileSystemService, execService);
-    if (result.status === "success" || result.status === "already_configured") {
-      const verification = await verifyAgentConfigured(agent, fileSystemService, execService);
-      if (!verification.ok) {
-        result = {
-          status: "failed",
-          message: agent.id === "gemini-cli" ? "Gemini installation did not complete. Retry, or run: gemini extensions install --consent https://github.com/githits-com/githits-cli" : verification.message ?? `${agent.name} verification failed after setup.`
-        };
-      }
+    if (intent === "skills") {
+      printSkillsInstructions(useColors);
+      return;
     }
-    outcomes.push({
-      id: agent.id,
-      name: agent.name,
-      status: result.status,
-      message: result.status === "failed" ? result.message : undefined
-    });
-    if (result.status === "success") {
-      console.log(`    ${success(`${agent.name} configured`, useColors)}
-`);
-    } else if (result.status === "already_configured") {
-      console.log(`    ${warning(`${agent.name} already configured`, useColors)}
-`);
-    } else {
-      console.log(`    ${error(result.message, useColors)}
+    if (intent === "later") {
+      console.log("\n  No changes made. Run `npx githits@latest init` whenever you're ready.\n");
+      return;
+    }
+  }
+  printSection(1, "Detect tools", useColors);
+  console.log("    Scanning for compatible AI coding tools...");
+  const progress = createScanProgressReporter(useColors);
+  const scanPromise = startSafeInitScan(fileSystemService, execService, (scanProgress) => progress.onProgress(scanProgress));
+  let scan;
+  try {
+    scan = await unwrapSafeScan(scanPromise);
+  } finally {
+    progress.finish();
+  }
+  printScanSummary(scan, useColors);
+  if (scan.needsSetup.length === 0 && scan.alreadyConfigured.length === 0) {
+    printTask("warning", "No supported AI coding tools detected", "install a supported tool and run `githits init` again", useColors);
+    console.log();
+    return;
+  }
+  let toSetup = scan.needsSetup;
+  printSection(2, "Choose tools", useColors);
+  if (!options.yes && scan.needsSetup.length > 0) {
+    try {
+      toSetup = await promptService.checkbox("  Select which tools should use GitHits:", buildInitAgentChoices(scan));
+    } catch (err) {
+      if (err instanceof ExitPromptError) {
+        console.log(`
+  Setup cancelled. No changes made.
 `);
+        return;
+      }
+      throw err;
     }
+  } else if (scan.needsSetup.length === 0) {
+    printTask("success", "No tool changes needed", "all detected tools already have GitHits MCP", useColors);
+  } else {
+    printTask("success", "Selected all detected tools", "--yes", useColors);
+  }
+  if (toSetup.length === 0 && scan.needsSetup.length > 0) {
+    printTask("skipped", "Setup skipped", "no tools selected", useColors);
+    console.log();
+    return;
   }
+  printSection(3, "Sign in", useColors);
+  const authStatus = await runInitAuthentication(options, promptService, createLoginDeps, useColors);
+  if (authStatus === "cancelled") {
+    return;
+  }
+  printSection(4, "Install and verify", useColors);
+  if (toSetup.length === 0) {
+    printTask("success", "Nothing to install", "all detected tools are already configured", useColors);
+    printPostSetupNextSteps(authStatus, useColors);
+    console.log();
+    return;
+  }
+  const outcomes = await installSelectedAgents(toSetup, scan, fileSystemService, execService, useColors, true);
+  console.log();
   const configured = outcomes.filter((o) => o.status === "success").length;
   const alreadyDone = outcomes.filter((o) => o.status === "already_configured").length + scan.alreadyConfigured.length;
   const failed = outcomes.filter((o) => o.status === "failed").length;
-  const skipped = outcomes.filter((o) => o.status === "skipped").length;
   if (failed > 0) {
     console.log("  Setup completed with errors.");
-  } else if (continuedWithoutAuth && (configured > 0 || alreadyDone > 0)) {
-    console.log("  MCP is configured, but authentication is still required.");
-    console.log("  Run `githits login` before using GitHits tools.");
   } else if (configured > 0 || alreadyDone > 0) {
-    printReadyNextSteps();
-  } else if (skipped > 0) {
-    console.log("  Setup skipped.");
+    printPostSetupNextSteps(authStatus, useColors);
   }
   if (failed > 0) {
-    console.log(`  ${failed} agent${failed !== 1 ? "s" : ""} failed to configure.`);
+    console.log(`  ${failed} tool${failed !== 1 ? "s" : ""} failed to configure.`);
     for (const outcome of outcomes.filter((o) => o.status === "failed")) {
       console.log(`    - ${outcome.name}: ${outcome.message ?? "Unknown error"}`);
     }
   }
-  if (skipped > 0) {
-    console.log(`  ${skipped} agent${skipped !== 1 ? "s" : ""} skipped.`);
+  if (scan.alreadyConfigured.length > 0) {
+    console.log(`  ${scan.alreadyConfigured.length} tool${scan.alreadyConfigured.length !== 1 ? "s" : ""} already configured.`);
   }
   console.log();
 }
@@ -9931,7 +11079,8 @@ async function initUninstallAction(options, deps) {
   const useColors = shouldUseColors();
   const { fileSystemService, promptService, execService } = deps;
   console.log(`
-  ${colorize("GitHits", "bold", useColors)} — Remove MCP server from your coding agents
+  ${colorize("Disconnect GitHits from your coding agents.", "bold", useColors)}`);
+  console.log(`  ${colorize("Removes the local GitHits MCP configuration.", "dim", useColors)}
 `);
   console.log(`  Scanning for configured agents...
 `);
@@ -10068,33 +11217,27 @@ async function initUninstallAction(options, deps) {
   }
   console.log();
 }
-function printAuthRecoveryHint() {
+function printAuthRecoveryHint(useColors) {
   console.log("    You can still configure MCP, but GitHits tools will require auth.");
   console.log("    Recovery steps:");
-  console.log("      githits auth status");
-  console.log("      githits login --force");
+  console.log(`      ${formatCommand("githits auth status", useColors)}`);
+  console.log(`      ${formatCommand("githits login --force", useColors)}`);
   console.log("    For CI or locked-down machines, set GITHITS_API_TOKEN.");
   console.log(`    If your system keychain is unavailable, set GITHITS_AUTH_STORAGE=file after accepting plaintext storage.
 `);
 }
-var INIT_DESCRIPTION = `Set up GitHits MCP server for your coding agents.
+var INIT_DESCRIPTION = `Connect GitHits to your coding agents.
 
-Authenticates with your GitHits account, then scans for available agents
-(Claude Code, Cursor, Windsurf, VS Code, Cline, Claude Desktop, Codex CLI,
-Pi, Gemini CLI, Google Antigravity), checks which are already configured,
-and sets up unconfigured ones with your confirmation.
-
-Supports CLI-based setup (Claude Code, Codex, Gemini CLI), Pi package setup,
-and config
-file editing (Cursor, Windsurf, VS Code, Cline, Claude Desktop,
-Google Antigravity) with atomic writes.`;
+Installs the local GitHits MCP server — the recommended way to connect — or
+sets up Agent Skills instead. Detects supported coding tools on this machine,
+signs you in, and configures the tools you select.`;
 var INIT_UNINSTALL_DESCRIPTION = `Remove GitHits MCP server configuration from your coding agents.
 
 Scans for available agents that currently have GitHits configured, then removes
 only the GitHits MCP/plugin configuration with your confirmation. Authentication
 tokens are not removed; use \`githits logout\` to remove stored credentials.`;
 function registerInitCommand(program) {
-  const initCommand = program.command("init").summary("Set up MCP server for your coding agents").description(INIT_DESCRIPTION).option("-y, --yes", "Skip prompts, configure all detected agents").option("--skip-login", "Skip authentication step").action(async (options) => {
+  const initCommand = program.command("init").summary("Connect GitHits to your coding agents").description(INIT_DESCRIPTION).option("-y, --yes", "Skip prompts, configure all detected tools").option("--skip-login", "Skip authentication step").option("--detect-agents", "Scan supported agents without installing").option("--install-agents <ids>", "Install MCP server for comma-separated agent IDs from --detect-agents").option("--json", "Emit JSON for --detect-agents or --install-agents").action(async (options) => {
     const fileSystemService = new FileSystemServiceImpl;
     const promptService = new PromptServiceImpl;
     const execService = new ExecServiceImpl;
@@ -10102,7 +11245,8 @@ function registerInitCommand(program) {
       fileSystemService,
       promptService,
       execService,
-      createLoginDeps: () => createContainer()
+      createLoginDeps: () => createContainer(),
+      isInteractive: process.stdin.isTTY === true && process.stdout.isTTY === true
     });
   });
   initCommand.command("uninstall").summary("Remove MCP server from your coding agents").description(INIT_UNINSTALL_DESCRIPTION).option("-y, --yes", "Skip prompts, uninstall from all configured agents").action(async (options) => {
@@ -10165,17 +11309,10 @@ function registerLanguagesCommand(program) {
 // src/commands/logout.ts
 async function logoutAction(deps) {
   const { authStorage, mcpUrl } = deps;
-  const auth = await authStorage.loadTokens(mcpUrl);
   await authStorage.clearAuthSession(mcpUrl);
-  if (!auth) {
-    console.log(`Not currently logged in.
+  console.log(`Logged out.
 `);
-    console.log(`  Environment: ${mcpUrl}`);
-  } else {
-    console.log(`Logged out.
-`);
-    console.log(`  Environment: ${mcpUrl}`);
-  }
+  console.log(`  Environment: ${mcpUrl}`);
 }
 var LOGOUT_DESCRIPTION = `Remove stored credentials.
 
@@ -11807,7 +12944,7 @@ function showMcpSetupInstructions() {
   console.log("Learn more at https://githits.com");
 }
 function registerMcpCommand(program) {
-  const mcpCommand = program.command("mcp").summary("Show setup instructions or start MCP server").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
+  const mcpCommand = program.command("mcp").summary("Show MCP setup instructions or start the local MCP server").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
 
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
@@ -12379,7 +13516,7 @@ async function registerPkgCommandGroup(program, options = {}) {
   if (!registration.shouldRegister) {
     return;
   }
-  const pkgCommand = program.command("pkg").summary("Package metadata: info, vulnerabilities, dependencies, changelog, upgrade reviews").description("Inspect package metadata from npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, vcpkg, and Zig: overviews, advisories, dependency graphs, and changelogs. Advisory data is unavailable for vcpkg and Zig. For source-level operations inside a dependency, use `githits code`.");
+  const pkgCommand = program.command("pkg").summary("Package metadata, dependencies, vulnerabilities and changelogs").description("Inspect package metadata from npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, vcpkg, and Zig: overviews, advisories, dependency graphs, and changelogs. Advisory data is unavailable for vcpkg and Zig. For source-level operations inside a dependency, use `githits code`.");
   registerPkgInfoCommand(pkgCommand);
   registerPkgVulnsCommand(pkgCommand);
   registerPkgDepsCommand(pkgCommand);
@@ -12408,7 +13545,8 @@ async function searchAction(query, options, deps) {
       offset: parseOptionalInt(options.offset, "--offset", 0),
       waitTimeoutMs: parseWaitMs(options.wait)
     });
-    const outcome = await service.search(built.params);
+    const spinner = startSpinner(SPINNER_MESSAGES.search, !options.json);
+    const outcome = await service.search(built.params).finally(() => spinner.stop());
     const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
     if (options.json) {
       console.log(JSON.stringify(payload));
@@ -12470,7 +13608,7 @@ Pass the searchRef returned by githits search when the initial request could
 not complete within the wait window. This can return progress, partial hits when
 the original request used --allow-partial, or final results.`;
 function registerSearchCommand(program) {
-  program.command("search").summary("Search indexed dependency and repository code, docs, and symbols").description(SEARCH_DESCRIPTION).argument("<query>", "Search query").requiredOption("--in <target>", "Search target: registry:name[@version] or https://github.com/org/repo[#ref]", collectRepeatable3, []).addOption(new Option3("--source <source>", "Source to search (repeatable; default: auto)").choices(["docs", "code", "symbol"]).argParser((value, previous = []) => collectRepeatable3(value.toLowerCase(), previous)).default(undefined)).addOption(new Option3("--kind <kind>", "Precise symbol kind filter").choices([
+  program.command("search").summary("Explore repository code, dependencies, docs and symbols").description(SEARCH_DESCRIPTION).argument("<query>", "Search query").requiredOption("--in <target>", "Search target: registry:name[@version] or https://github.com/org/repo[#ref]", collectRepeatable3, []).addOption(new Option3("--source <source>", "Source to search (repeatable; default: auto)").choices(["docs", "code", "symbol"]).argParser((value, previous = []) => collectRepeatable3(value.toLowerCase(), previous)).default(undefined)).addOption(new Option3("--kind <kind>", "Precise symbol kind filter").choices([
     ...knownSymbolKindList()
   ])).addOption(new Option3("--category <category>", "Broad symbol category filter").choices([...knownSymbolCategoryList()])).option("--path-prefix <prefix>", "Repository path prefix filter").addOption(new Option3("--intent <intent>", "File intent filter (omit to search across all intents)").choices([
     "production",
@@ -12485,7 +13623,7 @@ function registerSearchCommand(program) {
     const deps = await loadContainer2();
     await searchAction(query, options, deps);
   });
-  program.command("search-status").summary("Check status of a prior search").description(SEARCH_STATUS_DESCRIPTION).argument("<search-ref>", "Search reference returned by githits search").option("--json", "Output as JSON").action(async (searchRef, options) => {
+  program.command("search-status").summary("Check the status of a previous search").description(SEARCH_STATUS_DESCRIPTION).argument("<search-ref>", "Search reference returned by githits search").option("--json", "Output as JSON").action(async (searchRef, options) => {
     const deps = await loadContainer2();
     await searchStatusAction(searchRef, options, deps);
   });
@@ -12504,7 +13642,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-2fdxv7pe.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-681avsyw.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {
@@ -12969,6 +14107,10 @@ function formatUnifiedSearchMetadata(entry, _useColors) {
 // src/cli.ts
 var program = new Command;
 var argv = process.argv.slice(2);
+if (argv.includes("--no-color")) {
+  process.env.NO_COLOR = "1";
+}
+var useColors = shouldUseColors();
 var commandSpans = new WeakMap;
 var createUpdateCheckService = () => new NpmRegistryUpdateCheckService({
   currentVersion: version,
@@ -13005,21 +14147,23 @@ var rootCliPreAction = createRootCliPreAction({
   clearAuthSessionMetadata: clearAutoLoginAuthSessionMetadata,
   loginFlow: (options, deps) => loginFlow(options, deps, stderrLoginOutput)
 });
-program.name("githits").description("Code examples from global open source for your AI assistant").version(version).option("--no-color", "Disable colored output").hook("preAction", async (thisCommand, actionCommand) => {
+program.name("githits").description("Grounded open-source context for AI coding agents").version(version).option("--no-color", "Disable colored output").configureHelp({
+  styleTitle: (title) => colorizeBrand(title, "primary", useColors, { bold: true })
+}).hook("preAction", async (thisCommand, actionCommand) => {
   const command = actionCommand ?? thisCommand;
   commandSpans.set(command, startTelemetrySpan(getTelemetryCommandName(command)));
   await rootCliPreAction(thisCommand, actionCommand);
 }).hook("postAction", (_thisCommand, actionCommand) => {
   endTelemetrySpan(commandSpans.get(actionCommand));
 }).addHelpText("after", `
-Getting started:
-  githits init                         Set up MCP for your coding agents
-  githits login                        Authenticate with your GitHits account
+${colorizeBrand("Getting started:", "primary", useColors, { bold: true })}
+  githits init                         Connect GitHits to your coding agents
+  githits login                        Sign in to your GitHits account
   githits mcp                          Show MCP setup instructions
-  githits example "query"              Get code examples
+  githits example "query"              Find real-world implementations
 
 Learn more at https://githits.com
-Docs: https://app.githits.com/docs/
+Docs: https://docs.githits.com
 Support: support@githits.com`);
 registerInitCommand(program);
 registerLoginCommand(program);