@pkgseer/cli 0.4.11 → 0.5.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-r3pnzy5b.js";
+} from "./shared/chunk-x6hqsn93.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
@@ -331,6 +335,8 @@ var FetchCodeContextDocument = gql`
     endLine
     repoUrl
     gitRef
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -359,6 +365,16 @@ var TriggerIndexingDocument = gql`
   }
 }
     `;
+var IndexingProgressDocument = gql`
+    query IndexingProgress($ref: String!) {
+  indexingProgress(ref: $ref) {
+    status
+    filesIndexed
+    chunksCreated
+    elapsedMs
+  }
+}
+    `;
 var CreateProjectDocument = gql`
     mutation CreateProject($input: CreateProjectInput!) {
   createProject(input: $input) {
@@ -656,10 +672,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
@@ -693,14 +711,18 @@ var FindSymbolDocument = gql`
       indexedAt
       hint
     }
+    indexingStatus
+    indexingRef
   }
 }
     `;
 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
@@ -739,14 +761,18 @@ var SearchSymbolsDocument = gql`
       hint
     }
     warning
+    indexingStatus
+    indexingRef
   }
 }
     `;
 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
@@ -776,6 +802,8 @@ var ListSymbolsDocument = gql`
       path
       language
     }
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -815,6 +843,8 @@ var SymbolDependenciesDocument = gql`
     missingPackages
     total
     hasMore
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -844,14 +874,18 @@ var SymbolDependentsDocument = gql`
     }
     total
     hasMore
+    indexingStatus
+    indexingRef
   }
 }
     `;
 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
@@ -876,6 +910,8 @@ var PackageImportsDocument = gql`
     }
     uniqueDependencies
     unresolvedCount
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -909,6 +945,8 @@ var CallPathDocument = gql`
         callLine
       }
     }
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -941,10 +979,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
@@ -967,14 +1007,18 @@ var ListRepoFilesDocument = gql`
       indexedAt
       hint
     }
+    indexingStatus
+    indexingRef
   }
 }
     `;
 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
@@ -1001,14 +1045,18 @@ var GrepRepoFileDocument = gql`
       indexedAt
       hint
     }
+    indexingStatus
+    indexingRef
   }
 }
     `;
 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
@@ -1056,6 +1104,8 @@ var VersionDiffDocument = gql`
       }
     }
     hasMore
+    indexingStatus
+    indexingRef
   }
 }
     `;
@@ -1074,6 +1124,7 @@ var SearchResultsDocumentString = print(SearchResultsDocument);
 var FetchCodeContextDocumentString = print(FetchCodeContextDocument);
 var CliDocsGetDocumentString = print(CliDocsGetDocument);
 var TriggerIndexingDocumentString = print(TriggerIndexingDocument);
+var IndexingProgressDocumentString = print(IndexingProgressDocument);
 var CreateProjectDocumentString = print(CreateProjectDocument);
 var PackageSummaryDocumentString = print(PackageSummaryDocument);
 var PackageVulnerabilitiesDocumentString = print(PackageVulnerabilitiesDocument);
