@pkgseer/cli 0.4.2 → 0.4.7

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-w4ht5me5.js";
+} from "./shared/chunk-z0xepgqq.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -670,7 +670,7 @@ var FindSymbolDocument = gql`
     waitTimeoutMs: $waitTimeoutMs
   ) {
     symbols {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -685,6 +685,13 @@ var FindSymbolDocument = gql`
     totalMatches
     hasMore
     indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
   }
 }
     `;
@@ -713,7 +720,7 @@ var SearchSymbolsDocument = gql`
       contentPreview
       code
       language
-      symbolId
+      symbolRef
       qualifiedPath
       kind
       arity
@@ -730,6 +737,7 @@ var SearchSymbolsDocument = gql`
       indexedAt
       hint
     }
+    warning
   }
 }
     `;
@@ -749,7 +757,7 @@ var ListSymbolsDocument = gql`
     waitTimeoutMs: $waitTimeoutMs
   ) {
     symbols {
-      symbolId
+      symbolRef
       name
       qualifiedPath
       kind
@@ -767,12 +775,11 @@ var ListSymbolsDocument = gql`
       path
       language
     }
-    error
   }
 }
     `;
 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
@@ -781,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
@@ -810,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
@@ -880,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
@@ -950,6 +959,13 @@ var ListRepoFilesDocument = gql`
     total
     hasMore
     indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
   }
 }
     `;
@@ -977,6 +993,13 @@ var GrepRepoFileDocument = gql`
     language
     totalLines
     indexedVersion
+    diagnostics {
+      indexed
+      chunkCount
+      fileCount
+      indexedAt
+      hint
+    }
   }
 }
     `;
@@ -1019,7 +1042,7 @@ var VersionDiffDocument = gql`
         endLine
         isPublic
         minArity
-        symbolId
+        symbolRef
       }
       to {
         contentHash
@@ -1029,7 +1052,7 @@ var VersionDiffDocument = gql`
         endLine
         isPublic
         minArity
-        symbolId
+        symbolRef
       }
     }
     hasMore
@@ -1198,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);
 }
 
@@ -1371,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) {
@@ -1491,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";
@@ -1749,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;
@@ -1998,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 };
   }
@@ -2006,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
@@ -2296,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),
@@ -2360,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.
 
@@ -2373,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";
@@ -2404,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));
@@ -2432,27 +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");
-  let hint = "";
-  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)
@@ -2480,14 +2788,20 @@ function formatSeverity(severity) {
   return indicators[severity] || severity;
 }
 function extractGraphQLError(error) {
-  if (error && typeof error === "object" && "response" in error && error.response && typeof error.response === "object" && "errors" in error.response && Array.isArray(error.response.errors)) {
-    const errors = error.response.errors;
-    if (errors.length > 0) {
-      const messages = errors.map((e) => e.message).filter((m) => typeof m === "string");
+  if (error && typeof error === "object" && "response" in error && error.response && typeof error.response === "object" && "errors" in error.response) {
+    const respErrors = error.response.errors;
+    if (Array.isArray(respErrors)) {
+      const messages = respErrors.map((e) => e.message).filter((m) => typeof m === "string");
       if (messages.length > 0) {
         return messages.join("; ");
       }
     }
+    if (respErrors && typeof respErrors === "object" && !Array.isArray(respErrors) && "detail" in respErrors) {
+      const detail = respErrors.detail;
+      if (typeof detail === "string") {
+        return detail;
+      }
+    }
   }
   if (error && typeof error === "object" && "errors" in error && Array.isArray(error.errors)) {
     const errors = error.errors;
@@ -2535,17 +2849,10 @@ async function withCliErrorHandling(json, fn) {
       return;
     }
     const message = error instanceof Error ? error.message : "Unknown error";
-    const lower = message.toLowerCase();
-    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(/^([^:]+):/);
@@ -2581,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);
 }
@@ -2629,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}`);
   }
@@ -2659,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(`
 `);
@@ -2669,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(", ")}`);
@@ -2690,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"),
@@ -2700,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);
@@ -2730,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) {
@@ -2742,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);
@@ -2822,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.
@@ -2882,14 +3190,21 @@ 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;
   if (options.json) {
-    output(result.data.listRepoFiles, true);
+    output(data, true);
   } else {
-    console.log(formatFilesResult(result.data.listRepoFiles));
+    const formatted = formatFilesResult(data);
+    if (data.files.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
   }
 }
 var FILES_DESCRIPTION = `List files in a package's indexed repository.
@@ -2940,14 +3255,21 @@ 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;
   if (options.json) {
-    output(result.data.findSymbol, true);
+    output(data, true);
   } else {
-    console.log(formatFindResult(result.data.findSymbol));
+    const formatted = formatFindResult(data);
+    if (data.symbols.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
   }
 }
 var FIND_DESCRIPTION = `Find symbols (functions, classes, modules) by name.
