githits 0.4.2 → 0.4.3

package/dist/cli.js

@@ -49,11 +49,11 @@ import {
   shouldRunUpdateCheck,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-v8sths32.js";
+} from "./shared/chunk-15argn2z.js";
 import {
   __require,
   version
-} from "./shared/chunk-jdygt0ra.js";
+} from "./shared/chunk-q6d3ttgn.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -2022,7 +2022,7 @@ var SUPPORTED_DEPS_REGISTRIES = new Set([
   "RUBYGEMS",
   "GO"
 ]);
-var SUPPORTED_DEPS_REGISTRIES_HUMAN = "npm, pypi, hex, crates, vcpkg, zig, rubygems, and go";
+var SUPPORTED_DEPS_REGISTRIES_LIST = PKGSEER_REGISTRY_ARGS.filter((arg) => SUPPORTED_DEPS_REGISTRIES.has(toPkgseerRegistry(arg))).join(", ");
 function supportsDependenciesRegistry(registry) {
   return SUPPORTED_DEPS_REGISTRIES.has(registry);
 }
@@ -2037,7 +2037,7 @@ function buildPackageDependenciesParams(input) {
   }
   const registry = toPkgseerRegistry(normalisedRegistryArg);
   if (!supportsDependenciesRegistry(registry)) {
-    throw new UnsupportedDependenciesRegistryError(`pkg deps only supports ${SUPPORTED_DEPS_REGISTRIES_HUMAN}. Got: ${normalisedRegistryArg}.`);
+    throw new UnsupportedDependenciesRegistryError(`pkg deps only supports ${SUPPORTED_DEPS_REGISTRIES_LIST}. Got: ${normalisedRegistryArg}.`);
   }
   const version2 = normaliseVersion(input.version);
   const canonicalLifecycles = resolveLifecycles(input.lifecycle);
