githits 0.3.0 → 0.3.2

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   AuthConfigError,
+  AuthStorageLockTimeoutError,
   AuthStoragePolicyError,
   AuthenticationError,
   CLIENT_UPDATE_REQUIRED_REASON,
@@ -48,15 +49,59 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-5mk9k2gv.js";
+} from "./shared/chunk-zarrkzvq.js";
 import {
   __require,
   version
-} from "./shared/chunk-gxya097b.js";
+} from "./shared/chunk-w5kw8sef.js";
 
 // src/cli.ts
 import { Command } from "commander";
 
+// src/shared/require-auth.ts
+class AuthRequiredError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AuthRequiredError";
+  }
+}
+function requireAuth(deps, context) {
+  if (deps.hasValidToken)
+    return;
+  const suffix = context ? ` ${context}` : "";
+  console.log(`Authentication required${suffix}.
+`);
+  if (deps.mcpUrl !== "https://mcp.githits.com") {
+    console.log(`  Environment: ${deps.mcpUrl}`);
+    console.log(`  You're using a custom environment.
+`);
+  }
+  console.log("To authenticate:");
+  console.log(`  githits login
+`);
+  console.log("Or set GITHITS_API_TOKEN environment variable.");
+  console.log(`
+Need help? support@githits.com`);
+  throw new AuthRequiredError(`Authentication required${suffix}`);
+}
+
+// src/cli/errors.ts
+function handleCliError(error, deps) {
+  if (error instanceof AuthRequiredError) {
+    deps.exit(1);
+  }
+  if (isUserFacingError(error)) {
+    deps.stderr.write(`${error.message}
+
+`);
+    deps.exit(1);
+  }
+  throw error;
+}
+function isUserFacingError(error) {
+  return error instanceof AuthConfigError || error instanceof AuthStorageLockTimeoutError || error instanceof AuthStoragePolicyError;
+}
+
 // src/cli/update-check.ts
 function startUpdateCheckTask(service) {
   const controller = new AbortController;
@@ -440,6 +485,12 @@ function knownSymbolCategoryList() {
 function toFileIntent(intent) {
   return intent ? fileIntentMap[intent] : undefined;
 }
+function isKnownFileIntent(value) {
+  return value in fileIntentMap;
+}
+function knownFileIntentList() {
+  return Object.keys(fileIntentMap);
+}
 // src/shared/code-navigation-error-map.ts
 function mapCodeNavigationError(error2) {
   const mapped = classify(error2);
@@ -522,7 +573,8 @@ function classify(error2) {
     return {
       code: "AUTH_REQUIRED",
       message: error2.message,
-      retryable: false
+      retryable: false,
+      details: { action: "Run `githits login`, then retry this tool call." }
     };
   }
   if (error2 instanceof CodeNavigationNetworkError) {
@@ -618,23 +670,6 @@ function isInvalidArgumentError(error2) {
     return false;
   return error2.name.startsWith("Invalid") || error2.name.startsWith("Unsupported");
 }
-// src/shared/docs-follow-up.ts
-function lowerDocSourceKind(value) {
-  switch (value) {
-    case "CRAWLED":
-      return "crawled";
-    case "REPOSITORY":
-      return "repo";
-    default:
-      return;
-  }
-}
-// src/shared/extract-solution-id.ts
-var SOLUTION_URL_RE = /solutions\/([0-9a-fA-F-]{36})/;
-function extractSolutionId(markdown) {
-  const match = SOLUTION_URL_RE.exec(markdown);
-  return match?.[1];
-}
 // src/shared/package-spec.ts
 var KNOWN_REGISTRIES = [
   "npm",
@@ -709,6 +744,112 @@ function isKnownRegistry(value) {
   return KNOWN_REGISTRIES.includes(value);
 }
 
+// src/shared/code-navigation-target.ts
+function parseCodeNavigationTargetSpec(spec) {
+  const trimmed = spec.trim();
+  if (trimmed.length === 0) {
+    throw new InvalidArgumentError("Target spec cannot be empty.");
+  }
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    return parseRepoTarget(trimmed);
+  }
+  const parsed = parsePackageSpec(trimmed);
+  return {
+    registry: toCodeNavigationRegistry(parsed.registry),
+    packageName: parsed.name,
+    version: parsed.version
+  };
+}
+function parseRepoTarget(spec) {
+  const hashIndex = spec.lastIndexOf("#");
+  if (hashIndex === -1) {
+    return { repoUrl: spec, gitRef: "HEAD" };
+  }
+  const repoUrl = spec.slice(0, hashIndex);
+  const gitRef = spec.slice(hashIndex + 1);
+  if (!repoUrl || !gitRef) {
+    throw new InvalidArgumentError("Repository target must be a full URL with optional #gitRef suffix.");
+  }
+  return { repoUrl, gitRef };
+}
+// src/shared/docs-follow-up.ts
+function lowerDocSourceKind(value) {
+  switch (value) {
+    case "CRAWLED":
+      return "crawled";
+    case "REPOSITORY":
+      return "repo";
+    default:
+      return;
+  }
+}
+// src/shared/extract-solution-id.ts
+var SOLUTION_URL_RE = /solutions\/([0-9a-fA-F-]{36})/;
+function extractSolutionId(markdown) {
+  const match = SOLUTION_URL_RE.exec(markdown);
+  return match?.[1];
+}
+// src/shared/follow-up-command-text.ts
+function buildSearchHitFollowUpCommand(hit) {
+  const loc = hit.locator;
+  if (loc.pageId) {
+    return buildDocsReadCommand(loc.pageId, loc.startLine, loc.endLine);
+  }
+  if (loc.filePath) {
+    return buildCodeReadCommand({
+      registry: loc.registry,
+      packageName: loc.packageName,
+      version: loc.version,
+      repoUrl: loc.repoUrl,
+      gitRef: loc.gitRef,
+      filePath: loc.filePath,
+      startLine: loc.startLine,
+      endLine: loc.endLine
+    });
+  }
+  if (hit.type === "repository_code" || hit.type === "repository_symbol") {
+    return "follow-up unavailable: missing filePath";
+  }
+  if (loc.sourceUrl)
+    return loc.sourceUrl;
+  return "";
+}
+function buildDocsReadCommand(pageId, startLine, endLine) {
+  const parts = [`docs_read page_id=${quote(pageId)}`];
+  appendRange(parts, startLine, endLine);
+  return parts.join(" ");
+}
+function buildCodeReadCommand(input) {
+  if (!input.filePath)
+    return "follow-up unavailable: missing filePath";
+  const target = buildTargetSpec(input);
+  if (!target)
+    return "follow-up unavailable: missing target";
+  const parts = [
+    `code_read target=${quote(target)}`,
+    `path=${quote(input.filePath)}`
+  ];
+  appendRange(parts, input.startLine, input.endLine);
+  return parts.join(" ");
+}
+function buildTargetSpec(input) {
+  if (input.repoUrl) {
+    return `${input.repoUrl}#${input.gitRef ?? "HEAD"}`;
+  }
+  if (input.registry && input.packageName) {
+    return `${input.registry}:${input.packageName}${input.version ? `@${input.version}` : ""}`;
+  }
+  return;
+}
+function appendRange(parts, startLine, endLine) {
+  if (typeof startLine === "number")
+    parts.push(`start_line=${startLine}`);
+  if (typeof endLine === "number")
+    parts.push(`end_line=${endLine}`);
+}
+function quote(value) {
+  return JSON.stringify(value);
+}
 // src/shared/grep-repo-request.ts
 var PATTERN_MAX = 200;
 var CONTEXT_MIN = 0;
@@ -1326,7 +1467,7 @@ 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)}`);
+  parts.push(`pattern=${quote2(envelope.pattern)}`);
   const flags = [];
   if (envelope.patternType === "regex")
     flags.push("regex");
@@ -1345,9 +1486,9 @@ function buildFilterEcho(envelope) {
     return "";
   const parts = [];
   if (filter.path)
-    parts.push(`path=${quote(filter.path)}`);
+    parts.push(`path=${quote2(filter.path)}`);
   if (filter.pathPrefix)
-    parts.push(`path_prefix=${quote(filter.pathPrefix)}`);
+    parts.push(`path_prefix=${quote2(filter.pathPrefix)}`);
   if (filter.globs?.length)
     parts.push(`globs=${filter.globs.join(",")}`);
   if (filter.extensions?.length) {
@@ -1480,14 +1621,18 @@ function renderLine(line, gutterWidth, useContext) {
   const sep = !useContext || line.isMatch ? ":" : "-";
   return `  ${gutter}${sep} ${line.content}`;
 }
-function quote(value) {
+function quote2(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 }));
+  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, aliases }) => ({
+    name,
+    display_name,
+    aliases
+  }));
 }
 // src/shared/list-files-text.ts
 var SEP2 = " | ";
@@ -1505,7 +1650,7 @@ function renderListFilesText(envelope) {
   }
   if (envelope.hasMore) {
     lines.push("");
-    lines.push("More files available. Pass limit=N to widen or refine path_prefix.");
+    lines.push("More files available. Pass limit=N or refine the filter.");
   }
   if (envelope.hint) {
     lines.push("");
@@ -1539,15 +1684,48 @@ function buildIdentity(envelope) {
 }
 function buildFilterEcho2(envelope) {
   const parts = [];
+  if (envelope.filter?.path) {
+    parts.push(`path=${quote3(envelope.filter.path)}`);
+  }
   if (envelope.filter?.pathPrefix) {
-    parts.push(`path_prefix=${quote2(envelope.filter.pathPrefix)}`);
+    parts.push(`path_prefix=${quote3(envelope.filter.pathPrefix)}`);
+  }
+  if (envelope.filter?.globs?.length) {
+    parts.push(`globs=${envelope.filter.globs.join(",")}`);
+  }
+  if (envelope.filter?.extensions?.length) {
+    parts.push(`exts=${envelope.filter.extensions.join(",")}`);
+  }
+  if (envelope.filter?.fileTypes?.length) {
+    parts.push(`file_types=${envelope.filter.fileTypes.join(",")}`);
+  }
+  if (envelope.filter?.languages?.length) {
+    parts.push(`languages=${envelope.filter.languages.join(",")}`);
+  }
+  if (envelope.filter?.fileIntent) {
+    parts.push(`file_intent=${envelope.filter.fileIntent}`);
+  }
+  if (envelope.filter?.fileIntents?.length) {
+    parts.push(`file_intents=${envelope.filter.fileIntents.join(",")}`);
+  }
+  if (envelope.filter?.excludeFileIntents?.length) {
+    parts.push(`exclude_file_intents=${envelope.filter.excludeFileIntents.join(",")}`);
+  }
+  if (envelope.filter?.excludeDocFiles !== undefined) {
+    parts.push(`exclude_doc_files=${String(envelope.filter.excludeDocFiles)}`);
+  }
+  if (envelope.filter?.excludeTestFiles !== undefined) {
+    parts.push(`exclude_test_files=${String(envelope.filter.excludeTestFiles)}`);
+  }
+  if (envelope.filter?.includeHidden !== undefined) {
+    parts.push(`include_hidden=${String(envelope.filter.includeHidden)}`);
   }
   if (envelope.filter?.limit !== undefined) {
     parts.push(`limit=${envelope.filter.limit}`);
   }
   return parts.join(" ");
 }
-function quote2(value) {
+function quote3(value) {
   return value.includes('"') ? `'${value}'` : `"${value}"`;
 }
 // src/shared/list-package-docs-request.ts
@@ -1647,8 +1825,6 @@ function buildListPackageDocsSuccessPayload(result, options) {
         entry.requestedRef = page.requestedRef;
       if (page.filePath)
         entry.filePath = page.filePath;
-      if (page.linkName)
-        entry.linkName = page.linkName;
       if (lastUpdatedAt)
         entry.lastUpdatedAt = lastUpdatedAt;
       return entry;
@@ -1736,6 +1912,51 @@ function formatPageMeta(page, useColors, verbose) {
   }
   return lines;
 }
+// src/shared/list-package-docs-text.ts
+var SEP3 = " | ";
+function renderListPackageDocsText(envelope) {
+  const lines = [];
+  lines.push(buildHeader3(envelope));
+  lines.push("");
+  if (envelope.pages.length === 0) {
+    lines.push("No documentation pages found.");
+    return lines.join(`
+`);
+  }
+  for (const page of envelope.pages) {
+    lines.push([
+      page.pageId,
+      page.title ?? "",
+      page.sourceKind ?? "",
+      page.sourceUrl ?? ""
+    ].join(SEP3));
+    lines.push(`  ${buildDocsReadCommand(page.pageId)}`);
+    if (page.sourceKind === "repo" && page.repoUrl && page.filePath) {
+      lines.push(`  ${buildCodeReadCommand({
+        repoUrl: page.repoUrl,
+        gitRef: page.requestedRef ?? page.gitRef,
+        filePath: page.filePath,
+        startLine: 1,
+        endLine: 150
+      })}`);
+    }
+  }
+  if (envelope.nextCursor) {
+    lines.push("");
+    lines.push(`More docs available. Pass after=${envelope.nextCursor}.`);
+  }
+  if (envelope.stale) {
+    lines.push("");
+    lines.push("Documentation may be stale.");
+  }
+  return lines.join(`
+`);
+}
+function buildHeader3(envelope) {
+  const target = envelope.registry && envelope.name ? `${envelope.registry}:${envelope.name}${envelope.version ? `@${envelope.version}` : ""}` : "package docs";
+  const suffix = envelope.total !== undefined ? `/${envelope.total}` : "";
+  return `docs_list${SEP3}${target}${SEP3}${envelope.pages.length}${suffix} page${envelope.pages.length === 1 ? "" : "s"}`;
+}
 // src/shared/package-dependencies-request.ts
 class UnsupportedDependenciesRegistryError extends Error {
   constructor(message) {
@@ -1784,6 +2005,7 @@ function buildPackageDependenciesParams(input) {
   }
   const version2 = normaliseVersion(input.version);
   const canonicalLifecycles = resolveLifecycles(input.lifecycle);
+  const wireLifecycles = canonicalLifecycles.filter((entry) => entry !== "runtime" && entry !== "all");
   const maxDepth = input.maxDepth;
   if (maxDepth !== undefined) {
     if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 10) {
@@ -1792,13 +2014,14 @@ function buildPackageDependenciesParams(input) {
   }
   return {
     canonicalLifecycles,
+    wireLifecycles,
     params: {
       registry,
       packageName: trimmedName,
       version: version2,
       includeTransitive: input.includeTransitive,
       maxDepth,
-      lifecycle: canonicalLifecycles.length > 0 ? canonicalLifecycles : undefined
+      lifecycle: wireLifecycles.length > 0 ? wireLifecycles : undefined
     }
   };
 }
@@ -1823,16 +2046,29 @@ function resolveLifecycles(raw) {
     if (trimmed.length === 0)
       continue;
     const lower = trimmed.toLowerCase();
-    if (!isLifecycle(lower)) {
-      throw new InvalidPackageSpecError(`Unknown lifecycle '${trimmed}'. Expected one of: ${LIFECYCLES.join(", ")}.`);
+    if (!isLifecycleInput(lower)) {
+      throw new InvalidPackageSpecError(`Unknown lifecycle '${trimmed}'. Expected one of: ${LIFECYCLES.join(", ")}, all.`);
     }
     seen.add(lower);
   }
-  return Array.from(seen).sort((a, b) => LIFECYCLE_ORDER[a] - LIFECYCLE_ORDER[b]);
+  if (seen.has("all") && seen.size > 1) {
+    throw new InvalidPackageSpecError("lifecycle=all cannot be combined with other lifecycle values.");
+  }
+  return Array.from(seen).sort(lifecycleInputSort);
 }
 function isLifecycle(value) {
   return LIFECYCLES.includes(value);
 }
+function isLifecycleInput(value) {
+  return value === "all" || isLifecycle(value);
+}
+function lifecycleInputSort(a, b) {
+  if (a === "all")
+    return b === "all" ? 0 : 1;
+  if (b === "all")
+    return -1;
+  return LIFECYCLE_ORDER[a] - LIFECYCLE_ORDER[b];
+}
 // src/shared/package-dependencies-response.ts
 function buildPackageDependenciesSuccessPayload(report, options = {}) {
   const pkg = report.package;
@@ -1854,10 +2090,16 @@ function buildPackageDependenciesSuccessPayload(report, options = {}) {
     payload.runtime = { count: items.length, items };
   }
   const groupsInfo = report.dependencyGroups;
-  if (groupsInfo !== undefined) {
-    const groupItems = sortGroups(groupsInfo.groups.map(buildGroup));
+  if (groupsInfo !== undefined && shouldEmitGroups(options.canonicalLifecycles)) {
+    const groupItems = sortGroups(groupsInfo.groups.map(buildGroup).filter((group) => {
+      if (!options.canonicalLifecycles)
+        return false;
+      if (options.canonicalLifecycles.includes("all"))
+        return true;
+      return options.canonicalLifecycles.includes(group.lifecycle);
+    }));
     const groupsBlock = { items: groupItems };
-    if (groupsInfo.primaryGroup) {
+    if (groupsInfo.primaryGroup && groupItems.some((group) => group.name === groupsInfo.primaryGroup)) {
       groupsBlock.primaryGroup = groupsInfo.primaryGroup;
     }
     if (groupsInfo.environmentMarkers && groupsInfo.environmentMarkers.length > 0) {
@@ -1899,6 +2141,11 @@ function buildPackageDependenciesSuccessPayload(report, options = {}) {
   }
   return payload;
 }
+function shouldEmitGroups(lifecycles) {
+  if (!lifecycles || lifecycles.length === 0)
+    return false;
+  return lifecycles.some((entry) => entry !== "runtime");
+}
 function projectEnvironmentMarker(marker) {
   const out = {};
   if (marker.type !== undefined)
@@ -2117,7 +2364,7 @@ function formatPackageDependenciesTerminal(report, options = {}) {
   const verbose = options.verbose ?? false;
   const payload = buildPackageDependenciesSuccessPayload(report, {
     requestedVersion: options.requestedVersion,
-    canonicalLifecycles: options.canonicalLifecycles,
+    canonicalLifecycles: options.canonicalLifecycles ?? ["all"],
     includeTransitive: options.includeTransitive,
     maxDepth: options.maxDepth,
     includeImporters: verbose
@@ -2126,7 +2373,7 @@ function formatPackageDependenciesTerminal(report, options = {}) {
   const showGroups = options.showGroups ?? false;
   const includeTransitive = options.includeTransitive ?? false;
   const blocks = [];
-  blocks.push(formatHeaderBlock(payload, useColors, showGroups));
+  blocks.push(formatHeaderBlock(payload, useColors, showGroups, options));
   if (includeTransitive) {
     blocks.push(formatTransitiveDepsList(payload, verbose, useColors));
     const issues = formatConflictsAndCycles(payload, verbose, useColors);
@@ -2143,7 +2390,7 @@ function formatPackageDependenciesTerminal(report, options = {}) {
 `)}
 `;
 }
-function formatHeaderBlock(payload, useColors, showGroups) {
+function formatHeaderBlock(payload, useColors, showGroups, options) {
   const name = colorize(payload.name, "bold", useColors);
   const lines = [
     `${name} @ ${payload.version} · ${payload.registry}`
@@ -2151,11 +2398,11 @@ function formatHeaderBlock(payload, useColors, showGroups) {
   if (payload.requestedVersion) {
     lines.push(dim(`(requested ${payload.requestedVersion})`, useColors));
   }
-  lines.push(formatSummaryRow(payload, useColors, showGroups));
+  lines.push(formatSummaryRow(payload, useColors, showGroups, options));
   return lines.join(`
 `);
 }
-function formatSummaryRow(payload, useColors, showGroups) {
+function formatSummaryRow(payload, useColors, showGroups, options) {
   const countParts = [];
   const runtimeCount = payload.runtime?.count ?? 0;
   if (runtimeCount === 0) {
@@ -2192,7 +2439,7 @@ function formatSummaryRow(payload, useColors, showGroups) {
   const hidden = collectHiddenGroupNames(payload);
   if (hidden.length === 0)
     return countLine;
-  const hiddenLine = dim(`Hidden groups: ${hidden.join(", ")} — use --groups.`, useColors);
+  const hiddenLine = dim(`Hidden groups: ${hidden.join(", ")} — ${options.hiddenGroupsHint ?? "use --lifecycle all."}`, useColors);
   return `${countLine}
 ${hiddenLine}`;
 }
@@ -2483,7 +2730,8 @@ function classify2(error2) {
     return {
       code: "AUTH_REQUIRED",
       message: error2.message,
-      retryable: false
+      retryable: false,
+      details: { action: "Run `githits login`, then retry this tool call." }
     };
   }
   if (error2 instanceof PackageIntelligenceNetworkError) {
@@ -3688,6 +3936,55 @@ function requirePositiveInteger(raw, label) {
   }
   return parsed;
 }
+// src/shared/read-file-text.ts
+var SEP4 = " | ";
+function renderReadFileText(envelope) {
+  const lines = [];
+  lines.push(buildHeader4(envelope));
+  lines.push("");
+  if (envelope.isBinary) {
+    lines.push("Binary file - cannot display as text.");
+  } else if (envelope.content) {
+    appendNumberedContent(lines, envelope.content, envelope.startLine ?? 1);
+  } else {
+    lines.push("(no content returned)");
+  }
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(`hint: ${envelope.hint}`);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader4(envelope) {
+  const parts = [`code_read${SEP4}${envelope.path}`];
+  if (envelope.language)
+    parts.push(envelope.language);
+  const range = buildRange(envelope);
+  if (range)
+    parts.push(range);
+  return parts.join(SEP4);
+}
+function buildRange(envelope) {
+  if (envelope.startLine !== undefined && envelope.endLine !== undefined) {
+    return envelope.totalLines !== undefined ? `lines ${envelope.startLine}-${envelope.endLine}/${envelope.totalLines}` : `lines ${envelope.startLine}-${envelope.endLine}`;
+  }
+  if (envelope.totalLines !== undefined)
+    return `${envelope.totalLines} lines`;
+  return;
+}
+function appendNumberedContent(lines, content, startLine) {
+  const bodyLines = content.split(`
+`);
+  if (bodyLines.length > 0 && bodyLines[bodyLines.length - 1] === "") {
+    bodyLines.pop();
+  }
+  const endLine = startLine + bodyLines.length - 1;
+  const width = String(endLine).length;
+  for (let i = 0;i < bodyLines.length; i += 1) {
+    lines.push(`${String(startLine + i).padStart(width, " ")}  ${bodyLines[i]}`);
+  }
+}
 // src/shared/read-package-doc-request.ts
 function buildReadPackageDocParams(input) {
   const pageId = input.pageId?.trim() ?? "";
@@ -3731,8 +4028,6 @@ function buildReadPackageDocSuccessPayload(result, requestedPageId, range) {
   if (result.page?.breadcrumbs && result.page.breadcrumbs.length > 0) {
     envelope.breadcrumbs = result.page.breadcrumbs;
   }
-  if (result.page?.linkName)
-    envelope.linkName = result.page.linkName;
   if (result.page?.lastUpdatedAt) {
     envelope.lastUpdatedAt = toIsoDate(result.page.lastUpdatedAt) ?? undefined;
   }
@@ -3781,7 +4076,7 @@ function formatReadPackageDocTerminal(envelope, options) {
     return envelope.content ?? "";
   }
   const lines = [];
-  lines.push(buildHeader3(envelope, options.useColors));
+  lines.push(buildHeader5(envelope, options.useColors));
   lines.push(`pageId: ${envelope.pageId}`);
   if (envelope.sourceUrl)
     lines.push(`source: ${envelope.sourceUrl}`);
@@ -3801,37 +4096,49 @@ function formatReadPackageDocTerminal(envelope, options) {
 `)}
 `;
 }
-function buildHeader3(envelope, useColors) {
+function buildHeader5(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";
   return `${colorize(`${prefix} ${badge}`, "bold", useColors)}${title ? ` - ${title}` : ""}`;
 }
-// src/shared/require-auth.ts
-class AuthRequiredError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AuthRequiredError";
+// src/shared/read-package-doc-text.ts
+var SEP5 = " | ";
+function renderReadPackageDocText(envelope) {
+  const lines = [];
+  lines.push(buildHeader6(envelope));
+  if (envelope.sourceUrl)
+    lines.push(`source: ${envelope.sourceUrl}`);
+  if (envelope.filePath) {
+    const ref = envelope.requestedRef ?? envelope.gitRef;
+    lines.push(`file: ${envelope.filePath}${ref ? ` @ ${ref}` : ""}`);
   }
-}
-function requireAuth(deps, context) {
-  if (deps.hasValidToken)
-    return;
-  const suffix = context ? ` ${context}` : "";
-  console.log(`Authentication required${suffix}.
-`);
-  if (deps.mcpUrl !== "https://mcp.githits.com") {
-    console.log(`  Environment: ${deps.mcpUrl}`);
-    console.log(`  You're using a custom environment.
-`);
+  lines.push("");
+  if (envelope.content)
+    lines.push(envelope.content);
+  if (envelope.hint) {
+    lines.push("");
+    lines.push(`hint: ${envelope.hint}`);
   }
-  console.log("To authenticate:");
-  console.log(`  githits login
+  return lines.join(`
 `);