@@ -1139,6 +1190,9 @@ function getSdk(client, withWrapper = defaultWrapper) {
     TriggerIndexing(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(TriggerIndexingDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "TriggerIndexing", "mutation", variables);
     },
+    IndexingProgress(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(IndexingProgressDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "IndexingProgress", "query", variables);
+    },
     CreateProject(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(CreateProjectDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CreateProject", "mutation", variables);
     },
@@ -1641,20 +1695,27 @@ var TOOL_NAMES = [
   "fetch_package_doc",
   "search",
   "search_status",
-  "fetch_code_context",
+  "read_file",
   "search_project_docs",
-  "list_package_files",
-  "grep_package_file",
+  "list_files",
+  "grep_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
   "symbol_callers",
   "symbol_callees",
-  "package_imports",
+  "list_imports",
   "call_path",
   "trigger_indexing",
+  "indexing_status",
   "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 +1823,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 +2286,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 +2300,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 +2318,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 +2336,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 +2378,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 +2403,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 +2416,8 @@ class PkgseerServiceImpl {
     const result = await this.client.GrepRepoFile({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       filePath,
       pattern,
       contextLines: options?.contextLines,
@@ -2336,6 +2431,8 @@ class PkgseerServiceImpl {
     const result = await this.client.VersionDiff({
       registry,
       packageName,
+      repoUrl: options?.repoUrl,
+      gitRef: options?.gitRef,
       fromVersion,
       toVersion,
       includePrivate: options?.includePrivate,
@@ -2345,6 +2442,10 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
+  async getIndexingProgress(ref) {
+    const result = await this.client.IndexingProgress({ ref });
+    return { data: result.data, errors: result.errors };
+  }
   async triggerIndexing(input) {
     const result = await this.client.TriggerIndexing({ input });
     return { data: result.data, errors: result.errors };
@@ -6744,25 +6845,96 @@ var schemas = {
   packageName: z2.string().max(255).describe("Name of the package"),
   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.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."),
+  waitTimeoutMs: z2.coerce.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (0-60000, 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).",
+  being_indexed: "Hint: target is being indexed. Retry with a longer wait_timeout_ms (e.g., 30000) or use indexing_status to poll progress.",
   timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
 function buildHintedMessage(operation, message) {
@@ -6791,14 +6963,50 @@ function buildHintedMessage(operation, message) {
   return `Failed to ${operation}: ${message}`;
 }
 var MCP_GRAPHQL_HINTS = {
-  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).",
+  not_found: "Hint: verify the package name, registry, or repository URL are correct.",
+  being_indexed: "Hint: target is being indexed. Retry with a longer wait_timeout_ms (e.g., 30000) or use indexing_status to poll progress.",
   timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
+function getExtensionCode(errors) {
+  for (const error2 of errors) {
+    const ext = error2.extensions;
+    if (ext?.code && typeof ext.code === "string") {
+      return ext.code;
+    }
+  }
+  return;
+}
+function getExtensionIndexingRef(errors) {
+  for (const error2 of errors) {
+    const ext = error2.extensions;
+    const ref = ext?.indexing_ref ?? ext?.indexingRef;
+    if (ref && typeof ref === "string") {
+      return ref;
+    }
+  }
+  return;
+}
+var EXTENSION_CODE_HINTS = {
+  PACKAGE_INDEXING: "Hint: target is being indexed. Use indexing_status to poll progress, or retry with a longer wait_timeout_ms.",
+  NOT_FOUND: "Hint: verify the package name, registry, or repository URL are correct."
+};
 function handleGraphQLErrors(errors) {
   if (errors && errors.length > 0) {
     const combined = errors.map((e) => e.message).filter(Boolean).join(", ");
-    const hint = MCP_GRAPHQL_HINTS[classifyError(combined)];
+    const extensionCode = getExtensionCode(errors);
+    const indexingRef = getExtensionIndexingRef(errors);
+    if (extensionCode === "PACKAGE_INDEXING" && indexingRef) {
+      return errorResult(JSON.stringify({
+        error: combined,
+        indexingStatus: "INDEXING",
+        indexingRef,
+        message: "Target is being indexed. Use indexing_status tool with this indexingRef to poll progress, " + "or retry the original query after indexing completes."
+      }));
+    }
+    if (extensionCode === "PACKAGE_INDEXING") {
+      return errorResult(`Error: ${combined}. ` + "Hint: target is being indexed (background refresh). Retry the query in a few seconds.");
+    }
+    const hint = extensionCode ? EXTENSION_CODE_HINTS[extensionCode] : MCP_GRAPHQL_HINTS[classifyError(combined)];
     const suffix = hint ? `. ${hint}` : "";
     return errorResult(`Error: ${combined}${suffix}`);
   }
@@ -6818,8 +7026,8 @@ function notFoundError(packageName, registry) {
 
 // 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."),
+  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
@@ -6827,18 +7035,18 @@ var argsSchema = {
 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,
@@ -6888,54 +7096,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({
-    error: "repo_url is required. Get it from package_summary (returns repository URL). " + "Or use find_symbol(include_code=true) to read source without needing repo_url."
-  }).min(1).describe("Repository URL (GitHub). Example: https://github.com/expressjs/express"),
-  git_ref: z5.string({
-    error: "git_ref is required. Use the package version as a tag (e.g., 'v4.18.2'). " + "Get the latest version from package_summary."
-  }).min(1).describe("Git reference (tag, commit, or branch). Example: v4.18.2"),
-  file_path: z5.string({
-    error: "file_path is required. Get file paths from find_symbol (returns file locations) " + "or list_package_files (browse package file structure)."
-  }).min(1).describe("Path to file in repository. Example: src/router/index.js"),
-  start_line: z5.coerce.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
-  end_line: z5.coerce.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 (from package_summary), git_ref (version tag, e.g. 'v4.18.2'), " + "and file_path (from find_symbol or list_package_files). " + "Operates on the full repository — not filtered to package subdirectory in monorepos.",
-    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. " + "Requires documentation to have been crawled — if page_id is from a stale listing, re-check with list_package_docs.",
-    schema: argsSchema4,
+    schema: argsSchema3,
     annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
@@ -6952,13 +7122,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",
@@ -6967,31 +7136,36 @@ 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.coerce.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: 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: 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 ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7005,31 +7179,35 @@ function createFindSymbolTool(pkgseerService) {
     }
   };
 }
-// src/tools/grep-package-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.coerce.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
-  max_matches: z8.coerce.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 createGrepPackageFileTool(pkgseerService) {
+function createGrepFileTool(pkgseerService) {
   return {
-    name: "grep_package_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. " + "Use when you know the file path and are looking for specific text. " + "Use list_package_files to discover file paths. " + "In monorepos, operates only within this package's subdirectory. " + "Requires code indexing.",
-    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 package 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 ?? DEFAULT_WAIT_TIMEOUT_MS2
+          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)
@@ -7043,55 +7221,81 @@ function createGrepPackageFileTool(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/indexing-status.ts
+import { z as z8 } from "zod";
+var argsSchema6 = {
+  ref: z8.string().min(1).describe("Indexing reference from a previous tool result (returned when indexing times out).")
 };
-function createListPackageDocsTool(pkgseerService) {
+function createIndexingStatusTool(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: argsSchema7,
+    name: "indexing_status",
+    description: "Check indexing progress for a code navigation target. " + "Use after any code navigation tool returns an indexingRef (when indexing exceeded wait_timeout_ms). " + "Returns status (PENDING, INDEXING, INDEXED, FAILED, NOT_FOUND) with progress details. " + "When status is INDEXED, retry the original query to get results.",
+    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 ({ ref }, _extra) => {
+      return withErrorHandling("check indexing status", async () => {
+        const result = await pkgseerService.getIndexingProgress(ref);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listPackageDocs) {
-          return notFoundError(package_name, registry);
+        const progress = result.data?.indexingProgress;
+        if (!progress) {
+          return errorResult("Indexing session not found. The reference may be invalid or the session may have expired.");
         }
-        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
+        const response = {
+          status: progress.status,
+          ref
+        };
+        if (progress.filesIndexed != null) {
+          response.filesIndexed = progress.filesIndexed;
+        }
+        if (progress.chunksCreated != null) {
+          response.chunksCreated = progress.chunksCreated;
+        }
+        if (progress.elapsedMs != null) {
+          response.elapsedMs = progress.elapsedMs;
+        }
+        if (progress.status === "INDEXED") {
+          response.message = "Indexing is complete. Retry your original query to get results.";
+        } else if (progress.status === "INDEXING" || progress.status === "PENDING") {
+          response.message = "Indexing is in progress. Poll again to check status.";
+        } else if (progress.status === "FAILED") {
+          response.message = "Indexing failed.";
+        } else if (progress.status === "NOT_FOUND") {
+          response.message = "Indexing reference not found. The ref may be invalid or the session may have expired.";
+        }
+        return textResult(JSON.stringify(response, null, 2));
       });
     }
   };
 }
-// src/tools/list-package-files.ts
+// src/tools/list-files.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,
+var argsSchema7 = {
+  target: schemas.codeTarget,
   path_prefix: z9.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
   limit: z9.coerce.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListPackageFilesTool(pkgseerService) {
+function createListFilesTool(pkgseerService) {
   return {
-    name: "list_package_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. " + "In monorepos, returns only files within this package's subdirectory. " + "Requires code indexing.",
-    schema: argsSchema8,
+    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: argsSchema7,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("list package files", async () => {
-        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
-          version: args.version,
+      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
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7105,26 +7309,90 @@ function createListPackageFilesTool(pkgseerService) {
     }
   };
 }
-// src/tools/list-symbols.ts
+// src/tools/list-imports.ts
 import { z as z10 } from "zod";
+var argsSchema8 = {
+  target: schemas.codeTarget,
+  file_path: z10.string().max(1000).optional().describe("Filter to a specific file path"),
+  resolved_only: z10.boolean().optional().describe("Only return imports resolved to a known package"),
+  limit: z10.coerce.number().int().min(1).max(500).optional().describe("Max imports to return"),
+  mode: schemas.navigationMode,
+  wait_timeout_ms: schemas.waitTimeoutMs
+};
+function createListImportsTool(pkgseerService) {
+  return {
+    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: argsSchema8,
+    annotations: { readOnlyHint: true },
+    handler: async (args, _extra) => {
+      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,
+          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;
+        return textResult(JSON.stringify(result.data.packageImports, null, 2));
+      });
+    }
+  };
+}
+// src/tools/list-package-docs.ts
 var argsSchema9 = {
   registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to browse symbols for"),
-  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.coerce.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
-  version: schemas.version,
+  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: argsSchema9,
+    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(result.data?.listPackageDocs, null, 2));
+      });
+    }
+  };
+}
+// src/tools/list-symbols.ts
+import { z as z11 } from "zod";
+var argsSchema10 = {
+  target: schemas.codeTarget,
+  scope: z11.enum(["exports", "file"]).describe("Browsing scope: 'exports' for public API, 'file' for all symbols in a specific file"),
+  file_path: z11.string().max(1000).optional().describe("File path within the repo (required when scope=file)"),
+  namespace: z11.string().max(500).optional().describe("Filter by namespace prefix (e.g., 'React' to see React.*)"),
+  public_only: z11.boolean().optional().describe("Only return public symbols"),
+  include_popularity: z11.boolean().optional().describe("Include callerCount for each symbol (slightly slower)"),
+  limit: z11.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.",
-    schema: argsSchema9,
+    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: argsSchema10,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
@@ -7140,15 +7408,21 @@ 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 ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7159,13 +7433,13 @@ function createListSymbolsTool(pkgseerService) {
   };
 }
 // src/tools/package-dependencies.ts
-import { z as z11 } from "zod";
-var argsSchema10 = {
+import { z as z12 } from "zod";
+var argsSchema11 = {
   registry: schemas.registry,
   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.coerce.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+  include_transitive: z12.boolean().optional().describe("Whether to include transitive dependency DAG"),
+  max_depth: z12.coerce.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
 function decodeDag(rawDag) {
   if (!rawDag || typeof rawDag !== "object")
@@ -7243,7 +7517,7 @@ function createPackageDependenciesTool(pkgseerService) {
   return {
     name: "package_dependencies",
     description: "Analyze package dependencies. By default returns direct dependencies only. " + "Set include_transitive=true to get the full dependency tree (use max_depth to limit large trees). " + "Returns: dependency names, version constraints, and for transitive deps, a graph with depth levels. " + "Use this to understand complexity before adding a package, or to find nested dependencies.",
-    schema: argsSchema10,
+    schema: argsSchema11,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
       return withErrorHandling("fetch package dependencies", async () => {
@@ -7281,42 +7555,6 @@ 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.coerce.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 ?? DEFAULT_WAIT_TIMEOUT_MS2
-        });
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        return textResult(JSON.stringify(result.data.packageImports, null, 2));
-      });
-    }
-  };
-}
 // src/tools/package-quality.ts
 var argsSchema12 = {
   registry: schemas.registry,
@@ -7394,23 +7632,67 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     }
   };
 }
-// src/tools/search.ts
+// src/tools/read-file.ts
 import { z as z13 } from "zod";
-var packageInputSchema2 = z13.object({
-  registry: schemas.registry,
-  name: z13.string().min(1).describe("Package name"),
-  version: z13.string().optional().describe("Specific version (defaults to latest)")
-});
 var argsSchema15 = {
-  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({
+  target: schemas.codeTarget,
+  file_path: z13.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: z13.coerce.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
+  end_line: z13.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: argsSchema15,
+    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 z14 } from "zod";
+var targetInputSchema = z14.object({
+  registry: z14.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry (npm, pypi, hex, etc.). Required for package scope."),
+  package_name: z14.string().min(1).optional().describe("Package name. Required for package scope."),
+  version: z14.string().optional().describe("Specific version (defaults to latest). Package scope only."),
+  repo_url: z14.string().optional().describe("Repository URL (GitHub). Required for repo scope. Example: https://github.com/expressjs/express"),
+  git_ref: z14.string().optional().describe("Git ref — tag, branch, or commit. Required for repo scope. Use HEAD for latest.")
+}).describe("Search target: provide registry + package_name (package scope) OR repo_url + git_ref (repo scope).");
+var argsSchema16 = {
+  targets: z14.array(targetInputSchema, {
+    error: 'targets is required. Provide 1-20 targets as [{registry: "npm", package_name: "express"}] ' + 'or [{repo_url: "https://github.com/user/repo", git_ref: "HEAD"}]. ' + "Use package_summary to verify a package exists. " + "For project-wide doc search without specifying targets, use search_project_docs instead."
+  }).min(1).max(20).describe("Targets to search (1-20). Each uses registry + package_name (package scope) or repo_url + git_ref (repo scope)."),
+  query: z14.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.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)")
+  mode: z14.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
+  limit: z14.coerce.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
+  wait_timeout_ms: schemas.waitTimeoutMs
 };
 function toSearchMode2(mode) {
   if (!mode)
@@ -7422,6 +7704,47 @@ function toSearchMode2(mode) {
   };
   return map[mode.toLowerCase()];
 }
+function validateAndConvertTargets(targets) {
+  const inputs = [];
+  for (let i = 0;i < targets.length; i++) {
+    const t = targets[i];
+    const hasPackage = t.registry || t.package_name;
+    const hasRepo = t.repo_url || t.git_ref;
+    if (hasPackage && hasRepo) {
+      return {
+        error: `Target ${i + 1}: provide either registry + package_name or repo_url + git_ref, not both.`
+      };
+    }
+    if (!hasPackage && !hasRepo) {
+      return {
+        error: `Target ${i + 1}: provide registry + package_name (package scope) or repo_url + git_ref (repo scope).`
+      };
+    }
+    if (hasPackage) {
+      if (!t.registry || !t.package_name) {
+        return {
+          error: `Target ${i + 1}: both registry and package_name are required for package scope.`
+        };
+      }
+      inputs.push({
+        registry: toGraphQLRegistry(t.registry),
+        name: t.package_name,
+        version: t.version
+      });
+    } else {
+      if (!t.repo_url || !t.git_ref) {
+        return {
+          error: `Target ${i + 1}: both repo_url and git_ref are required for repo scope.`
+        };
+      }
+      inputs.push({
+        repoUrl: t.repo_url,
+        gitRef: t.git_ref
+      });
+    }
+  }
+  return { inputs };
+}
 function formatIndexingWarnings2(indexingStatus) {
   if (!indexingStatus || indexingStatus.length === 0)
     return null;
@@ -7440,7 +7763,7 @@ function formatIndexingWarnings2(indexingStatus) {
   if (warnings.length === 0)
     return null;
   return `
-Note: Some packages are not fully indexed:
+Note: Some targets are not fully indexed:
 ` + warnings.join(`
 `) + `
 Results may be incomplete. Retry later for more complete results.`;
@@ -7448,38 +7771,37 @@ Results may be incomplete. Retry later for more complete results.`;
 function createSearchTool(pkgseerService) {
   return {
     name: "search",
-    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,
+    description: "Search code and documentation across packages or repositories using full-text search. " + "Returns code chunks and doc pages matching your query with relevance scores and snippets. " + "Each target can use package scope (registry + package_name) or repo scope (repo_url + git_ref). " + "Use mode='code' for code only, mode='docs' for docs only, or mode='all' (default). " + "Provide 1-20 targets. 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 targets need indexing, waits up to wait_timeout_ms (default 10s) or returns searchRef — use search_status to poll.",
+    schema: argsSchema16,
     annotations: { readOnlyHint: true },
-    handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
-      return withErrorHandling("search packages", async () => {
+    handler: async ({ targets, query, mode, limit, wait_timeout_ms }, _extra) => {
+      return withErrorHandling("search", async () => {
         const normalizedQuery = query.trim();
         if (normalizedQuery.length === 0) {
           return errorResult("Search query is required.");
         }
-        const graphqlPackages = packages.map((pkg) => ({
-          registry: toGraphQLRegistry(pkg.registry),
-          name: pkg.name,
-          version: pkg.version
-        }));
-        const result = await pkgseerService.combinedSearch(graphqlPackages, normalizedQuery, {
+        const validated = validateAndConvertTargets(targets);
+        if ("error" in validated) {
+          return errorResult(validated.error);
+        }
+        const result = await pkgseerService.combinedSearch(validated.inputs, normalizedQuery, {
           mode: toSearchMode2(mode),
           limit,
-          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
         const asyncResult = result.data?.combinedSearch;
         if (!asyncResult) {
-          return errorResult("No search results returned. Check package names and registries.");
+          return errorResult("No search results returned. Check target names and registries.");
         }
         if (!asyncResult.completed) {
           const progressInfo = {
             completed: false,
             searchRef: asyncResult.searchRef,
             progress: asyncResult.progress,
-            message: "Search is still indexing. Retry with same query for results, " + "or increase waitTimeoutMs to wait longer."
+            message: "Search is still indexing. Use search_status with the searchRef to poll, " + "or retry with a longer wait_timeout_ms."
           };
           return textResult(JSON.stringify(progressInfo, null, 2));
         }
@@ -7489,7 +7811,7 @@ function createSearchTool(pkgseerService) {
         }
         const entries = searchResult.entries ?? [];
         if (entries.length === 0) {
-          return errorResult(`No results found for "${normalizedQuery}". ` + "Try broader terms or different packages.");
+          return errorResult(`No results found for "${normalizedQuery}". ` + "Try broader terms or different targets.");
         }
         let response = JSON.stringify(searchResult, null, 2);
         const indexingWarning = formatIndexingWarnings2(searchResult.indexingStatus);
@@ -7502,21 +7824,21 @@ function createSearchTool(pkgseerService) {
   };
 }
 // src/tools/search-project-docs.ts
-import { z as z14 } from "zod";
-var argsSchema16 = {
-  project_directory: z14.string().optional().describe("Directory to search for pkgseer.yml configuration. " + "Use this to specify which project's context to use when the MCP server " + "is installed at user level. Defaults to MCP server's working directory."),
-  project: z14.string().optional().describe("Project name to search. Overrides value from pkgseer.yml if provided."),
-  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.coerce.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
+import { z as z15 } from "zod";
+var argsSchema17 = {
+  project_directory: z15.string().optional().describe("Directory to search for pkgseer.yml configuration. " + "Use this to specify which project's context to use when the MCP server " + "is installed at user level. Defaults to MCP server's working directory."),
+  project: z15.string().optional().describe("Project name to search. Overrides value from pkgseer.yml if provided."),
+  terms: z15.array(z15.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
+  match_mode: z15.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
+  include_snippets: z15.boolean().optional().describe("Include content excerpts around matches"),
+  limit: z15.coerce.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
 function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
   return {
     name: "search_project_docs",
     description: "Search documentation across all dependencies in a PkgSeer project — " + "use when you need to find information but don't know which dependency has it. " + "Requires a pkgseer.yml project config (or pass project name directly). " + "Returns ranked results with snippets from multiple packages. " + "Use project_directory to specify which project's context to use. " + "For single-package doc search, use search(mode='docs') instead.",
-    schema: argsSchema16,
+    schema: argsSchema17,
     annotations: { readOnlyHint: true },
     handler: async ({
       project_directory,
@@ -7565,15 +7887,15 @@ function createSearchProjectDocsTool(deps) {
   };
 }
 // src/tools/search-status.ts
-import { z as z15 } from "zod";
-var argsSchema17 = {
-  searchRef: z15.string().min(1).describe("Search reference from a previous incomplete search")
+import { z as z16 } from "zod";
+var argsSchema18 = {
+  searchRef: z16.string().min(1).describe("Search reference from a previous incomplete search")
 };
 function createSearchStatusTool(pkgseerService) {
   return {
     name: "search_status",
     description: "Check the status of an async search and get results if complete. " + "Use after search returns completed=false with a searchRef. Sessions expire after 1 hour. " + "Returns status (PENDING, INDEXING, SEARCHING, COMPLETED, TIMEOUT, FAILED), " + "progress info (packagesReady/packagesTotal), and results when COMPLETED.",
-    schema: argsSchema17,
+    schema: argsSchema18,
     annotations: { readOnlyHint: true },
     handler: async ({ searchRef }, _extra) => {
       return withErrorHandling("check search status", async () => {
@@ -7615,14 +7937,13 @@ 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"),
-  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)"),
-  kind: z16.enum([
+import { z as z17 } from "zod";
+var argsSchema19 = {
+  target: schemas.codeTarget,
+  query: z17.string().max(500).optional().describe("Search query for full-text code search (max 500 chars). Required if keywords not provided."),
+  keywords: z17.array(z17.string()).max(20).optional().describe("Search keywords (max 20). Combined using match_mode. Alternative to query."),
+  match_mode: z17.enum(["or", "and"]).optional().describe("How to combine keywords: or (any match) or and (all must match)"),
+  kind: z17.enum([
     "function",
     "method",
     "class",
@@ -7631,30 +7952,35 @@ var argsSchema18 = {
     "type",
     "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.coerce.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
+  file_path: z17.string().optional().describe("Filter results to files whose path starts with this value (e.g., 'src/' for a directory)"),
+  limit: z17.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 using the code navigation index — " + "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 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,
+    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: argsSchema19,
     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 ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7676,27 +8002,27 @@ 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.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.)"),
+import { z as z18 } from "zod";
+var argsSchema20 = {
+  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: z18.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
+  limit: z18.coerce.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
+  include_external: z18.boolean().optional().describe("Include calls to symbols in other indexed packages. " + "Default (false) shows only calls within the same package."),
+  include_builtins: z18.boolean().optional().describe("Include calls to built-in/standard library functions (console, Math, etc.)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 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.",
-    schema: argsSchema19,
+    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: argsSchema20,
     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,
@@ -7715,26 +8041,26 @@ 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. " + "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"),
+import { z as z19 } from "zod";
+var argsSchema21 = {
+  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: z19.boolean().optional().describe("Only return callers from the same package. " + "Default (false) includes callers from other indexed packages."),
+  max_depth: z19.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
+  limit: z19.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. " + "Use find_symbol(include_code=true) on any caller to read its source.",
-    schema: argsSchema20,
+    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: argsSchema21,
     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,
@@ -7752,26 +8078,26 @@ function createSymbolCallersTool(pkgseerService) {
   };
 }
 // src/tools/trigger-indexing.ts
-import { z as z19 } from "zod";
-var packageInputSchema3 = z19.object({
+import { z as z20 } from "zod";
+var packageInputSchema2 = z20.object({
   registry: schemas.registry,
-  name: z19.string().max(255).describe("Package name"),
-  version: z19.string().max(100).optional().describe("Specific version to index")
+  name: z20.string().max(255).describe("Package name"),
+  version: z20.string().max(100).optional().describe("Specific version to index")
 });
-var repositoryInputSchema = z19.object({
-  url: z19.string().max(2000).describe("GitHub repository URL"),
-  ref: z19.string().max(200).optional().describe("Git ref to index (tag, branch, commit). Defaults to HEAD"),
-  discover_packages: z19.boolean().optional().describe("If true, discover packages published from this repo and trigger their metadata fetch")
+var repositoryInputSchema = z20.object({
+  url: z20.string().max(2000).describe("GitHub repository URL"),
+  ref: z20.string().max(200).optional().describe("Git ref to index (tag, branch, commit). Defaults to HEAD"),
+  discover_packages: z20.boolean().optional().describe("If true, discover packages published from this repo and trigger their metadata fetch")
 });
-var argsSchema21 = {
-  packages: z19.array(packageInputSchema3).max(100).optional().describe("Package versions to index (max 100)"),
-  repositories: z19.array(repositoryInputSchema).max(50).optional().describe("Repository URLs to index (max 50)")
+var argsSchema22 = {
+  packages: z20.array(packageInputSchema2).max(100).optional().describe("Package versions to index (max 100)"),
+  repositories: z20.array(repositoryInputSchema).max(50).optional().describe("Repository URLs to index (max 50)")
 };
 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 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,
+    schema: argsSchema22,
     annotations: { readOnlyHint: false, idempotentHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("trigger indexing", async () => {
@@ -7809,14 +8135,13 @@ 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"),
-  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"),
-  kind: z20.enum([
+import { z as z21 } from "zod";
+var argsSchema23 = {
+  target: schemas.codeTarget,
+  from_version: z21.string().max(100).describe("Source version (git ref, e.g., 'v4.18.2')"),
+  to_version: z21.string().max(100).describe("Target version (git ref, e.g., 'v5.0.0')"),
+  include_private: z21.boolean().optional().describe("Include private/non-exported symbols in the diff"),
+  kind: z21.enum([
     "function",
     "method",
     "class",
@@ -7825,22 +8150,28 @@ var argsSchema22 = {
     "type",
     "doc_section"
   ]).optional().describe("Filter by symbol kind"),
-  limit: z20.coerce.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
+  limit: z21.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.",
-    schema: argsSchema22,
+    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: argsSchema23,
     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 ?? DEFAULT_WAIT_TIMEOUT_MS2
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2,
+          repoUrl: tv.repoUrl,
+          gitRef: tv.gitRef
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7861,9 +8192,17 @@ 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_package_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.
 
+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):
@@ -7874,33 +8213,32 @@ Data availability — tools are grouped by what backend data they need:
    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. Package code (requires code repo indexing):
+3. Code navigation (requires code repo indexing, dual addressing via target):
    find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path,
-   package_imports, version_diff, list_package_files, grep_package_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.
-
-4. Repository (full repo scope, not package-filtered):
-   fetch_code_context
-   Uses repo_url (get from package_summary) + git_ref (version tag) + file_path. Operates on the full repository, not filtered to a package subdirectory.
+   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, the response includes an indexingRef — use indexing_status to poll progress, then retry the original query when status is INDEXED.
 
-Scope — package vs repository:
-Package code tools (group 3) are scoped to a single package. In monorepos, they return only data from that package's subdirectory. fetch_code_context (group 4) operates on the full repository. symbol_callers/symbol_callees can show cross-package results from other indexed packages.
+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_package_file: single file, pattern match → when you know the file path
+- grep_file: single file, pattern match → when you know the file path
 
-Utility: trigger_indexing (pre-warm indexes), search_status (poll async search).
+Utility: trigger_indexing (pre-warm indexes), search_status (poll async search), indexing_status (poll navigation indexing).
 
-Quick start: find_symbol(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.
+Quick start: find_symbol(target={registry:"npm", package_name:"<pkg>"}, name="<function>", include_code=true) often answers the question in one call.
 
 Common workflows (pass symbolRef between tools for chaining):
-- Read source: find_symbol(name=<fn>, include_code=true)
+- 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: package_summary → fetch_code_context(repo_url, git_ref, file_path)
-- Search code: search_symbols (single pkg, feeds callers/callees) or search(mode='code', packages=[...]) (multi-pkg)
+- 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', targets=[...]) (multi-target)
 - Browse docs: list_package_docs → fetch_package_doc(page_id)`;
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
@@ -7912,7 +8250,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,
@@ -7923,11 +8261,12 @@ 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_package_files: ({ pkgseerService }) => createListPackageFilesTool(pkgseerService),
-  grep_package_file: ({ pkgseerService }) => createGrepPackageFileTool(pkgseerService),
+  indexing_status: ({ pkgseerService }) => createIndexingStatusTool(pkgseerService),
+  list_files: ({ pkgseerService }) => createListFilesTool(pkgseerService),
+  grep_file: ({ pkgseerService }) => createGrepFileTool(pkgseerService),
   version_diff: ({ pkgseerService }) => createVersionDiffTool(pkgseerService)
 };
 var PUBLIC_READ_TOOLS = [
@@ -7940,24 +8279,25 @@ 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_package_files",
-  "grep_package_file",
+  "indexing_status",
+  "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));
@@ -8017,19 +8357,20 @@ function showMcpSetupInstructions(deps) {
   console.log("Alternative: Use CLI directly (no MCP setup needed)");
   console.log(`  ${highlight("pkgseer pkg info <package>", useColors)}`);
 }
-function registerMcpCommand(program) {
-  const mcpCommand = program.command("mcp").summary("Show setup instructions or start MCP server").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
+var MCP_COMMAND_DESCRIPTION = `Start the Model Context Protocol (MCP) server using STDIO transport.
 
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools (22):
+Available tools (23):
   Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-  Browse files: list_package_files, grep_package_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, indexing_status, search_status, list_imports`;
+function registerMcpCommand(program) {
+  const mcpCommand = program.command("mcp").summary("Show setup instructions or start MCP server").description(MCP_COMMAND_DESCRIPTION).action(async () => {
     const deps = await createContainer();
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions(deps);