@@ -2900,12 +2900,6 @@ function buildPackageSummarySuccessPayload(summary) {
   const github = buildGithub(pkg.githubRepository);
   if (github)
     payload.github = github;
-  if (summary.quickstart?.installCommand) {
-    payload.install = summary.quickstart.installCommand;
-  }
-  const usage = normaliseUsage(summary.quickstart?.usageExample);
-  if (usage)
-    payload.usage = usage;
   const vulns = buildVulnerabilities(summary.security);
   if (vulns)
     payload.vulnerabilities = vulns;
@@ -2964,20 +2958,12 @@ function buildGithub(github) {
     result.lastPushedAt = lastPushedAt;
   return Object.keys(result).length > 0 ? result : undefined;
 }
-function normaliseUsage(usage) {
-  if (!usage)
-    return;
-  const cleaned = usage.replace(/\r\n/g, `
-`).replace(/\r/g, `
-`);
-  return cleaned.length > 0 ? cleaned : undefined;
-}
 function buildVulnerabilities(security) {
   if (!security)
     return;
-  const total = security.vulnerabilityCount ?? 0;
-  if (total === 0)
+  if (typeof security.vulnerabilityCount !== "number")
     return;
+  const total = security.vulnerabilityCount;
   const result = {
     total,
     affectsLatest: security.hasCurrentVulnerabilities ?? false
@@ -3033,7 +3019,7 @@ function pickChangelogSummary(entry) {
   const firstLine = entry.body.split(/\r?\n/).map((line) => stripMarkdownHeading(line.trim())).find((line) => line.length > 0);
   if (!firstLine)
     return;
-  return firstLine.length > 120 ? `${firstLine.slice(0, 120).trimEnd()}…` : firstLine;
+  return firstLine.length > 120 ? `${firstLine.slice(0, 117).trimEnd()}...` : firstLine;
 }
 function stripMarkdownHeading(line) {
   return line.replace(/^#{1,6}\s+/, "").trim();
@@ -3044,7 +3030,7 @@ function formatPackageSummaryTerminal(summary, options = {}) {
   const width = resolveWidth(options.terminalWidth);
   const now = options.now ?? new Date;
   const sections = [];
-  const header = lean.license ? `${colorize(lean.name, "bold", useColors)} @ ${lean.version} · ${lean.license}` : `${colorize(lean.name, "bold", useColors)} @ ${lean.version}`;
+  const header = lean.license ? `${colorize(lean.name, "bold", useColors)} @ ${lean.version} | ${lean.license}` : `${colorize(lean.name, "bold", useColors)} @ ${lean.version}`;
   sections.push(header);
   if (lean.description) {
     sections.push(wrapText(lean.description, width));
@@ -3054,9 +3040,6 @@ function formatPackageSummaryTerminal(summary, options = {}) {
     sections.push(fields.join(`
 `));
   }
-  if (lean.vulnerabilities) {
-    sections.push(formatVulnFooter(lean.vulnerabilities, useColors));
-  }
   if (options.verbose) {
     const verbose = buildVerboseSections(lean, useColors);
     if (verbose.length > 0)
@@ -3101,10 +3084,19 @@ function wrapText(text, width) {
 function buildFieldList(lean, summary, useColors, now) {
   const fields = [];
   if (lean.repository) {
+    const repositoryParts = [dim(lean.repository, useColors)];
+    const githubPopularity = formatGithubPopularity(lean.github);
+    if (githubPopularity)
+      repositoryParts.push(`(${githubPopularity})`);
     fields.push({
       label: "Repository",
-      value: dim(lean.repository, useColors)
+      value: repositoryParts.join(" ")
     });
+  } else {
+    const githubPopularity = formatGithubPopularity(lean.github);
+    if (githubPopularity) {
+      fields.push({ label: "GitHub", value: githubPopularity });
+    }
   }
   if (lean.homepage) {
     fields.push({ label: "Homepage", value: dim(lean.homepage, useColors) });
@@ -3124,54 +3116,53 @@ function buildFieldList(lean, summary, useColors, now) {
       value: `${formatCompactNumber(lean.downloads.total)} total`
     });
   }
-  if (lean.github) {
-    fields.push({ label: "GitHub", value: formatGithubLine(lean.github) });
-  }
-  if (lean.install) {
-    fields.push({ label: "Install", value: lean.install });
+  if (lean.vulnerabilities) {
+    fields.push({
+      label: "Vulnerabilities",
+      value: formatVulnerabilityStatus(lean.vulnerabilities)
+    });
   }
   const labelWidth = Math.max(10, ...fields.map((field) => field.label.length));
   return fields.map((field) => `${field.label.padEnd(labelWidth)}  ${field.value}`);
 }
-function formatGithubLine(github) {
+function formatGithubPopularity(github) {
+  if (!github)
+    return;
   const parts = [];
+  if (github.archived) {
+    parts.push("[ARCHIVED]");
+  }
   if (github.stars !== undefined) {
-    parts.push(`★ ${formatCompactNumber(github.stars)}`);
+    parts.push(`${formatCompactNumber(github.stars)} stars`);
   }
   if (github.forks !== undefined) {
     parts.push(`${formatCompactNumber(github.forks)} forks`);
   }
   if (github.openIssues !== undefined) {
-    parts.push(`${formatCompactNumber(github.openIssues)} open issues`);
+    parts.push(`${formatCompactNumber(github.openIssues)} issues`);
   }
-  if (github.archived) {
-    parts.push("archived");
-  }
-  return parts.join(" · ");
+  return parts.length > 0 ? parts.join(", ") : undefined;
 }
-function formatVulnFooter(vulns, useColors) {
+function formatVulnerabilityStatus(vulns) {
+  if (vulns.total === 0) {
+    return "No active vulnerabilities in latest published version";
+  }
   const noun = vulns.total === 1 ? "vulnerability" : "vulnerabilities";
-  const base = `${vulns.total} known ${noun}`;
-  const full = vulns.affectsLatest ? `${base} · latest affected` : base;
-  return colorize(full, "yellow", useColors);
+  if (vulns.affectsLatest) {
+    return `${vulns.total} active ${noun}; latest affected`;
+  }
+  return `${vulns.total} known ${noun}; latest not affected`;
 }
 function buildVerboseSections(lean, useColors) {
   const blocks = [];
-  if (lean.usage) {
-    blocks.push([
-      highlight("Usage", useColors),
-      lean.usage.split(`
-`).map((line) => `  ${line}`).join(`
-`)
-    ].join(`
-`));
+  if (lean.github) {
+    const github = formatVerboseGithub(lean.github, useColors);
+    if (github)
+      blocks.push(github);
   }
   if (lean.vulnerabilities?.recent && lean.vulnerabilities.recent.length > 0) {
     blocks.push(formatVerboseAdvisories(lean.vulnerabilities.recent, useColors));
   }
-  if (lean.github?.topics && lean.github.topics.length > 0) {
-    blocks.push(`${"Topics".padEnd(10)}  ${lean.github.topics.join(", ")}`);
-  }
   if (lean.recentChanges && lean.recentChanges.length > 0) {
     blocks.push(formatVerboseChanges(lean.recentChanges, useColors));
   }
@@ -3179,6 +3170,23 @@ function buildVerboseSections(lean, useColors) {
 
 `);
 }
+function formatVerboseGithub(github, useColors) {
+  const fields = [];
+  if (github.language)
+    fields.push({ label: "Language", value: github.language });
+  if (github.lastPushedAt) {
+    fields.push({ label: "Last pushed", value: github.lastPushedAt });
+  }
+  if (github.topics && github.topics.length > 0) {
+    fields.push({ label: "Topics", value: github.topics.join(", ") });
+  }
+  const labelWidth = Math.max(10, ...fields.map((field) => field.label.length));
+  return fields.length > 0 ? [
+    highlight("GitHub", useColors),
+    ...fields.map((field) => `  ${field.label.padEnd(labelWidth)}  ${field.value}`)
+  ].join(`
+`) : undefined;
+}
 function formatVerboseAdvisories(advisories, useColors) {
   const labelWidth = Math.max(...advisories.map((a) => (a.severityLabel ?? "").length));
   const lines = [highlight("Recent advisories", useColors)];
@@ -3228,12 +3236,22 @@ var SUPPORTED_VULN_REGISTRIES = new Set([
   "NPM",
   "PYPI",
   "HEX",
-  "CRATES"
+  "CRATES",
+  "NUGET",
+  "MAVEN",
+  "PACKAGIST",
+  "RUBYGEMS",
+  "GO"
 ]);
-var SUPPORTED_VULN_REGISTRIES_HUMAN = "npm, pypi, hex, and crates";
+var SUPPORTED_VULN_REGISTRIES_HUMAN = "npm, pypi, hex, crates, nuget, maven, packagist, rubygems, and go";
 function supportsVulnerabilitiesRegistry(registry) {
   return SUPPORTED_VULN_REGISTRIES.has(registry);
 }
+var ADVISORY_SCOPE_TO_GRAPHQL = {
+  affected: "AFFECTED",
+  non_affecting: "NON_AFFECTING",
+  all: "ALL"
+};
 function buildPackageVulnerabilitiesParams(input) {
   const trimmedName = input.packageName?.trim() ?? "";
   if (!trimmedName) {
@@ -3247,22 +3265,27 @@ function buildPackageVulnerabilitiesParams(input) {
   if (!supportsVulnerabilitiesRegistry(registry)) {
     throw new UnsupportedVulnerabilitiesRegistryError(`pkg vulns only supports ${SUPPORTED_VULN_REGISTRIES_HUMAN}. Got: ${normalisedRegistryArg}.`);
   }
-  const minSeverity = resolveMinSeverity(input.minSeverity);
+  const severityLabel2 = resolveMinSeverityLabel(input.minSeverity);
+  const minSeverity = severityLabel2 !== undefined ? SEVERITY_LABEL_TO_CVSS[severityLabel2] : undefined;
   const trimmedVersion = input.version?.trim();
   if (trimmedVersion && /^v\d/i.test(trimmedVersion)) {
     throw new InvalidPackageSpecError(`Invalid version '${trimmedVersion}'. Use the canonical package version without a leading 'v' (for example '4.18.0', not 'v4.18.0').`);
   }
+  const advisoryScope = resolveAdvisoryScope(input.advisoryScope);
+  const filterWithScope = buildFilterEcho3(severityLabel2, input.includeWithdrawn, advisoryScope);
   return {
     params: {
       registry,
       packageName: trimmedName,
       version: trimmedVersion && trimmedVersion.length > 0 ? trimmedVersion : undefined,
       minSeverity,
-      includeWithdrawn: input.includeWithdrawn
-    }
+      includeWithdrawn: input.includeWithdrawn,
+      advisoryScope: advisoryScope ? ADVISORY_SCOPE_TO_GRAPHQL[advisoryScope] : undefined
+    },
+    ...filterWithScope ? { filter: filterWithScope } : {}
   };
 }
-function resolveMinSeverity(raw) {
+function resolveMinSeverityLabel(raw) {
   if (raw === undefined)
     return;
   const trimmed = raw.trim();
@@ -3272,12 +3295,36 @@ function resolveMinSeverity(raw) {
   if (!isSeverityLabel(lower)) {
     throw new InvalidPackageSpecError(`Unsupported severity '${raw}'. Expected one of: low, medium, high, critical.`);
   }
-  return SEVERITY_LABEL_TO_CVSS[lower];
+  return lower;
+}
+function buildFilterEcho3(minSeverity, includeWithdrawn, advisoryScope) {
+  const filter = {};
+  if (minSeverity !== undefined)
+    filter.minSeverity = minSeverity;
+  if (includeWithdrawn === true)
+    filter.includeWithdrawn = true;
+  if (advisoryScope !== undefined && advisoryScope !== "affected") {
+    filter.advisoryScope = advisoryScope;
+  }
+  return Object.keys(filter).length > 0 ? filter : undefined;
+}
+function resolveAdvisoryScope(raw) {
+  if (raw === undefined)
+    return;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0)
+    return;
+  const lower = trimmed.toLowerCase().replace(/-/g, "_");
+  if (lower === "affected" || lower === "non_affecting" || lower === "all") {
+    return lower;
+  }
+  throw new InvalidPackageSpecError(`Unsupported advisory scope '${raw}'. Expected one of: affected, non_affecting, all.`);
 }
 function isSeverityLabel(value) {
   return value === "low" || value === "medium" || value === "high" || value === "critical";
 }
 // src/shared/package-vulnerabilities-response.ts
+var DEFAULT_ADVISORY_CAP = 5;
 function buildPackageVulnerabilitiesSuccessPayload(report, options = {}) {
   const pkg = report.package;
   const security = report.security;
@@ -3293,11 +3340,12 @@ function buildPackageVulnerabilitiesSuccessPayload(report, options = {}) {
   if (requestedEcho !== undefined) {
     payload.requestedVersion = requestedEcho;
   }
-  if (total > 0) {
-    const sortedAdvisories = sortAdvisories(dedupedAdvisories.map(buildAdvisory));
-    if (sortedAdvisories.length > 0) {
-      payload.advisories = sortedAdvisories;
-    }
+  if (options.filter !== undefined) {
+    payload.filter = options.filter;
+  }
+  const sortedAdvisories = sortAdvisories(dedupedAdvisories.map(buildAdvisory));
+  if (sortedAdvisories.length > 0) {
+    payload.advisories = sortedAdvisories;
   }
   const upgradePaths = security?.upgradePaths;
   if (upgradePaths && upgradePaths.length > 0) {
@@ -3343,7 +3391,7 @@ function buildSummary(total, security, dedupedAdvisories) {
   if (typeof security?.currentVersionAffected === "boolean") {
     summary.affected = security.currentVersionAffected;
   }
-  if (total === 0)
+  if (dedupedAdvisories.length === 0)
     return summary;
   const bySeverity = computeBySeverity(dedupedAdvisories);
   const anyCounted = Object.values(bySeverity).some((n) => n > 0);
@@ -3731,17 +3779,25 @@ function lowerRegistry3(value) {
 }
 function formatPackageVulnerabilitiesTerminal(report, options = {}) {
   const payload = buildPackageVulnerabilitiesSuccessPayload(report, {
-    requestedVersion: options.requestedVersion
+    requestedVersion: options.requestedVersion,
+    filter: options.filter
   });
   const useColors = options.useColors ?? false;
   const verbose = options.verbose ?? false;
+  const surface = options.surface ?? "cli";
   const headerLine = formatHeader(payload, useColors);
   const requestedLine = payload.requestedVersion ? dim(`(requested ${payload.requestedVersion})`, useColors) : undefined;
+  const filterLines = formatFilterLines(payload.filter);
   if (payload.summary.total === 0) {
     const lines = [headerLine];
     if (requestedLine)
       lines.push(requestedLine);
+    lines.push(...filterLines);
     lines.push(formatNoAffectedVulnerabilitiesLine(payload));
+    if (payload.advisories && payload.advisories.length > 0) {
+      const rangeLimit = resolveAffectedRangesLimit(options.terminalWidth);
+      lines.push("", formatAdvisoryList(payload.advisories, verbose, useColors, rangeLimit, surface));
+    }
     return `${lines.join(`
 `)}
 `;
@@ -3750,15 +3806,21 @@ function formatPackageVulnerabilitiesTerminal(report, options = {}) {
   const headerBlock = [headerLine];
   if (requestedLine)
     headerBlock.push(requestedLine);
+  headerBlock.push(...filterLines);
   headerBlock.push(formatSummaryLine(payload, useColors));
-  const breakdown = formatBreakdownLine(payload.summary, useColors);
+  const selectedAdvisoryCount = payload.advisories?.length ?? 0;
+  const scope = payload.filter?.advisoryScope;
+  const selectedCountLine = formatSelectedAdvisoryCountLine(selectedAdvisoryCount, scope);
+  if (selectedCountLine)
+    headerBlock.push(selectedCountLine);
+  const breakdown = scope === undefined ? formatBreakdownLine(payload.summary, useColors) : undefined;
   if (breakdown)
     headerBlock.push(breakdown);
   blocks.push(headerBlock.join(`
 `));
   if (payload.advisories && payload.advisories.length > 0) {
     const rangeLimit = resolveAffectedRangesLimit(options.terminalWidth);
-    blocks.push(formatAdvisoryList(payload.advisories, verbose, useColors, rangeLimit));
+    blocks.push(formatAdvisoryList(payload.advisories, verbose, useColors, rangeLimit, surface));
   }
   const upgradeFooter = formatUpgradeFooter(payload.upgradePaths);
   if (upgradeFooter)
@@ -3770,7 +3832,29 @@ function formatPackageVulnerabilitiesTerminal(report, options = {}) {
 }
 function formatHeader(payload, useColors) {
   const name = colorize(payload.name, "bold", useColors);
-  return `${name} @ ${payload.version} · ${payload.registry}`;
+  return `${name} @ ${payload.version} | ${payload.registry}`;
+}
+function formatFilterLines(filter) {
+  if (!filter)
+    return [];
+  const lines = [];
+  if (filter.advisoryScope) {
+    lines.push(`Scope   ${formatAdvisoryScope(filter.advisoryScope)}`);
+  }
+  if (filter.minSeverity) {
+    lines.push(`Filter  severity >= ${filter.minSeverity}`);
+  }
+  if (filter.includeWithdrawn === true) {
+    lines.push("Filter  include withdrawn");
+  }
+  return lines;
+}
+function formatAdvisoryScope(scope) {
+  if (scope === "non_affecting")
+    return "historical advisories only";
+  if (scope === "all")
+    return "all package advisories";
+  return scope;
 }
 function formatSummaryLine(payload, useColors) {
   const n = payload.summary.total;
@@ -3786,13 +3870,41 @@ function formatSummaryLine(payload, useColors) {
   return base;
 }
 function formatNoAffectedVulnerabilitiesLine(payload) {
+  const selectedAdvisoryCount = payload.advisories?.length ?? 0;
+  if (payload.filter?.advisoryScope === "non_affecting") {
+    if (selectedAdvisoryCount > 0) {
+      return "No active vulnerabilities affect this version; historical advisories are listed below.";
+    }
+    return "No active vulnerabilities affect this version; no historical advisories match the current filter.";
+  }
+  if (payload.filter?.advisoryScope === "all") {
+    if (selectedAdvisoryCount > 0) {
+      return "No active vulnerabilities affect this version; package advisories are listed below.";
+    }
+    return "No active vulnerabilities affect this version; no package advisories match the current filter.";
+  }
+  if (payload.filter !== undefined) {
+    return "No vulnerabilities matching the filter affect this version.";
+  }
   const historical = payload.summary.nonAffectingVulnerabilityCount ?? 0;
   if (historical > 0) {
     const noun = historical === 1 ? "historical advisory" : "historical advisories";
     const verb = historical === 1 ? "does" : "do";
-    return `No vulnerabilities affect this version (${historical} ${noun} ${verb} not apply).`;
+    return `No active vulnerabilities affect this version (${historical} ${noun} ${verb} not apply).`;
   }
-  return "No known vulnerabilities affect this version.";
+  return "No active vulnerabilities affect this version.";
+}
+function formatSelectedAdvisoryCountLine(count, scope) {
+  if (scope === undefined)
+    return;
+  const noun = count === 1 ? "advisory" : "advisories";
+  if (scope === "non_affecting") {
+    return `  showing ${count} historical ${noun} that do not affect this version`;
+  }
+  if (scope === "all") {
+    return `  showing ${count} package ${noun} across affected and historical scopes`;
+  }
+  return;
 }
 function formatBreakdownLine(summary, useColors) {
   if (summary.total <= 1)
@@ -3818,22 +3930,31 @@ function formatBreakdownLine(summary, useColors) {
   }
   if (parts.length === 0)
     return;
-  return `  ${parts.join(" · ")}`;
+  return `  ${parts.join(" | ")}`;
 }
-function formatAdvisoryList(advisories, verbose, useColors, rangeLimit) {
-  const labelWidth = Math.max(...advisories.map((a) => severityColumnLabel(a).length));
+function formatAdvisoryList(advisories, verbose, useColors, rangeLimit, surface) {
+  const renderedAdvisories = verbose ? advisories : advisories.slice(0, DEFAULT_ADVISORY_CAP);
+  const labelWidth = Math.max(...renderedAdvisories.map((a) => severityColumnLabel(a).length));
   const lines = [];
-  for (const advisory of advisories) {
-    lines.push(...formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimit));
+  for (const advisory of renderedAdvisories) {
+    lines.push(...formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimit, surface));
     lines.push("");
   }
+  const hidden = advisories.length - renderedAdvisories.length;
+  if (hidden > 0) {
+    lines.push(dim(formatAdvisoryCapHint(hidden, surface), useColors));
+  }
   return lines.join(`
 `).trimEnd();
 }
+function formatAdvisoryCapHint(hidden, surface) {
+  const hint = surface === "mcp" ? "use verbose=true or format=json" : "use -v";
+  return `... (+${hidden} more; ${hint})`;
+}
 function severityColumnLabel(advisory) {
   if (advisory.isMalicious === true) {
     if (advisory.severityLabel)
-      return `MALWARE · ${advisory.severityLabel}`;
+      return `MALWARE | ${advisory.severityLabel}`;
     return "MALWARE";
   }
   return advisory.severityLabel ?? "unrated";
@@ -3862,7 +3983,7 @@ function severityColumnColor(advisory, useColors, padded) {
       return dim(padded, useColors);
   }
 }
-function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimit) {
+function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimit, surface) {
   const rawLabel = severityColumnLabel(advisory);
   const padded = rawLabel.padEnd(labelWidth);
   const colouredLabel = severityColumnColor(advisory, useColors, padded);
@@ -3879,7 +4000,7 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
     lines.push(`    ${label.padEnd(detailWidth)} ${value}`);
   };
   if (advisory.affectedRanges && advisory.affectedRanges.length > 0) {
-    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit, advisory.affectedVersionRangesCount, advisory.affectedVersionRangesTruncated));
+    pushRow("affected", formatRangeList(advisory.affectedRanges, verbose, useColors, rangeLimit, surface, advisory.affectedVersionRangesCount, advisory.affectedVersionRangesTruncated));
   }
   if (advisory.fixedIn && advisory.fixedIn.length > 0) {
     pushRow("fixed in", advisory.fixedIn.join(", "));
@@ -3906,12 +4027,12 @@ function formatAdvisoryLines(advisory, labelWidth, verbose, useColors, rangeLimi
   }
   return lines;
 }
-function formatRangeList(ranges, verbose, useColors, limit, totalCount, backendTruncated) {
+function formatRangeList(ranges, verbose, useColors, limit, surface, totalCount, backendTruncated) {
   const actualTotal = Math.max(totalCount ?? ranges.length, ranges.length);
   const backendHidden = backendTruncated === true ? actualTotal - ranges.length : 0;
   const appendBackendHint = (shown2) => {
     if (backendHidden > 0) {
-      const hint2 = dim(`… (+${backendHidden} ranges omitted by service)`, useColors);
+      const hint2 = dim(`... (+${backendHidden} ranges omitted by service)`, useColors);
       return shown2.length > 0 ? `${shown2}, ${hint2}` : hint2;
     }
     return shown2;
@@ -3921,7 +4042,8 @@ function formatRangeList(ranges, verbose, useColors, limit, totalCount, backendT
   }
   const shown = ranges.slice(0, limit).join(", ");
   const localHidden = ranges.length - limit;
-  const hintText = backendHidden > 0 ? `… (+${localHidden} more with -v; +${backendHidden} omitted by service)` : `… (+${localHidden} more; use -v)`;
+  const localHint = surface === "mcp" ? "use verbose=true" : "use -v";
+  const hintText = backendHidden > 0 ? `... (+${localHidden} more with ${localHint}; +${backendHidden} omitted by service)` : `... (+${localHidden} more; ${localHint})`;
   const hint = dim(hintText, useColors);
   return `${shown}, ${hint}`;
 }
@@ -4615,11 +4737,11 @@ function buildUnifiedSearchParams(input) {
 }
 function resolveTargets(target, targets) {
   if (target && targets) {
-    throw new InvalidArgumentError("Provide either target or targets, not both.");
+    throw new InvalidArgumentError("Provide either `target` for one search target or `targets` for multiple, not both.");
   }
   const resolved = target ? [target] : targets ?? [];
   if (resolved.length === 0) {
-    throw new InvalidArgumentError("At least one target is required.");
+    throw new InvalidArgumentError("Provide either `target` for one search target or `targets` for multiple; neither was set.");
   }
   const deduped = [];
   const seen = new Set;
@@ -4738,7 +4860,7 @@ function combineWarnings(parserWarnings, sourceStatus, hits = [], progress) {
   out.push(...buildHitFreshnessWarnings(hits));
   out.push(...buildProgressFreshnessWarnings(progress));
   out.push(...buildSourceStatusWarnings(sourceStatus));
-  return out;
+  return Array.from(new Set(out));
 }
 function buildUnifiedSearchErrorPayload(error2) {
   const mapped = mapCodeNavigationError(error2);
@@ -4949,7 +5071,7 @@ function compactProgress(progress) {
     payload.requestedTargets = progress.requestedTargets;
   }
   if (progress.filters)
-    payload.filters = buildFilterEcho3(progress.filters);
+    payload.filters = buildFilterEcho4(progress.filters);
   if (typeof progress.limit === "number")
     payload.limit = progress.limit;
   if (typeof progress.offset === "number")
@@ -4996,7 +5118,7 @@ function compactProgressTarget(target) {
     payload.requestedRefKind = target.requestedRefKind;
   return Object.keys(payload).length > 0 ? payload : undefined;
 }
-function buildFilterEcho3(filters) {
+function buildFilterEcho4(filters) {
   const echo = {};
   if (filters.kind)
     echo.kind = filters.kind.toLowerCase();
@@ -6271,7 +6393,7 @@ grep run. --symbol-field hydrates enclosing symbol metadata (appears under each
 match in --verbose output; full payload in --json).`;
 function registerCodeGrepCommand(pkgCommand) {
   return pkgCommand.command("grep").summary("Deterministic text grep over indexed dependency source").description(PKG_GREP_DESCRIPTION).argument("[spec-or-pattern]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the pattern.").argument("[pattern-or-prefix]", "Spec mode: the pattern. Repo mode: optional path-prefix.").argument("[path-prefix]", "Spec mode only: optional path-prefix. Ignored with --repo-url.").option("--repo-url <url>", "Repository URL addressing (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--path <path>", "Exact file path to grep").option("--glob <glob>", "Glob scope (repeatable)", collectRepeatable2, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable2, []).option("--regex", "Interpret the pattern as RE2 regex").option("--case-sensitive", "Enable ASCII case-sensitive matching").option("-C, --context <n>", "Context lines before and after each match (0-10)").option("-B, --before-context <n>", "Context lines before each match (0-10)").option("-A, --after-context <n>", "Context lines after each match (0-10)").option("--exclude-docs", "Skip files classified as documentation").option("--exclude-tests", "Skip files classified as tests").option("--limit <n>", "Max matches to return on this page (1-1000, default 50)").option("--per-file-limit <n>", "Cap matches per file within this page (0-1000, 0 = unlimited)").option("--cursor <cursor>", "Opaque nextCursor from a previous grep result").option("--symbol-field <field>", `Repeatable; surfaces in --json and under each --verbose match. ${GREP_REPO_SYMBOL_FIELDS_NOTE}`, collectRepeatable2, []).option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Render grouped output with file headers").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, arg3, options) => {
-    const { createContainer: createContainer2 } = await import("./shared/chunk-q2mre780.js");
+    const { createContainer: createContainer2 } = await import("./shared/chunk-kmka6wpx.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -6805,7 +6927,7 @@ function registerExampleCommand(program) {
   });
 }
 async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-q2mre780.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-kmka6wpx.js");
   return createContainer2();
 }
 // src/commands/feedback.ts
@@ -6833,17 +6955,25 @@ async function feedbackAction(solutionId, options, deps) {
     process.exit(1);
   }
 }
-var FEEDBACK_DESCRIPTION = `Submit feedback on a search result.
+var FEEDBACK_DESCRIPTION = `Submit feedback on a tool result or the GitHits experience.
+
+Two modes:
+  - Solution-tied: pass the [solution_id] from a prior 'githits example'
+    result (shown at the bottom of the markdown / under 'solution_id'
+    in --json) to anchor feedback to that specific result.
+  - Generic: omit [solution_id] to send feedback about any command
+    (search, pkg, docs, code) or the overall experience. A --message
+    is strongly recommended here.
 
-Rate whether a code example was helpful. Use --accept for positive
-feedback or --reject for negative. Optionally add a message.
+Use --accept for positive feedback or --reject for negative.
 
 Examples:
   githits feedback abc123 --accept
   githits feedback abc123 --reject -m "Example was outdated"
-  githits feedback abc123 --accept --message "Solved my problem" --json`;
+  githits feedback --accept -m "code_grep regex is fast on npm:lodash"
+  githits feedback --reject -m "search missing kotlin support"`;
 function registerFeedbackCommand(program) {
-  program.command("feedback").summary("Submit feedback on a search result").description(FEEDBACK_DESCRIPTION).argument("<solution_id>", "Solution ID from search result").addOption(new Option2("--accept", "Mark as helpful").conflicts("reject")).addOption(new Option2("--reject", "Mark as unhelpful").conflicts("accept")).option("-m, --message <text>", "Feedback explanation").option("--json", "Output as JSON for piping").action(async (solutionId, options) => {
+  program.command("feedback").summary("Submit feedback on a tool result or the GitHits experience").description(FEEDBACK_DESCRIPTION).argument("[solution_id]", "Solution ID from a prior 'githits example' result (omit for generic feedback)").addOption(new Option2("--accept", "Mark as helpful").conflicts("reject")).addOption(new Option2("--reject", "Mark as unhelpful").conflicts("accept")).option("-m, --message <text>", "Feedback explanation").option("--json", "Output as JSON for piping").action(async (solutionId, options) => {
     try {
       const deps = await createContainer();
       await feedbackAction(solutionId, options, deps);
@@ -7908,13 +8038,17 @@ function classify3(operation, error2) {
 
 // src/tools/feedback.ts
 var schema = {
-  solution_id: z.string().min(1).describe("The solution ID from a previous search result (shown in the result)"),
-  accepted: z.boolean().describe("True if the example was helpful/good, False if unhelpful/bad"),
-  feedback_text: z.string().optional().describe('Optional text explaining why (e.g., "This solved problem X" or "Example was outdated")')
+  solution_id: z.string().min(1).optional().describe("Optional. Pass the `solution_id` from a prior `get_example` response (shown on the trailing line of the markdown result, or under the `solution_id` key in JSON mode) to anchor feedback to that specific result. Omit for generic feedback about any tool (code/package navigation, search, docs) or the overall experience."),
+  accepted: z.boolean().describe("True for positive feedback (helpful/good), False for negative (unhelpful/bad). Always required."),
+  feedback_text: z.string().optional().describe('Optional context (e.g., "This solved problem X" or "code_grep regex over npm:lodash missed Foo function"). Strongly recommended when `solution_id` is omitted, since there is no specific result to anchor to.')
 };
-var DESCRIPTION = `Submit feedback on a GitHits example result.
+var DESCRIPTION = `Submit feedback on a tool result or the GitHits experience.
+
+Two modes:
+1. **Solution-tied** — pass the \`solution_id\` from a prior \`get_example\` response to rate that specific result.
+2. **Generic** — omit \`solution_id\` to send feedback about any tool (\`search\`, \`code_grep\`, \`code_read\`, \`code_files\`, \`docs_*\`, \`pkg_*\`) or the overall experience.
 
-Call after \`get_example\` to record whether the returned example was used. \`accepted=true\` when it solved the problem or was useful; \`accepted=false\` when it was irrelevant or wrong. Use \`feedback_text\` to add a short reason. Feeds back into ranking quality.`;
+\`accepted\` is always required (true = positive, false = negative). Add \`feedback_text\` for context — strongly recommended in generic mode. Feeds ranking and product quality.`;
 function createFeedbackTool(service) {
   return {
     name: "feedback",
@@ -7938,7 +8072,7 @@ var schema2 = {
   query: z2.string().min(1).describe("Natural-language example-search query for canonical code examples."),
   language: z2.string().min(1).optional().describe("Optional programming language. If omitted, GitHits tries to infer it automatically. Use search_language first only when you need to force a specific language and the exact name is uncertain."),
   license_mode: z2.enum(["strict", "yolo", "custom"]).optional().describe("License filtering mode: strict (default), yolo, or custom."),
-  format: z2.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` returns markdown directly with a trailing `solution_id` line when available. Pass `json` for `{result, solution_id?}`.")
+  format: z2.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` returns markdown directly with a trailing `solution_id` line when available. Pass `format: "json"` for `{result, solution_id?}`.')
 };
 var DESCRIPTION2 = `Get verified, canonical code examples from global open source.
 
@@ -8063,7 +8197,7 @@ var schema3 = {
   wait_timeout_ms: z4.number().optional(),
   format: z4.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output (matches grouped by file with grep -A/-B notation for context). Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION3 = "Deterministic text grep over indexed dependency and repository source files. " + "Use this when you know the text pattern you want; use `search` for discovery. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + 'Default response is a compact line-oriented listing (`format: "text-v1"`); pass `format: "json"` for the structured envelope. ' + "Matches chain directly into `code_read` (the `path` and `line` from each match feed straight into `start_line` / `end_line`).";
+var DESCRIPTION3 = "Deterministic text or regex grep over indexed dependency and repository source files. " + 'Use this when you know the pattern (literal by default; pass `pattern_type: "regex"` for RE2). ' + "Use `search` for discovery instead. " + "Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. " + "Each match's `path` chains into `code_read.path`; pick a window around `match.line` for `code_read.start_line` / `end_line`.";
 function createGrepRepoTool(service) {
   return {
     name: "code_grep",
@@ -8156,9 +8290,9 @@ var schema4 = {
   include_hidden: z5.boolean().optional(),
   limit: z5.number().optional().describe("Max entries to return (1–1000, default 200). Out-of-range values return an `INVALID_ARGUMENT` envelope."),
   wait_timeout_ms: z5.number().optional().describe("Max milliseconds to wait for indexing (0–60000, default 20000). On an `INDEXING` error envelope, retry with a longer timeout or pass a version from `details.availableVersions`."),
-  format: z5.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact paths-only listing tuned for agent context efficiency. Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
+  format: z5.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact paths-only listing. Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. Errors stay JSON-formatted in either mode for now.')
 };
-var DESCRIPTION4 = "List files in an indexed dependency. Default response is a compact " + 'paths-only listing (`format: "text-v1"`); pass `format: "json"` ' + "for the structured envelope `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "Address via `target.registry` + `target.package_name` (package " + "scope) or `target.repo_url` + `target.git_ref` (repo scope), " + "mutually exclusive. Narrow with `path`, `path_prefix`, `globs`, " + "`extensions`, `file_types`, `languages`, or file-intent filters. " + "The returned paths feed directly into `code_read` and help scope " + "`code_grep`. Returns an `INDEXING` error envelope when the " + "dependency is being indexed on-demand — retry with a longer " + "`wait_timeout_ms` or use a version from `details.availableVersions`.";
+var DESCRIPTION4 = "List files in an indexed dependency. Use this to discover paths " + "before `code_read` (when `code_read` returns `FILE_NOT_FOUND` or " + "you don't yet know the path) and to scope `code_grep`. Address " + "via `target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + `target.git_ref` (repo scope), mutually " + "exclusive. Narrow with `path`, `path_prefix`, `globs`, " + "`extensions`, `file_types`, `languages`, or file-intent filters. " + "JSON envelope shape: `{total, hasMore, files: [{path, name, " + "language, fileType, byteSize}], resolution, indexedVersion}`. " + "Returns an `INDEXING` error envelope when the dependency is being " + "indexed on-demand — retry with a longer `wait_timeout_ms` or use " + "a version from `details.availableVersions`.";
 function createListFilesTool(service) {
   return {
     name: "code_files",
@@ -8451,11 +8585,11 @@ function formatPackageChangelogTerminal(envelope, options) {
   const dateWidth = 10;
   for (const entry of envelope.entries.items) {
     const version2 = entry.version ?? "(unversioned)";
-    const date = entry.publishedAt ? formatDate(entry.publishedAt) : dim("—", options.useColors);
+    const date = entry.publishedAt ? formatDate(entry.publishedAt) : dim("-", options.useColors);
     const url = entry.htmlUrl ? dim(entry.htmlUrl, options.useColors) : dim("(no link)", options.useColors);
     const padded = padColumn(version2, versionWidth);
     const datePadded = padColumn(date, dateWidth);
-    lines.push(`${colorize(padded, "bold", options.useColors)}  ${datePadded}  ${url}`);
+    lines.push(`${highlight(`${padded}  ${datePadded}`, options.useColors)}  ${url}`);
     if (entry.body != null) {
       appendBodyLines(lines, entry.body, options);
     }
@@ -8472,28 +8606,28 @@ function appendBodyLines(lines, body, options) {
   }
   const bodyLines = body.split(`
 `);
-  const cap = options.verbose ? bodyLines.length : DEFAULT_BODY_PREVIEW_LINES;
+  const cap = options.verbose ? bodyLines.length : options.bodyPreviewLines ?? DEFAULT_BODY_PREVIEW_LINES;
   const visible = bodyLines.slice(0, cap);
   for (const bodyLine of visible) {
-    lines.push(`  ${dim(bodyLine, options.useColors)}`);
+    lines.push(`  ${bodyLine}`);
   }
   const hidden = bodyLines.length - visible.length;
   if (hidden > 0) {
-    lines.push(`  ${dim(`… (+${hidden} more line${hidden === 1 ? "" : "s"} — ${options.fullBodyHint ?? "use --verbose for the full body"})`, options.useColors)}`);
+    lines.push(`  ${dim(`... (+${hidden} more line${hidden === 1 ? "" : "s"} - ${options.fullBodyHint ?? "use --verbose for the full body"})`, options.useColors)}`);
   }
 }
 function buildSummaryLine(envelope, options) {
-  const identity = envelope.registry && envelope.name ? `${envelope.name} · ${envelope.registry}` : envelope.repoUrl ?? "(unknown)";
+  const identity = envelope.registry && envelope.name ? `${envelope.name} | ${envelope.registry}` : envelope.repoUrl ?? "(unknown)";
   const sourceLabel = envelope.source ? humanizeSource(envelope.source) : "package versions";
   const modeLabel = envelope.mode === "range" ? rangeLabel(envelope) : latestLabel(envelope);
   const countLabel = `${envelope.entries.count} ${plural2("entry", "entries", envelope.entries.count)}`;
   const parts = [identity, `source: ${sourceLabel}`, modeLabel, countLabel];
-  return colorize(parts.join(" · "), "bold", options.useColors);
+  return colorize(parts.join(" | "), "bold", options.useColors);
 }
 function rangeLabel(envelope) {
   const from = envelope.filter?.fromVersion ?? "earliest";
   const to = envelope.filter?.toVersion ?? "latest";
-  return `range ${from} → ${to}`;
+  return `range ${from} -> ${to}`;
 }
 function latestLabel(envelope) {
   if (envelope.filter?.toVersion) {
@@ -8552,9 +8686,11 @@ var schema6 = {
   limit: z7.number().optional().describe("Latest-mode cap on entry count (1–50, default 10). Rejected with `INVALID_ARGUMENT` when `from_version` is also set or when out of range."),
   git_ref: z7.string().optional().describe("Git branch or tag for CHANGELOG.md source (no effect on GitHub Releases or HexDocs). Defaults to the repository's default branch."),
   include_bodies: z7.boolean().optional().describe("When false, each entry in `entries.items[]` omits its `body` field. Default true. Set false when you only need the version / date / URL timeline — drops 10 KB+ per entry on large release notes."),
-  format: z7.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
+  verbose: z7.boolean().optional().describe("Text output only. Show full body previews. Mutually exclusive with include_bodies:false and body_lines."),
+  body_lines: z7.number().optional().describe("Text output only. Number of body lines to preview per entry (1-50, default 10). Ignored for format=json and include_bodies:false. Mutually exclusive with verbose:true."),
+  format: z7.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact entry timeline with body previews. Pass `format: "json"` for the structured envelope with full markdown bodies.')
 };
-var DESCRIPTION6 = "Release notes for a package or GitHub repo, newest-first. Default " + "latest mode returns the ten most recent entries (`limit` 1–50). " + "With `from_version`, returns every entry in the " + "`[from_version, to_version]` range (range mode, no count cap). " + "Address via `registry` + `package_name` or `repo_url` (mutually " + 'exclusive). Response includes optional `source` (`"releases"` / ' + '`"changelog_file"` / `"hexdocs"`) when a concrete changelog source ' + 'exists, `mode` (`"latest"` or `"range"`), ' + 'and entries with markdown body previews. Pass `format: "json"` ' + "for the structured envelope with full markdown bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only. " + "Package-version entries without changelog text succeed with `source` " + "omitted; no-source plus no entries returns `NOT_FOUND`. Supports npm, " + "PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, Packagist, RubyGems, Go.";
+var DESCRIPTION6 = "Release notes for a package or GitHub repo, newest-first. Default " + "latest mode returns the ten most recent entries (`limit` 1–50). " + "With `from_version`, returns every entry in the " + "`[from_version, to_version]` range (range mode, no count cap). " + "Address via `registry` + `package_name` or `repo_url` (mutually " + 'exclusive). Response includes optional `source` (`"releases"` / ' + '`"changelog_file"` / `"hexdocs"`) when a concrete changelog source ' + 'exists, `mode` (`"latest"` or `"range"`), and entries with ' + "markdown body previews. Example: " + '`{"registry":"npm","package_name":"express","limit":2}`. ' + "Text output previews 10 body lines by default; use `body_lines` " + "to tune the preview or `verbose:true` for full text bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only; " + 'pass `format: "json"` for the complete structured envelope. ' + "Package-version entries without changelog " + "text succeed with `source` omitted; no-source plus no entries " + "returns `NOT_FOUND`. Supports npm, PyPI, Hex, Crates, NuGet, " + "Maven, Zig, vcpkg, Packagist, RubyGems, and Go.";
 function createPackageChangelogTool(service) {
   return {
     name: "pkg_changelog",
@@ -8563,6 +8699,8 @@ function createPackageChangelogTool(service) {
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
+        const textFormat = isTextFormat5(args.format);
+        const bodyPreviewLines = textFormat ? validateTextOptions(args) : undefined;
         const { params, explicitFilterFields } = buildPackageChangelogParams({
           registry: args.registry,
           packageName: args.package_name,
@@ -8585,11 +8723,12 @@ function createPackageChangelogTool(service) {
           limit: params.limit,
           gitRef: params.gitRef
         });
-        if (isTextFormat5(args.format)) {
+        if (textFormat) {
           return textResult(formatPackageChangelogTerminal(payload, {
             useColors: false,
-            verbose: false,
-            fullBodyHint: 'pass format="json" for full bodies'
+            verbose: args.verbose ?? false,
+            bodyPreviewLines,
+            fullBodyHint: 'pass verbose=true, body_lines=<n>, or format="json" for full bodies'
           }).trimEnd());
         }
         return textResult(JSON.stringify(payload));
@@ -8613,22 +8752,36 @@ function createPackageChangelogTool(service) {
     }
   };
 }
+function validateTextOptions(args) {
+  if (args.include_bodies === false && args.verbose === true) {
+    throw new InvalidPackageSpecError("verbose:true conflicts with include_bodies:false because bodies are omitted. Drop one of the two options.");
+  }
+  if (args.verbose === true && args.body_lines !== undefined) {
+    throw new InvalidPackageSpecError("body_lines conflicts with verbose:true because verbose already shows full bodies. Drop one of the two options.");
+  }
+  if (args.body_lines === undefined)
+    return;
+  if (!Number.isInteger(args.body_lines) || args.body_lines < 1 || args.body_lines > 50) {
+    throw new InvalidPackageSpecError(`body_lines must be an integer between 1 and 50. Got ${args.body_lines}.`);
+  }
+  return args.body_lines;
+}
 function isTextFormat5(format) {
   return format === undefined || format === "text" || format === "text-v1";
 }
 // src/tools/package-dependencies.ts
 import { z as z8 } from "zod";
 var schema7 = {
-  registry: z8.string().describe(`Package registry. Dependency data is available on ${SUPPORTED_DEPS_REGISTRIES_HUMAN}.`),
+  registry: z8.string().describe(`Package registry. Dependency data is available on ${SUPPORTED_DEPS_REGISTRIES_LIST}.`),
   package_name: z8.string().describe("Package name (scoped names ok: @types/node)."),
   version: z8.string().optional().describe("Specific version to inspect. Defaults to latest when omitted. Tag-style inputs with a leading `v` (for example `v4.18.0`) are rejected — pass the canonical version (`4.18.0`)."),
   lifecycle: z8.union([z8.string(), z8.array(z8.string())]).optional().describe("Lifecycle breadth. Omit for runtime-only. Use `runtime` for explicit runtime-only, a concrete non-runtime lifecycle (`development`, `build`, `peer`, `optional`) for runtime plus matching groups, or `all` for runtime plus all available groups. Accepts a single value, a comma-separated string, or an array; `all` cannot be combined with other values. Uppercase is tolerated."),
   include_transitive: z8.boolean().optional().describe("When true the response gains a `transitive` block with aggregate counts (`edges`, `uniquePackages`), the preprocessed `packages[]` list (each `{name, version}` — the complete install footprint), plus typed `conflicts[]` (`{name, requiredVersions}`) and `circularDependencies[]` (`{cycle: string[]}`) when the backend reported any. Off by default."),
   include_importers: z8.boolean().optional().describe("Requires `include_transitive: true`. When true, each entry in `transitive.packages[]` also carries an `importers` array — every upstream package that pulls it in, with that importer's own resolved version and the constraint it declared. Off by default because adding provenance roughly quadruples the envelope size on heavy graphs. Turn on when you need to trace why a specific transitive dep is present."),
   max_depth: z8.number().int().min(1).max(10).optional().describe("Cap the transitive traversal at this depth (1–10). Omit to get the backend's full graph. Requires `include_transitive: true` — passing `max_depth` without the transitive flag is rejected with `INVALID_ARGUMENT`."),
-  format: z8.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
+  format: z8.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact dependency listing. Pass `format: "json"` for the structured envelope.')
 };
-var DESCRIPTION7 = "Analyze a package's dependency graph. Default output is compact " + "text listing direct runtime dependencies with resolved versions; " + 'pass `format: "json"` for the structured envelope. Non-runtime ' + "groups are omitted by default for token efficiency. Use `lifecycle` " + "with a concrete value for runtime plus matching groups, or `all` " + "for runtime plus all available groups. Set " + "`include_transitive: true` to add a `transitive` block with the " + "full install footprint, conflict detection, and circular-" + "dependency flags; layer `include_importers: true` on top when you " + "also need per-package provenance. Supports npm, PyPI, Hex, Crates, " + "RubyGems, Go, vcpkg, and Zig.";
+var DESCRIPTION7 = "Analyze a package's dependency graph. Lists direct runtime " + "dependencies with resolved versions; non-runtime groups are " + "omitted by default. Use `lifecycle` with a concrete value for " + "runtime plus matching groups, or `all` for runtime plus every " + "available group. Set `include_transitive: true` to add a " + "`transitive` block with the full install footprint, conflict " + "detection, and circular-dependency flags; layer " + "`include_importers: true` on top when you also need per-package " + "provenance. Supports npm, PyPI, Hex, Crates, Zig, vcpkg, RubyGems, " + "and Go.";
 function createPackageDependenciesTool(service) {
   return {
     name: "pkg_deps",
@@ -8701,9 +8854,10 @@ import { z as z9 } from "zod";
 var schema8 = {
   registry: z9.string().describe(`Package registry. One of: ${PKGSEER_REGISTRY_LIST}.`),
   package_name: z9.string().describe("Package name (scoped names ok: @types/node)."),
-  format: z9.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
+  verbose: z9.boolean().optional().describe("Text only. Adds GitHub language/topics/last-pushed, recent advisories, and recent changes. Ignored for format=json."),
+  format: z9.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact package overview. Pass `format: "json"` for the structured envelope.')
 };
-var DESCRIPTION8 = "Get a package overview — latest version, license, description, " + "repository, downloads, GitHub stars, install command, recent " + "changes, and a count of known vulnerabilities. Use before " + "recommending a package or to orient on what a dependency is. " + 'Default output is compact text; pass `format: "json"` for the ' + "structured envelope. " + "Works across npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, " + "RubyGems, Go, vcpkg, and Zig. Always returns data for the latest published " + "version.";
+var DESCRIPTION8 = "Latest-version package overview for dependency triage. Provide " + "`registry` and `package_name` (for example `npm` + `express`). " + "Default text returns license, description, repository popularity " + "(stars/forks/issues and [ARCHIVED] when applicable), downloads, " + "publish age, and vulnerability status. Set `verbose: true` for " + "GitHub language/topics/last-pushed, recent advisories, and recent " + 'changes. Pass `format: "json"` for structured fields. Use ' + "`pkg_vulns` for version-specific vulnerability details.";
 function createPackageSummaryTool(service) {
   return {
     name: "pkg_info",
@@ -8720,6 +8874,7 @@ function createPackageSummaryTool(service) {
         const payload = buildPackageSummarySuccessPayload(summary);
         if (isTextFormat7(args.format)) {
           return textResult(formatPackageSummaryTerminal(summary, {
+            verbose: args.verbose,
             useColors: false
           }).trimEnd());
         }
@@ -8750,14 +8905,16 @@ function isTextFormat7(format) {
 // src/tools/package-vulnerabilities.ts
 import { z as z10 } from "zod";
 var schema9 = {
-  registry: z10.string().describe("Package registry. Vulnerability data available on npm, pypi, hex, and crates only."),
+  registry: z10.string().describe("Package registry. Vulnerability data is unavailable for vcpkg and zig."),
   package_name: z10.string().describe("Package name (scoped names ok: @types/node)."),
   version: z10.string().optional().describe("Specific version to check. Defaults to latest when omitted."),
   min_severity: z10.string().optional().describe("Only return advisories at or above this severity (`low`, `medium`, `high`, `critical`; uppercase tolerated). Omit to see all, including null-severity advisories."),
   include_withdrawn: z10.boolean().optional().describe("Include retracted advisories (default: false)."),
-  format: z10.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` is compact for agents. Pass `json` for the structured envelope.")
+  advisory_scope: z10.string().optional().describe("Advisory rows to return: `affected` (default), `non_affecting` for historical advisories that do not affect the inspected version, or `all` for both affected and historical advisories. Counts always include affected/non-affecting/all totals."),
+  verbose: z10.boolean().optional().describe("Text output only. Show every advisory and full detail rows; format=json always returns the complete structured envelope."),
+  format: z10.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact advisory summary. Pass `format: "json"` for the structured envelope.')
 };
-var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, or " + "Crates (other registries are not yet supported for vulnerability " + "data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate " + "bucket. Pass `version` to inspect a specific release; otherwise " + "the latest is checked. Use `min_severity` to filter to a threshold " + "(`low`, `medium`, `high`, `critical`) and `include_withdrawn` to " + "also see retracted advisories. Default output is compact text; " + 'pass `format: "json"` for the structured envelope.';
+var DESCRIPTION9 = "Check known vulnerabilities for a package on npm, PyPI, Hex, " + "Crates, NuGet, Maven, Packagist, RubyGems, or Go (vcpkg and Zig " + "are not supported for vulnerability data). Returns a count summary, each advisory with OSV ID, " + "severity, affected ranges, and fix versions. Malicious-package " + "advisories surface in a separate bucket. Example: " + '`{"registry":"npm","package_name":"lodash","version":"4.17.20","min_severity":"high"}`. ' + "Pass `version` to inspect " + "a pinned release; omit it for latest. Default text is capped for " + "readability; use `verbose:true` for all selected advisory rows or " + '`format:"json"` for the complete envelope. Use ' + "`min_severity` to filter to a threshold (`low`, `medium`, `high`, " + "`critical`) and `include_withdrawn` to also see retracted " + 'advisories. Use `advisory_scope:"non_affecting"` to list ' + "historical advisories that do not affect the inspected version, or " + '`advisory_scope:"all"` to list affected and historical advisories together.';
 function createPackageVulnerabilitiesTool(service) {
   return {
     name: "pkg_vulns",
@@ -8766,21 +8923,26 @@ function createPackageVulnerabilitiesTool(service) {
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
-        const { params } = buildPackageVulnerabilitiesParams({
+        const { params, filter } = buildPackageVulnerabilitiesParams({
           registry: args.registry,
           packageName: args.package_name,
           version: args.version,
           minSeverity: args.min_severity,
-          includeWithdrawn: args.include_withdrawn
+          includeWithdrawn: args.include_withdrawn,
+          advisoryScope: args.advisory_scope
         });
         const report = await service.packageVulnerabilities(params);
         const payload = buildPackageVulnerabilitiesSuccessPayload(report, {
-          requestedVersion: args.version
+          requestedVersion: args.version,
+          filter
         });
         if (isTextFormat8(args.format)) {
           return textResult(formatPackageVulnerabilitiesTerminal(report, {
             useColors: false,
-            requestedVersion: args.version
+            requestedVersion: args.version,
+            filter,
+            verbose: args.verbose,
+            surface: "mcp"
           }).trimEnd());
         }
         return textResult(JSON.stringify(payload));
@@ -8900,7 +9062,8 @@ function shouldEmitCappedHint(bounded, payload) {
 }
 function buildCappedHint(payload, originalStart, originalEnd) {
   const requested = describeRequest(originalStart, originalEnd);
-  return `Returned lines ${payload.startLine}-${payload.endLine}/${payload.totalLines} ` + `(MCP cap: ${MCP_READ_MAX_SPAN} lines per call; you requested ${requested}). ` + `Pick a focused start_line/end_line window — typical 80-150 lines around a search/code_grep match. ` + `Each retry also costs context, so aim for one well-sized read.`;
+  const continuation = payload.endLine !== undefined ? ` To continue, retry with start_line=${payload.endLine + 1}.` : "";
+  return `Returned lines ${payload.startLine}-${payload.endLine}/${payload.totalLines} ` + `(MCP cap: ${MCP_READ_MAX_SPAN} lines per call; you requested ${requested}).` + `${continuation} ` + `Pick a focused start_line/end_line window — typical 80-150 lines around a search/code_grep match. ` + `Each retry also costs context, so aim for one well-sized read.`;
 }
 function describeRequest(originalStart, originalEnd) {
   if (originalStart === undefined && originalEnd === undefined) {
@@ -9031,9 +9194,9 @@ var schema12 = {
   limit: z13.coerce.number().int().min(1).max(100).optional().describe("Maximum results to return (default 10, max 100)."),
   offset: z13.coerce.number().int().min(0).optional(),
   wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional(),
-  format: z13.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output tuned for agent context efficiency. Pass `format: "json"` for the structured envelope (programmatic consumers, parity testing). `text` is an alias for `text-v1`. The text format is a public, snapshot-tested contract.')
+  format: z13.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output. Pass `format: "json"` for the structured envelope. `text` is an alias for `text-v1`. The text format is a public, snapshot-tested contract.')
 };
-var DESCRIPTION12 = "Search indexed dependency and repository code, docs, and explicit symbols. " + "Provide either `target` for one target or `targets` for many; omit `sources` to use backend AUTO. " + "The query field uses GitHits discovery syntax (AND/OR/parens/qualifiers; see the parameter description). " + "Structured parameters combine with that query using AND semantics. " + "Results are complete by default — if indexing is still running, the response carries a `searchRef` and no hits; pass it to `search_status` to follow up. " + "Set `allow_partial_results: true` to opt into hits from sources that finished while others continue indexing. " + "Each hit's `type` tells you the follow-up tool: `documentation_page` and `repository_doc` → `docs_read` with `locator.pageId`; `repository_code` and `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present).";
+var DESCRIPTION12 = "Search indexed dependency and repository code, docs, and explicit symbols. " + "Provide either `target` for one target or `targets` for many; omit `sources` to use backend AUTO. " + "Structured parameters combine with the `query` using AND semantics. " + "Complete by default — if indexing is still running, the response carries a `searchRef` and no hits; pass it to `search_status` to follow up. " + "Set `allow_partial_results: true` to opt into hits from sources that finished while others continue indexing. " + "Each hit's `type` tells you the follow-up tool: `documentation_page` and `repository_doc` → `docs_read` with `locator.pageId`; `repository_code` and `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present).";
 function createSearchTool(service) {
   return {
     name: "search",
@@ -9137,7 +9300,7 @@ function isTextFormat11(format) {
 import { z as z14 } from "zod";
 var schema13 = {
   query: z14.string().min(1).describe('Language name or partial name to search for (e.g., "python", "type", "java")'),
-  format: z14.enum(["json", "text", "text-v1"]).optional().describe("Response format. Default `text-v1` returns one language per line. Pass `json` for the structured array.")
+  format: z14.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` returns one language per line. Pass `format: "json"` for the structured array.')
 };
 var DESCRIPTION13 = `Find the correct language name for \`get_example\` when it is uncertain. Returns up to 5 matching languages by name, display name, or alias. Default output is one language per line; pass \`format: "json"\` for the structured array.`;
 function createSearchLanguageTool(service) {
@@ -9173,10 +9336,10 @@ function renderLanguageMatches(matches) {
 // src/tools/search-status.ts
 import { z as z15 } from "zod";
 var schema14 = {
-  search_ref: z15.string().min(1).describe("Search reference returned by search."),
+  search_ref: z15.string().min(1).describe("The `searchRef` field from a prior `search` response (camelCase in the response, snake_case as this parameter). Pass it through unchanged."),
   format: z15.enum(["json", "text", "text-v1"]).optional().describe('Response format. Default `text-v1` — compact line-oriented output matching `search`. Pass `format: "json"` for the structured envelope.')
 };
-var DESCRIPTION14 = "Check progress, fetch partial hits when the original request used allow_partial_results: true, or fetch final results for a prior unified search. " + "Pass the search_ref returned by `search` when the original request did not complete within the wait window.";
+var DESCRIPTION14 = "Check progress, fetch partial hits (when the original request used `allow_partial_results: true`), or fetch final results for a prior `search` that returned a `searchRef`. " + "Pass the `searchRef` from that response as `search_ref` here (response field is camelCase; this parameter is snake_case).";
 function createSearchStatusTool(service) {
   return {
     name: "search_status",
@@ -9201,50 +9364,54 @@ function isTextFormat13(format) {
   return format === undefined || format === "text" || format === "text-v1";
 }
 // src/commands/mcp-instructions.ts
-var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source. Use it for global solution synthesis and canonical examples when you're stuck, repeated attempts failed, you need up-to-date API usage, the question is comparative across OSS projects (e.g. "how does X vs Y handle Z"), the answer requires reading how a real codebase implements a feature, or the user mentions GitHits.
+var CORE_BLOCK = `GitHits provides verified, canonical code examples from global open source for AI agents. Pick a path:
+
+- Need a canonical example or cross-project pattern with no specific package pinned (you're stuck, repeated attempts failed, the user wants up-to-date API usage, or the user mentioned GitHits) — call \`get_example\` for global solution synthesis.
+- Inspecting a specific known dependency or repository (stack trace points there, verifying how a particular library works, evaluating an upgrade) — call \`search\` plus the indexed code, docs, and package tools listed below.
+- Question is comparative across OSS projects (e.g. "how does X vs Y handle Z") or requires reading how a real codebase implements a feature — combine the two: \`search\` for known targets, \`get_example\` for cross-project synthesis.
+- Rate a result or share tool/UX feedback — call \`feedback\` with a \`solution_id\` from a prior \`get_example\` response (solution-tied) or omit it for generic feedback about any tool (\`search\`, \`code_*\`, \`docs_*\`, \`pkg_*\`) or the overall experience.
 
-Example workflow: call \`get_example\` with one focused question; pass \`language\` only when you know the exact language name, otherwise call \`search_language\` first. Default output is markdown with a trailing \`solution_id\`; send \`feedback\` on that solution_id. Reuse prior results before searching again. For dependency-specific grounding, use package-scoped \`search\` before global \`get_example\`.`;
+\`get_example\` workflow: pass \`language\` only when you know the exact name; otherwise call \`search_language\` first. Default output is markdown with a trailing \`solution_id\`. Reuse prior results before searching again. For dependency-specific grounding, prefer package-scoped \`search\` before global \`get_example\`.`;
 var PACKAGE_TOOLS_PREAMBLE = `Indexed package/source tools inspect third-party dependency source, docs, and registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library works, or you're evaluating whether to add or upgrade a package.
 
 Package spec: \`registry:name[@version]\`. Default outputs are compact \`text-v1\` for agent context efficiency; pass \`format: "json"\` only when you need structured fields for programmatic parsing.`;
-var PKG_INFO_BULLET = '- `pkg_info` — compact package overview: latest version, license, downloads, quickstart, and active advisory count. Pass `format: "json"` for the structured envelope.';
-var DOCS_LIST_BULLET = "- `docs_list` — browse hosted and repository-backed package docs. Entries include stable pageIds, source URLs, and repo-file follow-up metadata when available.";
-var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. Works for both hosted docs and repo-backed docs.";
-var PKG_VULNS_BULLET = '- `pkg_vulns` — compact known CVE / OSV advisory summary for npm, PyPI, Hex, or Crates packages, optionally pinned to `version`. Filter with `min_severity`; include retracted advisories with `include_withdrawn`. Pass `format: "json"` for per-advisory structured fields.';
-var PKG_DEPS_BULLET = '- `pkg_deps` — compact direct runtime deps by default. Use `lifecycle: "runtime"` for explicit runtime-only, a concrete lifecycle for runtime plus matching non-runtime deps, or `lifecycle: "all"` for all groups. Use `include_transitive` for the full graph and `include_importers` for provenance. Pass `format: "json"` for the structured envelope.';
-var PKG_CHANGELOG_BULLET = '- `pkg_changelog` — compact release notes for a package or GitHub repo, newest-first. Default latest mode returns recent entries with markdown body previews; `from_version` switches to range mode. Set `include_bodies: false` for a compact timeline or pass `format: "json"` for full bodies.';
+var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation work (`search`, `code_grep`, `code_read`, `code_files`) often takes 3-10 calls. For cross-project comparisons, codebase mapping, pattern surveys, or "how does X actually work" investigations, spawn a sub-task/sub-agent and ask for a compact synthesis. Do it inline only when the raw snippet belongs in the main conversation.';
 var SEARCH_BULLET = '- `search` — unified search across indexed dependency code, docs, and symbols. Omit `sources` for AUTO. Use `sources:["code"]` for implementation/examples/tests text, `sources:["symbol"]` for precise API/entity lookup, and `sources:["docs"]` for guides/reference/changelogs. Default output is compact `text-v1` with ready-to-call follow-up arguments; pass `format: "json"` for structured locators, highlights, and source status. Complete by default; opt into partial hits with `allow_partial_results: true`. Incomplete responses carry a `searchRef`.';
 var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior `search` by `searchRef` to check progress, fetch partial hits, or fetch final results.";
-var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. `path`, `path_prefix`, and `globs` are OR-ed selectors; extensions, language, file type, and file-intent filters intersect on top. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
-var CODE_READ_BULLET = "- `code_read` — read a dependency file by `path`. **MCP cap: 150 lines per call**; choose focused `start_line` / `end_line` windows from `search` or `code_grep`. Binary files set `isBinary: true` and omit `content`. On `FILE_NOT_FOUND` / `NOT_FOUND`, call `code_files` for the actual path.";
 var CODE_GREP_BULLET = "- `code_grep` — deterministic text or regex grep over indexed source. Use it when you know the pattern; use `search` for discovery. Narrow with `path`, `path_prefix`, `globs`, or `extensions`. Each match's `path:line` chains into `code_read`.";
-var SEARCH_VS_SYMBOLS_TIP = 'Use code-first grounding for behavioral claims: source, symbols, tests, examples, and call sites beat docs prose. Prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Prefer `get_example` for global canonical example retrieval after package-scoped grounding. Use `code_grep` for deterministic text matching and `code_read` for focused-window inspection of a known file.';
-var REFERENCE_FIRST_TIP = "Strategy — reference-first, content-second. Locate symbols and lines with `search` / `code_grep` first, then read only the needed window with `code_read` using explicit `start_line` / `end_line` values, typically 80-150 lines around the match. The MCP `code_read` surface caps each call at 150 lines.";
-var MULTI_TURN_TIP = '**Delegate multi-call work to a sub-agent.** Code-navigation work (`search`, `code_grep`, `code_read`, `code_files`) often takes 3-10 calls. For cross-project comparisons, codebase mapping, pattern surveys, or "how does X actually work" investigations, spawn a sub-task/sub-agent and ask for a compact synthesis. Do it inline only when the raw snippet belongs in the main conversation.';
+var CODE_READ_BULLET = "- `code_read` — read a dependency file by `path`. **MCP cap: 150 lines per call**. When you already have an exact path (e.g. from a stack trace), call this directly; otherwise locate it first with `search` or `code_grep` and pick a focused `start_line` / `end_line` window. Binary files set `isBinary: true` and omit `content`. On `FILE_NOT_FOUND` / `NOT_FOUND`, call `code_files` for the actual path.";
+var CODE_FILES_BULLET = '- `code_files` — list files in an indexed dependency. `path`, `path_prefix`, and `globs` are OR-ed selectors; extensions, language, file type, and file-intent filters intersect on top. Returned paths feed into `code_read` and help scope `code_grep`; pass `format: "json"` for language/type/size metadata.';
+var DOCS_LIST_BULLET = "- `docs_list` — browse hosted and repository-backed package docs. Entries include stable pageIds, source URLs, and repo-file follow-up metadata when available.";
+var DOCS_READ_BULLET = "- `docs_read` — read a documentation page by pageId. Works for both hosted docs and repo-backed docs.";
+var PKG_INFO_BULLET = '- `pkg_info` — latest-version package triage by `registry` + `package_name` (e.g. `npm` + `express`): license, repository popularity, downloads, publish age, and vulnerability status. Set `verbose: true` for GitHub language/topics/last-pushed, recent advisories, and recent changes; pass `format: "json"` for structured fields.';
+var PKG_VULNS_BULLET = '- `pkg_vulns` — compact known CVE / OSV advisory summary for npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, or Go packages; vcpkg and Zig are not supported. Optionally pin `version` (e.g. `npm` + `lodash` + `4.17.20`). Filter with `min_severity`; include retracted advisories with `include_withdrawn`; set `advisory_scope: "non_affecting"` for historical advisories or `"all"` for affected + historical rows. Default text is capped; use `verbose: true` for all selected rows or `format: "json"` for the complete per-advisory envelope.';
+var PKG_DEPS_BULLET = '- `pkg_deps` — compact direct runtime deps by default. Use `lifecycle: "runtime"` for explicit runtime-only, a concrete lifecycle for runtime plus matching non-runtime deps, or `lifecycle: "all"` for all groups. Use `include_transitive` for the full graph and `include_importers` for provenance. Pass `format: "json"` for the structured envelope.';
+var PKG_CHANGELOG_BULLET = '- `pkg_changelog` — compact release notes for a package or GitHub repo, newest-first (e.g. `npm` + `express` + `limit: 2`). Default latest mode returns recent entries with 10-line markdown previews; `from_version` switches to range mode. Set `body_lines` to tune text previews, `verbose: true` for full text bodies, `include_bodies: false` for a compact timeline, or `format: "json"` for the complete envelope.';
+var STRATEGY_TIP = 'Strategy — reference-first. Locate symbols and lines with `search` or `code_grep` first, then read the needed window with `code_read` using explicit `start_line` / `end_line` (typical 80-150 lines around the match; the MCP `code_read` surface caps each call at 150 lines). Source, symbols, tests, and call sites beat docs prose for behavioral claims; use `sources:["symbol"]` when you want symbol-shaped results, `code_grep` for deterministic text matching, and `get_example` for global canonical examples after package-scoped grounding.';
 function buildMcpInstructions(_deps) {
-  const sections = [CORE_BLOCK];
-  const bullets = [];
-  bullets.push(DOCS_LIST_BULLET);
-  bullets.push(DOCS_READ_BULLET);
-  bullets.push(PKG_INFO_BULLET);
-  bullets.push(PKG_VULNS_BULLET);
-  bullets.push(PKG_DEPS_BULLET);
-  bullets.push(PKG_CHANGELOG_BULLET);
-  bullets.push(SEARCH_BULLET);
-  bullets.push(SEARCH_STATUS_BULLET);
-  bullets.push(CODE_FILES_BULLET);
-  bullets.push(CODE_READ_BULLET);
-  bullets.push(CODE_GREP_BULLET);
-  const parts = [PACKAGE_TOOLS_PREAMBLE];
-  parts.push(MULTI_TURN_TIP);
-  parts.push(bullets.join(`
-`));
-  parts.push(REFERENCE_FIRST_TIP);
-  parts.push(SEARCH_VS_SYMBOLS_TIP);
-  sections.push(parts.join(`
+  const bullets = [
+    SEARCH_BULLET,
+    SEARCH_STATUS_BULLET,
+    CODE_GREP_BULLET,
+    CODE_READ_BULLET,
+    CODE_FILES_BULLET,
+    DOCS_LIST_BULLET,
+    DOCS_READ_BULLET,
+    PKG_INFO_BULLET,
+    PKG_VULNS_BULLET,
+    PKG_DEPS_BULLET,
+    PKG_CHANGELOG_BULLET
+  ];
+  const packageSection = [
+    PACKAGE_TOOLS_PREAMBLE,
+    MULTI_TURN_TIP,
+    bullets.join(`
+`),
+    STRATEGY_TIP
+  ].join(`
 
-`));
-  return sections.join(`
+`);
+  return [CORE_BLOCK, packageSection].join(`
 
 `);
 }
@@ -9443,7 +9610,7 @@ function formatChangelogTerminalError(mapped) {
   if (available && available.length > 0) {
     const sample = available.slice(0, 5).join(", ");
     const more = available.length - 5;
-    const suffix = more > 0 ? `, … (+${more} more)` : "";
+    const suffix = more > 0 ? `, ... (+${more} more)` : "";
     lines.push(`  available: ${sample}${suffix}`);
   }
   return lines.join(`
@@ -9582,8 +9749,7 @@ groups). Concrete --lifecycle values include runtime plus matching groups.
 conflict detection, and circular-dependency flags.
 
 Package spec: <registry>:<name>[@<version>]. Supported registries:
-npm, pypi, hex, crates, vcpkg, zig, rubygems, go. Omit @<version> for the latest
-release.`;
+${SUPPORTED_DEPS_REGISTRIES_LIST}. Omit @<version> for the latest release.`;
 function registerPkgDepsCommand(pkgCommand) {
   return pkgCommand.command("deps").summary("Analyze dependencies for a package").description(PKG_DEPS_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or npm:express@4.18.0").option("-l, --lifecycle <phases>", "Dependency lifecycle breadth (runtime, development, build, peer, optional, all; comma-separated for multi-select except all).").option("-t, --transitive", "Include aggregate transitive counts, conflicts, and circular dependencies").option("--depth <n>", "Cap transitive traversal depth (1-10). Omit for the full graph.").option("-v, --verbose", "Show conditionType / selectionMode / environmentConstraints metadata in the groups view").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
     const deps = await createContainer();
@@ -9640,16 +9806,20 @@ function handlePkgInfoCommandError(error2, json) {
   console.error(formatMappedErrorForTerminal(mapped));
   process.exit(1);
 }
-var PKG_INFO_DESCRIPTION = `Get a package overview — latest version, license, description,
-repository, downloads, GitHub stars, install command, and known
-vulnerabilities. Use before picking a dependency or to orient on what
-a package is.
+var PKG_INFO_DESCRIPTION = `Latest-version package overview for dependency triage.
+
+Default output shows license, description, repository popularity
+(stars/forks/issues and [ARCHIVED] when applicable), downloads,
+publish age, and vulnerability status. --verbose adds GitHub
+language/topics/last-pushed, recent advisories, and recent changes.
 
 Package spec: <registry>:<name>. Supported registries: ${PKGSEER_REGISTRY_LIST}.
 
+Example: githits pkg info npm:express
+
 Always returns data for the latest published version.`;
 function registerPkgInfoCommand(pkgCommand) {
-  return pkgCommand.command("info").summary("Show a package overview").description(PKG_INFO_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or pypi:requests").option("-v, --verbose", "Show advisories, install usage, topics, and recent changes").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
+  return pkgCommand.command("info").summary("Show a package overview").description(PKG_INFO_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or pypi:requests").option("-v, --verbose", "Show GitHub language/topics/last-pushed, recent advisories, and recent changes").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
     const deps = await createContainer();
     await pkgInfoAction(spec, options, {
       packageIntelligenceService: deps.packageIntelligenceService,
@@ -9668,17 +9838,19 @@ async function pkgVulnsAction(spec, options, deps) {
       throw new InvalidPackageSpecError("Package intelligence is not configured for this environment.");
     }
     const parsed = parsePackageSpec(spec);
-    const { params } = buildPackageVulnerabilitiesParams({
+    const { params, filter } = buildPackageVulnerabilitiesParams({
       registry: parsed.registry,
       packageName: parsed.name,
       version: parsed.version,
       minSeverity: options.severity,
-      includeWithdrawn: options.includeWithdrawn
+      includeWithdrawn: options.includeWithdrawn,
+      advisoryScope: options.scope
     });
     const report = await deps.packageIntelligenceService.packageVulnerabilities(params);
     if (options.json) {
       const payload = buildPackageVulnerabilitiesSuccessPayload(report, {
-        requestedVersion: parsed.version
+        requestedVersion: parsed.version,
+        filter
       });
       console.log(JSON.stringify(payload));
       return;
@@ -9687,6 +9859,8 @@ async function pkgVulnsAction(spec, options, deps) {
       verbose: options.verbose,
       useColors: shouldUseColors(),
       requestedVersion: parsed.version,
+      filter,
+      surface: "cli",
       terminalWidth: process.stdout.columns
     });
     process.stdout.write(output);
@@ -9729,24 +9903,30 @@ function formatVulnsTerminalError(mapped) {
   if (available && available.length > 0) {
     const sample = available.slice(0, 5).join(", ");
     const more = available.length - 5;
-    const suffix = more > 0 ? `, … (+${more} more)` : "";
+    const suffix = more > 0 ? `, ... (+${more} more)` : "";
     lines.push(`  available: ${sample}${suffix}`);
   }
   return lines.join(`
 `);
 }
 var PKG_VULNS_DESCRIPTION = `Show known vulnerabilities for a package. Lists CVE / OSV advisories
-with severity, affected version ranges, and fix versions.
-Malicious-package advisories are flagged prominently.
+with severity, affected version ranges, and fix versions. Default text is
+capped for readability; use --verbose for all selected advisory rows or --json
+for the complete structured envelope.
 
 Package spec: <registry>:<name>[@<version>]. Supported registries:
-npm, pypi, hex, crates. Omit @<version> to check the latest release.
+npm, pypi, hex, crates, nuget, maven, packagist, rubygems, go. vcpkg and zig are not supported.
+Omit @<version> to check the latest release.
+Example: githits pkg vulns npm:lodash@4.17.20 --severity high
 
 Severity filter (--severity) and withdrawn-advisory visibility
 (--include-withdrawn) are passed through to the backend; the
-returned count reflects whatever survived the filter.`;
+returned count reflects whatever survived the filter and active filters
+are echoed in text and JSON output. Use --scope non_affecting to list
+historical advisories that do not affect the inspected version, or --scope all
+to list affected and historical package advisories together.`;
 function registerPkgVulnsCommand(pkgCommand) {
-  return pkgCommand.command("vulns").summary("List known vulnerabilities for a package").description(PKG_VULNS_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or npm:express@4.18.0").option("-s, --severity <level>", "Only show advisories at or above this severity (low, medium, high, critical). Omit to see all.").option("--include-withdrawn", "Include retracted advisories (default: off)").option("-v, --verbose", "Show aliases, modified/withdrawn dates, and malicious-advisory markers").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
+  return pkgCommand.command("vulns").summary("List known vulnerabilities for a package").description(PKG_VULNS_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express or npm:express@4.18.0").option("-s, --severity <level>", "Only show advisories at or above this severity (low, medium, high, critical). Omit to see all.").option("--scope <scope>", "Advisory rows to return: affected, non_affecting, all (default: affected)").option("--include-withdrawn", "Include retracted advisories (default: off)").option("-v, --verbose", "Show aliases, modified/withdrawn dates, and malicious-advisory markers").option("--json", "Emit the lean JSON envelope").action(async (spec, options) => {
     const deps = await createContainer();
     await pkgVulnsAction(spec, options, {
       packageIntelligenceService: deps.packageIntelligenceService,
@@ -9763,7 +9943,7 @@ async function registerPkgCommandGroup(program, options = {}) {
   if (!registration.shouldRegister) {
     return;
   }
-  const pkgCommand = program.command("pkg").summary("Package metadata: info, vulnerabilities, dependencies, changelog").description("Inspect package metadata from npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, vcpkg, and Zig: overviews, advisories, dependency graphs, and changelogs. For source-level operations inside a dependency, use `githits code`.");
+  const pkgCommand = program.command("pkg").summary("Package metadata: info, vulnerabilities, dependencies, changelog").description("Inspect package metadata from npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, vcpkg, and Zig: overviews, advisories, dependency graphs, and changelogs. Advisory data is unavailable for vcpkg and Zig. For source-level operations inside a dependency, use `githits code`.");
   registerPkgInfoCommand(pkgCommand);
   registerPkgVulnsCommand(pkgCommand);
   registerPkgDepsCommand(pkgCommand);
@@ -9887,7 +10067,7 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-q2mre780.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-kmka6wpx.js");
   return createContainer2();
 }
 function parseTargetSpecs(specs) {