@pkgseer/cli 0.4.3 → 0.4.8

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-d3mfgdr9.js";
+} from "./shared/chunk-edcjw6wf.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -670,7 +670,7 @@ var FindSymbolDocument = gql`
     waitTimeoutMs: $waitTimeoutMs
   ) {
     symbols {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -720,7 +720,7 @@ var SearchSymbolsDocument = gql`
       contentPreview
       code
       language
-      symbolId
+      symbolRef
       qualifiedPath
       kind
       arity
@@ -757,7 +757,7 @@ var ListSymbolsDocument = gql`
     waitTimeoutMs: $waitTimeoutMs
   ) {
     symbols {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -779,7 +779,7 @@ var ListSymbolsDocument = gql`
 }
     `;
 var SymbolDependenciesDocument = gql`
-    query SymbolDependencies($symbol: SymbolReferenceInput!, $maxDepth: Int, $maxResults: Int, $includeExternal: Boolean, $includeBuiltins: Boolean, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query SymbolDependencies($symbol: SymbolReferenceInput!, $maxDepth: Int, $maxResults: Int, $includeExternal: Boolean, $includeBuiltins: Boolean, $mode: NavigationMode, $waitTimeoutMs: Int, $version: String) {
   symbolDependencies(
     symbol: $symbol
     maxDepth: $maxDepth
@@ -788,14 +788,15 @@ var SymbolDependenciesDocument = gql`
     includeBuiltins: $includeBuiltins
     mode: $mode
     waitTimeoutMs: $waitTimeoutMs
+    version: $version
   ) {
     root {
-      symbolId
+      symbolRef
       name
       qualifiedPath
     }
     dependencies {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -817,21 +818,22 @@ var SymbolDependenciesDocument = gql`
 }
     `;
 var SymbolDependentsDocument = gql`
-    query SymbolDependents($symbol: SymbolReferenceInput!, $samePackageOnly: Boolean, $maxResults: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
+    query SymbolDependents($symbol: SymbolReferenceInput!, $samePackageOnly: Boolean, $maxResults: Int, $maxDepth: Int, $mode: NavigationMode, $waitTimeoutMs: Int) {
   symbolDependents(
     symbol: $symbol
     samePackageOnly: $samePackageOnly
     maxResults: $maxResults
+    maxDepth: $maxDepth
     mode: $mode
     waitTimeoutMs: $waitTimeoutMs
   ) {
     target {
-      symbolId
+      symbolRef
       name
       qualifiedPath
     }
     dependents {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -887,19 +889,19 @@ var CallPathDocument = gql`
   ) {
     pathFound
     fromSymbol {
-      symbolId
+      symbolRef
       name
       qualifiedPath
     }
     toSymbol {
-      symbolId
+      symbolRef
       name
       qualifiedPath
     }
     paths {
       length
       hops {
-        symbolId
+        symbolRef
         name
         qualifiedPath
         filePath
@@ -1040,7 +1042,7 @@ var VersionDiffDocument = gql`
         endLine
         isPublic
         minArity
-        symbolId
+        symbolRef
       }
       to {
         contentHash
@@ -1050,7 +1052,7 @@ var VersionDiffDocument = gql`
         endLine
         isPublic
         minArity
-        symbolId
+        symbolRef
       }
     }
     hasMore
@@ -1219,7 +1221,7 @@ function createClient(apiToken) {
   if (apiToken) {
     headers.Authorization = `Bearer ${apiToken}`;
   }
-  const client = new GraphQLClient(apiUrl, { headers });
+  const client = new GraphQLClient(apiUrl, { headers, errorPolicy: "all" });
   return getSdk(client);
 }
 
@@ -1392,7 +1394,7 @@ class AuthStorageImpl {
     this.configDir = configDir ?? fs.joinPath(fs.getHomeDir(), CONFIG_DIR);
     this.authPath = fs.joinPath(this.configDir, AUTH_FILE);
   }
-  getPath() {
+  getStorageLocation() {
     return this.authPath;
   }
   async load(baseUrl) {
@@ -1512,6 +1514,117 @@ class BrowserServiceImpl {
     await open(url);
   }
 }
+// src/services/chunking-keyring-service.ts
+var WINDOWS_MAX_ENTRY_SIZE = 1200;
+var CHUNKED_PREFIX = "CHUNKED:";
+var MAX_CHUNK_COUNT = 100;
+function chunkKey(account, writeId, index) {
+  return `${account}:chunk:${writeId}:${index}`;
+}
+function parseChunkedSentinel(value) {
+  if (!value.startsWith(CHUNKED_PREFIX))
+    return null;
+  const rest = value.slice(CHUNKED_PREFIX.length);
+  const colonIndex = rest.indexOf(":");
+  if (colonIndex === -1)
+    return null;
+  const writeId = rest.slice(0, colonIndex);
+  if (writeId.length === 0)
+    return null;
+  const countStr = rest.slice(colonIndex + 1);
+  const count = Number(countStr);
+  if (!Number.isInteger(count) || count <= 0)
+    return null;
+  return { writeId, count };
+}
+function splitIntoChunks(value, maxSize) {
+  if (value.length === 0)
+    return [""];
+  const chunks = [];
+  for (let offset = 0;offset < value.length; offset += maxSize) {
+    chunks.push(value.slice(offset, offset + maxSize));
+  }
+  return chunks;
+}
+function generateWriteId() {
+  let id;
+  do {
+    id = Math.random().toString(36).slice(2, 8);
+  } while (id.length < 6);
+  return id;
+}
+
+class ChunkingKeyringService {
+  inner;
+  maxEntrySize;
+  constructor(inner, maxEntrySize = WINDOWS_MAX_ENTRY_SIZE) {
+    this.inner = inner;
+    this.maxEntrySize = maxEntrySize;
+  }
+  getPassword(service, account) {
+    const value = this.inner.getPassword(service, account);
+    if (value === null)
+      return null;
+    if (!value.startsWith(CHUNKED_PREFIX))
+      return value;
+    const sentinel = parseChunkedSentinel(value);
+    if (sentinel === null)
+      return null;
+    const chunks = [];
+    for (let i = 0;i < sentinel.count; i++) {
+      const chunk = this.inner.getPassword(service, chunkKey(account, sentinel.writeId, i));
+      if (chunk === null) {
+        console.error(`Warning: Incomplete chunked keychain entry for "${account}" (missing chunk ${i} of ${sentinel.count}). Treating as missing.`);
+        return null;
+      }
+      chunks.push(chunk);
+    }
+    return chunks.join("");
+  }
+  setPassword(service, account, password) {
+    const oldValue = this.readOldSentinel(service, account);
+    if (password.length <= this.maxEntrySize) {
+      this.inner.setPassword(service, account, password);
+    } else {
+      const chunks = splitIntoChunks(password, this.maxEntrySize);
+      if (chunks.length > MAX_CHUNK_COUNT) {
+        throw new Error(`Value requires ${chunks.length} chunks, exceeding maximum of ${MAX_CHUNK_COUNT}. ` + `This likely indicates a bug — credential data should not be this large.`);
+      }
+      const writeId = generateWriteId();
+      for (const [i, chunk] of chunks.entries()) {
+        this.inner.setPassword(service, chunkKey(account, writeId, i), chunk);
+      }
+      this.inner.setPassword(service, account, `${CHUNKED_PREFIX}${writeId}:${chunks.length}`);
+    }
+    if (oldValue !== null) {
+      this.deleteChunkEntries(service, account, oldValue);
+    }
+  }
+  deletePassword(service, account) {
+    const oldValue = this.readOldSentinel(service, account);
+    if (oldValue !== null) {
+      this.deleteChunkEntries(service, account, oldValue);
+    }
+    return this.inner.deletePassword(service, account);
+  }
+  readOldSentinel(service, account) {
+    try {
+      const value = this.inner.getPassword(service, account);
+      if (value === null)
+        return null;
+      return parseChunkedSentinel(value);
+    } catch {
+      return null;
+    }
+  }
+  deleteChunkEntries(service, account, sentinel) {
+    for (let i = 0;i < sentinel.count; i++) {
+      try {
+        this.inner.deletePassword(service, chunkKey(account, sentinel.writeId, i));
+      } catch {}
+    }
+  }
+}
 // src/services/config-service.ts
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { z } from "zod";
@@ -1770,6 +1883,143 @@ class GitServiceImpl {
     return existsSync(gitPath);
   }
 }
+// src/services/keychain-auth-storage.ts
+var SERVICE_NAME = "pkgseer";
+var TOKEN_PREFIX = "v1:tokens:";
+function normalizeBaseUrl2(url) {
+  return url.replace(/\/+$/, "");
+}
+function parseJsonOrNull(json) {
+  if (json === null)
+    return null;
+  try {
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== "object" || parsed === null)
+      return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isValidTokenData(data) {
+  if (typeof data !== "object" || data === null)
+    return false;
+  const d = data;
+  return typeof d.token === "string" && d.token.length > 0 && typeof d.tokenName === "string" && d.tokenName.length > 0 && Array.isArray(d.scopes) && typeof d.createdAt === "string" && d.createdAt.length > 0 && (d.expiresAt === null || typeof d.expiresAt === "string" && d.expiresAt.length > 0) && typeof d.apiKeyId === "number";
+}
+
+class KeychainAuthStorage {
+  keyring;
+  constructor(keyring) {
+    this.keyring = keyring;
+  }
+  async load(baseUrl) {
+    const key = `${TOKEN_PREFIX}${normalizeBaseUrl2(baseUrl)}`;
+    const json = this.keyring.getPassword(SERVICE_NAME, key);
+    const data = parseJsonOrNull(json);
+    if (data !== null && !isValidTokenData(data))
+      return null;
+    return data;
+  }
+  async save(baseUrl, data) {
+    const key = `${TOKEN_PREFIX}${normalizeBaseUrl2(baseUrl)}`;
+    this.keyring.setPassword(SERVICE_NAME, key, JSON.stringify(data));
+  }
+  async clear(baseUrl) {
+    const key = `${TOKEN_PREFIX}${normalizeBaseUrl2(baseUrl)}`;
+    this.keyring.deletePassword(SERVICE_NAME, key);
+  }
+  getStorageLocation() {
+    switch (process.platform) {
+      case "darwin":
+        return "macOS Keychain (pkgseer)";
+      case "win32":
+        return "Windows Credential Manager (pkgseer)";
+      default:
+        return "System keychain (pkgseer)";
+    }
+  }
+}
+// src/services/keyring-service.ts
+import { Entry } from "@napi-rs/keyring";
+
+class KeychainUnavailableError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = "KeychainUnavailableError";
+    this.cause = cause;
+  }
+}
+function wrapKeyringError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  throw new KeychainUnavailableError(`System keychain unavailable: ${message}`, error);
+}
+
+class KeyringServiceImpl {
+  getPassword(service, account) {
+    try {
+      return new Entry(service, account).getPassword();
+    } catch (error) {
+      wrapKeyringError(error);
+    }
+  }
+  setPassword(service, account, password) {
+    try {
+      new Entry(service, account).setPassword(password);
+    } catch (error) {
+      wrapKeyringError(error);
+    }
+  }
+  deletePassword(service, account) {
+    try {
+      return new Entry(service, account).deleteCredential();
+    } catch (error) {
+      wrapKeyringError(error);
+    }
+  }
+}
+// src/services/migrating-auth-storage.ts
+class MigratingAuthStorage {
+  primary;
+  legacy;
+  constructor(primary, legacy) {
+    this.primary = primary;
+    this.legacy = legacy;
+  }
+  async load(baseUrl) {
+    const tokens = await this.primary.load(baseUrl);
+    if (tokens)
+      return tokens;
+    const legacyTokens = await this.legacy.load(baseUrl);
+    if (legacyTokens) {
+      await this.primary.save(baseUrl, legacyTokens);
+      try {
+        await this.legacy.clear(baseUrl);
+      } catch {}
+      return legacyTokens;
+    }
+    return null;
+  }
+  async save(baseUrl, data) {
+    await this.primary.save(baseUrl, data);
+  }
+  async clear(baseUrl) {
+    let primaryError;
+    try {
+      await this.primary.clear(baseUrl);
+    } catch (error) {
+      primaryError = error;
+    }
+    try {
+      await this.legacy.clear(baseUrl);
+    } catch {}
+    if (primaryError)
+      throw primaryError;
+  }
+  getStorageLocation() {
+    return this.primary.getStorageLocation();
+  }
+}
 // src/services/pkgseer-service.ts
 class PkgseerServiceImpl {
   client;
@@ -2019,7 +2269,8 @@ class PkgseerServiceImpl {
       includeExternal: options?.includeExternal,
       includeBuiltins: options?.includeBuiltins,
       mode: options?.mode,
-      waitTimeoutMs: options?.waitTimeoutMs
+      waitTimeoutMs: options?.waitTimeoutMs,
+      version: options?.version
     });
     return { data: result.data, errors: result.errors };
   }
@@ -2027,6 +2278,7 @@ class PkgseerServiceImpl {
     const result = await this.client.SymbolDependents({
       symbol,
       samePackageOnly: options?.samePackageOnly,
+      maxDepth: options?.maxDepth,
       maxResults: options?.maxResults,
       mode: options?.mode,
       waitTimeoutMs: options?.waitTimeoutMs
@@ -2317,10 +2569,29 @@ async function resolveApiToken(configService, baseUrl) {
   const tokenData = await configService.getApiToken(baseUrl);
   return tokenData?.token;
 }
+function createAuthStorage(fileSystemService) {
+  const fileStorage = new AuthStorageImpl(fileSystemService);
+  try {
+    const rawKeyring = new KeyringServiceImpl;
+    const keyring = process.platform === "win32" ? new ChunkingKeyringService(rawKeyring, WINDOWS_MAX_ENTRY_SIZE) : rawKeyring;
+    const probeKey = `__probe_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    keyring.setPassword("pkgseer", probeKey, "probe");
+    try {
+      keyring.deletePassword("pkgseer", probeKey);
+    } catch {}
+    const keychainStorage = new KeychainAuthStorage(keyring);
+    return new MigratingAuthStorage(keychainStorage, fileStorage);
+  } catch (error) {
+    if (!(error instanceof KeychainUnavailableError))
+      throw error;
+    console.error("Warning: System keychain unavailable. Falling back to file-based credential storage.");
+    return fileStorage;
+  }
+}
 async function createContainer() {
   const baseUrl = getBaseUrl();
   const fileSystemService = new FileSystemServiceImpl;
-  const authStorage = new AuthStorageImpl(fileSystemService);
+  const authStorage = createAuthStorage(fileSystemService);
   const configService = new ConfigServiceImpl(fileSystemService, authStorage);
   const [apiToken, configResult] = await Promise.all([
     resolveApiToken(configService, baseUrl),
@@ -2381,7 +2652,7 @@ async function authStatusAction(deps) {
     console.log("  Expires: never");
   }
   console.log(`
-  Stored at: ${authStorage.getPath()}`);
+  Storage: ${authStorage.getStorageLocation()}`);
 }
 var STATUS_DESCRIPTION = `Show current authentication status.
 
@@ -2394,6 +2665,42 @@ function registerAuthStatusCommand(program) {
   });
 }
 
+// src/lib/error-classification.ts
+function classifyError(message) {
+  const lower = message.toLowerCase();
+  if (lower.includes("being indexed") || lower.includes("retry with waittimeoutms")) {
+    return "being_indexed";
+  }
+  if (lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out")) {
+    return "timeout";
+  }
+  if (lower.includes("not found") || lower.includes("does not exist")) {
+    return "not_found";
+  }
+  if (lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission")) {
+    return "auth";
+  }
+  if (lower.includes("rate limit") || lower.includes("too many requests")) {
+    return "rate_limit";
+  }
+  return "unknown";
+}
+
+// src/lib/registry.ts
+var REGISTRY_MAP = {
+  npm: "NPM",
+  pypi: "PYPI",
+  hex: "HEX",
+  crates: "CRATES",
+  nuget: "NUGET",
+  maven: "MAVEN",
+  zig: "ZIG",
+  vcpkg: "VCPKG"
+};
+function toGraphQLRegistry(registry) {
+  return REGISTRY_MAP[registry.toLowerCase()] || "NPM";
+}
+
 // src/commands/shared.ts
 function parsePackageSpec(spec) {
   let registry = "npm";
@@ -2425,19 +2732,6 @@ function parsePackageSpec(spec) {
   }
   return { registry, name: rest };
 }
-function toGraphQLRegistry(registry) {
-  const map = {
-    npm: "NPM",
-    pypi: "PYPI",
-    hex: "HEX",
-    crates: "CRATES",
-    nuget: "NUGET",
-    maven: "MAVEN",
-    zig: "ZIG",
-    vcpkg: "VCPKG"
-  };
-  return map[registry.toLowerCase()] || "NPM";
-}
 function output(data, json) {
   if (json) {
     console.log(JSON.stringify(data));
@@ -2453,30 +2747,20 @@ function outputError(message, json) {
   }
   process.exit(1);
 }
+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.",
+  auth: " Hint: check login or token validity (pkgseer auth-status).",
+  rate_limit: " Hint: wait and retry, or reduce request frequency.",
+  unknown: ""
+};
 function handleErrors(errors, json) {
   if (!errors || errors.length === 0)
     return;
   const combined = errors.map((e) => e.message).filter(Boolean).join(", ");
-  const lower = combined.toLowerCase();
-  const isTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
-  const isNotFound = lower.includes("not found") || lower.includes("does not exist") || lower.includes("unknown");
-  const isAuth = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission");
-  const isRateLimit = lower.includes("rate limit") || lower.includes("too many requests");
-  const isBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
-  let hint = "";
-  if (isBeingIndexed) {
-    hint = " Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).";
-  } else if (isTimeout) {
-    hint = " Hint: lower the limit or narrow the scope, then retry.";
-  } else if (isNotFound) {
-    hint = " Hint: verify the name/registry and that the resource exists.";
-  } else if (isAuth) {
-    hint = " Hint: check login or token validity (pkgseer auth-status).";
-  } else if (isRateLimit) {
-    hint = " Hint: wait and retry, or reduce request frequency.";
-  }
-  const message = `${combined}${hint}`;
-  outputError(message, json);
+  const hint = CLI_HINTS[classifyError(combined)];
+  outputError(`${combined}${hint}`, json);
 }
 function formatNumber(num) {
   if (num == null)
@@ -2565,21 +2849,10 @@ async function withCliErrorHandling(json, fn) {
       return;
     }
     const message = error instanceof Error ? error.message : "Unknown error";
-    const lower = message.toLowerCase();
-    if (lower.includes("being indexed") || lower.includes("retry with waittimeoutms")) {
-      outputError(`${message}. Hint: package is being indexed. Try again with a longer --wait value (e.g., --wait 30000).`, json);
-      return;
-    }
-    if (lower.includes("-32001") || lower.includes("timeout")) {
-      outputError(`${message}. Hint: lower the limit or narrow the scope, then retry.`, json);
-      return;
-    }
-    if (lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission")) {
-      outputError(`${message}. Hint: check login or token validity.`, json);
-      return;
-    }
-    if (lower.includes("rate limit") || lower.includes("too many requests")) {
-      outputError(`${message}. Hint: wait and retry.`, json);
+    const kind = classifyError(message);
+    const hint = CLI_HINTS[kind];
+    if (hint) {
+      outputError(`${message}.${hint}`, json);
       return;
     }
     const colonMatch = message.match(/^([^:]+):/);
@@ -2615,12 +2888,12 @@ function parseSymbolRef(spec) {
     packageName: parsed.name
   };
 }
-function buildSymbolReference(spec, id) {
-  if (id) {
-    return { symbolId: Number.parseInt(id, 10) };
+function buildSymbolReference(spec, ref) {
+  if (ref) {
+    return { symbolRef: ref };
   }
   if (!spec) {
-    throw new Error("Symbol reference required. Use registry:package#symbolName or --id <number>");
+    throw new Error("Symbol reference required. Use registry:package#symbolName or --ref <string>");
   }
   return parseSymbolRef(spec);
 }
@@ -2663,7 +2936,7 @@ function formatSymbol(symbol) {
     const loc = symbol.startLine ? `${symbol.filePath}:${symbol.startLine}` : symbol.filePath;
     parts.push(`  File: ${loc}`);
   }
-  const meta = [`id:${symbol.symbolId}`];
+  const meta = [`ref:${symbol.symbolRef}`];
   if (symbol.callerCount != null) {
     meta.push(`callers:${symbol.callerCount}`);
   }
@@ -2693,8 +2966,8 @@ function formatDependencyEntry(entry) {
   if (entry.package) {
     parts.push(`  Package: ${entry.package.registry}:${entry.package.name}`);
   }
-  if (entry.symbolId) {
-    parts.push(`  id:${entry.symbolId}`);
+  if (entry.symbolRef) {
+    parts.push(`  ref:${entry.symbolRef}`);
   }
   return parts.join(`
 `);
@@ -2703,7 +2976,7 @@ function formatDependencyEntry(entry) {
 // src/commands/code/callees.ts
 function formatCalleesResult(data) {
   const lines = [];
-  lines.push(`Callees of ${data.root.qualifiedPath ?? data.root.name} (id:${data.root.symbolId})`);
+  lines.push(`Callees of ${data.root.qualifiedPath ?? data.root.name} (ref:${data.root.symbolRef})`);
   lines.push(`${data.total} callee(s)${data.hasMore ? " (more available)" : ""}`);
   if (data.externalPackages && data.externalPackages.length > 0) {
     lines.push(`External packages: ${data.externalPackages.join(", ")}`);
@@ -2724,7 +2997,7 @@ function formatCalleesResult(data) {
 }
 async function codeCalleesAction(symbolArg, options, deps) {
   const { pkgseerService } = deps;
-  const symbolRef = buildSymbolReference(symbolArg, options.id);
+  const symbolRef = buildSymbolReference(symbolArg, options.ref);
   const result = await pkgseerService.symbolDependencies(symbolRef, {
     maxDepth: parseIntOption(options.maxDepth, "--max-depth"),
     maxResults: parseIntOption(options.limit, "--limit"),
@@ -2734,27 +3007,27 @@ 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 --id.", 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.
 
 Shows functions and methods that the specified symbol depends on.
-Use registry:package#symbolName format or --id for direct lookup.
+Use registry:package#symbolName format or --ref for direct lookup.
 
 Examples:
   pkgseer code callees npm:express#Router
-  pkgseer code callees --id 12345
+  pkgseer code callees --ref npm:express:4.18.2:42
   pkgseer code callees npm:lodash#merge --max-depth 2 --include-external`;
 function registerCodeCalleesCommand(program) {
-  program.command("callees [symbol]").summary("Find what a symbol calls").description(CALLEES_DESCRIPTION).option("--id <id>", "Direct symbol ID").option("--max-depth <n>", "Max traversal depth").option("--limit <n>", "Max results").option("--include-external", "Include external package calls").option("--include-builtins", "Include builtin function calls").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (symbolArg, options) => {
+  program.command("callees [symbol]").summary("Find what a symbol calls").description(CALLEES_DESCRIPTION).option("--ref <ref>", "Direct symbol reference (registry:package:version:id)").option("--max-depth <n>", "Max traversal depth").option("--limit <n>", "Max results").option("--include-external", "Include external package calls").option("--include-builtins", "Include builtin function calls").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (symbolArg, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await codeCalleesAction(symbolArg, options, deps);
@@ -2764,7 +3037,7 @@ function registerCodeCalleesCommand(program) {
 // src/commands/code/callers.ts
 function formatCallersResult(data) {
   const lines = [];
-  lines.push(`Callers of ${data.target.qualifiedPath ?? data.target.name} (id:${data.target.symbolId})`);
+  lines.push(`Callers of ${data.target.qualifiedPath ?? data.target.name} (ref:${data.target.symbolRef})`);
   lines.push(`${data.total} caller(s)${data.hasMore ? " (more available)" : ""}`);
   lines.push("");
   for (const dep of data.dependents) {
@@ -2776,35 +3049,36 @@ function formatCallersResult(data) {
 }
 async function codeCallersAction(symbolArg, options, deps) {
   const { pkgseerService } = deps;
-  const symbolRef = buildSymbolReference(symbolArg, options.id);
+  const symbolRef = buildSymbolReference(symbolArg, options.ref);
   const result = await pkgseerService.symbolDependents(symbolRef, {
     samePackageOnly: options.samePackageOnly,
+    maxDepth: parseIntOption(options.maxDepth, "--max-depth"),
     maxResults: parseIntOption(options.limit, "--limit"),
     mode: parseNavigationMode(options.mode),
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.symbolDependents) {
-    outputError("Symbol not found. Verify the symbol reference or use --id.", 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.
 
 Shows functions and methods that call the specified symbol.
-Use registry:package#symbolName format or --id for direct lookup.
+Use registry:package#symbolName format or --ref for direct lookup.
 
 Examples:
   pkgseer code callers npm:express#Router
-  pkgseer code callers --id 12345
+  pkgseer code callers --ref npm:express:4.18.2:42
   pkgseer code callers npm:lodash#debounce --same-package-only`;
 function registerCodeCallersCommand(program) {
-  program.command("callers [symbol]").summary("Find what calls a symbol").description(CALLERS_DESCRIPTION).option("--id <id>", "Direct symbol ID").option("--same-package-only", "Only show callers from the same package").option("--limit <n>", "Max results").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (symbolArg, options) => {
+  program.command("callers [symbol]").summary("Find what calls a symbol").description(CALLERS_DESCRIPTION).option("--ref <ref>", "Direct symbol reference (registry:package:version:id)").option("--same-package-only", "Only show callers from the same package").option("--max-depth <n>", "Max traversal depth").option("--limit <n>", "Max results").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (symbolArg, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await codeCallersAction(symbolArg, options, deps);
@@ -2856,14 +3130,14 @@ async function codeDiffAction(packageArg, fromVersion, toVersion, options, deps)
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.versionDiff) {
+  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.
@@ -2916,11 +3190,11 @@ async function codeFilesAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.listRepoFiles) {
+  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 {
@@ -2981,11 +3255,11 @@ async function codeFindAction(packageArg, nameArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.findSymbol) {
+  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 {
@@ -3055,11 +3329,11 @@ async function codeGrepAction(packageArg, filePath, pattern, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.grepRepoFile) {
+  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 {
@@ -3142,14 +3416,14 @@ async function codeImportsAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.packageImports) {
+  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.
@@ -3211,14 +3485,14 @@ async function codeListAction(packageArg, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.listSymbols) {
+  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.
@@ -3257,9 +3531,9 @@ function formatPathResult(data) {
     for (const [j, hop] of callPath.hops.entries()) {
       const name = hop.qualifiedPath ?? hop.name ?? "unknown";
       const loc = hop.filePath ? hop.callLine ? ` ${hop.filePath}:${hop.callLine}` : ` ${hop.filePath}` : "";
-      const idPart = hop.symbolId ? ` (id:${hop.symbolId})` : "";
+      const refPart = hop.symbolRef ? ` (ref:${hop.symbolRef})` : "";
       const arrow = j < callPath.hops.length - 1 ? " ->" : "";
-      lines.push(`  ${j + 1}. ${name}${idPart}${loc}${arrow}`);
+      lines.push(`  ${j + 1}. ${name}${refPart}${loc}${arrow}`);
     }
     lines.push("");
   }
@@ -3268,35 +3542,35 @@ function formatPathResult(data) {
 }
 async function codePathAction(fromArg, toArg, options, deps) {
   const { pkgseerService } = deps;
-  const fromRef = buildSymbolReference(fromArg, options.fromId);
-  const toRef = buildSymbolReference(toArg, options.toId);
+  const fromRef = buildSymbolReference(fromArg, options.fromRef);
+  const toRef = buildSymbolReference(toArg, options.toRef);
   const result = await pkgseerService.callPath(fromRef, toRef, {
     maxDepth: parseIntOption(options.maxDepth, "--max-depth"),
     mode: parseNavigationMode(options.mode),
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.callPath) {
+  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.
 
 Discovers the shortest call path from one symbol to another.
-Use registry:package#symbolName format or --from-id/--to-id for direct lookup.
+Use registry:package#symbolName format or --from-ref/--to-ref for direct lookup.
 
 Examples:
   pkgseer code path npm:express#app npm:express#Router
-  pkgseer code path --from-id 123 --to-id 456
+  pkgseer code path --from-ref npm:express:4.18.2:123 --to-ref npm:express:4.18.2:456
   pkgseer code path npm:lodash#merge npm:lodash#cloneDeep --max-depth 5`;
 function registerCodePathCommand(program) {
-  program.command("path [from] [to]").summary("Find call path between symbols").description(PATH_DESCRIPTION).option("--from-id <id>", "Source symbol ID").option("--to-id <id>", "Target symbol ID").option("--max-depth <n>", "Max path depth").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (fromArg, toArg, options) => {
+  program.command("path [from] [to]").summary("Find call path between symbols").description(PATH_DESCRIPTION).option("--from-ref <ref>", "Source symbol reference (registry:package:version:id)").option("--to-ref <ref>", "Target symbol reference (registry:package:version:id)").option("--max-depth <n>", "Max path depth").option("--mode <mode>", "Response detail: summary or detailed").option("--wait <ms>", "Max ms to wait for indexing (0-30000)").option("--json", "Output as JSON").action(async (fromArg, toArg, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await codePathAction(fromArg, toArg, options, deps);
@@ -3356,11 +3630,11 @@ async function codeSearchAction(packageArg, query, options, deps) {
     waitTimeoutMs: parseWaitTimeout(options.wait)
   });
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.searchSymbols) {
+  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 {
@@ -3598,7 +3872,7 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
         }).join("; ");
         return { ref: ref.originalRef, result: null, error: errorMsg };
       }
-      if (!result2.data.getDocPage) {
+      if (!result2.data?.getDocPage) {
         return {
           ref: ref.originalRef,
           result: null,
@@ -3608,8 +3882,8 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
       return {
         ref: ref.originalRef,
         result: {
-          schemaVersion: result2.data.getDocPage?.schemaVersion ?? null,
-          page: result2.data.getDocPage?.page ?? null
+          schemaVersion: result2.data?.getDocPage?.schemaVersion ?? null,
+          page: result2.data?.getDocPage?.page ?? null
         }
       };
     }
@@ -3642,7 +3916,7 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
       }).join("; ");
       return { ref: ref.originalRef, result: null, error: errorMsg };
     }
-    if (!result.data.fetchPackageDoc) {
+    if (!result.data?.fetchPackageDoc) {
       return {
         ref: ref.originalRef,
         result: null,
@@ -3651,8 +3925,8 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
     }
     return {
       ref: ref.originalRef,
-      result: result.data.fetchPackageDoc ? {
-        page: result.data.fetchPackageDoc.page ?? null
+      result: result.data?.fetchPackageDoc ? {
+        page: result.data?.fetchPackageDoc.page ?? null
       } : null
     };
   } catch (error) {
@@ -3797,12 +4071,12 @@ async function docsListAction(packageArg, options, deps) {
   const version2 = parsed.version ?? options.pkgVersion;
   const result = await pkgseerService.cliDocsList(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.listPackageDocs) {
+  if (!result.data?.listPackageDocs) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
-    const pages = result.data.listPackageDocs.pages?.filter((p) => p) ?? [];
+    const pages = result.data?.listPackageDocs.pages?.filter((p) => p) ?? [];
     const slim = pages.map((p) => {
       if (!p || !p.id)
         return null;
@@ -3813,7 +4087,7 @@ async function docsListAction(packageArg, options, deps) {
     }).filter((p) => p !== null);
     output(slim, true);
   } else {
-    console.log(formatDocsList(result.data.listPackageDocs));
+    console.log(formatDocsList(result.data?.listPackageDocs));
   }
 }
 var LIST_DESCRIPTION2 = `List available documentation pages for a package.
@@ -4292,7 +4566,7 @@ async function pollSearchProgress(searchRef, pkgseerService, useColors) {
   const result = await pollUntilDone({
     fetch: async () => {
       const res = await pkgseerService.getSearchProgress(searchRef);
-      return res.data.searchProgress ?? null;
+      return res.data?.searchProgress ?? null;
     },
     isDone: (progress) => {
       if (!progress)
@@ -4325,7 +4599,7 @@ async function handleResume(searchRef, pkgseerService, options, useColors) {
     handleErrors(progressResult.errors, options.json ?? false);
     return true;
   }
-  const progress = progressResult.data.searchProgress;
+  const progress = progressResult.data?.searchProgress;
   if (!progress) {
     outputError("Search session not found. It may have expired (sessions last 1 hour).", options.json ?? false);
     return true;
@@ -4336,7 +4610,7 @@ async function handleResume(searchRef, pkgseerService, options, useColors) {
       handleErrors(resultsResponse.errors, options.json ?? false);
       return true;
     }
-    const searchResults = resultsResponse.data.searchResults;
+    const searchResults = resultsResponse.data?.searchResults;
     if (!searchResults) {
       outputError("Search completed but no results returned.", options.json ?? false);
       return true;
@@ -4379,8 +4653,8 @@ Ref: ${searchRef}`, options.json ?? false);
     }
     if (pollResult.status === "COMPLETED") {
       const resultsResponse = await pkgseerService.getSearchResults(searchRef);
-      if (resultsResponse.data.searchResults) {
-        outputResults(resultsResponse.data.searchResults, options, useColors);
+      if (resultsResponse.data?.searchResults) {
+        outputResults(resultsResponse.data?.searchResults, options, useColors);
       }
     } else {
       console.log(`Search ended with status: ${pollResult.status.toLowerCase()}`);
@@ -4421,7 +4695,7 @@ async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
     waitTimeoutMs
   });
   handleErrors(result.errors, options.json ?? false);
-  const asyncResult = result.data.combinedSearch;
+  const asyncResult = result.data?.combinedSearch;
   if (!asyncResult) {
     outputError("No results returned. Check package names and registries.", options.json ?? false);
     return;
@@ -4442,9 +4716,9 @@ async function searchAction(queryArg, options, deps, defaultMode = "ALL") {
       const pollResult = await pollSearchProgress(searchRef, pkgseerService, useColors);
       if (pollResult.success && pollResult.status === "COMPLETED") {
         const resultsResponse = await pkgseerService.getSearchResults(searchRef);
-        if (resultsResponse.data.searchResults) {
+        if (resultsResponse.data?.searchResults) {
           console.log("");
-          outputResults(resultsResponse.data.searchResults, options, useColors);
+          outputResults(resultsResponse.data?.searchResults, options, useColors);
           return;
         }
       }
@@ -4598,7 +4872,7 @@ async function indexAction(packages, options, deps) {
   }
   const result = await pkgseerService.triggerIndexing(input2);
   handleErrors(result.errors, options.json ?? false);
-  const data = result.data.triggerIndexing;
+  const data = result.data?.triggerIndexing;
   if (options.json) {
     output(data, true);
   } else {
@@ -4843,16 +5117,39 @@ async function setupCodexViaCli(shellService) {
 }
 function showAvailableTools(hasProject, useColors) {
   console.log(`
-Available MCP tools:`);
-  console.log("  • package_summary - Get package overview");
-  console.log("  • package_vulnerabilities - Check for security issues");
-  console.log("  • package_quality - Get quality score");
-  console.log("  • package_dependencies - List dependencies");
-  console.log("  • compare_packages - Compare multiple packages");
-  console.log("  • list_package_docs - List documentation pages");
-  console.log("  • fetch_package_doc - Fetch documentation content");
-  console.log("  • search_package_docs - Search package documentation");
-  console.log("  • search_project_docs - Search docs across project dependencies");
+Available MCP tools (21):`);
+  console.log("");
+  console.log("  Navigate source:");
+  console.log("    • find_symbol - Read source code of functions/classes");
+  console.log("    • list_symbols - Browse public API or file symbols");
+  console.log("    • search_symbols - Full-text search within package code");
+  console.log("    • symbol_callers - Trace what calls a function");
+  console.log("    • symbol_callees - Trace what a function calls");
+  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("    • fetch_code_context - Read source by file path and line range");
+  console.log("");
+  console.log("  Search & docs:");
+  console.log("    • search - Search code and docs across packages");
+  console.log("    • search_project_docs - Search docs across project dependencies");
+  console.log("    • list_package_docs - List documentation pages");
+  console.log("    • fetch_package_doc - Fetch documentation content");
+  console.log("");
+  console.log("  Evaluate:");
+  console.log("    • package_summary - Get package overview");
+  console.log("    • package_quality - Get quality score");
+  console.log("    • package_vulnerabilities - Check for security issues");
+  console.log("    • compare_packages - Compare multiple packages");
+  console.log("    • package_dependencies - List dependencies");
+  console.log("    • version_diff - Compare changes between versions");
+  console.log("");
+  console.log("  Utility:");
+  console.log("    • trigger_indexing - Pre-warm package indexes");
+  console.log("    • search_status - Check async search progress");
+  console.log("    • package_imports - See what a package imports");
   if (!hasProject) {
     console.log(dim(`
 Tip: Create pkgseer.yml to enable automatic project detection for search_project_docs.`, useColors));
@@ -5748,27 +6045,51 @@ function generateSkillContent(invocation = "pkgseer") {
   return `---
 name: pkgseer
 version: ${version}
-description: Search code/docs across npm, PyPI, Hex packages. Provides quality scores, security vulnerabilities, dependencies, comparisons. Use when user asks about package security, CVEs, vulnerabilities, code examples, API usage, package comparison, dependency analysis, or which package to use.
+description: Navigate source code, trace call graphs, and search docs across npm/PyPI/Hex packages. Quality scores, vulnerability checks, dependency analysis, and cross-package comparison. Use when debugging third-party dependencies, understanding how a library works internally, tracing a stack trace into dependency code, evaluating or comparing packages, checking security vulnerabilities, or understanding what changed between versions.
 ---
 
-# PkgSeer - Package Intelligence
+# PkgSeer - Package Source Code & Intelligence
+
+Navigate dependency source code and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
 
-Search and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
+Use PkgSeer instead of guessing library behavior, cloning repos, or browsing GitHub.
 
-## Search (Primary Use Case)
+## Code Navigation (Debug & Understand Dependencies)
+
+\`\`\`bash
+# Read source code of a function/class — use instead of guessing from training data
+${invocation} code find express Router --include-code
+${invocation} code find pypi:requests Session --include-code
+
+# Trace what calls a function (find entry points, debug triggers)
+${invocation} code callers -r npm -p express -n Router
+
+# Trace what a function calls (follow execution path)
+${invocation} code callees -r npm -p express -n Router
+
+# Find how function A reaches function B
+${invocation} code path -r npm -p express --from-name listen --to-name createServer
+
+# Search for error messages or patterns in dependency source
+${invocation} code search express "ERR_HTTP_HEADERS_SENT"
+${invocation} code grep express src/router/index.js "handle"
+
+# Browse package structure, API, and imports
+${invocation} code files express --path-prefix src/
+${invocation} code list express --scope exports
+${invocation} code imports express --resolved-only
+
+# Compare versions (detect breaking changes after upgrades)
+${invocation} code diff express v4.18.2 v5.0.0
+\`\`\`
+
+## Search Across Packages
 
 \`\`\`bash
-# Search code and docs across packages
 ${invocation} search "<query>" -P lodash,express         # npm packages
 ${invocation} search "<query>" -P pypi:requests          # PyPI packages
-${invocation} search "authentication" -P hex:phoenix,hex:plug
-
-# Search modes
 ${invocation} search "<query>" -P <packages> --mode code  # Code only
 ${invocation} search "<query>" -P <packages> --mode docs  # Docs only
-
-# Docs-only search (shorthand)
-${invocation} docs search "<query>" -P <packages>
 \`\`\`
 
 ## Package Analysis
@@ -5776,23 +6097,11 @@ ${invocation} docs search "<query>" -P <packages>
 Package format: \`[registry:]name[@version]\`
 
 \`\`\`bash
-# Overview: metadata, versions, quickstart
-${invocation} pkg info lodash
-${invocation} pkg info pypi:requests
-
-# Quality score (0-100) with category breakdown
-${invocation} pkg quality express@4.18.0
-${invocation} pkg quality pypi:django@4.2
-
-# Security: CVEs, severity, upgrade paths
-${invocation} pkg vulns lodash@4.17.21
-
-# Dependencies: direct, transitive, tree view
-${invocation} pkg deps express --transitive
-
-# Compare up to 10 packages
-${invocation} pkg compare lodash underscore ramda
-${invocation} pkg compare axios pypi:httpx  # cross-registry
+${invocation} pkg info lodash                        # Overview, versions, quickstart
+${invocation} pkg quality express@4.18.0             # Quality score (0-100)
+${invocation} pkg vulns lodash@4.17.21               # CVEs, severity, upgrade paths
+${invocation} pkg deps express --transitive          # Dependency tree
+${invocation} pkg compare lodash underscore ramda    # Side-by-side comparison
 \`\`\`
 
 ## Documentation
@@ -5808,6 +6117,7 @@ ${invocation} docs search "<query>" -P <packages> # Search docs only
 - Package format: \`[registry:]name[@version]\` (e.g., \`pypi:django@4.2\`)
 - Default registry: npm
 - Use \`--json\` for structured output when parsing
+- Quick start: \`${invocation} code find <package> <function> --include-code\`
 `;
 }
 function extractSkillVersion(content) {
@@ -5940,7 +6250,8 @@ PkgSeer skill ${action} for ${toolName}!`, useColors));
   console.log(`Location: ${highlight(paths.skillPath, useColors)}`);
   console.log(dim(`
 The skill is now available. Try asking:
-` + `  "Search for authentication examples in express"
+` + `  "How does express Router work internally?"
+` + `  "What changed between express v4 and v5?"
 ` + `  "Is lodash secure? Check for vulnerabilities"
 ` + '  "Compare axios vs fetch vs got"', useColors));
 }
@@ -6426,19 +6737,6 @@ function errorResult(message) {
 }
 
 // src/tools/shared.ts
-function toGraphQLRegistry2(registry) {
-  const map = {
-    npm: "NPM",
-    pypi: "PYPI",
-    hex: "HEX",
-    crates: "CRATES",
-    nuget: "NUGET",
-    maven: "MAVEN",
-    zig: "ZIG",
-    vcpkg: "VCPKG"
-  };
-  return map[registry.toLowerCase()] || "NPM";
-}
 function toNavigationMode(mode) {
   if (!mode)
     return;
@@ -6487,7 +6785,7 @@ var schemas = {
   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."),
   symbolReference: z2.object({
-    symbol_id: z2.number().int().optional().describe("Direct symbol ID from find_symbol or list_symbols results (preferred, avoids ambiguity)"),
+    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.")
@@ -6495,22 +6793,23 @@ var schemas = {
 };
 function toSymbolReferenceInput(ref) {
   return {
-    symbolId: ref.symbol_id,
-    registry: ref.registry ? toGraphQLRegistry2(ref.registry) : undefined,
+    symbolRef: ref.symbol_ref,
+    registry: ref.registry ? toGraphQLRegistry(ref.registry) : undefined,
     packageName: ref.package_name,
     symbolName: ref.symbol_name
   };
 }
+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."
+};
 function buildHintedMessage(operation, message) {
-  const lower = message.toLowerCase();
-  const isBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
-  if (isBeingIndexed) {
-    return `Failed to ${operation}: ${message}. ` + "Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).";
-  }
-  const isTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
-  if (isTimeout) {
-    return `Failed to ${operation}: ${message}. ` + "Hint: try lowering the limit or narrowing the scope, then retry.";
+  const kind = classifyError(message);
+  const hint = MCP_HINTS[kind];
+  if (hint) {
+    return `Failed to ${operation}: ${message}. ${hint}`;
   }
+  const lower = message.toLowerCase();
   if (lower.includes("graphql error (code: 500)")) {
     try {
       const jsonMatch = message.match(/\{.*\}/s);
@@ -6529,24 +6828,17 @@ 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.",
+  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."
+};
 function handleGraphQLErrors(errors) {
   if (errors && errors.length > 0) {
-    const messages = errors.map((e) => e.message).filter(Boolean);
-    const combined = messages.join(", ");
-    const lower = combined.toLowerCase();
-    const hasNotFound = lower.includes("not found") || lower.includes("does not exist");
-    const hasBeingIndexed = lower.includes("being indexed") || lower.includes("retry with waittimeoutms");
-    const hasTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
-    if (hasNotFound) {
-      return errorResult(`Error: ${combined}. Hint: verify the name/registry and that the resource exists.`);
-    }
-    if (hasBeingIndexed) {
-      return errorResult(`Error: ${combined}. Hint: package is being indexed. Try again with a longer wait_timeout_ms (e.g., 30000).`);
-    }
-    if (hasTimeout) {
-      return errorResult(`Error: ${combined}. Hint: try lowering the limit or narrowing the scope, then retry.`);
-    }
-    return errorResult(`Error: ${combined}`);
+    const combined = errors.map((e) => e.message).filter(Boolean).join(", ");
+    const hint = MCP_GRAPHQL_HINTS[classifyError(combined)];
+    const suffix = hint ? `. ${hint}` : "";
+    return errorResult(`Error: ${combined}${suffix}`);
   }
   return null;
 }
@@ -6564,8 +6856,8 @@ function notFoundError(packageName, registry) {
 
 // src/tools/call-path.ts
 var argsSchema = {
-  from: schemas.symbolReference.describe("Source symbol. Provide either symbol_id or registry + package_name + symbol_name."),
-  to: schemas.symbolReference.describe("Destination symbol. Provide either symbol_id or registry + package_name + symbol_name."),
+  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)"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -6573,17 +6865,18 @@ var argsSchema = {
 function createCallPathTool(pkgseerService) {
   return {
     name: "call_path",
-    description: "Find the shortest call path between two symbols in the same package. " + "Uses BFS to trace how function A eventually calls function B through intermediate calls. " + "Returns whether a path was found, with ordered call paths (shortest first) and 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. " + "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.symbolId && (!fromInput.symbolName || !fromInput.registry || !fromInput.packageName)) {
-          return errorResult("Invalid 'from' symbol: provide either symbol_id or symbol_name with registry and package_name.");
+        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 (!toInput.symbolId && (!toInput.symbolName || !toInput.registry || !toInput.packageName)) {
-          return errorResult("Invalid 'to' symbol: provide either symbol_id or symbol_name with registry and package_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.");
         }
         const result = await pkgseerService.callPath(fromInput, toInput, {
           maxDepth: args.max_depth,
@@ -6593,10 +6886,10 @@ function createCallPathTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.callPath) {
+        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));
       });
     }
   };
@@ -6616,10 +6909,11 @@ function createComparePackagesTool(pkgseerService) {
     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"}]',
     schema: argsSchema2,
+    annotations: { readOnlyHint: true },
     handler: async ({ packages }, _extra) => {
       return withErrorHandling("compare packages", async () => {
         const input2 = packages.map((pkg) => ({
-          registry: toGraphQLRegistry2(pkg.registry),
+          registry: toGraphQLRegistry(pkg.registry),
           name: pkg.name,
           version: pkg.version
         }));
@@ -6627,10 +6921,10 @@ function createComparePackagesTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.comparePackages) {
+        if (!result.data?.comparePackages) {
           return errorResult("Comparison failed: no results returned");
         }
-        return textResult(JSON.stringify(result.data.comparePackages, null, 2));
+        return textResult(JSON.stringify(result.data?.comparePackages, null, 2));
       });
     }
   };
@@ -6647,8 +6941,9 @@ var argsSchema3 = {
 function createFetchCodeContextTool(pkgseerService) {
   return {
     name: "fetch_code_context",
-    description: "Fetch code content from a repository by file path and line range. " + "Returns full file by default, or a specific line range. " + "For symbol-based lookup, use find_symbol(include_code=true) instead. " + "Requires repo_url, git_ref (tag/commit/branch), 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, git_ref, and file_path.",
     schema: argsSchema3,
+    annotations: { readOnlyHint: true },
     handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
       return withErrorHandling("fetch code context", async () => {
         const result = await pkgseerService.fetchCodeContext(repo_url, git_ref, file_path, {
@@ -6658,10 +6953,10 @@ function createFetchCodeContextTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.fetchCodeContext) {
+        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));
+        return textResult(JSON.stringify(result.data?.fetchCodeContext, null, 2));
       });
     }
   };
@@ -6676,16 +6971,17 @@ function createFetchPackageDocTool(pkgseerService) {
     name: "fetch_package_doc",
     description: "Get full content of a documentation page. Requires page_id from list_package_docs. " + "Returns: title, full content (markdown/HTML), format type, navigation breadcrumbs, " + "source URL, and last updated timestamp. Use this when you need complete documentation, " + "not just search snippets.",
     schema: argsSchema4,
+    annotations: { readOnlyHint: true },
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
         const result = await pkgseerService.getDocPage(page_id);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.getDocPage) {
+        if (!result.data?.getDocPage) {
           return errorResult(`Documentation page not found: ${page_id}`);
         }
-        return textResult(JSON.stringify(result.data.getDocPage, null, 2));
+        return textResult(JSON.stringify(result.data?.getDocPage, null, 2));
       });
     }
   };
@@ -6716,11 +7012,12 @@ var argsSchema5 = {
 function createFindSymbolTool(pkgseerService) {
   return {
     name: "find_symbol",
-    description: "Find functions, methods, or classes by name in a package. " + "Set include_code=true to get full source code inline, avoiding separate fetch_code_context calls. " + "Returns: symbol ID, 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: symbol ref, name, qualified path, kind, file location, and optionally source code. " + "Omit name to get all public exports. Use namespace to filter by module path.",
     schema: argsSchema5,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol", async () => {
-        const result = await pkgseerService.findSymbol(toGraphQLRegistry2(args.registry), args.package_name, {
+        const result = await pkgseerService.findSymbol(toGraphQLRegistry(args.registry), args.package_name, {
           name: args.name,
           namespace: args.namespace,
           kind: toSymbolKind(args.kind),
@@ -6734,10 +7031,10 @@ function createFindSymbolTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.findSymbol) {
+        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));
         }
@@ -6761,11 +7058,12 @@ var argsSchema6 = {
 function createGrepRepoFileTool(pkgseerService) {
   return {
     name: "grep_repo_file",
-    description: "Search for a pattern within a file in a package's repository. " + "Case-insensitive substring matching. Returns matching lines with context. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover available file paths.",
+    description: "Search for a pattern within a dependency's source file — " + "find error messages, config keys, or specific patterns without cloning the repo. " + "Case-insensitive substring matching with context lines. " + "Faster than fetch_code_context for large files. " + "Use list_repo_files to discover file paths.",
     schema: argsSchema6,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("grep repo file", async () => {
-        const result = await pkgseerService.grepRepoFile(toGraphQLRegistry2(args.registry), args.package_name, args.file_path, args.pattern, {
+        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,
@@ -6774,10 +7072,10 @@ function createGrepRepoFileTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.grepRepoFile) {
+        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));
         }
@@ -6795,18 +7093,19 @@ 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_package_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.",
     schema: argsSchema7,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("list package documentation", async () => {
-        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry2(registry), package_name, version2);
+        const result = await pkgseerService.listPackageDocs(toGraphQLRegistry(registry), package_name, version2);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.listPackageDocs) {
+        if (!result.data?.listPackageDocs) {
           return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(result.data.listPackageDocs, null, 2));
+        return textResult(JSON.stringify(result.data?.listPackageDocs, null, 2));
       });
     }
   };
@@ -6824,11 +7123,12 @@ var argsSchema8 = {
 function createListRepoFilesTool(pkgseerService) {
   return {
     name: "list_repo_files",
-    description: "List files in a package's indexed repository. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Useful for exploring package structure before searching or reading code.",
+    description: "Explore a dependency's file structure — " + "see what source files, configs, and docs exist. " + "Returns file paths, names, languages, types (source/doc/config), and sizes. " + "Use path_prefix to filter by directory (e.g., 'src/'). " + "Good first step when investigating unfamiliar package internals.",
     schema: argsSchema8,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("list repo files", async () => {
-        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry2(args.registry), args.package_name, {
+        const result = await pkgseerService.listRepoFiles(toGraphQLRegistry(args.registry), args.package_name, {
           version: args.version,
           pathPrefix: args.path_prefix,
           limit: args.limit,
@@ -6837,10 +7137,10 @@ function createListRepoFilesTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.listRepoFiles) {
+        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));
         }
@@ -6867,8 +7167,9 @@ var argsSchema9 = {
 function createListSymbolsTool(pkgseerService) {
   return {
     name: "list_symbols",
-    description: "Browse symbols in a package by scope. " + "Use scope='exports' for public API with namespace grouping and optional popularity. " + "Use scope='file' with file_path for all symbols in a specific file. " + "Returns symbols with IDs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to get source for any listed symbol.",
+    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,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
         const scope = toListScope(args.scope);
@@ -6883,7 +7184,7 @@ function createListSymbolsTool(pkgseerService) {
             isError: true
           };
         }
-        const result = await pkgseerService.listSymbols(toGraphQLRegistry2(args.registry), args.package_name, scope, {
+        const result = await pkgseerService.listSymbols(toGraphQLRegistry(args.registry), args.package_name, scope, {
           filePath: args.file_path,
           namespace: args.namespace,
           publicOnly: args.public_only,
@@ -6896,10 +7197,10 @@ function createListSymbolsTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.listSymbols) {
+        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));
       });
     }
   };
@@ -6990,22 +7291,23 @@ function createPackageDependenciesTool(pkgseerService) {
     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,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
       return withErrorHandling("fetch package dependencies", async () => {
-        const result = await pkgseerService.getPackageDependencies(toGraphQLRegistry2(registry), package_name, version2, include_transitive, max_depth);
+        const result = await pkgseerService.getPackageDependencies(toGraphQLRegistry(registry), package_name, version2, include_transitive, max_depth);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.packageDependencies) {
+        if (!result.data?.packageDependencies) {
           return notFoundError(package_name, registry);
         }
-        const deps = result.data.packageDependencies.dependencies;
+        const deps = result.data?.packageDependencies.dependencies;
         const decodedDag = decodeDag(deps?.transitive?.dag);
         const transitiveDag = deps?.transitive?.dag;
         const edgesWithDepth = buildEdgeDepths(decodedDag, typeof transitiveDag?.root === "string" ? transitiveDag.root : undefined);
         const output2 = {
           summary: deps?.summary,
-          package: result.data.packageDependencies.package,
+          package: result.data?.packageDependencies.package,
           direct: deps?.direct,
           transitive: deps?.transitive ? {
             totalEdges: deps.transitive.totalEdges,
@@ -7019,7 +7321,7 @@ function createPackageDependenciesTool(pkgseerService) {
               raw: deps.transitive.dag
             }
           } : undefined,
-          raw: result.data.packageDependencies
+          raw: result.data?.packageDependencies
         };
         return textResult(JSON.stringify(output2, null, 2));
       });
@@ -7041,11 +7343,12 @@ var argsSchema11 = {
 function createPackageImportsTool(pkgseerService) {
   return {
     name: "package_imports",
-    description: "Get import statements in a package. " + "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.",
+    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(toGraphQLRegistry2(args.registry), args.package_name, {
+        const result = await pkgseerService.packageImports(toGraphQLRegistry(args.registry), args.package_name, {
           filePath: args.file_path,
           resolvedOnly: args.resolved_only,
           limit: args.limit,
@@ -7056,10 +7359,10 @@ function createPackageImportsTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.packageImports) {
+        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));
       });
     }
   };
@@ -7075,16 +7378,17 @@ function createPackageQualityTool(pkgseerService) {
     name: "package_quality",
     description: "Evaluate package maintenance health and code quality. Use this to assess if a package is well-maintained " + "before adding it as a dependency. Returns: overall score (0-100), category scores (documentation, " + "testing, community, maintenance), and individual rule results with pass/fail status. " + "Useful for comparing quality between alternative packages.",
     schema: argsSchema12,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
-        const result = await pkgseerService.getPackageQuality(toGraphQLRegistry2(registry), package_name, version2);
+        const result = await pkgseerService.getPackageQuality(toGraphQLRegistry(registry), package_name, version2);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.packageQuality) {
+        if (!result.data?.packageQuality) {
           return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(result.data.packageQuality, null, 2));
+        return textResult(JSON.stringify(result.data?.packageQuality, null, 2));
       });
     }
   };
@@ -7099,16 +7403,17 @@ function createPackageSummaryTool(pkgseerService) {
     name: "package_summary",
     description: "Get a comprehensive overview of a package. Use this as your first tool when researching a package. " + "Returns: description, latest version, license, repository URL, download stats, " + "active security advisories count, and quickstart/installation instructions. " + "For deeper analysis, follow up with package_quality (maintenance health) or " + "package_vulnerabilities (security details).",
     schema: argsSchema13,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
-        const result = await pkgseerService.getPackageSummary(toGraphQLRegistry2(registry), package_name);
+        const result = await pkgseerService.getPackageSummary(toGraphQLRegistry(registry), package_name);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.packageSummary) {
+        if (!result.data?.packageSummary) {
           return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(result.data.packageSummary, null, 2));
+        return textResult(JSON.stringify(result.data?.packageSummary, null, 2));
       });
     }
   };
@@ -7124,16 +7429,17 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     name: "package_vulnerabilities",
     description: "Check security vulnerabilities for a package. Use this before adding dependencies or when auditing existing ones. " + "Returns: list of CVEs/advisories with severity levels, affected version ranges, fixed versions, " + "and upgrade recommendations. If version is specified, shows only vulnerabilities affecting that version.",
     schema: argsSchema14,
+    annotations: { readOnlyHint: true },
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
-        const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry2(registry), package_name, version2);
+        const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry(registry), package_name, version2);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.packageVulnerabilities) {
+        if (!result.data?.packageVulnerabilities) {
           return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(result.data.packageVulnerabilities, null, 2));
+        return textResult(JSON.stringify(result.data?.packageVulnerabilities, null, 2));
       });
     }
   };
@@ -7191,6 +7497,7 @@ function createSearchTool(pkgseerService) {
     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.",
     schema: argsSchema15,
+    annotations: { readOnlyHint: true },
     handler: async ({ packages, query, mode, limit, waitTimeoutMs }, _extra) => {
       return withErrorHandling("search packages", async () => {
         const normalizedQuery = query.trim();
@@ -7198,7 +7505,7 @@ function createSearchTool(pkgseerService) {
           return errorResult("Search query is required.");
         }
         const graphqlPackages = packages.map((pkg) => ({
-          registry: toGraphQLRegistry2(pkg.registry),
+          registry: toGraphQLRegistry(pkg.registry),
           name: pkg.name,
           version: pkg.version
         }));
@@ -7210,7 +7517,7 @@ function createSearchTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        const asyncResult = result.data.combinedSearch;
+        const asyncResult = result.data?.combinedSearch;
         if (!asyncResult) {
           return errorResult("No search results returned. Check package names and registries.");
         }
@@ -7255,8 +7562,9 @@ function createSearchProjectDocsTool(deps) {
   const { pkgseerService, configService, defaultProjectDir } = deps;
   return {
     name: "search_project_docs",
-    description: "Searches documentation across all dependencies in a PkgSeer project using search terms and match modes (any/all). Returns ranked results from multiple packages. Use project_directory to specify which project's context to use, or project to search a specific project directly.",
+    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,
+    annotations: { readOnlyHint: true },
     handler: async ({
       project_directory,
       project,
@@ -7290,13 +7598,13 @@ function createSearchProjectDocsTool(deps) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.searchProjectDocs) {
+        if (!result.data?.searchProjectDocs) {
           return errorResult(`Project not found: ${resolvedProject}`);
         }
-        if ((result.data.searchProjectDocs.entries ?? []).length === 0 && normalizedTerms.length > 0) {
+        if ((result.data?.searchProjectDocs.entries ?? []).length === 0 && normalizedTerms.length > 0) {
           return errorResult(`No documentation matched: ${normalizedTerms.join(", ")}. ` + "Try fewer or broader terms, or reduce match constraints.");
         }
-        return textResult(JSON.stringify(result.data.searchProjectDocs, null, 2));
+        return textResult(JSON.stringify(result.data?.searchProjectDocs, null, 2));
       });
     }
   };
@@ -7311,13 +7619,14 @@ function createSearchStatusTool(pkgseerService) {
     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,
+    annotations: { readOnlyHint: true },
     handler: async ({ searchRef }, _extra) => {
       return withErrorHandling("check search status", async () => {
         const progressResult = await pkgseerService.getSearchProgress(searchRef);
         const graphqlError = handleGraphQLErrors(progressResult.errors);
         if (graphqlError)
           return graphqlError;
-        const progress = progressResult.data.searchProgress;
+        const progress = progressResult.data?.searchProgress;
         if (!progress) {
           return errorResult("Search session not found. It may have expired (sessions last 1 hour).");
         }
@@ -7326,7 +7635,7 @@ function createSearchStatusTool(pkgseerService) {
           const resultsError = handleGraphQLErrors(resultsResponse.errors);
           if (resultsError)
             return resultsError;
-          const searchResults = resultsResponse.data.searchResults;
+          const searchResults = resultsResponse.data?.searchResults;
           if (!searchResults) {
             return errorResult("Search completed but results are no longer available. " + "The session may have expired (sessions last 1 hour).");
           }
@@ -7376,11 +7685,12 @@ var argsSchema18 = {
 function createSearchSymbolsTool(pkgseerService) {
   return {
     name: "search_symbols",
-    description: "Full-text search within package code. " + "Searches across functions, classes, modules, and doc sections. " + "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: use find_symbol(name=<result.name>, include_code=true) to get full source.",
+    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.",
     schema: argsSchema18,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("search symbols", async () => {
-        const result = await pkgseerService.searchSymbols(toGraphQLRegistry2(args.registry), args.package_name, {
+        const result = await pkgseerService.searchSymbols(toGraphQLRegistry(args.registry), args.package_name, {
           query: args.query,
           keywords: args.keywords,
           matchMode: toMatchMode(args.match_mode),
@@ -7394,10 +7704,10 @@ function createSearchSymbolsTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.searchSymbols) {
+        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;
@@ -7416,7 +7726,7 @@ 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_id or registry + package_name + symbol_name."),
+  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"),
@@ -7427,13 +7737,14 @@ var argsSchema19 = {
 function createSymbolCalleesTool(pkgseerService) {
   return {
     name: "symbol_callees",
-    description: "Find what a symbol calls (its dependencies). " + "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_id from find_symbol or list_symbols results. See symbol_callers for the reverse.",
+    description: "Trace what a function calls internally — " + "understand dependency behavior by following its execution path. " + "Returns direct callees at max_depth=1, or transitive call chains at higher depths. " + "Includes callee names, qualified paths, file locations, call lines, and external package references. " + "Get symbol_ref from find_symbol or list_symbols. See symbol_callers for the reverse.",
     schema: argsSchema19,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callees", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolId && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_id or symbol_name with registry and package_name to identify the 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.");
         }
         const result = await pkgseerService.symbolDependencies(symbolInput, {
           maxDepth: args.max_depth,
@@ -7446,10 +7757,10 @@ function createSymbolCalleesTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.symbolDependencies) {
+        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));
       });
     }
   };
@@ -7457,8 +7768,9 @@ 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_id or registry + package_name + symbol_name."),
+  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"),
   mode: schemas.navigationMode,
   wait_timeout_ms: schemas.waitTimeoutMs
@@ -7466,16 +7778,18 @@ var argsSchema20 = {
 function createSymbolCallersTool(pkgseerService) {
   return {
     name: "symbol_callers",
-    description: "Find what calls a symbol (its dependents/callers). " + "Returns the target symbol and a list of callers with file locations and call line numbers. " + "Use same_package_only to limit to callers within the same package. " + "Get symbol_id from find_symbol or list_symbols results. 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.",
     schema: argsSchema20,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("find symbol callers", async () => {
         const symbolInput = toSymbolReferenceInput(args.symbol);
-        if (!symbolInput.symbolId && (!symbolInput.symbolName || !symbolInput.registry || !symbolInput.packageName)) {
-          return errorResult("Provide either symbol_id or symbol_name with registry and package_name to identify the 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.");
         }
         const result = await pkgseerService.symbolDependents(symbolInput, {
           samePackageOnly: args.same_package_only,
+          maxDepth: args.max_depth,
           maxResults: args.limit,
           mode: toNavigationMode(args.mode),
           waitTimeoutMs: args.wait_timeout_ms
@@ -7483,10 +7797,10 @@ function createSymbolCallersTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.symbolDependents) {
+        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));
       });
     }
   };
@@ -7512,10 +7826,11 @@ function createTriggerIndexingTool(pkgseerService) {
     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.",
     schema: argsSchema21,
+    annotations: { readOnlyHint: false, idempotentHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("trigger indexing", async () => {
         const packages = args.packages?.map((p) => ({
-          registry: toGraphQLRegistry2(p.registry),
+          registry: toGraphQLRegistry(p.registry),
           name: p.name,
           version: p.version
         }));
@@ -7531,7 +7846,7 @@ function createTriggerIndexingTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.triggerIndexing) {
+        if (!result.data?.triggerIndexing) {
           return {
             content: [
               {
@@ -7542,7 +7857,7 @@ function createTriggerIndexingTool(pkgseerService) {
             isError: true
           };
         }
-        return textResult(JSON.stringify(result.data.triggerIndexing, null, 2));
+        return textResult(JSON.stringify(result.data?.triggerIndexing, null, 2));
       });
     }
   };
@@ -7570,11 +7885,12 @@ var argsSchema22 = {
 function createVersionDiffTool(pkgseerService) {
   return {
     name: "version_diff",
-    description: "Compare symbols between two package versions. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
+    description: "Compare two versions of a dependency to understand what changed — " + "use when debugging issues after upgrades or planning migrations. " + "Detects added, removed, moved, and modified symbols with severity " + "(breaking, behavior_change, non_breaking, internal). " + "Returns summary counts and per-symbol changes with file locations.",
     schema: argsSchema22,
+    annotations: { readOnlyHint: true },
     handler: async (args, _extra) => {
       return withErrorHandling("version diff", async () => {
-        const result = await pkgseerService.versionDiff(toGraphQLRegistry2(args.registry), args.package_name, args.from_version, args.to_version, {
+        const result = await pkgseerService.versionDiff(toGraphQLRegistry(args.registry), args.package_name, args.from_version, args.to_version, {
           includePrivate: args.include_private,
           kind: toSymbolKind(args.kind),
           limit: args.limit,
@@ -7583,15 +7899,37 @@ function createVersionDiffTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.versionDiff) {
+        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));
       });
     }
   };
 }
 // src/commands/mcp.ts
+var PKGSEER_INSTRUCTIONS = `PkgSeer provides source code intelligence for third-party packages across npm, PyPI, Hex, and other registries. All tools are read-only except trigger_indexing (which only queues background work).
+
+Use PkgSeer when:
+- A stack trace or error originates in a third-party dependency
+- You need to understand how a library function works internally
+- You want to trace call chains through dependency source code
+- You're evaluating, comparing, or auditing packages
+- 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 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
+
+Quick start: find_symbol(registry="npm", name="<function>", package_name="<pkg>", include_code=true) often answers the question in one call.`;
 var TOOL_FACTORIES = {
   package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
   package_vulnerabilities: ({ pkgseerService }) => createPackageVulnerabilitiesTool(pkgseerService),
@@ -7647,10 +7985,7 @@ 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"
-  });
+  const server = new McpServer({ name: "pkgseer", version: "0.1.0" }, { instructions: PKGSEER_INSTRUCTIONS });
   const defaultProjectDir = fileSystemService.getCwd();
   const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
   const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
@@ -7663,7 +7998,11 @@ function createMcpServer(deps) {
   for (const toolName of toolsToRegister) {
     const factory = TOOL_FACTORIES[toolName];
     const tool = factory(factoryDeps);
-    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.handler);
+    server.registerTool(tool.name, {
+      description: tool.description,
+      inputSchema: tool.schema,
+      annotations: tool.annotations
+    }, tool.handler);
   }
   return server;
 }
@@ -7712,10 +8051,13 @@ function registerMcpCommand(program) {
 When run interactively (TTY), shows setup instructions.
 When run via stdio (non-TTY), starts the MCP server.
 
-Available tools: package_summary, package_vulnerabilities,
-package_dependencies, package_quality, compare_packages,
-list_package_docs, fetch_package_doc, search_package_docs,
-search_project_docs`).action(async () => {
+Available tools (21):
+  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: 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 () => {
     const deps = await createContainer();
     if (process.stdout.isTTY && process.stdin.isTTY) {
       showMcpSetupInstructions(deps);
@@ -7779,12 +8121,12 @@ async function pkgCompareAction(packages, options, deps) {
   });
   const result = await pkgseerService.cliComparePackages(input2);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.comparePackages) {
+  if (!result.data?.comparePackages) {
     outputError("Comparison failed", options.json ?? false);
     return;
   }
   if (options.json) {
-    const pkgs = result.data.comparePackages.packages?.filter((p) => p) ?? [];
+    const pkgs = result.data?.comparePackages.packages?.filter((p) => p) ?? [];
     const slim = pkgs.map((p) => ({
       package: `${p?.packageName}@${p?.version}`,
       quality: p?.quality?.score,
@@ -7793,7 +8135,7 @@ async function pkgCompareAction(packages, options, deps) {
     }));
     output(slim, true);
   } else {
-    console.log(formatPackageComparison(result.data.comparePackages));
+    console.log(formatPackageComparison(result.data?.comparePackages));
   }
 }
 var COMPARE_DESCRIPTION = `Compare multiple packages.
@@ -7862,13 +8204,13 @@ async function pkgDepsAction(packageArg, options, deps) {
   const transitiveRequested = options.transitive ?? false;
   const result = await pkgseerService.cliPackageDeps(registry, parsed.name, version2, options.transitive, options.maxDepth ? Number.parseInt(options.maxDepth, 10) : undefined);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.packageDependencies) {
+  if (!result.data?.packageDependencies) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   const format = options.json ? "json" : options.format ?? "human";
   if (format === "json") {
-    const data = result.data.packageDependencies;
+    const data = result.data?.packageDependencies;
     output({
       package: `${data.package?.name}@${data.package?.version}`,
       directCount: data.dependencies?.summary?.directCount ?? 0,
@@ -7881,7 +8223,7 @@ async function pkgDepsAction(packageArg, options, deps) {
       }))
     }, true);
   } else if (format === "summary") {
-    const data = result.data.packageDependencies;
+    const data = result.data?.packageDependencies;
     const deps2 = data.dependencies;
     const directCount = deps2?.summary?.directCount ?? 0;
     const uniquePackagesCount = deps2?.summary?.uniquePackagesCount ?? 0;
@@ -7894,7 +8236,7 @@ async function pkgDepsAction(packageArg, options, deps) {
     console.log(lines.join(`
 `));
   } else {
-    console.log(formatPackageDependencies(result.data.packageDependencies, transitiveRequested));
+    console.log(formatPackageDependencies(result.data?.packageDependencies, transitiveRequested));
   }
 }
 var DEPS_DESCRIPTION = `Get package dependencies.
@@ -7978,12 +8320,12 @@ async function pkgInfoAction(packageArg, options, deps) {
   const registry = toGraphQLRegistry(parsed.registry !== "npm" ? parsed.registry : options.registry);
   const result = await pkgseerService.cliPackageInfo(registry, parsed.name);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.packageSummary) {
+  if (!result.data?.packageSummary) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
-    const data = result.data.packageSummary;
+    const data = result.data?.packageSummary;
     const pkg = data.package;
     const slim = {
       name: pkg?.name,
@@ -7995,7 +8337,7 @@ async function pkgInfoAction(packageArg, options, deps) {
     };
     output(slim, true);
   } else {
-    console.log(formatPackageSummary(result.data.packageSummary));
+    console.log(formatPackageSummary(result.data?.packageSummary));
   }
 }
 var INFO_DESCRIPTION = `Get package summary and metadata.
@@ -8046,15 +8388,15 @@ async function pkgQualityAction(packageArg, options, deps) {
   const version2 = parsed.version ?? options.pkgVersion;
   const result = await pkgseerService.cliPackageQuality(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.packageQuality) {
+  if (!result.data?.packageQuality) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   const format = options.json ? "json" : options.format ?? "human";
   if (format === "json") {
-    const quality = result.data.packageQuality.quality;
+    const quality = result.data?.packageQuality.quality;
     const slim = {
-      package: `${result.data.packageQuality.package?.name}@${result.data.packageQuality.package?.version}`,
+      package: `${result.data?.packageQuality.package?.name}@${result.data?.packageQuality.package?.version}`,
       score: quality?.overallScore,
       grade: quality?.grade,
       categories: quality?.categories?.filter((c) => c).map((c) => ({
@@ -8064,7 +8406,7 @@ async function pkgQualityAction(packageArg, options, deps) {
     };
     output(slim, true);
   } else {
-    console.log(formatPackageQuality(result.data.packageQuality));
+    console.log(formatPackageQuality(result.data?.packageQuality));
   }
 }
 var QUALITY_DESCRIPTION = `Get package quality score and breakdown.
@@ -8149,12 +8491,12 @@ async function pkgVulnsAction(packageArg, options, deps) {
   const version2 = parsed.version ?? options.pkgVersion;
   const result = await pkgseerService.cliPackageVulns(registry, parsed.name, version2);
   handleErrors(result.errors, options.json ?? false);
-  if (!result.data.packageVulnerabilities) {
+  if (!result.data?.packageVulnerabilities) {
     outputError(`Package not found: ${parsed.name} in ${parsed.registry}`, options.json ?? false);
     return;
   }
   if (options.json) {
-    const data = result.data.packageVulnerabilities;
+    const data = result.data?.packageVulnerabilities;
     const vulns = data.security?.vulnerabilities ?? [];
     const slim = {
       package: `${data.package?.name}@${data.package?.version}`,
@@ -8168,7 +8510,7 @@ async function pkgVulnsAction(packageArg, options, deps) {
     };
     output(slim, true);
   } else {
-    console.log(formatPackageVulnerabilities(result.data.packageVulnerabilities));
+    console.log(formatPackageVulnerabilities(result.data?.packageVulnerabilities));
   }
 }
 var VULNS_DESCRIPTION = `Check package for security vulnerabilities.