githits 0.4.5 → 0.4.7

package/dist/cli.js

@@ -51,11 +51,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-ygqss6gp.js";
+} from "./shared/chunk-tm11qwgr.js";
 import {
   __require,
   version
-} from "./shared/chunk-vfyz65v1.js";
+} from "./shared/chunk-7b4f7fd5.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}`;
@@ -583,6 +624,12 @@ function classify(error2) {
     if (error2.availableVersions && error2.availableVersions.length > 0) {
       details.availableVersions = error2.availableVersions;
     }
+    if (error2.availableRefs && error2.availableRefs.length > 0) {
+      details.availableRefs = error2.availableRefs;
+    }
+    if (error2.targetResolution) {
+      details.targetResolution = error2.targetResolution;
+    }
     return {
       code: "INDEXING",
       message: error2.message,
@@ -788,7 +835,7 @@ function parseCodeNavigationTargetSpec(spec) {
 function parseRepoTarget(spec) {
   const hashIndex = spec.lastIndexOf("#");
   if (hashIndex === -1) {
-    throw new InvalidArgumentError("Repository target must include #gitRef for code_files/code_read/code_grep.");
+    return { repoUrl: spec };
   }
   const repoUrl = spec.slice(0, hashIndex);
   const gitRef = spec.slice(hashIndex + 1);
@@ -827,6 +874,7 @@ function buildSearchHitFollowUpCommand(hit) {
       version: loc.version,
       repoUrl: loc.repoUrl,
       gitRef: loc.gitRef,
+      requestedRef: loc.requestedRef,
       filePath: loc.filePath,
       startLine: loc.startLine,
       endLine: loc.endLine,
@@ -863,9 +911,8 @@ function buildTargetSpec(input) {
     return `${input.registry}:${input.packageName}${input.version ? `@${input.version}` : ""}`;
   }
   if (input.repoUrl) {
-    if (!input.gitRef)
-      return;
-    return `${input.repoUrl}#${input.gitRef}`;
+    const ref = input.gitRef ?? input.requestedRef;
+    return ref ? `${input.repoUrl}#${ref}` : input.repoUrl;
   }
   if (input.registry && input.packageName) {
     return `${input.registry}:${input.packageName}${input.version ? `@${input.version}` : ""}`;
@@ -1061,6 +1108,161 @@ function shellQuote(value) {
   return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 
+// src/shared/target-resolution.ts
+function projectTargetResolution(resolution) {
+  if (!resolution)
+    return;
+  return {
+    ...resolution.requested ? { requested: projectIdentity(resolution.requested) } : {},
+    ...resolution.resolvedRequested ? { resolvedRequested: projectIdentity(resolution.resolvedRequested) } : {},
+    ...resolution.served ? { served: projectIdentity(resolution.served) } : {},
+    ...resolution.freshness ? { freshness: resolution.freshness } : {},
+    ...resolution.freshnessReason ? { freshnessReason: resolution.freshnessReason } : {},
+    ...resolution.indexingRef ? { indexingRef: resolution.indexingRef } : {},
+    availableVersions: resolution.availableVersions.map(projectArtifact),
+    availableRefs: resolution.availableRefs.map(projectArtifact)
+  };
+}
+function buildTargetResolutionNotes(resolution) {
+  if (!resolution)
+    return [];
+  const lines = [];
+  const requested = formatIdentity(resolution.requested);
+  const fresh = formatIdentity(resolution.resolvedRequested);
+  const served = formatIdentity(resolution.served);
+  const reason = resolution.freshnessReason ? ` (${resolution.freshnessReason})` : "";
+  switch (resolution.freshness) {
+    case "fallback_recent": {
+      const parts = ["using recent index"];
+      if (served)
+        parts.push(`served=${served}`);
+      if (fresh && identitiesMateriallyDiffer(fresh, served)) {
+        parts.push(`fresh=${fresh}`);
+      }
+      lines.push(`${parts.join(" | ")}${reason}`);
+      break;
+    }
+    case "indexing": {
+      const parts = ["indexing fresh target"];
+      if (requested)
+        parts.push(`requested=${requested}`);
+      if (fresh)
+        parts.push(`fresh=${fresh}`);
+      if (resolution.indexingRef)
+        parts.push(`indexingRef=${resolution.indexingRef}`);
+      lines.push(`${parts.join(" | ")}${reason}`);
+      break;
+    }
+    case "unavailable": {
+      const parts = ["target unavailable"];
+      if (requested)
+        parts.push(`requested=${requested}`);
+      lines.push(`${parts.join(" | ")}${reason}`);
+      break;
+    }
+    case "current": {
+      break;
+    }
+    default: {
+      if (resolution.freshness || identitiesDiffer(requested, fresh, served)) {
+        const parts = [
+          `target resolution: ${resolution.freshness ?? "unknown"}`
+        ];
+        if (served)
+          parts.push(`served=${served}`);
+        if (requested)
+          parts.push(`requested=${requested}`);
+        if (fresh && fresh !== served)
+          parts.push(`fresh=${fresh}`);
+        lines.push(`${parts.join(" | ")}${reason}`);
+      }
+      break;
+    }
+  }
+  const candidates = buildRetryCandidateLine(resolution);
+  if (candidates)
+    lines.push(candidates);
+  return lines;
+}
+function buildRetryCandidateLine(resolution) {
+  if (!resolution)
+    return;
+  const parts = [];
+  if (resolution.availableVersions.length > 0) {
+    parts.push(`versions=${resolution.availableVersions.map(formatArtifact).join(",")}`);
+  }
+  if (resolution.availableRefs.length > 0) {
+    parts.push(`refs=${resolution.availableRefs.map(formatArtifact).join(",")}`);
+  }
+  return parts.length > 0 ? `queryable now: ${parts.join(" | ")}` : undefined;
+}
+function buildResolutionFromRetryCandidates(target) {
+  if (!target.availableVersions?.length && !target.availableRefs?.length) {
+    return;
+  }
+  return {
+    freshness: target.freshness,
+    indexingRef: target.indexingRef,
+    availableVersions: target.availableVersions ?? [],
+    availableRefs: target.availableRefs ?? []
+  };
+}
+function projectIdentity(identity) {
+  const out = {};
+  if (identity.kind)
+    out.kind = identity.kind;
+  if (identity.registry)
+    out.registry = identity.registry;
+  if (identity.packageName)
+    out.packageName = identity.packageName;
+  if (identity.version)
+    out.version = identity.version;
+  if (identity.repoUrl)
+    out.repoUrl = identity.repoUrl;
+  if (identity.gitRef)
+    out.gitRef = identity.gitRef;
+  if (identity.commitSha)
+    out.commitSha = identity.commitSha;
+  return out;
+}
+function projectArtifact(artifact) {
+  return artifact.version ? { version: artifact.version, ref: artifact.ref } : { ref: artifact.ref };
+}
+function formatIdentity(identity) {
+  if (!identity)
+    return;
+  if (identity.registry && identity.packageName) {
+    const version2 = identity.version ? `@${identity.version}` : "";
+    const commit = identity.commitSha ? `#${shortSha(identity.commitSha)}` : "";
+    return `${identity.registry.toLowerCase()}:${identity.packageName}${version2}${commit}`;
+  }
+  if (identity.repoUrl) {
+    const ref = identity.gitRef ? `#${identity.gitRef}` : "";
+    const commit = identity.commitSha ? `@${shortSha(identity.commitSha)}` : "";
+    return `${identity.repoUrl}${ref}${commit}`;
+  }
+  return identity.gitRef ?? identity.version ?? identity.commitSha ?? identity.kind;
+}
+function formatArtifact(artifact) {
+  return artifact.version ? `${artifact.version}@${artifact.ref}` : artifact.ref;
+}
+function identitiesDiffer(requested, fresh, served) {
+  if (!served)
+    return Boolean(requested || fresh);
+  return Boolean(requested && requested !== served || fresh && fresh !== served);
+}
+function identitiesMateriallyDiffer(left, right) {
+  if (!left || !right)
+    return Boolean(left || right);
+  return stripShortCommit(left) !== stripShortCommit(right);
+}
+function stripShortCommit(value) {
+  return value.replace(/[@#][0-9a-f]{7}$/i, "");
+}
+function shortSha(value) {
+  return /^[0-9a-f]{12,}$/i.test(value) ? value.slice(0, 7) : value;
+}
+
 // src/shared/grep-repo-response.ts
 var UTF8_ENCODER = new TextEncoder;
 function buildGrepRepoSuccessPayload(result, options) {
@@ -1102,6 +1304,9 @@ function buildGrepRepoSuccessPayload(result, options) {
   if (result.resolution) {
     envelope.resolution = projectResolution(result.resolution);
   }
+  const targetResolution = projectTargetResolution(result.targetResolution);
+  if (targetResolution)
+    envelope.targetResolution = targetResolution;
   const filter = buildFilterBlock(options);
   if (filter)
     envelope.filter = filter;
@@ -1189,8 +1394,11 @@ function buildFilterBlock(options) {
   return Object.keys(filter).length > 0 ? filter : undefined;
 }
 function formatGrepRepoTerminal(envelope, options) {
-  if (envelope.matches.length === 0) {
-    return { stdout: "" };
+  if (envelope.matches.length === 0 && !options.verbose) {
+    return {
+      stdout: "",
+      stderr: formatTerminalNotes(envelope, options.useColors)
+    };
   }
   const blocks = buildRenderBlocks(envelope.matches);
   return options.verbose ? formatVerbose(envelope, blocks, options) : formatPlain(envelope, blocks, options);
@@ -1247,6 +1455,10 @@ function formatVerbose(envelope, blocks, options) {
   }
   lines.push("");
   const blocksByFile = groupBlocksByFile(blocks);
+  if (blocksByFile.size === 0) {
+    lines.push("No matches.");
+    lines.push("");
+  }
   for (const [filePath, fileBlocks] of blocksByFile) {
     lines.push(colorize(filePath, "bold", options.useColors));
     const gutterWidth = widestLineNumberInBlocks(fileBlocks);
@@ -1418,6 +1630,9 @@ function formatTerminalNotes(envelope, useColors) {
   if (envelope.hasMore && envelope.nextCursor) {
     lines.push(dim(`More grep results available — rerun with --cursor ${shellQuote(envelope.nextCursor)}`, useColors));
   }
+  for (const note of buildTargetResolutionNotes(envelope.targetResolution)) {
+    lines.push(dim(note, useColors));
+  }
   if (lines.length === 0)
     return;
   return `${lines.join(`
@@ -1548,6 +1763,9 @@ function buildTrailer(envelope) {
   if (skipNotes.length > 0) {
     lines.push(`Note: ${skipNotes.join(", ")}.`);
   }
+  for (const note of buildTargetResolutionNotes(envelope.targetResolution)) {
+    lines.push(note);
+  }
   return lines;
 }
 function buildRenderBlocks2(matches) {
@@ -1668,6 +1886,7 @@ function renderListFilesText(envelope) {
   lines.push("");
   if (envelope.files.length === 0) {
     lines.push(envelope.hint ?? "No files match the requested filter.");
+    appendTargetResolutionNotes(lines, envelope);
     return lines.join(`
 `);
   }
@@ -1682,9 +1901,18 @@ function renderListFilesText(envelope) {
     lines.push("");
     lines.push(envelope.hint);
   }
+  appendTargetResolutionNotes(lines, envelope);
   return lines.join(`
 `);
 }
+function appendTargetResolutionNotes(lines, envelope) {
+  const notes = buildTargetResolutionNotes(envelope.targetResolution);
+  if (notes.length === 0)
+    return;
+  lines.push("");
+  for (const note of notes)
+    lines.push(note);
+}
 function buildHeader2(envelope) {
   const identity = buildIdentity(envelope);
   const countValue = envelope.hasMore ? `${envelope.files.length}+` : String(envelope.total);
@@ -2203,7 +2431,7 @@ function buildDirectVersionLookup(graph) {
     if (!fromRoot)
       continue;
     const node = graph.nodes[edge.toIndex];
-    if (!node || !node.version)
+    if (!node?.version)
       continue;
     if (!out.has(node.name)) {
       out.set(node.name, node.version);
@@ -5176,6 +5404,9 @@ function buildReadFileSuccessPayload(result, options) {
   } else if (result.content != null) {
     envelope.content = result.content;
   }
+  const targetResolution = projectTargetResolution(result.targetResolution);
+  if (targetResolution)
+    envelope.targetResolution = targetResolution;
   return envelope;
 }
 function formatReadFileTerminal(envelope, options) {
@@ -5230,10 +5461,19 @@ function formatVerboseBody(envelope, options) {
     lines.push("");
     lines.push(dim(envelope.hint, options.useColors));
   }
+  appendTargetResolutionNotes2(lines, envelope, options);
   lines.push("");
   return lines.join(`
 `);
 }
+function appendTargetResolutionNotes2(lines, envelope, options) {
+  const notes = buildTargetResolutionNotes(envelope.targetResolution);
+  if (notes.length === 0)
+    return;
+  lines.push("");
+  for (const note of notes)
+    lines.push(dim(note, options.useColors));
+}
 function splitReadFileContentLines(envelope) {
   if (!envelope.content)
     return [];
@@ -5295,6 +5535,12 @@ function renderReadFileText(envelope) {
     lines.push("");
     lines.push(`hint: ${envelope.hint}`);
   }
+  const resolutionNotes = buildTargetResolutionNotes(envelope.targetResolution);
+  if (resolutionNotes.length > 0) {
+    lines.push("");
+    for (const note of resolutionNotes)
+      lines.push(note);
+  }
   return lines.join(`
 `);
 }
@@ -5758,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);
   });
@@ -5900,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) {
@@ -6316,6 +6617,15 @@ function compactProgressTarget(target) {
     payload.indexingRef = target.indexingRef;
   if (target.requestedRefKind)
     payload.requestedRefKind = target.requestedRefKind;
+  const targetResolution = projectTargetResolution(target.targetResolution);
+  if (targetResolution)
+    payload.targetResolution = targetResolution;
+  if (target.availableVersions?.length) {
+    payload.availableVersions = target.availableVersions;
+  }
+  if (target.availableRefs?.length) {
+    payload.availableRefs = target.availableRefs;
+  }
   return Object.keys(payload).length > 0 ? payload : undefined;
 }
 function buildFilterEcho3(filters) {
@@ -6358,7 +6668,11 @@ function buildProgressFreshnessWarnings(progress) {
     requestedTarget: target.requested,
     freshTarget: target.resolvedRequested,
     servedTarget: target.served
-  })).filter((entry) => Boolean(entry));
+  })).concat((progress?.targets ?? []).map((target) => progressTargetResolutionWarning(target)).filter((entry) => Boolean(entry))).filter((entry) => Boolean(entry));
+}
+function progressTargetResolutionWarning(target) {
+  const notes = buildTargetResolutionNotes(target.targetResolution ?? buildResolutionFromRetryCandidates(target));
+  return notes.length > 0 ? notes.join(" ") : undefined;
 }
 function freshnessWarning(input) {
   if (!isTrustRelevantFreshness(input.freshness))
@@ -6377,7 +6691,30 @@ function labelsDiverge(input) {
   const served = input.servedTarget;
   if (!served)
     return false;
-  return Boolean(input.freshTarget && input.freshTarget !== served || input.requestedTarget && input.requestedTarget !== 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 = [];
@@ -6389,6 +6726,14 @@ function warningForEntry(entry) {
   });
   if (freshness)
     return freshness;
+  const terminalLifecycleReason = terminalLifecycleWarningReason(entry);
+  if (terminalLifecycleReason) {
+    reasons.push(terminalLifecycleReason);
+  } else {
+    const targetResolutionWarning = targetResolutionWarningForEntry(entry);
+    if (targetResolutionWarning)
+      reasons.push(targetResolutionWarning);
+  }
   if (entry.incompatibleQueryFeatures?.length) {
     reasons.push(`incompatible query features [${entry.incompatibleQueryFeatures.join(", ")}]`);
   }
@@ -6401,10 +6746,10 @@ function warningForEntry(entry) {
   if (entry.ignoredFilters?.length) {
     reasons.push(`ignored filters [${entry.ignoredFilters.join(", ")}]`);
   }
-  if (entry.indexingStatus) {
+  if (!terminalLifecycleReason && reasons.length === 0 && entry.indexingStatus) {
     reasons.push(`indexing status ${entry.indexingStatus}`);
   }
-  if (entry.codeIndexState) {
+  if (!terminalLifecycleReason && reasons.length === 0 && entry.codeIndexState) {
     if (entry.codeIndexState !== "STALE") {
       reasons.push(`code index state ${entry.codeIndexState}`);
     }
@@ -6418,6 +6763,18 @@ function warningForEntry(entry) {
   }
   return;
 }
+function terminalLifecycleWarningReason(entry) {
+  const states = Array.from(new Set([entry.indexingStatus, entry.codeIndexState].filter(Boolean)));
+  const terminalStates = states.filter((state) => state !== "INDEXING" && state !== "STALE");
+  if (terminalStates.length === 0)
+    return;
+  const status = terminalStates.join("/");
+  return entry.note ? `${entry.note} (${status})` : `status ${status}`;
+}
+function targetResolutionWarningForEntry(entry) {
+  const notes = buildTargetResolutionNotes(entry.targetResolution);
+  return notes.length > 0 ? notes.join(" ") : undefined;
+}
 function compactSourceStatus(sourceStatus) {
   if (!sourceStatus || sourceStatus.length === 0)
     return;
@@ -6447,6 +6804,13 @@ function compactSourceStatusEntry(entry) {
     payload.codeIndexState = entry.codeIndexState;
     interesting = true;
   }
+  const targetResolution = projectTargetResolution(entry.targetResolution);
+  if (targetResolution) {
+    payload.targetResolution = targetResolution;
+    if (buildTargetResolutionNotes(targetResolution).length > 0) {
+      interesting = true;
+    }
+  }
   if (entry.indexingStatus && entry.indexingStatus !== "INDEXED") {
     payload.indexingStatus = entry.indexingStatus;
     interesting = true;
@@ -6484,7 +6848,7 @@ function assertSearchFollowUpInvariant(hit) {
   if ((hit.resultType === "DOCUMENTATION_PAGE" || hit.resultType === "REPOSITORY_DOC") && !hit.locator.pageId) {
     throw new MalformedCodeNavigationResponseError(`${hit.resultType} search hit missing required pageId.`);
   }
-  if (hit.resultType === "REPOSITORY_DOC" && (!hit.locator.repoUrl || !hit.locator.gitRef || !hit.locator.filePath)) {
+  if (hit.resultType === "REPOSITORY_DOC" && (!hit.locator.repoUrl || !hit.locator.filePath)) {
     throw new MalformedCodeNavigationResponseError("REPOSITORY_DOC search hit missing repo locator fields.");
   }
 }
@@ -6496,7 +6860,7 @@ function renderUnifiedSearchSuccess(payload) {
   lines.push(buildHeader8(payload));
   lines.push("");
   if (payload.results.length === 0) {
-    lines.push(payload.completed ? "No hits." : "No hits yet - indexing.");
+    lines.push(payload.completed ? "No hits." : noHitsYetMessage(payload));
   } else {
     appendUnifiedSearchHits(lines, payload.results);
   }
@@ -6509,6 +6873,18 @@ function renderUnifiedSearchSuccess(payload) {
   return lines.join(`
 `);
 }
+function noHitsYetMessage(payload) {
+  if (payload.completed)
+    return "No hits.";
+  const status = payload.progress?.status;
+  if (status === "TIMEOUT")
+    return "No hits yet - timed out waiting.";
+  if (status === "FAILED")
+    return "No hits - search failed.";
+  if (status === "SEARCHING")
+    return "No hits yet - searching.";
+  return "No hits yet - indexing.";
+}
 function renderUnifiedSearchError(payload) {
   const lines = [];
   const header = `search${SEP6}ERROR${SEP6}code=${payload.code}${payload.retryable ? `${SEP6}retryable` : ""}`;
@@ -6638,7 +7014,9 @@ function buildTrailer2(payload) {
     lines.push(`More hits available.${nextOffsetHint}`);
   }
   if (!payload.completed && payload.searchRef) {
-    lines.push(`Indexing in progress. Call search_status with searchRef=${payload.searchRef} to follow up.`);
+    const status = payload.progress?.status;
+    const action = status === "TIMEOUT" ? "Search timed out waiting for fresh data." : status === "FAILED" ? "Search failed before completion." : status === "SEARCHING" ? "Search in progress." : "Indexing in progress.";
+    lines.push(`${action} Call search_status with searchRef=${payload.searchRef} to follow up.`);
   }
   if (payload.sourceStatus && payload.sourceStatus.length > 0) {
     lines.push("source notes:");
@@ -6669,6 +7047,9 @@ function formatProgressTarget(target) {
     parts.push(`intent=${target.requestedRefKind}`);
   if (target.indexingRef)
     parts.push(`indexingRef=${target.indexingRef}`);
+  for (const note of buildTargetResolutionNotes(target.targetResolution ?? buildResolutionFromRetryCandidates(target))) {
+    parts.push(note);
+  }
   return parts.length > 0 ? parts.join(SEP6) : "target progress unavailable";
 }
 function describeFreshness(value) {
@@ -6686,6 +7067,10 @@ function describeFreshness(value) {
   }
 }
 function formatSourceStatus(entry) {
+  const terminalReason = terminalLifecycleReason(entry);
+  if (terminalReason) {
+    return `${entry.source} (${entry.targetLabel})${SEP6}${terminalReason}`;
+  }
   const parts = [`${entry.source} (${entry.targetLabel})`];
   if (entry.indexingStatus)
     parts.push(`indexing=${entry.indexingStatus}`);
@@ -6705,8 +7090,19 @@ function formatSourceStatus(entry) {
   }
   if (entry.note)
     parts.push(entry.note);
+  for (const note of buildTargetResolutionNotes(entry.targetResolution)) {
+    parts.push(note);
+  }
   return parts.join(SEP6);
 }
+function terminalLifecycleReason(entry) {
+  const states = Array.from(new Set([entry.indexingStatus, entry.codeIndexState].filter(Boolean)));
+  const terminalStates = states.filter((state) => state !== "INDEXING" && state !== "STALE");
+  if (terminalStates.length === 0)
+    return;
+  const status = terminalStates.join("/");
+  return entry.note ? `${entry.note} (${status})` : `status ${status}`;
+}
 function quote4(value) {
   return value.includes('"') ? `'${value}'` : `"${value}"`;
 }
@@ -6769,7 +7165,7 @@ function renderUnifiedSearchStatusText(payload) {
 `);
 }
 function buildHeader9(payload) {
-  const state = payload.completed ? "complete" : "indexing";
+  const state = payload.completed ? "complete" : payload.progress?.status.toLowerCase() ?? "incomplete";
   const parts = [`search_status${SEP7}${state}`];
   if (payload.searchRef)
     parts.push(`searchRef=${payload.searchRef}`);
@@ -6797,32 +7193,10 @@ function appendResult(lines, result) {
     lines.push("");
     lines.push("source notes:");
     for (const entry of result.sourceStatus) {
-      lines.push(`  - ${formatSourceStatus2(entry)}`);
+      lines.push(`  - ${formatSourceStatus(entry)}`);
     }
   }
 }
-function formatSourceStatus2(entry) {
-  const parts = [`${entry.source} (${entry.targetLabel})`];
-  if (entry.indexingStatus)
-    parts.push(`indexing=${entry.indexingStatus}`);
-  if (entry.codeIndexState)
-    parts.push(`codeIndex=${entry.codeIndexState}`);
-  if (entry.ignoredFilters?.length) {
-    parts.push(`ignored=${entry.ignoredFilters.join(",")}`);
-  }
-  if (entry.incompatibleFilters?.length) {
-    parts.push(`incompatible=${entry.incompatibleFilters.join(",")}`);
-  }
-  if (entry.ignoredQueryFeatures?.length) {
-    parts.push(`ignoredQuery=${entry.ignoredQueryFeatures.join(",")}`);
-  }
-  if (entry.incompatibleQueryFeatures?.length) {
-    parts.push(`incompatibleQuery=${entry.incompatibleQueryFeatures.join(",")}`);
-  }
-  if (entry.note)
-    parts.push(entry.note);
-  return parts.join(SEP7);
-}
 function formatProgress(progress) {
   const next = progress.next ? `; next: ${progress.next}` : "";
   return `progress: ${progress.status}, ${progress.targetsReady}/${progress.targetsTotal} targets ready, ${progress.elapsedMs}ms elapsed${next}`;
@@ -7042,6 +7416,9 @@ function buildListFilesSuccessPayload(result, options) {
     envelope.indexedVersion = result.indexedVersion;
   if (result.resolution)
     envelope.resolution = projectResolution2(result.resolution);
+  const targetResolution = projectTargetResolution(result.targetResolution);
+  if (targetResolution)
+    envelope.targetResolution = targetResolution;
   if (result.hint)
     envelope.hint = result.hint;
   const filter = buildFilterBlock2(options);
@@ -7152,6 +7529,7 @@ function formatVerbose2(envelope, options) {
   if (envelope.resolution || envelope.indexedVersion) {
     lines.push(buildResolutionLine(envelope, options));
   }
+  appendTargetResolutionNotes3(lines, envelope, options);
   lines.push("");
   const pathWidth = longestPathLength(envelope.files);
   for (const file of envelope.files) {
@@ -7180,6 +7558,7 @@ function formatEmpty(envelope, options, verbose) {
   if (envelope.resolution || envelope.indexedVersion) {
     lines.push(buildResolutionLine(envelope, options));
   }
+  appendTargetResolutionNotes3(lines, envelope, options);
   lines.push("");
   lines.push(dim(hint, options.useColors));
   lines.push("");
@@ -7202,6 +7581,11 @@ function buildResolutionLine(envelope, options) {
     parts.push(`commit ${commit.slice(0, 7)}`);
   return dim(parts.join(" · "), options.useColors);
 }
+function appendTargetResolutionNotes3(lines, envelope, options) {
+  const notes = buildTargetResolutionNotes(envelope.targetResolution);
+  for (const note of notes)
+    lines.push(dim(note, options.useColors));
+}
 function buildIdentityLabel(envelope) {
   if (envelope.registry && envelope.name) {
     return `${envelope.name} · ${envelope.registry}`;
@@ -7251,13 +7635,10 @@ function resolveCliCodeNavTarget(spec, options) {
   const hasRepoUrl = Boolean(options.repoUrl);
   const hasGitRef = Boolean(options.gitRef);
   if (hasSpec && (hasRepoUrl || hasGitRef)) {
-    throw new InvalidPackageSpecError("Provide either a package spec (e.g. `npm:express`) or `--repo-url` + `--git-ref`, not both.");
+    throw new InvalidPackageSpecError("Provide either a package spec (e.g. `npm:express`) or `--repo-url` with optional `--git-ref`, not both.");
   }
   if (!hasSpec && !hasRepoUrl) {
-    throw new InvalidPackageSpecError("A package spec (e.g. `npm:express`) or `--repo-url` + `--git-ref` is required.");
-  }
-  if (hasRepoUrl && !hasGitRef) {
-    throw new InvalidPackageSpecError("`--repo-url` requires `--git-ref` for code files/read/grep (a tag, branch, commit, or `HEAD`).");
+    throw new InvalidPackageSpecError("A package spec (e.g. `npm:express`) or `--repo-url` is required.");
   }
   if (hasSpec) {
     const parsed = parsePackageSpec(spec);
@@ -7301,6 +7682,13 @@ function formatIndexingError(mapped) {
     const suffix = more > 0 ? ` (+${more} more)` : "";
     lines.push(`  already-indexed versions: ${shown}${suffix}`);
   }
+  const refs = detail.availableRefs;
+  if (refs && refs.length > 0) {
+    const shown = refs.slice(0, 5).map((entry) => entry.ref).join(", ");
+    const more = refs.length - 5;
+    const suffix = more > 0 ? ` (+${more} more)` : "";
+    lines.push(`  already-indexed refs: ${shown}${suffix}`);
+  }
   return lines.join(`
 `);
 }
@@ -7381,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,
@@ -7439,7 +7828,7 @@ function resolvePositionals(firstArg, secondArg, hasRepoUrl) {
       throw new InvalidPackageSpecError("In --repo-url mode, pass only [path-prefix] — the package spec is replaced by --repo-url.");
     }
     if (firstArg && REGISTRY_SPEC_HINT.test(firstArg)) {
-      throw new InvalidPackageSpecError(`'${firstArg}' looks like a package spec. Provide either a package spec or \`--repo-url\` + \`--git-ref\`, not both.`);
+      throw new InvalidPackageSpecError(`'${firstArg}' looks like a package spec. Provide either a package spec or \`--repo-url\` with optional \`--git-ref\`, not both.`);
     }
     return { spec: undefined, pathPrefix: firstArg };
   }
@@ -7467,7 +7856,7 @@ On an INDEXING response, the dependency is being indexed on-demand
 — retry with a longer --wait (up to 60000 ms) or pick one of the
 already-indexed versions surfaced in the error detail.`;
 function registerCodeFilesCommand(pkgCommand) {
-  return pkgCommand.command("files").summary("List files in an indexed dependency").description(PKG_FILES_DESCRIPTION).argument("[spec-or-prefix]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the path-prefix.").argument("[path-prefix]", "Spec mode only: literal directory prefix (not a glob). Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--path <path>", "Exact file selector").option("--glob <glob>", "Glob selector (repeatable)", collectRepeatable).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable).option("--file-type <type>", "File type filter such as source or doc (repeatable)", collectRepeatable).option("--language <language>", "Language filter matching aigrep language names (repeatable)", collectRepeatable).option("--file-intent <intent>", "Inclusive file-intent filter. Repeat to include multiple intents: production, test, benchmark, example, generated, fixture, build, vendor", collectRepeatable).option("--exclude-intent <intent>", "Exclude these file intents after inclusive filtering (repeatable)", collectRepeatable).option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--hidden", "Include dotfiles and dot-prefixed paths").option("--limit <n>", "Max entries (1-1000, default 200)").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Annotate each path with language / file-type / byte size").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, options) => {
+  return pkgCommand.command("files").summary("List files in an indexed dependency").description(PKG_FILES_DESCRIPTION).argument("[spec-or-prefix]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the path-prefix.").argument("[path-prefix]", "Spec mode only: literal directory prefix (not a glob). 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 selector").option("--glob <glob>", "Glob selector (repeatable)", collectRepeatable).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable).option("--file-type <type>", "File type filter such as source or doc (repeatable)", collectRepeatable).option("--language <language>", "Language filter matching aigrep language names (repeatable)", collectRepeatable).option("--file-intent <intent>", "Inclusive file-intent filter. Repeat to include multiple intents: production, test, benchmark, example, generated, fixture, build, vendor", collectRepeatable).option("--exclude-intent <intent>", "Exclude these file intents after inclusive filtering (repeatable)", collectRepeatable).option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--hidden", "Include dotfiles and dot-prefixed paths").option("--limit <n>", "Max entries (1-1000, default 200)").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Annotate each path with language / file-type / byte size").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, options) => {
     const deps = await createContainer();
     await pkgFilesAction(arg1, arg2, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -7517,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,
@@ -7544,7 +7934,7 @@ async function pkgGrepAction(first, second, third, options, deps) {
     if (options.json) {
       console.log(JSON.stringify(payload));
       if (payload.totalMatches === 0)
-        process.exit(1);
+        process.exitCode = 1;
       return;
     }
     const rendered = formatGrepRepoTerminal(payload, {
@@ -7557,7 +7947,7 @@ async function pkgGrepAction(first, second, third, options, deps) {
     if (rendered.stderr)
       process.stderr.write(rendered.stderr);
     if (payload.totalMatches === 0)
-      process.exit(1);
+      process.exitCode = 1;
   } catch (error2) {
     handleCodeNavCommandError(error2, options.json ?? false, formatFileErrorWithFilesHint, 2);
   }
@@ -7570,7 +7960,7 @@ function resolvePositionals2(first, second, third, hasRepoUrl) {
     return { spec: undefined, pattern: first, pathPrefix: second };
   }
   if (first !== undefined && second === undefined) {
-    throw new InvalidPackageSpecError("In spec mode, pass at least <spec> <pattern>. If you meant to target a repository instead, pass --repo-url <url> --git-ref <ref>.");
+    throw new InvalidPackageSpecError("In spec mode, pass at least <spec> <pattern>. If you meant to target a repository instead, pass --repo-url <url> with optional --git-ref <ref>.");
   }
   return { spec: first, pattern: second, pathPrefix: third };
 }
@@ -7595,7 +7985,7 @@ var PKG_GREP_DESCRIPTION = `Deterministic text grep over indexed dependency and
 ${CLI_GREP_PATTERN_NOTE}
 Use \`githits search\` for discovery; use \`githits code grep\` when you know the text or regex to match.
 
-Addressing: <spec> (registry:name[@version]) OR --repo-url <url> --git-ref <ref>.
+Addressing: <spec> (registry:name[@version]) OR --repo-url <url> [--git-ref <ref>].
 Omitted version means latest release.
 In spec mode pass <spec> <pattern> [path-prefix]; in repo-URL mode pass only <pattern> [path-prefix].
 
@@ -7610,8 +8000,8 @@ for context, --verbose for grouped output, and --cursor to continue a paginated
 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 (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --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-zzmbjttb.js");
+  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-70bn2pmx.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -7721,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,
@@ -7845,7 +8236,7 @@ Binary files show a one-line sentinel instead of content. When a
 path is missing, the response is a FILE_NOT_FOUND error — use
 \`code files\` to discover available paths.`;
 function registerCodeReadCommand(pkgCommand) {
-  return pkgCommand.command("read").summary("Read a file from an indexed dependency").description(PKG_READ_DESCRIPTION).argument("[spec-or-path]", "In spec mode: package spec (e.g. npm:express). In --repo-url mode: the file path. See examples in `--help`.").argument("[path]", "File path (spec mode only — in --repo-url mode use the first positional).").option("--repo-url <url>", "Repository URL addressing (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--lines <start-end>", "Line range (e.g. `10-40`, `10-` for open end, `-40` for open start)").option("--start <n>", "Starting line (1-indexed). Alternative to --lines.").option("--end <n>", "Ending line (inclusive). Alternative to --lines.").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render a header and a line-number gutter alongside the content").option("--json", "Emit the JSON envelope").action(async (spec, path, options) => {
+  return pkgCommand.command("read").summary("Read a file from an indexed dependency").description(PKG_READ_DESCRIPTION).argument("[spec-or-path]", "In spec mode: package spec (e.g. npm:express). In --repo-url mode: the file path. See examples in `--help`.").argument("[path]", "File path (spec mode only — in --repo-url mode use the first positional).").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("--lines <start-end>", "Line range (e.g. `10-40`, `10-` for open end, `-40` for open start)").option("--start <n>", "Starting line (1-indexed). Alternative to --lines.").option("--end <n>", "Ending line (inclusive). Alternative to --lines.").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render a header and a line-number gutter alongside the content").option("--json", "Emit the JSON envelope").action(async (spec, path, options) => {
     const deps = await createContainer();
     await pkgReadAction(spec, path, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -7862,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 versions use the latest release. For repo default-branch discovery without refs use `githits search`; 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);
@@ -7883,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,
@@ -7953,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));
@@ -8006,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);
 }
@@ -8019,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 };
@@ -8059,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);
@@ -8071,7 +8465,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-zzmbjttb.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-70bn2pmx.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -8119,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);
@@ -8362,17 +8756,11 @@ function removeServerConfig(existingContent, serversKey, serverName) {
 `
   };
 }
-function formatSetupPreview(config) {
-  if (config.method === "cli") {
-    return config.commands.map((cmd) => `Will run: ${cmd.command} ${cmd.args.join(" ")}`).join(`
+function formatUninstallPreview(config) {
+  if (config.method === "composite") {
+    return config.steps.map(({ step }) => formatUninstallPreview(step)).join(`
 `);
   }
-  const snippet = JSON.stringify({ [config.serverName]: config.serverConfig }, null, 2);
-  return `Will add to ${config.configPath}:
-
-${snippet}`;
-}
-function formatUninstallPreview(config) {
   if (config.method === "cli") {
     return config.commands.map((cmd) => `Will run: ${cmd.command} ${cmd.args.join(" ")}`).join(`
 `);
@@ -8433,6 +8821,26 @@ async function getConfigUninstallCheckStatus(config, fs) {
     };
   }
 }
+async function isSetupAlreadyConfigured(config, fs, execService) {
+  if (config.method === "config-file") {
+    return isAlreadyConfigured(config, fs);
+  }
+  if (config.method === "cli") {
+    if (!config.checkCommand) {
+      return false;
+    }
+    return isCliAlreadyConfigured(config.checkCommand, execService);
+  }
+  for (const step of config.steps) {
+    if (!await isSetupAlreadyConfigured(step, fs, execService)) {
+      return false;
+    }
+  }
+  return true;
+}
+async function isCliAlreadyConfigured(check, execService) {
+  return await getCliCheckStatus(check, execService) === "configured";
+}
 async function getCliCheckStatus(check, execService) {
   try {
     const result = await execService.exec(check.command, check.args);
@@ -8463,6 +8871,7 @@ var ALREADY_EXISTS_PATTERNS = [
 var ALREADY_ABSENT_PATTERNS = [
   /(?:plugin|extension|server|mcp server)\s+["']?githits["']?\s+(?:was\s+)?not\s+found/i,
   /["']?githits["']?\s+(?:plugin|extension|server)?\s*(?:does\s+not\s+exist|is\s+not\s+installed|not\s+installed)/i,
+  /(?:package\s+)?["']?pi-mcp-adapter["']?\s+(?:is\s+)?not\s+installed/i,
   /unknown\s+(?:plugin|extension|server)\s+["']?githits["']?/i,
   /marketplace\s+["']?githits-plugins["']?\s+(?:was\s+)?not\s+found/i
 ];
@@ -8563,8 +8972,7 @@ async function executeCliUninstall(uninstall, execService) {
   let anyRemoved = false;
   let anyNotConfigured = false;
   const warnings = [];
-  for (let index = 0;index < uninstall.commands.length; index += 1) {
-    const cmd = uninstall.commands[index];
+  for (const cmd of uninstall.commands) {
     const result = await executeCliUninstallCommand(cmd, execService);
     if (result.status === "failed") {
       if (anyRemoved) {
@@ -8599,6 +9007,49 @@ async function executeCliUninstall(uninstall, execService) {
   }
   return { status: "removed", message: "Removed successfully" };
 }
+async function executeCompositeUninstall(uninstall, fs, execService) {
+  let anyRemoved = false;
+  let anyNotConfigured = false;
+  const warnings = [];
+  for (const { step, failureMode } of uninstall.steps) {
+    const result = await executeUninstallStep(step, fs, execService);
+    if (result.status === "removed") {
+      anyRemoved = true;
+      warnings.push(...result.warnings ?? []);
+      continue;
+    }
+    if (result.status === "not_configured") {
+      if (anyRemoved) {
+        warnings.push(result.message);
+      } else {
+        anyNotConfigured = true;
+      }
+      continue;
+    }
+    if (failureMode === "best-effort" && anyRemoved) {
+      warnings.push(result.message);
+      continue;
+    }
+    return result;
+  }
+  if (anyRemoved) {
+    return {
+      status: "removed",
+      message: "Removed successfully",
+      warnings: warnings.length > 0 ? warnings : undefined
+    };
+  }
+  if (anyNotConfigured) {
+    return {
+      status: "not_configured",
+      message: "GitHits not configured"
+    };
+  }
+  return { status: "not_configured", message: "GitHits not configured" };
+}
+async function executeUninstallStep(step, fs, execService) {
+  return step.method === "cli" ? executeCliUninstall(step, execService) : executeConfigFileUninstall(step, fs);
+}
 async function executeConfigFileSetup(setup, fs) {
   try {
     const parentDir = fs.getDirname(setup.configPath);
@@ -8642,6 +9093,26 @@ async function executeConfigFileSetup(setup, fs) {
     };
   }
 }
+async function executeCompositeSetup(setup, fs, execService) {
+  let executedAny = false;
+  for (const step of setup.steps) {
+    if (await isSetupAlreadyConfigured(step, fs, execService)) {
+      continue;
+    }
+    executedAny = true;
+    const result = step.method === "cli" ? await executeCliSetup(step, execService) : await executeConfigFileSetup(step, fs);
+    if (result.status === "failed") {
+      return result;
+    }
+  }
+  if (!executedAny) {
+    return {
+      status: "already_configured",
+      message: "GitHits already configured"
+    };
+  }
+  return { status: "success", message: "Configured successfully" };
+}
 async function executeConfigFileUninstall(setup, fs) {
   try {
     let existingContent = "";
@@ -8728,6 +9199,25 @@ function getOpenCodeConfigDir(fs) {
   }
   return fs.joinPath(fs.getHomeDir(), ".config", "opencode");
 }
+function expandHomePath(fs, path) {
+  if (path === "~") {
+    return fs.getHomeDir();
+  }
+  if (path.startsWith("~/")) {
+    return fs.joinPath(fs.getHomeDir(), path.slice(2));
+  }
+  return path;
+}
+function getPiAgentDir(fs) {
+  const configuredDir = process.env.PI_CODING_AGENT_DIR?.trim();
+  if (configuredDir) {
+    return expandHomePath(fs, configuredDir);
+  }
+  return fs.joinPath(fs.getHomeDir(), ".pi", "agent");
+}
+function getPiMcpConfigPath(fs) {
+  return fs.joinPath(getPiAgentDir(fs), "mcp.json");
+}
 function getOpenCodeDesktopDetectPaths(fs) {
   const userDataRoot = getUserDataRoot(fs);
   return [
@@ -8746,6 +9236,57 @@ async function isExecutableAvailable(exec, executable) {
     return false;
   }
 }
+async function resolveExecutableFromPath(exec, executable) {
+  return isExecutableAvailable(exec, executable);
+}
+var PI_GLOBAL_BIN_PROBES = [
+  { command: "npm", args: ["prefix", "-g"], output: "prefix" },
+  { command: "pnpm", args: ["bin", "-g"], output: "binDir" },
+  { command: "bun", args: ["pm", "bin", "-g"], output: "binDir" }
+];
+var PI_ADAPTER_CONFIGURED_PATTERN = /(?:^|\s|:)(?:npm:)?pi-mcp-adapter(?:[\s@:]|$)/i;
+function getPiExecutableNames() {
+  return process.platform === "win32" ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+}
+async function runGlobalBinProbe(exec, probe) {
+  try {
+    const result = await exec.exec(probe.command, [...probe.args]);
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    const probePath = result.stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0);
+    if (!probePath) {
+      return null;
+    }
+    if (probe.output === "prefix" && process.platform !== "win32") {
+      return fsJoinPathLike(probePath, "bin");
+    }
+    return probePath;
+  } catch {
+    return null;
+  }
+}
+function fsJoinPathLike(base, child) {
+  return base.endsWith("/") ? `${base}${child}` : `${base}/${child}`;
+}
+async function detectPiExecutable(exec, fs) {
+  if (await resolveExecutableFromPath(exec, "pi")) {
+    return { command: "pi" };
+  }
+  for (const probe of PI_GLOBAL_BIN_PROBES) {
+    const binDir = await runGlobalBinProbe(exec, probe);
+    if (!binDir) {
+      continue;
+    }
+    for (const executableName of getPiExecutableNames()) {
+      const candidate = fs.joinPath(binDir, executableName);
+      if (await fs.exists(candidate)) {
+        return { command: candidate };
+      }
+    }
+  }
+  return null;
+}
 var claudeCode = {
   name: "Claude Code",
   id: "claude-code",
@@ -8885,6 +9426,76 @@ var codexCli = {
     ]
   })
 };
+var pi = {
+  name: "Pi",
+  id: "pi",
+  detectionMethod: "binary",
+  setupMethod: "composite",
+  detectCommand: detectPiExecutable,
+  getSetupConfig: (fs, context) => {
+    const piCommand = context?.command ?? "pi";
+    return {
+      method: "composite",
+      steps: [
+        {
+          method: "cli",
+          commands: [
+            {
+              command: piCommand,
+              args: ["install", "npm:pi-mcp-adapter"]
+            }
+          ],
+          checkCommand: {
+            command: piCommand,
+            args: ["list"],
+            configuredPattern: PI_ADAPTER_CONFIGURED_PATTERN
+          }
+        },
+        {
+          method: "config-file",
+          configPath: getPiMcpConfigPath(fs),
+          serversKey: "mcpServers",
+          serverName: GITHITS_SERVER_NAME,
+          serverConfig: {
+            command: GITHITS_MCP_COMMAND,
+            args: [...GITHITS_MCP_ARGS],
+            lifecycle: "eager"
+          }
+        }
+      ]
+    };
+  },
+  getUninstallConfig: (fs, context) => {
+    const piCommand = context?.command ?? "pi";
+    return {
+      method: "composite",
+      steps: [
+        {
+          failureMode: "required",
+          step: {
+            method: "config-file",
+            configPath: getPiMcpConfigPath(fs),
+            serversKey: "mcpServers",
+            serverName: GITHITS_SERVER_NAME,
+            serverConfig: {}
+          }
+        },
+        {
+          failureMode: "required",
+          step: {
+            method: "cli",
+            commands: [
+              {
+                command: piCommand,
+                args: ["remove", "npm:pi-mcp-adapter"]
+              }
+            ]
+          }
+        }
+      ]
+    };
+  }
+};
 var vscode = {
   name: "VS Code / Copilot",
   id: "vscode",
@@ -9009,82 +9620,110 @@ var agentDefinitions = [
   cline,
   claudeDesktop,
   codexCli,
+  pi,
   geminiCli,
   googleAntigravity,
   openCode
 ];
-async function scanAgents(definitions, fs, execService) {
-  const result = {
-    needsSetup: [],
-    alreadyConfigured: [],
-    notDetected: []
-  };
-  for (const agent of definitions) {
-    let detected = false;
-    if (agent.detectionMethod === "binary" && agent.detectBinary) {
-      try {
-        detected = await agent.detectBinary(execService);
-      } 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 };
       }
-    } 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;
-        }
+    } 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 === "hybrid") {
-      let binaryDetected = false;
-      let pathDetected = false;
-      if (agent.detectBinary) {
-        try {
-          binaryDetected = await agent.detectBinary(execService);
-        } catch {
-          binaryDetected = false;
-        }
+    }
+  } 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;
-          }
+    }
+    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 };
     }
-    if (agent.setupMethod === "config-file") {
-      const config = agent.getSetupConfig(fs);
-      if (config.method === "config-file" && await isAlreadyConfigured(config, fs)) {
-        result.alreadyConfigured.push(agent);
-      } else {
-        result.needsSetup.push(agent);
-      }
+    const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
+    let configured = checkStatus === "configured";
+    if (!configured && checkStatus === "probe_failed") {
+      configured = await isGeminiExtensionInstalledFromFilesystem(fs);
+    }
+    return {
+      status: configured ? "already_configured" : "needs_setup",
+      agent: 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 {
-      const config = agent.getSetupConfig(fs);
-      if (config.method === "cli" && config.checkCommand) {
-        const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
-        let configured = checkStatus === "configured";
-        if (!configured && agent.id === "gemini-cli") {
-          if (checkStatus === "probe_failed") {
-            configured = await isGeminiExtensionInstalledFromFilesystem(fs);
-          }
-        }
-        if (configured) {
-          result.alreadyConfigured.push(agent);
-        } else {
-          result.needsSetup.push(agent);
-        }
-      } else {
-        result.needsSetup.push(agent);
-      }
+      result.notDetected.push(outcome.agent);
     }
   }
   return result;
@@ -9094,14 +9733,440 @@ 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);
+}
+function getPiConfigFileUninstall(agent, fileSystemService) {
+  if (agent.id !== "pi") {
+    return null;
+  }
+  const uninstallConfig = agent.getUninstallConfig?.(fileSystemService);
+  if (uninstallConfig?.method !== "composite") {
+    return null;
+  }
+  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 });
+}
 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("  Open a new coding agent session and try out one of the above.");
+  console.log();
+  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");
+}
+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)}`);
+}
+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)}`);
+}
+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 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 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("  Try a quick code example search:");
-  console.log('    npx githits@latest example "How do I use useEffect cleanup?"');
+  console.log("    No API keys or secrets are written into your MCP config.");
   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.");
+}
+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);
@@ -9135,28 +10200,54 @@ async function verifyAgentUnconfigured(agent, fileSystemService, execService) {
     message: `${agent.name} verification failed: still configured after uninstall.`
   };
 }
-async function scanCliAgentForUninstall(agent, fileSystemService, execService) {
-  const config = agent.getSetupConfig(fileSystemService);
-  if (config.method !== "cli" || !config.checkCommand) {
+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")
+      return "configured";
+    if (checkStatus === "not_configured")
+      return "not_configured";
+    if (agent.id === "gemini-cli" && await isGeminiExtensionInstalledFromFilesystem(fileSystemService)) {
+      return "configured";
+    }
     return {
       status: "failed",
-      message: `${agent.name} does not have a verified uninstall check command.`
+      message: `Cannot inspect ${agent.name}: ${config.checkCommand.command} ${config.checkCommand.args.join(" ")} failed.`
     };
   }
-  const checkStatus = await getCliCheckStatus(config.checkCommand, execService);
-  if (checkStatus === "configured") {
-    return "configured";
-  }
-  if (checkStatus === "not_configured") {
-    return "not_configured";
+  const accumulated = {
+    configured: false,
+    notConfigured: false
+  };
+  for (const step of config.steps) {
+    const check = await inspectSetupForUninstall(agent, step, fileSystemService, execService);
+    if (check === "configured") {
+      accumulated.configured = true;
+    } else if (check === "not_configured") {
+      accumulated.notConfigured = true;
+    } else {
+      accumulated.failure = check;
+    }
   }
-  if (agent.id === "gemini-cli" && await isGeminiExtensionInstalledFromFilesystem(fileSystemService)) {
+  if (accumulated.failure)
+    return accumulated.failure;
+  if (accumulated.configured)
     return "configured";
-  }
-  return {
-    status: "failed",
-    message: `Cannot inspect ${agent.name}: ${config.checkCommand.command} ${config.checkCommand.args.join(" ")} failed.`
-  };
+  return "not_configured";
 }
 async function scanAgentsForUninstall(fileSystemService, execService) {
   const setupScan = await scanAgents(agentDefinitions, fileSystemService, execService);
@@ -9170,35 +10261,41 @@ async function scanAgentsForUninstall(fileSystemService, execService) {
     ...setupScan.alreadyConfigured,
     ...setupScan.needsSetup
   ]) {
-    const config = agent.getSetupConfig(fileSystemService);
-    if (config.method === "config-file") {
-      const check = await getConfigUninstallCheckStatus(config, fileSystemService);
-      if (check.status === "configured") {
-        result.configured.push(agent);
-      } else if (check.status === "failed") {
-        result.failed.push({
-          id: agent.id,
-          name: agent.name,
-          status: "failed",
-          message: check.message
-        });
-      } else {
-        result.notConfigured.push(agent);
-      }
+    const config = getResolvedSetupConfig(agent, fileSystemService);
+    const check = await inspectSetupForUninstall(agent, config, fileSystemService, execService);
+    if (check === "configured") {
+      result.configured.push(agent);
+    } else if (check === "not_configured") {
+      result.notConfigured.push(agent);
     } else {
-      const check = await scanCliAgentForUninstall(agent, fileSystemService, execService);
-      if (check === "configured") {
-        result.configured.push(agent);
-      } else if (check === "not_configured") {
-        result.notConfigured.push(agent);
-      } else {
-        result.failed.push({
-          id: agent.id,
-          name: agent.name,
-          status: "failed",
-          message: check.message
-        });
-      }
+      result.failed.push({
+        id: agent.id,
+        name: agent.name,
+        status: "failed",
+        message: check.message
+      });
+    }
+  }
+  for (const agent of setupScan.notDetected) {
+    const piConfigUninstall = getPiConfigFileUninstall(agent, fileSystemService);
+    if (!piConfigUninstall) {
+      continue;
+    }
+    const check = await getConfigUninstallCheckStatus(piConfigUninstall, fileSystemService);
+    if (check.status === "configured") {
+      result.configured.push({
+        ...agent,
+        resolvedUninstallConfig: piConfigUninstall,
+        skipUninstallVerification: true
+      });
+      result.notDetected = result.notDetected.filter((a) => a.id !== agent.id);
+    } else if (check.status === "failed") {
+      result.failed.push({
+        id: agent.id,
+        name: agent.name,
+        status: "failed",
+        message: check.message
+      });
     }
   }
   return result;
@@ -9206,126 +10303,100 @@ 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;
+  printInitIntro(useColors);
+  if (!options.yes) {
+    let intent;
     try {
-      const loginDeps = await createLoginDeps();
-      loginResult = 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.
+      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;
-        }
+        return;
       }
-      continuedWithoutAuth = true;
-      console.log(`    Continuing without authentication...
-`);
+      throw err;
+    }
+    if (intent === "skills") {
+      printSkillsInstructions(useColors);
+      return;
+    }
+    if (intent === "later") {
+      console.log("\n  No changes made. Run `githits init` whenever you're ready.\n");
+      return;
     }
   }
-  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)}`);
-  }
-  for (const agent of scan.notDetected) {
-    console.log(`    ${colorize(`${agent.name} — not detected`, "dim", useColors)}`);
+  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();
   }
-  console.log();
+  printScanSummary(scan, useColors);
   if (scan.needsSetup.length === 0 && scan.alreadyConfigured.length === 0) {
-    console.log(`  No coding agents detected. Install an agent and try again.
-`);
+    printTask("warning", "No supported AI coding tools detected", "install a supported tool and run `githits init` again", useColors);
+    console.log();
     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");
-      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;
     }
-    console.log("  All detected agents are already configured.");
-    printReadyNextSteps();
+  } 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);
+  }
+  const outcomes = [];
+  if (toSetup.length === 0 && scan.needsSetup.length > 0) {
+    printTask("skipped", "Setup skipped", "no tools selected", 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.getSetupConfig(fileSystemService);
-    const preview2 = formatSetupPreview(config);
-    for (const line of preview2.split(`
-`)) {
-      console.log(`    ${line}`);
-    }
+  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();
-    if (!alwaysMode) {
-      let choice;
-      try {
-        choice = await promptService.confirm3("Proceed?");
-      } catch (err) {
-        if (err instanceof ExitPromptError) {
-          console.log(`
-  Setup cancelled.
-`);
-          return;
+    return;
+  }
+  const installTasks = createInstallTaskReporter(useColors);
+  for (const agent of toSetup) {
+    const config = getResolvedSetupConfig(agent, fileSystemService);
+    const finishTask = installTasks.start(agent.name);
+    let result;
+    try {
+      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.`
+          };
         }
-        throw err;
-      }
-      if (choice === "no") {
-        outcomes.push({ id: agent.id, name: agent.name, status: "skipped" });
-        console.log();
-        continue;
-      }
-      if (choice === "always") {
-        alwaysMode = true;
-      }
-    }
-    let result = config.method === "cli" ? await executeCliSetup(config, execService) : await executeConfigFileSetup(config, fileSystemService);
-    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.`
-        };
       }
+    } finally {
+      finishTask();
     }
     outcomes.push({
       id: agent.id,
@@ -9334,38 +10405,30 @@ async function initAction(options, deps) {
       message: result.status === "failed" ? result.message : undefined
     });
     if (result.status === "success") {
-      console.log(`    ${success(`${agent.name} configured`, useColors)}
-`);
+      printTask("success", agent.name, "configured and verified", useColors);
     } else if (result.status === "already_configured") {
-      console.log(`    ${warning(`${agent.name} already configured`, useColors)}
-`);
+      printTask("warning", agent.name, "already configured", useColors);
     } else {
-      console.log(`    ${error(result.message, useColors)}
-`);
+      printTask("failed", agent.name, result.message, useColors);
     }
   }
+  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();
 }
@@ -9373,7 +10436,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...
 `);
@@ -9401,8 +10465,8 @@ async function initUninstallAction(options, deps) {
   for (const agent of scan.configured) {
     console.log(`  Uninstalling from ${colorize(agent.name, "bold", useColors)}...
 `);
-    const setupConfig = agent.getSetupConfig(fileSystemService);
-    const uninstallConfig = setupConfig.method === "config-file" ? setupConfig : agent.getUninstallConfig?.(fileSystemService);
+    const setupConfig = getResolvedSetupConfig(agent, fileSystemService);
+    const uninstallConfig = agent.resolvedUninstallConfig ?? (setupConfig.method === "config-file" ? setupConfig : agent.getUninstallConfig?.(fileSystemService, agent.resolvedSetupContext));
     if (!uninstallConfig) {
       outcomes.push({
         id: agent.id,
@@ -9442,8 +10506,8 @@ async function initUninstallAction(options, deps) {
         alwaysMode = true;
       }
     }
-    let result = uninstallConfig.method === "cli" ? await executeCliUninstall(uninstallConfig, execService) : await executeConfigFileUninstall(uninstallConfig, fileSystemService);
-    if (result.status === "removed") {
+    let result = uninstallConfig.method === "cli" ? await executeCliUninstall(uninstallConfig, execService) : uninstallConfig.method === "config-file" ? await executeConfigFileUninstall(uninstallConfig, fileSystemService) : await executeCompositeUninstall(uninstallConfig, fileSystemService, execService);
+    if (result.status === "removed" && !agent.skipUninstallVerification) {
       const verification = await verifyAgentUnconfigured(agent, fileSystemService, execService);
       if (!verification.ok) {
         result = {
@@ -9510,32 +10574,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.
-
-Authenticates with your GitHits account, then scans for available agents
-(Claude Code, Cursor, Windsurf, VS Code, Cline, Claude Desktop, Codex CLI,
-Gemini CLI, Google Antigravity), checks which are already configured,
-and sets up unconfigured ones with your confirmation.
+var INIT_DESCRIPTION = `Connect GitHits to your coding agents.
 
-Supports CLI-based setup (Claude Code, Codex, Gemini CLI) 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").action(async (options) => {
     const fileSystemService = new FileSystemServiceImpl;
     const promptService = new PromptServiceImpl;
     const execService = new ExecServiceImpl;
@@ -9543,7 +10602,7 @@ function registerInitCommand(program) {
       fileSystemService,
       promptService,
       execService,
-      createLoginDeps: () => createAuthCommandDependencies()
+      createLoginDeps: () => createContainer()
     });
   });
   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) => {
@@ -9779,11 +10838,11 @@ var structuredCodeTargetSchema = z3.object({
   package_name: z3.string().max(255).optional().describe("Package name. Required for package scope."),
   version: z3.string().max(100).optional().describe("Package version, e.g. '4.18.2' (defaults to latest). For package scope only."),
   repo_url: z3.string().optional().describe("Repository URL (GitHub). Required for repo scope. Example: https://github.com/expressjs/express"),
-  git_ref: z3.string().optional().describe("Git ref - tag, branch, or commit. Required with repo_url for code_files/code_read/code_grep. Use HEAD for latest.")
-}).describe("Target: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).");
+  git_ref: z3.string().optional().describe("Git ref - tag, branch, commit, or HEAD. Omit with repo_url to request the backend-resolved default branch.")
+}).describe("Target: provide registry + package_name (package scope) or repo_url with optional git_ref (repo scope; omitted ref means default branch intent).");
 var codeTargetSchema = z3.union([
   structuredCodeTargetSchema,
-  z3.string().min(1).describe("Compact target string. Package: `npm:react@18.2.0` or `npm:react` for latest release. Repository: `https://github.com/facebook/react#HEAD` (git ref required for code_files/code_read/code_grep).")
+  z3.string().min(1).describe("Compact target string. Package: `npm:react@18.2.0` or `npm:react` for latest release. Repository: `https://github.com/facebook/react#HEAD` or `https://github.com/facebook/react` for default branch intent.")
 ]);
 function resolveCodeTarget(target) {
   if (typeof target === "string") {
@@ -9796,10 +10855,10 @@ function resolveCodeTarget(target) {
   const hasPackageTarget = Boolean(target.registry || target.package_name);
   const hasRepoTarget = Boolean(target.repo_url || target.git_ref);
   if (hasPackageTarget && hasRepoTarget) {
-    return invalidTargetResult("Invalid target: provide either registry + package_name or repo_url + git_ref, not both.");
+    return invalidTargetResult("Invalid target: provide either registry + package_name or repo_url with optional git_ref, not both.");
   }
   if (!hasPackageTarget && !hasRepoTarget) {
-    return invalidTargetResult("Missing target: provide registry + package_name or repo_url + git_ref.");
+    return invalidTargetResult("Missing target: provide registry + package_name or repo_url.");
   }
   if (hasPackageTarget) {
     if (!target.registry || !target.package_name) {
@@ -9811,11 +10870,8 @@ function resolveCodeTarget(target) {
       version: target.version
     };
   }
-  if (!target.repo_url || !target.git_ref) {
-    if (!target.repo_url) {
-      return invalidTargetResult("Incomplete repository target: repo_url is required.");
-    }
-    return invalidTargetResult("Incomplete repository target: git_ref is required for code_files/code_read/code_grep.");
+  if (!target.repo_url) {
+    return invalidTargetResult("Incomplete repository target: repo_url is required.");
   }
   return {
     repoUrl: target.repo_url,
@@ -9861,7 +10917,7 @@ var schema3 = {
   wait_timeout_ms: z4.number().optional(),
   format: z4.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output (matches grouped by file with grep -A/-B notation for context). Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION3 = "Deterministic text or regex grep over indexed dependency and repository source files. " + 'Use this when you know the pattern (literal by default; pass `pattern_type: "regex"` for RE2). ' + "Use `search` for discovery instead. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + "Each match's `filePath` (or text file heading) chains into `code_read.path`; pick a window around `match.line` for `code_read.start_line` / `end_line`." + `
+var DESCRIPTION3 = "Deterministic text or regex grep over indexed dependency and repository source files. " + 'Use this when you know the pattern (literal by default; pass `pattern_type: "regex"` for RE2). ' + "Use `search` for discovery instead. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + "Each match's `filePath` (or text file heading) chains into `code_read.path`; pick a window around `match.line` for `code_read.start_line` / `end_line`. " + "When fresh data is not ready within the wait window, responses may include `targetResolution` provenance and immediately-queryable alternatives in error details." + `
 
 ${CODE_GREP_GUARDRAIL}`;
 function createGrepRepoTool(service) {
@@ -9955,10 +11011,10 @@ var schema4 = {
   exclude_test_files: z5.boolean().optional(),
   include_hidden: z5.boolean().optional(),
   limit: z5.number().optional().describe("Max entries to return (1–1000, default 200). Out-of-range values return an `INVALID_ARGUMENT` envelope."),
-  wait_timeout_ms: z5.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`."),
+  wait_timeout_ms: z5.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version/ref from `details.availableVersions` / `details.availableRefs`."),
   format: z5.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact paths-only listing. Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION4 = "List files in an indexed dependency. First choice for file/path " + "enumeration tasks such as files under a directory; use " + "`path_prefix` for directory prefixes (e.g. `lib/`) and optional " + "`extensions` for language filtering. Use this to discover paths " + "before `code_read` (when `code_read` returns `FILE_NOT_FOUND` or " + "you don't yet know the path) and to scope `code_grep`. Address " + "via `target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + `target.git_ref` (repo scope), mutually " + "exclusive. Narrow with `path`, `path_prefix`, `globs`, " + "`extensions`, `file_types`, `languages`, or file-intent filters. " + "JSON envelope shape: `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "Returns an `INDEXING` error envelope when the dependency is being " + "indexed on-demand — retry with a longer `wait_timeout_ms` or use " + "a version from `details.availableVersions`.";
+var DESCRIPTION4 = "List files in an indexed dependency. First choice for file/path " + "enumeration tasks such as files under a directory; use " + "`path_prefix` for directory prefixes (e.g. `lib/`) and optional " + "`extensions` for language filtering. Use this to discover paths " + "before `code_read` (when `code_read` returns `FILE_NOT_FOUND` or " + "you don't yet know the path) and to scope `code_grep`. Address " + "via `target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + optional `target.git_ref` (repo scope), mutually " + "exclusive. Narrow with `path`, `path_prefix`, `globs`, " + "`extensions`, `file_types`, `languages`, or file-intent filters. " + "JSON envelope shape: `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "When fresh data is not ready within the wait window, responses may " + "include `targetResolution` provenance and immediately-queryable " + "alternatives. On an `INDEXING` error envelope, retry with a longer " + "`wait_timeout_ms` or use a version/ref from `details.availableVersions` " + "/ `details.availableRefs`.";
 function createListFilesTool(service) {
   return {
     name: "code_files",
@@ -10721,10 +11777,10 @@ var schema11 = {
   path: z12.string().describe("Exact file path to read, not a directory. Package addressing: package-relative. Repo addressing: repo-relative. Use `code_files` with `path_prefix` to list directories, then pass an emitted `path` here."),
   start_line: z12.number().optional().describe(`Starting line (1-indexed). Omit to start at line 1. The MCP surface caps any single read at ${MCP_READ_MAX_SPAN} lines — pick a focused window from your prior \`search\` / \`code_grep\` hit.`),
   end_line: z12.number().optional().describe(`Ending line (inclusive). Must be ≥ \`start_line\` when both are set. Omitting it implies \`start_line + ${MCP_READ_MAX_SPAN - 1}\` because the MCP surface caps each read at ${MCP_READ_MAX_SPAN} lines.`),
-  wait_timeout_ms: z12.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`."),
+  wait_timeout_ms: z12.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version/ref from `details.availableVersions` / `details.availableRefs`."),
   format: z12.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — line-numbered source content. Pass `format: "json"` for the structured envelope.')
 };
-var DESCRIPTION11 = "Read one exact file from an indexed dependency; it does not list " + "directories. Use `code_files` with `path_prefix` for file/path " + "enumeration. **MCP cap: " + `${MCP_READ_MAX_SPAN} lines per call** — broader requests (or no ` + `range) silently truncate to the first ${MCP_READ_MAX_SPAN} lines ` + "from your start, with a `hint` describing what was returned vs. " + "requested. Pick a focused window from a `search` / `code_grep` " + "match. Response: `{path, language, totalLines, startLine, endLine, " + "content, isBinary, hint?}`. Binary files set `isBinary: true` and " + "omit `content`. Pass the same `path` emitted by `code_files`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + `target.git_ref` (repo scope), " + "mutually exclusive. On `INDEXING` retry with a longer " + "`wait_timeout_ms`. On `NOT_FOUND` / `FILE_NOT_FOUND` call " + "`code_files` to discover the actual path." + `
+var DESCRIPTION11 = "Read one exact file from an indexed dependency; it does not list " + "directories. Use `code_files` with `path_prefix` for file/path " + "enumeration. **MCP cap: " + `${MCP_READ_MAX_SPAN} lines per call** — broader requests (or no ` + `range) silently truncate to the first ${MCP_READ_MAX_SPAN} lines ` + "from your start, with a `hint` describing what was returned vs. " + "requested. Pick a focused window from a `search` / `code_grep` " + "match. Response: `{path, language, totalLines, startLine, endLine, " + "content, isBinary, hint?}`. Binary files set `isBinary: true` and " + "omit `content`. Pass the same `path` emitted by `code_files`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + optional `target.git_ref` (repo scope), " + "mutually exclusive. When fresh data is not ready within the wait " + "window, responses may include `targetResolution` provenance and " + "immediately-queryable alternatives. On `INDEXING` retry with a " + "longer `wait_timeout_ms` or use a version/ref from error details. " + "On `NOT_FOUND` / `FILE_NOT_FOUND` call " + "`code_files` to discover the actual path." + `
 
 ${CODE_READ_GUARDRAIL}`;
 function deriveBoundedRange(startLine, endLine) {
@@ -11124,7 +12180,7 @@ var CORE_BLOCK = `GitHits provides verified, canonical code examples from global
 \`get_example\` workflow: pass \`language\` only when you know the exact name; otherwise call \`search_language\` first. Default output is markdown with a trailing \`solution_id\`. Reuse prior results before searching again. For dependency-specific grounding, prefer package-scoped \`search\` before global \`get_example\`.`;
 var PACKAGE_TOOLS_PREAMBLE = `Indexed package/source tools inspect third-party dependency source, docs, and registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library works, or you're evaluating whether to add or upgrade a package.
 
-Targets: \`registry:name[@version]\` (\`registry:name\` = latest release). For \`search\`, repo URL without \`#\` uses the backend default-branch snapshot; exact \`code_*\` tools need \`#ref\` such as \`#HEAD\`. Default outputs are compact \`text-v1\`; pass \`format: "json"\` only for structured parsing.`;
+Targets: \`registry:name[@version]\` (\`registry:name\` = latest release). Repo targets can request the backend default-branch intent by omitting the ref (\`https://github.com/org/repo\` for \`search\`, or \`repo_url\` without \`git_ref\` for \`code_*\`); pass \`#HEAD\` / \`git_ref:"HEAD"\` when you specifically need latest HEAD. Default outputs are compact \`text-v1\`; pass \`format: "json"\` only for structured parsing.`;
 var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation work (`search`, `code_grep`, `code_read`, `code_files`) often takes 3-10 calls. For cross-project comparisons, codebase mapping, pattern surveys, or "how does X actually work" investigations, spawn a sub-task/sub-agent and ask for a compact synthesis. Do it inline only when the raw snippet belongs in the main conversation.';
 var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and symbols. Omit `sources` for AUTO. Use `sources:["code"]` for implementation/examples/tests text, `sources:["symbol"]` for precise API/entity lookup, and `sources:["docs"]` for guides/reference/changelogs. Default output is compact `text-v1` with ready-to-call follow-up arguments; pass `format: "json"` for structured locators, highlights, and source status. Complete by default; opt into partial hits with `allow_partial_results: true`. Incomplete responses carry a `searchRef`.';
 var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior `search` by `searchRef` to check progress, fetch partial hits, or fetch final results.";
@@ -11251,7 +12307,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.
@@ -11823,7 +12879,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);
@@ -11852,7 +12908,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));
@@ -11914,7 +12971,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",
@@ -11929,7 +12986,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);
   });
@@ -11948,7 +13005,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-zzmbjttb.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-70bn2pmx.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {
@@ -12047,7 +13104,7 @@ function formatUnifiedSearchTerminal(payload) {
     lines.push("");
     lines.push("Partial results:");
   }
-  const sourceStatusNotes = formatSourceStatusNotes(payload.sourceStatus);
+  const sourceStatusNotes = formatSourceStatusNotes(payload.sourceStatus, warnings);
   if (payload.results.length === 0) {
     lines.push("No results.");
     if (sourceStatusNotes.length > 0) {
@@ -12159,13 +13216,17 @@ function formatSearchStatusPartialTerminal(payload) {
     sourceStatus: payload.result.sourceStatus
   });
 }
-function formatSourceStatusNotes(sourceStatus) {
+function formatSourceStatusNotes(sourceStatus, warnings) {
   const useColors = shouldUseColors();
   if (!sourceStatus) {
     return [];
   }
   const lines = [];
   for (const entry of sourceStatus) {
+    const warningPrefix = `Source '${entry.source.toLowerCase()}' for ${entry.targetLabel}:`;
+    if (warnings?.some((warning2) => warning2.startsWith(warningPrefix))) {
+      continue;
+    }
     const label = `${entry.source.toLowerCase()} on ${entry.targetLabel}`;
     if (entry.ignoredFilters && entry.ignoredFilters.length > 0) {
       lines.push(dim(`Note: ${label} ignored filters: ${entry.ignoredFilters.join(", ")}`, useColors));
@@ -12396,7 +13457,7 @@ function mergeRanges2(ranges) {
   }
   return merged;
 }
-function formatUnifiedSearchMetadata(entry, useColors) {
+function formatUnifiedSearchMetadata(entry, _useColors) {
   if (entry.type !== "documentation_page" && entry.type !== "repository_doc") {
     return [];
   }
@@ -12409,6 +13470,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,
@@ -12445,21 +13510,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);