@@ -3007,14 +3329,21 @@ 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;
   if (options.json) {
-    output(result.data.grepRepoFile, true);
+    output(data, true);
   } else {
-    console.log(formatGrepResult(result.data.grepRepoFile));
+    const formatted = formatGrepResult(data);
+    if (data.matches.length === 0 && data.diagnostics?.hint) {
+      console.log(`${formatted}
+Note: ${data.diagnostics.hint}`);
+    } else {
+      console.log(formatted);
+    }
   }
 }
 var GREP_DESCRIPTION = `Search for a pattern within a file in a package's repository.
@@ -3087,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.
@@ -3124,9 +3453,6 @@ function formatListResult(data) {
   if (data.file) {
     lines.push(`File: ${data.file.path}${data.file.language ? ` (${data.file.language})` : ""}`);
   }
-  if (data.error) {
-    lines.push(`Warning: ${data.error}`);
-  }
   lines.push("");
   for (const symbol of data.symbols) {
     lines.push(formatSymbol(symbol));
@@ -3159,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.
@@ -3205,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("");
   }
@@ -3216,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);
@@ -3304,14 +3630,25 @@ 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;
   if (options.json) {
-    output(result.data.searchSymbols, true);
+    output(data, true);
   } else {
-    console.log(formatSearchResult(result.data.searchSymbols));
+    let formatted = formatSearchResult(data);
+    if (data.warning) {
+      formatted = `Warning: ${data.warning}
+
+${formatted}`;
+    }
+    if (data.results.length === 0 && data.diagnostics?.hint) {
+      formatted = `${formatted}
+Note: ${data.diagnostics.hint}`;
+    }
+    console.log(formatted);
   }
 }
 var SEARCH_DESCRIPTION = `Full-text search within package code.
@@ -3535,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,
@@ -3545,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
         }
       };
     }