-  console.log("Or set GITHITS_API_TOKEN environment variable.");
-  console.log(`
-Need help? support@githits.com`);
-  throw new AuthRequiredError(`Authentication required${suffix}`);
+}
+function buildHeader6(envelope) {
+  const parts = [`docs_read${SEP5}${envelope.pageId}`];
+  if (envelope.title)
+    parts.push(envelope.title);
+  const range = buildRange2(envelope);
+  if (range)
+    parts.push(range);
+  return parts.join(SEP5);
+}
+function buildRange2(envelope) {
+  if (envelope.startLine !== undefined && envelope.endLine !== undefined) {
+    return envelope.totalLines !== undefined ? `lines ${envelope.startLine}-${envelope.endLine}/${envelope.totalLines}` : `lines ${envelope.startLine}-${envelope.endLine}`;
+  }
+  if (envelope.totalLines !== undefined)
+    return `${envelope.totalLines} lines`;
+  return;
 }
 // src/shared/unified-search-request.ts
 var DEFAULT_UNIFIED_SEARCH_LIMIT = 10;
@@ -4107,8 +4414,6 @@ function buildHitPayload(hit) {
     payload.title = hit.title;
   if (hit.summary)
     payload.summary = hit.summary;
-  if (typeof hit.score === "number")
-    payload.score = hit.score;
   const highlights = buildHighlights(hit.highlights);
   if (highlights)
     payload.highlights = highlights;
@@ -4275,49 +4580,17 @@ function assertSearchFollowUpInvariant(hit) {
     throw new MalformedCodeNavigationResponseError("REPOSITORY_DOC search hit missing repo locator fields.");
   }
 }
