githits 0.2.1 → 0.2.3

package/dist/cli.js

@@ -41,11 +41,11 @@ import {
   setMcpClientVersionProvider,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-ykr7x8jp.js";
+} from "./shared/chunk-a9js75mw.js";
 import {
   __require,
   version
-} from "./shared/chunk-szjytcvw.js";
+} from "./shared/chunk-js72s35a.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -1146,12 +1146,280 @@ function mergeRanges(existing, incoming) {
 function clampCharacterOffset(text, offset) {
   return Math.max(0, Math.min(text.length, offset));
 }
+// src/shared/grep-repo-text.ts
+var SEP = " | ";
+function renderGrepRepoText(envelope) {
+  const lines = [];
+  lines.push(buildHeader(envelope));
+  lines.push("");
+  if (envelope.matches.length === 0) {
+    lines.push("No matches.");
+    const trailer2 = buildTrailer(envelope);
+    if (trailer2.length > 0) {
+      lines.push("");
+      for (const t of trailer2)
+        lines.push(t);
+    }
+    return lines.join(`
+`);
+  }
+  const blocks = buildRenderBlocks2(envelope.matches);
+  const blocksByFile = groupBlocksByFile2(blocks);
+  const useContext = blocksHaveContext(blocks);
+  const matchCountsByFile = countMatchesByFile(envelope.matches);
+  let firstFile = true;
+  for (const [filePath, fileBlocks] of blocksByFile) {
+    if (!firstFile)
+      lines.push("");
+    firstFile = false;
+    const matchCount = matchCountsByFile.get(filePath) ?? 0;
+    lines.push(`${filePath} (${matchCount})`);
+    fileBlocks.forEach((block, idx) => {
+      if (useContext && idx > 0)
+        lines.push("  --");
+      const gutterWidth = widestLineNumberInBlock(block);
+      for (const ln of block.lines) {
+        lines.push(renderLine(ln, gutterWidth, useContext));
+      }
+    });
+  }
+  const trailer = buildTrailer(envelope);
+  if (trailer.length > 0) {
+    lines.push("");
+    for (const t of trailer)
+      lines.push(t);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader(envelope) {
+  const parts = [
+    `code_grep${SEP}${envelope.totalMatches} match${envelope.totalMatches === 1 ? "" : "es"} in ${envelope.uniqueFilesMatched} file${envelope.uniqueFilesMatched === 1 ? "" : "s"}`
+  ];
+  parts.push(`pattern=${quote(envelope.pattern)}`);
+  const flags = [];
+  if (envelope.patternType === "regex")
+    flags.push("regex");
+  if (envelope.caseSensitive)
+    flags.push("case-sensitive");
+  if (flags.length > 0)
+    parts.push(flags.join(","));
+  const filterEcho = buildFilterEcho(envelope);
+  if (filterEcho)
+    parts.push(filterEcho);
+  return parts.join(SEP);
+}
+function buildFilterEcho(envelope) {
+  const filter = envelope.filter;
+  if (!filter)
+    return "";
+  const parts = [];
+  if (filter.path)
+    parts.push(`path=${quote(filter.path)}`);
+  if (filter.pathPrefix)
+    parts.push(`path_prefix=${quote(filter.pathPrefix)}`);
+  if (filter.globs?.length)
+    parts.push(`globs=${filter.globs.join(",")}`);
+  if (filter.extensions?.length) {
+    parts.push(`exts=${filter.extensions.join(",")}`);
+  }
+  if (typeof filter.maxMatches === "number") {
+    parts.push(`max_matches=${filter.maxMatches}`);
+  }
+  if (typeof filter.maxMatchesPerFile === "number") {
+    parts.push(`max_matches_per_file=${filter.maxMatchesPerFile}`);
+  }
+  return parts.join(" ");
+}
+function buildTrailer(envelope) {
+  const lines = [];
+  if (envelope.truncatedReason) {
+    lines.push(`Truncated: ${envelope.truncatedReason}. Pass narrower path/path_prefix/globs or increase max_matches.`);
+  }
+  if (envelope.hasMore && envelope.nextCursor) {
+    lines.push(`More matches available. Pass cursor=${envelope.nextCursor} for the next page.`);
+  } else if (envelope.hasMore) {
+    lines.push("More matches available.");
+  }
+  const skipNotes = [];
+  if (envelope.binaryFilesSkipped) {
+    skipNotes.push(`${envelope.binaryFilesSkipped} binary file(s) skipped`);
+  }
+  if (envelope.filesTooLargeSkipped) {
+    skipNotes.push(`${envelope.filesTooLargeSkipped} oversized file(s) skipped`);
+  }
+  if (skipNotes.length > 0) {
+    lines.push(`Note: ${skipNotes.join(", ")}.`);
+  }
+  return lines;
+}
+function buildRenderBlocks2(matches) {
+  if (matches.length === 0)
+    return [];
+  const linesByFile = new Map;
+  for (const match of matches) {
+    let lineMap = linesByFile.get(match.filePath);
+    if (!lineMap) {
+      lineMap = new Map;
+      linesByFile.set(match.filePath, lineMap);
+    }
+    const before = match.contextBefore ?? [];
+    const beforeStart = match.line - before.length;
+    for (let i = 0;i < before.length; i += 1) {
+      const lineNumber = beforeStart + i;
+      if (!lineMap.has(lineNumber)) {
+        lineMap.set(lineNumber, {
+          lineNumber,
+          content: before[i] ?? "",
+          isMatch: false
+        });
+      }
+    }
+    lineMap.set(match.line, {
+      lineNumber: match.line,
+      content: match.lineContent,
+      isMatch: true
+    });
+    const after = match.contextAfter ?? [];
+    for (let i = 0;i < after.length; i += 1) {
+      const lineNumber = match.line + i + 1;
+      if (!lineMap.has(lineNumber)) {
+        lineMap.set(lineNumber, {
+          lineNumber,
+          content: after[i] ?? "",
+          isMatch: false
+        });
+      }
+    }
+  }
+  const blocks = [];
+  for (const [filePath, lineMap] of linesByFile) {
+    const sorted = [...lineMap.values()].sort((a, b) => a.lineNumber - b.lineNumber);
+    let current = [];
+    for (const line of sorted) {
+      const previous = current[current.length - 1];
+      if (!previous || line.lineNumber === previous.lineNumber + 1) {
+        current.push(line);
+        continue;
+      }
+      blocks.push({ filePath, lines: current });
+      current = [line];
+    }
+    if (current.length > 0) {
+      blocks.push({ filePath, lines: current });
+    }
+  }
+  return blocks;
+}
+function groupBlocksByFile2(blocks) {
+  const map = new Map;
+  for (const block of blocks) {
+    const list = map.get(block.filePath) ?? [];
+    list.push(block);
+    map.set(block.filePath, list);
+  }
+  return map;
+}
+function blocksHaveContext(blocks) {
+  for (const block of blocks) {
+    for (const line of block.lines) {
+      if (!line.isMatch)
+        return true;
+    }
+  }
+  return false;
+}
+function widestLineNumberInBlock(block) {
+  let max = 0;
+  for (const line of block.lines) {
+    const len = String(line.lineNumber).length;
+    if (len > max)
+      max = len;
+  }
+  return max;
+}
+function countMatchesByFile(matches) {
+  const counts = new Map;
+  for (const match of matches) {
+    counts.set(match.filePath, (counts.get(match.filePath) ?? 0) + 1);
+  }
+  return counts;
+}
+function renderLine(line, gutterWidth, useContext) {
+  const gutter = String(line.lineNumber).padStart(gutterWidth, " ");
+  const sep = !useContext || line.isMatch ? ":" : "-";
+  return `  ${gutter}${sep} ${line.content}`;
+}
+function quote(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
 // src/shared/language-filter.ts
 var DEFAULT_LIMIT = 5;
 function filterLanguages(languages, query, limit = DEFAULT_LIMIT) {
   const lowerQuery = query.toLowerCase();
   return languages.filter((lang) => lang.name.toLowerCase().includes(lowerQuery) || lang.display_name.toLowerCase().includes(lowerQuery) || lang.aliases.some((a) => a.toLowerCase().includes(lowerQuery))).slice(0, limit).map(({ name, display_name }) => ({ name, display_name }));
 }
+// src/shared/list-files-text.ts
+var SEP2 = " | ";
+function renderListFilesText(envelope) {
+  const lines = [];
+  lines.push(buildHeader2(envelope));
+  lines.push("");
+  if (envelope.files.length === 0) {
+    lines.push(envelope.hint ?? "No files match the requested filter.");
+    return lines.join(`
+`);
+  }
+  for (const entry of envelope.files) {
+    lines.push(entry.path);
+  }
+  if (envelope.hasMore) {
+    lines.push("");
+    lines.push("More files available. Pass limit=N to widen or refine path_prefix.");
+  }
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(envelope.hint);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader2(envelope) {
+  const identity = buildIdentity(envelope);
+  const countValue = envelope.hasMore ? `${envelope.files.length}+` : String(envelope.total);
+  const parts = [
+    `code_files${SEP2}${countValue} path${countValue === "1" ? "" : "s"}`
+  ];
+  if (identity)
+    parts.push(identity);
+  const filter = buildFilterEcho2(envelope);
+  if (filter)
+    parts.push(filter);
+  return parts.join(SEP2);
+}
+function buildIdentity(envelope) {
+  if (envelope.registry && envelope.name) {
+    const version2 = envelope.indexedVersion ?? envelope.resolution?.resolvedRef;
+    return version2 ? `${envelope.registry}:${envelope.name}@${version2}` : `${envelope.registry}:${envelope.name}`;
+  }
+  if (envelope.repoUrl) {
+    return envelope.gitRef ? `${envelope.repoUrl}@${envelope.gitRef}` : envelope.repoUrl;
+  }
+  return "";
+}
+function buildFilterEcho2(envelope) {
+  const parts = [];
+  if (envelope.filter?.pathPrefix) {
+    parts.push(`path_prefix=${quote2(envelope.filter.pathPrefix)}`);
+  }
+  if (envelope.filter?.limit !== undefined) {
+    parts.push(`limit=${envelope.filter.limit}`);
+  }
+  return parts.join(" ");
+}
+function quote2(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
 // src/shared/list-package-docs-request.ts
 function buildListPackageDocsParams(input) {
   const packageName = input.packageName?.trim() ?? "";
@@ -3114,7 +3382,7 @@ function formatReadPackageDocTerminal(envelope, options) {
     return envelope.content ?? "";
   }
   const lines = [];
-  lines.push(buildHeader(envelope, options.useColors));
+  lines.push(buildHeader3(envelope, options.useColors));
   lines.push(`pageId: ${envelope.pageId}`);
   if (envelope.sourceUrl)
     lines.push(`source: ${envelope.sourceUrl}`);
@@ -3134,7 +3402,7 @@ function formatReadPackageDocTerminal(envelope, options) {
 `)}
 `;
 }
-function buildHeader(envelope, useColors) {
+function buildHeader3(envelope, useColors) {
   const badge = envelope.sourceKind === "repo" ? "[repo]" : "[crawled]";
   const title = envelope.title ?? envelope.pageId;
   const prefix = envelope.registry && envelope.name ? `${envelope.registry}:${envelope.name}${envelope.version ? `@${envelope.version}` : ""}` : "documentation";
@@ -3581,6 +3849,188 @@ function parseRepoTarget(spec) {
   }
   return { repoUrl, gitRef };
 }
+// src/shared/unified-search-text.ts
+var SUMMARY_WRAP_WIDTH = 76;
+var SEP3 = " | ";
+function renderUnifiedSearchSuccess(payload) {
+  const lines = [];
+  lines.push(buildHeader4(payload));
+  lines.push("");
+  if (payload.results.length === 0) {
+    lines.push(payload.completed ? "No hits." : "No hits yet - indexing.");
+  } else {
+    payload.results.forEach((hit, idx) => {
+      if (idx > 0)
+        lines.push("");
+      appendHit(lines, idx + 1, hit);
+    });
+  }
+  const trailer = buildTrailer2(payload);
+  if (trailer.length > 0) {
+    lines.push("");
+    for (const line of trailer)
+      lines.push(line);
+  }
+  return lines.join(`
+`);
+}
+function renderUnifiedSearchError(payload) {
+  const lines = [];
+  const header = `search${SEP3}ERROR${SEP3}code=${payload.code}${payload.retryable ? `${SEP3}retryable` : ""}`;
+  lines.push(header);
+  lines.push(payload.error);
+  if (payload.details && Object.keys(payload.details).length > 0) {
+    lines.push("");
+    lines.push("details:");
+    for (const [key, value] of Object.entries(payload.details)) {
+      lines.push(`  ${key}: ${formatDetailValue(value)}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function buildHeader4(payload) {
+  const count = payload.results.length;
+  const status = payload.completed ? `${count} hit${count === 1 ? "" : "s"}` : `${count} partial`;
+  const parts = [`search${SEP3}${status}`];
+  parts.push(`query=${quote3(payload.query.raw)}`);
+  if (!payload.completed) {
+    parts.push(`searchRef=${payload.searchRef}`);
+  }
+  return parts.join(SEP3);
+}
+function appendHit(lines, index, hit) {
+  const headerParts = [hit.target, shortType(hit.type)];
+  if (typeof hit.score === "number") {
+    headerParts.push(formatScore(hit.score));
+  }
+  lines.push(`[${index}] ${headerParts.join("  ")}`);
+  const locator = buildLocatorLine(hit);
+  if (locator)
+    lines.push(`    ${locator}`);
+  if (hit.title && hit.title !== hit.locator.filePath) {
+    lines.push(`    ${hit.title}`);
+  }
+  if (hit.summary) {
+    for (const wrapped of wrapText2(hit.summary, SUMMARY_WRAP_WIDTH)) {
+      lines.push(`    ${wrapped}`);
+    }
+  }
+}
+function shortType(type) {
+  switch (type) {
+    case "repository_code":
+      return "code";
+    case "repository_symbol":
+      return "symbol";
+    case "documentation_page":
+      return "docs";
+    case "repository_doc":
+      return "repo-docs";
+    default:
+      return type;
+  }
+}
+function buildLocatorLine(hit) {
+  const loc = hit.locator;
+  if (loc.filePath) {
+    let line = `${loc.filePath}${formatLineRange(loc.startLine, loc.endLine)}`;
+    const tail = [];
+    if (loc.qualifiedPath)
+      tail.push(loc.qualifiedPath);
+    if (loc.kind)
+      tail.push(loc.kind);
+    if (tail.length > 0)
+      line += `  ${tail.join(SEP3)}`;
+    return line;
+  }
+  if (loc.pageId)
+    return `pageId: ${loc.pageId}`;
+  if (loc.sourceUrl)
+    return loc.sourceUrl;
+  return "";
+}
+function formatLineRange(start, end) {
+  if (typeof start !== "number")
+    return "";
+  if (typeof end !== "number" || end === start)
+    return `:${start}`;
+  return `:${start}-${end}`;
+}
+function formatScore(score) {
+  return score.toFixed(2);
+}
+function buildTrailer2(payload) {
+  const lines = [];
+  if (payload.hasMore) {
+    const nextOffsetHint = typeof payload.nextOffset === "number" ? ` Pass offset=${payload.nextOffset} for the next page or limit=N to widen.` : " Pass limit=N to widen.";
+    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.`);
+  }
+  if (payload.sourceStatus && payload.sourceStatus.length > 0) {
+    lines.push("source notes:");
+    for (const entry of payload.sourceStatus) {
+      lines.push(`  - ${formatSourceStatus(entry)}`);
+    }
+  }
+  return lines;
+}
+function formatSourceStatus(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(SEP3);
+}
+function quote3(value) {
+  return value.includes('"') ? `'${value}'` : `"${value}"`;
+}
+function formatDetailValue(value) {
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  return JSON.stringify(value);
+}
+function wrapText2(text, width) {
+  const lines = [];
+  for (const paragraph of text.split(/\n/)) {
+    if (paragraph.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let remaining = paragraph.trim();
+    while (remaining.length > width) {
+      let breakAt = remaining.lastIndexOf(" ", width);
+      if (breakAt <= 0)
+        breakAt = width;
+      lines.push(remaining.slice(0, breakAt).trimEnd());
+      remaining = remaining.slice(breakAt).trimStart();
+    }
+    if (remaining.length > 0)
+      lines.push(remaining);
+  }
+  return lines;
+}
 // src/shared/list-files-request.ts
 var LIMIT_MIN2 = 1;
 var LIMIT_MAX2 = 1000;
@@ -4140,7 +4590,7 @@ grep run. --symbol-field hydrates enclosing symbol metadata (appears under each
 match in --verbose output; full payload in --json).`;
 function registerCodeGrepCommand(pkgCommand) {
   return pkgCommand.command("grep").summary("Deterministic text grep over indexed dependency source").description(PKG_GREP_DESCRIPTION).argument("[spec-or-pattern]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the pattern.").argument("[pattern-or-prefix]", "Spec mode: the pattern. Repo mode: optional path-prefix.").argument("[path-prefix]", "Spec mode only: optional path-prefix. Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (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)", collectRepeatable, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable, []).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}`, collectRepeatable, []).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-67qnnqby.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-9zze00cp.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -4172,9 +4622,7 @@ function buildReadFileParams(input) {
       startLine,
       endLine,
       waitTimeoutMs
-    },
-    startLineExplicit: input.startLine !== undefined,
-    endLineExplicit: input.endLine !== undefined
+    }
   };
 }
 function normaliseLine(raw, name) {
@@ -4238,7 +4686,7 @@ function formatReadFileTerminal(envelope, options) {
 function formatBinary(envelope, options, verbose) {
   const sentinel = dim("Binary file — cannot display as text.", options.useColors);
   if (verbose) {
-    return `${buildHeader2(envelope, options)}
+    return `${buildHeader5(envelope, options)}
 
 ${sentinel}
 `;
@@ -4249,7 +4697,7 @@ ${sentinel}
 function formatNoContent(envelope, options, verbose) {
   const sentinel = dim("(no content returned)", options.useColors);
   if (verbose) {
-    return `${buildHeader2(envelope, options)}
+    return `${buildHeader5(envelope, options)}
 
 ${sentinel}
 `;
@@ -4259,7 +4707,7 @@ ${sentinel}
 }
 function formatVerboseBody(envelope, options) {
   const lines = [];
-  lines.push(buildHeader2(envelope, options));
+  lines.push(buildHeader5(envelope, options));
   lines.push("");
   const content = envelope.content ?? "";
   const bodyLines = content.split(`
@@ -4275,11 +4723,15 @@ function formatVerboseBody(envelope, options) {
     const gutter = dim(String(lineNumber).padStart(gutterWidth, " "), options.useColors);
     lines.push(`${gutter}  ${bodyLines[i]}`);
   }
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(dim(envelope.hint, options.useColors));
+  }
   lines.push("");
   return lines.join(`
 `);
 }
-function buildHeader2(envelope, options) {
+function buildHeader5(envelope, options) {
   const parts = [envelope.path];
   if (envelope.language)
     parts.push(envelope.language);
@@ -4639,12 +5091,13 @@ var EXAMPLE_DESCRIPTION = `Get verified, canonical code examples from global ope
 For dependency, package, or repository source search, use \`githits search\` instead.
 
 Examples:
+  githits example "how to use express middleware"
   githits example "how to use express middleware" --lang javascript
   githits example "async file reading" -l python --license yolo
   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").requiredOption("-l, --lang <language>", "Programming language").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("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) => {
     try {
       const deps = await loadContainer();
       await exampleAction(query, options, deps);
@@ -4656,7 +5109,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-67qnnqby.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-9zze00cp.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -4706,6 +5159,62 @@ function registerFeedbackCommand(program) {
   });
 }
 // src/commands/init/setup-handlers.ts
+import {
+  parse as parseJsonc,
+  printParseErrorCode
+} from "jsonc-parser";
+function parseConfigObject(content) {
+  let normalizedContent = content;
+  if (normalizedContent.charCodeAt(0) === 65279) {
+    normalizedContent = normalizedContent.slice(1);
+  }
+  const trimmed = normalizedContent.trim();
+  if (trimmed === "") {
+    return {
+      format: "json",
+      value: {}
+    };
+  }
+  try {
+    const parsed = JSON.parse(normalizedContent);
+    if (!isPlainObject(parsed)) {
+      return {
+        format: "invalid",
+        error: "Config file root is not a JSON object"
+      };
+    }
+    return {
+      format: "json",
+      value: parsed
+    };
+  } catch (jsonError) {
+    const parseErrors = [];
+    const parsed = parseJsonc(normalizedContent, parseErrors, {
+      allowTrailingComma: true,
+      disallowComments: false,
+      allowEmptyContent: false
+    });
+    if (parseErrors.length > 0) {
+      const firstParseError = parseErrors[0];
+      const strictErrorMessage = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      const jsoncDetail = firstParseError ? `${printParseErrorCode(firstParseError.error)} at offset ${firstParseError.offset}` : "Unknown parse error";
+      return {
+        format: "invalid",
+        error: `Invalid JSON: ${strictErrorMessage}. JSONC parse error: ${jsoncDetail}`
+      };
+    }
+    if (!isPlainObject(parsed)) {
+      return {
+        format: "invalid",
+        error: "Config file root is not a JSON object"
+      };
+    }
+    return {
+      format: "jsonc",
+      value: parsed
+    };
+  }
+}
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -4814,29 +5323,14 @@ function getMatchingServerKeys(servers, serverName) {
   return Object.keys(servers).filter((key) => key.toLowerCase() === normalizedTarget);
 }
 function mergeServerConfig(existingContent, serversKey, serverName, serverConfig) {
-  let content = existingContent;
-  if (content.charCodeAt(0) === 65279) {
-    content = content.slice(1);
-  }
-  const trimmed = content.trim();
-  if (trimmed === "") {
-    content = "{}";
-  }
-  let config;
-  try {
-    config = JSON.parse(content);
-  } catch (err) {
+  const parsedConfig = parseConfigObject(existingContent);
+  if (parsedConfig.format === "invalid") {
     return {
       status: "parse_error",
-      error: `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`
-    };
-  }
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
-    return {
-      status: "parse_error",
-      error: "Config file root is not a JSON object"
+      error: parsedConfig.error
     };
   }
+  const config = parsedConfig.value;
   if (!(serversKey in config)) {
     config[serversKey] = {};
   }
@@ -4875,23 +5369,12 @@ ${snippet}`;
 }
 async function isAlreadyConfigured(config, fs) {
   try {
-    let content;
-    try {
-      content = await fs.readFile(config.configPath);
-    } catch {
-      return false;
-    }
-    if (content.charCodeAt(0) === 65279) {
-      content = content.slice(1);
-    }
-    const trimmed = content.trim();
-    if (trimmed === "") {
-      return false;
-    }
-    const parsed = JSON.parse(trimmed);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    const content = await fs.readFile(config.configPath);
+    const parsedConfig = parseConfigObject(content);
+    if (parsedConfig.format === "invalid") {
       return false;
     }
+    const parsed = parsedConfig.value;
     const servers = parsed[config.serversKey];
     if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
       return false;
@@ -5049,6 +5532,32 @@ function getAppDataPath(fs, appName) {
       return fs.joinPath(home, ".config", appName);
   }
 }
+function getUserDataRoot(fs) {
+  const home = fs.getHomeDir();
+  switch (process.platform) {
+    case "win32":
+      return process.env.APPDATA ?? fs.joinPath(home, "AppData", "Roaming");
+    case "darwin":
+      return fs.joinPath(home, "Library", "Application Support");
+    default:
+      return process.env.XDG_DATA_HOME ?? fs.joinPath(home, ".local", "share");
+  }
+}
+function getOpenCodeConfigDir(fs) {
+  if (process.platform === "win32") {
+    return fs.joinPath(getUserDataRoot(fs), "opencode");
+  }
+  return fs.joinPath(fs.getHomeDir(), ".config", "opencode");
+}
+function getOpenCodeDesktopDetectPaths(fs) {
+  const userDataRoot = getUserDataRoot(fs);
+  return [
+    fs.joinPath(userDataRoot, "ai.opencode.desktop"),
+    fs.joinPath(userDataRoot, "ai.opencode.desktop.beta"),
+    fs.joinPath(userDataRoot, "ai.opencode.desktop.dev"),
+    getOpenCodeConfigDir(fs)
+  ];
+}
 async function isExecutableAvailable(exec, executable) {
   try {
     const lookupCommand = process.platform === "win32" ? "where" : "which";
@@ -5261,12 +5770,13 @@ var googleAntigravity = {
 var openCode = {
   name: "OpenCode",
   id: "opencode",
-  detectionMethod: "binary",
+  detectionMethod: "hybrid",
   setupMethod: "config-file",
+  detectPaths: (fs) => getOpenCodeDesktopDetectPaths(fs),
   detectBinary: async (exec) => isExecutableAvailable(exec, "opencode"),
   getSetupConfig: (fs) => ({
     method: "config-file",
-    configPath: process.platform === "win32" ? fs.joinPath(process.env.APPDATA ?? fs.joinPath(fs.getHomeDir(), "AppData", "Roaming"), "opencode", "opencode.json") : fs.joinPath(fs.getHomeDir(), ".config", "opencode", "opencode.json"),
+    configPath: fs.joinPath(getOpenCodeConfigDir(fs), "opencode.json"),
     serversKey: "mcp",
     serverName: GITHITS_SERVER_NAME,
     serverConfig: {
@@ -5310,6 +5820,26 @@ async function scanAgents(definitions, fs, execService) {
           break;
         }
       }
+    } else if (agent.detectionMethod === "hybrid") {
+      let binaryDetected = false;
+      let pathDetected = false;
+      if (agent.detectBinary) {
+        try {
+          binaryDetected = await agent.detectBinary(execService);
+        } catch {
+          binaryDetected = false;
+        }
+      }
+      if (!binaryDetected && agent.detectPaths) {
+        const paths = agent.detectPaths(fs);
+        for (const path of paths) {
+          if (await fs.isDirectory(path)) {
+            pathDetected = true;
+            break;
+          }
+        }
+      }
+      detected = binaryDetected || pathDetected;
     }
     if (!detected) {
       result.notDetected.push(agent);
@@ -5880,7 +6410,7 @@ function createFeedbackTool(service) {
 import { z as z2 } from "zod";
 var schema2 = {
   query: z2.string().min(1).describe("Natural-language example-search query for canonical code examples."),
-  language: z2.string().min(1).describe("Programming language. Use search_language first if the exact name is uncertain."),
+  language: z2.string().min(1).optional().describe("Optional programming language. If omitted, GitHits tries to infer it automatically. Use search_language first only when you need to force a specific language and the exact name is uncertain."),
   license_mode: z2.enum(["strict", "yolo", "custom"]).optional().describe("License filtering mode: strict (default), yolo, or custom.")
 };
 var DESCRIPTION2 = `Get verified, canonical code examples from global open source.
@@ -5970,10 +6500,6 @@ function invalidTargetResult(message) {
 }
 
 // src/tools/grep-repo.ts
-var pathSelectorSchema = z4.object({
-  kind: z4.enum(["exact", "prefix", "glob"]),
-  value: z4.string()
-});
 var schema3 = {
   target: codeTargetSchema,
   pattern: z4.string().describe(GREP_REPO_PATTERN_NOTE),
@@ -5992,9 +6518,10 @@ var schema3 = {
   max_matches_per_file: z4.number().optional(),
   cursor: z4.string().optional(),
   symbol_fields: z4.array(z4.enum(GREP_REPO_SYMBOL_FIELDS)).optional().describe(GREP_REPO_SYMBOL_FIELDS_NOTE),
-  wait_timeout_ms: z4.number().optional()
+  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 grep over indexed dependency and repository source files. " + "Use this when you know the text pattern you want; use `search` for discovery. " + "Whole-target grep is the default. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. " + "Matches chain directly into `code_read` via `matches[].filePath`.";
+var DESCRIPTION3 = "Deterministic text grep over indexed dependency and repository source files. " + "Use this when you know the text pattern you want; use `search` for discovery. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + 'Default response is a compact line-oriented listing (`format: "text-v1"`); pass `format: "json"` for the structured envelope. ' + "Matches chain directly into `code_read` (the `path` and `line` from each match feed straight into `start_line` / `end_line`).";
 function createGrepRepoTool(service) {
   return {
     name: "code_grep",
@@ -6050,6 +6577,9 @@ function createGrepRepoTool(service) {
           excludeTestFiles: build.params.excludeTestFiles,
           explicit: build.explicit
         });
+        if (isTextFormat(args.format)) {
+          return textResult(renderGrepRepoText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6063,15 +6593,19 @@ function createGrepRepoTool(service) {
     }
   };
 }
+function isTextFormat(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/list-files.ts
 import { z as z5 } from "zod";
 var schema4 = {
   target: codeTargetSchema,
   path_prefix: z5.string().optional().describe("Literal directory prefix to filter by (e.g. `src/` or `lib/parser`). NOT a glob — `*.ts` and similar patterns won't match. Omit to list from the repository root."),
   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 from `details.availableVersions`."),
+  format: z5.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact paths-only listing tuned for agent context efficiency. 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. Response: " + "`{total, hasMore, files: [{path, name, language, fileType, byteSize}], " + "resolution, indexedVersion}`. Address via `target.registry` + " + "`target.package_name` (package scope) or `target.repo_url` + " + "`target.git_ref` (repo scope), mutually exclusive. `path_prefix` " + "is a literal directory prefix — it does NOT accept globs " + "(`*.ts`) or extension filters. The returned `path` values feed " + "directly into `code_read` and help scope `code_grep`. 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. Default response is a compact " + 'paths-only listing (`format: "text-v1"`); pass `format: "json"` ' + "for the structured envelope `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + `target.git_ref` (repo scope), " + "mutually exclusive. `path_prefix` is a literal directory prefix — " + "it does NOT accept globs (`*.ts`) or extension filters. The " + "returned paths feed directly into `code_read` and help scope " + "`code_grep`. 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`.";
 function createListFilesTool(service) {
   return {
     name: "code_files",
@@ -6100,6 +6634,9 @@ function createListFilesTool(service) {
           pathPrefix: build.params.pathPrefix,
           limit: build.params.limit
         });
+        if (isTextFormat2(args.format)) {
+          return textResult(renderListFilesText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6113,6 +6650,9 @@ function createListFilesTool(service) {
     }
   };
 }
+function isTextFormat2(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/list-package-docs.ts
 import { z as z6 } from "zod";
 var schema5 = {
@@ -6644,14 +7184,34 @@ function createPackageVulnerabilitiesTool(service) {
 }
 // src/tools/read-file.ts
 import { z as z11 } from "zod";
+var MCP_READ_MAX_SPAN = 150;
 var schema10 = {
   target: codeTargetSchema,
   path: z11.string().describe("Path to the file. Package addressing: package-relative. Repo addressing: repo-relative. This is the same `path` key that `code_files` emits for each entry, so chaining needs no renaming."),
-  start_line: z11.number().optional().describe("Starting line (1-indexed). Omit for the full file from line 1."),
-  end_line: z11.number().optional().describe("Ending line (inclusive). Omit for end of file. Must be ≥ `start_line` when both are set."),
+  start_line: z11.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: z11.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: z11.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`.")
 };
-var DESCRIPTION10 = "Read a file from an indexed dependency. Default returns the full " + "file; use `start_line` / `end_line` for a bounded range. Response: " + "`{path, language, totalLines, startLine, endLine, content, " + "isBinary}`. Binary files set `isBinary: true` and omit `content` — " + "agents branch on the flag rather than checking null. 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`. " + "When the path doesn't resolve the response is a `NOT_FOUND` (or " + "`FILE_NOT_FOUND`) error — call `code_files` to discover the " + "actual paths.";
+var DESCRIPTION10 = "Read a file from an indexed dependency. **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.";
+function deriveBoundedRange(startLine, endLine) {
+  const start = startLine ?? 1;
+  if (endLine === undefined) {
+    return {
+      startLine: start,
+      endLine: start + MCP_READ_MAX_SPAN - 1,
+      capped: true
+    };
+  }
+  const span = endLine - start + 1;
+  if (span > MCP_READ_MAX_SPAN) {
+    return {
+      startLine: start,
+      endLine: start + MCP_READ_MAX_SPAN - 1,
+      capped: true
+    };
+  }
+  return { startLine: start, endLine, capped: false };
+}
 function createReadFileTool(service) {
   return {
     name: "code_read",
@@ -6663,11 +7223,12 @@ function createReadFileTool(service) {
       if ("content" in target)
         return target;
       try {
+        const bounded = deriveBoundedRange(args.start_line, args.end_line);
         const build = buildReadFileParams({
           target,
           filePath: args.path,
-          startLine: args.start_line,
-          endLine: args.end_line,
+          startLine: bounded.startLine,
+          endLine: bounded.endLine,
           waitTimeoutMs: args.wait_timeout_ms
         });
         const result = await service.readFile(build.params);
@@ -6678,6 +7239,9 @@ function createReadFileTool(service) {
           gitRef: target.gitRef,
           requestedFilePath: build.params.filePath
         });
+        if (shouldEmitCappedHint(bounded, payload)) {
+          payload.hint = buildCappedHint(payload, args.start_line, args.end_line);
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -6691,6 +7255,33 @@ function createReadFileTool(service) {
     }
   };
 }
+function shouldEmitCappedHint(bounded, payload) {
+  if (!bounded.capped)
+    return false;
+  if (payload.isBinary)
+    return false;
+  if (payload.endLine === undefined)
+    return false;
+  if (payload.totalLines === undefined)
+    return false;
+  return payload.endLine < payload.totalLines;
+}
+function buildCappedHint(payload, originalStart, originalEnd) {
+  const requested = describeRequest(originalStart, originalEnd);
+  return `Returned lines ${payload.startLine}-${payload.endLine}/${payload.totalLines} ` + `(MCP cap: ${MCP_READ_MAX_SPAN} lines per call; you requested ${requested}). ` + `Pick a focused start_line/end_line window — typical 80-150 lines around a search/code_grep match. ` + `Each retry also costs context, so aim for one well-sized read.`;
+}
+function describeRequest(originalStart, originalEnd) {
+  if (originalStart === undefined && originalEnd === undefined) {
+    return "no range";
+  }
+  if (originalEnd === undefined) {
+    return `start_line=${originalStart}, no end_line`;
+  }
+  if (originalStart === undefined) {
+    return `end_line=${originalEnd}, no start_line`;
+  }
+  return `lines ${originalStart}-${originalEnd}`;
+}
 // src/tools/read-package-doc.ts
 import { z as z12 } from "zod";
 var schema11 = {
@@ -6779,7 +7370,8 @@ var schema12 = {
   allow_partial_results: z13.boolean().optional().describe("Default false waits for all sources; if the wait window expires, returns only searchRef/progress. When true, includes hits from sources that finished so far and still returns searchRef for continuation. Partial payloads support normal pagination via nextOffset."),
   limit: z13.coerce.number().int().min(1).max(100).optional(),
   offset: z13.coerce.number().int().min(0).optional(),
-  wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional()
+  wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional(),
+  format: z13.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output tuned for agent context efficiency. Pass `format: "json"` for the structured envelope (programmatic consumers, parity testing). `text` is an alias for `text-v1`. The text format is a public, snapshot-tested contract.')
 };
 var DESCRIPTION12 = "Search indexed dependency and repository code, docs, and explicit symbols. " + "Provide either `target` for one target or `targets` for many; omit `sources` to use backend AUTO. " + "The query field uses GitHits discovery syntax (AND/OR/parens/qualifiers; see the parameter description). " + "Structured parameters combine with that query using AND semantics. " + "Results are complete by default — if indexing is still running, the response carries a `searchRef` and no hits; pass it to `search_status` to follow up. " + "Set `allow_partial_results: true` to opt into hits from sources that finished while others continue indexing. " + "Each hit's `type` tells you the follow-up tool: `documentation_page` and `repository_doc` → `docs_read` with `locator.pageId`; `repository_code` and `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present).";
 function createSearchTool(service) {
@@ -6817,9 +7409,16 @@ function createSearchTool(service) {
         });
         const outcome = await service.search(built.params);
         const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
+        if (isTextFormat3(args.format)) {
+          return textResult(renderUnifiedSearchSuccess(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
-        return errorResult(JSON.stringify(buildUnifiedSearchErrorPayload(error2)));
+        const payload = buildUnifiedSearchErrorPayload(error2);
+        if (isTextFormat3(args.format)) {
+          return errorResult(renderUnifiedSearchError(payload));
+        }
+        return errorResult(JSON.stringify(payload));
       }
     }
   };
@@ -6827,6 +7426,9 @@ function createSearchTool(service) {
 function isResolvedCodeTarget(target) {
   return !("content" in target);
 }
+function isTextFormat3(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/search-language.ts
 import { z as z14 } from "zod";
 var schema13 = {
@@ -6871,9 +7473,9 @@ function createSearchStatusTool(service) {
   };
 }
 // src/commands/mcp-instructions.ts
-var CORE_BLOCK = `GitHits surfaces verified, canonical code examples from global open source. Use it when you're stuck, the user is frustrated by repeated failed attempts, you need up-to-date API usage, or the user mentions GitHits.
+var CORE_BLOCK = `GitHits surfaces verified, canonical code examples from global open source. Use it when you're stuck, the user is frustrated by repeated failed attempts, you need up-to-date API usage, the question is comparative across OSS projects (e.g. "how does X vs Y handle Z"), the answer requires reading how a real codebase implements a feature, or the user mentions GitHits.
 
-Workflow: call \`search_language\` first if the language name is uncertain → call \`get_example\` with one focused question → send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
+Workflow: call \`get_example\` with one focused question, optionally passing \`language\` when the desired language is known; call \`search_language\` first only if you need to force a language and the exact name is uncertain. Send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
 var PACKAGE_TOOLS_PREAMBLE = `Package tools work with third-party dependency source plus registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library actually works, or you're evaluating whether to add or upgrade a package.
 
 Package spec: \`registry:name[@version]\`.`;
@@ -6883,12 +7485,14 @@ var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. W
 var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages (optionally pinned to `@version`). Malicious-package advisories surface in a disjoint `malware` bucket; filter with `min_severity` or include retracted advisories with `include_withdrawn`.";
 var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus, when the backend has them, dev / peer / optional / feature groups. Pass `lifecycle` to filter groups server-side, `include_transitive` for the full graph, and `include_importers` when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
 var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns the 10 most recent entries with full markdown bodies; `from_version` switches to range mode between two versions. Addressable via `registry` + `package_name` or `repo_url`. Set `include_bodies: false` for a version / date / URL timeline when bodies aren't needed.";
-var SEARCH_BULLET = "- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.";
+var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Default response is a compact text listing (`text-v1`); pass `format: "json"` for the structured envelope with full locator fields, highlights, and source status. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.';
 var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior unified search by `searchRef`. Use it after `search` returns incomplete state to check progress, fetch partial hits when the original request used `allow_partial_results: true`, or fetch final results.";
-var CODE_FILES_BULLET = "- `code_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory; the response includes each file's language, type, and byte size. Returned `path` values feed directly into `code_read` and help scope `code_grep`.";
-var CODE_READ_BULLET = "- `code_read` — fetch a file's contents from a dependency. Pass the same `path` emitted by `code_files`. Default returns the full file; pass `start_line` / `end_line` for a bounded range. Binary files set `isBinary: true` and omit `content` — branch on the flag. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `code_files` for the actual path.";
-var CODE_GREP_BULLET = "- `code_grep` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Returned `matches[].filePath` feeds directly into `code_read`.";
-var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for full-file inspection.';
+var CODE_FILES_BULLET = '- `code_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory. Default response is a paths-only listing (`text-v1`); pass `format: "json"` for the full envelope with each file\'s language, type, and byte size. Returned paths feed directly into `code_read` and help scope `code_grep`.';
+var CODE_READ_BULLET = "- `code_read` — fetch a file's contents from a dependency. Pass the same `path` emitted by `code_files`. **MCP cap: 150 lines per call** — broader requests (or no range) silently truncate to the first 150 lines from your start, with a `hint` describing what was returned vs. requested. Pick a focused window from a `search` / `code_grep` match. Binary files set `isBinary: true` and omit `content`. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `code_files` for the actual path.";
+var CODE_GREP_BULLET = '- `code_grep` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Default response groups matches by file with line numbers (`text-v1`); pass `format: "json"` for the `matches[]` array with byte offsets and symbol metadata. Each match\'s `path:line` chains directly into `code_read`.';
+var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for focused-window inspection of a known file.';
+var REFERENCE_FIRST_TIP = "Strategy — reference-first, content-second. Locate symbols and lines with `search` / `code_grep` first, then read only the lines you actually need with `code_read` using explicit `start_line` / `end_line` windows around the match (typically 80-150 lines). The MCP `code_read` surface caps each call at 150 lines; bigger requests are silently truncated. Each turn — including retries to widen or re-narrow — costs context, so pick a focused window the first time rather than starting wide and trimming.";
+var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation tools (`search`, `code_grep`, `code_read`, `code_files`) are inherently multi-call — answering even simple questions usually takes 3-10 tool calls, and reading raw source into the main conversation compounds quickly. The default approach for any cross-project comparison, codebase mapping, pattern survey, or "how does X actually work" investigation is to spawn a sub-task / sub-agent that does the digging and returns only a compact synthesis. Do the work in the main conversation only when the result genuinely belongs there (e.g., the user asked for a specific snippet to paste into their own code). When in doubt, delegate.';
 function isPackageToolsCapabilityOpen(deps) {
   return deps.codeNavigationCliOverrideEnabled || deps.codeNavigationCapability === "enabled" || deps.codeNavigationCapability === "unknown" && deps.envApiToken !== undefined;
 }
@@ -6920,9 +7524,14 @@ function buildMcpInstructions(deps) {
 
 `);
   }
-  const parts = [PACKAGE_TOOLS_PREAMBLE, bullets.join(`
-`)];
+  const parts = [PACKAGE_TOOLS_PREAMBLE];
+  if (deps.codeNavigationService) {
+    parts.push(MULTI_TURN_TIP);
+  }
+  parts.push(bullets.join(`
+`));
   if (deps.codeNavigationService) {
+    parts.push(REFERENCE_FIRST_TIP);
     parts.push(SEARCH_VS_SYMBOLS_TIP);
   }
   sections.push(parts.join(`
@@ -6936,28 +7545,34 @@ function buildMcpInstructions(deps) {
 // src/commands/mcp.ts
 function getMcpToolDefinitions(deps) {
   const tools = [
-    createGetExampleTool(deps.githitsService),
-    createSearchLanguageTool(deps.githitsService),
-    createFeedbackTool(deps.githitsService)
+    eraseTool(createGetExampleTool(deps.githitsService)),
+    eraseTool(createSearchLanguageTool(deps.githitsService)),
+    eraseTool(createFeedbackTool(deps.githitsService))
   ];
   const gateOpen = isPackageToolsCapabilityOpen(deps);
   if (gateOpen && deps.codeNavigationService) {
-    tools.push(createSearchTool(deps.codeNavigationService));
-    tools.push(createSearchStatusTool(deps.codeNavigationService));
-    tools.push(createListFilesTool(deps.codeNavigationService));
-    tools.push(createReadFileTool(deps.codeNavigationService));
-    tools.push(createGrepRepoTool(deps.codeNavigationService));
+    tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
   }
   if (gateOpen && deps.packageIntelligenceService) {
-    tools.push(createListPackageDocsTool(deps.packageIntelligenceService));
-    tools.push(createReadPackageDocTool(deps.packageIntelligenceService));
-    tools.push(createPackageSummaryTool(deps.packageIntelligenceService));
-    tools.push(createPackageVulnerabilitiesTool(deps.packageIntelligenceService));
-    tools.push(createPackageDependenciesTool(deps.packageIntelligenceService));
-    tools.push(createPackageChangelogTool(deps.packageIntelligenceService));
+    tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
   }
   return tools;
 }
+function eraseTool(tool) {
+  return {
+    ...tool,
+    handler: (args, extra) => tool.handler(args, extra)
+  };
+}
 function createMcpServer(deps) {
   const server = new McpServer({
     name: "githits",
@@ -7571,11 +8186,11 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-67qnnqby.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-9zze00cp.js");
   return createContainer2();
 }
 async function loadStartupCodeNavigationRegistrationState() {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-67qnnqby.js");
+  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-9zze00cp.js");
   return resolveStartupCodeNavigationRegistrationState2();
 }
 function parseTargetSpecs(specs) {
@@ -7929,7 +8544,7 @@ Getting started:
   githits init                         Set up MCP for your coding agents
   githits login                        Authenticate with your GitHits account
   githits mcp                          Show MCP setup instructions
-  githits example "query" -l python    Get code examples
+  githits example "query"              Get code examples
 
 Learn more at https://githits.com
 Docs: https://app.githits.com/docs/
@@ -7943,7 +8558,6 @@ registerLanguagesCommand(program);
 registerFeedbackCommand(program);
 var argv = process.argv.slice(2);
 var registrationArgv = stripRootRegistrationOptions(argv);
-var helpInvocation = isHelpInvocation(registrationArgv);
 var shouldLoadGatedHelpRegistration = needsGatedHelpRegistration(registrationArgv);
 var helpRegistrationOptions = shouldLoadGatedHelpRegistration ? await loadHelpRegistrationOptions(registrationArgv) : undefined;
 if (shouldEagerLoadSearchCommands(registrationArgv)) {
@@ -7989,7 +8603,7 @@ function isSearchHelpTarget(value) {
   return value === "search" || value === "search-status";
 }
 async function loadHelpRegistrationOptions(args) {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-67qnnqby.js");
+  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-9zze00cp.js");
   const registrationState = await resolveStartupCodeNavigationRegistrationState2();
   return {
     capability: registrationState.capability,