@pkgseer/cli 0.1.5 → 0.2.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-0fnprry7.js";
+} from "./shared/chunk-9016p6c6.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -205,11 +205,65 @@ var CliDocsListDocument = gql`
     pages {
       id
       title
-      words
     }
   }
 }
     `;
+var CombinedSearchDocument = gql`
+    query CombinedSearch($packages: [SearchPackageInput!]!, $query: String!, $mode: SearchMode, $limit: Int) {
+  combinedSearch(packages: $packages, query: $query, mode: $mode, limit: $limit) {
+    query
+    mode
+    totalResults
+    entries {
+      id
+      type
+      title
+      subtitle
+      packageName
+      registry
+      score
+      snippet
+      filePath
+      startLine
+      endLine
+      language
+      chunkType
+      repoUrl
+      gitRef
+      pageId
+      sourceUrl
+    }
+    indexingStatus {
+      registry
+      packageName
+      version
+      codeStatus
+      docsStatus
+    }
+  }
+}
+    `;
+var FetchCodeContextDocument = gql`
+    query FetchCodeContext($repoUrl: String!, $gitRef: String!, $filePath: String!, $startLine: Int, $endLine: Int) {
+  fetchCodeContext(
+    repoUrl: $repoUrl
+    gitRef: $gitRef
+    filePath: $filePath
+    startLine: $startLine
+    endLine: $endLine
+  ) {
+    content
+    filePath
+    language
+    totalLines
+    startLine
+    endLine
+    repoUrl
+    gitRef
+  }
+}
+    `;
 var CliDocsGetDocument = gql`
     query CliDocsGet($registry: Registry!, $packageName: String!, $pageId: String!, $version: String) {
   fetchPackageDoc(
@@ -428,7 +482,6 @@ var ListPackageDocsDocument = gql`
       slug
       order
       linkName
-      words
       lastUpdatedAt
       sourceUrl
     }
@@ -509,7 +562,6 @@ var SearchPackageDocsDocument = gql`
       slug
       order
       linkName
-      words
       lastUpdatedAt
       sourceUrl
       matchCount
@@ -540,7 +592,6 @@ var SearchProjectDocsDocument = gql`
       registry
       packageName
       version
-      words
       matchCount
       titleHit
       score
@@ -560,6 +611,8 @@ var CliComparePackagesDocumentString = print(CliComparePackagesDocument);
 var CliDocsSearchDocumentString = print(CliDocsSearchDocument);
 var CliProjectDocsSearchDocumentString = print(CliProjectDocsSearchDocument);
 var CliDocsListDocumentString = print(CliDocsListDocument);
+var CombinedSearchDocumentString = print(CombinedSearchDocument);
+var FetchCodeContextDocumentString = print(FetchCodeContextDocument);
 var CliDocsGetDocumentString = print(CliDocsGetDocument);
 var CreateProjectDocumentString = print(CreateProjectDocument);
 var PackageSummaryDocumentString = print(PackageSummaryDocument);
@@ -598,6 +651,12 @@ function getSdk(client, withWrapper = defaultWrapper) {
     CliDocsList(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliDocsListDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliDocsList", "query", variables);
     },
+    CombinedSearch(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CombinedSearchDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CombinedSearch", "query", variables);
+    },
+    FetchCodeContext(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(FetchCodeContextDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "FetchCodeContext", "query", variables);
+    },
     CliDocsGet(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliDocsGetDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliDocsGet", "query", variables);
     },
@@ -960,7 +1019,8 @@ var TOOL_NAMES = [
   "compare_packages",
   "list_package_docs",
   "fetch_package_doc",
-  "search_package_docs",
+  "search",
+  "fetch_code_context",
   "search_project_docs"
 ];
 var ToolNameSchema = z.enum(TOOL_NAMES);
@@ -1002,7 +1062,10 @@ class ConfigServiceImpl {
     return this.loadAndParseConfig(configPath, GlobalConfigSchema);
   }
   async loadProjectConfig() {
-    let currentDir = this.fs.getCwd();
+    return this.loadProjectConfigFrom(this.fs.getCwd());
+  }
+  async loadProjectConfigFrom(startDir) {
+    let currentDir = startDir;
     while (true) {
       const configPath = this.fs.joinPath(currentDir, PROJECT_CONFIG_FILE);
       const config = await this.loadAndParseConfig(configPath, ProjectConfigSchema);
@@ -1350,6 +1413,25 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
+  async combinedSearch(packages, query, options) {
+    const result = await this.client.CombinedSearch({
+      packages,
+      query,
+      mode: options?.mode,
+      limit: options?.limit
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async fetchCodeContext(repoUrl, gitRef, filePath, options) {
+    const result = await this.client.FetchCodeContext({
+      repoUrl,
+      gitRef,
+      filePath,
+      startLine: options?.startLine,
+      endLine: options?.endLine
+    });
+    return { data: result.data, errors: result.errors };
+  }
 }
 // src/services/project-service.ts
 var PROJECT_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
@@ -2182,8 +2264,7 @@ function formatDocsList(docs) {
   for (const page of docs.pages) {
     if (!page || !page.id)
       continue;
-    const words = page.words ? ` (${formatNumber(page.words)} words)` : "";
-    lines.push(`  ${page.title}${words}`);
+    lines.push(`  ${page.title}`);
     lines.push(`    ID: ${page.id}`);
     lines.push("");
   }
@@ -2234,51 +2315,6 @@ function registerDocsListCommand(program) {
   });
 }
 // src/commands/docs/search.ts
-function summarizeSearchResults(results) {
-  const entries = results.entries ?? [];
-  const count = entries.length;
-  const totalMatches = entries.reduce((acc, e) => acc + (e?.matchCount ?? 0), 0);
-  const lines = [];
-  lines.push(`Results: ${count} page${count === 1 ? "" : "s"} | matches: ${totalMatches}`);
-  lines.push("");
-  for (const entry of entries.filter((e) => !!e)) {
-    lines.push(`- ${entry.title ?? entry.slug ?? "untitled"} (${entry.matchCount ?? 0} matches)`);
-  }
-  if (count === 0) {
-    lines.push("No matches. Try broader terms or fewer constraints.");
-  }
-  return lines.join(`
-`);
-}
-function buildDocRef(entry, searchResult) {
-  if (!entry?.slug)
-    return "";
-  let registry;
-  let packageName;
-  let version2;
-  if ("packageName" in entry && "registry" in entry && "version" in entry) {
-    registry = entry.registry;
-    packageName = entry.packageName;
-    version2 = entry.version;
-  } else {
-    const rawRegistry = "registry" in searchResult ? searchResult.registry : null;
-    registry = rawRegistry ? rawRegistry.toLowerCase() : null;
-    packageName = "packageName" in searchResult ? searchResult.packageName : null;
-    version2 = "version" in searchResult ? searchResult.version : null;
-  }
-  const parts = [];
-  if (registry)
-    parts.push(registry.toLowerCase());
-  if (packageName)
-    parts.push(packageName);
-  if (version2)
-    parts.push(version2);
-  else if (registry && packageName)
-    parts.push("latest");
-  if (entry.slug)
-    parts.push(entry.slug);
-  return parts.join("/");
-}
 var colors = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -2286,7 +2322,8 @@ var colors = {
   magenta: "\x1B[35m",
   cyan: "\x1B[36m",
   yellow: "\x1B[33m",
-  green: "\x1B[32m"
+  green: "\x1B[32m",
+  blue: "\x1B[34m"
 };
 function shouldUseColors(noColor) {
   if (noColor)
@@ -2295,219 +2332,420 @@ function shouldUseColors(noColor) {
     return false;
   return process.stdout.isTTY ?? false;
 }
-function applyHighlights(line, highlights, useColors) {
-  if (!highlights || highlights.length === 0 || !useColors) {
-    return line;
-  }
-  const sorted = [...highlights].filter((h) => h && h.start != null && h.end != null).sort((a, b) => {
-    const aStart = a?.start ?? 0;
-    const bStart = b?.start ?? 0;
-    return bStart - aStart;
+function toSearchMode(mode) {
+  if (!mode)
+    return "ALL";
+  const map = {
+    all: "ALL",
+    code: "CODE",
+    docs: "DOCS"
+  };
+  return map[mode.toLowerCase()] ?? "ALL";
+}
+function parsePackageList(input2) {
+  return input2.split(",").map((spec) => {
+    const trimmed = spec.trim();
+    const atIndex = trimmed.lastIndexOf("@");
+    let regPkg;
+    let version2;
+    if (atIndex > 0) {
+      regPkg = trimmed.slice(0, atIndex);
+      version2 = trimmed.slice(atIndex + 1);
+    } else {
+      regPkg = trimmed;
+    }
+    const slashIndex = regPkg.indexOf("/");
+    if (slashIndex === -1) {
+      return {
+        registry: "NPM",
+        name: regPkg,
+        version: version2
+      };
+    }
+    const beforeSlash = regPkg.slice(0, slashIndex);
+    const afterSlash = regPkg.slice(slashIndex + 1);
+    if (beforeSlash.startsWith("@")) {
+      return {
+        registry: "NPM",
+        name: regPkg,
+        version: version2
+      };
+    }
+    return {
+      registry: toGraphQLRegistry(beforeSlash),
+      name: afterSlash,
+      version: version2
+    };
   });
-  let result = line;
-  for (const h of sorted) {
-    if (!h || h.start == null || h.end == null)
-      continue;
-    const before = result.slice(0, h.start);
-    const match = result.slice(h.start, h.end);
-    const after = result.slice(h.end);
-    result = `${before}${colors.bold}${colors.magenta}${match}${colors.reset}${after}`;
+}
+function formatTypeBadge(type, useColors) {
+  const typeStr = type ?? "DOC";
+  if (useColors) {
+    const color = typeStr === "CODE" ? colors.magenta : colors.cyan;
+    return `${color}[${typeStr}]${colors.reset}`;
   }
-  return result;
+  return `[${typeStr}]`;
 }
-function formatEntry(entry, searchResult, useColors) {
+function formatEntry(entry, useColors) {
   if (!entry)
     return "";
   const lines = [];
-  const ref = buildDocRef(entry, searchResult);
-  const matchInfo = entry.matchCount && entry.matchCount > 0 ? ` (${entry.matchCount} match${entry.matchCount > 1 ? "es" : ""})` : "";
-  if (useColors) {
-    lines.push(`${colors.cyan}${ref}${colors.reset}: ${colors.bold}${entry.title}${colors.reset}${colors.dim}${matchInfo}${colors.reset}`);
-  } else {
-    lines.push(`${ref}: ${entry.title}${matchInfo}`);
-  }
-  const matches = entry.matches ?? [];
-  for (const match of matches) {
-    if (!match?.context)
-      continue;
-    const ctx = match.context;
-    for (const beforeLine of ctx.before ?? []) {
-      if (beforeLine) {
-        const prefix = useColors ? colors.dim : "";
-        const suffix = useColors ? colors.reset : "";
-        lines.push(`  ${prefix}${beforeLine}${suffix}`);
+  const badge = formatTypeBadge(entry.type, useColors);
+  if (entry.type === "CODE") {
+    const title = entry.title ?? "Unknown";
+    const location = entry.filePath ? `${entry.filePath}:${entry.startLine ?? "?"}-${entry.endLine ?? "?"}` : "";
+    const lang = entry.language ? ` • ${entry.language}` : "";
+    if (useColors) {
+      lines.push(`${badge} ${colors.bold}${title}${colors.reset}`);
+      if (location) {
+        lines.push(`  ${colors.dim}${location}${lang}${colors.reset}`);
       }
-    }
-    for (const matchedLine of ctx.matchedLines ?? []) {
-      if (matchedLine?.content) {
-        const highlighted = applyHighlights(matchedLine.content, matchedLine.highlights, useColors);
-        lines.push(`  ${highlighted}`);
+    } else {
+      lines.push(`${badge} ${title}`);
+      if (location) {
+        lines.push(`  ${location}${lang}`);
       }
     }
-    for (const afterLine of ctx.after ?? []) {
-      if (afterLine) {
-        const prefix = useColors ? colors.dim : "";
-        const suffix = useColors ? colors.reset : "";
-        lines.push(`  ${prefix}${afterLine}${suffix}`);
+  } else {
+    const title = entry.title ?? "Untitled";
+    const ref = entry.pageId ?? entry.sourceUrl ?? "";
+    if (useColors) {
+      lines.push(`${badge} ${colors.bold}${title}${colors.reset}`);
+      if (ref) {
+        lines.push(`  ${colors.dim}${ref}${colors.reset}`);
+      }
+    } else {
+      lines.push(`${badge} ${title}`);
+      if (ref) {
+        lines.push(`  ${ref}`);
       }
     }
+  }
+  if (entry.snippet) {
     lines.push("");
+    const snippetLines = entry.snippet.split(`
+`).slice(0, 5);
+    for (const line of snippetLines) {
+      if (useColors) {
+        lines.push(`  ${colors.dim}${line}${colors.reset}`);
+      } else {
+        lines.push(`  ${line}`);
+      }
+    }
   }
+  lines.push("");
   return lines.join(`
 `);
 }
+function formatPackageHeader(entry, prevEntry, useColors) {
+  const pkg = entry?.packageName ?? "unknown";
+  const registry = entry?.registry?.toLowerCase() ?? "npm";
+  const prevPkg = prevEntry?.packageName;
+  const prevRegistry = prevEntry?.registry?.toLowerCase();
+  if (pkg === prevPkg && registry === prevRegistry) {
+    return "";
+  }
+  const header = `${pkg} (${registry})`;
+  const separator = "═".repeat(Math.min(50, header.length + 10));
+  if (useColors) {
+    return `
+${colors.yellow}${header}${colors.reset}
+${colors.dim}${separator}${colors.reset}
+`;
+  }
+  return `
+${header}
+${separator}
+`;
+}
 function formatSearchResults(results, useColors) {
   const entries = results.entries ?? [];
   if (entries.length === 0) {
-    return "No matching documentation found. Try broader terms or fewer constraints.";
+    return "No results found. Try broader terms or different packages.";
+  }
+  const lines = [];
+  let prevEntry = null;
+  for (const entry of entries) {
+    if (!entry)
+      continue;
+    const header = formatPackageHeader(entry, prevEntry, useColors);
+    if (header) {
+      lines.push(header);
+    }
+    lines.push(formatEntry(entry, useColors));
+    prevEntry = entry;
+  }
+  const codeCount = entries.filter((e) => e?.type === "CODE").length;
+  const docCount = entries.filter((e) => e?.type === "DOC" || e?.type === "REPO_DOC").length;
+  if (useColors) {
+    lines.push(`${colors.dim}───────────────────────────────────────────────────${colors.reset}`);
+    lines.push(`${colors.dim}Results: ${entries.length} total (${codeCount} code, ${docCount} docs)${colors.reset}`);
+  } else {
+    lines.push("───────────────────────────────────────────────────");
+    lines.push(`Results: ${entries.length} total (${codeCount} code, ${docCount} docs)`);
+  }
+  const indexingWarnings = formatIndexingWarnings(results.indexingStatus);
+  if (indexingWarnings) {
+    lines.push("");
+    lines.push(indexingWarnings);
   }
-  const formatted = entries.filter((e) => e != null).map((entry) => formatEntry(entry, results, useColors));
-  return formatted.join(`
+  return lines.join(`
 `);
 }
 function formatRefsOnly(results) {
   const entries = results.entries ?? [];
-  return entries.filter((e) => e != null).map((entry) => buildDocRef(entry, results)).join(`
+  return entries.filter((e) => e != null).map((entry) => {
+    if (!entry)
+      return "";
+    if (entry.type === "CODE") {
+      return `${entry.repoUrl ?? ""}:${entry.filePath ?? ""}:${entry.startLine ?? ""}`;
+    }
+    return entry.pageId ?? entry.id ?? "";
+  }).filter((s) => s !== "").join(`
 `);
 }
 function formatCount(results) {
   const entries = results.entries ?? [];
-  return entries.filter((e) => e != null).map((entry) => {
+  const counts = new Map;
+  for (const entry of entries) {
     if (!entry)
-      return "";
-    const ref = buildDocRef(entry, results);
-    return `${ref}: ${entry.matchCount ?? 0}`;
-  }).filter((s) => s !== "").join(`
+      continue;
+    const key = `${entry.packageName ?? "unknown"}@${entry.registry?.toLowerCase() ?? "npm"}`;
+    const current = counts.get(key) ?? { code: 0, docs: 0 };
+    if (entry.type === "CODE") {
+      current.code++;
+    } else {
+      current.docs++;
+    }
+    counts.set(key, current);
+  }
+  return Array.from(counts.entries()).map(([pkg, { code, docs }]) => `${pkg}: ${code} code, ${docs} docs`).join(`
+`);
+}
+function formatIndexingWarnings(indexingStatus) {
+  if (!indexingStatus || indexingStatus.length === 0)
+    return null;
+  const warnings = [];
+  for (const status of indexingStatus) {
+    if (!status)
+      continue;
+    const pkg = `${status.packageName}@${status.version ?? "latest"}`;
+    if (status.codeStatus && status.codeStatus !== "INDEXED") {
+      warnings.push(`  - ${pkg}: code ${status.codeStatus.toLowerCase()}`);
+    }
+    if (status.docsStatus && status.docsStatus !== "INDEXED") {
+      warnings.push(`  - ${pkg}: docs ${status.docsStatus.toLowerCase()}`);
+    }
+  }
+  if (warnings.length === 0)
+    return null;
+  return `Note: Some packages are not fully indexed:
+` + warnings.join(`
+`) + `
+Results may be incomplete.`;
+}
+var LANG_ABBREV = {
+  javascript: "js",
+  typescript: "ts",
+  python: "py",
+  markdown: "md"
+};
+function abbrevLang(lang) {
+  if (!lang)
+    return "";
+  const lower = lang.toLowerCase();
+  return LANG_ABBREV[lower] ?? lower;
+}
+function truncate(text, maxLen) {
+  if (text.length <= maxLen)
+    return text;
+  return text.slice(0, maxLen - 3) + "...";
+}
+function formatEntryCompact(entry, useColors) {
+  if (!entry)
+    return "";
+  const badge = formatTypeBadge(entry.type, useColors);
+  let header;
+  if (entry.type === "CODE") {
+    const loc = entry.filePath ? `${entry.filePath}:${entry.startLine ?? "?"}-${entry.endLine ?? "?"}` : "";
+    const lang = abbrevLang(entry.language);
+    const title = entry.title && entry.title !== "Unnamed" ? ` ${entry.title}` : "";
+    header = `${badge} ${loc}${lang ? ` ${lang}` : ""}${title}`;
+  } else {
+    const title = entry.title ?? "Untitled";
+    const ref = entry.pageId ? ` (${entry.pageId})` : "";
+    header = `${badge} ${title}${ref}`;
+  }
+  let snippet = "";
+  if (entry.snippet) {
+    const firstLine = entry.snippet.split(`
+`).map((l) => l.trim()).find((l) => l.length > 0);
+    if (firstLine) {
+      snippet = `  ${truncate(firstLine, 80)}`;
+      if (useColors) {
+        snippet = `  ${colors.dim}${truncate(firstLine, 80)}${colors.reset}`;
+      }
+    }
+  }
+  return snippet ? `${header}
+${snippet}` : header;
+}
+function formatPackageHeaderCompact(entry, prevEntry, useColors) {
+  const pkg = entry?.packageName ?? "unknown";
+  const registry = entry?.registry?.toLowerCase() ?? "npm";
+  const prevPkg = prevEntry?.packageName;
+  const prevRegistry = prevEntry?.registry?.toLowerCase();
+  if (pkg === prevPkg && registry === prevRegistry) {
+    return "";
+  }
+  const header = `${pkg} (${registry})`;
+  if (useColors) {
+    return `
+${colors.yellow}${header}${colors.reset}`;
+  }
+  return `
+${header}`;
+}
+function formatSearchResultsCompact(results, useColors) {
+  const entries = results.entries ?? [];
+  if (entries.length === 0) {
+    return "No results. Try broader terms or different packages.";
+  }
+  const lines = [];
+  let prevEntry = null;
+  for (const entry of entries) {
+    if (!entry)
+      continue;
+    const header = formatPackageHeaderCompact(entry, prevEntry, useColors);
+    if (header) {
+      lines.push(header);
+    }
+    lines.push(formatEntryCompact(entry, useColors));
+    prevEntry = entry;
+  }
+  const codeCount = entries.filter((e) => e?.type === "CODE").length;
+  const docCount = entries.filter((e) => e?.type === "DOC" || e?.type === "REPO_DOC").length;
+  lines.push(`
+${entries.length} results (${codeCount} code, ${docCount} docs)`);
+  const indexingWarnings = formatIndexingWarnings(results.indexingStatus);
+  if (indexingWarnings) {
+    lines.push(indexingWarnings);
+  }
+  return lines.join(`
 `);
 }
-function slimSearchResults(results) {
+function summarizeSearchResults(results) {
   const entries = results.entries ?? [];
-  return entries.filter((e) => e != null).map((entry) => {
+  const codeCount = entries.filter((e) => e?.type === "CODE").length;
+  const docCount = entries.filter((e) => e?.type === "DOC" || e?.type === "REPO_DOC").length;
+  const lines = [];
+  lines.push(`Results: ${entries.length} total | ${codeCount} code | ${docCount} docs`);
+  lines.push("");
+  const byPackage = new Map;
+  for (const entry of entries) {
     if (!entry)
-      return null;
-    return {
-      ref: buildDocRef(entry, results),
-      title: entry.title ?? "",
-      matchCount: entry.matchCount ?? 0,
-      matches: entry.matches?.filter((m) => m?.context).map((m) => {
-        if (!m?.context)
-          return null;
-        return {
-          before: (m.context.before ?? []).filter((l) => l != null),
-          lines: (m.context.matchedLines ?? []).filter((l) => l?.content).map((l) => l?.content ?? ""),
-          after: (m.context.after ?? []).filter((l) => l != null)
-        };
-      }).filter((m) => m != null)
-    };
-  }).filter((e) => e != null);
+      continue;
+    const key = `${entry.packageName ?? "unknown"} (${entry.registry?.toLowerCase() ?? "npm"})`;
+    const list = byPackage.get(key) ?? [];
+    list.push(entry);
+    byPackage.set(key, list);
+  }
+  for (const [pkg, pkgEntries] of byPackage) {
+    const pkgCode = pkgEntries.filter((e) => e?.type === "CODE").length;
+    const pkgDocs = pkgEntries.filter((e) => e?.type === "DOC" || e?.type === "REPO_DOC").length;
+    lines.push(`- ${pkg}: ${pkgCode} code, ${pkgDocs} docs`);
+  }
+  if (entries.length === 0) {
+    lines.push("No results. Try broader terms or different packages.");
+  }
+  return lines.join(`
+`);
 }
 async function docsSearchAction(queryArg, options, deps) {
-  const { pkgseerService, config } = deps;
-  const providedTerms = Array.isArray(queryArg) ? queryArg : queryArg ? [queryArg] : [];
-  const terms = providedTerms.concat(options.terms ?? []);
-  if (!terms.length) {
-    outputError("Search terms required. Provide terms as argument or with --terms", options.json ?? false);
+  const { pkgseerService } = deps;
+  const query = Array.isArray(queryArg) ? queryArg.join(" ") : queryArg ?? "";
+  if (!query.trim()) {
+    outputError("Search query required. Provide query as argument.", options.json ?? false);
     return;
   }
-  const contextBefore = options.context ? Number.parseInt(options.context, 10) : options.before ? Number.parseInt(options.before, 10) : 2;
-  const contextAfter = options.context ? Number.parseInt(options.context, 10) : options.after ? Number.parseInt(options.after, 10) : 2;
-  const maxMatches = options.maxMatches ? Number.parseInt(options.maxMatches, 10) : 5;
-  const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
-  const matchMode = options.match_mode?.toUpperCase() || options.mode?.toUpperCase() || undefined;
-  const useColors = shouldUseColors(options.noColor);
-  const project = options.project ?? config.project;
-  const packageName = options.package;
-  if (packageName) {
-    const registry = toGraphQLRegistry(options.registry ?? "npm");
-    const result = await pkgseerService.cliDocsSearch(registry, packageName, {
-      keywords: terms,
-      matchMode,
-      limit,
-      version: options.pkgVersion,
-      contextLinesBefore: contextBefore,
-      contextLinesAfter: contextAfter,
-      maxMatches
-    });
-    handleErrors(result.errors, options.json ?? false);
-    if (!result.data.searchPackageDocs) {
-      outputError(`No documentation found for ${packageName} in ${options.registry ?? "npm"}`, options.json ?? false);
-      return;
-    }
-    outputResults(result.data.searchPackageDocs, options, useColors);
+  if (!options.packages) {
+    outputError(`Package(s) required. Use -P or --packages:
+` + `  -P express              Single package (assumes npm)
+` + `  -P express,lodash       Multiple packages
+` + `  -P pypi/django          With registry prefix
+` + "  -P express@4.18.2       With version", options.json ?? false);
     return;
   }
-  if (project) {
-    const result = await pkgseerService.cliProjectDocsSearch(project, {
-      keywords: terms,
-      matchMode,
-      limit,
-      contextLinesBefore: contextBefore,
-      contextLinesAfter: contextAfter,
-      maxMatches
-    });
-    handleErrors(result.errors, options.json ?? false);
-    if (!result.data.searchProjectDocs) {
-      outputError(`Project not found: ${project}`, options.json ?? false);
-      return;
-    }
-    outputResults(result.data.searchProjectDocs, options, useColors);
+  const packages = parsePackageList(options.packages);
+  const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
+  const mode = toSearchMode(options.mode);
+  const useColors = shouldUseColors(options.noColor);
+  const result = await pkgseerService.combinedSearch(packages, query, {
+    mode,
+    limit
+  });
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.combinedSearch) {
+    outputError("No results returned. Check package names and registries.", options.json ?? false);
     return;
   }
-  outputError(`No project configured. Either:
-` + `  - Add project to pkgseer.yml
-` + `  - Use --project <name> to specify a project
-` + "  - Use --package <name> to search a specific package", options.json ?? false);
+  outputResults(result.data.combinedSearch, options, useColors);
 }
 function outputResults(results, options, useColors) {
   const format = options.json ? "json" : options.format ?? "human";
   if (format === "json") {
-    output(slimSearchResults(results), true);
+    output(results, true);
   } else if (options.refsOnly) {
     console.log(formatRefsOnly(results));
   } else if (options.count) {
     console.log(formatCount(results));
   } else if (format === "summary") {
     console.log(summarizeSearchResults(results));
-  } else {
+  } else if (options.verbose) {
     console.log(formatSearchResults(results, useColors));
+  } else {
+    console.log(formatSearchResultsCompact(results, useColors));
   }
 }
-var SEARCH_DESCRIPTION = `Search documentation with grep-like output.
-
-Searches across package or project documentation with keyword
-or freeform query support. Shows matching lines with context
-and highlights matched terms.
+var SEARCH_DESCRIPTION = `Search code and documentation across packages.
 
-By default, searches project documentation if project is
-configured in pkgseer.yml. Use --package to search a specific
-package instead.
+Searches both code (functions, classes) and documentation pages
+using the combined search endpoint. Returns results with snippets
+showing matches.
 
 Examples:
-  # Search with context (like grep)
-  pkgseer docs search "error handling" --package express
-  pkgseer docs search log --package express -C 3
+  # Search a single package (code + docs)
+  pkgseer docs search "error handling" -P express
 
-  # Multiple terms (OR by default)
-  pkgseer docs search -t "middleware,routing" --package express
+  # Search code only
+  pkgseer docs search "Router.use" -P express --mode code
 
-  # Strict matching (AND mode)
-  pkgseer docs search -t "error,middleware" --match-mode all --package express
+  # Search docs only
+  pkgseer docs search "middleware" -P express --mode docs
+
+  # Search multiple packages
+  pkgseer docs search "auth" -P express,passport
+
+  # With registry prefix (for non-npm packages)
+  pkgseer docs search "orm" -P pypi/django,pypi/sqlalchemy
+
+  # With specific version
+  pkgseer docs search "routing" -P express@4.18.2
 
   # Output for piping
-  pkgseer docs search log --package express --refs-only | \\
-    xargs -I{} pkgseer docs get express {}
+  pkgseer docs search "routing" -P express --refs-only
 
-  # Count matches
-  pkgseer docs search error --package express --count`;
+  # JSON output
+  pkgseer docs search "error" -P express --json`;
 function addSearchOptions(cmd) {
-  return cmd.option("-p, --package <name>", "Search specific package (overrides project)").option("-r, --registry <registry>", "Package registry (with --package)", "npm").option("-v, --pkg-version <version>", "Package version (with --package)").option("--project <name>", "Project name (overrides config)").option("-t, --terms <words>", "Comma-separated search terms", (val) => val.split(",").map((s) => s.trim())).option("-l, --limit <n>", "Max results (default: 25)").option("-A, --after <n>", "Lines of context after match (default: 2)").option("-B, --before <n>", "Lines of context before match (default: 2)").option("-C, --context <n>", "Lines of context before and after match").option("--max-matches <n>", "Max matches per page (default: 5)").option("--match-mode <mode>", "How to combine terms: any/or (default) or all/and").option("--refs-only", "Output only page references (for piping)").option("--count", "Output only match counts per page").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
+  return cmd.option("-P, --packages <packages>", "Packages to search (comma-separated). Format: name or registry/name[@version]. Examples: express | express,lodash | pypi/django@4.2").option("-m, --mode <mode>", "Search mode: all (default), code, docs").option("-l, --limit <n>", "Max results (default: 25)").option("-v, --verbose", "Expanded output with more details").option("--refs-only", "Output only references (for piping)").option("--count", "Output result counts by package").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
 }
 function registerDocsSearchCommand(program) {
-  const cmd = program.command("search [terms...]").summary("Search documentation").description(SEARCH_DESCRIPTION);
-  addSearchOptions(cmd).action(async (terms, options) => {
+  const cmd = program.command("search [query...]").summary("Search code and documentation").description(SEARCH_DESCRIPTION);
+  addSearchOptions(cmd).action(async (query, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
-      await docsSearchAction(terms, options, deps);
+      await docsSearchAction(query, options, deps);
     });
   });
 }
@@ -2684,6 +2922,56 @@ Note: Create the ${dirName} directory if it doesn't exist.`, useColors));
   console.log(dim(`
 After editing, restart your AI assistant to activate the MCP server.`, useColors));
 }
+async function isCliAvailable(shellService, command) {
+  try {
+    const checkCommand = process.platform === "win32" ? `where ${command}` : `which ${command}`;
+    await shellService.execute(checkCommand, process.cwd());
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function setupClaudeCodeViaCli(shellService, scope) {
+  try {
+    const command = `claude mcp add --transport stdio --scope ${scope} pkgseer -- npx -y @pkgseer/cli mcp start`;
+    await shellService.execute(command, process.cwd());
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function setupCodexViaCli(shellService) {
+  try {
+    const command = "codex mcp add pkgseer -- npx -y @pkgseer/cli mcp start";
+    await shellService.execute(command, process.cwd());
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+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");
+  if (!hasProject) {
+    console.log(dim(`
+Tip: Create pkgseer.yml to enable automatic project detection for search_project_docs.`, useColors));
+  }
+}
 async function mcpInitAction(deps) {
   const { fileSystemService: fs, promptService, hasProject } = deps;
   const useColors = shouldUseColors2();
@@ -2736,47 +3024,84 @@ Run ${highlight("pkgseer project init", useColors)} first, then ${highlight("pkg
   if (tool === "cursor" || tool === "codex" || tool === "claude-code") {
     const projectPath = tool === "cursor" ? ".cursor/mcp.json" : tool === "codex" ? ".codex/config.toml" : ".mcp.json";
     const globalPath = tool === "cursor" ? "~/.cursor/mcp.json" : tool === "codex" ? "~/.codex/config.toml" : "~/.claude.json";
-    if (hasProject) {
-      scope = await promptService.select("Where should the MCP config be created?", [
+    if (tool === "codex") {
+      console.log(dim(`
+Codex uses user-level configuration.
+`, useColors));
+      scope = "global";
+    } else {
+      scope = await promptService.select("Where should the MCP server be installed?", [
         {
-          value: "project",
-          name: `Project (${projectPath}) – recommended`,
-          description: "Uses project token; enables docs search for your packages"
+          value: "global",
+          name: `User-level (${globalPath}) – recommended`,
+          description: "Works across all projects. Use project_directory param for project features."
         },
         {
-          value: "global",
-          name: `Global (${globalPath})`,
-          description: "Works everywhere but without project-specific features"
+          value: "project",
+          name: `Project-level (${projectPath})`,
+          description: "Scoped to this project only."
         }
       ]);
-    } else {
-      console.log(dim(`
-Using global config (no pkgseer.yml found).
-`, useColors));
-      scope = "global";
     }
   }
   let configPath;
   let backupPath;
-  if (tool === "cursor") {
+  const { shellService } = deps;
+  if (tool === "claude-code") {
     if (!scope) {
       scope = "global";
     }
-    const paths = getCursorConfigPaths(fs, scope);
+    const claudeAvailable = await isCliAvailable(shellService, "claude");
+    if (claudeAvailable) {
+      console.log(dim(`
+Using Claude Code CLI to add MCP server...
+`, useColors));
+      const cliScope = scope === "global" ? "user" : "project";
+      const result = await setupClaudeCodeViaCli(shellService, cliScope);
+      if (result.success) {
+        console.log(success("PkgSeer MCP server configured for Claude Code!", useColors));
+        console.log(dim(`
+The MCP server has been registered. It should be available immediately.`, useColors));
+        showAvailableTools(hasProject, useColors);
+        return;
+      }
+      console.log(dim(`
+CLI setup failed: ${result.error}
+Falling back to file editing...
+`, useColors));
+    }
+    const paths = getClaudeCodeConfigPaths(fs, scope);
     configPath = paths.configPath;
     backupPath = paths.backupPath;
   } else if (tool === "codex") {
     if (!scope) {
-      scope = hasProject ? "project" : "global";
+      scope = "global";
+    }
+    const codexAvailable = await isCliAvailable(shellService, "codex");
+    if (codexAvailable) {
+      console.log(dim(`
+Using Codex CLI to add MCP server...
+`, useColors));
+      const result = await setupCodexViaCli(shellService);
+      if (result.success) {
+        console.log(success("PkgSeer MCP server configured for Codex CLI!", useColors));
+        console.log(dim(`
+The MCP server has been registered. It should be available immediately.`, useColors));
+        showAvailableTools(hasProject, useColors);
+        return;
+      }
+      console.log(dim(`
+CLI setup failed: ${result.error}
+`, useColors));
     }
     const paths = getCodexConfigPaths(fs, scope);
     showManualInstructions("codex", scope, paths.configPath, useColors);
     return;
-  } else if (tool === "claude-code") {
+  } else if (tool === "cursor") {
     if (!scope) {
       scope = "global";
     }
-    const paths = getClaudeCodeConfigPaths(fs, scope);
+    const paths = getCursorConfigPaths(fs, scope);
     configPath = paths.configPath;
     backupPath = paths.backupPath;
   } else {
@@ -2853,31 +3178,19 @@ Config file: ${highlight(configPath, useColors)}`);
 Next steps:
   1. Restart your AI assistant to activate the MCP server
   2. Test by asking your assistant about packages`, 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");
-  if (hasProject) {
-    console.log("  • search_project_docs - Search your project's docs");
-  }
+  showAvailableTools(hasProject, useColors);
 }
 var MCP_INIT_DESCRIPTION = `Configure PkgSeer's MCP server for your AI assistant.
 
 Guides you through:
   • Selecting your AI tool (Cursor IDE, Codex CLI, Claude Code)
-  • Choosing configuration location (project or global)
-  • Safely editing config files with automatic backup
+  • Choosing installation scope (user-level or project-level)
+  • Setting up via CLI commands or config file editing
 
-Project-level config (recommended):
-  • Uses your project token for authenticated features
-  • Enables search_project_docs (search your project's packages)
-  • Portable with your project`;
+User-level (recommended):
+  • Works across all your projects
+  • Use project_directory parameter for project-specific features
+  • Automatically updated when using npx`;
 function registerMcpInitCommand(mcpCommand) {
   mcpCommand.command("init").summary("Configure MCP server for AI assistants").description(MCP_INIT_DESCRIPTION).action(async () => {
     const deps = await createContainer();
@@ -2886,6 +3199,7 @@ function registerMcpInitCommand(mcpCommand) {
       fileSystemService: deps.fileSystemService,
       promptService: deps.promptService,
       configService: deps.configService,
+      shellService: deps.shellService,
       baseUrl: deps.baseUrl,
       hasProject
     });
@@ -3525,30 +3839,362 @@ function registerProjectInitCommand(program) {
   });
 }
 
-// src/commands/init.ts
-async function initAction(options, deps) {
-  const useColors = shouldUseColors2();
-  console.log("Welcome to PkgSeer!");
-  console.log(`───────────────────
-`);
-  console.log(`Set up PkgSeer for your project:
+// src/commands/skill-init.ts
+function generateSkillContent() {
+  return `---
+name: pkgseer
+version: ${version}
+description: >-
+  Search code and documentation across npm, PyPI, and Hex packages.
+  Find functions, classes, APIs, and usage examples. Also provides
+  quality scores, security vulnerabilities, dependencies, and comparisons.
+  Triggers on: "how does X work", "find examples of", "search for",
+  "is X secure", "compare X vs Y", package evaluation, dependency decisions,
+  "what package should I use for", API lookup, security audits.
+---
+
+# PkgSeer - Package Intelligence
+
+Search and analyze packages across npm, PyPI, and Hex. All commands support \`--json\`.
+
+## Search (Primary Use Case)
+
+\`\`\`bash
+# Search code and docs across packages
+pkgseer search "<query>" -P lodash,express    # npm packages
+pkgseer search "<query>" -P requests -r pypi  # PyPI packages
+pkgseer search "authentication" -P phoenix,plug -r hex
+
+# Search modes
+pkgseer search "<query>" -P <packages> --code  # Code only
+pkgseer search "<query>" -P <packages> --docs  # Docs only
+
+# Search project dependencies (requires pkgseer.yml)
+pkgseer docs search "<query>"
+\`\`\`
+
+## Package Analysis
+
+\`\`\`bash
+# Overview: metadata, versions, quickstart
+pkgseer pkg info <package> [-r npm|pypi|hex]
+
+# Quality score (0-100) with category breakdown
+pkgseer pkg quality <package> [-r registry] [-v version]
+
+# Security: CVEs, severity, upgrade paths
+pkgseer pkg vulns <package> [-r registry] [-v version]
+
+# Dependencies: direct, transitive, tree view
+pkgseer pkg deps <package> [-r registry] [-t] [-d depth]
+
+# Compare up to 10 packages
+pkgseer pkg compare lodash underscore ramda
+pkgseer pkg compare npm:axios pypi:httpx  # cross-registry
+\`\`\`
+
+## Documentation
+
+\`\`\`bash
+pkgseer docs list <package> [-r registry]  # List pages
+pkgseer docs get <package>/<page-id>       # Fetch content
+\`\`\`
+
+## Tips
+
+- Default registry: npm. Use \`-r pypi\` or \`-r hex\` for others
+- Use \`--json\` for structured output when parsing
+- Version defaults to latest; use \`-v\` for specific
+`;
+}
+function extractSkillVersion(content) {
+  const match = content.match(/^version:\s*["']?([^"'\n]+)["']?/m);
+  return match?.[1]?.trim() ?? null;
+}
+function getClaudeCodeSkillPaths(fs, scope) {
+  const baseDir = scope === "user" ? fs.joinPath(fs.getHomeDir(), ".claude", "skills", "pkgseer") : fs.joinPath(fs.getCwd(), ".claude", "skills", "pkgseer");
+  return {
+    skillDir: baseDir,
+    skillPath: fs.joinPath(baseDir, "SKILL.md")
+  };
+}
+function getCodexSkillPaths(fs, scope) {
+  const baseDir = scope === "user" ? fs.joinPath(fs.getHomeDir(), ".codex", "skills", "pkgseer") : fs.joinPath(fs.getCwd(), ".codex", "skills", "pkgseer");
+  return {
+    skillDir: baseDir,
+    skillPath: fs.joinPath(baseDir, "SKILL.md")
+  };
+}
+async function installSkill(fs, skillDir, skillPath) {
+  try {
+    const exists = await fs.exists(skillPath);
+    let updated = false;
+    if (exists) {
+      const existingContent = await fs.readFile(skillPath);
+      const existingVersion = extractSkillVersion(existingContent);
+      if (existingVersion === version) {
+        return {
+          success: true,
+          path: skillPath,
+          updated: false
+        };
+      }
+      updated = true;
+    }
+    await fs.ensureDir(skillDir);
+    const content = generateSkillContent();
+    await fs.writeFile(skillPath, content);
+    return {
+      success: true,
+      path: skillPath,
+      updated
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function skillInitAction(deps) {
+  const { fileSystemService: fs, promptService } = deps;
+  const useColors = shouldUseColors2();
+  console.log("Skill Setup");
+  console.log(`───────────
+`);
+  console.log(`Install PkgSeer as an agent skill for your AI assistant.
+`);
+  console.log(dim(`Skills provide Claude/Codex with package intelligence capabilities
+` + `through natural language - no MCP server required.
+`, useColors));
+  const tool = await promptService.select("Which AI tool would you like to configure?", [
+    {
+      value: "claude-code",
+      name: "Claude Code",
+      description: "Install skill for Claude Code CLI"
+    },
+    {
+      value: "codex",
+      name: "Codex CLI",
+      description: "Install skill for OpenAI Codex CLI"
+    },
+    {
+      value: "other",
+      name: "Other / Manual",
+      description: "Show SKILL.md content for manual installation"
+    }
+  ]);
+  if (tool === "other") {
+    showManualInstructions2(useColors);
+    return;
+  }
+  const scope = await promptService.select("Where should the skill be installed?", [
+    {
+      value: "user",
+      name: "User-level (recommended)",
+      description: "Available in all your projects"
+    },
+    {
+      value: "project",
+      name: "Project-level",
+      description: "Only available in this project"
+    }
+  ]);
+  const paths = tool === "claude-code" ? getClaudeCodeSkillPaths(fs, scope) : getCodexSkillPaths(fs, scope);
+  const exists = await fs.exists(paths.skillPath);
+  if (exists) {
+    const existingContent = await fs.readFile(paths.skillPath);
+    const existingVersion = extractSkillVersion(existingContent);
+    if (existingVersion === version) {
+      console.log(success(`
+PkgSeer skill already installed (v${version})`, useColors));
+      console.log(`Location: ${highlight(paths.skillPath, useColors)}`);
+      return;
+    }
+    console.log(`
+Existing skill found: v${existingVersion ?? "unknown"} → v${version}`);
+    const proceed = await promptService.confirm("Update to latest version?", true);
+    if (!proceed) {
+      console.log(dim(`
+Skip update.`, useColors));
+      return;
+    }
+  }
+  console.log(dim(`
+Installing skill...`, useColors));
+  const result = await installSkill(fs, paths.skillDir, paths.skillPath);
+  if (!result.success) {
+    console.log(error(`
+Failed to install skill: ${result.error}`, useColors));
+    showManualInstructions2(useColors);
+    return;
+  }
+  const toolName = tool === "claude-code" ? "Claude Code" : "Codex";
+  const action = result.updated ? "updated" : "installed";
+  console.log(success(`
+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"
+` + `  "Is lodash secure? Check for vulnerabilities"
+` + '  "Compare axios vs fetch vs got"', useColors));
+}
+function showManualInstructions2(useColors) {
+  console.log(`
+Manual Installation`);
+  console.log(`───────────────────
+`);
+  console.log(`Create a SKILL.md file in your skills directory:
+`);
+  console.log("Claude Code:");
+  console.log(`  User:    ${highlight("~/.claude/skills/pkgseer/SKILL.md", useColors)}`);
+  console.log(`  Project: ${highlight(".claude/skills/pkgseer/SKILL.md", useColors)}
+`);
+  console.log("Codex:");
+  console.log(`  User:    ${highlight("~/.codex/skills/pkgseer/SKILL.md", useColors)}`);
+  console.log(`  Project: ${highlight(".codex/skills/pkgseer/SKILL.md", useColors)}
+`);
+  console.log(`Content:
+`);
+  console.log("─".repeat(60));
+  console.log(generateSkillContent());
+  console.log("─".repeat(60));
+}
+async function skillUpdateAction(deps) {
+  const { fileSystemService: fs } = deps;
+  const useColors = shouldUseColors2();
+  console.log(`Checking for skill updates...
+`);
+  const locations = [
+    {
+      name: "Claude Code (user)",
+      ...getClaudeCodeSkillPaths(fs, "user")
+    },
+    {
+      name: "Claude Code (project)",
+      ...getClaudeCodeSkillPaths(fs, "project")
+    },
+    {
+      name: "Codex (user)",
+      ...getCodexSkillPaths(fs, "user")
+    },
+    {
+      name: "Codex (project)",
+      ...getCodexSkillPaths(fs, "project")
+    }
+  ];
+  let foundAny = false;
+  let updatedAny = false;
+  for (const loc of locations) {
+    const exists = await fs.exists(loc.skillPath);
+    if (!exists)
+      continue;
+    foundAny = true;
+    const content = await fs.readFile(loc.skillPath);
+    const existingVersion = extractSkillVersion(content);
+    if (existingVersion === version) {
+      console.log(`${loc.name}: ${highlight(`v${version}`, useColors)} (current)`);
+      continue;
+    }
+    const result = await installSkill(fs, loc.skillDir, loc.skillPath);
+    if (result.success) {
+      console.log(`${loc.name}: ${dim(`v${existingVersion ?? "unknown"}`, useColors)} → ${highlight(`v${version}`, useColors)}`);
+      updatedAny = true;
+    } else {
+      console.log(error(`${loc.name}: Failed to update - ${result.error}`, useColors));
+    }
+  }
+  if (!foundAny) {
+    console.log(dim("No installed skills found.", useColors));
+    console.log(dim(`Run 'pkgseer skill init' to install the skill.
+`, useColors));
+    return;
+  }
+  if (updatedAny) {
+    console.log(success(`
+Skills updated successfully!`, useColors));
+  } else {
+    console.log(dim(`
+All skills are up to date.`, useColors));
+  }
+}
+var SKILL_INIT_DESCRIPTION = `Install PkgSeer as an agent skill for AI assistants.
+
+Skills provide package intelligence through natural language:
+  • Search code and documentation across packages
+  • Check security vulnerabilities and quality scores
+  • Compare packages and analyze dependencies
+
+Supports Claude Code and Codex CLI with user or project scope.`;
+var SKILL_UPDATE_DESCRIPTION = `Update installed PkgSeer skills to the latest version.
+
+Checks all installed skill locations and updates any that are outdated.`;
+function registerSkillCommand(program) {
+  const skillCmd = program.command("skill").summary("Manage PkgSeer agent skill").description("Install and manage PkgSeer as an agent skill for AI assistants.");
+  skillCmd.command("init").summary("Install skill for AI assistants").description(SKILL_INIT_DESCRIPTION).action(async () => {
+    const deps = await createContainer();
+    await skillInitAction({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+  });
+  skillCmd.command("update").summary("Update installed skills").description(SKILL_UPDATE_DESCRIPTION).action(async () => {
+    const deps = await createContainer();
+    await skillUpdateAction({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+  });
+}
+
+// src/commands/init.ts
+async function initAction(options, deps) {
+  const useColors = shouldUseColors2();
+  console.log("Welcome to PkgSeer!");
+  console.log(`───────────────────
+`);
+  console.log(`Set up PkgSeer for your project:
 ` + `  1. Project configuration – track dependencies and monitor vulnerabilities
-` + `  2. MCP server – enable AI assistant integration
+` + `  2. AI integration – enable AI assistant capabilities
 `);
-  console.log(dim(`Or run separately: pkgseer project init, pkgseer mcp init
+  console.log(dim(`Or run separately: pkgseer project init, pkgseer skill init, pkgseer mcp init
 `, useColors));
   let setupProject = !options.skipProject;
-  let setupMcp = !options.skipMcp;
-  if (options.skipProject && options.skipMcp) {
+  let aiIntegration = "none";
+  if (options.skipProject && options.skipMcp && options.skipSkill) {
     showCliUsage(useColors);
     return;
   }
-  if (!options.skipProject && !options.skipMcp) {
-    const choice = await deps.promptService.select("What would you like to set up?", [
+  const promptForAiIntegration = async () => {
+    return deps.promptService.select("Which AI integration would you like?", [
+      {
+        value: "skill",
+        name: "Skill (recommended for Claude Code / Codex)",
+        description: "Lightweight file-based integration, auto-triggers on package queries"
+      },
+      {
+        value: "mcp",
+        name: "MCP server (for Cursor / advanced use)",
+        description: "Structured tool integration via Model Context Protocol"
+      }
+    ]);
+  };
+  if (options.skipMcp && !options.skipSkill) {
+    aiIntegration = "skill";
+  } else if (!options.skipMcp && options.skipSkill) {
+    aiIntegration = "mcp";
+  } else if (options.skipMcp && options.skipSkill) {
+    aiIntegration = "none";
+  }
+  if (!options.skipProject && !options.skipMcp && !options.skipSkill) {
+    const setupChoice = await deps.promptService.select("What would you like to set up?", [
       {
-        value: "both",
-        name: "Both project and MCP server (recommended)",
-        description: "Full setup: dependency tracking + AI assistant integration"
+        value: "full",
+        name: "Project + AI integration (recommended)",
+        description: "Full setup: dependency tracking + AI assistant capabilities"
       },
       {
         value: "project",
@@ -3556,9 +4202,9 @@ async function initAction(options, deps) {
         description: "Track dependencies and monitor for vulnerabilities"
       },
       {
-        value: "mcp",
-        name: "MCP server only",
-        description: "Enable AI assistant integration"
+        value: "ai",
+        name: "AI integration only",
+        description: "Enable AI assistant capabilities"
       },
       {
         value: "cli",
@@ -3566,15 +4212,21 @@ async function initAction(options, deps) {
         description: "Use PkgSeer as a command-line tool"
       }
     ]);
-    if (choice === "cli") {
+    if (setupChoice === "cli") {
       showCliUsage(useColors);
       return;
     }
-    setupProject = choice === "both" || choice === "project";
-    setupMcp = choice === "both" || choice === "mcp";
+    setupProject = setupChoice === "full" || setupChoice === "project";
+    const setupAi = setupChoice === "full" || setupChoice === "ai";
+    if (setupAi) {
+      aiIntegration = await promptForAiIntegration();
+    }
+  } else if (!options.skipMcp && !options.skipSkill) {
+    aiIntegration = await promptForAiIntegration();
   }
   const projectInit = deps.projectInitAction ?? projectInitAction;
   const mcpInit = deps.mcpInitAction ?? mcpInitAction;
+  const skillInit = deps.skillInitAction ?? skillInitAction;
   if (setupProject) {
     const existingConfig = await deps.configService.loadProjectConfig();
     if (existingConfig?.config.project) {
@@ -3606,7 +4258,21 @@ ${highlight("✓", useColors)} Project setup complete!
       }
     }
   }
-  if (setupMcp) {
+  if (aiIntegration === "skill") {
+    console.log(`
+` + "=".repeat(50));
+    console.log("Skill Setup");
+    console.log("=".repeat(50) + `
+`);
+    await skillInit({
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+    console.log(`
+${highlight("✓", useColors)} Skill setup complete!
+`);
+  } else if (aiIntegration === "mcp") {
     const currentConfig = await deps.configService.loadProjectConfig();
     const hasProjectNow = currentConfig?.config.project !== undefined;
     console.log(`
@@ -3618,6 +4284,7 @@ ${highlight("✓", useColors)} Project setup complete!
       fileSystemService: deps.fileSystemService,
       promptService: deps.promptService,
       configService: deps.configService,
+      shellService: deps.shellService,
       baseUrl: deps.baseUrl,
       hasProject: hasProjectNow
     });
@@ -3636,15 +4303,18 @@ ${highlight("✓", useColors)} MCP setup complete!
       console.log(dim(`  View at: ${deps.baseUrl}/projects/${finalConfig.config.project}`, useColors));
     }
   }
-  if (setupMcp) {
-    console.log("MCP Server: Configured");
+  if (aiIntegration === "skill") {
+    console.log("AI Integration: Skill installed");
+    console.log(dim("  The skill is available immediately.", useColors));
+  } else if (aiIntegration === "mcp") {
+    console.log("AI Integration: MCP server configured");
     console.log(dim("  Restart your AI assistant to activate the MCP server.", useColors));
   }
   console.log(dim(`
 Next steps:
 ` + `  • Use CLI commands: pkgseer pkg info <package>
-` + `  • Search docs: pkgseer docs search <query>
-` + "  • Quick reference: pkgseer quickstart", useColors));
+` + `  • Search packages: pkgseer search <query> -P <packages>
+` + "  • Search project docs: pkgseer docs search <query>", useColors));
 }
 function showCliUsage(useColors) {
   console.log("Using PkgSeer via CLI");
@@ -3669,13 +4339,13 @@ function showCliUsage(useColors) {
 ` + "Tip: Run 'pkgseer quickstart' for a quick reference guide.", useColors));
 }
 function registerInitCommand(program) {
-  program.command("init").summary("Set up project and MCP server").description(`Set up PkgSeer for your project.
+  program.command("init").summary("Set up project and AI integration").description(`Set up PkgSeer for your project.
 
 Guides you through:
   • Project configuration – track dependencies, monitor vulnerabilities
-  • MCP server – enable AI assistant integration
+  • AI integration – skill or MCP server for AI assistants
 
-Run separately: pkgseer project init, pkgseer mcp init`).option("--skip-project", "Skip project setup").option("--skip-mcp", "Skip MCP setup").action(async (options) => {
+Run separately: pkgseer project init, pkgseer skill init, pkgseer mcp init`).option("--skip-project", "Skip project setup").option("--skip-mcp", "Skip MCP setup (use skill instead)").option("--skip-skill", "Skip skill setup (use MCP instead)").action(async (options) => {
     const deps = await createContainer();
     await initAction(options, deps);
   });
@@ -3912,7 +4582,7 @@ var argsSchema = {
 function createComparePackagesTool(pkgseerService) {
   return {
     name: "compare_packages",
-    description: 'Compares 2-10 packages across metadata, quality, and security. Example: [{"registry":"npm","name":"react","version":"18.2.0"},{"registry":"pypi","name":"requests"}].',
+    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). " + 'Format: [{"registry":"npm","name":"lodash"},{"registry":"npm","name":"underscore"}]',
     schema: argsSchema,
     handler: async ({ packages }, _extra) => {
       return withErrorHandling("compare packages", async () => {
@@ -3933,16 +4603,47 @@ function createComparePackagesTool(pkgseerService) {
     }
   };
 }
-// src/tools/fetch-package-doc.ts
+// src/tools/fetch-code-context.ts
 import { z as z4 } from "zod";
 var argsSchema2 = {
-  page_id: z4.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
+  repo_url: z4.string().min(1).describe("Repository URL (GitHub). Example: https://github.com/expressjs/express"),
+  git_ref: z4.string().min(1).describe("Git reference (tag, commit, or branch). Example: v4.18.2"),
+  file_path: z4.string().min(1).describe("Path to file in repository. Example: src/router/index.js"),
+  start_line: z4.number().int().positive().optional().describe("Starting line (1-indexed). If omitted, starts from line 1."),
+  end_line: z4.number().int().positive().optional().describe("Ending line. If omitted, returns to end of file.")
+};
+function createFetchCodeContextTool(pkgseerService) {
+  return {
+    name: "fetch_code_context",
+    description: "Fetch code content from a repository. Use this to expand code search results and see " + "more context around a match. Returns full file by default, or a specific line range. " + "Requires repo_url, git_ref (tag/commit/branch), and file_path from search results.",
+    schema: argsSchema2,
+    handler: async ({ repo_url, git_ref, file_path, start_line, end_line }, _extra) => {
+      return withErrorHandling("fetch code context", async () => {
+        const result = await pkgseerService.fetchCodeContext(repo_url, git_ref, file_path, {
+          startLine: start_line,
+          endLine: end_line
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.fetchCodeContext) {
+          return errorResult(`Code not found: ${file_path} at ${git_ref} in ${repo_url}. ` + "Check that the repository, file path, and git ref are correct.");
+        }
+        return textResult(JSON.stringify(result.data.fetchCodeContext, null, 2));
+      });
+    }
+  };
+}
+// src/tools/fetch-package-doc.ts
+import { z as z5 } from "zod";
+var argsSchema3 = {
+  page_id: z5.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
 };
 function createFetchPackageDocTool(pkgseerService) {
   return {
     name: "fetch_package_doc",
-    description: "Fetches the full content of a documentation page by globally unique page ID (from list_package_docs). Returns full metadata (title, content, format, breadcrumbs, source, base URL, last updated).",
-    schema: argsSchema2,
+    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: argsSchema3,
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
         const result = await pkgseerService.getDocPage(page_id);
@@ -3958,7 +4659,7 @@ function createFetchPackageDocTool(pkgseerService) {
   };
 }
 // src/tools/list-package-docs.ts
-var argsSchema3 = {
+var argsSchema4 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to list documentation for"),
   version: schemas.version
@@ -3966,8 +4667,8 @@ var argsSchema3 = {
 function createListPackageDocsTool(pkgseerService) {
   return {
     name: "list_package_docs",
-    description: "Lists documentation pages for a package version. Returns page titles, globally unique IDs, and metadata. Use this to discover available documentation before fetching specific pages.",
-    schema: argsSchema3,
+    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.",
+    schema: argsSchema4,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("list package documentation", async () => {
         const result = await pkgseerService.listPackageDocs(toGraphQLRegistry2(registry), package_name, version2);
@@ -3983,13 +4684,13 @@ function createListPackageDocsTool(pkgseerService) {
   };
 }
 // src/tools/package-dependencies.ts
-import { z as z5 } from "zod";
-var argsSchema4 = {
+import { z as z6 } from "zod";
+var argsSchema5 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve dependencies for"),
   version: schemas.version,
-  include_transitive: z5.boolean().optional().describe("Whether to include transitive dependency DAG"),
-  max_depth: z5.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+  include_transitive: z6.boolean().optional().describe("Whether to include transitive dependency DAG"),
+  max_depth: z6.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
 function decodeDag(rawDag) {
   if (!rawDag || typeof rawDag !== "object")
@@ -4066,8 +4767,8 @@ function buildEdgeDepths(decodedDag, rootId) {
 function createPackageDependenciesTool(pkgseerService) {
   return {
     name: "package_dependencies",
-    description: "Retrieves direct and transitive dependencies for a package version. Options: include_transitive (bool) and max_depth (1-10). Transitive output includes a DAG (`n/e/v` keys) decoded into readable nodes/edges with depth and counts; raw DAG is preserved alongside decoded form.",
-    schema: argsSchema4,
+    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: argsSchema5,
     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);
@@ -4105,7 +4806,7 @@ function createPackageDependenciesTool(pkgseerService) {
   };
 }
 // src/tools/package-quality.ts
-var argsSchema5 = {
+var argsSchema6 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to analyze"),
   version: schemas.version
@@ -4113,8 +4814,8 @@ var argsSchema5 = {
 function createPackageQualityTool(pkgseerService) {
   return {
     name: "package_quality",
-    description: "Retrieves quality score and rule-level breakdown for a package",
-    schema: argsSchema5,
+    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: argsSchema6,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package quality", async () => {
         const result = await pkgseerService.getPackageQuality(toGraphQLRegistry2(registry), package_name, version2);
@@ -4130,15 +4831,15 @@ function createPackageQualityTool(pkgseerService) {
   };
 }
 // src/tools/package-summary.ts
-var argsSchema6 = {
+var argsSchema7 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to retrieve summary for")
 };
 function createPackageSummaryTool(pkgseerService) {
   return {
     name: "package_summary",
-    description: "Retrieves comprehensive package summary including metadata, versions, security advisories, and quickstart information",
-    schema: argsSchema6,
+    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: argsSchema7,
     handler: async ({ registry, package_name }, _extra) => {
       return withErrorHandling("fetch package summary", async () => {
         const result = await pkgseerService.getPackageSummary(toGraphQLRegistry2(registry), package_name);
@@ -4154,7 +4855,7 @@ function createPackageSummaryTool(pkgseerService) {
   };
 }
 // src/tools/package-vulnerabilities.ts
-var argsSchema7 = {
+var argsSchema8 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
   version: schemas.version
@@ -4162,8 +4863,8 @@ var argsSchema7 = {
 function createPackageVulnerabilitiesTool(pkgseerService) {
   return {
     name: "package_vulnerabilities",
-    description: "Retrieves vulnerability details for a package, including affected version ranges and upgrade guidance",
-    schema: argsSchema7,
+    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: argsSchema8,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("fetch package vulnerabilities", async () => {
         const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry2(registry), package_name, version2);
@@ -4178,79 +4879,126 @@ function createPackageVulnerabilitiesTool(pkgseerService) {
     }
   };
 }
-// src/tools/search-package-docs.ts
-import { z as z6 } from "zod";
-var argsSchema8 = {
+// src/tools/search.ts
+import { z as z7 } from "zod";
+var packageInputSchema2 = z7.object({
   registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to search documentation for"),
-  terms: z6.array(z6.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
-  match_mode: z6.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
-  include_snippets: z6.boolean().optional().describe("Include content excerpts around matches"),
-  limit: z6.number().int().min(1).max(100).optional().describe("Maximum number of results to return"),
-  version: schemas.version
+  name: z7.string().min(1).describe("Package name"),
+  version: z7.string().optional().describe("Specific version (defaults to latest)")
+});
+var argsSchema9 = {
+  packages: z7.array(packageInputSchema2).min(1).max(20).describe("Packages to search (1-20). Each package needs registry and name."),
+  query: z7.string().min(1).describe("Search query - natural language or keywords"),
+  mode: z7.enum(["all", "code", "docs"]).optional().describe('Search mode: "all" (default), "code" only, or "docs" only'),
+  limit: z7.number().int().min(1).max(100).optional().describe("Maximum results (default: 20)")
 };
-function createSearchPackageDocsTool(pkgseerService) {
+function toSearchMode2(mode) {
+  if (!mode)
+    return;
+  const map = {
+    all: "ALL",
+    code: "CODE",
+    docs: "DOCS"
+  };
+  return map[mode.toLowerCase()];
+}
+function formatIndexingWarnings2(indexingStatus) {
+  if (!indexingStatus || indexingStatus.length === 0)
+    return null;
+  const warnings = [];
+  for (const status of indexingStatus) {
+    if (!status)
+      continue;
+    const pkg = `${status.packageName}@${status.version ?? "latest"} (${status.registry?.toLowerCase() ?? "unknown"})`;
+    if (status.codeStatus && status.codeStatus !== "INDEXED") {
+      warnings.push(`  - ${pkg}: code ${status.codeStatus.toLowerCase()}`);
+    }
+    if (status.docsStatus && status.docsStatus !== "INDEXED") {
+      warnings.push(`  - ${pkg}: docs ${status.docsStatus.toLowerCase()}`);
+    }
+  }
+  if (warnings.length === 0)
+    return null;
+  return `
+Note: Some packages are not fully indexed:
+` + warnings.join(`
+`) + `
+Results may be incomplete. Retry later for more complete results.`;
+}
+function createSearchTool(pkgseerService) {
   return {
-    name: "search_package_docs",
-    description: "Searches package documentation using search terms and match modes (any/all). Returns ranked results with match context. Defaults to include_snippets=true.",
-    schema: argsSchema8,
-    handler: async ({
-      registry,
-      package_name,
-      terms,
-      match_mode,
-      include_snippets,
-      limit,
-      version: version2
-    }, _extra) => {
-      return withErrorHandling("search package documentation", async () => {
-        const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
-        if (normalizedTerms.length === 0) {
-          return errorResult("Search terms are required to run documentation search.");
+    name: "search",
+    description: "Search code and documentation across packages. Returns functions, classes, and documentation pages " + "matching your query. Use mode='code' for code only, mode='docs' for documentation only, or " + "mode='all' (default) for both. Provide 1-20 packages to search. Results include relevance scores " + "and snippets showing matches.",
+    schema: argsSchema9,
+    handler: async ({ packages, query, mode, limit }, _extra) => {
+      return withErrorHandling("search packages", async () => {
+        const normalizedQuery = query.trim();
+        if (normalizedQuery.length === 0) {
+          return errorResult("Search query is required.");
         }
-        const matchMode = match_mode === "all" || match_mode === "and" ? "AND" : match_mode === "any" || match_mode === "or" ? "OR" : undefined;
-        const includeSnippets = include_snippets ?? true;
-        const result = await pkgseerService.searchPackageDocs(toGraphQLRegistry2(registry), package_name, {
-          keywords: normalizedTerms,
-          matchMode,
-          includeSnippets,
-          limit,
-          version: version2
+        const graphqlPackages = packages.map((pkg) => ({
+          registry: toGraphQLRegistry2(pkg.registry),
+          name: pkg.name,
+          version: pkg.version
+        }));
+        const result = await pkgseerService.combinedSearch(graphqlPackages, normalizedQuery, {
+          mode: toSearchMode2(mode),
+          limit
         });
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.searchPackageDocs) {
-          return errorResult(`No documentation found for ${package_name} in ${registry}`);
+        if (!result.data.combinedSearch) {
+          return errorResult("No search results returned. Check package names and registries.");
         }
-        if ((result.data.searchPackageDocs.entries ?? []).length === 0 && normalizedTerms.length > 0) {
-          return errorResult(`No documentation matched: ${normalizedTerms.join(", ")}. ` + "Try fewer or broader terms, or reduce match constraints.");
+        const searchResult = result.data.combinedSearch;
+        const entries = searchResult.entries ?? [];
+        if (entries.length === 0) {
+          return errorResult(`No results found for "${normalizedQuery}". ` + "Try broader terms or different packages.");
+        }
+        let response = JSON.stringify(searchResult, null, 2);
+        const indexingWarning = formatIndexingWarnings2(searchResult.indexingStatus);
+        if (indexingWarning) {
+          response += indexingWarning;
         }
-        return textResult(JSON.stringify(result.data.searchPackageDocs, null, 2));
+        return textResult(response);
       });
     }
   };
 }
 // src/tools/search-project-docs.ts
-import { z as z7 } from "zod";
-var argsSchema9 = {
-  project: z7.string().optional().describe("Project name to search. Optional if configured in pkgseer.yml; only needed to search a different project."),
-  terms: z7.array(z7.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
-  match_mode: z7.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
-  include_snippets: z7.boolean().optional().describe("Include content excerpts around matches"),
-  limit: z7.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
+import { z as z8 } from "zod";
+var argsSchema10 = {
+  project_directory: z8.string().optional().describe("Directory to search for pkgseer.yml configuration. " + "Use this to specify which project's context to use when the MCP server " + "is installed at user level. Defaults to MCP server's working directory."),
+  project: z8.string().optional().describe("Project name to search. Overrides value from pkgseer.yml if provided."),
+  terms: z8.array(z8.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
+  match_mode: z8.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
+  include_snippets: z8.boolean().optional().describe("Include content excerpts around matches"),
+  limit: z8.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
 function createSearchProjectDocsTool(deps) {
-  const { pkgseerService, config } = 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. Uses project from pkgseer.yml config by default.",
-    schema: argsSchema9,
-    handler: async ({ project, terms, match_mode, include_snippets, limit }, _extra) => {
+    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.",
+    schema: argsSchema10,
+    handler: async ({
+      project_directory,
+      project,
+      terms,
+      match_mode,
+      include_snippets,
+      limit
+    }, _extra) => {
       return withErrorHandling("search project documentation", async () => {
-        const resolvedProject = project ?? config.project;
+        const targetDir = project_directory ?? defaultProjectDir;
+        const projectConfig = await configService.loadProjectConfigFrom(targetDir);
+        const resolvedProject = project ?? projectConfig?.config.project;
         if (!resolvedProject) {
-          return errorResult("No project provided and none configured in pkgseer.yml. " + "Either pass project parameter or add project to your config.");
+          return errorResult(`No project specified and no pkgseer.yml found. To fix:
+` + `  1. Pass project_directory: '/path/to/project' (folder containing pkgseer.yml)
+` + `  2. Pass project: 'project-name' directly if you know the project name
+` + "  3. Run 'pkgseer project init' to create pkgseer.yml in your project");
         }
         const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
         if (normalizedTerms.length === 0) {
@@ -4287,8 +5035,13 @@ var TOOL_FACTORIES = {
   compare_packages: ({ pkgseerService }) => createComparePackagesTool(pkgseerService),
   list_package_docs: ({ pkgseerService }) => createListPackageDocsTool(pkgseerService),
   fetch_package_doc: ({ pkgseerService }) => createFetchPackageDocTool(pkgseerService),
-  search_package_docs: ({ pkgseerService }) => createSearchPackageDocsTool(pkgseerService),
-  search_project_docs: ({ pkgseerService, config }) => createSearchProjectDocsTool({ pkgseerService, config })
+  search: ({ pkgseerService }) => createSearchTool(pkgseerService),
+  fetch_code_context: ({ pkgseerService }) => createFetchCodeContextTool(pkgseerService),
+  search_project_docs: ({ pkgseerService, configService, defaultProjectDir }) => createSearchProjectDocsTool({
+    pkgseerService,
+    configService,
+    defaultProjectDir
+  })
 };
 var PUBLIC_READ_TOOLS = [
   "package_summary",
@@ -4298,21 +5051,29 @@ var PUBLIC_READ_TOOLS = [
   "compare_packages",
   "list_package_docs",
   "fetch_package_doc",
-  "search_package_docs"
+  "search",
+  "fetch_code_context"
 ];
 var PROJECT_READ_TOOLS = ["search_project_docs"];
 var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
 function createMcpServer(deps) {
-  const { pkgseerService, config } = deps;
+  const { pkgseerService, configService, config, fileSystemService } = deps;
   const server = new McpServer({
     name: "pkgseer",
     version: "0.1.0"
   });
+  const defaultProjectDir = fileSystemService.getCwd();
   const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
   const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
+  const factoryDeps = {
+    pkgseerService,
+    configService,
+    config,
+    defaultProjectDir
+  };
   for (const toolName of toolsToRegister) {
     const factory = TOOL_FACTORIES[toolName];
-    const tool = factory({ pkgseerService, config });
+    const tool = factory(factoryDeps);
     server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.handler);
   }
   return server;
@@ -5259,103 +6020,13 @@ function registerProjectUploadCommand(program) {
     });
   });
 }
-// src/commands/quickstart.ts
-var QUICKSTART_TEXT = `# PkgSeer CLI - Quick Reference for AI Agents
-
-PkgSeer provides package intelligence for npm, PyPI, and Hex registries.
-
-## Package Commands (pkgseer pkg)
-
-### Get package info
-\`pkgseer pkg info <package> [-r npm|pypi|hex] [--json]\`
-Returns: metadata, versions, security advisories, quickstart
-
-### Check quality score
-\`pkgseer pkg quality <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: overall score, category breakdown, rule details
-
-### List dependencies
-\`pkgseer pkg deps <package> [-r registry] [-v pkg-version] [-t] [-d depth] [--json]\`
-Returns: direct deps, transitive count, dependency tree (with -t)
-
-### Check vulnerabilities
-\`pkgseer pkg vulns <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: CVEs, severity, affected versions, upgrade guidance
-
-### Compare packages
-\`pkgseer pkg compare <pkg1> <pkg2> [...] [--json]\`
-Format: [registry:]name[@version] (e.g., npm:lodash, pypi:requests@2.31.0)
-Returns: side-by-side quality, downloads, vulnerabilities
-
-## Documentation Commands (pkgseer docs)
-
-### List doc pages
-\`pkgseer docs list <package> [-r registry] [-v pkg-version] [--json]\`
-Returns: page titles, IDs (slugs), word counts
-
-### Get doc page
-\`pkgseer docs get <package>/<page-id> [<package>/<page-id> ...] [-r registry] [-v pkg-version] [--json]\`
-Returns: full page content (markdown), breadcrumbs, source URL
-Supports multiple pages: \`pkgseer docs get express/readme express/api\`
-
-### Search docs
-\`pkgseer docs search "<query>" [-p package] [-r registry] [--json]\`
-\`pkgseer docs search --keywords term1,term2 [-s] [-l limit]\`
-Default: searches project docs (if project configured)
-With -p: searches specific package docs
-Returns: ranked results with relevance scores
-
-## Tips for AI Agents
-
-1. Use \`--json\` for structured data parsing
-2. Default registry is npm; use \`-r pypi\` or \`-r hex\` for others
-3. Version defaults to latest; use \`-v <version>\` for specific version
-4. For docs search, configure project in pkgseer.yml for project-wide search
-5. Compare up to 10 packages at once with \`pkg compare\`
-
-## MCP Server
-
-For Model Context Protocol integration:
-\`pkgseer mcp\`
-
-Add to MCP config:
-{
-  "pkgseer": {
-    "command": "pkgseer",
-    "args": ["mcp"]
-  }
-}
-`;
-function quickstartAction(options) {
-  if (options.json) {
-    console.log(JSON.stringify({
-      version,
-      quickstart: QUICKSTART_TEXT
-    }));
-  } else {
-    console.log(QUICKSTART_TEXT);
-  }
-}
-var QUICKSTART_DESCRIPTION = `Show quick reference for AI agents.
-
-Displays a concise guide to pkgseer CLI commands optimized
-for LLM agents. Includes command syntax, options, and tips
-for effective usage.
-
-Use --json for structured output.`;
-function registerQuickstartCommand(program) {
-  program.command("quickstart").summary("Show quick reference for AI agents").description(QUICKSTART_DESCRIPTION).option("--json", "Output as JSON").action((options) => {
-    quickstartAction(options);
-  });
-}
-
 // src/cli.ts
 var program = new Command;
 program.name("pkgseer").description("Package intelligence for your AI assistant").version(version).addHelpText("after", `
 Getting started:
-  pkgseer init         Interactive setup wizard (project + MCP)
+  pkgseer init         Interactive setup wizard (project + AI)
   pkgseer login        Authenticate with your account
-  pkgseer quickstart   Quick reference for AI agents
+  pkgseer skill init   Install AI agent skill
 
 Package commands:
   pkgseer pkg info <package>      Get package summary
@@ -5372,9 +6043,9 @@ Documentation commands:
 Learn more at https://pkgseer.dev`);
 registerInitCommand(program);
 registerMcpCommand(program);
+registerSkillCommand(program);
 registerLoginCommand(program);
 registerLogoutCommand(program);
-registerQuickstartCommand(program);
 var auth = program.command("auth").description("View and manage authentication");
 registerAuthStatusCommand(auth);
 var config = program.command("config").description("View and manage configuration");