-// src/shared/unified-search-target.ts
-function parseUnifiedSearchTargetSpec(spec) {
-  const trimmed = spec.trim();
-  if (trimmed.length === 0) {
-    throw new InvalidArgumentError("Target spec cannot be empty.");
-  }
-  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
-    return parseRepoTarget(trimmed);
-  }
-  const parsed = parsePackageSpec(trimmed);
-  return {
-    registry: toCodeNavigationRegistry(parsed.registry),
-    packageName: parsed.name,
-    version: parsed.version
-  };
-}
-function parseRepoTarget(spec) {
-  const hashIndex = spec.lastIndexOf("#");
-  if (hashIndex === -1) {
-    return { repoUrl: spec, gitRef: "HEAD" };
-  }
-  const repoUrl = spec.slice(0, hashIndex);
-  const gitRef = spec.slice(hashIndex + 1);
-  if (!repoUrl || !gitRef) {
-    throw new InvalidArgumentError("Repository target must be a full URL with optional #gitRef suffix.");
-  }
-  return { repoUrl, gitRef };
-}
 // src/shared/unified-search-text.ts
 var SUMMARY_WRAP_WIDTH = 76;
-var SEP3 = " | ";
+var SEP6 = " | ";
 function renderUnifiedSearchSuccess(payload) {
   const lines = [];
-  lines.push(buildHeader4(payload));
+  lines.push(buildHeader7(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);
-    });
+    appendUnifiedSearchHits(lines, payload.results);
   }
   const trailer = buildTrailer2(payload);
   if (trailer.length > 0) {
@@ -4330,7 +4603,7 @@ function renderUnifiedSearchSuccess(payload) {
 }
 function renderUnifiedSearchError(payload) {
   const lines = [];
-  const header = `search${SEP3}ERROR${SEP3}code=${payload.code}${payload.retryable ? `${SEP3}retryable` : ""}`;
+  const header = `search${SEP6}ERROR${SEP6}code=${payload.code}${payload.retryable ? `${SEP6}retryable` : ""}`;
   lines.push(header);
   lines.push(payload.error);
   if (payload.details && Object.keys(payload.details).length > 0) {
@@ -4343,21 +4616,25 @@ function renderUnifiedSearchError(payload) {
   return lines.join(`
 `);
 }
-function buildHeader4(payload) {
+function buildHeader7(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)}`);
+  const parts = [`search${SEP6}${status}`];
+  parts.push(`query=${quote4(payload.query.raw)}`);
   if (!payload.completed) {
     parts.push(`searchRef=${payload.searchRef}`);
   }
-  return parts.join(SEP3);
+  return parts.join(SEP6);
+}
+function appendUnifiedSearchHits(lines, hits) {
+  hits.forEach((hit, idx) => {
+    if (idx > 0)
+      lines.push("");
+    appendHit(lines, idx + 1, hit);
+  });
 }
 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)
@@ -4387,6 +4664,15 @@ function shortType(type) {
 }
 function buildLocatorLine(hit) {
   const loc = hit.locator;
+  const followUp = buildSearchHitFollowUpCommand(hit);
+  if (followUp) {
+    const tail = [];
+    if (loc.qualifiedPath)
+      tail.push(loc.qualifiedPath);
+    if (loc.kind)
+      tail.push(loc.kind);
+    return tail.length > 0 ? `${followUp}  ${tail.join(SEP6)}` : followUp;
+  }
   if (loc.filePath) {
     let line = `${loc.filePath}${formatLineRange(loc.startLine, loc.endLine)}`;
     const tail = [];
@@ -4395,7 +4681,7 @@ function buildLocatorLine(hit) {
     if (loc.kind)
       tail.push(loc.kind);
     if (tail.length > 0)
-      line += `  ${tail.join(SEP3)}`;
+      line += `  ${tail.join(SEP6)}`;
     return line;
   }
   if (loc.pageId)
@@ -4411,9 +4697,6 @@ function formatLineRange(start, end) {
     return `:${start}`;
   return `:${start}-${end}`;
 }
-function formatScore(score) {
-  return score.toFixed(2);
-}
 function buildTrailer2(payload) {
   const lines = [];
   if (payload.warnings && payload.warnings.length > 0) {
@@ -4457,9 +4740,9 @@ function formatSourceStatus(entry) {
   }
   if (entry.note)
     parts.push(entry.note);
-  return parts.join(SEP3);
+  return parts.join(SEP6);
 }
-function quote3(value) {
+function quote4(value) {
   return value.includes('"') ? `'${value}'` : `"${value}"`;
 }
 function formatDetailValue(value) {
@@ -4491,6 +4774,89 @@ function wrapText2(text, width) {
   }
   return lines;
 }
+
+// src/shared/unified-search-status-text.ts
+var SEP7 = " | ";
+function renderUnifiedSearchStatusText(payload) {
+  const lines = [];
+  lines.push(buildHeader8(payload));
+  if (!payload.completed && payload.progress) {
+    lines.push(formatProgress(payload.progress));
+  }
+  const result = payload.result;
+  if (result)
+    appendResult(lines, result);
+  if (!payload.completed) {
+    lines.push(`next: call search_status search_ref=${quote5(payload.searchRef)}`);
+  }
+  return lines.join(`
+`);
+}
+function buildHeader8(payload) {
+  const state = payload.completed ? "complete" : "indexing";
+  const parts = [`search_status${SEP7}${state}`];
+  if (payload.searchRef)
+    parts.push(`searchRef=${payload.searchRef}`);
+  return parts.join(SEP7);
+}
+function appendResult(lines, result) {
+  lines.push("");
+  if (result.warnings && result.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning2 of result.warnings)
+      lines.push(`  - ${warning2}`);
+    lines.push("");
+  }
+  if (result.results.length === 0) {
+    lines.push("No hits.");
+  } else {
+    appendUnifiedSearchHits(lines, result.results);
+  }
+  if (result.hasMore) {
+    const nextOffsetHint = typeof result.nextOffset === "number" ? ` Pass offset=${result.nextOffset} for the next page or limit=N to widen.` : " Pass limit=N to widen.";
+    lines.push("");
+    lines.push(`More hits available.${nextOffsetHint}`);
+  }
+  if (result.sourceStatus && result.sourceStatus.length > 0) {
+    lines.push("");
+    lines.push("source notes:");
+    for (const entry of result.sourceStatus) {
+      lines.push(`  - ${formatSourceStatus2(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) {
+  return `progress: ${progress.status}, ${progress.targetsReady}/${progress.targetsTotal} targets ready, ${progress.elapsedMs}ms elapsed`;
+}
+function quote5(value) {
+  return JSON.stringify(value);
+}
+// src/shared/unified-search-target.ts
+function parseUnifiedSearchTargetSpec(spec) {
+  return parseCodeNavigationTargetSpec(spec);
+}
 // src/shared/list-files-request.ts
 var LIMIT_MIN2 = 1;
 var LIMIT_MAX2 = 1000;
@@ -4501,20 +4867,140 @@ function buildListFilesParams(input) {
   const limitExplicit = input.limit !== undefined;
   const limit = normaliseLimit(input.limit);
   const waitTimeoutMs = normaliseWaitTimeoutMs(input.waitTimeoutMs);
+  const path = normalizeOptionalNonEmpty2(input.path, "path");
   const pathPrefix = normalisePathPrefix(input.pathPrefix);
+  const globs = normalizeStringList2(input.globs, "globs");
+  const extensions = normalizeExtensions2(input.extensions);
+  const fileTypes = normalizeStringList2(input.fileTypes, "file_types");
+  const languages = normalizeStringList2(input.languages, "languages");
+  const { fileIntent, fileIntentEcho } = normalizeOptionalFileIntent(input.fileIntent, "file_intent");
+  const fileIntents = normalizeFileIntentList(input.fileIntents, "file_intents");
+  const excludeFileIntents = normalizeFileIntentList(input.excludeFileIntents, "exclude_file_intents");
+  if (fileIntent && fileIntents.length > 0) {
+    throw new InvalidPackageSpecError("`file_intent` cannot be combined with `file_intents`.");
+  }
+  const pathSelectors = buildPathSelectors2({ path, globs });
+  const pathExplicit = path !== undefined;
   const pathPrefixExplicit = pathPrefix !== undefined;
+  const globsExplicit = globs.length > 0;
   return {
     params: {
       target: input.target,
+      pathSelectors,
       pathPrefix,
+      extensions: extensions.length > 0 ? extensions : undefined,
+      fileTypes: fileTypes.length > 0 ? fileTypes : undefined,
+      languages: languages.length > 0 ? languages : undefined,
+      fileIntent,
+      fileIntents: fileIntents.length > 0 ? fileIntents : undefined,
+      excludeFileIntents: excludeFileIntents.length > 0 ? excludeFileIntents : undefined,
+      excludeDocFiles: input.excludeDocFiles,
+      excludeTestFiles: input.excludeTestFiles,
+      includeHidden: input.includeHidden,
       limit,
       waitTimeoutMs
     },
     effectiveLimit: limit,
     limitExplicit,
-    pathPrefixExplicit
+    explicit: {
+      path: pathExplicit,
+      pathPrefix: pathPrefixExplicit,
+      globs: globsExplicit,
+      extensions: extensions.length > 0,
+      fileTypes: fileTypes.length > 0,
+      languages: languages.length > 0,
+      fileIntent: fileIntent !== undefined,
+      fileIntents: fileIntents.length > 0,
+      excludeFileIntents: excludeFileIntents.length > 0,
+      excludeDocFiles: input.excludeDocFiles !== undefined,
+      excludeTestFiles: input.excludeTestFiles !== undefined,
+      includeHidden: input.includeHidden !== undefined,
+      limit: limitExplicit
+    },
+    filterEcho: {
+      path,
+      pathPrefix,
+      globs: globsExplicit ? globs : undefined,
+      extensions: extensions.length > 0 ? extensions : undefined,
+      fileTypes: fileTypes.length > 0 ? fileTypes : undefined,
+      languages: languages.length > 0 ? languages : undefined,
+      fileIntent: fileIntentEcho,
+      fileIntents: fileIntents.length > 0 ? fileIntents.map((intent) => intent.toLowerCase()) : undefined,
+      excludeFileIntents: excludeFileIntents.length > 0 ? excludeFileIntents.map((intent) => intent.toLowerCase()) : undefined,
+      excludeDocFiles: input.excludeDocFiles,
+      excludeTestFiles: input.excludeTestFiles,
+      includeHidden: input.includeHidden,
+      limit: limitExplicit ? limit : undefined
+    }
   };
 }
+function buildPathSelectors2(input) {
+  const selectors = [];
+  if (input.path)
+    selectors.push({ kind: "EXACT", value: input.path });
+  for (const glob of input.globs) {
+    selectors.push({ kind: "GLOB", value: glob });
+  }
+  return selectors.length > 0 ? selectors : undefined;
+}
+function normalizeOptionalNonEmpty2(raw, field) {
+  if (raw === undefined)
+    return;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new InvalidPackageSpecError(`\`${field}\` cannot be empty when provided.`);
+  }
+  return trimmed;
+}
+function normalizeStringList2(raw, field) {
+  if (!raw)
+    return [];
+  const values = [];
+  for (const entry of raw) {
+    const trimmed = entry.trim();
+    if (trimmed.length === 0) {
+      throw new InvalidPackageSpecError(`\`${field}\` entries cannot be empty.`);
+    }
+    values.push(trimmed);
+  }
+  return values;
+}
+function normalizeExtensions2(raw) {
+  const values = normalizeStringList2(raw, "extensions");
+  for (const value of values) {
+    if (value.startsWith(".")) {
+      throw new InvalidPackageSpecError("`extensions` values must not include a leading dot.");
+    }
+  }
+  return values;
+}
+function normalizeOptionalFileIntent(raw, field) {
+  if (raw === undefined)
+    return {};
+  const trimmed = raw.trim().toLowerCase();
+  if (trimmed.length === 0) {
+    throw new InvalidPackageSpecError(`\`${field}\` cannot be empty when provided.`);
+  }
+  if (!isKnownFileIntent(trimmed)) {
+    throw new InvalidPackageSpecError(`\`${field}\` must be one of: ${knownFileIntentList().join(", ")}. Got ${raw}.`);
+  }
+  return {
+    fileIntent: toFileIntent(trimmed),
+    fileIntentEcho: trimmed
+  };
+}
+function normalizeFileIntentList(raw, field) {
+  const values = normalizeStringList2(raw, field);
+  const intents = [];
+  for (const value of values) {
+    const lower = value.toLowerCase();
+    if (!isKnownFileIntent(lower)) {
+      throw new InvalidPackageSpecError(`\`${field}\` values must be one of: ${knownFileIntentList().join(", ")}. Got ${value}.`);
+    }
+    intents.push(toFileIntent(lower));
+  }
+  return intents;
+}
 function normaliseLimit(raw) {
   if (raw === undefined)
     return LIMIT_DEFAULT2;
@@ -4593,10 +5079,43 @@ function projectResolution2(resolution) {
 }
 function buildFilterBlock2(options) {
   const filter = {};
-  if (options.pathPrefixExplicit && options.pathPrefix) {
+  if (options.explicit.path && options.path) {
+    filter.path = options.path;
+  }
+  if (options.explicit.pathPrefix && options.pathPrefix) {
     filter.pathPrefix = options.pathPrefix;
   }
-  if (options.limitExplicit && options.limit !== undefined) {
+  if (options.explicit.globs && options.globs && options.globs.length > 0) {
+    filter.globs = options.globs;
+  }
+  if (options.explicit.extensions && options.extensions && options.extensions.length > 0) {
+    filter.extensions = options.extensions;
+  }
+  if (options.explicit.fileTypes && options.fileTypes && options.fileTypes.length > 0) {
+    filter.fileTypes = options.fileTypes;
+  }
+  if (options.explicit.languages && options.languages && options.languages.length > 0) {
+    filter.languages = options.languages;
+  }
+  if (options.explicit.fileIntent && options.fileIntent) {
+    filter.fileIntent = options.fileIntent;
+  }
+  if (options.explicit.fileIntents && options.fileIntents && options.fileIntents.length > 0) {
+    filter.fileIntents = options.fileIntents;
+  }
+  if (options.explicit.excludeFileIntents && options.excludeFileIntents && options.excludeFileIntents.length > 0) {
+    filter.excludeFileIntents = options.excludeFileIntents;
+  }
+  if (options.explicit.excludeDocFiles) {
+    filter.excludeDocFiles = options.excludeDocFiles;
+  }
+  if (options.explicit.excludeTestFiles) {
+    filter.excludeTestFiles = options.excludeTestFiles;
+  }
+  if (options.explicit.includeHidden) {
+    filter.includeHidden = options.includeHidden;
+  }
+  if (options.explicit.limit && options.limit !== undefined) {
     filter.limit = options.limit;
   }
   return Object.keys(filter).length > 0 ? filter : undefined;
@@ -4848,9 +5367,19 @@ async function pkgFilesAction(firstArg, secondArg, options, deps) {
     const target = resolveCliCodeNavTarget(spec, options);
     const limit = parseIntCliOption(options.limit, "--limit", 1, 1000);
     const wait = parseIntCliOption(options.wait, "--wait", 0, MAX_WAIT_TIMEOUT_MS);
-    const build = buildListFilesParams({
+    const build = buildCliListFilesParams({
       target,
+      path: options.path,
       pathPrefix,
+      globs: options.glob,
+      extensions: options.ext,
+      fileTypes: options.fileType,
+      languages: options.language,
+      fileIntents: options.fileIntent,
+      excludeFileIntents: options.excludeIntent,
+      excludeDocFiles: options.excludeDocs,
+      excludeTestFiles: options.excludeTests,
+      includeHidden: options.hidden,
       limit,
       waitTimeoutMs: wait
     });
@@ -4860,10 +5389,20 @@ async function pkgFilesAction(firstArg, secondArg, options, deps) {
       name: target.packageName,
       repoUrl: target.repoUrl,
       gitRef: target.gitRef,
-      limitExplicit: build.limitExplicit,
-      pathPrefixExplicit: build.pathPrefixExplicit,
-      pathPrefix: build.params.pathPrefix,
-      limit: build.params.limit
+      path: build.filterEcho.path,
+      pathPrefix: build.filterEcho.pathPrefix,
+      globs: build.filterEcho.globs,
+      extensions: build.filterEcho.extensions,
+      fileTypes: build.filterEcho.fileTypes,
+      languages: build.filterEcho.languages,
+      fileIntent: build.filterEcho.fileIntent,
+      fileIntents: build.filterEcho.fileIntents,
+      excludeFileIntents: build.filterEcho.excludeFileIntents,
+      excludeDocFiles: build.filterEcho.excludeDocFiles,
+      excludeTestFiles: build.filterEcho.excludeTestFiles,
+      includeHidden: build.filterEcho.includeHidden,
+      limit: build.filterEcho.limit,
+      explicit: build.explicit
     });
     if (options.json) {
       console.log(JSON.stringify(payload));
@@ -4880,6 +5419,21 @@ async function pkgFilesAction(firstArg, secondArg, options, deps) {
     handleCodeNavCommandError(error2, options.json ?? false, formatIndexingError);
   }
 }
+function collectRepeatable(value, previous) {
+  return [...previous ?? [], value];
+}
+function buildCliListFilesParams(input) {
+  try {
+    return buildListFilesParams(input);
+  } catch (error2) {
+    if (!(error2 instanceof InvalidPackageSpecError))
+      throw error2;
+    const rewritten = error2.message.replace(/^`path`/, "`--path`").replace(/`globs`/g, "`--glob`").replace(/`extensions`/g, "`--ext`").replace(/`file_types`/g, "`--file-type`").replace(/`languages`/g, "`--language`").replace(/`file_intent`/g, "`--file-intent`").replace(/`file_intents`/g, "`--file-intent`").replace(/`exclude_file_intents`/g, "`--exclude-intent`").replace(/`path_prefix`/g, "`[path-prefix]`");
+    if (rewritten === error2.message)
+      throw error2;
+    throw new InvalidPackageSpecError(rewritten);
+  }
+}
 var REGISTRY_SPEC_HINT = /^(npm|pypi|hex|crates|nuget|maven|zig|vcpkg|packagist):/i;
 function resolvePositionals(firstArg, secondArg, hasRepoUrl) {
   if (hasRepoUrl) {
@@ -4899,8 +5453,11 @@ fetch more. Returned paths feed directly into \`githits code read\`
 and \`githits code grep\`.
 
 [path-prefix] is a literal directory prefix (e.g. \`src/\` or
-\`lib/parser\`), NOT a glob — \`*.ts\` and similar patterns won't
-match. File-type / extension filtering is not supported server-side.
+\`lib/parser\`). Use --path for exact-file selectors, repeatable
+--glob for glob selectors, and --ext / --file-type / --language /
+--file-intent to intersect further. Selectors ([path-prefix], --path,
+--glob) are OR-ed — a file matches if any selector matches. The other
+filters intersect on top.
 
 Addressing: <spec> (registry:name[@version]) OR --repo-url <url>
 --git-ref <ref>. Supported registries: npm, pypi, hex, crates,
@@ -4913,7 +5470,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("--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 (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) => {
     const deps = await createContainer();
     await pkgFilesAction(arg1, arg2, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -5020,7 +5577,7 @@ function resolvePositionals2(first, second, third, hasRepoUrl) {
   }
   return { spec: first, pattern: second, pathPrefix: third };
 }
-function collectRepeatable(value, previous = []) {
+function collectRepeatable2(value, previous = []) {
   return [...previous, value];
 }
 function buildCliGrepParams(input) {
@@ -5055,8 +5612,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)", 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-1gqfte6e.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 (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-rwcs5gyy.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -5152,7 +5709,7 @@ function formatReadFileTerminal(envelope, options) {
 function formatBinary(envelope, options, verbose) {
   const sentinel = dim("Binary file — cannot display as text.", options.useColors);
   if (verbose) {
-    return `${buildHeader5(envelope, options)}
+    return `${buildHeader9(envelope, options)}
 
 ${sentinel}
 `;
@@ -5163,7 +5720,7 @@ ${sentinel}
 function formatNoContent(envelope, options, verbose) {
   const sentinel = dim("(no content returned)", options.useColors);
   if (verbose) {
-    return `${buildHeader5(envelope, options)}
+    return `${buildHeader9(envelope, options)}
 
 ${sentinel}
 `;
@@ -5173,7 +5730,7 @@ ${sentinel}
 }
 function formatVerboseBody(envelope, options) {
   const lines = [];
-  lines.push(buildHeader5(envelope, options));
+  lines.push(buildHeader9(envelope, options));
   lines.push("");
   const content = envelope.content ?? "";
   const bodyLines = content.split(`
@@ -5197,7 +5754,7 @@ function formatVerboseBody(envelope, options) {
   return lines.join(`
 `);
 }
-function buildHeader5(envelope, options) {
+function buildHeader9(envelope, options) {
   const parts = [envelope.path];
   if (envelope.language)
     parts.push(envelope.language);
@@ -5575,7 +6132,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-rwcs5gyy.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -6364,14 +6921,11 @@ async function preflightAuthPersistence(authStorage, mcpUrl) {
     createdAt: new Date(0).toISOString()
   };
   try {
-    await authStorage.saveClient(probeUrl, probeClient);
-    await authStorage.saveTokens(probeUrl, probeTokens);
-    await authStorage.clearTokens(probeUrl);
-    await authStorage.clearClient(probeUrl);
+    await authStorage.saveAuthSession(probeUrl, probeClient, probeTokens);
+    await authStorage.clearAuthSession(probeUrl);
     return null;
   } catch (error2) {
-    await authStorage.clearTokens(probeUrl).catch(() => {});
-    await authStorage.clearClient(probeUrl).catch(() => {});
+    await authStorage.clearAuthSession(probeUrl).catch(() => {});
     const message = error2 instanceof Error ? error2.message : String(error2);
     return {
       status: "failed",
@@ -6425,7 +6979,6 @@ async function loginFlow(options, deps) {
           redirectUri,
           registeredAt: new Date().toISOString()
         };
-        await authStorage.saveClient(mcpUrl, client);
       }
       port = options.port;
     } else {
@@ -6447,7 +7000,6 @@ async function loginFlow(options, deps) {
       redirectUri,
       registeredAt: new Date().toISOString()
     };
-    await authStorage.saveClient(mcpUrl, client);
   }
   const { verifier, challenge, state } = authService.generatePkceParams();
   const authUrl = authService.buildAuthUrl({
@@ -6512,7 +7064,7 @@ async function loginFlow(options, deps) {
     };
   }
   const expiresAt = new Date(Date.now() + tokenResponse.expiresIn * 1000).toISOString();
-  await authStorage.saveTokens(mcpUrl, {
+  await authStorage.saveAuthSession(mcpUrl, client, {
     accessToken: tokenResponse.accessToken,
     refreshToken: tokenResponse.refreshToken,
     expiresAt,
@@ -6762,7 +7314,11 @@ async function languagesAction(query, options, deps) {
   requireAuth(deps);
   try {
     const allLanguages = await deps.githitsService.getLanguages();
-    const displayList = query ? filterLanguages(allLanguages, query) : allLanguages.map(({ name, display_name }) => ({ name, display_name }));
+    const displayList = query ? filterLanguages(allLanguages, query) : allLanguages.map(({ name, display_name, aliases }) => ({
+      name,
+      display_name,
+      aliases
+    }));
     if (options.json) {
       console.log(JSON.stringify(displayList));
     } else if (query && displayList.length === 0) {
@@ -6803,17 +7359,7 @@ function registerLanguagesCommand(program) {
 async function logoutAction(deps) {
   const { authStorage, mcpUrl } = deps;
   const auth = await authStorage.loadTokens(mcpUrl);
-  let firstError;
-  try {
-    await authStorage.clearTokens(mcpUrl);
-  } catch (error2) {
-    firstError = error2;
-  }
-  try {
-    await authStorage.clearClient(mcpUrl);
-  } catch (error2) {
-    firstError ??= error2;
-  }
+  await authStorage.clearAuthSession(mcpUrl);
   if (!auth) {
     console.log(`Not currently logged in.
 `);
@@ -6823,8 +7369,6 @@ async function logoutAction(deps) {
 `);
     console.log(`  Environment: ${mcpUrl}`);
   }
-  if (firstError)
-    throw firstError;
 }
 var LOGOUT_DESCRIPTION = `Remove stored credentials.
 
@@ -6870,8 +7414,9 @@ function classify3(operation, error2) {
   if (error2 instanceof AuthenticationError) {
     return {
       error: error2.message,
-      code: "UNAUTHENTICATED",
-      retryable: false
+      code: "AUTH_REQUIRED",
+      retryable: false,
+      details: { action: "Run `githits login`, then retry this tool call." }
     };
   }
   const message = error2 instanceof Error ? error2.message : "Unknown error";
@@ -6913,11 +7458,12 @@ 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).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.")
+  license_mode: z2.enum(["strict", "yolo", "custom"]).optional().describe("License filtering mode: strict (default), yolo, or custom."),
+  format: z2.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` returns markdown directly with a trailing `solution_id` line when available. Pass `json` for `{result, solution_id?}`.")
 };
 var DESCRIPTION2 = `Get verified, canonical code examples from global open source.
 
-Returns JSON \`{result, solution_id?}\`. \`result\` is markdown — render or quote it directly. Pass \`solution_id\` to \`feedback\` after using or rejecting the example. For searching indexed dependency and repository code/docs, use the unified \`search\` tool instead.`;
+Default output is markdown, with a trailing \`solution_id: ...\` line when available. Pass \`format: "json"\` for \`{result, solution_id?}\`. Pass \`solution_id\` to \`feedback\` after using or rejecting the example. For searching indexed dependency and repository code/docs, use the unified \`search\` tool instead.`;
 function createGetExampleTool(service) {
   return {
     name: "get_example",
@@ -6933,17 +7479,25 @@ function createGetExampleTool(service) {
         });
         const solutionId = extractSolutionId(markdown);
         const payload = solutionId ? { result: markdown, solution_id: solutionId } : { result: markdown };
+        if (isTextFormat(args.format)) {
+          return textResult(solutionId ? `${markdown.trimEnd()}
+
+solution_id: ${solutionId}` : markdown);
+        }
         return textResult(JSON.stringify(payload));
       });
     }
   };
 }
+function isTextFormat(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/grep-repo.ts
 import { z as z4 } from "zod";
 
 // src/tools/code-navigation-shared.ts
 import { z as z3 } from "zod";
-var codeTargetSchema = z3.object({
+var structuredCodeTargetSchema = z3.object({
   registry: z3.enum([
     "npm",
     "pypi",
@@ -6960,7 +7514,18 @@ var codeTargetSchema = z3.object({
   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. Use HEAD for latest.")
 }).describe("Target: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).");
+var codeTargetSchema = z3.union([
+  structuredCodeTargetSchema,
+  z3.string().min(1).describe("Compact target string. Package: `npm:react@18.2.0`. Repository: `https://github.com/facebook/react#HEAD` (git ref suffix optional, defaults to HEAD).")
+]);
 function resolveCodeTarget(target) {
+  if (typeof target === "string") {
+    try {
+      return parseCodeNavigationTargetSpec(target);
+    } catch (error2) {
+      return mappedInvalidTargetResult(error2);
+    }
+  }
   const hasPackageTarget = Boolean(target.registry || target.package_name);
   const hasRepoTarget = Boolean(target.repo_url || target.git_ref);
   if (hasPackageTarget && hasRepoTarget) {
@@ -6993,6 +7558,15 @@ function resolveCodeTarget(target) {
     gitRef: target.git_ref
   };
 }
+function mappedInvalidTargetResult(error2) {
+  const mapped = mapCodeNavigationError(error2);
+  return errorResult(JSON.stringify({
+    error: mapped.message,
+    code: mapped.code,
+    retryable: mapped.retryable ?? false,
+    ...mapped.details ? { details: mapped.details } : {}
+  }));
+}
 function invalidTargetResult(message) {
   return errorResult(JSON.stringify({
     error: message,
@@ -7079,7 +7653,7 @@ function createGrepRepoTool(service) {
           excludeTestFiles: build.params.excludeTestFiles,
           explicit: build.explicit
         });
-        if (isTextFormat(args.format)) {
+        if (isTextFormat2(args.format)) {
           return textResult(renderGrepRepoText(payload));
         }
         return textResult(JSON.stringify(payload));
@@ -7095,19 +7669,30 @@ function createGrepRepoTool(service) {
     }
   };
 }
-function isTextFormat(format) {
+function isTextFormat2(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."),
+  path: z5.string().optional().describe("Exact target-relative file path to include. When combined with `path_prefix` or `globs`, files matching any selector are returned."),
+  path_prefix: z5.string().optional().describe("Literal directory prefix to filter by (e.g. `src/` or `lib/parser`). NOT a glob. OR-ed with `path` and `globs` when combined."),
+  globs: z5.array(z5.string()).optional().describe("Repeatable glob selectors with real glob semantics (e.g. `src/**/*.ts`). OR-ed with `path` and `path_prefix`."),
+  extensions: z5.array(z5.string()).optional().describe("File extensions to include, without a leading dot."),
+  file_types: z5.array(z5.string()).optional().describe("File type filters to include, matching aigrep file_type values such as `source` or `doc`."),
+  languages: z5.array(z5.string()).optional().describe("Language filters to include, matching aigrep language names."),
+  file_intent: z5.string().optional().describe(`Single inclusive file-intent filter. Cannot be combined with \`file_intents\`. Valid values: ${knownFileIntentList().join(", ")}.`),
+  file_intents: z5.array(z5.string()).optional().describe(`Inclusive file-intent filters. Cannot be combined with \`file_intent\`. Valid values: ${knownFileIntentList().join(", ")}.`),
+  exclude_file_intents: z5.array(z5.string()).optional().describe(`Exclude these file intents after inclusive intent filtering. Valid values: ${knownFileIntentList().join(", ")}.`),
+  exclude_doc_files: z5.boolean().optional(),
+  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`."),
   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. 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`.";
+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. Narrow with `path`, `path_prefix`, `globs`, " + "`extensions`, `file_types`, `languages`, or file-intent 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",
@@ -7121,7 +7706,18 @@ function createListFilesTool(service) {
       try {
         const build = buildListFilesParams({
           target,
+          path: args.path,
           pathPrefix: args.path_prefix,
+          globs: args.globs,
+          extensions: args.extensions,
+          fileTypes: args.file_types,
+          languages: args.languages,
+          fileIntent: args.file_intent,
+          fileIntents: args.file_intents,
+          excludeFileIntents: args.exclude_file_intents,
+          excludeDocFiles: args.exclude_doc_files,
+          excludeTestFiles: args.exclude_test_files,
+          includeHidden: args.include_hidden,
           limit: args.limit,
           waitTimeoutMs: args.wait_timeout_ms
         });
@@ -7131,12 +7727,22 @@ function createListFilesTool(service) {
           name: target.packageName,
           repoUrl: target.repoUrl,
           gitRef: target.gitRef,
-          limitExplicit: build.limitExplicit,
-          pathPrefixExplicit: build.pathPrefixExplicit,
-          pathPrefix: build.params.pathPrefix,
-          limit: build.params.limit
+          path: build.filterEcho.path,
+          pathPrefix: build.filterEcho.pathPrefix,
+          globs: build.filterEcho.globs,
+          extensions: build.filterEcho.extensions,
+          fileTypes: build.filterEcho.fileTypes,
+          languages: build.filterEcho.languages,
+          fileIntent: build.filterEcho.fileIntent,
+          fileIntents: build.filterEcho.fileIntents,
+          excludeFileIntents: build.filterEcho.excludeFileIntents,
+          excludeDocFiles: build.filterEcho.excludeDocFiles,
+          excludeTestFiles: build.filterEcho.excludeTestFiles,
+          includeHidden: build.filterEcho.includeHidden,
+          limit: build.filterEcho.limit,
+          explicit: build.explicit
         });
-        if (isTextFormat2(args.format)) {
+        if (isTextFormat3(args.format)) {
           return textResult(renderListFilesText(payload));
         }
         return textResult(JSON.stringify(payload));
@@ -7152,7 +7758,7 @@ function createListFilesTool(service) {
     }
   };
 }
-function isTextFormat2(format) {
+function isTextFormat3(format) {
   return format === undefined || format === "text" || format === "text-v1";
 }
 // src/tools/list-package-docs.ts
@@ -7162,7 +7768,8 @@ var schema5 = {
   package_name: z6.string().describe("Package name (scoped names ok: @types/node)."),
   version: z6.string().optional().describe("Optional package version."),
   limit: z6.number().optional().describe("Max pages to return (1-500, default 100)."),
-  after: z6.string().optional().describe("Pagination cursor from a prior response.")
+  after: z6.string().optional().describe("Pagination cursor from a prior response."),
+  format: z6.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact page list with ready-to-call `docs_read` follow-ups. Pass `format: "json"` for the structured envelope.')
 };
 var DESCRIPTION5 = "List mixed package documentation pages from hosted docs and repository-backed docs. " + "Every entry includes a stable `pageId`, `sourceKind` (`crawled` or `repo`), and source URL; repo-backed entries also expose `repoUrl` / `gitRef` / `filePath` for exact file reads. " + "Pass a returned `pageId` to `docs_read`. Use this to browse before reading a full page.";
 function createListPackageDocsTool(service) {
@@ -7187,6 +7794,9 @@ function createListPackageDocsTool(service) {
           limit: build.params.limit,
           after: build.params.after
         });
+        if (isTextFormat4(args.format)) {
+          return textResult(renderListPackageDocsText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7200,6 +7810,9 @@ function createListPackageDocsTool(service) {
     }
   };
 }
+function isTextFormat4(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/package-changelog.ts
 import { z as z7 } from "zod";
 
@@ -7318,17 +7931,15 @@ function buildPackageChangelogSuccessPayload(report, options) {
     }
     return lean;
   });
-  if (report.source == null) {
-    throw new Error("Changelog envelope builder received a null source — should have been promoted to NOT_FOUND at the service boundary.");
-  }
   const envelope = {
-    source: report.source,
     mode: options.mode,
     entries: {
       count: items.length,
       items
     }
   };
+  if (report.source)
+    envelope.source = report.source;
   if (options.registry)
     envelope.registry = options.registry;
   if (options.name)
@@ -7402,12 +8013,12 @@ function appendBodyLines(lines, body, options) {
   }
   const hidden = bodyLines.length - visible.length;
   if (hidden > 0) {
-    lines.push(`  ${dim(`… (+${hidden} more line${hidden === 1 ? "" : "s"} — use --verbose for the full body)`, options.useColors)}`);
+    lines.push(`  ${dim(`… (+${hidden} more line${hidden === 1 ? "" : "s"} — ${options.fullBodyHint ?? "use --verbose for the full body"})`, options.useColors)}`);
   }
 }
 function buildSummaryLine(envelope, options) {
   const identity = envelope.registry && envelope.name ? `${envelope.name} · ${envelope.registry}` : envelope.repoUrl ?? "(unknown)";
-  const sourceLabel = humanizeSource(envelope.source);
+  const sourceLabel = envelope.source ? humanizeSource(envelope.source) : "package versions";
   const modeLabel = envelope.mode === "range" ? rangeLabel(envelope) : latestLabel(envelope);
   const countLabel = `${envelope.entries.count} ${plural2("entry", "entries", envelope.entries.count)}`;
   const parts = [identity, `source: ${sourceLabel}`, modeLabel, countLabel];
@@ -7474,9 +8085,10 @@ var schema6 = {
   to_version: z7.string().optional().describe("End of range / latest-mode cap. Works in either mode. Defaults to latest on the wire. Tag-style `v`-prefixed inputs are rejected."),
   limit: z7.number().optional().describe("Latest-mode cap on entry count (1–50, default 10). Rejected with `INVALID_ARGUMENT` when `from_version` is also set or when out of range."),
   git_ref: z7.string().optional().describe("Git branch or tag for CHANGELOG.md source (no effect on GitHub Releases or HexDocs). Defaults to the repository's default branch."),
-  include_bodies: z7.boolean().optional().describe("When false, each entry in `entries.items[]` omits its `body` field. Default true. Set false when you only need the version / date / URL timeline — drops 10 KB+ per entry on large release notes.")
+  include_bodies: z7.boolean().optional().describe("When false, each entry in `entries.items[]` omits its `body` field. Default true. Set false when you only need the version / date / URL timeline — drops 10 KB+ per entry on large release notes."),
+  format: z7.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
 };
-var DESCRIPTION6 = "Release notes for a package or GitHub repo, newest-first. Default " + "latest mode returns the ten most recent entries (`limit` 1–50). " + "With `from_version`, returns every entry in the " + "`[from_version, to_version]` range (range mode, no count cap). " + "Address via `registry` + `package_name` or `repo_url` (mutually " + 'exclusive). Response: `source` (`"releases"` / `"changelog_file"` ' + '/ `"hexdocs"`), `mode` (`"latest"` or `"range"`), ' + "`entries: { count, items }` with full markdown bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only. " + "Supports npm, PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, " + "Packagist; returns `NOT_FOUND` when a package has no changelog " + "source.";
+var DESCRIPTION6 = "Release notes for a package or GitHub repo, newest-first. Default " + "latest mode returns the ten most recent entries (`limit` 1–50). " + "With `from_version`, returns every entry in the " + "`[from_version, to_version]` range (range mode, no count cap). " + "Address via `registry` + `package_name` or `repo_url` (mutually " + 'exclusive). Response includes optional `source` (`"releases"` / ' + '`"changelog_file"` / `"hexdocs"`) when a concrete changelog source ' + 'exists, `mode` (`"latest"` or `"range"`), ' + 'and entries with markdown body previews. Pass `format: "json"` ' + "for the structured envelope with full markdown bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only. " + "Package-version entries without changelog text succeed with `source` " + "omitted; no-source plus no entries returns `NOT_FOUND`. Supports npm, " + "PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, Packagist.";
 function createPackageChangelogTool(service) {
   return {
     name: "pkg_changelog",
@@ -7507,6 +8119,13 @@ function createPackageChangelogTool(service) {
           limit: params.limit,
           gitRef: params.gitRef
         });
+        if (isTextFormat5(args.format)) {
+          return textResult(formatPackageChangelogTerminal(payload, {
+            useColors: false,
+            verbose: false,
+            fullBodyHint: 'pass format="json" for full bodies'
+          }).trimEnd());
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7528,18 +8147,22 @@ function createPackageChangelogTool(service) {
     }
   };
 }
+function isTextFormat5(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/package-dependencies.ts
 import { z as z8 } from "zod";
 var schema7 = {
   registry: z8.string().describe("Package registry. Dependency data is available on npm, pypi, hex, crates, vcpkg, and zig."),
   package_name: z8.string().describe("Package name (scoped names ok: @types/node)."),
   version: z8.string().optional().describe("Specific version to inspect. Defaults to latest when omitted. Tag-style inputs with a leading `v` (for example `v4.18.0`) are rejected — pass the canonical version (`4.18.0`)."),
-  lifecycle: z8.union([z8.string(), z8.array(z8.string())]).optional().describe('Filter the `groups` block server-side by lifecycle phase. Accepts a single value, a comma-separated string (e.g. `"runtime,development"`), or an array of strings. Canonical values: `runtime`, `development`, `build`, `peer`, `optional`. Uppercase is tolerated. When the filter matches nothing the response still includes `groups: { items: [] }` so you can tell an empty-match apart from a registry that has no groups concept.'),
+  lifecycle: z8.union([z8.string(), z8.array(z8.string())]).optional().describe("Lifecycle breadth. Omit for runtime-only. Use `runtime` for explicit runtime-only, a concrete non-runtime lifecycle (`development`, `build`, `peer`, `optional`) for runtime plus matching groups, or `all` for runtime plus all available groups. Accepts a single value, a comma-separated string, or an array; `all` cannot be combined with other values. Uppercase is tolerated."),
   include_transitive: z8.boolean().optional().describe("When true the response gains a `transitive` block with aggregate counts (`edges`, `uniquePackages`), the preprocessed `packages[]` list (each `{name, version}` — the complete install footprint), plus typed `conflicts[]` (`{name, requiredVersions}`) and `circularDependencies[]` (`{cycle: string[]}`) when the backend reported any. Off by default."),
   include_importers: z8.boolean().optional().describe("Requires `include_transitive: true`. When true, each entry in `transitive.packages[]` also carries an `importers` array — every upstream package that pulls it in, with that importer's own resolved version and the constraint it declared. Off by default because adding provenance roughly quadruples the envelope size on heavy graphs. Turn on when you need to trace why a specific transitive dep is present."),
-  max_depth: z8.number().int().min(1).max(10).optional().describe("Cap the transitive traversal at this depth (1–10). Omit to get the backend's full graph. Requires `include_transitive: true` — passing `max_depth` without the transitive flag is rejected with `INVALID_ARGUMENT`.")
+  max_depth: z8.number().int().min(1).max(10).optional().describe("Cap the transitive traversal at this depth (1–10). Omit to get the backend's full graph. Requires `include_transitive: true` — passing `max_depth` without the transitive flag is rejected with `INVALID_ARGUMENT`."),
+  format: z8.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
 };
-var DESCRIPTION7 = "Analyze a package's dependency graph. The response always includes " + "a `runtime` block listing the direct runtime dependencies as " + "`{name, version, constraint}` records (the backend resolves each " + "constraint to a concrete version for you). It also always includes " + "a structured `groups` block whenever the backend returns group " + "metadata — one group per lifecycle (`runtime`, `development`, " + "`build`, `peer`, `optional`) plus feature-conditional groups for " + "registries that have them (PyPI extras, Crates features). Use " + "`lifecycle` to filter `groups` server-side. Set " + "`include_transitive: true` to add a `transitive` block with the " + "full install footprint, conflict detection, and circular-" + "dependency flags; layer `include_importers: true` on top when you " + "also need per-package provenance. Supports npm, PyPI, Hex, Crates, " + "vcpkg, and Zig.";
+var DESCRIPTION7 = "Analyze a package's dependency graph. Default output is compact " + "text listing direct runtime dependencies with resolved versions; " + 'pass `format: "json"` for the structured envelope. Non-runtime ' + "groups are omitted by default for token efficiency. Use `lifecycle` " + "with a concrete value for runtime plus matching groups, or `all` " + "for runtime plus all available groups. Set " + "`include_transitive: true` to add a `transitive` block with the " + "full install footprint, conflict detection, and circular-" + "dependency flags; layer `include_importers: true` on top when you " + "also need per-package provenance. Supports npm, PyPI, Hex, Crates, " + "vcpkg, and Zig.";
 function createPackageDependenciesTool(service) {
   return {
     name: "pkg_deps",
@@ -7571,6 +8194,18 @@ function createPackageDependenciesTool(service) {
           maxDepth: args.max_depth,
           includeImporters: args.include_importers ?? false
         });
+        if (isTextFormat6(args.format)) {
+          const textLifecycles = canonicalLifecycles.length > 0 ? canonicalLifecycles : ["all"];
+          return textResult(formatPackageDependenciesTerminal(report, {
+            useColors: false,
+            requestedVersion: args.version,
+            canonicalLifecycles: textLifecycles,
+            includeTransitive: args.include_transitive,
+            maxDepth: args.max_depth,
+            showGroups: canonicalLifecycles.length > 0 && !canonicalLifecycles.every((item) => item === "runtime"),
+            hiddenGroupsHint: 'pass lifecycle="all".'
+          }).trimEnd());
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7592,13 +8227,17 @@ function createPackageDependenciesTool(service) {
     }
   };
 }
+function isTextFormat6(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/package-summary.ts
 import { z as z9 } from "zod";
 var schema8 = {
   registry: z9.string().describe("Package registry. One of: npm, pypi, hex, crates, nuget, maven, zig, vcpkg, packagist."),
-  package_name: z9.string().describe("Package name (scoped names ok: @types/node).")
+  package_name: z9.string().describe("Package name (scoped names ok: @types/node)."),
+  format: z9.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
 };
-var DESCRIPTION8 = "Get a package overview — latest version, license, description, " + "repository, downloads, GitHub stars, install command, recent " + "changes, and a count of known vulnerabilities. Use before " + "recommending a package or to orient on what a dependency is. " + "Works across npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, " + "vcpkg, and Zig. Always returns data for the latest published " + "version.";
+var DESCRIPTION8 = "Get a package overview — latest version, license, description, " + "repository, downloads, GitHub stars, install command, recent " + "changes, and a count of known vulnerabilities. Use before " + "recommending a package or to orient on what a dependency is. " + 'Default output is compact text; pass `format: "json"` for the ' + "structured envelope. " + "Works across npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, " + "vcpkg, and Zig. Always returns data for the latest published " + "version.";
 function createPackageSummaryTool(service) {
   return {
     name: "pkg_info",
@@ -7613,6 +8252,11 @@ function createPackageSummaryTool(service) {
         });
         const summary = await service.packageSummary(params);
         const payload = buildPackageSummarySuccessPayload(summary);
+        if (isTextFormat7(args.format)) {
+          return textResult(formatPackageSummaryTerminal(summary, {
+            useColors: false
+          }).trimEnd());
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7634,6 +8278,9 @@ function createPackageSummaryTool(service) {
     }
   };
 }
+function isTextFormat7(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/package-vulnerabilities.ts
 import { z as z10 } from "zod";
 var schema9 = {
@@ -7641,9 +8288,10 @@ var schema9 = {
   package_name: z10.string().describe("Package name (scoped names ok: @types/node)."),
   version: z10.string().optional().describe("Specific version to check. Defaults to latest when omitted."),
   min_severity: z10.string().optional().describe("Only return advisories at or above this severity (`low`, `medium`, `high`, `critical`; uppercase tolerated). Omit to see all, including null-severity advisories."),
-  include_withdrawn: z10.boolean().optional().describe("Include retracted advisories (default: false).")
+  include_withdrawn: z10.boolean().optional().describe("Include retracted advisories (default: false)."),
+  format: z10.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
 };
-var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories.";
+var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories. Default output is compact text; " + 'pass `format: "json"` for the structured envelope.';
 function createPackageVulnerabilitiesTool(service) {
   return {
     name: "pkg_vulns",
@@ -7663,6 +8311,12 @@ function createPackageVulnerabilitiesTool(service) {
         const payload = buildPackageVulnerabilitiesSuccessPayload(report, {
           requestedVersion: args.version
         });
+        if (isTextFormat8(args.format)) {
+          return textResult(formatPackageVulnerabilitiesTerminal(report, {
+            useColors: false,
+            requestedVersion: args.version
+          }).trimEnd());
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7684,6 +8338,9 @@ function createPackageVulnerabilitiesTool(service) {
     }
   };
 }
+function isTextFormat8(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/tools/read-file.ts
 import { z as z11 } from "zod";
 var MCP_READ_MAX_SPAN = 150;
@@ -7692,7 +8349,8 @@ var schema10 = {
   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 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`.")
+  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`."),
+  format: z11.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — line-numbered source content. Pass `format: "json"` for the structured envelope.')
 };
 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) {
@@ -7744,6 +8402,9 @@ function createReadFileTool(service) {
         if (shouldEmitCappedHint(bounded, payload)) {
           payload.hint = buildCappedHint(payload, args.start_line, args.end_line);
         }
+        if (isTextFormat9(args.format)) {
+          return textResult(renderReadFileText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapCodeNavigationError(error2);
@@ -7757,6 +8418,9 @@ function createReadFileTool(service) {
     }
   };
 }
+function isTextFormat9(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 function shouldEmitCappedHint(bounded, payload) {
   if (!bounded.capped)
     return false;
@@ -7786,10 +8450,12 @@ function describeRequest(originalStart, originalEnd) {
 }
 // src/tools/read-package-doc.ts
 import { z as z12 } from "zod";
+var MCP_DOC_READ_MAX_SPAN = 150;
 var schema11 = {
   page_id: z12.string().describe("Documentation page ID from `docs_list` or `search` results. Pass through unchanged; repo-backed IDs are snapshot-pinned."),
   start_line: z12.number().optional().describe("Starting line (1-indexed). Omit for the full page. Use with `end_line` to bound how much content the tool returns when a page is large."),
-  end_line: z12.number().optional().describe("Ending line (inclusive). Omit for end of page. Must be ≥ `start_line` when both are set.")
+  end_line: z12.number().optional().describe("Ending line (inclusive). Omit for end of page. Must be ≥ `start_line` when both are set."),
+  format: z12.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — raw markdown content capped to 150 lines by default. Pass `format: "json"` for the structured envelope; explicit ranges still slice JSON content.')
 };
 var DESCRIPTION11 = "Read a documentation page by page ID. Works for both hosted/crawled docs and repository-backed docs. " + "Pass `start_line` / `end_line` to fetch only a slice when a page is too long — response carries `totalLines` so you can target the next slice. " + "Repo-backed results additionally include exact file follow-up metadata for `code_read`.";
 function createReadPackageDocTool(service) {
@@ -7802,8 +8468,14 @@ function createReadPackageDocTool(service) {
       try {
         const build = buildReadPackageDocParams({ pageId: args.page_id });
         const result = await service.readPackageDoc(build.params);
-        const range = args.start_line !== undefined || args.end_line !== undefined ? { startLine: args.start_line, endLine: args.end_line } : undefined;
-        const payload = buildReadPackageDocSuccessPayload(result, build.params.pageId, range);
+        const textMode = isTextFormat10(args.format);
+        const range = buildRange3(args, textMode);
+        const payload = buildReadPackageDocSuccessPayload(result, build.params.pageId, range?.range);
+        if (range?.hint && payload.endLine !== undefined) {
+          payload.hint = range.hint(payload);
+        }
+        if (textMode)
+          return textResult(renderReadPackageDocText(payload));
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const mapped = mapPackageIntelligenceError(error2);
@@ -7817,6 +8489,22 @@ function createReadPackageDocTool(service) {
     }
   };
 }
+function isTextFormat10(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
+function buildRange3(args, textMode) {
+  if (textMode) {
+    const startLine = args.start_line ?? 1;
+    const requestedEnd = args.end_line ?? startLine + MCP_DOC_READ_MAX_SPAN - 1;
+    const endLine = Math.min(requestedEnd, startLine + MCP_DOC_READ_MAX_SPAN - 1);
+    const wasClamped = requestedEnd > endLine;
+    return {
+      range: { startLine, endLine },
+      hint: wasClamped ? (payload) => `Returned lines ${payload.startLine}-${payload.endLine}${payload.totalLines !== undefined ? `/${payload.totalLines}` : ""} (MCP text cap: ${MCP_DOC_READ_MAX_SPAN} lines per call; you requested lines ${startLine}-${requestedEnd}).` : undefined
+    };
+  }
+  return args.start_line !== undefined || args.end_line !== undefined ? { range: { startLine: args.start_line, endLine: args.end_line } } : undefined;
+}
 // src/tools/search.ts
 import { z as z13 } from "zod";
 var schema12 = {
@@ -7911,13 +8599,13 @@ function createSearchTool(service) {
         });
         const outcome = await service.search(built.params);
         const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
-        if (isTextFormat3(args.format)) {
+        if (isTextFormat11(args.format)) {
           return textResult(renderUnifiedSearchSuccess(payload));
         }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         const payload = buildUnifiedSearchErrorPayload(error2);
-        if (isTextFormat3(args.format)) {
+        if (isTextFormat11(args.format)) {
           return errorResult(renderUnifiedSearchError(payload));
         }
         return errorResult(JSON.stringify(payload));
@@ -7928,15 +8616,16 @@ function createSearchTool(service) {
 function isResolvedCodeTarget(target) {
   return !("content" in target);
 }
-function isTextFormat3(format) {
+function isTextFormat11(format) {
   return format === undefined || format === "text" || format === "text-v1";
 }
 // src/tools/search-language.ts
 import { z as z14 } from "zod";
 var schema13 = {
-  query: z14.string().min(1).describe('Language name or partial name to search for (e.g., "python", "type", "java")')
+  query: z14.string().min(1).describe('Language name or partial name to search for (e.g., "python", "type", "java")'),
+  format: z14.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` returns one language per line. Pass `json` for the structured array.")
 };
-var DESCRIPTION13 = `Find the correct language name for \`get_example\` when it is uncertain. Returns up to 5 matching languages by name, display name, or alias.`;
+var DESCRIPTION13 = `Find the correct language name for \`get_example\` when it is uncertain. Returns up to 5 matching languages by name, display name, or alias. Default output is one language per line; pass \`format: "json"\` for the structured array.`;
 function createSearchLanguageTool(service) {
   return {
     name: "search_language",
@@ -7946,15 +8635,32 @@ function createSearchLanguageTool(service) {
       return withErrorHandling("search languages", async () => {
         const allLanguages = await service.getLanguages();
         const result = filterLanguages(allLanguages, args.query);
+        if (isTextFormat12(args.format)) {
+          return textResult(renderLanguageMatches(result));
+        }
         return textResult(JSON.stringify(result));
       });
     }
   };
 }
+function isTextFormat12(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
+function renderLanguageMatches(matches) {
+  if (matches.length === 0)
+    return "No matching languages.";
+  return matches.map((match) => {
+    const label = match.display_name ? `${match.name} (${match.display_name})` : match.name;
+    const aliases = match.aliases?.length ? ` aliases: ${match.aliases.join(", ")}` : "";
+    return `${label}${aliases}`;
+  }).join(`
+`);
+}
 // src/tools/search-status.ts
 import { z as z15 } from "zod";
 var schema14 = {
-  search_ref: z15.string().min(1).describe("Search reference returned by search.")
+  search_ref: z15.string().min(1).describe("Search reference returned by search."),
+  format: z15.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output matching `search`. Pass `format: "json"` for the structured envelope.')
 };
 var DESCRIPTION14 = "Check progress, fetch partial hits when the original request used allow_partial_results: true, or fetch final results for a prior unified search. " + "Pass the search_ref returned by `search` when the original request did not complete within the wait window.";
 function createSearchStatusTool(service) {
@@ -7967,6 +8673,9 @@ function createSearchStatusTool(service) {
       try {
         const outcome = await service.searchStatus(args.search_ref);
         const payload = buildUnifiedSearchStatusPayload(outcome);
+        if (isTextFormat13(args.format)) {
+          return textResult(renderUnifiedSearchStatusText(payload));
+        }
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         return errorResult(JSON.stringify(buildUnifiedSearchErrorPayload(error2)));
@@ -7974,25 +8683,28 @@ function createSearchStatusTool(service) {
     }
   };
 }
+function isTextFormat13(format) {
+  return format === undefined || format === "text" || format === "text-v1";
+}
 // src/commands/mcp-instructions.ts
-var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source. Use it when you're stuck, repeated attempts failed, 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.
+var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source. Use it for global solution synthesis and canonical examples when you're stuck, repeated attempts failed, 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.
 
-Example workflow: call \`get_example\` with one focused question; pass \`language\` only when you know the exact language name, otherwise call \`search_language\` first. Send \`feedback\` on the returned solution_id. Reuse prior results before searching again.`;
+Example workflow: call \`get_example\` with one focused question; pass \`language\` only when you know the exact language name, otherwise call \`search_language\` first. Default output is markdown with a trailing \`solution_id\`; send \`feedback\` on that solution_id. Reuse prior results before searching again. For dependency-specific grounding, use 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.
 
-Package spec: \`registry:name[@version]\`.`;
-var PKG_INFO_BULLET = "- `pkg_info` — instant package overview: latest version, license, downloads, quickstart, and active advisory count.";
+Package spec: \`registry:name[@version]\`. Default outputs are compact \`text-v1\` for agent context efficiency; pass \`format: "json"\` only when you need structured fields for programmatic parsing.`;
+var PKG_INFO_BULLET = '- `pkg_info` — compact package overview: latest version, license, downloads, quickstart, and active advisory count. Pass `format: "json"` for the structured envelope.';
 var DOCS_LIST_BULLET = "- `docs_list` — browse hosted and repository-backed package docs. Entries include stable pageIds, source URLs, and repo-file follow-up metadata when available.";
 var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. Works for both hosted docs and repo-backed docs.";
-var PKG_VULNS_BULLET = "- `pkg_vulns` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages, optionally pinned to `@version`. Filter with `min_severity`; include retracted advisories with `include_withdrawn`.";
-var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus lifecycle/feature groups when available. Use `lifecycle` to filter groups, `include_transitive` for the full graph, and `include_importers` for 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 recent entries with markdown bodies; `from_version` switches to range mode. Set `include_bodies: false` for a compact timeline.";
-var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and symbols. Omit `sources` for AUTO. Default output is compact `text-v1`; pass `format: "json"` for locators, highlights, and source status. Complete by default; opt into partial hits with `allow_partial_results: true`. Incomplete responses carry a `searchRef`.';
+var PKG_VULNS_BULLET = '- `pkg_vulns` — compact known CVE / OSV advisory summary for npm, PyPI, Hex, or Crates packages, optionally pinned to `version`. Filter with `min_severity`; include retracted advisories with `include_withdrawn`. Pass `format: "json"` for per-advisory structured fields.';
+var PKG_DEPS_BULLET = '- `pkg_deps` — compact direct runtime deps by default. Use `lifecycle: "runtime"` for explicit runtime-only, a concrete lifecycle for runtime plus matching non-runtime deps, or `lifecycle: "all"` for all groups. Use `include_transitive` for the full graph and `include_importers` for provenance. Pass `format: "json"` for the structured envelope.';
+var PKG_CHANGELOG_BULLET = '- `pkg_changelog` — compact release notes for a package or GitHub repo, newest-first. Default latest mode returns recent entries with markdown body previews; `from_version` switches to range mode. Set `include_bodies: false` for a compact timeline or pass `format: "json"` for full bodies.';
+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.";
-var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. Use `path_prefix` to scope to a directory. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
+var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. `path`, `path_prefix`, and `globs` are OR-ed selectors; extensions, language, file type, and file-intent filters intersect on top. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
 var CODE_READ_BULLET = "- `code_read` — read a dependency file by `path`. **MCP cap: 150 lines per call**; choose focused `start_line` / `end_line` windows from `search` or `code_grep`. Binary files set `isBinary: true` and omit `content`. On `FILE_NOT_FOUND` / `NOT_FOUND`, call `code_files` for the actual path.";
 var CODE_GREP_BULLET = "- `code_grep` — deterministic text or regex grep over indexed source. Use it when you know the pattern; use `search` for discovery. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. Each match's `path:line` chains 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 SEARCH_VS_SYMBOLS_TIP = 'Use code-first grounding for behavioral claims: source, symbols, tests, examples, and call sites beat docs prose. Prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Prefer `get_example` for global canonical example retrieval after package-scoped grounding. 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 needed window with `code_read` using explicit `start_line` / `end_line` values, typically 80-150 lines around the match. The MCP `code_read` surface caps each call at 150 lines.";
 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.';
 function buildMcpInstructions(_deps) {
@@ -8283,12 +8995,12 @@ async function pkgDepsAction(spec, options, deps) {
       console.log(JSON.stringify(payload));
       return;
     }
-    const showGroups = (options.groups ?? false) || canonicalLifecycles.length > 0;
+    const showGroups = canonicalLifecycles.some((entry) => entry !== "runtime");
     const output = formatPackageDependenciesTerminal(report, {
       verbose: options.verbose,
       useColors: shouldUseColors(),
       requestedVersion: parsed.version,
-      canonicalLifecycles,
+      canonicalLifecycles: canonicalLifecycles.length > 0 ? canonicalLifecycles : undefined,
       includeTransitive: options.transitive,
       maxDepth: userDepth,
       showGroups
@@ -8350,9 +9062,9 @@ function formatDepsTerminalError(mapped) {
 `);
 }
 var PKG_DEPS_DESCRIPTION = `Analyze package dependencies. By default shows the flat list of
-direct runtime dependencies. Use --groups for the structured view
+direct runtime dependencies. Use --lifecycle all for the structured view
 (dev / peer / build / optional, plus registry-specific feature / TFM
-groups). --lifecycle filters groups server-side and implies --groups.
+groups). Concrete --lifecycle values include runtime plus matching groups.
 --transitive opts into aggregate edge / unique-package counts,
 conflict detection, and circular-dependency flags.
 
@@ -8360,7 +9072,7 @@ Package spec: <registry>:<name>[@<version>]. Supported registries:
 npm, pypi, hex, crates, vcpkg, zig. Omit @<version> for the latest
 release.`;
 function registerPkgDepsCommand(pkgCommand) {
-  return pkgCommand.command("deps").summary("Analyze dependencies for a package").description(PKG_DEPS_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or npm:express@4.18.0").option("-g, --groups", "Render the structured groups view instead of the flat runtime list").option("-l, --lifecycle <phases>", "Filter groups server-side (runtime, development, build, peer, optional; comma-separated for multi-select). Implies --groups.").option("-t, --transitive", "Include aggregate transitive counts, conflicts, and circular dependencies").option("--depth <n>", "Cap transitive traversal depth (1-10). Omit for the full graph.").option("-v, --verbose", "Show conditionType / selectionMode / environmentConstraints metadata in the groups view").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
+  return pkgCommand.command("deps").summary("Analyze dependencies for a package").description(PKG_DEPS_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or npm:express@4.18.0").option("-l, --lifecycle <phases>", "Dependency lifecycle breadth (runtime, development, build, peer, optional, all; comma-separated for multi-select except all).").option("-t, --transitive", "Include aggregate transitive counts, conflicts, and circular dependencies").option("--depth <n>", "Cap transitive traversal depth (1-10). Omit for the full graph.").option("-v, --verbose", "Show conditionType / selectionMode / environmentConstraints metadata in the groups view").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
     const deps = await createContainer();
     await pkgDepsAction(spec, options, {
       packageIntelligenceService: deps.packageIntelligenceService,
@@ -8629,7 +9341,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]", collectRepeatable2, []).addOption(new Option3("--source <source>", "Source to search (repeatable; default: auto)").choices(["docs", "code", "symbol"]).argParser((value, previous = []) => collectRepeatable2(value.toLowerCase(), previous)).default(undefined)).addOption(new Option3("--kind <kind>", "Precise symbol kind filter").choices([
+  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([
     ...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",
@@ -8663,7 +9375,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-1gqfte6e.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-rwcs5gyy.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {
@@ -8720,7 +9432,7 @@ function parseWaitMs(value) {
   }
   return seconds * 1000;
 }
-function collectRepeatable2(value, previous) {
+function collectRepeatable3(value, previous) {
   return [...previous, value];
 }
 function handleSearchError(error2, json, context = "search") {
@@ -9072,15 +9784,10 @@ registerAuthStatusCommand(authCommand);
 try {
   await runWithUpdateCheckFlush(() => withTelemetrySpan("cli.parse", () => program.parseAsync()), updateCheckTask, { stderr: process.stderr, requiredUpdateRefreshTask });
 } catch (error2) {
-  if (isUserFacingError(error2)) {
-    console.error(`${error2.message}
-`);
-    process.exit(1);
-  }
-  throw error2;
-}
-function isUserFacingError(error2) {
-  return error2 instanceof AuthConfigError || error2 instanceof AuthStoragePolicyError;
+  handleCliError(error2, {
+    stderr: process.stderr,
+    exit: process.exit
+  });
 }
 function stripRootRegistrationOptions(args) {
   return args.filter((arg) => arg !== "--no-color");