@pkgseer/cli 0.4.10 → 0.4.11

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-5nhq42tx.js";
+} from "./shared/chunk-r3pnzy5b.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -1643,6 +1643,8 @@ var TOOL_NAMES = [
   "search_status",
   "fetch_code_context",
   "search_project_docs",
+  "list_package_files",
+  "grep_package_file",
   "find_symbol",
   "search_symbols",
   "list_symbols",
@@ -1651,8 +1653,6 @@ var TOOL_NAMES = [
   "package_imports",
   "call_path",
   "trigger_indexing",
-  "list_repo_files",
-  "grep_repo_file",
   "version_diff"
 ];
 var ToolNameSchema = z.enum(TOOL_NAMES);
@@ -2749,8 +2749,8 @@ function outputError(message, json) {
 }
 var CLI_HINTS = {
   being_indexed: " Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).",
-  timeout: " Hint: lower the limit or narrow the scope, then retry.",
-  not_found: " Hint: verify the name/registry and that the resource exists.",
+  timeout: " Hint: this may be transient — retry the same command. If the issue persists, try simplifying the query.",
+  not_found: " Hint: verify the package name and registry are correct.",
   auth: " Hint: check login or token validity (pkgseer auth-status).",
   rate_limit: " Hint: wait and retry, or reduce request frequency.",
   unknown: ""
@@ -3007,14 +3007,10 @@ async function codeCalleesAction(symbolArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.symbolDependencies) {
-    outputError("Symbol not found. Verify the symbol reference or use --ref.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.symbolDependencies, true);
+    output(result.data.symbolDependencies, true);
   } else {
-    console.log(formatCalleesResult(result.data?.symbolDependencies));
+    console.log(formatCalleesResult(result.data.symbolDependencies));
   }
 }
 var CALLEES_DESCRIPTION = `Find what a symbol calls.
@@ -3058,14 +3054,10 @@ async function codeCallersAction(symbolArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.symbolDependents) {
-    outputError("Symbol not found. Verify the symbol reference or use --ref.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.symbolDependents, true);
+    output(result.data.symbolDependents, true);
   } else {
-    console.log(formatCallersResult(result.data?.symbolDependents));
+    console.log(formatCallersResult(result.data.symbolDependents));
   }
 }
 var CALLERS_DESCRIPTION = `Find what calls a symbol.
@@ -3130,14 +3122,10 @@ async function codeDiffAction(packageArg, fromVersion, toVersion, options, deps)
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.versionDiff) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.versionDiff, true);
+    output(result.data.versionDiff, true);
   } else {
-    console.log(formatDiffResult(result.data?.versionDiff));
+    console.log(formatDiffResult(result.data.versionDiff));
   }
 }
 var DIFF_DESCRIPTION = `Compare symbols between two package versions.
@@ -3190,11 +3178,7 @@ async function codeFilesAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.listRepoFiles) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.listRepoFiles;
+  const data = result.data.listRepoFiles;
   if (options.json) {
     output(data, true);
   } else {
@@ -3255,11 +3239,7 @@ async function codeFindAction(packageArg, nameArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.findSymbol) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.findSymbol;
+  const data = result.data.findSymbol;
   if (options.json) {
     output(data, true);
   } else {
@@ -3329,11 +3309,7 @@ async function codeGrepAction(packageArg, filePath, pattern, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.grepRepoFile) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.grepRepoFile;
+  const data = result.data.grepRepoFile;
   if (options.json) {
     output(data, true);
   } else {
@@ -3416,14 +3392,10 @@ async function codeImportsAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.packageImports) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.packageImports, true);
+    output(result.data.packageImports, true);
   } else {
-    console.log(formatImportsResult(result.data?.packageImports));
+    console.log(formatImportsResult(result.data.packageImports));
   }
 }
 var IMPORTS_DESCRIPTION = `List import statements in a package.
