@pkgseer/cli 0.4.10 → 0.5.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-5nhq42tx.js";
+} from "./shared/chunk-kh5enjt9.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -315,13 +315,17 @@ var SearchResultsDocument = gql`
 }
     `;
 var FetchCodeContextDocument = gql`
-    query FetchCodeContext($repoUrl: String!, $gitRef: String!, $filePath: String!, $startLine: Int, $endLine: Int) {
+    query FetchCodeContext($repoUrl: String, $gitRef: String, $registry: Registry, $packageName: String, $version: String, $filePath: String!, $startLine: Int, $endLine: Int, $waitTimeoutMs: Int) {
   fetchCodeContext(
     repoUrl: $repoUrl
     gitRef: $gitRef
+    registry: $registry
+    packageName: $packageName
+    version: $version
     filePath: $filePath
     startLine: $startLine
     endLine: $endLine
+    waitTimeoutMs: $waitTimeoutMs
   ) {
     content
     filePath
@@ -656,10 +660,12 @@ var SearchPackageDocsDocument = gql`
 }
     `;
 var FindSymbolDocument = gql`
-    query FindSymbol($registry: Registry!, $packageName: String!, $name: String, $namespace: String, $kind: SymbolKind, $publicOnly: Boolean, $version: String, $includeCode: Boolean, $contextLines: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query FindSymbol($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $name: String, $namespace: String, $kind: SymbolKind, $publicOnly: Boolean, $version: String, $includeCode: Boolean, $contextLines: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   findSymbol(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     name: $name
     namespace: $namespace
     kind: $kind
@@ -697,10 +703,12 @@ var FindSymbolDocument = gql`
 }
     `;
 var SearchSymbolsDocument = gql`
-    query SearchSymbols($registry: Registry!, $packageName: String!, $query: String, $keywords: [String!], $matchMode: MatchMode, $kind: SymbolKind, $filePath: String, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query SearchSymbols($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $query: String, $keywords: [String!], $matchMode: MatchMode, $kind: SymbolKind, $filePath: String, $version: String, $limit: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   searchSymbols(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     query: $query
     keywords: $keywords
     matchMode: $matchMode
@@ -743,10 +751,12 @@ var SearchSymbolsDocument = gql`
 }
     `;
 var ListSymbolsDocument = gql`
-    query ListSymbols($registry: Registry!, $packageName: String!, $scope: ListScope!, $filePath: String, $namespace: String, $publicOnly: Boolean, $includePopularity: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query ListSymbols($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $scope: ListScope!, $filePath: String, $namespace: String, $publicOnly: Boolean, $includePopularity: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
   listSymbols(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     scope: $scope
     filePath: $filePath
     namespace: $namespace
@@ -848,10 +858,12 @@ var SymbolDependentsDocument = gql`
 }
     `;
 var PackageImportsDocument = gql`
-    query PackageImports($registry: Registry!, $packageName: String!, $filePath: String, $resolvedOnly: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query PackageImports($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $filePath: String, $resolvedOnly: Boolean, $limit: Int, $version: String, $mode: NavigationMode, $waitTimeoutMs: Int) {
   packageImports(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     filePath: $filePath
     resolvedOnly: $resolvedOnly
     limit: $limit
@@ -941,10 +953,12 @@ var SearchProjectDocsDocument = gql`
 }
     `;
 var ListRepoFilesDocument = gql`
-    query ListRepoFiles($registry: Registry!, $packageName: String!, $version: String, $pathPrefix: String, $limit: Int, $waitTimeoutMs: Int) {
+    query ListRepoFiles($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $version: String, $pathPrefix: String, $limit: Int, $waitTimeoutMs: Int) {
   listRepoFiles(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     version: $version
     pathPrefix: $pathPrefix
     limit: $limit
@@ -971,10 +985,12 @@ var ListRepoFilesDocument = gql`
 }
     `;
 var GrepRepoFileDocument = gql`
-    query GrepRepoFile($registry: Registry!, $packageName: String!, $filePath: String!, $pattern: String!, $contextLines: Int, $maxMatches: Int, $version: String, $waitTimeoutMs: Int) {
+    query GrepRepoFile($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $filePath: String!, $pattern: String!, $contextLines: Int, $maxMatches: Int, $version: String, $waitTimeoutMs: Int) {
   grepRepoFile(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     filePath: $filePath
     pattern: $pattern
     contextLines: $contextLines
@@ -1005,10 +1021,12 @@ var GrepRepoFileDocument = gql`
 }
     `;
 var VersionDiffDocument = gql`
-    query VersionDiff($registry: Registry!, $packageName: String!, $fromVersion: String!, $toVersion: String!, $includePrivate: Boolean, $kind: SymbolKind, $limit: Int, $waitTimeoutMs: Int) {
+    query VersionDiff($registry: Registry, $packageName: String, $repoUrl: String, $gitRef: String, $fromVersion: String!, $toVersion: String!, $includePrivate: Boolean, $kind: SymbolKind, $limit: Int, $waitTimeoutMs: Int) {
   versionDiff(
     registry: $registry
     packageName: $packageName
+    repoUrl: $repoUrl
+    gitRef: $gitRef
     fromVersion: $fromVersion
     toVersion: $toVersion
     includePrivate: $includePrivate
@@ -1641,20 +1659,26 @@ var TOOL_NAMES = [
   "fetch_package_doc",
   "search",
   "search_status",
-  "fetch_code_context",
+  "read_file",
   "search_project_docs",
+  "list_files",
+  "grep_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
   "symbol_callers",
   "symbol_callees",
-  "package_imports",
+  "list_imports",
   "call_path",
   "trigger_indexing",
-  "list_repo_files",
-  "grep_repo_file",
   "version_diff"
 ];
+var TOOL_NAME_MIGRATION = {
+  fetch_code_context: "read_file",
+  list_package_files: "list_files",
+  grep_package_file: "grep_file",
+  package_imports: "list_imports"
+};
 var ToolNameSchema = z.enum(TOOL_NAMES);
 var SharedConfigFields = {
   enabled_tools: z.array(ToolNameSchema).optional()
@@ -1762,6 +1786,24 @@ class ConfigServiceImpl {
       if (parsed === null || parsed === undefined) {
         return schema.parse({});
       }
+      if (parsed && typeof parsed === "object" && Array.isArray(parsed.enabled_tools)) {
+        const migrated = [];
+        let hasMigrations = false;
+        for (const name of parsed.enabled_tools) {
+          const replacement = TOOL_NAME_MIGRATION[name];
+          if (replacement) {
+            migrated.push(replacement);
+            hasMigrations = true;
+          } else {
+            migrated.push(name);
+          }
+        }
+        if (hasMigrations) {
+          const oldNames = parsed.enabled_tools.filter((n) => TOOL_NAME_MIGRATION[n]);
+          console.warn(`[pkgseer] Config at ${path}: migrating deprecated tool names: ${oldNames.join(", ")}. Update your config to use the new names.`);
+          parsed.enabled_tools = migrated;
+        }
+      }
       const result = schema.safeParse(parsed);
       if (result.success) {
         return result.data;
@@ -2207,9 +2249,13 @@ class PkgseerServiceImpl {
     const result = await this.client.FetchCodeContext({
       repoUrl,
       gitRef,
+      registry: options?.registry,
+      packageName: options?.packageName,
+      version: options?.version,
       filePath,
       startLine: options?.startLine,
-      endLine: options?.endLine
+      endLine: options?.endLine,
+      waitTimeoutMs: options?.waitTimeoutMs
     });
     return { data: result.data, errors: result.errors };
   }
@@ -2217,6 +2263,8 @@ class PkgseerServiceImpl {
     const result = await this.client.FindSymbol({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       name: options?.name,
       namespace: options?.namespace,
       kind: options?.kind,
@@ -2233,6 +2281,8 @@ class PkgseerServiceImpl {
     const result = await this.client.SearchSymbols({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       query: options?.query,
       keywords: options?.keywords,
       matchMode: options?.matchMode,
@@ -2249,6 +2299,8 @@ class PkgseerServiceImpl {
     const result = await this.client.ListSymbols({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       scope,
       filePath: options?.filePath,
       namespace: options?.namespace,
@@ -2289,6 +2341,8 @@ class PkgseerServiceImpl {
     const result = await this.client.PackageImports({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       filePath: options?.filePath,
       resolvedOnly: options?.resolvedOnly,
       limit: options?.limit,
@@ -2312,6 +2366,8 @@ class PkgseerServiceImpl {
     const result = await this.client.ListRepoFiles({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       version: options?.version,
       pathPrefix: options?.pathPrefix,
       limit: options?.limit,
@@ -2323,6 +2379,8 @@ class PkgseerServiceImpl {
     const result = await this.client.GrepRepoFile({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       filePath,
       pattern,
       contextLines: options?.contextLines,
@@ -2336,6 +2394,8 @@ class PkgseerServiceImpl {
     const result = await this.client.VersionDiff({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       fromVersion,
       toVersion,
       includePrivate: options?.includePrivate,
@@ -2749,8 +2809,8 @@ function outputError(message, json) {
 }
 var CLI_HINTS = {
   being_indexed: " Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).",
-  timeout: " Hint: lower the limit or narrow the scope, then retry.",
-  not_found: " Hint: verify the name/registry and that the resource exists.",
+  timeout: " Hint: this may be transient — retry the same command. If the issue persists, try simplifying the query.",
+  not_found: " Hint: verify the package name and registry are correct.",
   auth: " Hint: check login or token validity (pkgseer auth-status).",
   rate_limit: " Hint: wait and retry, or reduce request frequency.",
   unknown: ""
@@ -3007,14 +3067,10 @@ async function codeCalleesAction(symbolArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.symbolDependencies) {
-    outputError("Symbol not found. Verify the symbol reference or use --ref.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.symbolDependencies, true);
+    output(result.data.symbolDependencies, true);
   } else {
-    console.log(formatCalleesResult(result.data?.symbolDependencies));
+    console.log(formatCalleesResult(result.data.symbolDependencies));
   }
 }
 var CALLEES_DESCRIPTION = `Find what a symbol calls.
@@ -3058,14 +3114,10 @@ async function codeCallersAction(symbolArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.symbolDependents) {
-    outputError("Symbol not found. Verify the symbol reference or use --ref.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.symbolDependents, true);
+    output(result.data.symbolDependents, true);
   } else {
-    console.log(formatCallersResult(result.data?.symbolDependents));
+    console.log(formatCallersResult(result.data.symbolDependents));
   }
 }
 var CALLERS_DESCRIPTION = `Find what calls a symbol.
@@ -3130,14 +3182,10 @@ async function codeDiffAction(packageArg, fromVersion, toVersion, options, deps)
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.versionDiff) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.versionDiff, true);
+    output(result.data.versionDiff, true);
   } else {
-    console.log(formatDiffResult(result.data?.versionDiff));
+    console.log(formatDiffResult(result.data.versionDiff));
   }
 }
 var DIFF_DESCRIPTION = `Compare symbols between two package versions.
@@ -3190,11 +3238,7 @@ async function codeFilesAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.listRepoFiles) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.listRepoFiles;
+  const data = result.data.listRepoFiles;
   if (options.json) {
     output(data, true);
   } else {
@@ -3255,11 +3299,7 @@ async function codeFindAction(packageArg, nameArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.findSymbol) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.findSymbol;
+  const data = result.data.findSymbol;
   if (options.json) {
     output(data, true);
   } else {
@@ -3329,11 +3369,7 @@ async function codeGrepAction(packageArg, filePath, pattern, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.grepRepoFile) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.grepRepoFile;
+  const data = result.data.grepRepoFile;
   if (options.json) {
     output(data, true);
   } else {
@@ -3416,14 +3452,10 @@ async function codeImportsAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.packageImports) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.packageImports, true);
+    output(result.data.packageImports, true);
   } else {
-    console.log(formatImportsResult(result.data?.packageImports));
+    console.log(formatImportsResult(result.data.packageImports));
   }
 }
 var IMPORTS_DESCRIPTION = `List import statements in a package.
@@ -3485,14 +3517,10 @@ async function codeListAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.listSymbols) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.listSymbols, true);
+    output(result.data.listSymbols, true);
   } else {
-    console.log(formatListResult(result.data?.listSymbols));
+    console.log(formatListResult(result.data.listSymbols));
   }
 }
 var LIST_DESCRIPTION = `Browse symbols in a package.
@@ -3550,14 +3578,10 @@ async function codePathAction(fromArg, toArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.callPath) {
-    outputError("Could not find call path. Verify the symbol references.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.callPath, true);
+    output(result.data.callPath, true);
   } else {
-    console.log(formatPathResult(result.data?.callPath));
+    console.log(formatPathResult(result.data.callPath));
   }
 }
 var PATH_DESCRIPTION = `Find call path between two symbols.
@@ -3630,11 +3654,7 @@ async function codeSearchAction(packageArg, query, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.searchSymbols) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.searchSymbols;
+  const data = result.data.searchSymbols;
   if (options.json) {
     output(data, true);
   } else {
@@ -5118,7 +5138,7 @@ async function setupCodexViaCli(shellService) {
 }
 function showAvailableTools(hasProject, useColors) {
   console.log(`
-Available MCP tools (21):`);
+Available MCP tools (22):`);
   console.log("");
   console.log("  Navigate source:");
   console.log("    • find_symbol - Read source code of functions/classes");
@@ -5129,8 +5149,8 @@ Available MCP tools (21):`);
   console.log("    • call_path - Find call path between two functions");
   console.log("");
   console.log("  Browse files:");
-  console.log("    • list_repo_files - Explore package file structure");
-  console.log("    • grep_repo_file - Search for patterns in source files");
+  console.log("    • list_package_files - Explore package file structure");
+  console.log("    • grep_package_file - Search for patterns in source files");
   console.log("    • fetch_code_context - Read source by file path and line range");
   console.log("");
   console.log("  Search & docs:");
@@ -6782,27 +6802,99 @@ function toListScope(scope) {
 var schemas = {
   registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).describe("Package registry (npm, pypi, hex, crates, nuget, maven, zig, or vcpkg)"),
   packageName: z2.string().max(255).describe("Name of the package"),
-  version: z2.string().max(100).optional().describe("Specific version (defaults to latest)"),
+  version: z2.string().max(100).optional().describe("Specific version, e.g. '4.18.2' (defaults to latest)"),
   navigationMode: z2.enum(["summary", "detailed"]).optional().describe("Response detail level. summary (default) returns core fields; detailed adds all optional fields."),
-  waitTimeoutMs: z2.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000). 0 = error immediately if not indexed."),
+  waitTimeoutMs: z2.coerce.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000, default 10000). Set 0 to error immediately if not indexed."),
   symbolReference: z2.object({
     symbol_ref: z2.string().optional().describe("Compound symbol reference (registry:package:version:id) from find_symbol or list_symbols results. Self-contained — no additional fields needed."),
-    registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry (required for name-based lookup)"),
-    package_name: z2.string().max(255).optional().describe("Package name (required for name-based lookup)"),
-    symbol_name: z2.string().max(500).optional().describe("Symbol name or qualified path (required for name-based lookup). Matches both short name and qualifiedPath.")
-  })
+    registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry. For package-scoped lookup (with package_name + symbol_name)."),
+    package_name: z2.string().max(255).optional().describe("Package name. For package-scoped lookup (with registry + symbol_name)."),
+    symbol_name: z2.string().max(500).optional().describe("Symbol name or qualified path (required for name-based lookup). Matches both short name and qualifiedPath."),
+    version: z2.string().max(100).optional().describe("Package version. For package-scoped lookup."),
+    repo_url: z2.string().optional().describe("Repository URL (GitHub). For repo-scoped lookup (with git_ref + symbol_name)."),
+    git_ref: z2.string().optional().describe("Git ref (tag, branch, commit, or HEAD). Required with repo_url.")
+  }),
+  codeTarget: z2.object({
+    registry: z2.enum([
+      "npm",
+      "pypi",
+      "hex",
+      "crates",
+      "nuget",
+      "maven",
+      "zig",
+      "vcpkg"
+    ]).optional().describe("Package registry (npm, pypi, hex, etc.). Required for package scope."),
+    package_name: z2.string().max(255).optional().describe("Package name. Required for package scope."),
+    version: z2.string().max(100).optional().describe("Package version, e.g. '4.18.2' (defaults to latest). For package scope only."),
+    repo_url: z2.string().optional().describe("Repository URL (GitHub). Required for repo scope. Example: https://github.com/expressjs/express"),
+    git_ref: z2.string().optional().describe("Git ref — tag, branch, or commit. Required for repo scope. Use HEAD for latest.")
+  }).describe("Target: provide registry + package_name (package scope) OR repo_url + git_ref (repo scope).")
 };
 function toSymbolReferenceInput(ref) {
   return {
     symbolRef: ref.symbol_ref,
     registry: ref.registry ? toGraphQLRegistry(ref.registry) : undefined,
     packageName: ref.package_name,
-    symbolName: ref.symbol_name
+    symbolName: ref.symbol_name,
+    version: ref.version,
+    repoUrl: ref.repo_url,
+    gitRef: ref.git_ref
+  };
+}
+function isToolError(value) {
+  return "content" in value;
+}
+function resolveCodeTarget(target) {
+  const hasPackage = target.registry || target.package_name;
+  const hasRepo = target.repo_url || target.git_ref;
+  if (hasPackage && hasRepo) {
+    return errorResult("Invalid target: provide either registry + package_name (package scope) or repo_url + git_ref (repo scope), not both.");
+  }
+  if (!hasPackage && !hasRepo) {
+    return errorResult("Missing target: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).");
+  }
+  if (hasPackage) {
+    if (!target.registry || !target.package_name) {
+      return errorResult("Incomplete package target: both registry and package_name are required for package scope.");
+    }
+    return {
+      mode: "package",
+      registry: target.registry,
+      packageName: target.package_name,
+      version: target.version
+    };
+  }
+  if (!target.repo_url) {
+    return errorResult("Incomplete repo target: repo_url is required with git_ref.");
+  }
+  if (!target.git_ref) {
+    return errorResult("Incomplete repo target: git_ref is required with repo_url (use HEAD for latest).");
+  }
+  return { mode: "repo", repoUrl: target.repo_url, gitRef: target.git_ref };
+}
+function buildCodeTargetVars(resolved) {
+  if (resolved.mode === "package") {
+    return {
+      registry: toGraphQLRegistry(resolved.registry),
+      packageName: resolved.packageName,
+      version: resolved.version,
+      repoUrl: undefined,
+      gitRef: undefined
+    };
+  }
+  return {
+    registry: undefined,
+    packageName: undefined,
+    version: undefined,
+    repoUrl: resolved.repoUrl,
+    gitRef: resolved.gitRef
   };
 }
+var DEFAULT_WAIT_TIMEOUT_MS2 = 1e4;
 var MCP_HINTS = {
   being_indexed: "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).",
-  timeout: "Hint: try lowering the limit or narrowing the scope, then retry."
+  timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
 function buildHintedMessage(operation, message) {
   const kind = classifyError(message);
@@ -6830,9 +6922,9 @@ function buildHintedMessage(operation, message) {
   return `Failed to ${operation}: ${message}`;
 }
 var MCP_GRAPHQL_HINTS = {
-  not_found: "Hint: verify the name/registry and that the resource exists.",
+  not_found: "Hint: verify the package name and registry are correct.",
   being_indexed: "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).",
-  timeout: "Hint: try lowering the limit or narrowing the scope, then retry."
+  timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
 function handleGraphQLErrors(errors) {
   if (errors && errors.length > 0) {
@@ -6852,45 +6944,42 @@ async function withErrorHandling(operation, fn) {
   }
 }
 function notFoundError(packageName, registry) {
-  return errorResult(`Package not found: ${packageName} in ${registry}`);
+  return errorResult(`Package not found: ${packageName} in ${registry}. Verify the package name and registry are correct.`);
 }
 
 // src/tools/call-path.ts
 var argsSchema = {
-  from: schemas.symbolReference.describe("Source symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
-  to: schemas.symbolReference.describe("Destination symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
-  max_depth: z3.number().int().min(1).max(10).optional().describe("Maximum path length to search (max hops between from and to)"),
+  from: schemas.symbolReference.describe("Source symbol. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
+  to: schemas.symbolReference.describe("Destination symbol. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
+  max_depth: z3.coerce.number().int().min(1).max(10).optional().describe("Maximum path length to search (max hops between from and to)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createCallPathTool(pkgseerService) {
   return {
     name: "call_path",
-    description: "Trace how execution flows from one function to another in a dependency — " + "debug how a public API reaches an internal function or error handler. " + "Uses BFS through intermediate calls. " + "Returns ordered call paths (shortest first) with hop details. " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
+    description: "Trace how execution flows from one function to another in a dependency — " + "debug how a public API reaches an internal function or error handler. " + "Uses BFS through intermediate calls. " + "Returns ordered call paths (shortest first) with hop details. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "For direct callers/callees only, use symbol_callers or symbol_callees instead.",
     schema: argsSchema,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find call path", async () => {
         const fromInput = toSymbolReferenceInput(args.from);
         const toInput = toSymbolReferenceInput(args.to);
-        if (!fromInput.symbolRef && (!fromInput.symbolName || !fromInput.registry || !fromInput.packageName)) {
-          return errorResult("Invalid 'from' symbol: provide either symbol_ref or symbol_name with registry and package_name.");
+        if (!fromInput.symbolRef && !(fromInput.symbolName && fromInput.registry && fromInput.packageName) && !(fromInput.symbolName && fromInput.repoUrl && fromInput.gitRef)) {
+          return errorResult("Invalid 'from' symbol: provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
-        if (!toInput.symbolRef && (!toInput.symbolName || !toInput.registry || !toInput.packageName)) {
-          return errorResult("Invalid 'to' symbol: provide either symbol_ref or symbol_name with registry and package_name.");
+        if (!toInput.symbolRef && !(toInput.symbolName && toInput.registry && toInput.packageName) && !(toInput.symbolName && toInput.repoUrl && toInput.gitRef)) {
+          return errorResult("Invalid 'to' symbol: provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.callPath(fromInput, toInput, {
           maxDepth: args.max_depth,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.callPath) {
-          return errorResult("Could not find call path. Verify the symbols exist and the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.callPath, null, 2));
+        return textResult(JSON.stringify(result.data.callPath, null, 2));
       });
     }
   };
@@ -6908,7 +6997,7 @@ var argsSchema2 = {
 function createComparePackagesTool(pkgseerService) {
   return {
     name: "compare_packages",
-    description: "Compare 2-10 packages side-by-side. Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
+    description: "Compare 2-10 packages side-by-side (available immediately — no indexing required). " + "Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
     schema: argsSchema2,
     annotations: { readOnlyHint: true },
     handler: async ({ packages }, _extra) => {
@@ -6930,48 +7019,16 @@ function createComparePackagesTool(pkgseerService) {
     }
   };
 }
-// src/tools/fetch-code-context.ts
+// src/tools/fetch-package-doc.ts
 import { z as z5 } from "zod";
 var argsSchema3 = {
-  repo_url: z5.string().min(1).describe("Repository URL (GitHub). Example: https://github.com/expressjs/express"),
-  git_ref: z5.string().min(1).describe("Git reference (tag, commit, or branch). Example: v4.18.2"),
-  file_path: z5.string().min(1).describe("Path to file in repository. Example: src/router/index.js"),
-  start_line: z5.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
-  end_line: z5.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file.")
-};
-function createFetchCodeContextTool(pkgseerService) {
-  return {
-    name: "fetch_code_context",
-    description: "Read source code from a dependency's repository by file path and line range — " + "use when you have a file path from a stack trace or symbol lookup. " + "Returns full file or a specific line range. " + "Prefer find_symbol(include_code=true) for function/class lookup. " + "Requires repo_url, git_ref, and file_path.",
-    schema: argsSchema3,
-    annotations: { readOnlyHint: true },
-    handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
-      return withErrorHandling("fetch code context", async () => {
-        const result = await pkgseerService.fetchCodeContext(repo_url, git_ref, file_path, {
-          startLine: start_line,
-          endLine: end_line
-        });
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data?.fetchCodeContext) {
-          return errorResult(`Code not found: ${file_path} at ${git_ref} in ${repo_url}. ` + "Check that the repository, file path, and git ref are correct.");
-        }
-        return textResult(JSON.stringify(result.data?.fetchCodeContext, null, 2));
-      });
-    }
-  };
-}
-// src/tools/fetch-package-doc.ts
-import { z as z6 } from "zod";
-var argsSchema4 = {
-  page_id: z6.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
+  page_id: z5.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
 };
 function createFetchPackageDocTool(pkgseerService) {
   return {
     name: "fetch_package_doc",
-    description: "Get full content of a documentation page. Requires page_id from list_package_docs. " + "Returns: title, full content (markdown/HTML), format type, navigation breadcrumbs, " + "source URL, and last updated timestamp. Use this when you need complete documentation, " + "not just search snippets.",
-    schema: argsSchema4,
+    description: "Get full content of a documentation page. Requires page_id from list_package_docs. " + "Returns: title, full content (markdown/HTML), format type, navigation breadcrumbs, " + "source URL, and last updated timestamp. Use this when you need complete documentation, " + "not just search snippets. " + "Requires documentation to have been crawled — if page_id is from a stale listing, re-check with list_package_docs.",
+    schema: argsSchema3,
     annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
@@ -6988,13 +7045,12 @@ function createFetchPackageDocTool(pkgseerService) {
   };
 }
 // src/tools/find-symbol.ts
-import { z as z7 } from "zod";
-var argsSchema5 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search for symbols"),
-  name: z7.string().max(500).optional().describe("Symbol name to search for (exact match or prefix). Omit to return all public exports."),
-  namespace: z7.string().max(500).optional().describe("Filter by namespace/module path prefix"),
-  kind: z7.enum([
+import { z as z6 } from "zod";
+var argsSchema4 = {
+  target: schemas.codeTarget,
+  name: z6.string().max(500).optional().describe("Symbol name to search for (exact match or prefix). Omit to return all public exports."),
+  namespace: z6.string().max(500).optional().describe("Filter by namespace/module path prefix"),
+  kind: z6.enum([
     "function",
     "method",
     "class",
@@ -7003,39 +7059,41 @@ var argsSchema5 = {
     "type",
     "doc_section"
   ]).optional().describe("Filter by symbol kind"),
-  public_only: z7.boolean().optional().describe("Only return public/exported symbols"),
-  version: schemas.version,
-  include_code: z7.boolean().optional().describe("Include source code in results"),
-  context_lines: z7.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
+  public_only: z6.boolean().optional().describe("Only return public/exported symbols"),
+  include_code: z6.boolean().optional().describe("Include source code in results"),
+  context_lines: z6.coerce.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Read source code of any function, class, or method in a third-party package — " + "use instead of guessing implementations from training data. " + "Set include_code=true for full source inline. " + "Returns: symbol ref, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
-    schema: argsSchema5,
+    description: "Read source code of any function, class, or method — use instead of guessing " + "implementations from training data. Accepts package scope (registry + package_name) " + "or repo scope (repo_url + git_ref) via the target parameter. " + "Set include_code=true for full source inline. " + "Returns: symbolRef, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path. " + "Pass symbolRef from results to symbol_callers, symbol_callees, or call_path.",
+    schema: argsSchema4,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol", async () => {
-        const result = await pkgseerService.findSymbol(toGraphQLRegistry(args.registry), args.package_name, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.findSymbol(tv.registry, tv.packageName, {
           name: args.name,
           namespace: args.namespace,
           kind: toSymbolKind(args.kind),
           publicOnly: args.public_only,
-          version: args.version,
+          version: tv.version,
           includeCode: args.include_code,
           contextLines: args.context_lines,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.findSymbol) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.findSymbol;
+        const data = result.data.findSymbol;
         if (data.symbols.length === 0 && data.diagnostics?.hint) {
           return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
@@ -7044,39 +7102,40 @@ function createFindSymbolTool(pkgseerService) {
     }
   };
 }
-// src/tools/grep-repo-file.ts
-import { z as z8 } from "zod";
-var argsSchema6 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search within"),
-  file_path: z8.string().describe("Path to the file (relative to package root)"),
-  pattern: z8.string().max(200).describe("Case-insensitive substring to search for (max 200 chars)"),
-  context_lines: z8.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
-  max_matches: z8.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
-  version: schemas.version,
+// src/tools/grep-file.ts
+import { z as z7 } from "zod";
+var argsSchema5 = {
+  target: schemas.codeTarget,
+  file_path: z7.string().describe("Path to the file (relative to package root)"),
+  pattern: z7.string().max(200).describe("Case-insensitive substring to search for (max 200 chars)"),
+  context_lines: z7.coerce.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
+  max_matches: z7.coerce.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createGrepRepoFileTool(pkgseerService) {
+function createGrepFileTool(pkgseerService) {
   return {
-    name: "grep_repo_file",
-    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Case-insensitive substring matching with context lines. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover file paths.",
-    schema: argsSchema6,
+    name: "grep_file",
+    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Case-insensitive substring matching with context lines. " + "Use when you know the file path and are looking for specific text. " + "Use list_files to discover file paths. " + "In monorepos with package scope, operates only within this package's subdirectory. " + "Requires code indexing.",
+    schema: argsSchema5,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("grep repo file", async () => {
-        const result = await pkgseerService.grepRepoFile(toGraphQLRegistry(args.registry), args.package_name, args.file_path, args.pattern, {
+      return withErrorHandling("grep file", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.grepRepoFile(tv.registry, tv.packageName, args.file_path, args.pattern, {
           contextLines: args.context_lines,
           maxMatches: args.max_matches,
-          version: args.version,
-          waitTimeoutMs: args.wait_timeout_ms
+          version: tv.version,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.grepRepoFile) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.grepRepoFile;
+        const data = result.data.grepRepoFile;
         if (data.matches.length === 0 && data.diagnostics?.hint) {
           return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
@@ -7085,67 +7144,108 @@ function createGrepRepoFileTool(pkgseerService) {
     }
   };
 }
-// src/tools/list-package-docs.ts
-var argsSchema7 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to list documentation for"),
-  version: schemas.version
+// src/tools/list-files.ts
+import { z as z8 } from "zod";
+var argsSchema6 = {
+  target: schemas.codeTarget,
+  path_prefix: z8.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
+  limit: z8.coerce.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+  wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListPackageDocsTool(pkgseerService) {
+function createListFilesTool(pkgseerService) {
   return {
-    name: "list_package_docs",
-    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search(mode='docs') to find specific topics.",
-    schema: argsSchema7,
+    name: "list_files",
+    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals. " + "In monorepos with package scope, returns only files within this package's subdirectory. " + "Requires code indexing.",
+    schema: argsSchema6,
     annotations: { readOnlyHint: true },
-    handler: async ({ registry, package_name, version: version2 }, _extra) => {
-      return withErrorHandling("list package documentation", async () => {
-        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
+    handler: async (args, _extra) => {
+      return withErrorHandling("list files", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.listRepoFiles(tv.registry, tv.packageName, {
+          version: tv.version,
+          pathPrefix: args.path_prefix,
+          limit: args.limit,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
+        });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listPackageDocs) {
-          return notFoundError(package_name, registry);
+        const data = result.data.listRepoFiles;
+        if (data.files.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
-        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
 }
-// src/tools/list-repo-files.ts
+// src/tools/list-imports.ts
 import { z as z9 } from "zod";
-var argsSchema8 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to list files for"),
-  version: schemas.version,
-  path_prefix: z9.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
-  limit: z9.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+var argsSchema7 = {
+  target: schemas.codeTarget,
+  file_path: z9.string().max(1000).optional().describe("Filter to a specific file path"),
+  resolved_only: z9.boolean().optional().describe("Only return imports resolved to a known package"),
+  limit: z9.coerce.number().int().min(1).max(500).optional().describe("Max imports to return"),
+  mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListRepoFilesTool(pkgseerService) {
+function createListImportsTool(pkgseerService) {
   return {
-    name: "list_repo_files",
-    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals.",
-    schema: argsSchema8,
+    name: "list_imports",
+    description: "See what a dependency imports — understand its internal dependencies and external package usage. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
+    schema: argsSchema7,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("list repo files", async () => {
-        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
-          version: args.version,
-          pathPrefix: args.path_prefix,
+      return withErrorHandling("list imports", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.packageImports(tv.registry, tv.packageName, {
+          filePath: args.file_path,
+          resolvedOnly: args.resolved_only,
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms
+          version: tv.version,
+          mode: toNavigationMode(args.mode),
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listRepoFiles) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.listRepoFiles;
-        if (data.files.length === 0 && data.diagnostics?.hint) {
-          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        return textResult(JSON.stringify(result.data.packageImports, null, 2));
+      });
+    }
+  };
+}
+// src/tools/list-package-docs.ts
+var argsSchema8 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to list documentation for"),
+  version: schemas.version
+};
+function createListPackageDocsTool(pkgseerService) {
+  return {
+    name: "list_package_docs",
+    description: "Discover available documentation pages for a package. Start here before fetching or searching docs. " + "Returns: page titles, unique IDs (needed for fetch_package_doc), word counts, and update timestamps. " + "Workflow: list_package_docs → fetch_package_doc for full content, or search(mode='docs') to find specific topics. " + "Requires documentation to have been crawled — if results are empty, use trigger_indexing first, then retry.",
+    schema: argsSchema8,
+    annotations: { readOnlyHint: true },
+    handler: async ({ registry, package_name, version: version2 }, _extra) => {
+      return withErrorHandling("list package documentation", async () => {
+        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data?.listPackageDocs) {
+          return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(data, null, 2));
+        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
       });
     }
   };
@@ -7153,22 +7253,20 @@ function createListRepoFilesTool(pkgseerService) {
 // src/tools/list-symbols.ts
 import { z as z10 } from "zod";
 var argsSchema9 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to browse symbols for"),
+  target: schemas.codeTarget,
   scope: z10.enum(["exports", "file"]).describe("Browsing scope: 'exports' for public API, 'file' for all symbols in a specific file"),
   file_path: z10.string().max(1000).optional().describe("File path within the repo (required when scope=file)"),
   namespace: z10.string().max(500).optional().describe("Filter by namespace prefix (e.g., 'React' to see React.*)"),
   public_only: z10.boolean().optional().describe("Only return public symbols"),
   include_popularity: z10.boolean().optional().describe("Include callerCount for each symbol (slightly slower)"),
-  limit: z10.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
-  version: schemas.version,
+  limit: z10.coerce.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
-    description: "Browse a dependency's public API or file-level symbols. " + "Use scope='exports' for the public API with optional popularity ranking. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbol refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to read source for any result.",
+    description: "Browse a dependency's public API or file-level symbols. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Use scope='exports' for the public API with optional popularity ranking. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbol refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to read source for any result.",
     schema: argsSchema9,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
@@ -7185,23 +7283,26 @@ function createListSymbolsTool(pkgseerService) {
             isError: true
           };
         }
-        const result = await pkgseerService.listSymbols(toGraphQLRegistry(args.registry), args.package_name, scope, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.listSymbols(tv.registry, tv.packageName, scope, {
           filePath: args.file_path,
           namespace: args.namespace,
           publicOnly: args.public_only,
           includePopularity: args.include_popularity,
           limit: args.limit,
-          version: args.version,
+          version: tv.version,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listSymbols) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.listSymbols, null, 2));
+        return textResult(JSON.stringify(result.data.listSymbols, null, 2));
       });
     }
   };
@@ -7213,7 +7314,7 @@ var argsSchema10 = {
   package_name: schemas.packageName.describe("Name of the package to retrieve dependencies for"),
   version: schemas.version,
   include_transitive: z11.boolean().optional().describe("Whether to include transitive dependency DAG"),
-  max_depth: z11.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+  max_depth: z11.coerce.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
 function decodeDag(rawDag) {
   if (!rawDag || typeof rawDag !== "object")
@@ -7329,47 +7430,8 @@ function createPackageDependenciesTool(pkgseerService) {
     }
   };
 }
-// src/tools/package-imports.ts
-import { z as z12 } from "zod";
-var argsSchema11 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to get imports for"),
-  file_path: z12.string().max(1000).optional().describe("Filter to a specific file path"),
-  resolved_only: z12.boolean().optional().describe("Only return imports resolved to a known package"),
-  limit: z12.number().int().min(1).max(500).optional().describe("Max imports to return"),
-  version: schemas.version,
-  mode: schemas.navigationMode,
-  wait_timeout_ms: schemas.waitTimeoutMs
-};
-function createPackageImportsTool(pkgseerService) {
-  return {
-    name: "package_imports",
-    description: "See what a dependency imports — understand its internal dependencies and external package usage. " + "Returns parsed import/require/use statements with optional resolution to known packages. " + "Use resolved_only=true to see only imports that map to packages in the PkgSeer registry. " + "Includes: source path, imported names, and de-duplicated dependency list.",
-    schema: argsSchema11,
-    annotations: { readOnlyHint: true },
-    handler: async (args, _extra) => {
-      return withErrorHandling("fetch package imports", async () => {
-        const result = await pkgseerService.packageImports(toGraphQLRegistry(args.registry), args.package_name, {
-          filePath: args.file_path,
-          resolvedOnly: args.resolved_only,
-          limit: args.limit,
-          version: args.version,
-          mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
-        });
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data?.packageImports) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.packageImports, null, 2));
-      });
-    }
-  };
-}
 // src/tools/package-quality.ts
-var argsSchema12 = {
+var argsSchema11 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to analyze"),
   version: schemas.version
@@ -7377,8 +7439,8 @@ var argsSchema12 = {
 function createPackageQualityTool(pkgseerService) {
   return {
     name: "package_quality",
-    description: "Evaluate package maintenance health and code quality. Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
-    schema: argsSchema12,
+    description: "Evaluate package maintenance health and code quality (available immediately — no indexing required). " + "Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
+    schema: argsSchema11,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
@@ -7395,15 +7457,15 @@ function createPackageQualityTool(pkgseerService) {
   };
 }
 // src/tools/package-summary.ts
-var argsSchema13 = {
+var argsSchema12 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve summary for")
 };
 function createPackageSummaryTool(pkgseerService) {
   return {
     name: "package_summary",
-    description: "Get a comprehensive overview of a package. Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details).",
-    schema: argsSchema13,
+    description: "Get a comprehensive overview of a package (available immediately — no indexing required). " + "Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details). " + "Use package.repositoryUrl + package.latestVersion as git_ref with fetch_code_context to read source files.",
+    schema: argsSchema12,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
@@ -7420,7 +7482,7 @@ function createPackageSummaryTool(pkgseerService) {
   };
 }
 // src/tools/package-vulnerabilities.ts
-var argsSchema14 = {
+var argsSchema13 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
   version: schemas.version
@@ -7428,8 +7490,8 @@ var argsSchema14 = {
 function createPackageVulnerabilitiesTool(pkgseerService) {
   return {
     name: "package_vulnerabilities",
-    description: "Check security vulnerabilities for a package. Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
-    schema: argsSchema14,
+    description: "Check security vulnerabilities for a package (available immediately — no indexing required). " + "Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
+    schema: argsSchema13,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
@@ -7445,6 +7507,48 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     }
   };
 }
+// src/tools/read-file.ts
+import { z as z12 } from "zod";
+var argsSchema14 = {
+  target: schemas.codeTarget,
+  file_path: z12.string({
+    error: "file_path is required. Get file paths from find_symbol (returns file locations) " + "or list_files (browse file structure)."
+  }).min(1).describe("Path to file in repository. Example: src/router/index.js"),
+  start_line: z12.coerce.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
+  end_line: z12.coerce.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file."),
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createReadFileTool(pkgseerService) {
+  return {
+    name: "read_file",
+    description: "Read source code from a dependency's repository by file path and line range — " + "use when you have a file path from a stack trace or symbol lookup. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Returns full file or a specific line range. " + "Prefer find_symbol(include_code=true) for function/class lookup. " + "Use list_files to discover file paths. " + "With repo scope, operates on the full repository. " + "With package scope, scoped to the package subdirectory in monorepos.",
+    schema: argsSchema14,
+    annotations: { readOnlyHint: true },
+    handler: async (args, _extra) => {
+      return withErrorHandling("read file", async () => {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.fetchCodeContext(tv.repoUrl, tv.gitRef, args.file_path, {
+          startLine: args.start_line,
+          endLine: args.end_line,
+          registry: tv.registry,
+          packageName: tv.packageName,
+          version: tv.version,
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data?.fetchCodeContext) {
+          return errorResult(`File not found: ${args.file_path}. ` + "Check that the file path and target are correct. " + "Use list_files to discover available files.");
+        }
+        return textResult(JSON.stringify(result.data.fetchCodeContext, null, 2));
+      });
+    }
+  };
+}
 // src/tools/search.ts
 import { z as z13 } from "zod";
 var packageInputSchema2 = z13.object({
@@ -7452,13 +7556,16 @@ var packageInputSchema2 = z13.object({
   name: z13.string().min(1).describe("Package name"),
   version: z13.string().optional().describe("Specific version (defaults to latest)")
 });
-var DEFAULT_AGENT_WAIT_TIMEOUT_MS = 1e4;
 var argsSchema15 = {
-  packages: z13.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
-  query: z13.string().min(1).describe("Search query - natural language or keywords"),
+  packages: z13.array(packageInputSchema2, {
+    error: 'packages is required. Provide 1-20 packages as [{registry: "npm", name: "express"}]. ' + "Use package_summary to verify a package exists. " + "For project-wide doc search without specifying packages, use search_project_docs instead."
+  }).min(1).max(20).describe('Packages to search (1-20). Format: [{"registry":"npm","name":"express"}]'),
+  query: z13.string({
+    error: "query is required. Provide search terms as natural language or keywords, " + "e.g., 'error handling middleware'."
+  }).min(1).describe("Search query - natural language or keywords"),
   mode: z13.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
-  limit: z13.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
-  waitTimeoutMs: z13.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
+  limit: z13.coerce.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
+  waitTimeoutMs: z13.coerce.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
 };
 function toSearchMode2(mode) {
   if (!mode)
@@ -7496,7 +7603,7 @@ Results may be incomplete. Retry later for more complete results.`;
 function createSearchTool(pkgseerService) {
   return {
     name: "search",
-    description: "Search code and documentation across packages. Returns functions, classes, and doc pages " + "matching your query. Use mode='code' for code only, mode='docs' for docs only, or " + "mode='all' (default). Provide 1-20 packages. Results include relevance scores and snippets. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
+    description: "Search code and documentation across packages using full-text search. " + "Returns code chunks and doc pages matching your query with relevance scores and snippets. " + "Use mode='code' for code only, mode='docs' for docs only, or mode='all' (default). " + "Provide 1-20 packages. For symbol-level results that feed into symbol_callers/symbol_callees, " + "use search_symbols instead. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "Code results include repoUrl and filePath for use with fetch_code_context. " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
     schema: argsSchema15,
     annotations: { readOnlyHint: true },
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
@@ -7513,7 +7620,7 @@ function createSearchTool(pkgseerService) {
         const result = await pkgseerService.combinedSearch(graphqlPackages, normalizedQuery, {
           mode: toSearchMode2(mode),
           limit,
-          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_AGENT_WAIT_TIMEOUT_MS
+          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7557,7 +7664,7 @@ var argsSchema16 = {
   terms: z14.array(z14.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
   match_mode: z14.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
   include_snippets: z14.boolean().optional().describe("Include content excerpts around matches"),
-  limit: z14.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
+  limit: z14.coerce.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
 function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
@@ -7582,7 +7689,9 @@ function createSearchProjectDocsTool(deps) {
           return errorResult(`No project specified and no pkgseer.yml found. To fix:
 ` + `  1. Pass project_directory: '/path/to/project' (folder containing pkgseer.yml)
 ` + `  2. Pass project: 'project-name' directly if you know the project name
-` + "  3. Run 'pkgseer project init' to create pkgseer.yml in your project");
+` + `  3. Run 'pkgseer project init' to create pkgseer.yml in your project
+
+` + "Or use search(mode='docs', packages=[{registry: 'npm', name: '...'}]) to search " + "specific packages without a project.");
         }
         const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
         if (normalizedTerms.length === 0) {
@@ -7663,8 +7772,7 @@ function createSearchStatusTool(pkgseerService) {
 // src/tools/search-symbols.ts
 import { z as z16 } from "zod";
 var argsSchema18 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search within"),
+  target: schemas.codeTarget,
   query: z16.string().max(500).optional().describe("Search query for full-text code search (max 500 chars). Required if keywords not provided."),
   keywords: z16.array(z16.string()).max(20).optional().describe("Search keywords (max 20). Combined using match_mode. Alternative to query."),
   match_mode: z16.enum(["or", "and"]).optional().describe("How to combine keywords: or (any match) or and (all must match)"),
@@ -7678,37 +7786,39 @@ var argsSchema18 = {
     "doc_section"
   ]).optional().describe("Filter results by code chunk type"),
   file_path: z16.string().optional().describe("Filter results to files whose path starts with this value (e.g., 'src/' for a directory)"),
-  version: schemas.version,
-  limit: z16.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
+  limit: z16.coerce.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Search a dependency's source code by text — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns matching code chunks with name, type, file path, line numbers, and content previews. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source.",
+    description: "Search a dependency's source code by text using the code navigation index — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns symbol-level results that can feed directly into symbol_callers, symbol_callees, or call_path. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source. " + "For free-form text search across multiple packages, use search(mode='code') instead.",
     schema: argsSchema18,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
-        const result = await pkgseerService.searchSymbols(toGraphQLRegistry(args.registry), args.package_name, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.searchSymbols(tv.registry, tv.packageName, {
           query: args.query,
           keywords: args.keywords,
           matchMode: toMatchMode(args.match_mode),
           kind: toSymbolKind(args.kind),
           filePath: args.file_path,
-          version: args.version,
+          version: tv.version,
           limit: args.limit,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.searchSymbols) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.searchSymbols;
+        const data = result.data.searchSymbols;
         const extra = {};
         if (data.results.length === 0 && data.diagnostics?.hint) {
           extra._hint = data.diagnostics.hint;
@@ -7727,10 +7837,10 @@ function createSearchSymbolsTool(pkgseerService) {
 // src/tools/symbol-callees.ts
 import { z as z17 } from "zod";
 var argsSchema19 = {
-  symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide either symbol_ref or registry + package_name + symbol_name."),
-  max_depth: z17.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
-  limit: z17.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
-  include_external: z17.boolean().optional().describe("Include calls to symbols in other packages"),
+  symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
+  max_depth: z17.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
+  limit: z17.coerce.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
+  include_external: z17.boolean().optional().describe("Include calls to symbols in other indexed packages. " + "Default (false) shows only calls within the same package."),
   include_builtins: z17.boolean().optional().describe("Include calls to built-in/standard library functions (console, Math, etc.)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -7738,14 +7848,14 @@ var argsSchema19 = {
 function createSymbolCalleesTool(pkgseerService) {
   return {
     name: "symbol_callees",
-    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
+    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
     schema: argsSchema19,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolRef && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_ref or symbol_name with registry and package_name to identify the symbol.");
+        if (!symbolInput.symbolRef && !(symbolInput.symbolName && symbolInput.registry && symbolInput.packageName) && !(symbolInput.symbolName && symbolInput.repoUrl && symbolInput.gitRef)) {
+          return errorResult("Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.symbolDependencies(symbolInput, {
           maxDepth: args.max_depth,
@@ -7753,15 +7863,12 @@ function createSymbolCalleesTool(pkgseerService) {
           includeExternal: args.include_external,
           includeBuiltins: args.include_builtins,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.symbolDependencies) {
-          return errorResult("Symbol not found. Verify the symbol reference and that the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.symbolDependencies, null, 2));
+        return textResult(JSON.stringify(result.data.symbolDependencies, null, 2));
       });
     }
   };
@@ -7769,39 +7876,36 @@ function createSymbolCalleesTool(pkgseerService) {
 // src/tools/symbol-callers.ts
 import { z as z18 } from "zod";
 var argsSchema20 = {
-  symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide either symbol_ref or registry + package_name + symbol_name."),
-  same_package_only: z18.boolean().optional().describe("Only return callers from the same package"),
-  max_depth: z18.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
-  limit: z18.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
+  symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name."),
+  same_package_only: z18.boolean().optional().describe("Only return callers from the same package. " + "Default (false) includes callers from other indexed packages."),
+  max_depth: z18.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
+  limit: z18.coerce.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse.",
+    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Supports package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse. " + "Use find_symbol(include_code=true) on any caller to read its source.",
     schema: argsSchema20,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolRef && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_ref or symbol_name with registry and package_name to identify the symbol.");
+        if (!symbolInput.symbolRef && !(symbolInput.symbolName && symbolInput.registry && symbolInput.packageName) && !(symbolInput.symbolName && symbolInput.repoUrl && symbolInput.gitRef)) {
+          return errorResult("Provide symbol_ref, or registry + package_name + symbol_name, or repo_url + git_ref + symbol_name.");
         }
         const result = await pkgseerService.symbolDependents(symbolInput, {
           samePackageOnly: args.same_package_only,
           maxDepth: args.max_depth,
           maxResults: args.limit,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.symbolDependents) {
-          return errorResult("Symbol not found. Verify the symbol reference and that the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.symbolDependents, null, 2));
+        return textResult(JSON.stringify(result.data.symbolDependents, null, 2));
       });
     }
   };
@@ -7825,7 +7929,7 @@ var argsSchema21 = {
 function createTriggerIndexingTool(pkgseerService) {
   return {
     name: "trigger_indexing",
-    description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search requests to ensure packages are indexed. " + "Rate limited to 10 requests per minute.",
+    description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search or doc requests to ensure packages are indexed. " + "Code tools auto-wait via wait_timeout_ms on subsequent calls. Most packages index within 10-30s. " + "Rate limited to 10 requests per minute.",
     schema: argsSchema21,
     annotations: { readOnlyHint: false, idempotentHint: true },
     handler: async (args, _extra) => {
@@ -7866,8 +7970,7 @@ function createTriggerIndexingTool(pkgseerService) {
 // src/tools/version-diff.ts
 import { z as z20 } from "zod";
 var argsSchema22 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to compare versions for"),
+  target: schemas.codeTarget,
   from_version: z20.string().max(100).describe("Source version (git ref, e.g., 'v4.18.2')"),
   to_version: z20.string().max(100).describe("Target version (git ref, e.g., 'v5.0.0')"),
   include_private: z20.boolean().optional().describe("Include private/non-exported symbols in the diff"),
@@ -7880,30 +7983,33 @@ var argsSchema22 = {
     "type",
     "doc_section"
   ]).optional().describe("Filter by symbol kind"),
-  limit: z20.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
+  limit: z20.coerce.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createVersionDiffTool(pkgseerService) {
   return {
     name: "version_diff",
-    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
+    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Accepts package scope (registry + package_name) or repo scope (repo_url + git_ref) via the target parameter. " + "With repo scope, from_version and to_version are literal git refs (tags, branches, commits) — " + "the backend does not normalize them. Use target.git_ref=HEAD to identify the repository. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
     schema: argsSchema22,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("version diff", async () => {
-        const result = await pkgseerService.versionDiff(toGraphQLRegistry(args.registry), args.package_name, args.from_version, args.to_version, {
+        const resolved = resolveCodeTarget(args.target);
+        if (isToolError(resolved))
+          return resolved;
+        const tv = buildCodeTargetVars(resolved);
+        const result = await pkgseerService.versionDiff(tv.registry, tv.packageName, args.from_version, args.to_version, {
           includePrivate: args.include_private,
           kind: toSymbolKind(args.kind),
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.versionDiff) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.versionDiff, null, 2));
+        return textResult(JSON.stringify(result.data.versionDiff, null, 2));
       });
     }
   };
@@ -7919,18 +8025,54 @@ Use PkgSeer when:
 - You need to understand what changed between package versions
 
 Instead of guessing library behavior from training data, use find_symbol(include_code=true) to read actual source.
-Instead of cloning repos to search code, use search_symbols or grep_repo_file.
+Instead of cloning repos to search code, use search_symbols or grep_file.
 Instead of manually tracing call chains on GitHub, use symbol_callers and symbol_callees.
 
-Tool groups:
-- Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-- Browse files: list_repo_files, grep_repo_file, fetch_code_context
-- Search across packages: search, search_project_docs
-- Browse docs: list_package_docs, fetch_package_doc
-- Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
-- Utility: trigger_indexing, search_status, package_imports
+Dual addressing — code tools accept a target object with two modes:
+- Package scope: target: { registry: "npm", package_name: "express" } (optional version)
+  In monorepos, results are scoped to the package's subdirectory.
+- Repo scope: target: { repo_url: "https://github.com/expressjs/express", git_ref: "v4.18.2" }
+  Operates on the full repository, not filtered to a package subdirectory.
+
+Use package scope when you know the package name. Use repo scope when you have a repo URL (e.g., from package_summary) and need full-repo access or the repo isn't published as a package.
+
+Data availability — tools are grouped by what backend data they need:
+
+1. Registry metadata (available immediately, no indexing):
+   package_summary, package_quality, package_vulnerabilities, package_dependencies, compare_packages
+   Start here when researching a package — these always work instantly.
+
+2. Documentation (requires doc site crawling):
+   list_package_docs, fetch_package_doc, search(mode='docs'), search_project_docs
+   If results are empty, docs may not be crawled yet — use trigger_indexing first, then retry.
+
+3. Code navigation (requires code repo indexing, dual addressing via target):
+   find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path,
+   list_imports, version_diff, list_files, grep_file, read_file, search(mode='code')
+   These wait up to wait_timeout_ms (default 10s) for indexing. If indexing takes longer, you'll get a "being indexed" response — retry the same call. Most packages index within 10-30 seconds.
+
+Symbol reference tools (symbol_callers, symbol_callees, call_path) accept a symbol object with either:
+- symbol_ref from a previous find_symbol/search_symbols result (preferred, fastest)
+- Package lookup: registry + package_name + symbol_name
+- Repo lookup: repo_url + git_ref + symbol_name
+symbol_callers/symbol_callees can show cross-package results from other indexed packages.
+
+Choosing a code search tool:
+- search_symbols: single package, symbol-level → results feed symbol_callers/callees/call_path
+- search(mode='code'): multi-package, full-text → code chunks with snippets
+- grep_file: single file, pattern match → when you know the file path
+
+Utility: trigger_indexing (pre-warm indexes), search_status (poll async search).
+
+Quick start: find_symbol(target={registry:"npm", package_name:"<pkg>"}, name="<function>", include_code=true) often answers the question in one call.
 
-Quick start: find_symbol(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.`;
+Common workflows (pass symbolRef between tools for chaining):
+- Read source: find_symbol(target={registry, package_name}, name=<fn>, include_code=true)
+- Trace calls: find_symbol → symbol_callees(symbol={symbol_ref: <symbolRef>})
+- Find callers: find_symbol → symbol_callers(symbol={symbol_ref: <symbolRef>})
+- Read file: read_file(target={registry, package_name}, file_path=<path>) or read_file(target={repo_url, git_ref}, file_path=<path>)
+- Search code: search_symbols (single pkg, feeds callers/callees) or search(mode='code', packages=[...]) (multi-pkg)
+- Browse docs: list_package_docs → fetch_package_doc(page_id)`;
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
   package_vulnerabilities: ({ pkgseerService }) => createPackageVulnerabilitiesTool(pkgseerService),
@@ -7941,7 +8083,7 @@ var TOOL_FACTORIES = {
   fetch_package_doc: ({ pkgseerService }) => createFetchPackageDocTool(pkgseerService),
   search: ({ pkgseerService }) => createSearchTool(pkgseerService),
   search_status: ({ pkgseerService }) => createSearchStatusTool(pkgseerService),
-  fetch_code_context: ({ pkgseerService }) => createFetchCodeContextTool(pkgseerService),
+  read_file: ({ pkgseerService }) => createReadFileTool(pkgseerService),
   search_project_docs: ({ pkgseerService, configService, defaultProjectDir }) => createSearchProjectDocsTool({
     pkgseerService,
     configService,
@@ -7952,11 +8094,11 @@ var TOOL_FACTORIES = {
   list_symbols: ({ pkgseerService }) => createListSymbolsTool(pkgseerService),
   symbol_callers: ({ pkgseerService }) => createSymbolCallersTool(pkgseerService),
   symbol_callees: ({ pkgseerService }) => createSymbolCalleesTool(pkgseerService),
-  package_imports: ({ pkgseerService }) => createPackageImportsTool(pkgseerService),
+  list_imports: ({ pkgseerService }) => createListImportsTool(pkgseerService),
   call_path: ({ pkgseerService }) => createCallPathTool(pkgseerService),
   trigger_indexing: ({ pkgseerService }) => createTriggerIndexingTool(pkgseerService),
-  list_repo_files: ({ pkgseerService }) => createListRepoFilesTool(pkgseerService),
-  grep_repo_file: ({ pkgseerService }) => createGrepRepoFileTool(pkgseerService),
+  list_files: ({ pkgseerService }) => createListFilesTool(pkgseerService),
+  grep_file: ({ pkgseerService }) => createGrepFileTool(pkgseerService),
   version_diff: ({ pkgseerService }) => createVersionDiffTool(pkgseerService)
 };
 var PUBLIC_READ_TOOLS = [
@@ -7969,24 +8111,24 @@ var PUBLIC_READ_TOOLS = [
   "fetch_package_doc",
   "search",
   "search_status",
-  "fetch_code_context",
+  "read_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
   "symbol_callers",
   "symbol_callees",
-  "package_imports",
+  "list_imports",
   "call_path",
   "trigger_indexing",
-  "list_repo_files",
-  "grep_repo_file",
+  "list_files",
+  "grep_file",
   "version_diff"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];
 var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
 function createMcpServer(deps) {
   const { pkgseerService, configService, config, fileSystemService } = deps;
-  const server = new McpServer({ name: "pkgseer", version: "0.1.0" }, { instructions: PKGSEER_INSTRUCTIONS });
+  const server = new McpServer({ name: "pkgseer", version: "0.5.0" }, { instructions: PKGSEER_INSTRUCTIONS });
   const defaultProjectDir = fileSystemService.getCwd();
   const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
   const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
@@ -8052,13 +8194,13 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools (21):
+Available tools (22):
   Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-  Browse files: list_repo_files, grep_repo_file, fetch_code_context
+  Browse files: list_files, grep_file, read_file
   Search: search, search_project_docs
   Docs: list_package_docs, fetch_package_doc
   Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
-  Utility: trigger_indexing, search_status, package_imports`).action(async () => {
+  Utility: trigger_indexing, search_status, list_imports`).action(async () => {
     const deps = await createContainer();
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions(deps);