@pkgseer/cli 0.1.0-alpha.3 → 0.1.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-awxns4wd.js";
+} from "./shared/chunk-3ne7e7xh.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -12,6 +12,233 @@ import { GraphQLClient } from "graphql-request";
 // src/generated/graphql.ts
 import { print } from "graphql";
 import gql from "graphql-tag";
+var CliPackageInfoDocument = gql`
+    query CliPackageInfo($registry: Registry!, $name: String!) {
+  packageSummary(registry: $registry, name: $name) {
+    package {
+      name
+      registry
+      description
+      latestVersion
+      license
+      homepage
+      repositoryUrl
+    }
+    security {
+      vulnerabilityCount
+    }
+    quickstart {
+      installCommand
+    }
+  }
+}
+    `;
+var CliPackageVulnsDocument = gql`
+    query CliPackageVulns($registry: Registry!, $name: String!, $version: String) {
+  packageVulnerabilities(registry: $registry, name: $name, version: $version) {
+    package {
+      name
+      version
+    }
+    security {
+      vulnerabilityCount
+      vulnerabilities {
+        osvId
+        summary
+        severityScore
+        fixedInVersions
+      }
+    }
+  }
+}
+    `;
+var CliPackageQualityDocument = gql`
+    query CliPackageQuality($registry: Registry!, $name: String!, $version: String) {
+  packageQuality(registry: $registry, name: $name, version: $version) {
+    package {
+      name
+      version
+    }
+    quality {
+      overallScore
+      grade
+      categories {
+        category
+        score
+      }
+    }
+  }
+}
+    `;
+var CliPackageDepsDocument = gql`
+    query CliPackageDeps($registry: Registry!, $name: String!, $version: String, $includeTransitive: Boolean) {
+  packageDependencies(
+    registry: $registry
+    name: $name
+    version: $version
+    includeTransitive: $includeTransitive
+  ) {
+    package {
+      name
+      version
+    }
+    dependencies {
+      summary {
+        directCount
+        uniquePackagesCount
+      }
+      direct {
+        name
+        versionConstraint
+        type
+      }
+    }
+  }
+}
+    `;
+var CliComparePackagesDocument = gql`
+    query CliComparePackages($packages: [PackageComparisonInput!]!) {
+  comparePackages(packages: $packages) {
+    packages {
+      packageName
+      version
+      license
+      downloadsLastMonth
+      vulnerabilityCount
+      quality {
+        score
+      }
+    }
+  }
+}
+    `;
+var CliDocsSearchDocument = gql`
+    query CliDocsSearch($registry: Registry!, $packageName: String!, $keywords: [String!], $query: String, $matchMode: MatchMode, $limit: Int, $version: String, $contextLinesBefore: Int, $contextLinesAfter: Int, $maxMatches: Int) {
+  searchPackageDocs(
+    registry: $registry
+    packageName: $packageName
+    keywords: $keywords
+    query: $query
+    matchMode: $matchMode
+    limit: $limit
+    version: $version
+  ) {
+    registry
+    packageName
+    version
+    entries {
+      slug
+      title
+      matchCount
+      matchedKeywords
+      matches(
+        contextLinesBefore: $contextLinesBefore
+        contextLinesAfter: $contextLinesAfter
+        maxMatches: $maxMatches
+      ) {
+        context {
+          before
+          matchedLines {
+            content
+            highlights {
+              term
+              start
+              end
+            }
+          }
+          after
+        }
+      }
+    }
+  }
+}
+    `;
+var CliProjectDocsSearchDocument = gql`
+    query CliProjectDocsSearch($project: String!, $keywords: [String!], $query: String, $matchMode: MatchMode, $limit: Int, $contextLinesBefore: Int, $contextLinesAfter: Int, $maxMatches: Int) {
+  searchProjectDocs(
+    project: $project
+    keywords: $keywords
+    query: $query
+    matchMode: $matchMode
+    limit: $limit
+  ) {
+    entries {
+      slug
+      title
+      packageName
+      registry
+      version
+      matchCount
+      matchedKeywords
+      matches(
+        contextLinesBefore: $contextLinesBefore
+        contextLinesAfter: $contextLinesAfter
+        maxMatches: $maxMatches
+      ) {
+        context {
+          before
+          matchedLines {
+            content
+            highlights {
+              term
+              start
+              end
+            }
+          }
+          after
+        }
+      }
+    }
+  }
+}
+    `;
+var CliDocsListDocument = gql`
+    query CliDocsList($registry: Registry!, $packageName: String!, $version: String) {
+  listPackageDocs(
+    registry: $registry
+    packageName: $packageName
+    version: $version
+  ) {
+    packageName
+    version
+    pages {
+      slug
+      title
+      words
+    }
+  }
+}
+    `;
+var CliDocsGetDocument = gql`
+    query CliDocsGet($registry: Registry!, $packageName: String!, $pageId: String!, $version: String) {
+  fetchPackageDoc(
+    registry: $registry
+    packageName: $packageName
+    pageId: $pageId
+    version: $version
+  ) {
+    page {
+      title
+      content
+      breadcrumbs
+    }
+  }
+}
+    `;
+var CreateProjectDocument = gql`
+    mutation CreateProject($input: CreateProjectInput!) {
+  createProject(input: $input) {
+    project {
+      name
+      defaultBranch
+    }
+    errors {
+      field
+      message
+    }
+  }
+}
+    `;
 var PackageSummaryDocument = gql`
     query PackageSummary($registry: Registry!, $name: String!) {
   packageSummary(registry: $registry, name: $name) {
@@ -182,14 +409,179 @@ var ComparePackagesDocument = gql`
   }
 }
     `;
+var ListPackageDocsDocument = gql`
+    query ListPackageDocs($registry: Registry!, $packageName: String!, $version: String) {
+  listPackageDocs(
+    registry: $registry
+    packageName: $packageName
+    version: $version
+  ) {
+    schemaVersion
+    registry
+    packageName
+    version
+    stale
+    pages {
+      id
+      title
+      slug
+      order
+      linkName
+      words
+      lastUpdatedAt
+      sourceUrl
+    }
+    metadata
+  }
+}
+    `;
+var FetchPackageDocDocument = gql`
+    query FetchPackageDoc($registry: Registry!, $packageName: String!, $pageId: String!, $version: String) {
+  fetchPackageDoc(
+    registry: $registry
+    packageName: $packageName
+    pageId: $pageId
+    version: $version
+  ) {
+    schemaVersion
+    registry
+    packageName
+    version
+    page {
+      id
+      title
+      content
+      contentFormat
+      breadcrumbs
+      linkName
+      linkTargets
+      lastUpdatedAt
+      source {
+        url
+        label
+      }
+      baseUrl
+    }
+  }
+}
+    `;
+var SearchPackageDocsDocument = gql`
+    query SearchPackageDocs($registry: Registry!, $packageName: String!, $keywords: [String!], $query: String, $includeSnippets: Boolean, $limit: Int, $version: String) {
+  searchPackageDocs(
+    registry: $registry
+    packageName: $packageName
+    keywords: $keywords
+    query: $query
+    includeSnippets: $includeSnippets
+    limit: $limit
+    version: $version
+  ) {
+    schemaVersion
+    registry
+    packageName
+    version
+    query
+    entries {
+      id
+      title
+      slug
+      order
+      linkName
+      words
+      lastUpdatedAt
+      sourceUrl
+      matchCount
+      titleHit
+      score
+      matchedKeywords
+      snippet
+    }
+    metadata
+  }
+}
+    `;
+var SearchProjectDocsDocument = gql`
+    query SearchProjectDocs($project: String!, $keywords: [String!], $query: String, $includeSnippets: Boolean, $limit: Int) {
+  searchProjectDocs(
+    project: $project
+    keywords: $keywords
+    query: $query
+    includeSnippets: $includeSnippets
+    limit: $limit
+  ) {
+    schemaVersion
+    project
+    query
+    entries {
+      id
+      title
+      slug
+      registry
+      packageName
+      version
+      words
+      matchCount
+      titleHit
+      score
+      matchedKeywords
+      snippet
+    }
+    metadata
+  }
+}
+    `;
 var defaultWrapper = (action, _operationName, _operationType, _variables) => action();
+var CliPackageInfoDocumentString = print(CliPackageInfoDocument);
+var CliPackageVulnsDocumentString = print(CliPackageVulnsDocument);
+var CliPackageQualityDocumentString = print(CliPackageQualityDocument);
+var CliPackageDepsDocumentString = print(CliPackageDepsDocument);
+var CliComparePackagesDocumentString = print(CliComparePackagesDocument);
+var CliDocsSearchDocumentString = print(CliDocsSearchDocument);
+var CliProjectDocsSearchDocumentString = print(CliProjectDocsSearchDocument);
+var CliDocsListDocumentString = print(CliDocsListDocument);
+var CliDocsGetDocumentString = print(CliDocsGetDocument);
+var CreateProjectDocumentString = print(CreateProjectDocument);
 var PackageSummaryDocumentString = print(PackageSummaryDocument);
 var PackageVulnerabilitiesDocumentString = print(PackageVulnerabilitiesDocument);
 var PackageDependenciesDocumentString = print(PackageDependenciesDocument);
 var PackageQualityDocumentString = print(PackageQualityDocument);
 var ComparePackagesDocumentString = print(ComparePackagesDocument);
+var ListPackageDocsDocumentString = print(ListPackageDocsDocument);
+var FetchPackageDocDocumentString = print(FetchPackageDocDocument);
+var SearchPackageDocsDocumentString = print(SearchPackageDocsDocument);
+var SearchProjectDocsDocumentString = print(SearchProjectDocsDocument);
 function getSdk(client, withWrapper = defaultWrapper) {
   return {
+    CliPackageInfo(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliPackageInfoDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliPackageInfo", "query", variables);
+    },
+    CliPackageVulns(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliPackageVulnsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliPackageVulns", "query", variables);
+    },
+    CliPackageQuality(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliPackageQualityDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliPackageQuality", "query", variables);
+    },
+    CliPackageDeps(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliPackageDepsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliPackageDeps", "query", variables);
+    },
+    CliComparePackages(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliComparePackagesDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliComparePackages", "query", variables);
+    },
+    CliDocsSearch(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliDocsSearchDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliDocsSearch", "query", variables);
+    },
+    CliProjectDocsSearch(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliProjectDocsSearchDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliProjectDocsSearch", "query", variables);
+    },
+    CliDocsList(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliDocsListDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliDocsList", "query", variables);
+    },
+    CliDocsGet(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CliDocsGetDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CliDocsGet", "query", variables);
+    },
+    CreateProject(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(CreateProjectDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "CreateProject", "mutation", variables);
+    },
     PackageSummary(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(PackageSummaryDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "PackageSummary", "query", variables);
     },
@@ -204,6 +596,18 @@ function getSdk(client, withWrapper = defaultWrapper) {
     },
     ComparePackages(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(ComparePackagesDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "ComparePackages", "query", variables);
+    },
+    ListPackageDocs(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(ListPackageDocsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "ListPackageDocs", "query", variables);
+    },
+    FetchPackageDoc(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(FetchPackageDocDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "FetchPackageDoc", "query", variables);
+    },
+    SearchPackageDocs(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchPackageDocsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchPackageDocs", "query", variables);
+    },
+    SearchProjectDocs(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchProjectDocsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchProjectDocs", "query", variables);
     }
   };
 }
@@ -494,6 +898,32 @@ function migrateV2ToV3(legacy) {
     tokens
   };
 }
+// src/services/auth-utils.ts
+var PROJECT_MANIFEST_UPLOAD_SCOPE = "project_manifest_upload";
+async function checkProjectWriteScope(authStorage, baseUrl) {
+  const envToken = process.env.PKGSEER_API_TOKEN;
+  if (envToken) {
+    return {
+      token: envToken,
+      tokenName: "PKGSEER_API_TOKEN",
+      scopes: [],
+      createdAt: new Date().toISOString(),
+      expiresAt: null,
+      apiKeyId: 0
+    };
+  }
+  const auth = await authStorage.load(baseUrl);
+  if (!auth) {
+    return null;
+  }
+  if (auth.expiresAt && new Date(auth.expiresAt) < new Date) {
+    return null;
+  }
+  if (!auth.scopes.includes(PROJECT_MANIFEST_UPLOAD_SCOPE)) {
+    return null;
+  }
+  return auth;
+}
 // src/services/browser-service.ts
 import open from "open";
 
@@ -502,8 +932,143 @@ class BrowserServiceImpl {
     await open(url);
   }
 }
+// src/services/config-service.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { z } from "zod";
+var CONFIG_DIR2 = ".pkgseer";
+var GLOBAL_CONFIG_FILE = "config.yml";
+var PROJECT_CONFIG_FILE = "pkgseer.yml";
+var TOOL_NAMES = [
+  "package_summary",
+  "package_vulnerabilities",
+  "package_dependencies",
+  "package_quality",
+  "compare_packages",
+  "list_package_docs",
+  "fetch_package_doc",
+  "search_package_docs",
+  "search_project_docs"
+];
+var ToolNameSchema = z.enum(TOOL_NAMES);
+var SharedConfigFields = {
+  enabled_tools: z.array(ToolNameSchema).optional()
+};
+var GlobalConfigSchema = z.object({
+  ...SharedConfigFields
+});
+var ManifestGroupSchema = z.object({
+  label: z.string(),
+  files: z.array(z.string()),
+  allow_mix_deps: z.boolean().optional()
+});
+var ProjectConfigSchema = z.object({
+  ...SharedConfigFields,
+  project: z.string().optional(),
+  manifests: z.array(ManifestGroupSchema).optional()
+});
+var MergedConfigSchema = z.object({
+  enabled_tools: z.array(ToolNameSchema).optional(),
+  project: z.string().optional(),
+  manifests: z.array(ManifestGroupSchema).optional()
+});
+
+class ConfigServiceImpl {
+  fs;
+  constructor(fs) {
+    this.fs = fs;
+  }
+  getGlobalConfigPath() {
+    return this.fs.joinPath(this.fs.getHomeDir(), CONFIG_DIR2, GLOBAL_CONFIG_FILE);
+  }
+  async loadGlobalConfig() {
+    const configPath = this.getGlobalConfigPath();
+    return this.loadAndParseConfig(configPath, GlobalConfigSchema);
+  }
+  async loadProjectConfig() {
+    let currentDir = this.fs.getCwd();
+    while (true) {
+      const configPath = this.fs.joinPath(currentDir, PROJECT_CONFIG_FILE);
+      const config = await this.loadAndParseConfig(configPath, ProjectConfigSchema);
+      if (config) {
+        return { config, path: configPath };
+      }
+      const parentDir = this.fs.getDirname(currentDir);
+      if (parentDir === currentDir) {
+        break;
+      }
+      currentDir = parentDir;
+    }
+    return null;
+  }
+  async loadMergedConfig() {
+    const [globalConfig, projectResult] = await Promise.all([
+      this.loadGlobalConfig(),
+      this.loadProjectConfig()
+    ]);
+    const merged = {};
+    if (globalConfig?.enabled_tools) {
+      merged.enabled_tools = globalConfig.enabled_tools;
+    }
+    if (projectResult?.config) {
+      if (projectResult.config.enabled_tools) {
+        merged.enabled_tools = projectResult.config.enabled_tools;
+      }
+      if (projectResult.config.project) {
+        merged.project = projectResult.config.project;
+      }
+    }
+    return {
+      config: merged,
+      globalPath: globalConfig ? this.getGlobalConfigPath() : null,
+      projectPath: projectResult?.path ?? null
+    };
+  }
+  async writeProjectConfig(config) {
+    const validated = ProjectConfigSchema.parse(config);
+    const currentDir = this.fs.getCwd();
+    const configPath = this.fs.joinPath(currentDir, PROJECT_CONFIG_FILE);
+    const existing = await this.loadProjectConfig();
+    const existingConfig = existing?.config ?? {};
+    const mergedConfig = {
+      ...existingConfig,
+      ...validated
+    };
+    const yamlContent = stringifyYaml(mergedConfig, {
+      defaultStringType: "PLAIN",
+      nullStr: ""
+    });
+    await this.fs.writeFile(configPath, yamlContent);
+  }
+  async loadAndParseConfig(path, schema) {
+    const exists = await this.fs.exists(path);
+    if (!exists) {
+      return null;
+    }
+    try {
+      const content = await this.fs.readFile(path);
+      const parsed = parseYaml(content);
+      if (parsed === null || parsed === undefined) {
+        return schema.parse({});
+      }
+      const result = schema.safeParse(parsed);
+      if (result.success) {
+        return result.data;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+}
 // src/services/filesystem-service.ts
-import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  stat,
+  unlink,
+  writeFile
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -540,6 +1105,50 @@ class FileSystemServiceImpl {
   joinPath(...segments) {
     return join(...segments);
   }
+  getCwd() {
+    return process.cwd();
+  }
+  getDirname(path) {
+    return dirname(path);
+  }
+  async readdir(path) {
+    return readdir(path);
+  }
+  async isDirectory(path) {
+    try {
+      const stats = await stat(path);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+}
+// src/services/git-service.ts
+import { exec } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join as join2 } from "node:path";
+import { promisify } from "node:util";
+var execAsync = promisify(exec);
+
+class GitServiceImpl {
+  cwd;
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+  async getCurrentBranch() {
+    try {
+      const { stdout } = await execAsync("git rev-parse --abbrev-ref HEAD", {
+        cwd: this.cwd
+      });
+      return stdout.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  async isGitRepository() {
+    const gitPath = join2(this.cwd, ".git");
+    return existsSync(gitPath);
+  }
 }
 // src/services/pkgseer-service.ts
 class PkgseerServiceImpl {
@@ -581,12 +1190,343 @@ class PkgseerServiceImpl {
     const result = await this.client.ComparePackages({ packages });
     return { data: result.data, errors: result.errors };
   }
-}
-// src/container.ts
-async function resolveApiToken(authStorage, baseUrl) {
-  const envToken = process.env.PKGSEER_API_TOKEN;
-  if (envToken) {
-    return envToken;
+  async listPackageDocs(registry, packageName, version2) {
+    const result = await this.client.ListPackageDocs({
+      registry,
+      packageName,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async fetchPackageDoc(registry, packageName, pageId, version2) {
+    const result = await this.client.FetchPackageDoc({
+      registry,
+      packageName,
+      pageId,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async searchPackageDocs(registry, packageName, options) {
+    const result = await this.client.SearchPackageDocs({
+      registry,
+      packageName,
+      keywords: options?.keywords,
+      query: options?.query,
+      includeSnippets: options?.includeSnippets,
+      limit: options?.limit,
+      version: options?.version
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async searchProjectDocs(project, options) {
+    const result = await this.client.SearchProjectDocs({
+      project,
+      keywords: options?.keywords,
+      query: options?.query,
+      includeSnippets: options?.includeSnippets,
+      limit: options?.limit
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliPackageInfo(registry, name) {
+    const result = await this.client.CliPackageInfo({ registry, name });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliPackageVulns(registry, name, version2) {
+    const result = await this.client.CliPackageVulns({
+      registry,
+      name,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliPackageQuality(registry, name, version2) {
+    const result = await this.client.CliPackageQuality({
+      registry,
+      name,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliPackageDeps(registry, name, version2, includeTransitive) {
+    const result = await this.client.CliPackageDeps({
+      registry,
+      name,
+      version: version2,
+      includeTransitive
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliComparePackages(packages) {
+    const result = await this.client.CliComparePackages({ packages });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliDocsList(registry, packageName, version2) {
+    const result = await this.client.CliDocsList({
+      registry,
+      packageName,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliDocsGet(registry, packageName, pageId, version2) {
+    const result = await this.client.CliDocsGet({
+      registry,
+      packageName,
+      pageId,
+      version: version2
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliDocsSearch(registry, packageName, options) {
+    const result = await this.client.CliDocsSearch({
+      registry,
+      packageName,
+      keywords: options?.keywords,
+      query: options?.query,
+      matchMode: options?.matchMode,
+      limit: options?.limit,
+      version: options?.version,
+      contextLinesBefore: options?.contextLinesBefore,
+      contextLinesAfter: options?.contextLinesAfter,
+      maxMatches: options?.maxMatches
+    });
+    return { data: result.data, errors: result.errors };
+  }
+  async cliProjectDocsSearch(project, options) {
+    const result = await this.client.CliProjectDocsSearch({
+      project,
+      keywords: options?.keywords,
+      query: options?.query,
+      matchMode: options?.matchMode,
+      limit: options?.limit,
+      contextLinesBefore: options?.contextLinesBefore,
+      contextLinesAfter: options?.contextLinesAfter,
+      maxMatches: options?.maxMatches
+    });
+    return { data: result.data, errors: result.errors };
+  }
+}
+// src/services/project-service.ts
+var PROJECT_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+var MIN_NAME_LENGTH = 1;
+var MAX_NAME_LENGTH = 100;
+function validateProjectName(name) {
+  const trimmedName = name?.trim() ?? "";
+  if (!trimmedName || trimmedName.length === 0) {
+    return { valid: false, error: "Project name cannot be empty" };
+  }
+  if (trimmedName.length < MIN_NAME_LENGTH) {
+    return {
+      valid: false,
+      error: `Project name must be at least ${MIN_NAME_LENGTH} character`
+    };
+  }
+  if (trimmedName.length > MAX_NAME_LENGTH) {
+    return {
+      valid: false,
+      error: `Project name must be at most ${MAX_NAME_LENGTH} characters`
+    };
+  }
+  if (!PROJECT_NAME_REGEX.test(trimmedName)) {
+    return {
+      valid: false,
+      error: "Project name can only contain alphanumeric characters, hyphens, and underscores, and must start with an alphanumeric character"
+    };
+  }
+  return { valid: true };
+}
+
+class ProjectServiceImpl {
+  client;
+  baseUrl;
+  apiToken;
+  constructor(client, baseUrl, apiToken) {
+    this.client = client;
+    this.baseUrl = baseUrl;
+    this.apiToken = apiToken;
+  }
+  async createProject(input) {
+    const validation = validateProjectName(input.name);
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+    const result = await this.client.CreateProject({ input });
+    if (result.errors && result.errors.length > 0 && result.errors[0]) {
+      throw new Error(result.errors[0].message);
+    }
+    if (!result.data?.createProject) {
+      throw new Error("Failed to create project");
+    }
+    if (result.data.createProject.errors && result.data.createProject.errors.length > 0) {
+      const firstError = result.data.createProject.errors[0];
+      if (firstError) {
+        throw new Error(firstError.message ?? "Validation failed");
+      }
+    }
+    return {
+      project: result.data.createProject.project ? {
+        name: result.data.createProject.project.name,
+        defaultBranch: result.data.createProject.project.defaultBranch
+      } : null,
+      errors: result.data.createProject.errors?.map((e) => ({
+        field: e?.field ?? "",
+        message: e?.message ?? ""
+      })) ?? null
+    };
+  }
+  detectPairedManifests(files) {
+    if (files.length !== 2) {
+      return null;
+    }
+    const depsTreeFile = files.find((f) => f.filename === "deps-tree.txt");
+    const depsFile = files.find((f) => f.filename === "deps.txt");
+    if (depsTreeFile && depsFile) {
+      return { projectFile: depsTreeFile, lockFile: depsFile };
+    }
+    const pyprojectFile = files.find((f) => f.filename === "pyproject.toml");
+    const poetryLockFile = files.find((f) => f.filename === "poetry.lock");
+    if (pyprojectFile && poetryLockFile) {
+      return { projectFile: pyprojectFile, lockFile: poetryLockFile };
+    }
+    const pipfile = files.find((f) => f.filename === "Pipfile");
+    const pipfileLock = files.find((f) => f.filename === "Pipfile.lock");
+    if (pipfile && pipfileLock) {
+      return { projectFile: pipfile, lockFile: pipfileLock };
+    }
+    return null;
+  }
+  async uploadManifests(params) {
+    const { project, branch, label, files } = params;
+    if (files.length === 0) {
+      throw new Error("At least one file is required");
+    }
+    const formData = new FormData;
+    formData.append("branch", branch);
+    formData.append("label", label);
+    const pairedManifests = this.detectPairedManifests(files);
+    if (pairedManifests) {
+      const { projectFile, lockFile } = pairedManifests;
+      for (const file of [projectFile, lockFile]) {
+        const sizeInBytes = new TextEncoder().encode(file.content).length;
+        const sizeInMB = sizeInBytes / (1024 * 1024);
+        if (sizeInMB > 10) {
+          throw new Error(`File ${file.filename} exceeds 10MB limit (${sizeInMB.toFixed(2)}MB)`);
+        }
+      }
+      const projectBlob = new Blob([projectFile.content], {
+        type: "text/plain"
+      });
+      const lockBlob = new Blob([lockFile.content], { type: "text/plain" });
+      formData.append("project_file", projectBlob, projectFile.filename);
+      formData.append("lock_file", lockBlob, lockFile.filename);
+    } else {
+      for (const file of files) {
+        const sizeInBytes = new TextEncoder().encode(file.content).length;
+        const sizeInMB = sizeInBytes / (1024 * 1024);
+        if (sizeInMB > 10) {
+          throw new Error(`File ${file.filename} exceeds 10MB limit (${sizeInMB.toFixed(2)}MB)`);
+        }
+        const blob = new Blob([file.content], { type: "text/plain" });
+        formData.append("files[]", blob, file.filename);
+      }
+    }
+    const url = `${this.baseUrl}/api/projects/${project}/manifests`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`
+      },
+      body: formData
+    });
+    if (!response.ok) {
+      let errorMessage = `Failed to upload manifests: ${response.status} ${response.statusText}`;
+      try {
+        const responseClone = response.clone();
+        const errorData = await responseClone.json();
+        if (errorData.error?.message) {
+          errorMessage = errorData.error.message;
+        } else if (errorData.error?.code) {
+          errorMessage = `Upload failed: ${errorData.error.code}`;
+        }
+      } catch {
+        try {
+          const responseClone = response.clone();
+          const errorText = await responseClone.text();
+          if (errorText) {
+            errorMessage = `Failed to upload manifests: ${errorText}`;
+          }
+        } catch {
+          errorMessage = `Failed to upload manifests: ${response.status} ${response.statusText}`;
+        }
+      }
+      if (response.status === 401) {
+        throw new Error("Authentication required. Please run `pkgseer login`.");
+      }
+      if (response.status === 403) {
+        throw new Error("Insufficient permissions. Please run `pkgseer login` with proper scopes.");
+      }
+      if (response.status === 404) {
+        throw new Error(`Project not found: ${project}`);
+      }
+      if (response.status === 429) {
+        const retryAfter = response.headers.get("Retry-After");
+        const retryMsg = retryAfter ? ` Please retry after ${retryAfter} seconds.` : "";
+        throw new Error(`Upload rate limit exceeded.${retryMsg}`);
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+}
+// src/services/prompt-service.ts
+import { confirm, input, select } from "@inquirer/prompts";
+
+class PromptServiceImpl {
+  async input(message, defaultValue) {
+    return input({ message, default: defaultValue });
+  }
+  async select(message, options) {
+    return select({
+      message,
+      choices: options.map((opt) => ({
+        value: opt.value,
+        name: opt.name,
+        description: opt.description
+      }))
+    });
+  }
+  async confirm(message, defaultValue) {
+    return confirm({ message, default: defaultValue });
+  }
+}
+// src/services/shell-service.ts
+import { exec as exec2 } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+var execAsync2 = promisify2(exec2);
+
+class ShellServiceImpl {
+  async execute(command, cwd) {
+    try {
+      const { stdout } = await execAsync2(command, {
+        cwd,
+        maxBuffer: 10 * 1024 * 1024
+      });
+      return stdout.trim();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Command failed: ${command}
+  Working directory: ${cwd}
+  Error: ${errorMessage}`);
+    }
+  }
+}
+// src/container.ts
+async function resolveApiToken(authStorage, baseUrl) {
+  const envToken = process.env.PKGSEER_API_TOKEN;
+  if (envToken) {
+    return envToken;
   }
   const stored = await authStorage.load(baseUrl);
   if (stored) {
@@ -601,7 +1541,11 @@ async function createContainer() {
   const baseUrl = getBaseUrl();
   const fileSystemService = new FileSystemServiceImpl;
   const authStorage = new AuthStorageImpl(fileSystemService);
-  const apiToken = await resolveApiToken(authStorage, baseUrl);
+  const configService = new ConfigServiceImpl(fileSystemService);
+  const [apiToken, configResult] = await Promise.all([
+    resolveApiToken(authStorage, baseUrl),
+    configService.loadMergedConfig()
+  ]);
   const client = createClient(apiToken);
   return {
     pkgseerService: new PkgseerServiceImpl(client),
@@ -609,7 +1553,14 @@ async function createContainer() {
     authService: new AuthServiceImpl(baseUrl),
     browserService: new BrowserServiceImpl,
     fileSystemService,
+    configService,
+    projectService: new ProjectServiceImpl(client, baseUrl, apiToken ?? ""),
+    gitService: new GitServiceImpl,
+    promptService: new PromptServiceImpl,
+    shellService: new ShellServiceImpl,
+    config: configResult.config,
     baseUrl,
+    apiToken,
     hasValidToken: apiToken !== undefined
   };
 }
@@ -663,388 +1614,2895 @@ function registerAuthStatusCommand(program) {
   });
 }
 
-// src/commands/login.ts
-import { hostname } from "node:os";
-var TIMEOUT_MS = 5 * 60 * 1000;
-function randomPort() {
-  return Math.floor(Math.random() * 2000) + 8000;
-}
-async function loginAction(options, deps) {
-  const { authService, authStorage, browserService, baseUrl } = deps;
-  const existing = await authStorage.load(baseUrl);
-  if (existing) {
-    const isExpired = existing.expiresAt && new Date(existing.expiresAt) < new Date;
-    if (!isExpired) {
-      console.log(`Already logged in.
-`);
-      console.log(`  Environment: ${baseUrl}`);
-      console.log(`  Token: ${existing.tokenName}
-`);
-      console.log("To switch accounts, run `pkgseer logout` first.");
-      return;
-    }
-    console.log(`Token expired. Starting new login...
+// src/commands/config-show.ts
+async function configShowAction(deps) {
+  const { configService } = deps;
+  const { config, globalPath, projectPath } = await configService.loadMergedConfig();
+  if (!globalPath && !projectPath) {
+    console.log(`No configuration found.
 `);
-  }
-  const { verifier, challenge, state } = authService.generatePkceParams();
-  const port = options.port ?? randomPort();
-  const authUrl = authService.buildAuthUrl({
-    state,
-    port,
-    codeChallenge: challenge,
-    hostname: hostname()
-  });
-  const serverPromise = authService.startCallbackServer(port);
-  if (options.browser === false) {
-    console.log(`Open this URL in your browser:
+    console.log("  Global config: ~/.pkgseer/config.yml");
+    console.log(`  Project config: pkgseer.yml
 `);
-    console.log(`  ${authUrl}
-`);
-  } else {
-    console.log("Opening browser...");
-    await browserService.open(authUrl);
+    console.log("Create a config file to customize pkgseer behavior.");
+    return;
   }
-  console.log(`Waiting for authentication...
-`);
-  let timeoutId;
-  const timeoutPromise = new Promise((_, reject) => {
-    timeoutId = setTimeout(() => reject(new Error("Authentication timed out")), TIMEOUT_MS);
-  });
-  let callback;
-  try {
-    callback = await Promise.race([serverPromise, timeoutPromise]);
-    clearTimeout(timeoutId);
-  } catch (error) {
-    clearTimeout(timeoutId);
-    if (error instanceof Error) {
-      console.log(`${error.message}.
+  console.log(`Configuration sources:
 `);
-      console.log("Run `pkgseer login` to try again.");
-    }
-    process.exit(1);
+  if (globalPath) {
+    console.log(`  Global: ${globalPath}`);
   }
-  if (callback.state !== state) {
-    console.error(`Security error: authentication state mismatch.
-`);
-    console.log("This could indicate a security issue. Please try again.");
-    process.exit(1);
+  if (projectPath) {
+    console.log(`  Project: ${projectPath}`);
   }
-  let tokenResponse;
-  try {
-    tokenResponse = await authService.exchangeCodeForToken({
-      code: callback.code,
-      codeVerifier: verifier,
-      state
-    });
-  } catch (error) {
-    console.error(`Failed to complete authentication: ${error instanceof Error ? error.message : error}
+  console.log(`
+Merged configuration:
 `);
-    console.log("Run `pkgseer login` to try again.");
-    process.exit(1);
+  if (config.enabled_tools !== undefined) {
+    if (config.enabled_tools.length > 0) {
+      console.log("  enabled_tools:");
+      for (const tool of config.enabled_tools) {
+        console.log(`    - ${tool}`);
+      }
+    } else {
+      console.log("  enabled_tools: [] (no tools enabled)");
+    }
+  } else {
+    console.log("  enabled_tools: (all tools enabled by default)");
   }
-  await authStorage.save(baseUrl, {
-    token: tokenResponse.token,
-    tokenName: tokenResponse.tokenName,
-    scopes: tokenResponse.scopes,
-    createdAt: new Date().toISOString(),
-    expiresAt: tokenResponse.expiresAt,
-    apiKeyId: tokenResponse.apiKeyId
-  });
-  console.log(`✓ Logged in
-`);
-  console.log(`  Environment: ${baseUrl}`);
-  console.log(`  Token: ${tokenResponse.tokenName}`);
-  if (tokenResponse.expiresAt) {
-    const days = Math.ceil((new Date(tokenResponse.expiresAt).getTime() - Date.now()) / (1000 * 60 * 60 * 24));
-    console.log(`  Expires: in ${days} days`);
+  if (config.project) {
+    console.log(`  project: ${config.project}`);
   }
-  console.log(`
-You're ready to use pkgseer with your AI assistant.`);
 }
-var LOGIN_DESCRIPTION = `Authenticate with your PkgSeer account via browser.
-
-Opens your browser to complete authentication securely. The CLI receives
-a token that's stored locally and used for API requests.
+var SHOW_DESCRIPTION = `Display current configuration.
 
-Use --no-browser in environments without a display (CI, SSH sessions)
-to get a URL you can open on another device.`;
-function registerLoginCommand(program) {
-  program.command("login").summary("Authenticate with your PkgSeer account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).action(async (options) => {
+Shows the merged configuration from global (~/.pkgseer/config.yml) and
+project (pkgseer.yml) config files. Project config takes precedence
+over global config for overlapping settings.`;
+function registerConfigShowCommand(program) {
+  program.command("show").summary("Display current configuration").description(SHOW_DESCRIPTION).action(async () => {
     const deps = await createContainer();
-    await loginAction(options, deps);
+    await configShowAction(deps);
   });
 }
 
-// src/commands/logout.ts
-async function logoutAction(deps) {
-  const { authService, authStorage, baseUrl } = deps;
-  const auth = await authStorage.load(baseUrl);
-  if (!auth) {
-    console.log(`Not currently logged in.
-`);
-    console.log(`  Environment: ${baseUrl}`);
-    return;
+// src/commands/shared.ts
+function toGraphQLRegistry(registry) {
+  const map = {
+    npm: "NPM",
+    pypi: "PYPI",
+    hex: "HEX"
+  };
+  return map[registry.toLowerCase()] || "NPM";
+}
+function output(data, json) {
+  if (json) {
+    console.log(JSON.stringify(data));
+  } else {
+    console.log(data);
   }
-  try {
-    await authService.revokeToken(auth.token);
-  } catch {}
-  await authStorage.clear(baseUrl);
-  console.log(`✓ Logged out
-`);
-  console.log(`  Environment: ${baseUrl}`);
 }
-var LOGOUT_DESCRIPTION = `Remove stored credentials and revoke the token.
-
-Clears the locally stored authentication token and notifies the server
-to revoke it. Use this when switching accounts or on shared machines.`;
-function registerLogoutCommand(program) {
-  program.command("logout").summary("Remove stored credentials").description(LOGOUT_DESCRIPTION).action(async () => {
+function outputError(message, json) {
+  if (json) {
+    console.error(JSON.stringify({ error: message }));
+  } else {
+    console.error(`Error: ${message}`);
+  }
+  process.exit(1);
+}
+function handleErrors(errors, json) {
+  if (errors && errors.length > 0) {
+    const message = errors.map((e) => e.message).join(", ");
+    outputError(message, json);
+  }
+}
+function formatNumber(num) {
+  if (num == null)
+    return "N/A";
+  return num.toLocaleString();
+}
+function keyValueTable(pairs) {
+  const maxKeyLen = Math.max(...pairs.map(([k]) => k.length));
+  return pairs.map(([key, value]) => `  ${key.padEnd(maxKeyLen)}  ${value ?? "N/A"}`).join(`
+`);
+}
+function formatSeverity(severity) {
+  const indicators = {
+    CRITICAL: "\uD83D\uDD34 CRITICAL",
+    HIGH: "\uD83D\uDFE0 HIGH",
+    MEDIUM: "\uD83D\uDFE1 MEDIUM",
+    LOW: "\uD83D\uDFE2 LOW",
+    UNKNOWN: "⚪ UNKNOWN"
+  };
+  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 (messages.length > 0) {
+        return messages.join("; ");
+      }
+    }
+  }
+  if (error && typeof error === "object" && "errors" in error && Array.isArray(error.errors)) {
+    const errors = error.errors;
+    if (errors.length > 0) {
+      const messages = errors.map((e) => e.message).filter((m) => typeof m === "string");
+      if (messages.length > 0) {
+        return messages.join("; ");
+      }
+    }
+  }
+  if (error instanceof Error) {
+    const message = error.message;
+    const jsonMatch = message.match(/"message"\s*:\s*"([^"]+)"/);
+    if (jsonMatch?.[1]) {
+      return jsonMatch[1];
+    }
+    if (message.includes("Cannot query field") || message.includes("Unknown field")) {
+      return message;
+    }
+  }
+  return null;
+}
+function formatErrorMessage(errorMessage, isJson) {
+  if (isJson) {
+    return errorMessage;
+  }
+  if (errorMessage.includes("Cannot query field") || errorMessage.includes("Unknown field") || errorMessage.includes("Field") && errorMessage.includes("doesn't exist")) {
+    return `${errorMessage}
+
+` + `This error usually indicates a schema mismatch. Possible causes:
+` + `  - The server schema is outdated (try updating the server)
+` + `  - The client schema is outdated (run: bun run codegen)
+` + `  - You're querying a different server than expected (check PKGSEER_URL)`;
+  }
+  return errorMessage;
+}
+async function withCliErrorHandling(json, fn) {
+  try {
+    await fn();
+  } catch (error) {
+    const graphQLError = extractGraphQLError(error);
+    if (graphQLError) {
+      const formatted = formatErrorMessage(graphQLError, json);
+      outputError(formatted, json);
+      return;
+    }
+    const message = error instanceof Error ? error.message : "Unknown error";
+    const colonMatch = message.match(/^([^:]+):/);
+    const shortMessage = colonMatch?.[1] ?? message;
+    outputError(shortMessage, json);
+  }
+}
+function formatScore(score) {
+  if (score == null)
+    return "N/A";
+  const percentage = score > 1 ? Math.round(score) : Math.round(score * 100);
+  const filled = Math.round(percentage / 5);
+  const bar = "█".repeat(Math.min(filled, 20)) + "░".repeat(Math.max(20 - filled, 0));
+  return `${bar} ${percentage}%`;
+}
+
+// src/commands/docs/get.ts
+function parsePackageRef(ref) {
+  if (!ref.includes("/")) {
+    throw new Error(`Invalid format: "${ref}". Expected format:
+` + `  Full form: <registry>/<package>/<version>/<document>
+` + `  Short form: <package>/<document>
+` + `Examples: npm/express/4.18.2/readme or express/readme`);
+  }
+  const parts = ref.split("/");
+  if (parts.length < 2) {
+    throw new Error(`Invalid format: "${ref}". Expected at least 2 parts separated by "/"`);
+  }
+  if (parts.length >= 4) {
+    const registry = parts[0];
+    const packageName2 = parts[1];
+    const version2 = parts[2];
+    const pageId2 = parts.slice(3).join("/");
+    if (!registry || !packageName2 || !version2 || !pageId2) {
+      throw new Error(`Invalid full form: "${ref}". All components (registry/package/version/document) are required.`);
+    }
+    return {
+      registry: registry.toLowerCase(),
+      packageName: packageName2,
+      version: version2,
+      pageId: pageId2,
+      originalRef: ref
+    };
+  }
+  const packageName = parts[0];
+  const pageId = parts.slice(1).join("/");
+  if (!packageName || !pageId) {
+    throw new Error(`Invalid format: "${ref}". Expected format: <package>/<document>`);
+  }
+  return { packageName, pageId, originalRef: ref };
+}
+function formatDocPage(data, ref) {
+  const lines = [];
+  const page = data.page;
+  if (!page) {
+    return `[${ref}] No page content available.`;
+  }
+  lines.push(`[${ref}]`);
+  lines.push("");
+  if (page.breadcrumbs && page.breadcrumbs.length > 0) {
+    lines.push(page.breadcrumbs.join(" > "));
+    lines.push("");
+  }
+  lines.push(`# ${page.title}`);
+  lines.push("");
+  if (page.content) {
+    lines.push(page.content);
+  } else {
+    lines.push("(No content available)");
+  }
+  return lines.join(`
+`);
+}
+function extractErrorMessage(error) {
+  if (error instanceof Error) {
+    const message = error.message;
+    if (message.includes('"response"')) {
+      const colonIndex = message.indexOf(":");
+      if (colonIndex > 0) {
+        return message.slice(0, colonIndex).trim();
+      }
+    }
+    return message;
+  }
+  return "Unknown error occurred";
+}
+async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
+  try {
+    const registry = ref.registry ? toGraphQLRegistry(ref.registry) : defaultRegistry;
+    const version2 = ref.version ?? defaultVersion;
+    const result = await pkgseerService.cliDocsGet(registry, ref.packageName, ref.pageId, version2);
+    if (result.errors && result.errors.length > 0) {
+      const errorMsg = result.errors.map((e) => {
+        if (typeof e === "object" && e !== null && "message" in e) {
+          return String(e.message);
+        }
+        return String(e);
+      }).join("; ");
+      return { ref: ref.originalRef, result: null, error: errorMsg };
+    }
+    if (!result.data.fetchPackageDoc) {
+      return {
+        ref: ref.originalRef,
+        result: null,
+        error: `Page not found: ${ref.pageId} for ${ref.packageName}`
+      };
+    }
+    return { ref: ref.originalRef, result: result.data.fetchPackageDoc };
+  } catch (error) {
+    return {
+      ref: ref.originalRef,
+      result: null,
+      error: extractErrorMessage(error)
+    };
+  }
+}
+async function docsGetAction(refs, options, deps) {
+  if (refs.length === 0) {
+    outputError("At least one page reference required. Format: <package>/<slug>", options.json ?? false);
+    return;
+  }
+  const { pkgseerService } = deps;
+  const defaultRegistry = toGraphQLRegistry(options.registry);
+  const parsedRefs = [];
+  for (const ref of refs) {
+    try {
+      parsedRefs.push(parsePackageRef(ref));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      outputError(`Invalid reference "${ref}": ${message}`, options.json ?? false);
+      return;
+    }
+  }
+  const results = await Promise.all(parsedRefs.map((ref) => fetchPage(ref, defaultRegistry, options.pkgVersion, pkgseerService)));
+  const errors = results.filter((r) => r.error);
+  const successes = results.filter((r) => r.result);
+  if (errors.length === results.length) {
+    const errorMessages = errors.map((e) => `  ${e.ref}: ${e.error}`).join(`
+`);
+    outputError(`Failed to fetch all pages:
+${errorMessages}`, options.json ?? false);
+    return;
+  }
+  if (errors.length > 0 && !options.json) {
+    for (const { ref, error } of errors) {
+      console.error(`Error fetching ${ref}: ${error}`);
+    }
+    if (successes.length > 0) {
+      console.error("");
+    }
+  }
+  if (options.json) {
+    const jsonResults = results.map((r) => {
+      if (r.error) {
+        return { ref: r.ref, error: r.error };
+      }
+      const page = r.result?.page;
+      return {
+        ref: r.ref,
+        title: page?.title,
+        content: page?.content
+      };
+    });
+    output(jsonResults, true);
+  } else {
+    if (successes.length > 0) {
+      const pages = successes.filter((r) => r.result !== null).map((r) => formatDocPage(r.result, r.ref));
+      console.log(pages.join(`
+
+---
+
+`));
+    }
+  }
+  if (errors.length > 0) {
+    process.exit(1);
+  }
+}
+var GET_DESCRIPTION = `Fetch one or more documentation pages.
+
+Retrieves the full content of documentation pages including
+title, breadcrumbs, content (markdown), and source URL.
+
+Use 'pkgseer docs list' first to discover available page IDs, or
+use the output format from 'pkgseer docs search --refs-only'.
+
+Format: <registry>/<package>/<version>/<document> (full form)
+        or <package>/<document> (short form, requires --registry/--pkg-version)
+
+Examples:
+  # Full form (from search output)
+  pkgseer docs get npm/express/4.18.2/readme
+  pkgseer docs get hex/postgrex/1.15.0/readme
+
+  # Short form (backward compatibility)
+  pkgseer docs get express/readme --registry npm --pkg-version 4.18.2
+  pkgseer docs get postgrex/readme --registry hex
+
+  # Multiple pages
+  pkgseer docs get npm/express/4.18.2/readme npm/express/4.18.2/writing-middleware
+
+  # Pipe from search (full form works seamlessly)
+  pkgseer docs search log --package express --refs-only | \\
+    xargs pkgseer docs get`;
+function registerDocsGetCommand(program) {
+  program.command("get <refs...>").summary("Fetch documentation page(s)").description(GET_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (refs, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await docsGetAction(refs, options, deps);
+    });
+  });
+}
+// src/commands/docs/list.ts
+function formatDocsList(docs) {
+  const lines = [];
+  lines.push(`\uD83D\uDCDA Documentation: ${docs.packageName}@${docs.version}`);
+  lines.push("");
+  if (!docs.pages || docs.pages.length === 0) {
+    lines.push("No documentation pages found.");
+    return lines.join(`
+`);
+  }
+  lines.push(`Found ${docs.pages.length} pages:`);
+  lines.push("");
+  for (const page of docs.pages) {
+    if (!page)
+      continue;
+    const words = page.words ? ` (${formatNumber(page.words)} words)` : "";
+    lines.push(`  ${page.title}${words}`);
+    lines.push(`    ID: ${page.slug}`);
+    lines.push("");
+  }
+  lines.push("Use 'pkgseer docs get <package>/<page-id>' to fetch a page.");
+  return lines.join(`
+`);
+}
+async function docsListAction(packageName, options, deps) {
+  const { pkgseerService } = deps;
+  const registry = toGraphQLRegistry(options.registry);
+  const result = await pkgseerService.cliDocsList(registry, packageName, options.pkgVersion);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.listPackageDocs) {
+    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const pages = result.data.listPackageDocs.pages?.filter((p) => p) ?? [];
+    const slim = pages.map((p) => ({
+      slug: p.slug,
+      title: p.title
+    }));
+    output(slim, true);
+  } else {
+    console.log(formatDocsList(result.data.listPackageDocs));
+  }
+}
+var LIST_DESCRIPTION = `List available documentation pages for a package.
+
+Shows all documentation pages with titles, page IDs (slugs),
+word counts, and descriptions. Use the page ID with 'docs get'
+to fetch the full content of a specific page.
+
+Examples:
+  pkgseer docs list lodash
+  pkgseer docs list requests --registry pypi
+  pkgseer docs list phoenix --registry hex --version 1.7.0 --json`;
+function registerDocsListCommand(program) {
+  program.command("list <package>").summary("List documentation pages").description(LIST_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await docsListAction(packageName, options, deps);
+    });
+  });
+}
+// src/commands/docs/search.ts
+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",
+  dim: "\x1B[2m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  green: "\x1B[32m"
+};
+function shouldUseColors(noColor) {
+  if (noColor)
+    return false;
+  if (process.env.NO_COLOR !== undefined)
+    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;
+  });
+  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}`;
+  }
+  return result;
+}
+function formatEntry(entry, searchResult, 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}`);
+      }
+    }
+    for (const matchedLine of ctx.matchedLines ?? []) {
+      if (matchedLine?.content) {
+        const highlighted = applyHighlights(matchedLine.content, matchedLine.highlights, useColors);
+        lines.push(`  ${highlighted}`);
+      }
+    }
+    for (const afterLine of ctx.after ?? []) {
+      if (afterLine) {
+        const prefix = useColors ? colors.dim : "";
+        const suffix = useColors ? colors.reset : "";
+        lines.push(`  ${prefix}${afterLine}${suffix}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function formatSearchResults(results, useColors) {
+  const entries = results.entries ?? [];
+  if (entries.length === 0) {
+    return "No matching documentation found.";
+  }
+  const formatted = entries.filter((e) => e != null).map((entry) => formatEntry(entry, results, useColors));
+  return formatted.join(`
+`);
+}
+function formatRefsOnly(results) {
+  const entries = results.entries ?? [];
+  return entries.filter((e) => e != null).map((entry) => buildDocRef(entry, results)).join(`
+`);
+}
+function formatCount(results) {
+  const entries = results.entries ?? [];
+  return entries.filter((e) => e != null).map((entry) => {
+    if (!entry)
+      return "";
+    const ref = buildDocRef(entry, results);
+    return `${ref}: ${entry.matchCount ?? 0}`;
+  }).filter((s) => s !== "").join(`
+`);
+}
+function slimSearchResults(results) {
+  const entries = results.entries ?? [];
+  return entries.filter((e) => e != null).map((entry) => {
+    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);
+}
+async function docsSearchAction(queryArg, options, deps) {
+  const { pkgseerService, config } = deps;
+  const searchQuery = queryArg || options.query;
+  const keywords = options.keywords;
+  if (!searchQuery && (!keywords || keywords.length === 0)) {
+    outputError("Search query required. Provide a query as argument or use --query/--keywords", 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.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, {
+      query: searchQuery,
+      keywords,
+      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);
+    return;
+  }
+  if (project) {
+    const result = await pkgseerService.cliProjectDocsSearch(project, {
+      query: searchQuery,
+      keywords,
+      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);
+    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);
+}
+function outputResults(results, options, useColors) {
+  if (options.json) {
+    output(slimSearchResults(results), true);
+  } else if (options.refsOnly) {
+    console.log(formatRefsOnly(results));
+  } else if (options.count) {
+    console.log(formatCount(results));
+  } else {
+    console.log(formatSearchResults(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.
+
+By default, searches project documentation if project is
+configured in pkgseer.yml. Use --package to search a specific
+package instead.
+
+Examples:
+  # Search with context (like grep)
+  pkgseer docs search "error handling" --package express
+  pkgseer docs search log --package express -C 3
+
+  # Multiple keywords (OR by default)
+  pkgseer docs search -k "middleware,routing" --package express
+
+  # Strict matching (AND mode)
+  pkgseer docs search -k "error,middleware" --mode and --package express
+
+  # Output for piping
+  pkgseer docs search log --package express --refs-only | \\
+    xargs -I{} pkgseer docs get express {}
+
+  # Count matches
+  pkgseer docs search error --package express --count`;
+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("-q, --query <query>", "Search query (alternative to argument)").option("-k, --keywords <words>", "Comma-separated keywords", (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("--mode <mode>", "Match mode: or (default), and").option("--refs-only", "Output only page references (for piping)").option("--count", "Output only match counts per page").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
+}
+function registerDocsSearchCommand(program) {
+  const cmd = program.command("search [query]").summary("Search documentation").description(SEARCH_DESCRIPTION);
+  addSearchOptions(cmd).action(async (query, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await docsSearchAction(query, options, deps);
+    });
+  });
+}
+// src/commands/login.ts
+import { hostname } from "node:os";
+var TIMEOUT_MS = 5 * 60 * 1000;
+function randomPort() {
+  return Math.floor(Math.random() * 2000) + 8000;
+}
+async function loginAction(options, deps) {
+  const { authService, authStorage, browserService, baseUrl } = deps;
+  const existing = await authStorage.load(baseUrl);
+  if (existing && !options.force) {
+    const isExpired = existing.expiresAt && new Date(existing.expiresAt) < new Date;
+    if (!isExpired) {
+      console.log(`Already logged in.
+`);
+      console.log(`  Environment: ${baseUrl}`);
+      console.log(`  Token: ${existing.tokenName}
+`);
+      console.log("To switch accounts, run `pkgseer logout` first.");
+      console.log("To re-authenticate with different scopes, use `pkgseer login --force`.");
+      return;
+    }
+    console.log(`Token expired. Starting new login...
+`);
+  } else if (existing && options.force) {
+    console.log(`Re-authenticating (--force flag)...
+`);
+  }
+  const { verifier, challenge, state } = authService.generatePkceParams();
+  const port = options.port ?? randomPort();
+  const authUrl = authService.buildAuthUrl({
+    state,
+    port,
+    codeChallenge: challenge,
+    hostname: hostname()
+  });
+  const serverPromise = authService.startCallbackServer(port);
+  if (options.browser === false) {
+    console.log(`Open this URL in your browser:
+`);
+    console.log(`  ${authUrl}
+`);
+  } else {
+    console.log("Opening browser...");
+    await browserService.open(authUrl);
+  }
+  console.log(`Waiting for authentication...
+`);
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error("Authentication timed out")), TIMEOUT_MS);
+  });
+  let callback;
+  try {
+    callback = await Promise.race([serverPromise, timeoutPromise]);
+    clearTimeout(timeoutId);
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error) {
+      console.log(`${error.message}.
+`);
+      console.log("Run `pkgseer login` to try again.");
+    }
+    process.exit(1);
+  }
+  if (callback.state !== state) {
+    console.error(`Security error: authentication state mismatch.
+`);
+    console.log("This could indicate a security issue. Please try again.");
+    process.exit(1);
+  }
+  let tokenResponse;
+  try {
+    tokenResponse = await authService.exchangeCodeForToken({
+      code: callback.code,
+      codeVerifier: verifier,
+      state
+    });
+  } catch (error) {
+    console.error(`Failed to complete authentication: ${error instanceof Error ? error.message : error}
+`);
+    console.log("Run `pkgseer login` to try again.");
+    process.exit(1);
+  }
+  await authStorage.save(baseUrl, {
+    token: tokenResponse.token,
+    tokenName: tokenResponse.tokenName,
+    scopes: tokenResponse.scopes,
+    createdAt: new Date().toISOString(),
+    expiresAt: tokenResponse.expiresAt,
+    apiKeyId: tokenResponse.apiKeyId
+  });
+  console.log(`✓ Logged in
+`);
+  console.log(`  Environment: ${baseUrl}`);
+  console.log(`  Token: ${tokenResponse.tokenName}`);
+  if (tokenResponse.expiresAt) {
+    const days = Math.ceil((new Date(tokenResponse.expiresAt).getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    console.log(`  Expires: in ${days} days`);
+  }
+  console.log(`
+You're ready to use pkgseer with your AI assistant.`);
+}
+var LOGIN_DESCRIPTION = `Authenticate with your PkgSeer account via browser.
+
+Opens your browser to complete authentication securely. The CLI receives
+a token that's stored locally and used for API requests.
+
+Use --no-browser in environments without a display (CI, SSH sessions)
+to get a URL you can open on another device.`;
+function registerLoginCommand(program) {
+  program.command("login").summary("Authenticate with your PkgSeer account").description(LOGIN_DESCRIPTION).option("--no-browser", "Print URL instead of opening browser").option("--port <port>", "Port for local callback server", parseInt).option("--force", "Re-authenticate even if already logged in").action(async (options) => {
+    const deps = await createContainer();
+    await loginAction(options, deps);
+  });
+}
+
+// src/commands/logout.ts
+async function logoutAction(deps) {
+  const { authService, authStorage, baseUrl } = deps;
+  const auth = await authStorage.load(baseUrl);
+  if (!auth) {
+    console.log(`Not currently logged in.
+`);
+    console.log(`  Environment: ${baseUrl}`);
+    return;
+  }
+  try {
+    await authService.revokeToken(auth.token);
+  } catch {}
+  await authStorage.clear(baseUrl);
+  console.log(`✓ Logged out
+`);
+  console.log(`  Environment: ${baseUrl}`);
+}
+var LOGOUT_DESCRIPTION = `Remove stored credentials and revoke the token.
+
+Clears the locally stored authentication token and notifies the server
+to revoke it. Use this when switching accounts or on shared machines.`;
+function registerLogoutCommand(program) {
+  program.command("logout").summary("Remove stored credentials").description(LOGOUT_DESCRIPTION).action(async () => {
+    const deps = await createContainer();
+    await logoutAction(deps);
+  });
+}
+
+// src/commands/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/compare-packages.ts
+import { z as z3 } from "zod";
+
+// src/tools/shared.ts
+import { z as z2 } from "zod";
+
+// src/tools/types.ts
+function textResult(text) {
+  return {
+    content: [{ type: "text", text }]
+  };
+}
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+
+// src/tools/shared.ts
+function toGraphQLRegistry2(registry) {
+  const map = {
+    npm: "NPM",
+    pypi: "PYPI",
+    hex: "HEX"
+  };
+  return map[registry.toLowerCase()] || "NPM";
+}
+var schemas = {
+  registry: z2.enum(["npm", "pypi", "hex"]).describe("Package registry (npm, pypi, or hex)"),
+  packageName: z2.string().max(255).describe("Name of the package"),
+  version: z2.string().max(100).optional().describe("Specific version (defaults to latest)")
+};
+function handleGraphQLErrors(errors) {
+  if (errors && errors.length > 0) {
+    return errorResult(`Error: ${errors.map((e) => e.message).join(", ")}`);
+  }
+  return null;
+}
+async function withErrorHandling(operation, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return errorResult(`Failed to ${operation}: ${message}`);
+  }
+}
+function notFoundError(packageName, registry) {
+  return errorResult(`Package not found: ${packageName} in ${registry}`);
+}
+
+// src/tools/compare-packages.ts
+var packageInputSchema = z3.object({
+  registry: z3.enum(["npm", "pypi", "hex"]),
+  name: z3.string().max(255),
+  version: z3.string().max(100).optional()
+});
+var argsSchema = {
+  packages: z3.array(packageInputSchema).min(2).max(10).describe("List of packages to compare (2-10 packages)")
+};
+function createComparePackagesTool(pkgseerService) {
+  return {
+    name: "compare_packages",
+    description: "Compares multiple packages across metadata, quality, and security dimensions",
+    schema: argsSchema,
+    handler: async ({ packages }, _extra) => {
+      return withErrorHandling("compare packages", async () => {
+        const input2 = packages.map((pkg) => ({
+          registry: toGraphQLRegistry2(pkg.registry),
+          name: pkg.name,
+          version: pkg.version
+        }));
+        const result = await pkgseerService.comparePackages(input2);
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.comparePackages) {
+          return errorResult("Comparison failed: no results returned");
+        }
+        return textResult(JSON.stringify(result.data.comparePackages, null, 2));
+      });
+    }
+  };
+}
+// src/tools/fetch-package-doc.ts
+import { z as z4 } from "zod";
+var argsSchema2 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to fetch documentation for"),
+  page_id: z4.string().max(500).describe("Documentation page identifier (from list_package_docs)"),
+  version: schemas.version
+};
+function createFetchPackageDocTool(pkgseerService) {
+  return {
+    name: "fetch_package_doc",
+    description: "Fetches the full content of a specific documentation page. Returns page title, content (markdown/HTML), breadcrumbs, and source attribution. Use list_package_docs first to get available page IDs.",
+    schema: argsSchema2,
+    handler: async ({ registry, package_name, page_id, version: version2 }, _extra) => {
+      return withErrorHandling("fetch documentation page", async () => {
+        const result = await pkgseerService.fetchPackageDoc(toGraphQLRegistry2(registry), package_name, page_id, version2);
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.fetchPackageDoc) {
+          return errorResult(`Documentation page not found: ${page_id} for ${package_name} in ${registry}`);
+        }
+        return textResult(JSON.stringify(result.data.fetchPackageDoc, null, 2));
+      });
+    }
+  };
+}
+// src/tools/list-package-docs.ts
+var argsSchema3 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to list documentation for"),
+  version: schemas.version
+};
+function createListPackageDocsTool(pkgseerService) {
+  return {
+    name: "list_package_docs",
+    description: "Lists documentation pages for a package version. Returns page titles, slugs, and metadata. Use this to discover available documentation before fetching specific pages.",
+    schema: argsSchema3,
+    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 graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.listPackageDocs) {
+          return notFoundError(package_name, registry);
+        }
+        return textResult(JSON.stringify(result.data.listPackageDocs, null, 2));
+      });
+    }
+  };
+}
+// src/tools/package-dependencies.ts
+import { z as z5 } from "zod";
+var argsSchema4 = {
+  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)")
+};
+function createPackageDependenciesTool(pkgseerService) {
+  return {
+    name: "package_dependencies",
+    description: "Retrieves direct and transitive dependencies for a package version",
+    schema: argsSchema4,
+    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 graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.packageDependencies) {
+          return notFoundError(package_name, registry);
+        }
+        return textResult(JSON.stringify(result.data.packageDependencies, null, 2));
+      });
+    }
+  };
+}
+// src/tools/package-quality.ts
+var argsSchema5 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to analyze"),
+  version: schemas.version
+};
+function createPackageQualityTool(pkgseerService) {
+  return {
+    name: "package_quality",
+    description: "Retrieves quality score and rule-level breakdown for a package",
+    schema: argsSchema5,
+    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 graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.packageQuality) {
+          return notFoundError(package_name, registry);
+        }
+        return textResult(JSON.stringify(result.data.packageQuality, null, 2));
+      });
+    }
+  };
+}
+// src/tools/package-summary.ts
+var argsSchema6 = {
+  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,
+    handler: async ({ registry, package_name }, _extra) => {
+      return withErrorHandling("fetch package summary", async () => {
+        const result = await pkgseerService.getPackageSummary(toGraphQLRegistry2(registry), package_name);
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.packageSummary) {
+          return notFoundError(package_name, registry);
+        }
+        return textResult(JSON.stringify(result.data.packageSummary, null, 2));
+      });
+    }
+  };
+}
+// src/tools/package-vulnerabilities.ts
+var argsSchema7 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
+  version: schemas.version
+};
+function createPackageVulnerabilitiesTool(pkgseerService) {
+  return {
+    name: "package_vulnerabilities",
+    description: "Retrieves vulnerability details for a package, including affected version ranges and upgrade guidance",
+    schema: argsSchema7,
+    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 graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.packageVulnerabilities) {
+          return notFoundError(package_name, registry);
+        }
+        return textResult(JSON.stringify(result.data.packageVulnerabilities, null, 2));
+      });
+    }
+  };
+}
+// src/tools/search-package-docs.ts
+import { z as z6 } from "zod";
+var argsSchema8 = {
+  registry: schemas.registry,
+  package_name: schemas.packageName.describe("Name of the package to search documentation for"),
+  keywords: z6.array(z6.string()).optional().describe("Keywords to search for; combined into a single query"),
+  query: z6.string().max(500).optional().describe("Freeform search query (alternative to keywords)"),
+  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
+};
+function createSearchPackageDocsTool(pkgseerService) {
+  return {
+    name: "search_package_docs",
+    description: "Searches package documentation with keyword or freeform query support. Returns ranked results with relevance scores. Use include_snippets=true to get content excerpts showing match context.",
+    schema: argsSchema8,
+    handler: async ({
+      registry,
+      package_name,
+      keywords,
+      query,
+      include_snippets,
+      limit,
+      version: version2
+    }, _extra) => {
+      return withErrorHandling("search package documentation", async () => {
+        if (!keywords?.length && !query) {
+          return errorResult("Either keywords or query must be provided for search");
+        }
+        const result = await pkgseerService.searchPackageDocs(toGraphQLRegistry2(registry), package_name, {
+          keywords,
+          query,
+          includeSnippets: include_snippets,
+          limit,
+          version: version2
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.searchPackageDocs) {
+          return errorResult(`No documentation found for ${package_name} in ${registry}`);
+        }
+        return textResult(JSON.stringify(result.data.searchPackageDocs, null, 2));
+      });
+    }
+  };
+}
+// 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."),
+  keywords: z7.array(z7.string()).optional().describe("Keywords to search for; combined into a single query"),
+  query: z7.string().max(500).optional().describe("Freeform search query (alternative to keywords)"),
+  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")
+};
+function createSearchProjectDocsTool(deps) {
+  const { pkgseerService, config } = deps;
+  return {
+    name: "search_project_docs",
+    description: "Searches documentation across all dependencies in a PkgSeer project. Returns ranked results from multiple packages. Uses project from pkgseer.yml config by default.",
+    schema: argsSchema9,
+    handler: async ({ project, keywords, query, include_snippets, limit }, _extra) => {
+      return withErrorHandling("search project documentation", async () => {
+        const resolvedProject = project ?? 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.");
+        }
+        if (!keywords?.length && !query) {
+          return errorResult("Either keywords or query must be provided for search");
+        }
+        const result = await pkgseerService.searchProjectDocs(resolvedProject, {
+          keywords,
+          query,
+          includeSnippets: include_snippets,
+          limit
+        });
+        const graphqlError = handleGraphQLErrors(result.errors);
+        if (graphqlError)
+          return graphqlError;
+        if (!result.data.searchProjectDocs) {
+          return errorResult(`Project not found: ${resolvedProject}`);
+        }
+        return textResult(JSON.stringify(result.data.searchProjectDocs, null, 2));
+      });
+    }
+  };
+}
+// src/commands/mcp.ts
+var TOOL_FACTORIES = {
+  package_summary: ({ pkgseerService }) => createPackageSummaryTool(pkgseerService),
+  package_vulnerabilities: ({ pkgseerService }) => createPackageVulnerabilitiesTool(pkgseerService),
+  package_dependencies: ({ pkgseerService }) => createPackageDependenciesTool(pkgseerService),
+  package_quality: ({ pkgseerService }) => createPackageQualityTool(pkgseerService),
+  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 })
+};
+var PUBLIC_READ_TOOLS = [
+  "package_summary",
+  "package_vulnerabilities",
+  "package_dependencies",
+  "package_quality",
+  "compare_packages",
+  "list_package_docs",
+  "fetch_package_doc",
+  "search_package_docs"
+];
+var PROJECT_READ_TOOLS = ["search_project_docs"];
+var ALL_TOOLS = [...PUBLIC_READ_TOOLS, ...PROJECT_READ_TOOLS];
+function createMcpServer(deps) {
+  const { pkgseerService, config } = deps;
+  const server = new McpServer({
+    name: "pkgseer",
+    version: "0.1.0"
+  });
+  const enabledToolNames = config.enabled_tools ?? ALL_TOOLS;
+  const toolsToRegister = enabledToolNames.filter((name) => ALL_TOOLS.includes(name));
+  for (const toolName of toolsToRegister) {
+    const factory = TOOL_FACTORIES[toolName];
+    const tool = factory({ pkgseerService, config });
+    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.handler);
+  }
+  return server;
+}
+function requireAuth(deps) {
+  if (deps.hasValidToken) {
+    return;
+  }
+  console.log(`Authentication required to start MCP server.
+`);
+  if (deps.baseUrl !== "https://pkgseer.dev") {
+    console.log(`  Environment: ${deps.baseUrl}`);
+    console.log(`  You're using a custom environment.
+`);
+  }
+  console.log("To authenticate:");
+  console.log(`  pkgseer login
+`);
+  console.log("Or set PKGSEER_API_TOKEN environment variable.");
+  process.exit(1);
+}
+async function startMcpServer(deps) {
+  requireAuth(deps);
+  const server = createMcpServer(deps);
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+}
+function registerMcpCommand(program) {
+  program.command("mcp").summary("Start MCP server for AI assistants").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
+
+This allows AI assistants like Claude, Cursor, and others to query package
+information directly. Add this to your assistant's MCP configuration:
+
+  "pkgseer": {
+    "command": "pkgseer",
+    "args": ["mcp"]
+  }
+
+Available tools: package_summary, package_vulnerabilities,
+package_dependencies, package_quality, compare_packages,
+list_package_docs, fetch_package_doc, search_package_docs,
+search_project_docs`).action(async () => {
     const deps = await createContainer();
-    await logoutAction(deps);
+    await startMcpServer(deps);
   });
 }
 
-// src/commands/mcp.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// src/commands/pkg/compare.ts
+function parsePackageSpec(spec) {
+  let registry = "npm";
+  let rest = spec;
+  if (spec.includes(":")) {
+    const colonIndex = spec.indexOf(":");
+    const potentialRegistry = spec.slice(0, colonIndex).toLowerCase();
+    if (["npm", "pypi", "hex"].includes(potentialRegistry)) {
+      registry = potentialRegistry;
+      rest = spec.slice(colonIndex + 1);
+    }
+  }
+  const atIndex = rest.lastIndexOf("@");
+  if (atIndex > 0) {
+    return {
+      registry,
+      name: rest.slice(0, atIndex),
+      version: rest.slice(atIndex + 1)
+    };
+  }
+  return { registry, name: rest };
+}
+function formatPackageComparison(comparison) {
+  const lines = [];
+  lines.push("\uD83D\uDCCA Package Comparison");
+  lines.push("");
+  if (!comparison.packages || comparison.packages.length === 0) {
+    lines.push("No packages to compare.");
+    return lines.join(`
+`);
+  }
+  const packages = comparison.packages.filter((p) => p != null);
+  const maxNameLen = Math.max(...packages.map((p) => `${p.packageName}@${p.version}`.length));
+  const header = "Package".padEnd(maxNameLen + 2);
+  lines.push(`  ${header}  Quality     Downloads/mo  Vulns`);
+  lines.push(`  ${"─".repeat(maxNameLen + 2)}  ${"─".repeat(10)}  ${"─".repeat(12)}  ${"─".repeat(5)}`);
+  for (const pkg of packages) {
+    const name = `${pkg.packageName}@${pkg.version}`.padEnd(maxNameLen + 2);
+    const scoreValue = pkg.quality?.score;
+    const quality = scoreValue != null ? `${Math.round(scoreValue > 1 ? scoreValue : scoreValue * 100)}%`.padEnd(10) : "N/A".padEnd(10);
+    const downloads = pkg.downloadsLastMonth ? formatNumber(pkg.downloadsLastMonth).padEnd(12) : "N/A".padEnd(12);
+    const vulns = pkg.vulnerabilityCount != null ? pkg.vulnerabilityCount === 0 ? "✅ 0" : `⚠️  ${pkg.vulnerabilityCount}` : "N/A";
+    lines.push(`  ${name}  ${quality}  ${downloads}  ${vulns}`);
+  }
+  return lines.join(`
+`);
+}
+async function pkgCompareAction(packages, options, deps) {
+  const { pkgseerService } = deps;
+  if (packages.length < 2) {
+    outputError("At least 2 packages required for comparison", options.json ?? false);
+    return;
+  }
+  if (packages.length > 10) {
+    outputError("Maximum 10 packages can be compared at once", options.json ?? false);
+    return;
+  }
+  const input2 = packages.map((spec) => {
+    const parsed = parsePackageSpec(spec);
+    return {
+      registry: toGraphQLRegistry(parsed.registry),
+      name: parsed.name,
+      version: parsed.version
+    };
+  });
+  const result = await pkgseerService.cliComparePackages(input2);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.comparePackages) {
+    outputError("Comparison failed", options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const pkgs = result.data.comparePackages.packages?.filter((p) => p) ?? [];
+    const slim = pkgs.map((p) => ({
+      package: `${p.packageName}@${p.version}`,
+      quality: p.quality?.score,
+      downloads: p.downloadsLastMonth,
+      vulnerabilities: p.vulnerabilityCount
+    }));
+    output(slim, true);
+  } else {
+    console.log(formatPackageComparison(result.data.comparePackages));
+  }
+}
+var COMPARE_DESCRIPTION = `Compare multiple packages.
 
-// src/tools/types.ts
-function textResult(text) {
-  return {
-    content: [{ type: "text", text }]
-  };
+Compares packages across quality, security, and popularity metrics.
+Supports cross-registry comparison.
+
+Package format: [registry:]name[@version]
+  - lodash (npm, latest)
+  - pypi:requests (pypi, latest)
+  - npm:express@4.18.0 (npm, specific version)
+
+Examples:
+  pkgseer pkg compare lodash underscore ramda
+  pkgseer pkg compare npm:axios pypi:requests
+  pkgseer pkg compare express@4.18.0 express@5.0.0 --json`;
+function registerPkgCompareCommand(program) {
+  program.command("compare <packages...>").summary("Compare multiple packages").description(COMPARE_DESCRIPTION).option("--json", "Output as JSON").action(async (packages, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await pkgCompareAction(packages, options, deps);
+    });
+  });
 }
-function errorResult(message) {
-  return {
-    content: [{ type: "text", text: message }],
-    isError: true
-  };
+// src/commands/pkg/deps.ts
+function formatPackageDependencies(data) {
+  const lines = [];
+  const pkg = data.package;
+  const deps = data.dependencies;
+  if (!pkg) {
+    return "No package data available.";
+  }
+  lines.push(`\uD83D\uDCE6 ${pkg.name}@${pkg.version}`);
+  lines.push("");
+  if (deps?.summary) {
+    lines.push("Summary:");
+    lines.push(`  Direct dependencies: ${deps.summary.directCount ?? 0}`);
+    if (deps.summary.uniquePackagesCount) {
+      lines.push(`  Unique packages: ${deps.summary.uniquePackagesCount}`);
+    }
+    lines.push("");
+  }
+  if (deps?.direct && deps.direct.length > 0) {
+    lines.push(`Dependencies (${deps.direct.length}):`);
+    for (const dep of deps.direct) {
+      if (dep) {
+        const type = dep.type !== "RUNTIME" ? ` [${dep.type?.toLowerCase()}]` : "";
+        lines.push(`  ${dep.name} ${dep.versionConstraint}${type}`);
+      }
+    }
+  } else {
+    lines.push("No direct dependencies.");
+  }
+  return lines.join(`
+`);
 }
-// src/tools/shared.ts
-import { z } from "zod";
-function toGraphQLRegistry(registry) {
-  const map = {
-    npm: "NPM",
-    pypi: "PYPI",
-    hex: "HEX"
+async function pkgDepsAction(packageName, options, deps) {
+  const { pkgseerService } = deps;
+  const registry = toGraphQLRegistry(options.registry);
+  const result = await pkgseerService.cliPackageDeps(registry, packageName, options.pkgVersion, options.transitive);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.packageDependencies) {
+    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const data = result.data.packageDependencies;
+    const slim = {
+      package: `${data.package?.name}@${data.package?.version}`,
+      directCount: data.dependencies?.summary?.directCount ?? 0,
+      dependencies: data.dependencies?.direct?.filter((d) => d).map((d) => ({
+        name: d.name,
+        version: d.versionConstraint,
+        type: d.type
+      }))
+    };
+    output(slim, true);
+  } else {
+    console.log(formatPackageDependencies(result.data.packageDependencies));
+  }
+}
+var DEPS_DESCRIPTION = `Get package dependencies.
+
+Lists direct dependencies and shows version constraints and
+dependency types (runtime, dev, optional).
+
+Examples:
+  pkgseer pkg deps express
+  pkgseer pkg deps lodash --transitive
+  pkgseer pkg deps requests --registry pypi --json`;
+function registerPkgDepsCommand(program) {
+  program.command("deps <package>").summary("Get package dependencies").description(DEPS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("-t, --transitive", "Include transitive dependencies").option("--json", "Output as JSON").action(async (packageName, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await pkgDepsAction(packageName, options, deps);
+    });
+  });
+}
+// src/commands/pkg/info.ts
+function formatPackageSummary(data) {
+  const lines = [];
+  const pkg = data.package;
+  if (!pkg) {
+    return "No package data available.";
+  }
+  lines.push(`\uD83D\uDCE6 ${pkg.name}@${pkg.latestVersion}`);
+  lines.push("");
+  if (pkg.description) {
+    lines.push(pkg.description);
+    lines.push("");
+  }
+  lines.push("Package Info:");
+  lines.push(keyValueTable([
+    ["Registry", pkg.registry],
+    ["Version", pkg.latestVersion],
+    ["License", pkg.license]
+  ]));
+  lines.push("");
+  if (pkg.homepage || pkg.repositoryUrl) {
+    lines.push("Links:");
+    const links = [];
+    if (pkg.homepage)
+      links.push(["Homepage", pkg.homepage]);
+    if (pkg.repositoryUrl)
+      links.push(["Repository", pkg.repositoryUrl]);
+    lines.push(keyValueTable(links));
+    lines.push("");
+  }
+  const vulnCount = data.security?.vulnerabilityCount ?? 0;
+  if (vulnCount > 0) {
+    lines.push(`⚠️  Security: ${vulnCount} vulnerabilities`);
+    lines.push("");
+  }
+  if (data.quickstart?.installCommand) {
+    lines.push("Quick Start:");
+    lines.push(`  ${data.quickstart.installCommand}`);
+  }
+  return lines.join(`
+`);
+}
+async function pkgInfoAction(packageName, options, deps) {
+  const { pkgseerService } = deps;
+  const registry = toGraphQLRegistry(options.registry);
+  const result = await pkgseerService.cliPackageInfo(registry, packageName);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.packageSummary) {
+    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const data = result.data.packageSummary;
+    const pkg = data.package;
+    const slim = {
+      name: pkg?.name,
+      version: pkg?.latestVersion,
+      description: pkg?.description,
+      license: pkg?.license,
+      install: data.quickstart?.installCommand,
+      vulnerabilities: data.security?.vulnerabilityCount ?? 0
+    };
+    output(slim, true);
+  } else {
+    console.log(formatPackageSummary(result.data.packageSummary));
+  }
+}
+var INFO_DESCRIPTION = `Get package summary and metadata.
+
+Displays comprehensive information about a package including:
+- Basic metadata (version, license, description)
+- Download statistics
+- Security advisories
+- Quick start instructions
+
+Examples:
+  pkgseer pkg info lodash
+  pkgseer pkg info requests --registry pypi
+  pkgseer pkg info phoenix --registry hex --json`;
+function registerPkgInfoCommand(program) {
+  program.command("info <package>").summary("Get package summary and metadata").description(INFO_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("--json", "Output as JSON").action(async (packageName, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await pkgInfoAction(packageName, options, deps);
+    });
+  });
+}
+// src/commands/pkg/quality.ts
+function formatPackageQuality(data) {
+  const lines = [];
+  const quality = data.quality;
+  if (!quality) {
+    return "No quality data available.";
+  }
+  lines.push(`\uD83D\uDCCA Quality Score: ${formatScore(quality.overallScore)} (Grade: ${quality.grade})`);
+  lines.push("");
+  if (quality.categories && quality.categories.length > 0) {
+    lines.push("Category Breakdown:");
+    for (const category of quality.categories) {
+      if (category) {
+        const name = (category.category || "Unknown").padEnd(20);
+        lines.push(`  ${name} ${formatScore(category.score)}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+async function pkgQualityAction(packageName, options, deps) {
+  const { pkgseerService } = deps;
+  const registry = toGraphQLRegistry(options.registry);
+  const result = await pkgseerService.cliPackageQuality(registry, packageName, options.pkgVersion);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.packageQuality) {
+    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const quality = result.data.packageQuality.quality;
+    const slim = {
+      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) => ({
+        name: c.category,
+        score: c.score
+      }))
+    };
+    output(slim, true);
+  } else {
+    console.log(formatPackageQuality(result.data.packageQuality));
+  }
+}
+var QUALITY_DESCRIPTION = `Get package quality score and breakdown.
+
+Analyzes package quality across multiple dimensions:
+- Maintenance and activity
+- Documentation coverage
+- Security practices
+- Community engagement
+
+Examples:
+  pkgseer pkg quality lodash
+  pkgseer pkg quality express -v 4.18.0
+  pkgseer pkg quality requests --registry pypi --json`;
+function registerPkgQualityCommand(program) {
+  program.command("quality <package>").summary("Get package quality score").description(QUALITY_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await pkgQualityAction(packageName, options, deps);
+    });
+  });
+}
+// src/commands/pkg/vulns.ts
+function getSeverityLabel(score) {
+  if (score == null)
+    return "UNKNOWN";
+  if (score >= 9)
+    return "CRITICAL";
+  if (score >= 7)
+    return "HIGH";
+  if (score >= 4)
+    return "MEDIUM";
+  return "LOW";
+}
+function formatPackageVulnerabilities(data) {
+  const lines = [];
+  const pkg = data.package;
+  const security = data.security;
+  if (!pkg) {
+    return "No package data available.";
+  }
+  lines.push(`\uD83D\uDD12 Security Report: ${pkg.name}@${pkg.version}`);
+  lines.push("");
+  if (!security?.vulnerabilities || security.vulnerabilities.length === 0) {
+    lines.push("✅ No known vulnerabilities!");
+    return lines.join(`
+`);
+  }
+  const bySeverity = security.vulnerabilities.reduce((acc, v) => {
+    if (v) {
+      const label = getSeverityLabel(v.severityScore);
+      acc[label] = (acc[label] || 0) + 1;
+    }
+    return acc;
+  }, {});
+  lines.push(`⚠️  Found ${security.vulnerabilityCount} vulnerabilities:`);
+  for (const [severity, count] of Object.entries(bySeverity)) {
+    lines.push(`  ${formatSeverity(severity)}: ${count}`);
+  }
+  lines.push("");
+  lines.push("Details:");
+  for (const vuln of security.vulnerabilities) {
+    if (!vuln)
+      continue;
+    lines.push("");
+    lines.push(`  ${formatSeverity(getSeverityLabel(vuln.severityScore))}`);
+    lines.push(`  ${vuln.summary || vuln.osvId}`);
+    lines.push(`  ID: ${vuln.osvId}`);
+    if (vuln.fixedInVersions && vuln.fixedInVersions.length > 0) {
+      lines.push(`  Fixed in: ${vuln.fixedInVersions.join(", ")}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+async function pkgVulnsAction(packageName, options, deps) {
+  const { pkgseerService } = deps;
+  const registry = toGraphQLRegistry(options.registry);
+  const result = await pkgseerService.cliPackageVulns(registry, packageName, options.pkgVersion);
+  handleErrors(result.errors, options.json ?? false);
+  if (!result.data.packageVulnerabilities) {
+    outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
+    return;
+  }
+  if (options.json) {
+    const data = result.data.packageVulnerabilities;
+    const vulns = data.security?.vulnerabilities ?? [];
+    const slim = {
+      package: `${data.package?.name}@${data.package?.version}`,
+      count: data.security?.vulnerabilityCount ?? 0,
+      vulnerabilities: vulns.filter((v) => v).map((v) => ({
+        id: v.osvId,
+        severity: v.severityScore,
+        summary: v.summary,
+        fixed: v.fixedInVersions
+      }))
+    };
+    output(slim, true);
+  } else {
+    console.log(formatPackageVulnerabilities(result.data.packageVulnerabilities));
+  }
+}
+var VULNS_DESCRIPTION = `Check package for security vulnerabilities.
+
+Scans for known security vulnerabilities and provides:
+- Severity ratings (critical, high, medium, low)
+- CVE identifiers
+- Affected version ranges
+- Upgrade recommendations
+
+Examples:
+  pkgseer pkg vulns lodash
+  pkgseer pkg vulns express -v 4.17.0
+  pkgseer pkg vulns requests --registry pypi --json`;
+function registerPkgVulnsCommand(program) {
+  program.command("vulns <package>").summary("Check for security vulnerabilities").description(VULNS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+    await withCliErrorHandling(options.json ?? false, async () => {
+      const deps = await createContainer();
+      await pkgVulnsAction(packageName, options, deps);
+    });
+  });
+}
+// src/services/gitignore-parser.ts
+function parseGitIgnoreLine(line) {
+  const trimmed = line.trimEnd();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return null;
+  }
+  const isNegation = trimmed.startsWith("!");
+  const pattern = isNegation ? trimmed.slice(1) : trimmed;
+  const isRootOnly = pattern.startsWith("/");
+  const patternWithoutRoot = isRootOnly ? pattern.slice(1) : pattern;
+  const isDirectory = patternWithoutRoot.endsWith("/");
+  const cleanPattern = isDirectory ? patternWithoutRoot.slice(0, -1) : patternWithoutRoot;
+  return {
+    pattern: cleanPattern,
+    isNegation,
+    isDirectory,
+    isRootOnly
   };
-  return map[registry.toLowerCase()] || "NPM";
 }
-var schemas = {
-  registry: z.enum(["npm", "pypi", "hex"]).describe("Package registry (npm, pypi, or hex)"),
-  packageName: z.string().max(255).describe("Name of the package"),
-  version: z.string().max(100).optional().describe("Specific version (defaults to latest)")
-};
-function handleGraphQLErrors(errors) {
-  if (errors && errors.length > 0) {
-    return errorResult(`Error: ${errors.map((e) => e.message).join(", ")}`);
+function matchesPattern(path, pattern) {
+  const { pattern: p, isDirectory, isRootOnly } = pattern;
+  let regexStr = p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "___DOUBLE_STAR___").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/___DOUBLE_STAR___/g, ".*");
+  if (isRootOnly) {
+    if (isDirectory) {
+      regexStr = `^${regexStr}(/|$)`;
+    } else {
+      regexStr = `^${regexStr}(/|$)`;
+    }
+  } else {
+    if (isDirectory) {
+      regexStr = `(^|/)${regexStr}(/|$)`;
+    } else {
+      regexStr = `(^|/)${regexStr}(/|$)`;
+    }
   }
-  return null;
+  const regex = new RegExp(regexStr);
+  return regex.test(path);
 }
-async function withErrorHandling(operation, fn) {
+async function parseGitIgnore(gitignorePath, fs) {
   try {
-    return await fn();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    return errorResult(`Failed to ${operation}: ${message}`);
+    const content = await fs.readFile(gitignorePath);
+    const lines = content.split(`
+`);
+    const patterns = [];
+    for (const line of lines) {
+      const pattern = parseGitIgnoreLine(line);
+      if (pattern) {
+        patterns.push(pattern);
+      }
+    }
+    return patterns.length > 0 ? patterns : null;
+  } catch {
+    return null;
   }
 }
-function notFoundError(packageName, registry) {
-  return errorResult(`Package not found: ${packageName} in ${registry}`);
+function shouldIgnorePath(relativePath, patterns) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  let ignored = false;
+  for (const pattern of patterns) {
+    if (matchesPattern(normalized, pattern)) {
+      if (pattern.isNegation) {
+        ignored = false;
+      } else {
+        ignored = true;
+      }
+    }
+  }
+  return ignored;
 }
-// src/tools/package-summary.ts
-var argsSchema = {
-  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: argsSchema,
-    handler: async ({ registry, package_name }, _extra) => {
-      return withErrorHandling("fetch package summary", async () => {
-        const result = await pkgseerService.getPackageSummary(toGraphQLRegistry(registry), package_name);
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data.packageSummary) {
-          return notFoundError(package_name, registry);
+function shouldIgnoreDirectory(relativeDirPath, patterns) {
+  const normalized = relativeDirPath.replace(/\\/g, "/").replace(/\/$/, "") + "/";
+  return shouldIgnorePath(normalized, patterns);
+}
+
+// src/services/manifest-detector.ts
+var DEFAULT_EXCLUDED_DIRS = [
+  "node_modules",
+  "vendor",
+  ".git",
+  "dist",
+  "build",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".next"
+];
+var MANIFEST_TYPES = [
+  {
+    type: "npm",
+    filenames: [
+      "package.json",
+      "package-lock.json",
+      "yarn.lock",
+      "pnpm-lock.yaml"
+    ]
+  },
+  {
+    type: "pypi",
+    filenames: ["requirements.txt", "pyproject.toml", "Pipfile", "poetry.lock"]
+  },
+  {
+    type: "hex",
+    filenames: ["mix.exs", "mix.lock"]
+  }
+];
+function suggestLabel(relativePath) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  const parts = normalized.split("/").filter((p) => p.length > 0);
+  if (parts.length === 1) {
+    return "root";
+  }
+  return parts[parts.length - 2];
+}
+async function scanDirectoryRecursive(directory, fs, rootDir, options, currentDepth = 0, gitignorePatterns = null) {
+  const detected = [];
+  if (currentDepth > options.maxDepth) {
+    return detected;
+  }
+  const relativeDirPath = directory === rootDir ? "." : directory.replace(rootDir, "").replace(/^[/\\]/, "");
+  const baseName = directory.split(/[/\\]/).pop() ?? "";
+  if (options.excludedDirs.includes(baseName)) {
+    return detected;
+  }
+  if (gitignorePatterns && shouldIgnoreDirectory(relativeDirPath, gitignorePatterns)) {
+    return detected;
+  }
+  for (const manifestType of MANIFEST_TYPES) {
+    for (const filename of manifestType.filenames) {
+      const filePath = fs.joinPath(directory, filename);
+      const exists = await fs.exists(filePath);
+      if (exists) {
+        const relativePath = directory === rootDir ? filename : fs.joinPath(directory.replace(rootDir, "").replace(/^[/\\]/, ""), filename);
+        if (gitignorePatterns && shouldIgnorePath(relativePath, gitignorePatterns)) {
+          continue;
         }
-        return textResult(JSON.stringify(result.data.packageSummary, null, 2));
-      });
+        detected.push({
+          filename,
+          relativePath,
+          absolutePath: filePath,
+          type: manifestType.type,
+          suggestedLabel: suggestLabel(relativePath)
+        });
+      }
+    }
+  }
+  try {
+    const entries = await fs.readdir(directory);
+    for (const entry of entries) {
+      const entryPath = fs.joinPath(directory, entry);
+      const isDir = await fs.isDirectory(entryPath);
+      if (isDir && !options.excludedDirs.includes(entry)) {
+        const subRelativePath = fs.joinPath(relativeDirPath, entry);
+        if (!gitignorePatterns || !shouldIgnoreDirectory(subRelativePath, gitignorePatterns)) {
+          const subDetected = await scanDirectoryRecursive(entryPath, fs, rootDir, options, currentDepth + 1, gitignorePatterns);
+          detected.push(...subDetected);
+        }
+      }
     }
+  } catch {}
+  return detected;
+}
+async function scanForManifests(directory, fs, options) {
+  const opts = {
+    maxDepth: options?.maxDepth ?? 3,
+    excludedDirs: options?.excludedDirs ?? DEFAULT_EXCLUDED_DIRS
   };
+  const gitignorePath = fs.joinPath(directory, ".gitignore");
+  const gitignorePatterns = await parseGitIgnore(gitignorePath, fs);
+  return scanDirectoryRecursive(directory, fs, directory, opts, 0, gitignorePatterns);
 }
-// src/tools/package-vulnerabilities.ts
-var argsSchema2 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to inspect for vulnerabilities"),
-  version: schemas.version
-};
-function createPackageVulnerabilitiesTool(pkgseerService) {
-  return {
-    name: "package_vulnerabilities",
-    description: "Retrieves vulnerability details for a package, including affected version ranges and upgrade guidance",
-    schema: argsSchema2,
-    handler: async ({ registry, package_name, version: version2 }, _extra) => {
-      return withErrorHandling("fetch package vulnerabilities", async () => {
-        const result = await pkgseerService.getPackageVulnerabilities(toGraphQLRegistry(registry), package_name, version2);
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data.packageVulnerabilities) {
-          return notFoundError(package_name, registry);
-        }
-        return textResult(JSON.stringify(result.data.packageVulnerabilities, null, 2));
+function filterRedundantPackageJson(manifests) {
+  const dirToManifests = new Map;
+  for (const manifest of manifests) {
+    const dir = manifest.relativePath.split(/[/\\]/).slice(0, -1).join("/") || ".";
+    if (!dirToManifests.has(dir)) {
+      dirToManifests.set(dir, []);
+    }
+    dirToManifests.get(dir).push(manifest);
+  }
+  const filtered = [];
+  for (const [dir, dirManifests] of dirToManifests.entries()) {
+    const hasLockFile = dirManifests.some((m) => m.filename === "package-lock.json");
+    const hasPackageJson = dirManifests.some((m) => m.filename === "package.json");
+    for (const manifest of dirManifests) {
+      if (manifest.filename === "package.json" && hasLockFile) {
+        continue;
+      }
+      filtered.push(manifest);
+    }
+  }
+  return filtered;
+}
+async function detectAndGroupManifests(directory, fs, options) {
+  const manifests = await scanForManifests(directory, fs, options);
+  const filteredManifests = filterRedundantPackageJson(manifests);
+  const groupsMap = new Map;
+  for (const manifest of filteredManifests) {
+    const existing = groupsMap.get(manifest.suggestedLabel) ?? [];
+    existing.push(manifest);
+    groupsMap.set(manifest.suggestedLabel, existing);
+  }
+  const groups = [];
+  for (const [label, manifests2] of groupsMap.entries()) {
+    const ecosystems = new Set(manifests2.map((m) => m.type));
+    if (ecosystems.size > 1) {
+      const ecosystemGroups = new Map;
+      for (const manifest of manifests2) {
+        const ecosystemLabel = `${label}-${manifest.type}`;
+        const existing = ecosystemGroups.get(ecosystemLabel) ?? [];
+        existing.push(manifest);
+        ecosystemGroups.set(ecosystemLabel, existing);
+      }
+      for (const [
+        ecosystemLabel,
+        ecosystemManifests
+      ] of ecosystemGroups.entries()) {
+        groups.push({ label: ecosystemLabel, manifests: ecosystemManifests });
+      }
+    } else {
+      groups.push({ label, manifests: manifests2 });
+    }
+  }
+  groups.sort((a, b) => {
+    if (a.label.startsWith("root")) {
+      if (b.label.startsWith("root")) {
+        return a.label.localeCompare(b.label);
+      }
+      return -1;
+    }
+    if (b.label.startsWith("root")) {
+      return 1;
+    }
+    return a.label.localeCompare(b.label);
+  });
+  return groups;
+}
+
+// src/commands/project/detect.ts
+function matchManifestsWithConfig(detectedGroups, existingManifests) {
+  const fileToConfig = new Map;
+  for (const group of existingManifests) {
+    for (const file of group.files) {
+      fileToConfig.set(file, {
+        label: group.label,
+        allow_mix_deps: group.allow_mix_deps
+      });
+    }
+  }
+  const labelToFiles = new Map;
+  const labelToConfig = new Map;
+  for (const detectedGroup of detectedGroups) {
+    for (const manifest of detectedGroup.manifests) {
+      const existingConfig = fileToConfig.get(manifest.relativePath);
+      let label;
+      const hasEcosystemSuffix = detectedGroup.label.endsWith("-npm") || detectedGroup.label.endsWith("-hex") || detectedGroup.label.endsWith("-pypi");
+      if (hasEcosystemSuffix) {
+        label = detectedGroup.label;
+      } else {
+        label = existingConfig?.label ?? detectedGroup.label;
+      }
+      const allowMixDeps = existingConfig?.allow_mix_deps;
+      if (!labelToConfig.has(label)) {
+        labelToConfig.set(label, {
+          files: new Set,
+          allow_mix_deps: allowMixDeps
+        });
+      }
+      const config = labelToConfig.get(label);
+      config.files.add(manifest.relativePath);
+      if (allowMixDeps) {
+        config.allow_mix_deps = true;
+      }
+    }
+  }
+  const result = [];
+  for (const [label, config] of labelToConfig.entries()) {
+    const fileArray = Array.from(config.files);
+    const hasNewFiles = fileArray.some((file) => !fileToConfig.has(file));
+    const hasChangedLabels = fileArray.some((file) => {
+      const oldConfig = fileToConfig.get(file);
+      return oldConfig !== undefined && oldConfig.label !== label;
+    });
+    result.push({
+      label,
+      files: fileArray.sort(),
+      isNew: hasNewFiles,
+      changedLabel: hasChangedLabels ? label : undefined,
+      allow_mix_deps: config.allow_mix_deps
+    });
+  }
+  return result.sort((a, b) => {
+    if (a.label.startsWith("root")) {
+      if (b.label.startsWith("root")) {
+        return a.label.localeCompare(b.label);
+      }
+      return -1;
+    }
+    if (b.label.startsWith("root")) {
+      return 1;
+    }
+    return a.label.localeCompare(b.label);
+  });
+}
+async function projectDetectAction(options, deps) {
+  const { configService, fileSystemService, promptService, shellService } = deps;
+  const projectConfig = await configService.loadProjectConfig();
+  if (!projectConfig?.config.project) {
+    console.error(`✗ No project is configured in pkgseer.yml`);
+    console.log(`
+  To get started, run: pkgseer project init`);
+    console.log(`  This will create a project and detect your manifest files.`);
+    process.exit(1);
+  }
+  const projectName = projectConfig.config.project;
+  const existingManifests = projectConfig.config.manifests ?? [];
+  console.log(`Scanning for manifest files in project "${projectName}"...
+`);
+  const cwd = fileSystemService.getCwd();
+  const detectedGroups = await detectAndGroupManifests(cwd, fileSystemService, {
+    maxDepth: options.maxDepth ?? 3
+  });
+  if (detectedGroups.length === 0) {
+    console.log("No manifest files were found in the current directory.");
+    if (existingManifests.length > 0) {
+      console.log(`
+  Your existing configuration in pkgseer.yml will remain unchanged.`);
+      console.log(`  Tip: Make sure you're running this command from the project root directory.`);
+    } else {
+      console.log(`
+  Tip: Manifest files like package.json, requirements.txt, or pyproject.toml should be in the current directory or subdirectories.`);
+    }
+    return;
+  }
+  const suggestedManifests = matchManifestsWithConfig(detectedGroups, existingManifests);
+  console.log("Current configuration in pkgseer.yml:");
+  if (existingManifests.length === 0) {
+    console.log("  (no manifests configured yet)");
+  } else {
+    for (const group of existingManifests) {
+      console.log(`  Label: ${group.label}`);
+      for (const file of group.files) {
+        console.log(`    ${file}`);
+      }
+    }
+  }
+  console.log(`
+Suggested configuration:`);
+  for (const group of suggestedManifests) {
+    const markers = [];
+    if (group.isNew)
+      markers.push("new");
+    if (group.changedLabel)
+      markers.push("label changed");
+    const markerStr = markers.length > 0 ? ` (${markers.join(", ")})` : "";
+    console.log(`  Label: ${group.label}${markerStr}`);
+    for (const file of group.files) {
+      const wasInConfig = existingManifests.some((g) => g.files.includes(file));
+      const prefix = wasInConfig ? "    " : "  + ";
+      console.log(`${prefix}${file}`);
+    }
+  }
+  const hasHexManifests = detectedGroups.some((group) => group.manifests.some((m) => m.type === "hex"));
+  const hasHexInSuggested = suggestedManifests.some((g) => g.files.some((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock")));
+  let allowMixDeps = false;
+  if (hasHexInSuggested) {
+    const existingHasMixDeps = existingManifests.some((g) => g.allow_mix_deps === true);
+    if (!existingHasMixDeps) {
+      console.log(`
+  Note: Elixir/Hex manifest files (mix.exs, mix.lock) are Elixir code and cannot be directly uploaded.`);
+      console.log(`  Instead, we need to run "mix deps --all" and "mix deps.tree" to generate dependency information.`);
+      allowMixDeps = await promptService.confirm(`
+  Allow running "mix deps --all" and "mix deps.tree" for hex manifests?`, true);
+    } else {
+      allowMixDeps = true;
+    }
+  }
+  const finalManifests = suggestedManifests.map((g) => {
+    const hasHexInGroup = g.files.some((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock"));
+    return {
+      label: g.label,
+      files: g.files,
+      isNew: g.isNew,
+      changedLabel: g.changedLabel,
+      ...hasHexInGroup && allowMixDeps ? { allow_mix_deps: true } : {},
+      ...g.allow_mix_deps !== undefined ? { allow_mix_deps: g.allow_mix_deps } : {}
+    };
+  });
+  const hasChanges = finalManifests.length !== existingManifests.length || finalManifests.some((g) => g.isNew || g.changedLabel) || existingManifests.some((existing) => {
+    const suggested = finalManifests.find((s) => s.label === existing.label);
+    if (!suggested)
+      return true;
+    const existingFiles = new Set(existing.files);
+    const suggestedFiles = new Set(suggested.files);
+    return existingFiles.size !== suggestedFiles.size || !Array.from(existingFiles).every((f) => suggestedFiles.has(f));
+  }) || finalManifests.some((g) => {
+    const existing = existingManifests.find((e) => e.label === g.label);
+    return existing?.allow_mix_deps !== g.allow_mix_deps;
+  });
+  if (!hasChanges) {
+    console.log(`
+✓ Your configuration is already up to date!`);
+    console.log(`
+  All detected manifest files match your current pkgseer.yml configuration.`);
+    return;
+  }
+  if (options.update) {
+    await configService.writeProjectConfig({
+      project: projectName,
+      manifests: finalManifests.map((g) => ({
+        label: g.label,
+        files: g.files,
+        ...g.allow_mix_deps ? { allow_mix_deps: g.allow_mix_deps } : {}
+      }))
+    });
+    console.log(`
+✓ Configuration updated successfully!`);
+    console.log(`
+  Your pkgseer.yml has been updated with the detected manifest files.`);
+    console.log(`  Run 'pkgseer project upload' to upload them to your project.`);
+  } else {
+    const shouldUpdate = await promptService.confirm(`
+Would you like to update pkgseer.yml with these changes?`, false);
+    if (shouldUpdate) {
+      await configService.writeProjectConfig({
+        project: projectName,
+        manifests: finalManifests.map((g) => ({
+          label: g.label,
+          files: g.files,
+          ...g.allow_mix_deps ? { allow_mix_deps: g.allow_mix_deps } : {}
+        }))
       });
+      console.log(`
+✓ Configuration updated successfully!`);
+      console.log(`
+  Your pkgseer.yml has been updated. Run 'pkgseer project upload' to upload the manifests.`);
+    } else {
+      console.log(`
+  Configuration was not updated.`);
+      console.log(`  To apply these changes automatically, run: pkgseer project detect --update`);
+      console.log(`  Or manually edit pkgseer.yml and then run: pkgseer project upload`);
     }
-  };
+  }
 }
-// src/tools/package-dependencies.ts
-import { z as z2 } from "zod";
-var argsSchema3 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to retrieve dependencies for"),
-  version: schemas.version,
-  include_transitive: z2.boolean().optional().describe("Whether to include transitive dependency DAG"),
-  max_depth: z2.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
+var DETECT_DESCRIPTION = `Detect manifest files and update your project configuration.
+
+This command scans your project directory for manifest files (like
+package.json, requirements.txt, etc.) and compares them with your
+current pkgseer.yml configuration. It will:
+
+  • Preserve existing labels for files you've already configured
+  • Suggest new labels for newly detected files
+  • Show you what would change before updating
+
+Perfect for when you add new manifest files or reorganize your
+project structure. Run with --update to automatically apply changes.`;
+function registerProjectDetectCommand(program) {
+  program.command("detect").summary("Detect manifest files and suggest config updates").description(DETECT_DESCRIPTION).option("--max-depth <depth>", "Maximum directory depth to scan for manifests", (val) => Number.parseInt(val, 10), 3).option("--update", "Automatically update pkgseer.yml without prompting", false).action(async (options) => {
+    const deps = await createContainer();
+    await projectDetectAction({ maxDepth: options.maxDepth, update: options.update }, {
+      configService: deps.configService,
+      fileSystemService: deps.fileSystemService,
+      promptService: deps.promptService,
+      shellService: deps.shellService
+    });
+  });
+}
+// src/commands/shared-colors.ts
+var colors2 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  red: "\x1B[31m"
 };
-function createPackageDependenciesTool(pkgseerService) {
-  return {
-    name: "package_dependencies",
-    description: "Retrieves direct and transitive dependencies for a package version",
-    schema: argsSchema3,
-    handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
-      return withErrorHandling("fetch package dependencies", async () => {
-        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) {
-          return notFoundError(package_name, registry);
+function shouldUseColors2(noColor) {
+  if (noColor)
+    return false;
+  if (process.env.NO_COLOR !== undefined)
+    return false;
+  return process.stdout.isTTY ?? false;
+}
+function success(text, useColors) {
+  const checkmark = useColors ? `${colors2.green}✓${colors2.reset}` : "✓";
+  return `${checkmark} ${text}`;
+}
+function error(text, useColors) {
+  const cross = useColors ? `${colors2.red}✗${colors2.reset}` : "✗";
+  return `${cross} ${text}`;
+}
+function highlight(text, useColors) {
+  if (!useColors)
+    return text;
+  return `${colors2.bold}${colors2.cyan}${text}${colors2.reset}`;
+}
+function dim(text, useColors) {
+  if (!useColors)
+    return text;
+  return `${colors2.dim}${text}${colors2.reset}`;
+}
+
+// src/commands/project/manifest-upload-utils.ts
+async function processManifestFiles(params) {
+  const {
+    files,
+    basePath,
+    hasHexManifests,
+    allowMixDeps,
+    fileSystemService,
+    shellService
+  } = params;
+  const hexFiles = files.filter((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock"));
+  let generatedHexFiles = [];
+  if (hasHexManifests && allowMixDeps && hexFiles.length > 0) {
+    const firstHexFile = hexFiles[0];
+    if (!firstHexFile) {
+      throw new Error("No hex files found");
+    }
+    const absolutePath = fileSystemService.joinPath(basePath, firstHexFile);
+    const manifestDir = fileSystemService.getDirname(absolutePath);
+    try {
+      const [depsContent, depsTreeContent] = await Promise.all([
+        shellService.execute("mix deps --all", manifestDir),
+        shellService.execute("mix deps.tree", manifestDir)
+      ]);
+      generatedHexFiles = [
+        {
+          filename: "deps.txt",
+          path: absolutePath,
+          content: depsContent
+        },
+        {
+          filename: "deps-tree.txt",
+          path: absolutePath,
+          content: depsTreeContent
         }
-        return textResult(JSON.stringify(result.data.packageDependencies, null, 2));
-      });
+      ];
+    } catch (error2) {
+      const errorMessage = error2 instanceof Error ? error2.message : String(error2);
+      throw new Error(`Failed to generate dependencies for hex manifest: ${firstHexFile}
+` + `  Error: ${errorMessage}
+` + `  Make sure 'mix' is installed and the directory contains a valid Elixir project.`);
     }
-  };
+  }
+  const filePromises = files.map(async (relativePath) => {
+    const isHexFile = relativePath.endsWith("mix.exs") || relativePath.endsWith("mix.lock");
+    if (isHexFile) {
+      if (!allowMixDeps) {
+        return null;
+      }
+      return null;
+    }
+    const absolutePath = fileSystemService.joinPath(basePath, relativePath);
+    const exists = await fileSystemService.exists(absolutePath);
+    if (!exists) {
+      throw new Error(`File not found: ${relativePath}
+  Make sure the file exists and the path in pkgseer.yml is correct.`);
+    }
+    const content = await fileSystemService.readFile(absolutePath);
+    const filename = relativePath.split(/[/\\]/).pop() ?? relativePath;
+    return {
+      filename,
+      path: absolutePath,
+      content
+    };
+  });
+  const regularFiles = await Promise.all(filePromises);
+  const result = [];
+  let hexFilesInserted = false;
+  for (let i = 0;i < files.length; i++) {
+    const relativePath = files[i];
+    if (!relativePath) {
+      continue;
+    }
+    const isHexFile = relativePath.endsWith("mix.exs") || relativePath.endsWith("mix.lock");
+    if (isHexFile && !hexFilesInserted && generatedHexFiles.length > 0) {
+      result.push(...generatedHexFiles);
+      hexFilesInserted = true;
+    } else if (!isHexFile) {
+      const regularFile = regularFiles[i];
+      if (regularFile !== undefined) {
+        result.push(regularFile);
+      }
+    } else {
+      result.push(null);
+    }
+  }
+  return result;
 }
-// src/tools/package-quality.ts
-var argsSchema4 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to analyze"),
-  version: schemas.version
-};
-function createPackageQualityTool(pkgseerService) {
-  return {
-    name: "package_quality",
-    description: "Retrieves quality score and rule-level breakdown for a package",
-    schema: argsSchema4,
-    handler: async ({ registry, package_name, version: version2 }, _extra) => {
-      return withErrorHandling("fetch package quality", async () => {
-        const result = await pkgseerService.getPackageQuality(toGraphQLRegistry(registry), package_name, version2);
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data.packageQuality) {
-          return notFoundError(package_name, registry);
-        }
-        return textResult(JSON.stringify(result.data.packageQuality, null, 2));
-      });
+
+// src/commands/project/init.ts
+async function projectInitAction(options, deps) {
+  const {
+    projectService,
+    configService,
+    fileSystemService,
+    gitService,
+    promptService,
+    shellService,
+    authStorage,
+    baseUrl
+  } = deps;
+  const useColors = shouldUseColors2();
+  const auth = await checkProjectWriteScope(authStorage, baseUrl);
+  if (!auth) {
+    console.error(error(`Authentication required with ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope`, useColors));
+    console.log(`
+  Your current token doesn't have the required permissions for creating projects and uploading manifests.`);
+    console.log(`
+  To fix this:`);
+    console.log(`    1. Run: ${highlight(`pkgseer login --force`, useColors)}`);
+    console.log(`    2. Make sure to grant ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope during authentication`);
+    console.log(`
+  Or check your current scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+    process.exit(1);
+  }
+  const isEnvToken = auth.scopes.length === 0 && auth.tokenName === "PKGSEER_API_TOKEN";
+  if (isEnvToken) {} else if (!auth.scopes.includes(PROJECT_MANIFEST_UPLOAD_SCOPE)) {
+    console.error(error(`Token missing required scope: ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)}`, useColors));
+    console.log(`
+  To fix this:`);
+    console.log(`    1. Run: ${highlight(`pkgseer login --force`, useColors)}`);
+    console.log(`    2. Make sure to grant ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope during authentication`);
+    console.log(`
+  Or check your current scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+    process.exit(1);
+  }
+  const existingConfig = await configService.loadProjectConfig();
+  if (existingConfig?.config.project) {
+    console.error(error(`A project is already configured in pkgseer.yml: ${highlight(existingConfig.config.project, useColors)}`, useColors));
+    console.log(dim(`
+  To reinitialize, either remove pkgseer.yml or edit it manually.`, useColors));
+    console.log(dim(`  To update manifest files, use: `, useColors) + highlight(`pkgseer project detect`, useColors));
+    process.exit(1);
+  }
+  let projectName = options.name?.trim();
+  if (!projectName) {
+    const cwd2 = fileSystemService.getCwd();
+    const basename = cwd2.split(/[/\\]/).pop() ?? "project";
+    const input2 = await promptService.input(`Project name:`, basename);
+    projectName = input2.trim();
+  }
+  console.log(`
+Creating project ${highlight(projectName, useColors)}...`);
+  let createResult;
+  let projectAlreadyExists = false;
+  try {
+    createResult = await projectService.createProject({
+      name: projectName
+    });
+  } catch (createError) {
+    const errorMessage = createError instanceof Error ? createError.message : String(createError);
+    if (createError instanceof Error && (errorMessage.includes("already been taken") || errorMessage.includes("already exists"))) {
+      console.log(dim(`
+  Project ${highlight(projectName, useColors)} already exists on the server.`, useColors));
+      console.log(dim(`  This might happen if you previously ran init but didn't complete the setup.`, useColors));
+      const useExisting = await promptService.confirm(`
+  Do you want to use the existing project and continue with manifest setup?`, true);
+      if (!useExisting) {
+        console.log(dim(`
+  Exiting. Please choose a different project name or use an existing project.`, useColors));
+        process.exit(0);
+      }
+      projectAlreadyExists = true;
+      createResult = {
+        project: {
+          name: projectName,
+          defaultBranch: "main"
+        },
+        errors: null
+      };
+    } else {
+      console.error(error(`Failed to create project: ${errorMessage}`, useColors));
+      if (createError instanceof Error && (errorMessage.includes("Insufficient permissions") || errorMessage.includes("Required scopes") || errorMessage.includes(PROJECT_MANIFEST_UPLOAD_SCOPE))) {
+        console.log(`
+  Your current token doesn't have the required permissions for creating projects.`);
+        console.log(`
+  To fix this:`);
+        console.log(`    1. Run: ${highlight(`pkgseer login --force`, useColors)}`);
+        console.log(`    2. Make sure to grant ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope during authentication`);
+        console.log(`
+  Or check your current scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+      } else if (createError instanceof Error && (errorMessage.includes("alphanumeric") || errorMessage.includes("hyphens") || errorMessage.includes("underscores"))) {
+        console.log(dim(`
+  Project name requirements:`, useColors));
+        console.log(dim(`    • Must start with an alphanumeric character (a-z, A-Z, 0-9)`, useColors));
+        console.log(dim(`    • Can contain letters, numbers, hyphens (-), and underscores (_)`, useColors));
+        console.log(dim(`    • Example valid names: ${highlight(`my-project`, useColors)}, ${highlight(`project_123`, useColors)}, ${highlight(`backend`, useColors)}`, useColors));
+      }
+      process.exit(1);
     }
+  }
+  if (!createResult.project) {
+    if (createResult.errors && createResult.errors.length > 0) {
+      const firstError = createResult.errors[0];
+      console.error(error(`Failed to create project: ${firstError?.message ?? "Unknown error"}`, useColors));
+      if (firstError?.field) {
+        console.log(dim(`
+  Field: ${firstError.field}`, useColors));
+      }
+      process.exit(1);
+    }
+    console.error(error(`Failed to create project`, useColors));
+    console.log(dim(`
+  Please try again or contact support if the issue persists.`, useColors));
+    process.exit(1);
+  }
+  if (projectAlreadyExists) {
+    console.log(success(`Using existing project ${highlight(createResult.project.name, useColors)}`, useColors));
+  } else {
+    console.log(success(`Project ${highlight(createResult.project.name, useColors)} created successfully!`, useColors));
+  }
+  const maxDepth = options.maxDepth ?? 3;
+  console.log(dim(`
+Scanning for manifest files (max depth: ${maxDepth})...`, useColors));
+  const cwd = fileSystemService.getCwd();
+  const manifestGroups = await detectAndGroupManifests(cwd, fileSystemService, {
+    maxDepth
+  });
+  const configToWrite = {
+    project: projectName
   };
-}
-// src/tools/compare-packages.ts
-import { z as z3 } from "zod";
-var packageInputSchema = z3.object({
-  registry: z3.enum(["npm", "pypi", "hex"]),
-  name: z3.string().max(255),
-  version: z3.string().max(100).optional()
-});
-var argsSchema5 = {
-  packages: z3.array(packageInputSchema).min(2).max(10).describe("List of packages to compare (2-10 packages)")
-};
-function createComparePackagesTool(pkgseerService) {
-  return {
-    name: "compare_packages",
-    description: "Compares multiple packages across metadata, quality, and security dimensions",
-    schema: argsSchema5,
-    handler: async ({ packages }, _extra) => {
-      return withErrorHandling("compare packages", async () => {
-        const input = packages.map((pkg) => ({
-          registry: toGraphQLRegistry(pkg.registry),
-          name: pkg.name,
-          version: pkg.version
-        }));
-        const result = await pkgseerService.comparePackages(input);
-        const graphqlError = handleGraphQLErrors(result.errors);
-        if (graphqlError)
-          return graphqlError;
-        if (!result.data.comparePackages) {
-          return errorResult("Comparison failed: no results returned");
+  if (manifestGroups.length > 0) {
+    console.log(`
+Found ${highlight(`${manifestGroups.length}`, useColors)} manifest group${manifestGroups.length === 1 ? "" : "s"}:
+`);
+    for (const group of manifestGroups) {
+      console.log(`  Label: ${highlight(group.label, useColors)}`);
+      for (const manifest of group.manifests) {
+        console.log(`    ${highlight(manifest.relativePath, useColors)} ${dim(`(${manifest.type})`, useColors)}`);
+      }
+    }
+    const hasHexManifests = manifestGroups.some((group) => group.manifests.some((m) => m.type === "hex"));
+    let allowMixDeps = false;
+    if (hasHexManifests) {
+      console.log(dim(`
+  Note: Elixir/Hex manifest files (mix.exs, mix.lock) are Elixir code and cannot be directly uploaded.`, useColors));
+      console.log(dim(`  Instead, we need to run "mix deps --all" and "mix deps.tree" to generate dependency information.`, useColors));
+      allowMixDeps = await promptService.confirm(`
+  Allow running "mix deps --all" and "mix deps.tree" for hex manifests?`, true);
+    }
+    configToWrite.manifests = manifestGroups.map((group) => {
+      const hasHexInGroup = group.manifests.some((m) => m.type === "hex");
+      return {
+        label: group.label,
+        files: group.manifests.map((m) => m.relativePath),
+        ...hasHexInGroup && allowMixDeps ? { allow_mix_deps: true } : {}
+      };
+    });
+    const action = await promptService.select(`
+What would you like to do next?`, [
+      {
+        value: "upload",
+        name: "Save config and upload manifests now",
+        description: "Recommended: saves configuration and uploads files immediately"
+      },
+      {
+        value: "edit",
+        name: "Save config for manual editing",
+        description: "Saves configuration so you can customize labels before uploading"
+      },
+      {
+        value: "abort",
+        name: "Skip configuration for now",
+        description: "Project is created but no config saved (you can run init again later)"
+      }
+    ]);
+    if (action === "abort") {
+      if (projectAlreadyExists) {
+        console.log(`
+${success(`Using existing project ${highlight(projectName, useColors)}`, useColors)}`);
+      } else {
+        console.log(`
+${success(`Project ${highlight(projectName, useColors)} created successfully!`, useColors)}`);
+      }
+      console.log(dim(`
+  Configuration was not saved. To configure later, run:`, useColors));
+      console.log(`    ${highlight(`pkgseer project init --name ${projectName}`, useColors)}`);
+      console.log(dim(`
+  Or manually create pkgseer.yml and run: `, useColors) + highlight(`pkgseer project upload`, useColors));
+      process.exit(0);
+    }
+    if (action === "upload") {
+      await configService.writeProjectConfig(configToWrite);
+      console.log(success(`Configuration saved to ${highlight("pkgseer.yml", useColors)}`, useColors));
+      const branch = await gitService.getCurrentBranch() ?? createResult.project.defaultBranch;
+      console.log(`
+Uploading manifest files to branch ${highlight(branch, useColors)}...`);
+      const cwd2 = fileSystemService.getCwd();
+      for (const group of manifestGroups) {
+        try {
+          const hasHexManifests2 = group.manifests.some((m) => m.type === "hex");
+          const allowMixDeps2 = configToWrite.manifests?.find((m) => m.label === group.label)?.allow_mix_deps === true;
+          const allFiles = await processManifestFiles({
+            files: group.manifests.map((m) => m.relativePath),
+            basePath: cwd2,
+            hasHexManifests: hasHexManifests2,
+            allowMixDeps: allowMixDeps2 ?? false,
+            fileSystemService,
+            shellService
+          });
+          const validFiles = allFiles.filter((f) => f !== null);
+          if (validFiles.length === 0) {
+            console.log(`  ${dim(`(no files to upload for ${group.label})`, useColors)}`);
+            continue;
+          }
+          const uploadResult = await projectService.uploadManifests({
+            project: projectName,
+            branch,
+            label: group.label,
+            files: validFiles
+          });
+          for (const result of uploadResult.results) {
+            if (result.status === "success") {
+              const depsCount = result.dependencies_count ?? 0;
+              const labelText = highlight(group.label, useColors);
+              const fileText = highlight(result.filename, useColors);
+              const depsText = dim(`(${depsCount} dependencies)`, useColors);
+              console.log(`  ${success(`${labelText}: ${fileText}`, useColors)} ${depsText}`);
+            } else {
+              console.log(`  ${error(`${group.label}: ${result.filename} - ${result.error ?? "Unknown error"}`, useColors)}`);
+            }
+          }
+        } catch (uploadError) {
+          const errorMessage = uploadError instanceof Error ? uploadError.message : String(uploadError);
+          let userMessage = `Failed to upload ${group.label}: ${errorMessage}`;
+          if (hasHexManifests) {
+            if (errorMessage.includes("command not found") || errorMessage.includes("mix:")) {
+              userMessage = `Failed to process hex manifest files for ${group.label}.
+` + `  Error: ${errorMessage}
+` + `  Make sure Elixir and 'mix' are installed. Install Elixir from https://elixir-lang.org/install.html`;
+            } else if (errorMessage.includes("Failed to generate dependencies")) {
+              userMessage = errorMessage;
+            } else if (errorMessage.includes("Network") || errorMessage.includes("ECONNREFUSED")) {
+              userMessage = `Failed to upload ${group.label}: Network error.
+` + `  Error: ${errorMessage}
+` + `  Check your internet connection and try again.`;
+            }
+          } else if (errorMessage.includes("Network") || errorMessage.includes("ECONNREFUSED")) {
+            userMessage = `Failed to upload ${group.label}: Network error.
+` + `  Error: ${errorMessage}
+` + `  Check your internet connection and try again.`;
+          }
+          console.error(error(userMessage, useColors));
         }
-        return textResult(JSON.stringify(result.data.comparePackages, null, 2));
-      });
+      }
+      console.log(`
+${success(`Project initialization complete!`, useColors)}`);
+      console.log(dim(`
+  View your project: `, useColors) + highlight(`${deps.baseUrl}/projects/${projectName}`, useColors));
+      console.log(dim(`
+  To upload updated manifests later, run: `, useColors) + highlight(`pkgseer project upload`, useColors));
+      return;
     }
-  };
+  } else {
+    console.log(dim(`
+No manifest files were found in the current directory.`, useColors));
+  }
+  await configService.writeProjectConfig(configToWrite);
+  console.log(success(`Configuration saved to ${highlight("pkgseer.yml", useColors)}`, useColors));
+  if (manifestGroups.length > 0) {
+    console.log(dim(`
+  Next steps:`, useColors));
+    console.log(dim(`    1. Edit pkgseer.yml to customize manifest labels if needed`, useColors));
+    console.log(dim(`    2. Run: `, useColors) + highlight(`pkgseer project upload`, useColors));
+    console.log(dim(`
+  Tip: Use `, useColors) + highlight(`pkgseer project detect`, useColors) + dim(` to automatically update your config when you add new manifest files.`, useColors));
+  } else {
+    console.log(dim(`
+  Next steps:`, useColors));
+    console.log(dim(`    1. Add manifest files to your project`, useColors));
+    console.log(dim(`    2. Edit pkgseer.yml to configure them:`, useColors));
+    console.log(dim(`
+       manifests:`, useColors));
+    console.log(dim(`         - label: backend`, useColors));
+    console.log(dim(`           files:`, useColors));
+    console.log(dim(`             - `, useColors) + highlight(`package-lock.json`, useColors));
+    console.log(dim(`
+    3. Run: `, useColors) + highlight(`pkgseer project upload`, useColors));
+    console.log(dim(`
+  Tip: Run `, useColors) + highlight(`pkgseer project detect`, useColors) + dim(` after adding manifest files to auto-configure them.`, useColors));
+  }
 }
-// src/commands/mcp.ts
-function createMcpServer(deps) {
-  const { pkgseerService } = deps;
-  const server = new McpServer({
-    name: "pkgseer",
-    version: "0.1.0"
+var INIT_DESCRIPTION = `Initialize a new project in the current directory.
+
+This command will:
+  1. Create a new project entry (or prompt for a project name)
+  2. Scan for manifest files (package.json, requirements.txt, etc.)
+  3. Suggest labels based on directory structure
+  4. Optionally upload manifests to the project
+
+The project name defaults to the current directory name, or you can
+specify it with --name. Manifest files are automatically detected
+and grouped by their directory structure.`;
+function registerProjectInitCommand(program) {
+  program.command("init").summary("Initialize a new project").description(INIT_DESCRIPTION).option("--name <name>", "Project name (alphanumeric, hyphens, underscores only)").option("--max-depth <depth>", "Maximum directory depth to scan for manifests", (val) => Number.parseInt(val, 10), 3).action(async (options) => {
+    const deps = await createContainer();
+    await projectInitAction({ name: options.name, maxDepth: options.maxDepth }, {
+      projectService: deps.projectService,
+      configService: deps.configService,
+      fileSystemService: deps.fileSystemService,
+      gitService: deps.gitService,
+      promptService: deps.promptService,
+      shellService: deps.shellService,
+      authStorage: deps.authStorage,
+      baseUrl: deps.baseUrl
+    });
   });
-  const tools = [
-    createPackageSummaryTool(pkgseerService),
-    createPackageVulnerabilitiesTool(pkgseerService),
-    createPackageDependenciesTool(pkgseerService),
-    createPackageQualityTool(pkgseerService),
-    createComparePackagesTool(pkgseerService)
-  ];
-  for (const tool of tools) {
-    server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.handler);
-  }
-  return server;
 }
-function requireAuth(deps) {
-  if (deps.hasValidToken) {
-    return;
+// src/commands/project/upload.ts
+async function projectUploadAction(options, deps) {
+  const {
+    projectService,
+    configService,
+    fileSystemService,
+    gitService,
+    shellService,
+    promptService,
+    authStorage,
+    baseUrl
+  } = deps;
+  const useColors = shouldUseColors2();
+  const tokenData = await checkProjectWriteScope(authStorage, baseUrl);
+  if (!tokenData) {
+    console.error(error(`Authentication required. Please run 'pkgseer login'.`, useColors));
+    console.log(`
+  To fix this:`);
+    console.log(`    1. Run: ${highlight(`pkgseer login --force`, useColors)}`);
+    console.log(`    2. Make sure to grant ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope during authentication`);
+    console.log(`
+  Or check your current scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+    process.exit(1);
   }
-  console.log(`Authentication required to start MCP server.
-`);
-  if (deps.baseUrl !== "https://pkgseer.dev") {
-    console.log(`  Environment: ${deps.baseUrl}`);
-    console.log(`  You're using a custom environment.
-`);
+  const isEnvToken = tokenData.scopes.length === 0 && tokenData.tokenName === "PKGSEER_API_TOKEN";
+  if (isEnvToken) {} else if (!tokenData.scopes.includes(PROJECT_MANIFEST_UPLOAD_SCOPE)) {
+    console.error(error(`Token missing required scope: ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)}`, useColors));
+    console.log(`
+  To fix this:`);
+    console.log(`    1. Run: ${highlight(`pkgseer login --force`, useColors)}`);
+    console.log(`    2. Make sure to grant ${highlight(PROJECT_MANIFEST_UPLOAD_SCOPE, useColors)} scope during authentication`);
+    console.log(`
+  Or check your current scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+    process.exit(1);
   }
-  console.log("To authenticate:");
-  console.log(`  pkgseer login
+  const projectConfig = await configService.loadProjectConfig();
+  if (!projectConfig?.config.project) {
+    console.error(error(`No project is configured in pkgseer.yml`, useColors));
+    console.log(`
+  To get started, run: ${highlight(`pkgseer project init`, useColors)}`);
+    console.log(`  This will create a project and detect your manifest files.`);
+    process.exit(1);
+  }
+  const projectName = projectConfig.config.project;
+  let manifests = projectConfig.config.manifests ?? [];
+  const configDir = fileSystemService.getDirname(projectConfig.path);
+  if (manifests.length === 0) {
+    console.error(error(`No manifest files are configured in pkgseer.yml`, useColors));
+    console.log(`
+  To add manifest files, you can:`);
+    console.log(`    1. Run: ${highlight(`pkgseer project detect`, useColors)}`);
+    console.log(`       This will automatically detect and configure manifest files`);
+    console.log(`    2. Or manually edit pkgseer.yml to add manifest files`);
+    console.log(`
+  Then run this command again to upload them.`);
+    process.exit(1);
+  }
+  const needsPermission = manifests.some((group) => {
+    const hasHexFiles = group.files.some((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock"));
+    return hasHexFiles && group.allow_mix_deps !== true;
+  });
+  if (needsPermission) {
+    console.log(dim(`
+  Note: Elixir/Hex manifest files (mix.exs, mix.lock) are Elixir code and cannot be directly uploaded.`, useColors));
+    console.log(dim(`  Instead, we need to run "mix deps --all" and "mix deps.tree" to generate dependency information.`, useColors));
+    const allowMixDeps = await promptService.confirm(`
+  Allow running "mix deps --all" and "mix deps.tree" for hex manifests?`, true);
+    if (!allowMixDeps) {
+      console.log(dim(`
+  Upload cancelled. Hex manifest files cannot be uploaded directly.`, useColors));
+      console.log(dim(`  To upload hex manifests, you must allow running "mix deps --all" and "mix deps.tree".`, useColors));
+      process.exit(0);
+    }
+    manifests = manifests.map((group) => {
+      const hasHexFiles = group.files.some((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock"));
+      if (hasHexFiles) {
+        return { ...group, allow_mix_deps: true };
+      }
+      return group;
+    });
+    await configService.writeProjectConfig({
+      project: projectName,
+      manifests
+    });
+    console.log(success(`Configuration updated: ${highlight("allow_mix_deps", useColors)} permission saved`, useColors));
+  }
+  let branch = options.branch;
+  if (!branch) {
+    branch = await gitService.getCurrentBranch() ?? "main";
+  }
+  console.log(`Uploading manifest files to project ${highlight(projectName, useColors)}`);
+  console.log(`Branch: ${highlight(branch, useColors)}
 `);
-  console.log("Or set PKGSEER_API_TOKEN environment variable.");
-  process.exit(1);
+  const basePath = configDir;
+  let totalSucceeded = 0;
+  let totalFailed = 0;
+  for (const manifestGroup of manifests) {
+    console.log(`Uploading ${manifestGroup.label}...`);
+    try {
+      const hexFiles = manifestGroup.files.filter((f) => f.endsWith("mix.exs") || f.endsWith("mix.lock"));
+      const hasHexManifests = hexFiles.length > 0;
+      const isHexGroup = manifestGroup.allow_mix_deps === true;
+      if (hasHexManifests && !isHexGroup) {
+        console.log(`  ${dim(`Skipping hex files. Please run 'pkgseer project detect' to update configuration.`, useColors)}`);
+        totalFailed += hexFiles.length;
+        continue;
+      }
+      let allFiles;
+      try {
+        allFiles = await processManifestFiles({
+          files: manifestGroup.files,
+          basePath,
+          hasHexManifests,
+          allowMixDeps: isHexGroup,
+          fileSystemService,
+          shellService
+        });
+      } catch (processError) {
+        const errorMessage = processError instanceof Error ? processError.message : String(processError);
+        let userMessage = `Failed to process files for ${manifestGroup.label}: ${errorMessage}`;
+        if (hasHexManifests) {
+          if (errorMessage.includes("command not found") || errorMessage.includes("mix:")) {
+            userMessage = `Failed to process hex manifest files for ${manifestGroup.label}.
+` + `  Error: ${errorMessage}
+` + `  Make sure Elixir and 'mix' are installed. Install Elixir from https://elixir-lang.org/install.html`;
+          } else if (errorMessage.includes("Failed to generate dependencies")) {
+            userMessage = errorMessage;
+          } else {
+            userMessage = `Failed to process hex manifest files for ${manifestGroup.label}.
+` + `  Error: ${errorMessage}
+` + `  Make sure the directory contains a valid Elixir project and dependencies can be resolved.`;
+          }
+        }
+        console.error(error(userMessage, useColors));
+        totalFailed += manifestGroup.files.length;
+        continue;
+      }
+      const validFiles = allFiles.filter((f) => f !== null);
+      if (validFiles.length === 0) {
+        console.log(`  ${dim(`(no files to upload for this group)`, useColors)}`);
+        continue;
+      }
+      const uploadResult = await projectService.uploadManifests({
+        project: projectName,
+        branch,
+        label: manifestGroup.label,
+        files: validFiles
+      });
+      for (const result of uploadResult.results) {
+        if (result.status === "success") {
+          const depsCount = result.dependencies_count ?? 0;
+          console.log(`  ${success(`${highlight(result.filename, useColors)}`, useColors)} ${dim(`(${depsCount} dependencies)`, useColors)}`);
+          totalSucceeded++;
+        } else {
+          console.log(`  ${error(`${result.filename} - ${result.error ?? "Unknown error"}`, useColors)}`);
+          totalFailed++;
+        }
+      }
+    } catch (uploadError) {
+      console.error(error(`Failed to upload ${manifestGroup.label}: ${uploadError instanceof Error ? uploadError.message : uploadError}`, useColors));
+      totalFailed += manifestGroup.files.length;
+    }
+  }
+  if (totalSucceeded > 0 || totalFailed > 0) {
+    const successText = totalSucceeded > 0 ? `${totalSucceeded} file${totalSucceeded === 1 ? "" : "s"} succeeded` : "";
+    const failText = totalFailed > 0 ? `${totalFailed} file${totalFailed === 1 ? "" : "s"} failed` : "";
+    const statusText = [successText, failText].filter(Boolean).join(", ");
+    console.log(`
+${success(`Upload complete: ${statusText}`, useColors)}`);
+  }
+  if (totalFailed > 0) {
+    console.log(`
+  Some files failed to upload. Please check the errors above and try again.`);
+    console.log(`  Tip: Make sure all files exist and are readable, and that you're authenticated with proper scopes.`);
+    console.log(`  Check your scopes with: ${highlight(`pkgseer auth status`, useColors)}`);
+    process.exit(1);
+  }
+  console.log(`
+  Your manifest files have been uploaded successfully!`);
+  console.log(`  View your project dependencies and insights in the PkgSeer dashboard.`);
 }
-async function startMcpServer(deps) {
-  requireAuth(deps);
-  const server = createMcpServer(deps);
-  const transport = new StdioServerTransport;
-  await server.connect(transport);
+var UPLOAD_DESCRIPTION = `Upload manifest files to your project.
+
+This command reads the manifest files configured in pkgseer.yml
+and uploads them to your project. It will:
+
+  • Upload each manifest group with its configured label
+  • Use your current git branch (or 'main' if not in a git repo)
+  • Show progress and results for each file
+
+Make sure you've configured manifest files first (using 'pkgseer
+project init' or 'pkgseer project detect'), and that you're
+authenticated (run 'pkgseer login' if needed).`;
+function registerProjectUploadCommand(program) {
+  program.command("upload").summary("Upload manifest files to a project").description(UPLOAD_DESCRIPTION).option("--branch <branch>", "Git branch name (defaults to current branch or 'main')").action(async (options) => {
+    const deps = await createContainer();
+    await projectUploadAction(options, {
+      projectService: deps.projectService,
+      configService: deps.configService,
+      fileSystemService: deps.fileSystemService,
+      gitService: deps.gitService,
+      shellService: deps.shellService,
+      promptService: deps.promptService,
+      authStorage: deps.authStorage,
+      baseUrl: deps.baseUrl
+    });
+  });
 }
-function registerMcpCommand(program) {
-  program.command("mcp").summary("Start MCP server for AI assistants").description(`Start the Model Context Protocol (MCP) server using STDIO transport.
+// src/commands/quickstart.ts
+var QUICKSTART_TEXT = `# PkgSeer CLI - Quick Reference for AI Agents
 
-This allows AI assistants like Claude, Cursor, and others to query package
-information directly. Add this to your assistant's MCP configuration:
+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.
 
-Available tools: package_summary, package_vulnerabilities,
-package_dependencies, package_quality, compare_packages`).action(async () => {
-    const deps = await createContainer();
-    await startMcpServer(deps);
+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);
   });
 }
 
@@ -1054,11 +4512,41 @@ program.name("pkgseer").description("Package intelligence for your AI assistant"
 Getting started:
   pkgseer login      Authenticate with your account
   pkgseer mcp        Start the MCP server for AI assistants
+  pkgseer quickstart Show quick reference for AI agents
+
+Package commands:
+  pkgseer pkg info <package>      Get package summary
+  pkgseer pkg vulns <package>     Check vulnerabilities
+  pkgseer pkg quality <package>   Get quality score
+  pkgseer pkg deps <package>      List dependencies
+  pkgseer pkg compare <pkg...>    Compare packages
+
+Documentation commands:
+  pkgseer docs list <package>     List doc pages
+  pkgseer docs get <pkg> <page>   Fetch a doc page
+  pkgseer docs search <query>     Search documentation
 
 Learn more at https://pkgseer.dev`);
 registerMcpCommand(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");
+registerConfigShowCommand(config);
+var pkg = program.command("pkg").description("Package intelligence commands");
+registerPkgInfoCommand(pkg);
+registerPkgQualityCommand(pkg);
+registerPkgDepsCommand(pkg);
+registerPkgVulnsCommand(pkg);
+registerPkgCompareCommand(pkg);
+var docs = program.command("docs").description("Package documentation commands");
+registerDocsListCommand(docs);
+registerDocsGetCommand(docs);
+registerDocsSearchCommand(docs);
+var project = program.command("project").description("Project management commands");
+registerProjectInitCommand(project);
+registerProjectDetectCommand(project);
+registerProjectUploadCommand(project);
 program.parse();