@@ -3579,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,
@@ -3588,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) {
@@ -3734,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;
@@ -3750,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.
@@ -4229,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)
@@ -4262,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;
@@ -4273,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;
@@ -4316,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()}`);
@@ -4358,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;
@@ -4379,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;
         }
       }
@@ -4535,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 {
@@ -6363,19 +6700,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;
@@ -6424,7 +6748,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.")
@@ -6432,34 +6756,52 @@ 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 kind = classifyError(message);
+  const hint = MCP_HINTS[kind];
+  if (hint) {
+    return `Failed to ${operation}: ${message}. ${hint}`;
+  }
   const lower = message.toLowerCase();
-  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.";
+  if (lower.includes("graphql error (code: 500)")) {
+    try {
+      const jsonMatch = message.match(/\{.*\}/s);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]);
+        const detail = parsed.errors?.detail ?? parsed.detail;
+        if (typeof detail === "string") {
+          return `Failed to ${operation}: ${detail}`;
+        }
+      }
+    } catch {}
+    const detailMatch = message.match(/"detail"\s*:\s*"([^"]+)"/);
+    if (detailMatch?.[1]) {
+      return `Failed to ${operation}: ${detailMatch[1]}`;
+    }
   }
   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 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 (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;
 }
@@ -6477,8 +6819,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
@@ -6492,11 +6834,11 @@ function createCallPathTool(pkgseerService) {
       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,
@@ -6506,10 +6848,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));
       });
     }
   };
@@ -6532,7 +6874,7 @@ function createComparePackagesTool(pkgseerService) {
     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
         }));
@@ -6540,10 +6882,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));
       });
     }
   };
@@ -6571,10 +6913,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));
       });
     }
   };
@@ -6595,10 +6937,10 @@ function createFetchPackageDocTool(pkgseerService) {
         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));
       });
     }
   };
@@ -6629,11 +6971,11 @@ 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: "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 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,
     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),
@@ -6647,10 +6989,14 @@ 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);
         }
-        return textResult(JSON.stringify(result.data.findSymbol, null, 2));
+        const data = result.data?.findSymbol;
+        if (data.symbols.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
@@ -6674,7 +7020,7 @@ function createGrepRepoFileTool(pkgseerService) {
     schema: argsSchema6,
     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,
@@ -6683,10 +7029,14 @@ 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);
         }
-        return textResult(JSON.stringify(result.data.grepRepoFile, null, 2));
+        const data = result.data?.grepRepoFile;
+        if (data.matches.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
@@ -6704,14 +7054,14 @@ function createListPackageDocsTool(pkgseerService) {
     schema: argsSchema7,
     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));
       });
     }
   };
@@ -6733,7 +7083,7 @@ function createListRepoFilesTool(pkgseerService) {
     schema: argsSchema8,
     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,
@@ -6742,10 +7092,14 @@ 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);
         }
-        return textResult(JSON.stringify(result.data.listRepoFiles, null, 2));
+        const data = result.data?.listRepoFiles;
+        if (data.files.length === 0 && data.diagnostics?.hint) {
+          return textResult(JSON.stringify({ ...data, _hint: data.diagnostics.hint }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
@@ -6768,7 +7122,7 @@ 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 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 refs, names, qualified paths, kinds, and file locations. " + "Use find_symbol(name=<symbol>, include_code=true) to get source for any listed symbol.",
     schema: argsSchema9,
     handler: async (args, _extra) => {
       return withErrorHandling("list symbols", async () => {
@@ -6784,7 +7138,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,
@@ -6797,10 +7151,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));
       });
     }
   };
@@ -6893,20 +7247,20 @@ function createPackageDependenciesTool(pkgseerService) {
     schema: argsSchema10,
     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,
@@ -6920,7 +7274,7 @@ function createPackageDependenciesTool(pkgseerService) {
               raw: deps.transitive.dag
             }
           } : undefined,
-          raw: result.data.packageDependencies
+          raw: result.data?.packageDependencies
         };
         return textResult(JSON.stringify(output2, null, 2));
       });
@@ -6946,7 +7300,7 @@ function createPackageImportsTool(pkgseerService) {
     schema: argsSchema11,
     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,
@@ -6957,10 +7311,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));
       });
     }
   };
@@ -6978,14 +7332,14 @@ function createPackageQualityTool(pkgseerService) {
     schema: argsSchema12,
     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));
       });
     }
   };
@@ -7002,14 +7356,14 @@ function createPackageSummaryTool(pkgseerService) {
     schema: argsSchema13,
     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));
       });
     }
   };
@@ -7027,14 +7381,14 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     schema: argsSchema14,
     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));
       });
     }
   };
@@ -7099,7 +7453,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
         }));
@@ -7111,7 +7465,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.");
         }
@@ -7191,13 +7545,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));
       });
     }
   };
@@ -7218,7 +7572,7 @@ function createSearchStatusTool(pkgseerService) {
         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).");
         }
@@ -7227,7 +7581,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).");
           }
@@ -7281,7 +7635,7 @@ function createSearchSymbolsTool(pkgseerService) {
     schema: argsSchema18,
     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),
@@ -7295,10 +7649,21 @@ 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);
         }
-        return textResult(JSON.stringify(result.data.searchSymbols, null, 2));
+        const data = result.data?.searchSymbols;
+        const extra = {};
+        if (data.results.length === 0 && data.diagnostics?.hint) {
+          extra._hint = data.diagnostics.hint;
+        }
+        if (data.warning) {
+          extra._warning = data.warning;
+        }
+        if (Object.keys(extra).length > 0) {
+          return textResult(JSON.stringify({ ...data, ...extra }, null, 2));
+        }
+        return textResult(JSON.stringify(data, null, 2));
       });
     }
   };
@@ -7306,7 +7671,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"),
@@ -7317,13 +7682,13 @@ 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: "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_ref from find_symbol or list_symbols results. See symbol_callers for the reverse.",
     schema: argsSchema19,
     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,
@@ -7336,10 +7701,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));
       });
     }
   };
@@ -7347,8 +7712,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
@@ -7356,16 +7722,17 @@ 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: "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_ref from find_symbol or list_symbols results. See symbol_callees for the reverse.",
     schema: argsSchema20,
     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
@@ -7373,10 +7740,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));
       });
     }
   };
@@ -7405,7 +7772,7 @@ function createTriggerIndexingTool(pkgseerService) {
     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
         }));
@@ -7421,7 +7788,7 @@ function createTriggerIndexingTool(pkgseerService) {
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.triggerIndexing) {
+        if (!result.data?.triggerIndexing) {
           return {
             content: [
               {
@@ -7432,7 +7799,7 @@ function createTriggerIndexingTool(pkgseerService) {
             isError: true
           };
         }
-        return textResult(JSON.stringify(result.data.triggerIndexing, null, 2));
+        return textResult(JSON.stringify(result.data?.triggerIndexing, null, 2));
       });
     }
   };
@@ -7464,7 +7831,7 @@ function createVersionDiffTool(pkgseerService) {
     schema: argsSchema22,
     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,
@@ -7473,10 +7840,10 @@ 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));
       });
     }
   };
@@ -7669,12 +8036,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,
@@ -7683,7 +8050,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.
@@ -7752,13 +8119,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,
@@ -7771,7 +8138,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;
@@ -7784,7 +8151,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.
@@ -7868,12 +8235,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,
@@ -7885,7 +8252,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.
@@ -7936,15 +8303,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) => ({
@@ -7954,7 +8321,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.
@@ -8039,12 +8406,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}`,
@@ -8058,7 +8425,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.