@@ -3485,14 +3457,10 @@ async function codeListAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.listSymbols) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.listSymbols, true);
+    output(result.data.listSymbols, true);
   } else {
-    console.log(formatListResult(result.data?.listSymbols));
+    console.log(formatListResult(result.data.listSymbols));
   }
 }
 var LIST_DESCRIPTION = `Browse symbols in a package.
@@ -3550,14 +3518,10 @@ async function codePathAction(fromArg, toArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.callPath) {
-    outputError("Could not find call path. Verify the symbol references.", options.json ?? false);
-    return;
-  }
   if (options.json) {
-    output(result.data?.callPath, true);
+    output(result.data.callPath, true);
   } else {
-    console.log(formatPathResult(result.data?.callPath));
+    console.log(formatPathResult(result.data.callPath));
   }
 }
 var PATH_DESCRIPTION = `Find call path between two symbols.
@@ -3630,11 +3594,7 @@ async function codeSearchAction(packageArg, query, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data?.searchSymbols) {
-    outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
-    return;
-  }
-  const data = result.data?.searchSymbols;
+  const data = result.data.searchSymbols;
   if (options.json) {
     output(data, true);
   } else {
@@ -5118,7 +5078,7 @@ async function setupCodexViaCli(shellService) {
 }
 function showAvailableTools(hasProject, useColors) {
   console.log(`
-Available MCP tools (21):`);
+Available MCP tools (22):`);
   console.log("");
   console.log("  Navigate source:");
   console.log("    • find_symbol - Read source code of functions/classes");
@@ -5129,8 +5089,8 @@ Available MCP tools (21):`);
   console.log("    • call_path - Find call path between two functions");
   console.log("");
   console.log("  Browse files:");
-  console.log("    • list_repo_files - Explore package file structure");
-  console.log("    • grep_repo_file - Search for patterns in source files");
+  console.log("    • list_package_files - Explore package file structure");
+  console.log("    • grep_package_file - Search for patterns in source files");
   console.log("    • fetch_code_context - Read source by file path and line range");
   console.log("");
   console.log("  Search & docs:");
@@ -6782,9 +6742,9 @@ function toListScope(scope) {
 var schemas = {
   registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).describe("Package registry (npm, pypi, hex, crates, nuget, maven, zig, or vcpkg)"),
   packageName: z2.string().max(255).describe("Name of the package"),
-  version: z2.string().max(100).optional().describe("Specific version (defaults to latest)"),
+  version: z2.string().max(100).optional().describe("Specific version, e.g. '4.18.2' (defaults to latest)"),
   navigationMode: z2.enum(["summary", "detailed"]).optional().describe("Response detail level. summary (default) returns core fields; detailed adds all optional fields."),
-  waitTimeoutMs: z2.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000). 0 = error immediately if not indexed."),
+  waitTimeoutMs: z2.coerce.number().int().min(0).max(30000).optional().describe("Max milliseconds to wait for package indexing (0-30000, default 10000). Set 0 to error immediately if not indexed."),
   symbolReference: z2.object({
     symbol_ref: z2.string().optional().describe("Compound symbol reference (registry:package:version:id) from find_symbol or list_symbols results. Self-contained — no additional fields needed."),
     registry: z2.enum(["npm", "pypi", "hex", "crates", "nuget", "maven", "zig", "vcpkg"]).optional().describe("Package registry (required for name-based lookup)"),
@@ -6800,9 +6760,10 @@ function toSymbolReferenceInput(ref) {
     symbolName: ref.symbol_name
   };
 }
+var DEFAULT_WAIT_TIMEOUT_MS2 = 1e4;
 var MCP_HINTS = {
   being_indexed: "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).",
-  timeout: "Hint: try lowering the limit or narrowing the scope, then retry."
+  timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
 function buildHintedMessage(operation, message) {
   const kind = classifyError(message);
@@ -6830,9 +6791,9 @@ function buildHintedMessage(operation, message) {
   return `Failed to ${operation}: ${message}`;
 }
 var MCP_GRAPHQL_HINTS = {
-  not_found: "Hint: verify the name/registry and that the resource exists.",
+  not_found: "Hint: verify the package name and registry are correct.",
   being_indexed: "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).",
-  timeout: "Hint: try lowering the limit or narrowing the scope, then retry."
+  timeout: "Hint: this may be transient — retry the same query. If the issue persists, try simplifying the query."
 };
 function handleGraphQLErrors(errors) {
   if (errors && errors.length > 0) {
@@ -6852,14 +6813,14 @@ async function withErrorHandling(operation, fn) {
   }
 }
 function notFoundError(packageName, registry) {
-  return errorResult(`Package not found: ${packageName} in ${registry}`);
+  return errorResult(`Package not found: ${packageName} in ${registry}. Verify the package name and registry are correct.`);
 }
 
 // src/tools/call-path.ts
 var argsSchema = {
   from: schemas.symbolReference.describe("Source symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
   to: schemas.symbolReference.describe("Destination symbol. Provide either symbol_ref or registry + package_name + symbol_name."),
-  max_depth: z3.number().int().min(1).max(10).optional().describe("Maximum path length to search (max hops between from and to)"),
+  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
 };
@@ -6882,15 +6843,12 @@ function createCallPathTool(pkgseerService) {
         const result = await pkgseerService.callPath(fromInput, toInput, {
           maxDepth: args.max_depth,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.callPath) {
-          return errorResult("Could not find call path. Verify the symbols exist and the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.callPath, null, 2));
+        return textResult(JSON.stringify(result.data.callPath, null, 2));
       });
     }
   };
@@ -6908,7 +6866,7 @@ var argsSchema2 = {
 function createComparePackagesTool(pkgseerService) {
   return {
     name: "compare_packages",
-    description: "Compare 2-10 packages side-by-side. Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
+    description: "Compare 2-10 packages side-by-side (available immediately — no indexing required). " + "Use this when evaluating alternatives (e.g., react vs preact vs solid-js). " + "Returns for each package: quality score, download counts, vulnerability count, license, and latest version. " + "Supports cross-registry comparison (npm, pypi, hex, crates). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
     schema: argsSchema2,
     annotations: { readOnlyHint: true },
     handler: async ({ packages }, _extra) => {
@@ -6933,16 +6891,22 @@ function createComparePackagesTool(pkgseerService) {
 // src/tools/fetch-code-context.ts
 import { z as z5 } from "zod";
 var argsSchema3 = {
-  repo_url: z5.string().min(1).describe("Repository URL (GitHub). Example: https://github.com/expressjs/express"),
-  git_ref: z5.string().min(1).describe("Git reference (tag, commit, or branch). Example: v4.18.2"),
-  file_path: z5.string().min(1).describe("Path to file in repository. Example: src/router/index.js"),
-  start_line: z5.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
-  end_line: z5.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file.")
+  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, git_ref, and file_path.",
+    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) => {
@@ -6970,7 +6934,7 @@ var argsSchema4 = {
 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.",
+    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,
     annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
@@ -7006,14 +6970,14 @@ var argsSchema5 = {
   public_only: z7.boolean().optional().describe("Only return public/exported symbols"),
   version: schemas.version,
   include_code: z7.boolean().optional().describe("Include source code in results"),
-  context_lines: z7.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
+  context_lines: z7.coerce.number().int().min(0).max(30).optional().describe("Lines of surrounding context when include_code=true (max 30)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Read source code of any function, class, or method in a third-party package — " + "use instead of guessing implementations from training data. " + "Set include_code=true for full source inline. " + "Returns: symbol ref, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
+    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,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
@@ -7027,15 +6991,12 @@ function createFindSymbolTool(pkgseerService) {
           includeCode: args.include_code,
           contextLines: args.context_lines,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.findSymbol) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.findSymbol;
+        const data = result.data.findSymbol;
         if (data.symbols.length === 0 && data.diagnostics?.hint) {
           return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
@@ -7044,39 +7005,36 @@ function createFindSymbolTool(pkgseerService) {
     }
   };
 }
-// src/tools/grep-repo-file.ts
+// 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.number().int().min(0).max(10).optional().describe("Lines of context around each match (max 10)"),
-  max_matches: z8.number().int().min(1).max(200).optional().describe("Maximum matches to return (max 200)"),
+  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,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createGrepRepoFileTool(pkgseerService) {
+function createGrepPackageFileTool(pkgseerService) {
   return {
-    name: "grep_repo_file",
-    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Case-insensitive substring matching with context lines. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover file paths.",
+    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,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("grep repo file", async () => {
+      return withErrorHandling("grep package file", async () => {
         const result = await pkgseerService.grepRepoFile(toGraphQLRegistry(args.registry), args.package_name, args.file_path, args.pattern, {
           contextLines: args.context_lines,
           maxMatches: args.max_matches,
           version: args.version,
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.grepRepoFile) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.grepRepoFile;
+        const data = result.data.grepRepoFile;
         if (data.matches.length === 0 && data.diagnostics?.hint) {
           return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
@@ -7094,7 +7052,7 @@ var argsSchema7 = {
 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.",
+    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,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
@@ -7111,37 +7069,34 @@ function createListPackageDocsTool(pkgseerService) {
     }
   };
 }
-// src/tools/list-repo-files.ts
+// src/tools/list-package-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,
   path_prefix: z9.string().optional().describe("Filter to files under this path (e.g., 'src/')"),
-  limit: z9.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
+  limit: z9.coerce.number().int().min(1).max(1000).optional().describe("Max files to return (max 1000)"),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
-function createListRepoFilesTool(pkgseerService) {
+function createListPackageFilesTool(pkgseerService) {
   return {
-    name: "list_repo_files",
-    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals.",
+    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,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
-      return withErrorHandling("list repo files", async () => {
+      return withErrorHandling("list package files", async () => {
         const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
           version: args.version,
           pathPrefix: args.path_prefix,
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listRepoFiles) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.listRepoFiles;
+        const data = result.data.listRepoFiles;
         if (data.files.length === 0 && data.diagnostics?.hint) {
           return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
         }
@@ -7160,7 +7115,7 @@ var argsSchema9 = {
   namespace: z10.string().max(500).optional().describe("Filter by namespace prefix (e.g., 'React' to see React.*)"),
   public_only: z10.boolean().optional().describe("Only return public symbols"),
   include_popularity: z10.boolean().optional().describe("Include callerCount for each symbol (slightly slower)"),
-  limit: z10.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
+  limit: z10.coerce.number().int().min(1).max(100).optional().describe("Max symbols to return (max 100)"),
   version: schemas.version,
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -7193,15 +7148,12 @@ function createListSymbolsTool(pkgseerService) {
           limit: args.limit,
           version: args.version,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.listSymbols) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.listSymbols, null, 2));
+        return textResult(JSON.stringify(result.data.listSymbols, null, 2));
       });
     }
   };
@@ -7213,7 +7165,7 @@ var argsSchema10 = {
   package_name: schemas.packageName.describe("Name of the package to retrieve dependencies for"),
   version: schemas.version,
   include_transitive: z11.boolean().optional().describe("Whether to include transitive dependency DAG"),
-  max_depth: z11.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+  max_depth: z11.coerce.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
 function decodeDag(rawDag) {
   if (!rawDag || typeof rawDag !== "object")
@@ -7336,7 +7288,7 @@ var argsSchema11 = {
   package_name: schemas.packageName.describe("Name of the package to get imports for"),
   file_path: z12.string().max(1000).optional().describe("Filter to a specific file path"),
   resolved_only: z12.boolean().optional().describe("Only return imports resolved to a known package"),
-  limit: z12.number().int().min(1).max(500).optional().describe("Max imports to return"),
+  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
@@ -7355,15 +7307,12 @@ function createPackageImportsTool(pkgseerService) {
           limit: args.limit,
           version: args.version,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.packageImports) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.packageImports, null, 2));
+        return textResult(JSON.stringify(result.data.packageImports, null, 2));
       });
     }
   };
@@ -7377,7 +7326,7 @@ var argsSchema12 = {
 function createPackageQualityTool(pkgseerService) {
   return {
     name: "package_quality",
-    description: "Evaluate package maintenance health and code quality. Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
+    description: "Evaluate package maintenance health and code quality (available immediately — no indexing required). " + "Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
     schema: argsSchema12,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
@@ -7402,7 +7351,7 @@ var argsSchema13 = {
 function createPackageSummaryTool(pkgseerService) {
   return {
     name: "package_summary",
-    description: "Get a comprehensive overview of a package. Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details).",
+    description: "Get a comprehensive overview of a package (available immediately — no indexing required). " + "Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details). " + "Use package.repositoryUrl + package.latestVersion as git_ref with fetch_code_context to read source files.",
     schema: argsSchema13,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name }, _extra) => {
@@ -7428,7 +7377,7 @@ var argsSchema14 = {
 function createPackageVulnerabilitiesTool(pkgseerService) {
   return {
     name: "package_vulnerabilities",
-    description: "Check security vulnerabilities for a package. Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
+    description: "Check security vulnerabilities for a package (available immediately — no indexing required). " + "Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
     schema: argsSchema14,
     annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
@@ -7452,13 +7401,16 @@ var packageInputSchema2 = z13.object({
   name: z13.string().min(1).describe("Package name"),
   version: z13.string().optional().describe("Specific version (defaults to latest)")
 });
-var DEFAULT_AGENT_WAIT_TIMEOUT_MS = 1e4;
 var argsSchema15 = {
-  packages: z13.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
-  query: z13.string().min(1).describe("Search query - natural language or keywords"),
+  packages: z13.array(packageInputSchema2, {
+    error: 'packages is required. Provide 1-20 packages as [{registry: "npm", name: "express"}]. ' + "Use package_summary to verify a package exists. " + "For project-wide doc search without specifying packages, use search_project_docs instead."
+  }).min(1).max(20).describe('Packages to search (1-20). Format: [{"registry":"npm","name":"express"}]'),
+  query: z13.string({
+    error: "query is required. Provide search terms as natural language or keywords, " + "e.g., 'error handling middleware'."
+  }).min(1).describe("Search query - natural language or keywords"),
   mode: z13.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
-  limit: z13.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
-  waitTimeoutMs: z13.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
+  limit: z13.coerce.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)"),
+  waitTimeoutMs: z13.coerce.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing (default: 10000, 0=immediate)")
 };
 function toSearchMode2(mode) {
   if (!mode)
@@ -7496,7 +7448,7 @@ Results may be incomplete. Retry later for more complete results.`;
 function createSearchTool(pkgseerService) {
   return {
     name: "search",
-    description: "Search code and documentation across packages. Returns functions, classes, and doc pages " + "matching your query. Use mode='code' for code only, mode='docs' for docs only, or " + "mode='all' (default). Provide 1-20 packages. Results include relevance scores and snippets. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
+    description: "Search code and documentation across packages using full-text search. " + "Returns code chunks and doc pages matching your query with relevance scores and snippets. " + "Use mode='code' for code only, mode='docs' for docs only, or mode='all' (default). " + "Provide 1-20 packages. For symbol-level results that feed into symbol_callers/symbol_callees, " + "use search_symbols instead. " + "For full source of code results, use find_symbol(name=<title>, include_code=true). " + "Code results include repoUrl and filePath for use with fetch_code_context. " + "If packages need indexing, waits up to waitTimeoutMs (default 10s) or returns searchRef — use search_status to poll.",
     schema: argsSchema15,
     annotations: { readOnlyHint: true },
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
@@ -7513,7 +7465,7 @@ function createSearchTool(pkgseerService) {
         const result = await pkgseerService.combinedSearch(graphqlPackages, normalizedQuery, {
           mode: toSearchMode2(mode),
           limit,
-          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_AGENT_WAIT_TIMEOUT_MS
+          waitTimeoutMs: waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
@@ -7557,7 +7509,7 @@ var argsSchema16 = {
   terms: z14.array(z14.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
   match_mode: z14.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
   include_snippets: z14.boolean().optional().describe("Include content excerpts around matches"),
-  limit: z14.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
+  limit: z14.coerce.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
 function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
@@ -7582,7 +7534,9 @@ function createSearchProjectDocsTool(deps) {
           return errorResult(`No project specified and no pkgseer.yml found. To fix:
 ` + `  1. Pass project_directory: '/path/to/project' (folder containing pkgseer.yml)
 ` + `  2. Pass project: 'project-name' directly if you know the project name
-` + "  3. Run 'pkgseer project init' to create pkgseer.yml in your project");
+` + `  3. Run 'pkgseer project init' to create pkgseer.yml in your project
+
+` + "Or use search(mode='docs', packages=[{registry: 'npm', name: '...'}]) to search " + "specific packages without a project.");
         }
         const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
         if (normalizedTerms.length === 0) {
@@ -7679,14 +7633,14 @@ var argsSchema18 = {
   ]).optional().describe("Filter results by code chunk type"),
   file_path: z16.string().optional().describe("Filter results to files whose path starts with this value (e.g., 'src/' for a directory)"),
   version: schemas.version,
-  limit: z16.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
+  limit: z16.coerce.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Search a dependency's source code by text — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns matching code chunks with name, type, file path, line numbers, and content previews. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source.",
+    description: "Search a dependency's source code by text using the code navigation index — " + "find where error messages, exceptions, or patterns appear across functions, classes, and modules. " + "Supports query string or keyword list with match_mode. " + "Use file_path to filter by directory (e.g., 'src/'). " + "Returns symbol-level results that can feed directly into symbol_callers, symbol_callees, or call_path. " + "Follow up with find_symbol(name=<result.name>, include_code=true) for full source. " + "For free-form text search across multiple packages, use search(mode='code') instead.",
     schema: argsSchema18,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
@@ -7700,15 +7654,12 @@ function createSearchSymbolsTool(pkgseerService) {
           version: args.version,
           limit: args.limit,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.searchSymbols) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        const data = result.data?.searchSymbols;
+        const data = result.data.searchSymbols;
         const extra = {};
         if (data.results.length === 0 && data.diagnostics?.hint) {
           extra._hint = data.diagnostics.hint;
@@ -7728,9 +7679,9 @@ function createSearchSymbolsTool(pkgseerService) {
 import { z as z17 } from "zod";
 var argsSchema19 = {
   symbol: schemas.symbolReference.describe("Symbol to find callees for. Provide either symbol_ref or registry + package_name + symbol_name."),
-  max_depth: z17.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
-  limit: z17.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
-  include_external: z17.boolean().optional().describe("Include calls to symbols in other packages"),
+  max_depth: z17.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callees only, 2+ = transitive, max 5)"),
+  limit: z17.coerce.number().int().min(1).max(100).optional().describe("Maximum dependency entries to return"),
+  include_external: z17.boolean().optional().describe("Include calls to symbols in other indexed packages. " + "Default (false) shows only calls within the same package."),
   include_builtins: z17.boolean().optional().describe("Include calls to built-in/standard library functions (console, Math, etc.)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -7753,15 +7704,12 @@ function createSymbolCalleesTool(pkgseerService) {
           includeExternal: args.include_external,
           includeBuiltins: args.include_builtins,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.symbolDependencies) {
-          return errorResult("Symbol not found. Verify the symbol reference and that the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.symbolDependencies, null, 2));
+        return textResult(JSON.stringify(result.data.symbolDependencies, null, 2));
       });
     }
   };
@@ -7770,16 +7718,16 @@ function createSymbolCalleesTool(pkgseerService) {
 import { z as z18 } from "zod";
 var argsSchema20 = {
   symbol: schemas.symbolReference.describe("Symbol to find callers for. Provide either symbol_ref or registry + package_name + symbol_name."),
-  same_package_only: z18.boolean().optional().describe("Only return callers from the same package"),
-  max_depth: z18.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
-  limit: z18.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
+  same_package_only: z18.boolean().optional().describe("Only return callers from the same package. " + "Default (false) includes callers from other indexed packages."),
+  max_depth: z18.coerce.number().int().min(1).max(5).optional().describe("BFS traversal depth (1 = direct callers only, 2+ = transitive, max 5)"),
+  limit: z18.coerce.number().int().min(1).max(100).optional().describe("Maximum entries to return"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse.",
+    description: "Trace what calls a function in a dependency's source code — " + "find entry points or debug why behavior triggers. " + "Returns callers with file locations and call line numbers. " + "Use same_package_only for within-package callers only. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callees for the reverse. " + "Use find_symbol(include_code=true) on any caller to read its source.",
     schema: argsSchema20,
     annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
@@ -7793,15 +7741,12 @@ function createSymbolCallersTool(pkgseerService) {
           maxDepth: args.max_depth,
           maxResults: args.limit,
           mode: toNavigationMode(args.mode),
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.symbolDependents) {
-          return errorResult("Symbol not found. Verify the symbol reference and that the package is indexed.");
-        }
-        return textResult(JSON.stringify(result.data?.symbolDependents, null, 2));
+        return textResult(JSON.stringify(result.data.symbolDependents, null, 2));
       });
     }
   };
@@ -7825,7 +7770,7 @@ var argsSchema21 = {
 function createTriggerIndexingTool(pkgseerService) {
   return {
     name: "trigger_indexing",
-    description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search requests to ensure packages are indexed. " + "Rate limited to 10 requests per minute.",
+    description: "Pre-warm PkgSeer indexes by triggering indexing for packages and/or repositories. " + "Fire-and-forget: triggers jobs and returns immediately with accepted/skipped counts. " + "Use before search or doc requests to ensure packages are indexed. " + "Code tools auto-wait via wait_timeout_ms on subsequent calls. Most packages index within 10-30s. " + "Rate limited to 10 requests per minute.",
     schema: argsSchema21,
     annotations: { readOnlyHint: false, idempotentHint: true },
     handler: async (args, _extra) => {
@@ -7880,7 +7825,7 @@ var argsSchema22 = {
     "type",
     "doc_section"
   ]).optional().describe("Filter by symbol kind"),
-  limit: z20.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
+  limit: z20.coerce.number().int().min(1).max(500).optional().describe("Max changes to return (max 500). Summary always reflects full counts."),
   wait_timeout_ms: schemas.waitTimeoutMs
 };
 function createVersionDiffTool(pkgseerService) {
@@ -7895,15 +7840,12 @@ function createVersionDiffTool(pkgseerService) {
           includePrivate: args.include_private,
           kind: toSymbolKind(args.kind),
           limit: args.limit,
-          waitTimeoutMs: args.wait_timeout_ms
+          waitTimeoutMs: args.wait_timeout_ms ?? DEFAULT_WAIT_TIMEOUT_MS2
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data?.versionDiff) {
-          return notFoundError(args.package_name, args.registry);
-        }
-        return textResult(JSON.stringify(result.data?.versionDiff, null, 2));
+        return textResult(JSON.stringify(result.data.versionDiff, null, 2));
       });
     }
   };
@@ -7919,18 +7861,47 @@ Use PkgSeer when:
 - You need to understand what changed between package versions
 
 Instead of guessing library behavior from training data, use find_symbol(include_code=true) to read actual source.
-Instead of cloning repos to search code, use search_symbols or grep_repo_file.
+Instead of cloning repos to search code, use search_symbols or grep_package_file.
 Instead of manually tracing call chains on GitHub, use symbol_callers and symbol_callees.
 
-Tool groups:
-- Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-- Browse files: list_repo_files, grep_repo_file, fetch_code_context
-- Search across packages: search, search_project_docs
-- Browse docs: list_package_docs, fetch_package_doc
-- Evaluate: package_summary, package_quality, package_vulnerabilities, compare_packages, package_dependencies, version_diff
-- Utility: trigger_indexing, search_status, package_imports
+Data availability — tools are grouped by what backend data they need:
+
+1. Registry metadata (available immediately, no indexing):
+   package_summary, package_quality, package_vulnerabilities, package_dependencies, compare_packages
+   Start here when researching a package — these always work instantly.
+
+2. Documentation (requires doc site crawling):
+   list_package_docs, fetch_package_doc, search(mode='docs'), search_project_docs
+   If results are empty, docs may not be crawled yet — use trigger_indexing first, then retry.
+
+3. Package code (requires code repo indexing):
+   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.
+
+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.
+
+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
+
+Utility: trigger_indexing (pre-warm indexes), search_status (poll async search).
+
+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(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.`;
+Common workflows (pass symbolRef between tools for chaining):
+- Read source: find_symbol(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)
+- Browse docs: list_package_docs → fetch_package_doc(page_id)`;
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
   package_vulnerabilities: ({ pkgseerService }) => createPackageVulnerabilitiesTool(pkgseerService),
@@ -7955,8 +7926,8 @@ var TOOL_FACTORIES = {
   package_imports: ({ pkgseerService }) => createPackageImportsTool(pkgseerService),
   call_path: ({ pkgseerService }) => createCallPathTool(pkgseerService),
   trigger_indexing: ({ pkgseerService }) => createTriggerIndexingTool(pkgseerService),
-  list_repo_files: ({ pkgseerService }) => createListRepoFilesTool(pkgseerService),
-  grep_repo_file: ({ pkgseerService }) => createGrepRepoFileTool(pkgseerService),
+  list_package_files: ({ pkgseerService }) => createListPackageFilesTool(pkgseerService),
+  grep_package_file: ({ pkgseerService }) => createGrepPackageFileTool(pkgseerService),
   version_diff: ({ pkgseerService }) => createVersionDiffTool(pkgseerService)
 };
 var PUBLIC_READ_TOOLS = [
@@ -7978,8 +7949,8 @@ var PUBLIC_READ_TOOLS = [
   "package_imports",
   "call_path",
   "trigger_indexing",
-  "list_repo_files",
-  "grep_repo_file",
+  "list_package_files",
+  "grep_package_file",
   "version_diff"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];
@@ -8052,9 +8023,9 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools (21):
+Available tools (22):
   Navigate source: find_symbol, list_symbols, search_symbols, symbol_callers, symbol_callees, call_path
-  Browse files: list_repo_files, grep_repo_file, fetch_code_context
+  Browse files: list_package_files, grep_package_file, fetch_code_context
   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

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-5nhq42tx.js";
+} from "./shared/chunk-r3pnzy5b.js";
 export {
   version
 };

package/dist/shared/{chunk-5nhq42tx.js → chunk-r3pnzy5b.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.4.10";
+var version = "0.4.11";
 
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pkgseer/cli",
   "description": "CLI companion for PkgSeer - package intelligence for developers and AI assistants",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "type": "module",
   "files": [
     "dist",