githits 0.2.0 → 0.2.2

package/dist/cli.js

@@ -32,6 +32,7 @@ import {
   flushTelemetry,
   getCodeNavigationCapability,
   getCodeNavigationUrl,
+  getEnvApiToken,
   isCodeNavigationCliOverrideEnabled,
   isTelemetryEnabled,
   refreshExpiredToken,
@@ -40,11 +41,11 @@ import {
   setMcpClientVersionProvider,
   startTelemetrySpan,
   withTelemetrySpan
-} from "./shared/chunk-1t81jdax.js";
+} from "./shared/chunk-ns1j9dan.js";
 import {
   __require,
   version
-} from "./shared/chunk-fa4571ch.js";
+} from "./shared/chunk-g6ay6x9v.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -80,7 +81,6 @@ async function authStatusAction(deps) {
     console.log(`Authenticated via environment variable.
 `);
     console.log(`  Source: GITHITS_API_TOKEN`);
-    console.log(`  Token: ${envApiToken.slice(0, 8)}...`);
     displayCodeNavigationStatus(getCodeNavigationCapability(envApiToken), codeNavigationCliOverrideEnabled);
     return;
   }
@@ -138,10 +138,27 @@ function registerAuthStatusCommand(program) {
     await authStatusAction(deps);
   });
 }
+// src/commands/gated-command-group.ts
+async function resolveGatedCommandGroupRegistrationState(options = {}) {
+  const codeNavigationUrl = options.codeNavigationUrl ?? getCodeNavigationUrl();
+  if (!codeNavigationUrl) {
+    return { codeNavigationUrl: undefined, shouldRegister: false };
+  }
+  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
+  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
+    capability: options.capability ?? "unknown",
+    expiredStoredAuth: options.expiredStoredAuth ?? false
+  } : await resolveStartupCodeNavigationRegistrationState();
+  const envTokenPresent = options.envTokenPresent ?? Boolean(getEnvApiToken());
+  return {
+    codeNavigationUrl,
+    shouldRegister: overrideEnabled || registrationState.capability === "enabled" || envTokenPresent || registrationState.expiredStoredAuth
+  };
+}
+
 // src/shared/code-navigation-defaults.ts
 var DEFAULT_WAIT_TIMEOUT_MS = 20000;
 var MAX_WAIT_TIMEOUT_MS = 60000;
-var SEARCH_SYMBOLS_DEFAULT_FILE_INTENT = "PRODUCTION";
 var FILE_INTENT_ALL = Symbol("FILE_INTENT_ALL");
 
 // src/shared/colors.ts
@@ -299,17 +316,10 @@ var fileIntentMap = {
   build: "BUILD",
   vendor: "VENDOR"
 };
-var matchModeMap = {
-  or: "OR",
-  and: "AND"
-};
 function toCodeNavigationRegistry(registry) {
   return toPkgseerRegistry(registry);
 }
-function toSearchSymbolsMatchMode(mode) {
-  return mode ? matchModeMap[mode] : undefined;
-}
-function toSearchSymbolsKind(kind) {
+function toSymbolKind(kind) {
   return kind ? symbolKindMap[kind] : undefined;
 }
 function toSymbolCategory(category) {
@@ -321,7 +331,7 @@ function knownSymbolKindList() {
 function knownSymbolCategoryList() {
   return Object.keys(symbolCategoryMap);
 }
-function toSearchSymbolsFileIntent(intent) {
+function toFileIntent(intent) {
   return intent ? fileIntentMap[intent] : undefined;
 }
 // src/shared/code-navigation-error-map.ts
@@ -478,6 +488,23 @@ function isInvalidArgumentError(error2) {
     return false;
   return error2.name.startsWith("Invalid") || error2.name.startsWith("Unsupported");
 }
+// src/shared/docs-follow-up.ts
+function lowerDocSourceKind(value) {
+  switch (value) {
+    case "CRAWLED":
+      return "crawled";
+    case "REPOSITORY":
+      return "repo";
+    default:
+      return;
+  }
+}
+// src/shared/extract-solution-id.ts
+var SOLUTION_URL_RE = /solutions\/([0-9a-fA-F-]{36})/;
+function extractSolutionId(markdown) {
+  const match = SOLUTION_URL_RE.exec(markdown);
+  return match?.[1];
+}
 // src/shared/package-spec.ts
 var KNOWN_REGISTRIES = [
   "npm",
@@ -729,19 +756,27 @@ function normalizeWaitTimeoutMs(value) {
 function buildGrepRepoSuccessPayload(result, options) {
   const envelope = {
     pattern: options.pattern,
-    patternType: options.patternType,
-    caseSensitive: options.caseSensitive,
     matches: result.matches.map(projectMatch),
     hasMore: result.hasMore,
-    truncatedReason: result.truncatedReason.toLowerCase(),
-    routeTaken: result.routeTaken?.toLowerCase(),
     filesScanned: result.filesScanned,
     filesInScope: result.filesInScope,
-    binaryFilesSkipped: result.binaryFilesSkipped,
-    filesTooLargeSkipped: result.filesTooLargeSkipped,
     totalMatches: result.totalMatches,
     uniqueFilesMatched: result.uniqueFilesMatched
   };
+  if (options.patternType !== "literal") {
+    envelope.patternType = options.patternType;
+  }
+  if (options.caseSensitive)
+    envelope.caseSensitive = true;
+  if (result.binaryFilesSkipped > 0) {
+    envelope.binaryFilesSkipped = result.binaryFilesSkipped;
+  }
+  if (result.filesTooLargeSkipped > 0) {
+    envelope.filesTooLargeSkipped = result.filesTooLargeSkipped;
+  }
+  if (result.truncatedReason && result.truncatedReason !== "NONE") {
+    envelope.truncatedReason = result.truncatedReason.toLowerCase();
+  }
   if (options.registry)
     envelope.registry = options.registry;
   if (options.name)
@@ -763,19 +798,26 @@ function buildGrepRepoSuccessPayload(result, options) {
   return envelope;
 }
 function projectMatch(match) {
-  return {
+  const projected = {
     filePath: match.filePath,
     line: match.line,
     matchStartByte: match.matchStartByte,
     matchEndByte: match.matchEndByte,
-    lineContent: match.lineContent,
-    contextBefore: match.contextBefore,
-    contextAfter: match.contextAfter,
-    fileContentHash: match.fileContentHash,
-    fileIntent: match.fileIntent,
-    symbolRowId: match.symbolRowId,
-    symbol: match.symbol
+    lineContent: match.lineContent
   };
+  if (match.contextBefore && match.contextBefore.length > 0) {
+    projected.contextBefore = match.contextBefore;
+  }
+  if (match.contextAfter && match.contextAfter.length > 0) {
+    projected.contextAfter = match.contextAfter;
+  }
+  if (match.fileContentHash)
+    projected.fileContentHash = match.fileContentHash;
+  if (match.fileIntent)
+    projected.fileIntent = match.fileIntent;
+  if (match.symbol)
+    projected.symbol = match.symbol;
+  return projected;
 }
 function projectResolution(resolution) {
   if (!resolution)
@@ -1110,39 +1152,191 @@ function filterLanguages(languages, query, limit = DEFAULT_LIMIT) {
   const lowerQuery = query.toLowerCase();
   return languages.filter((lang) => lang.name.toLowerCase().includes(lowerQuery) || lang.display_name.toLowerCase().includes(lowerQuery) || lang.aliases.some((a) => a.toLowerCase().includes(lowerQuery))).slice(0, limit).map(({ name, display_name }) => ({ name, display_name }));
 }
-// src/shared/normalise-keywords.ts
-var MAX_KEYWORDS = 20;
-
-class InvalidKeywordsError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidKeywordsError";
+// src/shared/list-package-docs-request.ts
+function buildListPackageDocsParams(input) {
+  const packageName = input.packageName?.trim() ?? "";
+  if (!packageName) {
+    throw new InvalidPackageSpecError("Package name is required.");
   }
+  const registry = input.registry?.trim().toLowerCase() ?? "";
+  if (!isKnownPkgseerRegistryArg(registry)) {
+    throw new UnsupportedRegistryError(`Unsupported registry '${input.registry}'. Supported: npm, pypi, hex, crates, nuget, maven, zig, vcpkg, packagist.`);
+  }
+  const params = {
+    registry: toPkgseerRegistry(registry),
+    packageName
+  };
+  const version2 = input.version?.trim();
+  if (version2)
+    params.version = version2;
+  const after = input.after?.trim();
+  if (after)
+    params.after = after;
+  if (input.limit !== undefined) {
+    if (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > 500) {
+      throw new InvalidPackageSpecError("Limit must be an integer between 1 and 500.");
+    }
+    params.limit = input.limit;
+  }
+  return {
+    params,
+    limitExplicit: input.limit !== undefined,
+    afterExplicit: Boolean(after)
+  };
 }
-function normaliseKeywords(rawComma, rawRepeated) {
-  const seen = new Set;
-  const out = [];
-  const add = (value) => {
-    const trimmed = value.trim();
-    if (trimmed === "")
-      return;
-    if (seen.has(trimmed))
-      return;
-    seen.add(trimmed);
-    out.push(trimmed);
+// src/shared/format-date.ts
+function toIsoDate(iso) {
+  if (!iso)
+    return null;
+  const parsed = new Date(iso);
+  if (Number.isNaN(parsed.getTime()))
+    return null;
+  return parsed.toISOString().slice(0, 10);
+}
+var MINUTE = 60;
+var HOUR = 60 * MINUTE;
+var DAY = 24 * HOUR;
+var MONTH = 30 * DAY;
+var YEAR = 365 * DAY;
+function toRelativeDate(iso, now = new Date) {
+  if (!iso)
+    return null;
+  const parsed = new Date(iso);
+  if (Number.isNaN(parsed.getTime()))
+    return null;
+  const deltaSeconds = Math.floor((now.getTime() - parsed.getTime()) / 1000);
+  if (deltaSeconds < 0) {
+    return toIsoDate(iso);
+  }
+  if (deltaSeconds < MINUTE)
+    return "just now";
+  if (deltaSeconds < HOUR)
+    return formatUnit(deltaSeconds, MINUTE, "minute");
+  if (deltaSeconds < DAY)
+    return formatUnit(deltaSeconds, HOUR, "hour");
+  if (deltaSeconds < MONTH)
+    return formatUnit(deltaSeconds, DAY, "day");
+  if (deltaSeconds < YEAR)
+    return formatUnit(deltaSeconds, MONTH, "month");
+  return formatUnit(deltaSeconds, YEAR, "year");
+}
+function formatUnit(deltaSeconds, unit, label) {
+  const n = Math.floor(deltaSeconds / unit);
+  return `${n} ${label}${n === 1 ? "" : "s"} ago`;
+}
+
+// src/shared/list-package-docs-response.ts
+function buildListPackageDocsSuccessPayload(result, options) {
+  const envelope = {
+    hasMore: result.pageInfo?.hasNextPage ?? false,
+    pages: result.pages.map((page) => {
+      assertDocListEntry(page);
+      const pageId = page.id;
+      const lastUpdatedAt = toIsoDate(page.lastUpdatedAt);
+      const entry = { pageId };
+      if (page.title)
+        entry.title = page.title;
+      const sourceKind = lowerDocSourceKind(page.sourceKind);
+      if (sourceKind)
+        entry.sourceKind = sourceKind;
+      if (page.sourceUrl)
+        entry.sourceUrl = page.sourceUrl;
+      if (page.repoUrl)
+        entry.repoUrl = page.repoUrl;
+      if (page.gitRef)
+        entry.gitRef = page.gitRef;
+      if (page.requestedRef)
+        entry.requestedRef = page.requestedRef;
+      if (page.filePath)
+        entry.filePath = page.filePath;
+      if (page.linkName)
+        entry.linkName = page.linkName;
+      if (lastUpdatedAt)
+        entry.lastUpdatedAt = lastUpdatedAt;
+      return entry;
+    })
   };
-  if (rawComma !== undefined && rawComma !== "") {
-    for (const piece of rawComma.split(","))
-      add(piece);
+  if (result.registry)
+    envelope.registry = result.registry.toLowerCase();
+  if (result.packageName)
+    envelope.name = result.packageName;
+  if (result.version)
+    envelope.version = result.version;
+  if (typeof result.stale === "boolean")
+    envelope.stale = result.stale;
+  if (result.pageInfo?.totalCount !== undefined)
+    envelope.total = result.pageInfo.totalCount;
+  if (result.pageInfo?.endCursor)
+    envelope.nextCursor = result.pageInfo.endCursor;
+  const filter = {};
+  if (options.limitExplicit && options.limit !== undefined)
+    filter.limit = options.limit;
+  if (options.afterExplicit && options.after)
+    filter.after = options.after;
+  if (Object.keys(filter).length > 0)
+    envelope.filter = filter;
+  return envelope;
+}
+function assertDocListEntry(page) {
+  if (!page.id) {
+    throw new MalformedPackageIntelligenceResponseError("Documentation page list entry missing required id.");
+  }
+  if (page.sourceKind === "REPOSITORY" && (!page.repoUrl || !page.gitRef || !page.filePath)) {
+    throw new MalformedPackageIntelligenceResponseError("Repository-backed documentation list entry missing repo locator fields.");
+  }
+}
+function formatListPackageDocsTerminal(envelope, options) {
+  const lines = [];
+  lines.push(buildSummaryHeader(envelope, options.useColors));
+  lines.push("");
+  if (envelope.pages.length === 0) {
+    lines.push(dim("No documentation pages found.", options.useColors));
+    lines.push("");
+    return lines.join(`
+`);
   }
-  if (rawRepeated !== undefined) {
-    for (const piece of rawRepeated)
-      add(piece);
+  for (const page of envelope.pages) {
+    lines.push(formatPageHeader(page, options.useColors));
+    const meta = formatPageMeta(page, options.useColors, options.verbose ?? false);
+    if (meta.length > 0)
+      lines.push(...meta);
+    lines.push("");
   }
-  if (out.length > MAX_KEYWORDS) {
-    throw new InvalidKeywordsError(`Too many keywords: got ${out.length}, maximum is ${MAX_KEYWORDS}.`);
+  if (envelope.nextCursor) {
+    lines.push(dim(`Next cursor: ${envelope.nextCursor}`, options.useColors));
   }
-  return out;
+  if (envelope.stale) {
+    lines.push(dim("Documentation may be stale.", options.useColors));
+  }
+  if (envelope.nextCursor || envelope.stale)
+    lines.push("");
+  return lines.join(`
+`);
+}
+function buildSummaryHeader(envelope, useColors) {
+  const target = envelope.registry && envelope.name ? `${envelope.registry}:${envelope.name}${envelope.version ? `@${envelope.version}` : ""}` : "package docs";
+  const summary = `${target} · ${envelope.pages.length} page${envelope.pages.length === 1 ? "" : "s"}`;
+  const suffix = envelope.total !== undefined ? ` of ${envelope.total}` : "";
+  return `${colorize(summary, "bold", useColors)}${dim(suffix, useColors)}`;
+}
+function formatPageHeader(page, useColors) {
+  const badge = page.sourceKind === "repo" ? "[repo]" : "[crawled]";
+  const title = page.title ?? page.pageId;
+  return `${colorize(page.pageId, "bold", useColors)} ${dim(badge, useColors)} - ${title}`;
+}
+function formatPageMeta(page, useColors, verbose) {
+  const lines = [];
+  if (page.sourceUrl) {
+    lines.push(`  ${dim("source:", useColors)} ${page.sourceUrl}`);
+  }
+  if (page.filePath) {
+    const ref = page.requestedRef ?? page.gitRef;
+    lines.push(`  ${dim("file:", useColors)} ${page.filePath}${ref ? ` @ ${ref}` : ""}`);
+  }
+  if (verbose && page.lastUpdatedAt) {
+    lines.push(`  ${dim("updated:", useColors)} ${page.lastUpdatedAt}`);
+  }
+  return lines;
 }
 // src/shared/package-dependencies-request.ts
 class UnsupportedDependenciesRegistryError extends Error {
@@ -1969,47 +2163,6 @@ function buildPackageSummaryParams(input) {
     }
   };
 }
-// src/shared/format-date.ts
-function toIsoDate(iso) {
-  if (!iso)
-    return null;
-  const parsed = new Date(iso);
-  if (Number.isNaN(parsed.getTime()))
-    return null;
-  return parsed.toISOString().slice(0, 10);
-}
-var MINUTE = 60;
-var HOUR = 60 * MINUTE;
-var DAY = 24 * HOUR;
-var MONTH = 30 * DAY;
-var YEAR = 365 * DAY;
-function toRelativeDate(iso, now = new Date) {
-  if (!iso)
-    return null;
-  const parsed = new Date(iso);
-  if (Number.isNaN(parsed.getTime()))
-    return null;
-  const deltaSeconds = Math.floor((now.getTime() - parsed.getTime()) / 1000);
-  if (deltaSeconds < 0) {
-    return toIsoDate(iso);
-  }
-  if (deltaSeconds < MINUTE)
-    return "just now";
-  if (deltaSeconds < HOUR)
-    return formatUnit(deltaSeconds, MINUTE, "minute");
-  if (deltaSeconds < DAY)
-    return formatUnit(deltaSeconds, HOUR, "hour");
-  if (deltaSeconds < MONTH)
-    return formatUnit(deltaSeconds, DAY, "day");
-  if (deltaSeconds < YEAR)
-    return formatUnit(deltaSeconds, MONTH, "month");
-  return formatUnit(deltaSeconds, YEAR, "year");
-}
-function formatUnit(deltaSeconds, unit, label) {
-  const n = Math.floor(deltaSeconds / unit);
-  return `${n} ${label}${n === 1 ? "" : "s"} ago`;
-}
-
 // src/shared/format-number.ts
 function formatCompactNumber(n) {
   if (!Number.isFinite(n)) {
@@ -2836,6 +2989,157 @@ function formatUpgradeFooter(paths) {
     return `Upgrade to ${paths[0]}.`;
   return `Upgrade options: ${paths.join(", ")}.`;
 }
+// src/shared/parse-lines-option.ts
+function parseLinesOption(raw) {
+  const trimmed = raw.trim();
+  const dashIndex = trimmed.indexOf("-");
+  if (dashIndex < 0) {
+    throw new InvalidPackageSpecError(`--lines expects a range like \`10-40\`, \`10-\`, or \`-40\`. Single-line form isn't accepted — use --start ${trimmed}.`);
+  }
+  const startRaw = trimmed.slice(0, dashIndex).trim();
+  const endRaw = trimmed.slice(dashIndex + 1).trim();
+  if (startRaw.length === 0 && endRaw.length === 0) {
+    throw new InvalidPackageSpecError("--lines requires at least one bound. Use `10-40`, `10-` for open end, or `-40` for open start.");
+  }
+  const startLine = startRaw.length > 0 ? requirePositiveInteger(startRaw, "--lines start") : undefined;
+  const endLine = endRaw.length > 0 ? requirePositiveInteger(endRaw, "--lines end") : undefined;
+  if (startLine !== undefined && endLine !== undefined && startLine > endLine) {
+    throw new InvalidPackageSpecError(`--lines range is reversed: ${startLine} > ${endLine}.`);
+  }
+  if (startLine === undefined && endLine !== undefined) {
+    return { startLine: 1, endLine };
+  }
+  return { startLine, endLine };
+}
+function requirePositiveInteger(raw, label) {
+  if (!/^\d+$/.test(raw)) {
+    throw new InvalidPackageSpecError(`${label} must be a positive integer. Got '${raw}'.`);
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (parsed < 1) {
+    throw new InvalidPackageSpecError(`${label} must be ≥ 1 (lines are 1-indexed). Got ${parsed}.`);
+  }
+  return parsed;
+}
+// src/shared/read-package-doc-request.ts
+function buildReadPackageDocParams(input) {
+  const pageId = input.pageId?.trim() ?? "";
+  if (!pageId) {
+    throw new InvalidPackageSpecError("Page ID is required.");
+  }
+  return {
+    params: { pageId }
+  };
+}
+// src/shared/read-package-doc-response.ts
+function buildReadPackageDocSuccessPayload(result, requestedPageId, range) {
+  const pageId = result.page?.id;
+  if (!pageId) {
+    throw new MalformedPackageIntelligenceResponseError(`Documentation page '${requestedPageId}' missing required id in response.`);
+  }
+  if ((result.page?.sourceKind ?? result.sourceKind) === "REPOSITORY" && (!result.page?.repoUrl || !result.page?.gitRef || !result.page?.filePath)) {
+    throw new MalformedPackageIntelligenceResponseError(`Repository-backed documentation page '${pageId}' missing repo locator fields.`);
+  }
+  const envelope = { pageId };
+  if (result.registry)
+    envelope.registry = result.registry.toLowerCase();
+  if (result.packageName)
+    envelope.name = result.packageName;
+  if (result.version)
+    envelope.version = result.version;
+  if (result.page?.title)
+    envelope.title = result.page.title;
+  if (result.page?.contentFormat)
+    envelope.format = result.page.contentFormat;
+  if (result.page?.content !== undefined) {
+    const sliced = sliceContent(result.page.content, range);
+    envelope.content = sliced.content;
+    if (sliced.totalLines !== undefined)
+      envelope.totalLines = sliced.totalLines;
+    if (sliced.startLine !== undefined)
+      envelope.startLine = sliced.startLine;
+    if (sliced.endLine !== undefined)
+      envelope.endLine = sliced.endLine;
+  }
+  if (result.page?.breadcrumbs && result.page.breadcrumbs.length > 0) {
+    envelope.breadcrumbs = result.page.breadcrumbs;
+  }
+  if (result.page?.linkName)
+    envelope.linkName = result.page.linkName;
+  if (result.page?.lastUpdatedAt) {
+    envelope.lastUpdatedAt = toIsoDate(result.page.lastUpdatedAt) ?? undefined;
+  }
+  const sourceKind = lowerDocSourceKind(result.page?.sourceKind ?? result.sourceKind);
+  if (sourceKind)
+    envelope.sourceKind = sourceKind;
+  if (result.page?.source?.url)
+    envelope.sourceUrl = result.page.source.url;
+  if (result.page?.source?.label)
+    envelope.sourceLabel = result.page.source.label;
+  if (result.page?.repoUrl)
+    envelope.repoUrl = result.page.repoUrl;
+  if (result.page?.gitRef)
+    envelope.gitRef = result.page.gitRef;
+  if (result.page?.requestedRef)
+    envelope.requestedRef = result.page.requestedRef;
+  if (result.page?.filePath)
+    envelope.filePath = result.page.filePath;
+  if (result.page?.baseUrl)
+    envelope.baseUrl = result.page.baseUrl;
+  return envelope;
+}
+function sliceContent(content, range) {
+  if (content.length === 0) {
+    return { content };
+  }
+  const trimmed = content.endsWith(`
+`) ? content.slice(0, -1) : content;
+  const lines = trimmed.split(`
+`);
+  const totalLines = lines.length;
+  if (!range || range.startLine === undefined && range.endLine === undefined) {
+    return { content, totalLines };
+  }
+  const startLine = Math.max(1, range.startLine ?? 1);
+  const endLine = Math.min(totalLines, range.endLine ?? totalLines);
+  if (startLine > totalLines) {
+    return { content: "", totalLines, startLine, endLine: startLine - 1 };
+  }
+  const sliced = lines.slice(startLine - 1, endLine).join(`
+`);
+  return { content: sliced, totalLines, startLine, endLine };
+}
+function formatReadPackageDocTerminal(envelope, options) {
+  if (!(options.verbose ?? false)) {
+    return envelope.content ?? "";
+  }
+  const lines = [];
+  lines.push(buildHeader(envelope, options.useColors));
+  lines.push(`pageId: ${envelope.pageId}`);
+  if (envelope.sourceUrl)
+    lines.push(`source: ${envelope.sourceUrl}`);
+  if (envelope.filePath) {
+    const ref = envelope.requestedRef ?? envelope.gitRef;
+    lines.push(`file: ${envelope.filePath}${ref ? ` @ ${ref}` : ""}`);
+  }
+  if (envelope.lastUpdatedAt)
+    lines.push(`updated: ${envelope.lastUpdatedAt}`);
+  if (envelope.breadcrumbs && envelope.breadcrumbs.length > 0) {
+    lines.push(`breadcrumbs: ${envelope.breadcrumbs.join(" > ")}`);
+  }
+  lines.push("");
+  if (envelope.content)
+    lines.push(envelope.content);
+  return `${lines.join(`
+`)}
+`;
+}
+function buildHeader(envelope, useColors) {
+  const badge = envelope.sourceKind === "repo" ? "[repo]" : "[crawled]";
+  const title = envelope.title ?? envelope.pageId;
+  const prefix = envelope.registry && envelope.name ? `${envelope.registry}:${envelope.name}${envelope.version ? `@${envelope.version}` : ""}` : "documentation";
+  return `${colorize(`${prefix} ${badge}`, "bold", useColors)}${title ? ` - ${title}` : ""}`;
+}
 // src/shared/require-auth.ts
 class AuthRequiredError extends Error {
   constructor(message) {
@@ -2862,106 +3166,13 @@ function requireAuth(deps, context) {
 Need help? support@githits.com`);
   throw new AuthRequiredError(`Authentication required${suffix}`);
 }
-// src/shared/search-symbols-request.ts
-function buildSearchSymbolsParams(input) {
-  const defaulted = [];
-  const resolvedFileIntent = resolveFileIntent(input.fileIntent, defaulted);
-  const resolvedWaitTimeoutMs = resolveWaitTimeoutMs(input.waitTimeoutMs, defaulted);
-  return {
-    params: {
-      target: input.target,
-      query: input.query,
-      keywords: input.keywords,
-      matchMode: input.matchMode,
-      kind: input.kind,
-      category: input.category,
-      filePath: input.filePath,
-      limit: input.limit,
-      fileIntent: resolvedFileIntent,
-      waitTimeoutMs: resolvedWaitTimeoutMs
-    },
-    defaulted
-  };
-}
-function resolveFileIntent(input, defaulted) {
-  if (input === FILE_INTENT_ALL) {
-    return;
-  }
-  if (input === undefined) {
-    defaulted.push("fileIntent");
-    return SEARCH_SYMBOLS_DEFAULT_FILE_INTENT;
-  }
-  return input;
-}
-function resolveWaitTimeoutMs(input, defaulted) {
-  if (input === undefined) {
-    defaulted.push("waitTimeoutMs");
-    return DEFAULT_WAIT_TIMEOUT_MS;
-  }
-  return input;
-}
-// src/shared/search-symbols-response.ts
-function buildSearchSymbolsSuccessPayload(params, defaulted, result) {
-  const payload = {
-    query: {
-      target: params.target,
-      query: params.query,
-      keywords: params.keywords,
-      matchMode: params.matchMode?.toLowerCase(),
-      kind: params.kind?.toLowerCase(),
-      category: params.category?.toLowerCase(),
-      filePath: params.filePath,
-      fileIntent: echoFileIntent(params.fileIntent),
-      limit: params.limit,
-      waitTimeoutMs: params.waitTimeoutMs ?? 0,
-      defaulted
-    },
-    results: result.results,
-    returnedCount: result.results.length,
-    totalMatches: result.totalMatches,
-    hasMore: result.hasMore
-  };
-  if (result.version)
-    payload.version = result.version;
-  if (result.resolution)
-    payload.resolution = result.resolution;
-  if (result.warning)
-    payload.warning = result.warning;
-  if (result.hint && !isLegacyZeroChunksHint(result.hint)) {
-    payload.hint = result.hint;
-  }
-  return payload;
-}
-function isLegacyZeroChunksHint(hint) {
-  return hint.toLowerCase().includes("0 searchable chunks");
-}
-function buildSearchSymbolsErrorPayload(error2) {
-  const mapped = mapCodeNavigationError(error2);
-  const payload = {
-    error: mapped.message,
-    code: mapped.code
-  };
-  if (typeof mapped.retryable === "boolean") {
-    payload.retryable = mapped.retryable;
-  }
-  if (mapped.details && Object.keys(mapped.details).length > 0) {
-    payload.details = mapped.details;
-  }
-  return payload;
-}
-function echoFileIntent(resolved) {
-  if (resolved === undefined)
-    return "all";
-  return resolved.toLowerCase();
-}
 // src/shared/unified-search-request.ts
 function buildUnifiedSearchParams(input) {
   const targets = resolveTargets(input.target, input.targets);
   const rawQuery = normaliseRequiredQuery(input.query);
-  const defaulted = [];
-  const limit = resolveNumber(input.limit, 20, "limit", defaulted);
-  const offset = resolveNumber(input.offset, 0, "offset", defaulted);
-  const waitTimeoutMs = resolveNumber(input.waitTimeoutMs, DEFAULT_WAIT_TIMEOUT_MS, "waitTimeoutMs", defaulted);
+  const limit = input.limit ?? 20;
+  const offset = input.offset ?? 0;
+  const waitTimeoutMs = input.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
   const qualifierClauses = buildQualifierClauses({
     name: input.name,
     language: input.language
@@ -2971,7 +3182,7 @@ function buildUnifiedSearchParams(input) {
     kind: input.kind,
     category: input.category,
     pathPrefix: input.pathPrefix,
-    fileIntent: resolveFileIntent2(input.fileIntent, input.sources, defaulted),
+    fileIntent: input.fileIntent,
     publicOnly: input.publicOnly
   });
   return {
@@ -2986,8 +3197,7 @@ function buildUnifiedSearchParams(input) {
       waitTimeoutMs
     },
     rawQuery,
-    compiledQuery,
-    defaulted
+    compiledQuery
   };
 }
 function resolveTargets(target, targets) {
@@ -3021,27 +3231,10 @@ function normaliseRequiredQuery(query) {
   }
   return trimmed;
 }
-function resolveNumber(value, fallback, field, defaulted) {
-  if (value === undefined) {
-    defaulted.push(field);
-    return fallback;
-  }
-  return value;
-}
-function resolveFileIntent2(value, sources, defaulted) {
-  if (value === undefined) {
-    if (sources && sources.length > 0 && sources.every((entry) => entry === "DOCS")) {
-      return;
-    }
-    defaulted.push("fileIntent");
-    return SEARCH_SYMBOLS_DEFAULT_FILE_INTENT;
-  }
-  return value;
-}
-function buildQualifierClauses(input) {
-  const clauses = [];
-  if (input.name) {
-    clauses.push(`name:${quoteQualifierValue(input.name)}`);
+function buildQualifierClauses(input) {
+  const clauses = [];
+  if (input.name) {
+    clauses.push(`name:${quoteQualifierValue(input.name)}`);
   }
   if (input.language) {
     clauses.push(`lang:${quoteQualifierValue(input.language)}`);
@@ -3083,39 +3276,46 @@ function buildFilters(input) {
   return Object.keys(filters).length > 0 ? filters : undefined;
 }
 // src/shared/unified-search-response.ts
-function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, defaulted, outcome) {
+var DEFAULT_LIMIT2 = 20;
+var DEFAULT_OFFSET = 0;
+function buildUnifiedSearchSuccessPayload(params, rawQuery, compiledQuery, outcome) {
   const warnings = outcome.state === "completed" ? outcome.result.queryWarnings : outcome.result?.queryWarnings ?? outcome.progress?.queryWarnings ?? [];
-  const query = buildQueryEcho(params, rawQuery, compiledQuery, defaulted, warnings);
+  const query = buildQueryEcho(params, rawQuery, compiledQuery, warnings);
   if (outcome.state === "incomplete") {
     const result = outcome.result;
     const payload = {
       query,
       completed: false,
-      returnedCount: result?.results.length ?? 0,
       hasMore: result?.page.hasMore ?? false,
       results: result?.results.map(buildHitPayload) ?? [],
-      searchRef: outcome.searchRef,
-      progress: outcome.progress
+      searchRef: outcome.searchRef
     };
     if (result?.page.hasMore === true) {
       payload.nextOffset = result.page.offset + result.page.returned;
     }
-    if (result) {
-      payload.sourceStatus = result.sourceStatus;
-    }
+    const progress = compactProgress(outcome.progress);
+    if (progress)
+      payload.progress = progress;
+    const sourceStatus2 = compactSourceStatus(result?.sourceStatus);
+    if (sourceStatus2)
+      payload.sourceStatus = sourceStatus2;
     return payload;
   }
-  return {
+  const completed = {
     query,
     completed: true,
-    returnedCount: outcome.result.results.length,
     hasMore: outcome.result.page.hasMore,
-    nextOffset: outcome.result.page.hasMore ? outcome.result.page.offset + outcome.result.page.returned : undefined,
-    results: outcome.result.results.map(buildHitPayload),
-    searchRef: outcome.searchRef,
-    progress: outcome.progress,
-    sourceStatus: outcome.result.sourceStatus
+    results: outcome.result.results.map(buildHitPayload)
   };
+  if (outcome.result.page.hasMore) {
+    completed.nextOffset = outcome.result.page.offset + outcome.result.page.returned;
+  }
+  if (outcome.searchRef)
+    completed.searchRef = outcome.searchRef;
+  const sourceStatus = compactSourceStatus(outcome.result.sourceStatus);
+  if (sourceStatus)
+    completed.sourceStatus = sourceStatus;
+  return completed;
 }
 function buildUnifiedSearchErrorPayload(error2) {
   const mapped = mapCodeNavigationError(error2);
@@ -3133,82 +3333,225 @@ function buildUnifiedSearchErrorPayload(error2) {
 }
 function buildUnifiedSearchStatusPayload(outcome) {
   if (outcome.state === "incomplete") {
-    const payload = {
+    const payload2 = {
       completed: false,
-      searchRef: outcome.searchRef,
-      progress: outcome.progress
+      searchRef: outcome.searchRef
     };
+    const progress = compactProgress(outcome.progress);
+    if (progress)
+      payload2.progress = progress;
     if (outcome.result) {
-      payload.result = buildUnifiedSearchStatusResultPayload(outcome.result);
+      payload2.result = buildUnifiedSearchStatusResultPayload(outcome.result);
     }
-    return payload;
+    return payload2;
   }
-  return {
+  const payload = {
     completed: true,
-    searchRef: outcome.searchRef,
-    progress: outcome.progress,
     result: buildUnifiedSearchStatusResultPayload(outcome.result)
   };
+  if (outcome.searchRef)
+    payload.searchRef = outcome.searchRef;
+  return payload;
 }
 function buildUnifiedSearchStatusResultPayload(result) {
-  return {
-    query: result.query,
-    queryWarnings: result.queryWarnings,
-    sources: result.sources.map((entry) => entry.toLowerCase()),
-    returnedCount: result.results.length,
+  const payload = {
     hasMore: result.page.hasMore,
-    nextOffset: result.page.hasMore ? result.page.offset + result.page.returned : undefined,
-    results: result.results.map(buildHitPayload),
-    sourceStatus: result.sourceStatus
+    results: result.results.map(buildHitPayload)
   };
+  if (result.page.hasMore) {
+    payload.nextOffset = result.page.offset + result.page.returned;
+  }
+  if (result.queryWarnings.length > 0) {
+    payload.warnings = result.queryWarnings;
+  }
+  if (result.sources.length > 0) {
+    payload.sources = result.sources.map((entry) => entry.toLowerCase());
+  }
+  const sourceStatus = compactSourceStatus(result.sourceStatus);
+  if (sourceStatus)
+    payload.sourceStatus = sourceStatus;
+  return payload;
 }
-function buildQueryEcho(params, rawQuery, compiledQuery, defaulted, warnings) {
-  return {
-    raw: rawQuery,
-    compiled: compiledQuery,
-    warnings,
-    targets: params.targets,
-    sources: params.sources?.map((entry) => entry.toLowerCase()),
-    filters: params.filters ? {
-      kind: params.filters.kind?.toLowerCase(),
-      category: params.filters.category?.toLowerCase(),
-      pathPrefix: params.filters.pathPrefix,
-      fileIntent: params.filters.fileIntent?.toLowerCase(),
-      publicOnly: params.filters.publicOnly
-    } : undefined,
-    allowPartialResults: params.allowPartialResults ?? false,
-    limit: params.limit ?? 0,
-    offset: params.offset ?? 0,
-    waitTimeoutMs: params.waitTimeoutMs ?? 0,
-    defaulted
+function buildQueryEcho(params, rawQuery, compiledQuery, warnings) {
+  const echo = {
+    raw: rawQuery
   };
+  if (compiledQuery !== rawQuery) {
+    echo.compiled = compiledQuery;
+  }
+  if (warnings.length > 0) {
+    echo.warnings = warnings;
+  }
+  if (params.sources && params.sources.length > 0) {
+    echo.sources = params.sources.map((entry) => entry.toLowerCase());
+  }
+  if (params.filters) {
+    const filters = {};
+    if (params.filters.kind)
+      filters.kind = params.filters.kind.toLowerCase();
+    if (params.filters.category)
+      filters.category = params.filters.category.toLowerCase();
+    if (params.filters.pathPrefix)
+      filters.pathPrefix = params.filters.pathPrefix;
+    if (params.filters.fileIntent)
+      filters.fileIntent = params.filters.fileIntent.toLowerCase();
+    if (typeof params.filters.publicOnly === "boolean")
+      filters.publicOnly = params.filters.publicOnly;
+    if (Object.keys(filters).length > 0)
+      echo.filters = filters;
+  }
+  if (params.allowPartialResults === true) {
+    echo.allowPartialResults = true;
+  }
+  if (params.limit !== undefined && params.limit !== DEFAULT_LIMIT2) {
+    echo.limit = params.limit;
+  }
+  if (params.offset !== undefined && params.offset !== DEFAULT_OFFSET) {
+    echo.offset = params.offset;
+  }
+  if (params.waitTimeoutMs !== undefined && params.waitTimeoutMs !== DEFAULT_WAIT_TIMEOUT_MS) {
+    echo.waitTimeoutMs = params.waitTimeoutMs;
+  }
+  return echo;
 }
 function buildHitPayload(hit) {
-  return {
+  assertSearchFollowUpInvariant(hit);
+  const payload = {
     type: hit.resultType.toLowerCase(),
     target: hit.targetLabel,
-    title: hit.title,
-    summary: hit.summary,
-    score: hit.score,
-    highlights: hit.highlights,
-    locator: {
-      registry: hit.locator.registry,
-      packageName: hit.locator.packageName,
-      version: hit.locator.version,
-      pageId: hit.locator.pageId,
-      repoUrl: hit.locator.repoUrl,
-      gitRef: hit.locator.gitRef,
-      filePath: hit.locator.filePath,
-      startLine: hit.locator.startLine,
-      endLine: hit.locator.endLine,
-      fileContentHash: hit.locator.fileContentHash,
-      symbolRef: hit.locator.symbolRef,
-      qualifiedPath: hit.locator.qualifiedPath,
-      kind: hit.locator.kind,
-      category: hit.locator.category,
-      language: hit.locator.language
-    }
+    locator: buildLocatorPayload(hit)
   };
+  if (hit.title)
+    payload.title = hit.title;
+  if (hit.summary)
+    payload.summary = hit.summary;
+  if (typeof hit.score === "number")
+    payload.score = hit.score;
+  const highlights = buildHighlights(hit.highlights);
+  if (highlights)
+    payload.highlights = highlights;
+  return payload;
+}
+function buildLocatorPayload(hit) {
+  const locator = {};
+  const src = hit.locator;
+  if (src.registry)
+    locator.registry = src.registry;
+  if (src.packageName)
+    locator.packageName = src.packageName;
+  if (src.version)
+    locator.version = src.version;
+  if (src.pageId)
+    locator.pageId = src.pageId;
+  if (src.sourceKind)
+    locator.sourceKind = src.sourceKind;
+  if (src.sourceUrl)
+    locator.sourceUrl = src.sourceUrl;
+  if (src.repoUrl)
+    locator.repoUrl = src.repoUrl;
+  if (src.gitRef)
+    locator.gitRef = src.gitRef;
+  if (src.requestedRef)
+    locator.requestedRef = src.requestedRef;
+  if (src.filePath)
+    locator.filePath = src.filePath;
+  if (typeof src.startLine === "number")
+    locator.startLine = src.startLine;
+  if (typeof src.endLine === "number")
+    locator.endLine = src.endLine;
+  if (src.qualifiedPath && src.qualifiedPath !== hit.title) {
+    locator.qualifiedPath = src.qualifiedPath;
+  }
+  if (src.kind)
+    locator.kind = src.kind;
+  if (src.category)
+    locator.category = src.category;
+  if (src.language)
+    locator.language = src.language;
+  return locator;
+}
+function buildHighlights(highlights) {
+  if (!highlights)
+    return;
+  const compact = {};
+  if (highlights.title && highlights.title.length > 0) {
+    compact.title = highlights.title;
+  }
+  if (highlights.summary && highlights.summary.length > 0) {
+    compact.summary = highlights.summary;
+  }
+  return Object.keys(compact).length > 0 ? compact : undefined;
+}
+function compactProgress(progress) {
+  if (!progress)
+    return;
+  const payload = {
+    status: progress.status,
+    targetsReady: progress.targetsReady,
+    targetsTotal: progress.targetsTotal,
+    elapsedMs: progress.elapsedMs
+  };
+  if (progress.expiresAt)
+    payload.expiresAt = progress.expiresAt;
+  return payload;
+}
+function compactSourceStatus(sourceStatus) {
+  if (!sourceStatus || sourceStatus.length === 0)
+    return;
+  const compact = [];
+  for (const entry of sourceStatus) {
+    const slim = compactSourceStatusEntry(entry);
+    if (slim)
+      compact.push(slim);
+  }
+  return compact.length > 0 ? compact : undefined;
+}
+function compactSourceStatusEntry(entry) {
+  const payload = {
+    source: entry.source.toLowerCase(),
+    targetLabel: entry.targetLabel
+  };
+  let interesting = false;
+  if (entry.indexingStatus && entry.indexingStatus !== "INDEXED") {
+    payload.indexingStatus = entry.indexingStatus;
+    interesting = true;
+  }
+  if (entry.codeIndexState && entry.codeIndexState !== "CURRENT" && entry.codeIndexState !== "STALE") {
+    payload.codeIndexState = entry.codeIndexState;
+    interesting = true;
+  }
+  if (typeof entry.resultCount === "number" && entry.resultCount > 0) {
+    payload.resultCount = entry.resultCount;
+  }
+  if (entry.ignoredFilters.length > 0) {
+    payload.ignoredFilters = entry.ignoredFilters;
+    interesting = true;
+  }
+  if (entry.incompatibleFilters.length > 0) {
+    payload.incompatibleFilters = entry.incompatibleFilters;
+    interesting = true;
+  }
+  if (entry.ignoredQueryFeatures.length > 0) {
+    payload.ignoredQueryFeatures = entry.ignoredQueryFeatures;
+    interesting = true;
+  }
+  if (entry.incompatibleQueryFeatures.length > 0) {
+    payload.incompatibleQueryFeatures = entry.incompatibleQueryFeatures;
+    interesting = true;
+  }
+  if (entry.note) {
+    payload.note = entry.note;
+    interesting = true;
+  }
+  return interesting ? payload : undefined;
+}
+function assertSearchFollowUpInvariant(hit) {
+  if ((hit.resultType === "DOCUMENTATION_PAGE" || hit.resultType === "REPOSITORY_DOC") && !hit.locator.pageId) {
+    throw new MalformedCodeNavigationResponseError(`${hit.resultType} search hit missing required pageId.`);
+  }
+  if (hit.resultType === "REPOSITORY_DOC" && (!hit.locator.repoUrl || !hit.locator.gitRef || !hit.locator.filePath)) {
+    throw new MalformedCodeNavigationResponseError("REPOSITORY_DOC search hit missing repo locator fields.");
+  }
 }
 // src/shared/unified-search-target.ts
 function parseUnifiedSearchTargetSpec(spec) {
@@ -3378,7 +3721,7 @@ function formatPlain2(envelope, options) {
 }
 function formatVerbose2(envelope, options) {
   const lines = [];
-  lines.push(buildSummaryHeader(envelope, options));
+  lines.push(buildSummaryHeader2(envelope, options));
   if (envelope.resolution || envelope.indexedVersion) {
     lines.push(buildResolutionLine(envelope, options));
   }
@@ -3406,7 +3749,7 @@ function formatEmpty(envelope, options, verbose) {
 ` };
   }
   const lines = [];
-  lines.push(buildSummaryHeader(envelope, options));
+  lines.push(buildSummaryHeader2(envelope, options));
   if (envelope.resolution || envelope.indexedVersion) {
     lines.push(buildResolutionLine(envelope, options));
   }
@@ -3416,7 +3759,7 @@ function formatEmpty(envelope, options, verbose) {
   return { stdout: lines.join(`
 `) };
 }
-function buildSummaryHeader(envelope, options) {
+function buildSummaryHeader2(envelope, options) {
   const identity = buildIdentityLabel(envelope);
   const countValue = envelope.hasMore ? `${envelope.files.length}+` : String(envelope.total);
   const counts = `${countValue} ${plural("file", "files", envelope.files.length)}`;
@@ -3654,7 +3997,7 @@ On an INDEXING response, the dependency is being indexed on-demand
 — retry with a longer --wait (up to 60000 ms) or pick one of the
 already-indexed versions surfaced in the error detail.`;
 function registerCodeFilesCommand(pkgCommand) {
-  return pkgCommand.command("files").summary("List files in an indexed dependency").description(PKG_FILES_DESCRIPTION).argument("[arg1]", "In spec mode: package spec (e.g. npm:express). In --repo-url mode: the path-prefix.").argument("[arg2]", "In spec mode: the path-prefix (literal directory, not a glob). Unused in --repo-url mode.").option("--repo-url <url>", "Repository URL addressing (requires --git-ref)").option("--git-ref <ref>", "Tag, commit, branch, or HEAD. Required with --repo-url.").option("--limit <n>", "Max entries (1-1000, default 200)").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Annotate each path with language / file-type / byte size").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, options) => {
+  return pkgCommand.command("files").summary("List files in an indexed dependency").description(PKG_FILES_DESCRIPTION).argument("[spec-or-prefix]", "Spec mode: package spec (e.g. npm:express). Repo mode (with --repo-url): the path-prefix.").argument("[path-prefix]", "Spec mode only: literal directory prefix (not a glob). 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("--limit <n>", "Max entries (1-1000, default 200)").option("--wait <ms>", `Indexing wait timeout (0-${MAX_WAIT_TIMEOUT_MS}, default ${DEFAULT_WAIT_TIMEOUT_MS})`).option("-v, --verbose", "Annotate each path with language / file-type / byte size").option("--json", "Emit the JSON envelope").action(async (arg1, arg2, options) => {
     const deps = await createContainer();
     await pkgFilesAction(arg1, arg2, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -3796,8 +4139,8 @@ for context, --verbose for grouped output, and --cursor to continue a paginated
 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("[arg1]", "In spec mode: package spec (e.g. npm:express). In --repo-url mode: the pattern.").argument("[arg2]", "In spec mode: the pattern. In --repo-url mode: optional path-prefix.").argument("[arg3]", "In spec mode: optional path-prefix. Unused in --repo-url mode.").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)", collectRepeatable, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable, []).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}`, collectRepeatable, []).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-cdx2gnrs.js");
+  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)", collectRepeatable, []).option("--ext <ext>", "Extension filter without leading dot (repeatable)", collectRepeatable, []).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}`, collectRepeatable, []).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-4drb8s8v.js");
     const deps = await createContainer2();
     await pkgGrepAction(arg1, arg2, arg3, options, {
       codeNavigationService: deps.codeNavigationService,
@@ -3895,7 +4238,7 @@ function formatReadFileTerminal(envelope, options) {
 function formatBinary(envelope, options, verbose) {
   const sentinel = dim("Binary file — cannot display as text.", options.useColors);
   if (verbose) {
-    return `${buildHeader(envelope, options)}
+    return `${buildHeader2(envelope, options)}
 
 ${sentinel}
 `;
@@ -3906,7 +4249,7 @@ ${sentinel}
 function formatNoContent(envelope, options, verbose) {
   const sentinel = dim("(no content returned)", options.useColors);
   if (verbose) {
-    return `${buildHeader(envelope, options)}
+    return `${buildHeader2(envelope, options)}
 
 ${sentinel}
 `;
@@ -3916,7 +4259,7 @@ ${sentinel}
 }
 function formatVerboseBody(envelope, options) {
   const lines = [];
-  lines.push(buildHeader(envelope, options));
+  lines.push(buildHeader2(envelope, options));
   lines.push("");
   const content = envelope.content ?? "";
   const bodyLines = content.split(`
@@ -3936,7 +4279,7 @@ function formatVerboseBody(envelope, options) {
   return lines.join(`
 `);
 }
-function buildHeader(envelope, options) {
+function buildHeader2(envelope, options) {
   const parts = [envelope.path];
   if (envelope.language)
     parts.push(envelope.language);
@@ -4026,14 +4369,14 @@ function resolveLineRange(options, pathWithRange) {
     };
   }
   if (hasLines) {
-    return parseLinesOption(options.lines);
+    return parseLinesOption2(options.lines);
   }
   return {
     startLine: parseIntCliOption(options.start, "--start", 1, Number.MAX_SAFE_INTEGER),
     endLine: parseIntCliOption(options.end, "--end", 1, Number.MAX_SAFE_INTEGER)
   };
 }
-function parseLinesOption(raw) {
+function parseLinesOption2(raw) {
   const trimmed = raw.trim();
   const dashIndex = trimmed.indexOf("-");
   if (dashIndex < 0) {
@@ -4044,8 +4387,8 @@ function parseLinesOption(raw) {
   if (startRaw.length === 0 && endRaw.length === 0) {
     throw new InvalidPackageSpecError("--lines requires at least one bound. Use `10-40`, `10-` for open end, or `-40` for open start.");
   }
-  const startLine = startRaw.length > 0 ? requirePositiveInteger(startRaw, "--lines start") : undefined;
-  const endLine = endRaw.length > 0 ? requirePositiveInteger(endRaw, "--lines end") : undefined;
+  const startLine = startRaw.length > 0 ? requirePositiveInteger2(startRaw, "--lines start") : undefined;
+  const endLine = endRaw.length > 0 ? requirePositiveInteger2(endRaw, "--lines end") : undefined;
   if (startLine !== undefined && endLine !== undefined && startLine > endLine) {
     throw new InvalidPackageSpecError(`--lines range is reversed: ${startLine} > ${endLine}.`);
   }
@@ -4068,14 +4411,14 @@ function parsePathWithOptionalRange(path) {
   if (!startRaw) {
     throw new InvalidPackageSpecError(`Invalid path with range: '${path}'. Use <path>:<start>-<end>.`);
   }
-  const startLine = requirePositiveInteger(startRaw, "path range start");
-  const endLine = endRaw !== undefined && endRaw.length > 0 ? requirePositiveInteger(endRaw, "path range end") : startLine;
+  const startLine = requirePositiveInteger2(startRaw, "path range start");
+  const endLine = endRaw !== undefined && endRaw.length > 0 ? requirePositiveInteger2(endRaw, "path range end") : startLine;
   if (startLine > endLine) {
     throw new InvalidPackageSpecError(`Path range is reversed: ${startLine} > ${endLine}.`);
   }
   return { filePath, startLine, endLine };
 }
-function requirePositiveInteger(raw, label) {
+function requirePositiveInteger2(raw, label) {
   if (!/^\d+$/.test(raw)) {
     throw new InvalidPackageSpecError(`${label} must be a positive integer. Got '${raw}'.`);
   }
@@ -4114,308 +4457,211 @@ function registerCodeReadCommand(pkgCommand) {
   });
 }
 
-// src/commands/code/search-symbols.ts
-async function searchSymbolsAction(packageArg, query, options, deps) {
+// src/commands/code/index.ts
+async function registerCodeCommandGroup(program, options = {}) {
+  const registration = await resolveGatedCommandGroupRegistrationState(options);
+  if (!registration.shouldRegister) {
+    return;
+  }
+  const codeCommand = program.command("code").summary("Source-level operations on indexed dependencies").description("List files, read files, and grep substrings inside indexed dependency source. Every command accepts either `<spec>` (registry:name[@version]) or `--repo-url <url> --git-ref <ref>`. For symbol or unified discovery search use `githits search`; for package-level metadata use `githits pkg`.");
+  registerCodeFilesCommand(codeCommand);
+  registerCodeReadCommand(codeCommand);
+  registerCodeGrepCommand(codeCommand);
+}
+// src/commands/docs/list.ts
+async function docsListAction(spec, options, deps) {
   requireAuth(deps);
   try {
-    if (!deps.codeNavigationUrl || !deps.codeNavigationService) {
-      throw new InvalidArgumentError("Code navigation is not configured for this environment.");
-    }
-    const keywords = normaliseKeywords(options.keywords, options.keyword);
-    if (!query && keywords.length === 0) {
-      throw new InvalidArgumentError("Provide a query argument, or pass keywords via --keywords or repeated --keyword.");
-    }
-    const parsed = parsePackageSpec(packageArg);
-    const { params, defaulted } = buildSearchSymbolsParams({
-      target: {
-        registry: toCodeNavigationRegistry(parsed.registry),
-        packageName: parsed.name,
-        version: parsed.version
-      },
-      query,
-      keywords: keywords.length > 0 ? keywords : undefined,
-      matchMode: parseMatchMode(options.matchMode),
-      kind: parseKind(options.kind),
-      category: parseCategory(options.category),
-      filePath: options.file,
-      limit: parseOptionalInt(options.limit, "--limit", 1, 50),
-      fileIntent: parseIntent(options.intent),
-      waitTimeoutMs: parseWaitSeconds(options.wait)
+    if (!deps.codeNavigationUrl || !deps.packageIntelligenceService) {
+      throw new InvalidPackageSpecError("Package intelligence is not configured for this environment.");
+    }
+    const parsed = parsePackageSpec(spec);
+    const limit = parseLimitOption(options.limit);
+    const build = buildListPackageDocsParams({
+      registry: parsed.registry,
+      packageName: parsed.name,
+      version: parsed.version,
+      limit,
+      after: options.after
+    });
+    const result = await deps.packageIntelligenceService.listPackageDocs(build.params);
+    const payload = buildListPackageDocsSuccessPayload(result, {
+      limitExplicit: build.limitExplicit,
+      afterExplicit: build.afterExplicit,
+      limit: build.params.limit,
+      after: build.params.after
     });
-    const result = await deps.codeNavigationService.searchSymbols(params);
-    const payload = buildSearchSymbolsSuccessPayload(params, defaulted, result);
     if (options.json) {
       console.log(JSON.stringify(payload));
       return;
     }
-    console.log(formatSearchSymbolsTerminal(payload, parsed.registry, parsed.name, parsed.version, query));
+    process.stdout.write(formatListPackageDocsTerminal(payload, {
+      verbose: options.verbose ?? false,
+      useColors: shouldUseColors()
+    }));
   } catch (error2) {
-    handleSearchSymbolsCommandError(error2, options.json ?? false);
+    handleDocsListError(error2, options.json ?? false);
   }
 }
-var SEARCH_SYMBOLS_DESCRIPTION = `Find functions, classes, modules, and doc sections inside an indexed dependency by exact-token search.
-
-Prefer top-level \`githits search --source symbol\` for new symbol-shaped workflows. \`githits code search\` remains available for the older dedicated symbol-search UX and JSON parity contract.
-
-Package spec: <registry>:<name>[@<version>]. Omit the registry to default to
-npm. Supported registries: npm, pypi, hex, crates, nuget, maven, zig, vcpkg,
-packagist.
-
-Filter by --category (broad: callable, type, module, data, documentation)
-or --kind (precise: function, method, class, trait, …). Prefer --category
-for most use cases; reach for --kind when you need a specific construct.
-
-Default file intent is production source. Pass --intent all to include tests,
-examples, benchmarks, generated files, and other non-production code.
-
-Examples:
-  githits code search npm:express middleware
-  githits code search npm:express middleware --intent all
-  githits code search pypi:requests timeout --category callable --limit 10
-  githits code search crates:serde Serialize --kind trait --limit 5
-  githits code search npm:@types/node Buffer --file src/ --json
-  githits code search npm:express --keywords "router,handler" --match-mode and`;
-function registerCodeSearchSymbolsCommand(program) {
-  program.command("search <package> [query]").alias("search-symbols").summary("Legacy symbol search over indexed package source").description(SEARCH_SYMBOLS_DESCRIPTION).option("--category <category>", "Filter by broad symbol category: callable, type, module, data, documentation. Preferred over --kind for most use cases.").option("--kind <kind>", "Filter by precise symbol kind (function, method, constructor, getter, setter, class, interface, trait, struct, enum, record, module, namespace, property, event, etc.). Prefer --category for broad filtering.").option("--limit <n>", "Max results (1-50; default: 25)").option("--keywords <words>", "Comma-separated keywords (alternative to the query argument)").option("--keyword <word>", "Single keyword (repeatable; combines with --keywords)", collectRepeatable2, []).option("--match-mode <mode>", "How to combine keywords: or (any match) or and (all match)").option("--file <prefix>", "Filter to files matching path prefix").option("--intent <intent>", "File intent filter (production, test, benchmark, example, generated, fixture, build, vendor, all). Default: production.").option("--wait <seconds>", "Max seconds to wait for indexing (0-60; default: 20). Accepts `10` or `10s`. Indexing usually completes within 30 seconds; pass `--wait 60` to block on a first-time request.").option("--json", "Output as JSON").action(async (packageArg, query, options) => {
-    try {
-      const deps = await createContainer();
-      await searchSymbolsAction(packageArg, query, options, deps);
-    } catch (error2) {
-      if (error2 instanceof AuthRequiredError) {
-        process.exit(1);
-      }
-      throw error2;
-    }
-  });
-}
-function collectRepeatable2(value, previous) {
-  return [...previous, value];
-}
-function formatSearchSymbolsTerminal(payload, registry, packageName, version2, query) {
-  const lines = [];
-  if (payload.warning) {
-    lines.push(`Warning: ${payload.warning}`);
-    lines.push("");
-  }
-  lines.push(formatHeader2(payload));
-  lines.push("");
-  if (payload.results.length === 0) {
-    lines.push(formatZeroResultMessage(query, registry, packageName, version2, payload.query, payload.hint));
-    return lines.join(`
-`).trimEnd();
-  }
-  for (const entry of payload.results) {
-    lines.push(...formatEntry(entry));
-    lines.push("");
-  }
-  if (payload.hint) {
-    lines.push(`Note: ${payload.hint}`);
-  }
-  return lines.join(`
-`).trimEnd();
-}
-function formatHeader2(payload) {
-  let summary = `${payload.returnedCount} match(es)`;
-  if (payload.hasMore)
-    summary += " (more available)";
-  if (payload.version) {
-    summary += ` · indexed ${displayVersion(payload.version)}`;
-    const requested = payload.resolution?.requestedVersion ?? payload.resolution?.requestedRef;
-    if (requested && !isTrivialRefDifference(requested, payload.version) && !isTrivialRefDifference(requested, payload.resolution?.resolvedRef)) {
-      summary += ` (requested ${requested})`;
-    }
-  }
-  return summary;
-}
-function displayVersion(version2) {
-  if (/^[0-9a-f]{40}$/i.test(version2))
-    return version2.slice(0, 7);
-  return version2;
-}
-function isTrivialRefDifference(requested, resolved) {
-  if (!resolved)
-    return false;
-  if (requested === resolved)
-    return true;
-  const stripV = (v) => v.startsWith("v") ? v.slice(1) : v;
-  return stripV(requested) === stripV(resolved);
-}
-function formatEntry(entry) {
-  const out = [];
-  const locationParts = [];
-  if (entry.filePath) {
-    if (entry.startLine) {
-      locationParts.push(entry.endLine && entry.endLine !== entry.startLine ? `${entry.filePath}:${entry.startLine}-${entry.endLine}` : `${entry.filePath}:${entry.startLine}`);
-    } else {
-      locationParts.push(entry.filePath);
-    }
-  }
-  const kindLabel = resolveKindLabel(entry);
-  if (kindLabel)
-    locationParts.push(`[${kindLabel}]`);
-  out.push(locationParts.length > 0 ? locationParts.join("  ") : "unnamed match");
-  if (entry.name)
-    out.push(`  ${entry.name}`);
-  const snippet = buildSnippet(entry.code);
-  for (const snippetLine of snippet)
-    out.push(snippetLine);
-  return out;
-}
-function resolveKindLabel(entry) {
-  if (!entry.kind)
-    return;
-  const normalised = entry.kind.toLowerCase();
-  if (normalised === "fallback")
+function parseLimitOption(value) {
+  if (value === undefined)
     return;
-  return normalised;
-}
-function buildSnippet(code, maxLines = 3) {
-  if (!code)
-    return [];
-  const raw = code.split(`
-`);
-  while (raw.length > 0 && raw[0]?.trim() === "")
-    raw.shift();
-  while (raw.length > 0 && raw[raw.length - 1]?.trim() === "")
-    raw.pop();
-  if (raw.length === 0)
-    return [];
-  const indent = commonLeadingIndent(raw);
-  const dedented = raw.map((line) => indent > 0 ? line.slice(indent) : line);
-  const truncated = dedented.length > maxLines;
-  const selected = dedented.slice(0, maxLines);
-  const visible = truncated ? [...selected, "…"] : selected;
-  return visible.map((line) => `    ${line}`);
-}
-function commonLeadingIndent(lines) {
-  let min = Number.POSITIVE_INFINITY;
-  for (const line of lines) {
-    if (line.trim() === "")
-      continue;
-    const match = line.match(/^(\s*)/);
-    const len = match?.[1]?.length ?? 0;
-    if (len < min)
-      min = len;
-  }
-  return Number.isFinite(min) ? min : 0;
-}
-function formatZeroResultMessage(query, registry, packageName, version2, echo, serverHint) {
-  const target = version2 ? `${registry}:${packageName}@${version2}` : `${registry}:${packageName}`;
-  const queryText = query ? `"${query}"` : "the given keywords";
-  const header = `No matches for ${queryText} in ${target}.`;
-  if (serverHint) {
-    return [header, serverHint].join(`
-`);
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 500) {
+    throw new InvalidPackageSpecError("--limit must be an integer between 1 and 500.");
   }
-  const suggestions = [];
-  if (echo.kind)
-    suggestions.push("drop --kind");
-  if (echo.category)
-    suggestions.push("drop --category");
-  if (echo.filePath)
-    suggestions.push("broaden or remove --file");
-  if (echo.fileIntent !== "all")
-    suggestions.push("try --intent all");
-  if (echo.matchMode === "and")
-    suggestions.push("try --match-mode or");
-  suggestions.push("try broader keywords");
-  return [header, `Try: ${suggestions.join(", ")}.`].join(`
-`);
+  return parsed;
 }
-function handleSearchSymbolsCommandError(error2, json) {
+function handleDocsListError(error2, json) {
+  const mapped = mapPackageIntelligenceError(error2);
   if (json) {
-    console.error(JSON.stringify(buildSearchSymbolsErrorPayload(error2)));
-    process.exit(1);
+    console.error(JSON.stringify({
+      error: mapped.message,
+      code: mapped.code,
+      retryable: mapped.retryable ?? false,
+      ...mapped.details ? { details: mapped.details } : {}
+    }));
+  } else {
+    console.error(mapped.message);
   }
-  const mapped = mapCodeNavigationError(error2);
-  console.error(`Failed to search symbols: ${mapped.message}`);
   process.exit(1);
 }
-function parseOptionalInt(value, optionName, min, max) {
-  if (value === undefined)
-    return;
-  const parsed = Number.parseInt(value, 10);
-  if (Number.isNaN(parsed) || parsed < min || parsed > max) {
-    throw new InvalidArgumentError(`${optionName} must be a number between ${min} and ${max}`);
-  }
-  return parsed;
+var DOCS_LIST_DESCRIPTION = `List package documentation pages from mixed sources.
+
+Docs are mixed by default: hosted/crawled docs and repository-backed docs
+appear together. Every entry shows its page ID, source badge, and source
+location. Repo-backed docs also carry exact file follow-up metadata in JSON.
+
+Package spec: <registry>:<name>[@version].`;
+function registerDocsListCommand(docsCommand) {
+  return docsCommand.command("list").summary("List documentation pages for a package").description(DOCS_LIST_DESCRIPTION).argument("<spec>", "Package spec, e.g. npm:express@5.2.1").option("--limit <n>", "Max pages (1-500, default 100)").option("--after <cursor>", "Pagination cursor from a prior response").option("-v, --verbose", "Show updated timestamps when available").option("--json", "Emit the JSON envelope").action(async (spec, options) => {
+    const deps = await createContainer();
+    await docsListAction(spec, options, {
+      packageIntelligenceService: deps.packageIntelligenceService,
+      codeNavigationUrl: deps.codeNavigationUrl,
+      hasValidToken: deps.hasValidToken,
+      mcpUrl: deps.mcpUrl
+    });
+  });
 }
-function parseMatchMode(value) {
-  if (!value)
-    return;
-  const parsed = toSearchSymbolsMatchMode(value.toLowerCase());
-  if (!parsed) {
-    throw new InvalidArgumentError("--match-mode must be 'or' or 'and'");
+
+// src/commands/docs/read.ts
+async function docsReadAction(pageId, options, deps) {
+  requireAuth(deps);
+  try {
+    if (!deps.codeNavigationUrl || !deps.packageIntelligenceService) {
+      throw new InvalidPackageSpecError("Package intelligence is not configured for this environment.");
+    }
+    const range = options.lines ? parseLinesOption(options.lines) : undefined;
+    const build = buildReadPackageDocParams({ pageId });
+    const result = await deps.packageIntelligenceService.readPackageDoc(build.params);
+    const payload = buildReadPackageDocSuccessPayload(result, build.params.pageId, range);
+    if (options.json) {
+      console.log(JSON.stringify(payload));
+      return;
+    }
+    process.stdout.write(formatReadPackageDocTerminal(payload, {
+      verbose: options.verbose ?? false,
+      useColors: shouldUseColors()
+    }));
+  } catch (error2) {
+    handleDocsReadError(error2, options.json ?? false);
   }
-  return parsed;
 }
-function parseKind(value) {
-  if (!value)
-    return;
-  const parsed = toSearchSymbolsKind(value.toLowerCase());
-  if (!parsed) {
-    throw new InvalidArgumentError(`--kind must be one of ${knownSymbolKindList().join(", ")}`);
+function handleDocsReadError(error2, json) {
+  const mapped = mapPackageIntelligenceError(error2);
+  if (json) {
+    console.error(JSON.stringify({
+      error: mapped.message,
+      code: mapped.code,
+      retryable: mapped.retryable ?? false,
+      ...mapped.details ? { details: mapped.details } : {}
+    }));
+  } else {
+    console.error(mapped.message);
   }
-  return parsed;
+  process.exit(1);
 }
-function parseCategory(value) {
-  if (!value)
-    return;
-  const parsed = toSymbolCategory(value.toLowerCase());
-  if (!parsed) {
-    throw new InvalidArgumentError(`--category must be one of ${knownSymbolCategoryList().join(", ")}`);
-  }
-  return parsed;
+var DOCS_READ_DESCRIPTION = `Read a documentation page by page ID.
+
+Use page IDs from githits docs list, githits search --json, or MCP doc/search
+results. Default output is content-only for easy piping; pass --verbose for a
+metadata header. Use --lines for a bounded line range (e.g. \`--lines 10-40\`,
+\`--lines 10-\` for open-ended, or \`--lines -40\` for the first 40 lines) —
+useful when a page is too long to read whole.`;
+function registerDocsReadCommand(docsCommand) {
+  return docsCommand.command("read").summary("Read a documentation page by page ID").description(DOCS_READ_DESCRIPTION).argument("<page-id>", "Documentation page ID from docs/search results").option("--lines <range>", "Bounded line range, e.g. 10-40, 10-, or -40 (1-indexed inclusive)").option("-v, --verbose", "Show metadata header before content").option("--json", "Emit the JSON envelope").action(async (pageId, options) => {
+    const deps = await createContainer();
+    await docsReadAction(pageId, options, {
+      packageIntelligenceService: deps.packageIntelligenceService,
+      codeNavigationUrl: deps.codeNavigationUrl,
+      hasValidToken: deps.hasValidToken,
+      mcpUrl: deps.mcpUrl
+    });
+  });
 }
-function parseIntent(value) {
-  if (value === undefined)
+
+// src/commands/docs/index.ts
+async function registerDocsCommandGroup(program, options = {}) {
+  const registration = await resolveGatedCommandGroupRegistrationState(options);
+  if (!registration.shouldRegister) {
     return;
-  const lower = value.toLowerCase();
-  if (lower === "all")
-    return FILE_INTENT_ALL;
-  const parsed = toSearchSymbolsFileIntent(lower);
-  if (!parsed) {
-    throw new InvalidArgumentError("--intent must be one of production, test, benchmark, example, generated, fixture, build, vendor, or all");
   }
-  return parsed;
+  const docsCommand = program.command("docs").summary("Browse and read mixed package documentation").description("Browse and read package documentation across hosted docs and repository-backed docs. Docs are mixed by default; entries are source-badged and repo-backed pages also expose exact file follow-up metadata.");
+  registerDocsListCommand(docsCommand);
+  registerDocsReadCommand(docsCommand);
 }
-function parseWaitSeconds(value) {
-  if (value === undefined)
-    return;
-  const trimmed = value.trim();
-  const withoutSuffix = trimmed.endsWith("s") ? trimmed.slice(0, -1) : trimmed;
-  if (trimmed.endsWith("ms")) {
-    throw new InvalidArgumentError("--wait is specified in seconds (e.g. `10` or `10s`), not milliseconds.");
-  }
-  const parsed = Number.parseInt(withoutSuffix, 10);
-  if (Number.isNaN(parsed) || parsed < 0 || parsed > 60 || withoutSuffix !== String(parsed)) {
-    throw new InvalidArgumentError("--wait must be a number of seconds between 0 and 60 (e.g. `10` or `10s`).");
+// src/commands/example.ts
+import { Option } from "commander";
+async function exampleAction(query, options, deps) {
+  requireAuth(deps);
+  try {
+    const result = await deps.githitsService.search({
+      query,
+      language: options.lang,
+      licenseMode: options.license,
+      includeExplanation: options.explain
+    });
+    if (options.json) {
+      const solutionId = extractSolutionId(result);
+      const payload = solutionId ? { result, solution_id: solutionId } : { result };
+      console.log(JSON.stringify(payload));
+    } else {
+      console.log(result);
+    }
+  } catch (error2) {
+    console.error(`Failed to get example: ${error2 instanceof Error ? error2.message : error2}`);
+    process.exit(1);
   }
-  return parsed * 1000;
 }
+var EXAMPLE_DESCRIPTION = `Get verified, canonical code examples from global open source.
 
-// src/commands/code/index.ts
-async function registerCodeCommandGroup(program, options = {}) {
-  const codeNavigationUrl = options.codeNavigationUrl ?? getCodeNavigationUrl();
-  if (!codeNavigationUrl) {
-    return;
-  }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await resolveStartupCodeNavigationRegistrationState();
-  if (!overrideEnabled && registrationState.capability !== "enabled" && !registrationState.expiredStoredAuth) {
-    return;
-  }
-  const codeCommand = program.command("code").summary("Source-level operations on indexed dependencies").description("Search exact tokens, list files, read files, and grep substrings inside indexed dependency source. Every command accepts either `<spec>` (registry:name[@version]) or `--repo-url <url> --git-ref <ref>`. For package-level metadata (versions, vulnerabilities, dependencies, changelog) use `githits pkg`.");
-  registerCodeSearchSymbolsCommand(codeCommand);
-  registerCodeFilesCommand(codeCommand);
-  registerCodeReadCommand(codeCommand);
-  registerCodeGrepCommand(codeCommand);
+For dependency, package, or repository source search, use \`githits search\` instead.
+
+Examples:
+  githits example "how to use express middleware"
+  githits example "how to use express middleware" --lang javascript
+  githits example "async file reading" -l python --license yolo
+  githits example "react hooks patterns" -l typescript --explain
+  githits example "react hooks patterns" -l typescript --json`;
+function registerExampleCommand(program) {
+  program.command("example").summary("Get code examples from global open source").description(EXAMPLE_DESCRIPTION).argument("<query>", "Natural language example-search query").option("-l, --lang <language>", "Optional programming language; omitted values are inferred by GitHits").addOption(new Option("--license <mode>", "License filter mode").choices(["strict", "yolo", "custom"]).default(undefined)).option("--explain", "Include AI-generated explanation").option("--json", "Output as JSON for piping").action(async (query, options) => {
+    try {
+      const deps = await loadContainer();
+      await exampleAction(query, options, deps);
+    } catch (error2) {
+      if (error2 instanceof AuthRequiredError)
+        process.exit(1);
+      throw error2;
+    }
+  });
+}
+async function loadContainer() {
+  const { createContainer: createContainer2 } = await import("./shared/chunk-4drb8s8v.js");
+  return createContainer2();
 }
 // src/commands/feedback.ts
-import { Option } from "commander";
+import { Option as Option2 } from "commander";
 async function feedbackAction(solutionId, options, deps) {
   requireAuth(deps);
   if (!options.accept && !options.reject) {
@@ -4449,7 +4695,7 @@ Examples:
   githits feedback abc123 --reject -m "Example was outdated"
   githits feedback abc123 --accept --message "Solved my problem" --json`;
 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 Option("--accept", "Mark as helpful").conflicts("reject")).addOption(new Option("--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 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) => {
     try {
       const deps = await createContainer();
       await feedbackAction(solutionId, options, deps);
@@ -4461,6 +4707,62 @@ function registerFeedbackCommand(program) {
   });
 }
 // src/commands/init/setup-handlers.ts
+import {
+  parse as parseJsonc,
+  printParseErrorCode
+} from "jsonc-parser";
+function parseConfigObject(content) {
+  let normalizedContent = content;
+  if (normalizedContent.charCodeAt(0) === 65279) {
+    normalizedContent = normalizedContent.slice(1);
+  }
+  const trimmed = normalizedContent.trim();
+  if (trimmed === "") {
+    return {
+      format: "json",
+      value: {}
+    };
+  }
+  try {
+    const parsed = JSON.parse(normalizedContent);
+    if (!isPlainObject(parsed)) {
+      return {
+        format: "invalid",
+        error: "Config file root is not a JSON object"
+      };
+    }
+    return {
+      format: "json",
+      value: parsed
+    };
+  } catch (jsonError) {
+    const parseErrors = [];
+    const parsed = parseJsonc(normalizedContent, parseErrors, {
+      allowTrailingComma: true,
+      disallowComments: false,
+      allowEmptyContent: false
+    });
+    if (parseErrors.length > 0) {
+      const firstParseError = parseErrors[0];
+      const strictErrorMessage = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      const jsoncDetail = firstParseError ? `${printParseErrorCode(firstParseError.error)} at offset ${firstParseError.offset}` : "Unknown parse error";
+      return {
+        format: "invalid",
+        error: `Invalid JSON: ${strictErrorMessage}. JSONC parse error: ${jsoncDetail}`
+      };
+    }
+    if (!isPlainObject(parsed)) {
+      return {
+        format: "invalid",
+        error: "Config file root is not a JSON object"
+      };
+    }
+    return {
+      format: "jsonc",
+      value: parsed
+    };
+  }
+}
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -4569,29 +4871,14 @@ function getMatchingServerKeys(servers, serverName) {
   return Object.keys(servers).filter((key) => key.toLowerCase() === normalizedTarget);
 }
 function mergeServerConfig(existingContent, serversKey, serverName, serverConfig) {
-  let content = existingContent;
-  if (content.charCodeAt(0) === 65279) {
-    content = content.slice(1);
-  }
-  const trimmed = content.trim();
-  if (trimmed === "") {
-    content = "{}";
-  }
-  let config;
-  try {
-    config = JSON.parse(content);
-  } catch (err) {
+  const parsedConfig = parseConfigObject(existingContent);
+  if (parsedConfig.format === "invalid") {
     return {
       status: "parse_error",
-      error: `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`
-    };
-  }
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
-    return {
-      status: "parse_error",
-      error: "Config file root is not a JSON object"
+      error: parsedConfig.error
     };
   }
+  const config = parsedConfig.value;
   if (!(serversKey in config)) {
     config[serversKey] = {};
   }
@@ -4629,24 +4916,13 @@ function formatSetupPreview(config) {
 ${snippet}`;
 }
 async function isAlreadyConfigured(config, fs) {
-  try {
-    let content;
-    try {
-      content = await fs.readFile(config.configPath);
-    } catch {
-      return false;
-    }
-    if (content.charCodeAt(0) === 65279) {
-      content = content.slice(1);
-    }
-    const trimmed = content.trim();
-    if (trimmed === "") {
-      return false;
-    }
-    const parsed = JSON.parse(trimmed);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  try {
+    const content = await fs.readFile(config.configPath);
+    const parsedConfig = parseConfigObject(content);
+    if (parsedConfig.format === "invalid") {
       return false;
     }
+    const parsed = parsedConfig.value;
     const servers = parsed[config.serversKey];
     if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
       return false;
@@ -4804,6 +5080,32 @@ function getAppDataPath(fs, appName) {
       return fs.joinPath(home, ".config", appName);
   }
 }
+function getUserDataRoot(fs) {
+  const home = fs.getHomeDir();
+  switch (process.platform) {
+    case "win32":
+      return process.env.APPDATA ?? fs.joinPath(home, "AppData", "Roaming");
+    case "darwin":
+      return fs.joinPath(home, "Library", "Application Support");
+    default:
+      return process.env.XDG_DATA_HOME ?? fs.joinPath(home, ".local", "share");
+  }
+}
+function getOpenCodeConfigDir(fs) {
+  if (process.platform === "win32") {
+    return fs.joinPath(getUserDataRoot(fs), "opencode");
+  }
+  return fs.joinPath(fs.getHomeDir(), ".config", "opencode");
+}
+function getOpenCodeDesktopDetectPaths(fs) {
+  const userDataRoot = getUserDataRoot(fs);
+  return [
+    fs.joinPath(userDataRoot, "ai.opencode.desktop"),
+    fs.joinPath(userDataRoot, "ai.opencode.desktop.beta"),
+    fs.joinPath(userDataRoot, "ai.opencode.desktop.dev"),
+    getOpenCodeConfigDir(fs)
+  ];
+}
 async function isExecutableAvailable(exec, executable) {
   try {
     const lookupCommand = process.platform === "win32" ? "where" : "which";
@@ -5016,12 +5318,13 @@ var googleAntigravity = {
 var openCode = {
   name: "OpenCode",
   id: "opencode",
-  detectionMethod: "binary",
+  detectionMethod: "hybrid",
   setupMethod: "config-file",
+  detectPaths: (fs) => getOpenCodeDesktopDetectPaths(fs),
   detectBinary: async (exec) => isExecutableAvailable(exec, "opencode"),
   getSetupConfig: (fs) => ({
     method: "config-file",
-    configPath: process.platform === "win32" ? fs.joinPath(process.env.APPDATA ?? fs.joinPath(fs.getHomeDir(), "AppData", "Roaming"), "opencode", "opencode.json") : fs.joinPath(fs.getHomeDir(), ".config", "opencode", "opencode.json"),
+    configPath: fs.joinPath(getOpenCodeConfigDir(fs), "opencode.json"),
     serversKey: "mcp",
     serverName: GITHITS_SERVER_NAME,
     serverConfig: {
@@ -5065,6 +5368,26 @@ async function scanAgents(definitions, fs, execService) {
           break;
         }
       }
+    } else if (agent.detectionMethod === "hybrid") {
+      let binaryDetected = false;
+      let pathDetected = false;
+      if (agent.detectBinary) {
+        try {
+          binaryDetected = await agent.detectBinary(execService);
+        } catch {
+          binaryDetected = false;
+        }
+      }
+      if (!binaryDetected && agent.detectPaths) {
+        const paths = agent.detectPaths(fs);
+        for (const path of paths) {
+          if (await fs.isDirectory(path)) {
+            pathDetected = true;
+            break;
+          }
+        }
+      }
+      detected = binaryDetected || pathDetected;
     }
     if (!detected) {
       result.notDetected.push(agent);
@@ -5586,9 +5909,23 @@ async function withErrorHandling(operation, fn) {
   try {
     return await fn();
   } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : "Unknown error";
-    return errorResult(`Failed to ${operation}: ${message}`);
+    return errorResult(JSON.stringify(classify3(operation, error2)));
+  }
+}
+function classify3(operation, error2) {
+  if (error2 instanceof AuthenticationError) {
+    return {
+      error: error2.message,
+      code: "UNAUTHENTICATED",
+      retryable: false
+    };
   }
+  const message = error2 instanceof Error ? error2.message : "Unknown error";
+  return {
+    error: `Failed to ${operation}: ${message}`,
+    code: "UNKNOWN",
+    retryable: false
+  };
 }
 
 // src/tools/feedback.ts
@@ -5597,24 +5934,9 @@ var schema = {
   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")')
 };
-var DESCRIPTION = `Submit feedback on a GitHits search result.
+var DESCRIPTION = `Submit feedback on a GitHits example result.
 
-Use this tool after receiving a search result to indicate whether the example was helpful.
-This feedback helps improve GitHits' search quality.
-
-**When to use**:
-- After using the search tool, provide feedback on whether the result was useful
-- Use \`accepted=true\` if the example solved your problem or was helpful, and you used it
-- Use \`accepted=false\` if the example was not relevant or unhelpful, and you did not use it
-- Optionally provide textual feedback explaining why
-
-Args:
-    solution_id: The solution ID from a previous search result (shown in the result)
-    accepted: True if the example was helpful/good, False if unhelpful/bad
-    feedback_text: Optional text explaining why (e.g., "This solved problem X" or "Example was outdated")
-
-Returns:
-    Confirmation message or error`;
+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.`;
 function createFeedbackTool(service) {
   return {
     name: "feedback",
@@ -5636,13 +5958,12 @@ function createFeedbackTool(service) {
 import { z as z2 } from "zod";
 var schema2 = {
   query: z2.string().min(1).describe("Natural-language example-search query for canonical code examples."),
-  language: z2.string().min(1).describe("Programming language. Use search_language first if the exact name is uncertain."),
+  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.")
 };
 var DESCRIPTION2 = `Get verified, canonical code examples from global open source.
 
-Use this for example retrieval. For searching indexed dependency and repository code/docs,
-use the unified \`search\` tool instead.`;
+Returns JSON \`{result, solution_id?}\`. \`result\` is markdown — render or quote it directly. Pass \`solution_id\` to \`feedback\` after using or rejecting the example. For searching indexed dependency and repository code/docs, use the unified \`search\` tool instead.`;
 function createGetExampleTool(service) {
   return {
     name: "get_example",
@@ -5650,13 +5971,15 @@ function createGetExampleTool(service) {
     schema: schema2,
     handler: async (args) => {
       return withErrorHandling("get example", async () => {
-        const result = await service.search({
+        const markdown = await service.search({
           query: args.query,
           language: args.language,
           licenseMode: args.license_mode,
           includeExplanation: false
         });
-        return textResult(result);
+        const solutionId = extractSolutionId(markdown);
+        const payload = solutionId ? { result: markdown, solution_id: solutionId } : { result: markdown };
+        return textResult(JSON.stringify(payload));
       });
     }
   };
@@ -5725,15 +6048,11 @@ function invalidTargetResult(message) {
 }
 
 // src/tools/grep-repo.ts
-var pathSelectorSchema = z4.object({
-  kind: z4.enum(["exact", "prefix", "glob"]),
-  value: z4.string()
-});
 var schema3 = {
   target: codeTargetSchema,
   pattern: z4.string().describe(GREP_REPO_PATTERN_NOTE),
-  path: z4.string().optional().describe("Exact file path to grep. Shares the same path vocabulary as `read_file`."),
-  path_prefix: z4.string().optional().describe("Literal directory prefix to scope grep, matching `list_files` / `search` naming."),
+  path: z4.string().optional().describe("Exact file path to grep. Shares the same path vocabulary as `code_read`."),
+  path_prefix: z4.string().optional().describe("Literal directory prefix to scope grep, matching `code_files` / `search` naming."),
   globs: z4.array(z4.string()).optional().describe("Repeatable glob scopes with real glob semantics (e.g. `src/**/*.ts`)."),
   extensions: z4.array(z4.string()).optional().describe("Extensions to include, without a leading dot."),
   pattern_type: z4.enum(["literal", "regex"]).optional(),
@@ -5749,10 +6068,10 @@ var schema3 = {
   symbol_fields: z4.array(z4.enum(GREP_REPO_SYMBOL_FIELDS)).optional().describe(GREP_REPO_SYMBOL_FIELDS_NOTE),
   wait_timeout_ms: z4.number().optional()
 };
-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`. " + "Matches chain directly into `read_file` via `matches[].filePath`.";
+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`. " + "Matches chain directly into `code_read` via `matches[].filePath`.";
 function createGrepRepoTool(service) {
   return {
-    name: "grep_repo",
+    name: "code_grep",
     description: DESCRIPTION3,
     schema: schema3,
     annotations: { readOnlyHint: true },
@@ -5826,10 +6145,10 @@ var schema4 = {
   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`.")
 };
-var DESCRIPTION4 = "List files in an indexed dependency. Response: " + "`{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. `path_prefix` " + "is a literal directory prefix — it does NOT accept globs " + "(`*.ts`) or extension filters. The returned `path` values feed " + "directly into `read_file` and help scope `grep_repo`. 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. Response: " + "`{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. `path_prefix` " + "is a literal directory prefix — it does NOT accept globs " + "(`*.ts`) or extension filters. The returned `path` values 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`.";
 function createListFilesTool(service) {
   return {
-    name: "list_files",
+    name: "code_files",
     description: DESCRIPTION4,
     schema: schema4,
     annotations: { readOnlyHint: true },
@@ -5868,8 +6187,53 @@ function createListFilesTool(service) {
     }
   };
 }
-// src/tools/package-changelog.ts
+// src/tools/list-package-docs.ts
 import { z as z6 } from "zod";
+var schema5 = {
+  registry: z6.string().describe("Package registry. One of: npm, pypi, hex, crates, nuget, maven, zig, vcpkg, packagist."),
+  package_name: z6.string().describe("Package name (scoped names ok: @types/node)."),
+  version: z6.string().optional().describe("Optional package version."),
+  limit: z6.number().optional().describe("Max pages to return (1-500, default 100)."),
+  after: z6.string().optional().describe("Pagination cursor from a prior response.")
+};
+var DESCRIPTION5 = "List mixed package documentation pages from hosted docs and repository-backed docs. " + "Every entry includes a stable `pageId`, `sourceKind` (`crawled` or `repo`), and source URL; repo-backed entries also expose `repoUrl` / `gitRef` / `filePath` for exact file reads. " + "Pass a returned `pageId` to `docs_read`. Use this to browse before reading a full page.";
+function createListPackageDocsTool(service) {
+  return {
+    name: "docs_list",
+    description: DESCRIPTION5,
+    schema: schema5,
+    annotations: { readOnlyHint: true },
+    handler: async (args) => {
+      try {
+        const build = buildListPackageDocsParams({
+          registry: args.registry,
+          packageName: args.package_name,
+          version: args.version,
+          limit: args.limit,
+          after: args.after
+        });
+        const result = await service.listPackageDocs(build.params);
+        const payload = buildListPackageDocsSuccessPayload(result, {
+          limitExplicit: build.limitExplicit,
+          afterExplicit: build.afterExplicit,
+          limit: build.params.limit,
+          after: build.params.after
+        });
+        return textResult(JSON.stringify(payload));
+      } catch (error2) {
+        const mapped = mapPackageIntelligenceError(error2);
+        return errorResult(JSON.stringify({
+          error: mapped.message,
+          code: mapped.code,
+          retryable: mapped.retryable ?? false,
+          ...mapped.details ? { details: mapped.details } : {}
+        }));
+      }
+    }
+  };
+}
+// src/tools/package-changelog.ts
+import { z as z7 } from "zod";
 
 // src/shared/package-changelog-request.ts
 function buildPackageChangelogParams(input) {
@@ -6134,22 +6498,22 @@ function stripAnsi(text) {
 }
 
 // src/tools/package-changelog.ts
-var schema5 = {
-  registry: z6.string().optional().describe("Package registry (with `package_name`). Mutually exclusive with `repo_url`. Supported: npm, pypi, hex, crates, vcpkg, zig, nuget, maven, packagist."),
-  package_name: z6.string().optional().describe("Package name (with `registry`). Scoped names ok (`@types/node`). Mutually exclusive with `repo_url`."),
-  repo_url: z6.string().optional().describe("GitHub repository URL (https://…). Mutually exclusive with `registry` + `package_name`. Use when agents have a repo URL without a registry mapping."),
-  from_version: z6.string().optional().describe("Start of version range. When set, the response returns every entry between `from_version` and `to_version` (or latest) with no count cap — range mode. Mutually exclusive with `limit`. Tag-style `v`-prefixed inputs are rejected."),
-  to_version: z6.string().optional().describe("End of range / latest-mode cap. Works in either mode. Defaults to latest on the wire. Tag-style `v`-prefixed inputs are rejected."),
-  limit: z6.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: z6.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: z6.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.")
+var schema6 = {
+  registry: z7.string().optional().describe("Package registry (with `package_name`). Mutually exclusive with `repo_url`. Supported: npm, pypi, hex, crates, vcpkg, zig, nuget, maven, packagist."),
+  package_name: z7.string().optional().describe("Package name (with `registry`). Scoped names ok (`@types/node`). Mutually exclusive with `repo_url`."),
+  repo_url: z7.string().optional().describe("GitHub repository URL (https://…). Mutually exclusive with `registry` + `package_name`. Use when agents have a repo URL without a registry mapping."),
+  from_version: z7.string().optional().describe("Start of version range. When set, the response returns every entry between `from_version` and `to_version` (or latest) with no count cap — range mode. Mutually exclusive with `limit`. Tag-style `v`-prefixed inputs are rejected."),
+  to_version: z7.string().optional().describe("End of range / latest-mode cap. Works in either mode. Defaults to latest on the wire. Tag-style `v`-prefixed inputs are rejected."),
+  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.")
 };
-var DESCRIPTION5 = "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: `source` (`"releases"` / `"changelog_file"` ' + '/ `"hexdocs"`), `mode` (`"latest"` or `"range"`), ' + "`entries: { count, items }` with full markdown bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only. " + "Supports npm, PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, " + "Packagist; returns `NOT_FOUND` when a package has no changelog " + "source.";
+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: `source` (`"releases"` / `"changelog_file"` ' + '/ `"hexdocs"`), `mode` (`"latest"` or `"range"`), ' + "`entries: { count, items }` with full markdown bodies. Set " + "`include_bodies: false` for a version / date / URL timeline only. " + "Supports npm, PyPI, Hex, Crates, vcpkg, Zig, NuGet, Maven, " + "Packagist; returns `NOT_FOUND` when a package has no changelog " + "source.";
 function createPackageChangelogTool(service) {
   return {
-    name: "package_changelog",
-    description: DESCRIPTION5,
-    schema: schema5,
+    name: "pkg_changelog",
+    description: DESCRIPTION6,
+    schema: schema6,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6197,22 +6561,22 @@ function createPackageChangelogTool(service) {
   };
 }
 // src/tools/package-dependencies.ts
-import { z as z7 } from "zod";
-var schema6 = {
-  registry: z7.string().describe("Package registry. Dependency data is available on npm, pypi, hex, crates, vcpkg, and zig."),
-  package_name: z7.string().describe("Package name (scoped names ok: @types/node)."),
-  version: z7.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: z7.union([z7.string(), z7.array(z7.string())]).optional().describe('Filter the `groups` block server-side by lifecycle phase. Accepts a single value, a comma-separated string (e.g. `"runtime,development"`), or an array of strings. Canonical values: `runtime`, `development`, `build`, `peer`, `optional`. Uppercase is tolerated. When the filter matches nothing the response still includes `groups: { items: [] }` so you can tell an empty-match apart from a registry that has no groups concept.'),
-  include_transitive: z7.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: z7.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: z7.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`.")
+import { z as z8 } from "zod";
+var schema7 = {
+  registry: z8.string().describe("Package registry. Dependency data is available on npm, pypi, hex, crates, vcpkg, and zig."),
+  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('Filter the `groups` block server-side by lifecycle phase. Accepts a single value, a comma-separated string (e.g. `"runtime,development"`), or an array of strings. Canonical values: `runtime`, `development`, `build`, `peer`, `optional`. Uppercase is tolerated. When the filter matches nothing the response still includes `groups: { items: [] }` so you can tell an empty-match apart from a registry that has no groups concept.'),
+  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`.")
 };
-var DESCRIPTION6 = "Analyze a package's dependency graph. The response always includes " + "a `runtime` block listing the direct runtime dependencies as " + "`{name, version, constraint}` records (the backend resolves each " + "constraint to a concrete version for you). It also always includes " + "a structured `groups` block whenever the backend returns group " + "metadata — one group per lifecycle (`runtime`, `development`, " + "`build`, `peer`, `optional`) plus feature-conditional groups for " + "registries that have them (PyPI extras, Crates features). Use " + "`lifecycle` to filter `groups` server-side. 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, " + "vcpkg, and Zig.";
+var DESCRIPTION7 = "Analyze a package's dependency graph. The response always includes " + "a `runtime` block listing the direct runtime dependencies as " + "`{name, version, constraint}` records (the backend resolves each " + "constraint to a concrete version for you). It also always includes " + "a structured `groups` block whenever the backend returns group " + "metadata — one group per lifecycle (`runtime`, `development`, " + "`build`, `peer`, `optional`) plus feature-conditional groups for " + "registries that have them (PyPI extras, Crates features). Use " + "`lifecycle` to filter `groups` server-side. 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, " + "vcpkg, and Zig.";
 function createPackageDependenciesTool(service) {
   return {
-    name: "package_dependencies",
-    description: DESCRIPTION6,
-    schema: schema6,
+    name: "pkg_deps",
+    description: DESCRIPTION7,
+    schema: schema7,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6261,17 +6625,17 @@ function createPackageDependenciesTool(service) {
   };
 }
 // src/tools/package-summary.ts
-import { z as z8 } from "zod";
-var schema7 = {
-  registry: z8.string().describe("Package registry. One of: npm, pypi, hex, crates, nuget, maven, zig, vcpkg, packagist."),
-  package_name: z8.string().describe("Package name (scoped names ok: @types/node).")
+import { z as z9 } from "zod";
+var schema8 = {
+  registry: z9.string().describe("Package registry. One of: npm, pypi, hex, crates, nuget, maven, zig, vcpkg, packagist."),
+  package_name: z9.string().describe("Package name (scoped names ok: @types/node).")
 };
-var DESCRIPTION7 = "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. " + "Works across npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, " + "vcpkg, and Zig. Always returns data for the latest published " + "version.";
+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. " + "Works across npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, " + "vcpkg, and Zig. Always returns data for the latest published " + "version.";
 function createPackageSummaryTool(service) {
   return {
-    name: "package_summary",
-    description: DESCRIPTION7,
-    schema: schema7,
+    name: "pkg_info",
+    description: DESCRIPTION8,
+    schema: schema8,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6303,20 +6667,20 @@ function createPackageSummaryTool(service) {
   };
 }
 // src/tools/package-vulnerabilities.ts
-import { z as z9 } from "zod";
-var schema8 = {
-  registry: z9.string().describe("Package registry. Vulnerability data available on npm, pypi, hex, and crates only."),
-  package_name: z9.string().describe("Package name (scoped names ok: @types/node)."),
-  version: z9.string().optional().describe("Specific version to check. Defaults to latest when omitted."),
-  min_severity: z9.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: z9.boolean().optional().describe("Include retracted advisories (default: false).")
+import { z as z10 } from "zod";
+var schema9 = {
+  registry: z10.string().describe("Package registry. Vulnerability data available on npm, pypi, hex, and crates only."),
+  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).")
 };
-var DESCRIPTION8 = "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, plus suggested " + "upgrade paths. 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.";
+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, plus suggested " + "upgrade paths. 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.";
 function createPackageVulnerabilitiesTool(service) {
   return {
-    name: "package_vulnerabilities",
-    description: DESCRIPTION8,
-    schema: schema8,
+    name: "pkg_vulns",
+    description: DESCRIPTION9,
+    schema: schema9,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6353,20 +6717,20 @@ function createPackageVulnerabilitiesTool(service) {
   };
 }
 // src/tools/read-file.ts
-import { z as z10 } from "zod";
-var schema9 = {
+import { z as z11 } from "zod";
+var schema10 = {
   target: codeTargetSchema,
-  path: z10.string().describe("Path to the file. Package addressing: package-relative. Repo addressing: repo-relative. This is the same `path` key that `list_files` emits for each entry, so the `list_files` → `read_file` chain needs no renaming."),
-  start_line: z10.number().optional().describe("Starting line (1-indexed). Omit for the full file from line 1."),
-  end_line: z10.number().optional().describe("Ending line (inclusive). Omit for end of file. Must be ≥ `start_line` when both are set."),
-  wait_timeout_ms: z10.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`.")
+  path: z11.string().describe("Path to the file. Package addressing: package-relative. Repo addressing: repo-relative. This is the same `path` key that `code_files` emits for each entry, so chaining needs no renaming."),
+  start_line: z11.number().optional().describe("Starting line (1-indexed). Omit for the full file from line 1."),
+  end_line: z11.number().optional().describe("Ending line (inclusive). Omit for end of file. Must be ≥ `start_line` when both are set."),
+  wait_timeout_ms: z11.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`.")
 };
-var DESCRIPTION9 = "Read a file from an indexed dependency. Default returns the full " + "file; use `start_line` / `end_line` for a bounded range. Response: " + "`{path, language, totalLines, startLine, endLine, content, " + "isBinary}`. Binary files set `isBinary: true` and omit `content` — " + "agents branch on the flag rather than checking null. Pass the same " + "`path` emitted by `list_files`. Address via " + "`target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + `target.git_ref` (repo scope), mutually " + "exclusive. On `INDEXING` retry with a longer `wait_timeout_ms` " + "(note: `fetchCodeContext` doesn't emit `availableVersions` in " + "details, only `indexingRef`). When the path doesn't resolve the " + "response is a `NOT_FOUND` (or `FILE_NOT_FOUND`) error — call " + "`list_files` to discover the actual paths.";
+var DESCRIPTION10 = "Read a file from an indexed dependency. Default returns the full " + "file; use `start_line` / `end_line` for a bounded range. Response: " + "`{path, language, totalLines, startLine, endLine, content, " + "isBinary}`. Binary files set `isBinary: true` and omit `content` — " + "agents branch on the flag rather than checking null. Pass the same " + "`path` emitted by `code_files`. Address via " + "`target.registry` + `target.package_name` (package scope) or " + "`target.repo_url` + `target.git_ref` (repo scope), mutually " + "exclusive. On `INDEXING` retry with a longer `wait_timeout_ms`. " + "When the path doesn't resolve the response is a `NOT_FOUND` (or " + "`FILE_NOT_FOUND`) error — call `code_files` to discover the " + "actual paths.";
 function createReadFileTool(service) {
   return {
-    name: "read_file",
-    description: DESCRIPTION9,
-    schema: schema9,
+    name: "code_read",
+    description: DESCRIPTION10,
+    schema: schema10,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       const target = resolveCodeTarget(args.target);
@@ -6401,15 +6765,48 @@ function createReadFileTool(service) {
     }
   };
 }
+// src/tools/read-package-doc.ts
+import { z as z12 } from "zod";
+var schema11 = {
+  page_id: z12.string().describe("Documentation page ID from `docs_list` or `search` results. Pass through unchanged; repo-backed IDs are snapshot-pinned."),
+  start_line: z12.number().optional().describe("Starting line (1-indexed). Omit for the full page. Use with `end_line` to bound how much content the tool returns when a page is large."),
+  end_line: z12.number().optional().describe("Ending line (inclusive). Omit for end of page. Must be ≥ `start_line` when both are set.")
+};
+var DESCRIPTION11 = "Read a documentation page by page ID. Works for both hosted/crawled docs and repository-backed docs. " + "Pass `start_line` / `end_line` to fetch only a slice when a page is too long — response carries `totalLines` so you can target the next slice. " + "Repo-backed results additionally include exact file follow-up metadata for `code_read`.";
+function createReadPackageDocTool(service) {
+  return {
+    name: "docs_read",
+    description: DESCRIPTION11,
+    schema: schema11,
+    annotations: { readOnlyHint: true },
+    handler: async (args) => {
+      try {
+        const build = buildReadPackageDocParams({ pageId: args.page_id });
+        const result = await service.readPackageDoc(build.params);
+        const range = args.start_line !== undefined || args.end_line !== undefined ? { startLine: args.start_line, endLine: args.end_line } : undefined;
+        const payload = buildReadPackageDocSuccessPayload(result, build.params.pageId, range);
+        return textResult(JSON.stringify(payload));
+      } catch (error2) {
+        const mapped = mapPackageIntelligenceError(error2);
+        return errorResult(JSON.stringify({
+          error: mapped.message,
+          code: mapped.code,
+          retryable: mapped.retryable ?? false,
+          ...mapped.details ? { details: mapped.details } : {}
+        }));
+      }
+    }
+  };
+}
 // src/tools/search.ts
-import { z as z11 } from "zod";
-var schema10 = {
-  query: z11.string().min(1).describe("Discovery query string. Supports implicit AND, uppercase OR, parentheses, unary -, quoted phrases, semantic qualifiers (kind:, category:, path:, lang:, name:, intent:), and routing qualifiers (registry:, package:, version:, repo:). Parsed once and compiled per source; it is not forwarded as a raw backend query."),
+import { z as z13 } from "zod";
+var schema12 = {
+  query: z13.string().min(1).describe("Discovery query string. Supports implicit AND, uppercase OR, parentheses, unary -, quoted phrases, semantic qualifiers (kind:, category:, path:, lang:, name:, intent:), and routing qualifiers (registry:, package:, version:, repo:). Parsed once and compiled per source; it is not forwarded as a raw backend query."),
   target: codeTargetSchema.optional(),
-  targets: z11.array(codeTargetSchema).max(20).optional(),
-  sources: z11.array(z11.enum(["docs", "code", "symbol"])).optional().describe("Optional source selection. Omit for backend AUTO."),
-  category: z11.enum(["callable", "type", "module", "data", "documentation"]).optional(),
-  kind: z11.enum([
+  targets: z13.array(codeTargetSchema).max(20).optional(),
+  sources: z13.array(z13.enum(["docs", "code", "symbol"])).optional().describe("Optional source selection. Omit for backend AUTO."),
+  category: z13.enum(["callable", "type", "module", "data", "documentation"]).optional(),
+  kind: z13.enum([
     "function",
     "method",
     "constructor",
@@ -6439,8 +6836,8 @@ var schema10 = {
     "constant",
     "doc_section"
   ]).optional(),
-  path_prefix: z11.string().optional(),
-  file_intent: z11.enum([
+  path_prefix: z13.string().optional(),
+  file_intent: z13.enum([
     "production",
     "test",
     "benchmark",
@@ -6449,21 +6846,21 @@ var schema10 = {
     "fixture",
     "build",
     "vendor"
-  ]).optional().describe("Optional file-intent filter. When omitted, AUTO/code/symbol searches default to production; explicit docs-only searches omit the filter because docs do not support it."),
-  public_only: z11.boolean().optional(),
-  name: z11.string().optional(),
-  language: z11.string().optional(),
-  allow_partial_results: z11.boolean().optional().describe("Default false waits for all sources; if the wait window expires, returns only searchRef/progress. When true, includes hits from sources that finished so far and still returns searchRef for continuation. Partial payloads support normal pagination via nextOffset."),
-  limit: z11.coerce.number().int().min(1).max(100).optional(),
-  offset: z11.coerce.number().int().min(0).optional(),
-  wait_timeout_ms: z11.coerce.number().int().min(0).max(60000).optional()
+  ]).optional().describe("Optional file-intent filter. Omit it to search across all intents; some sources may ignore this filter and report that in sourceStatus."),
+  public_only: z13.boolean().optional(),
+  name: z13.string().optional(),
+  language: z13.string().optional(),
+  allow_partial_results: z13.boolean().optional().describe("Default false waits for all sources; if the wait window expires, returns only searchRef/progress. When true, includes hits from sources that finished so far and still returns searchRef for continuation. Partial payloads support normal pagination via nextOffset."),
+  limit: z13.coerce.number().int().min(1).max(100).optional(),
+  offset: z13.coerce.number().int().min(0).optional(),
+  wait_timeout_ms: z13.coerce.number().int().min(0).max(60000).optional()
 };
-var DESCRIPTION10 = "Search indexed dependency and repository code, docs, and explicit symbols. " + "The query field uses GitHits discovery syntax (AND/OR/parens/qualifiers; see the parameter description). " + "Structured parameters combine with that query using AND semantics. " + "Provide either `target` for one target or `targets` for many. Omit `sources` to use backend AUTO. " + "Results are complete by default; set `allow_partial_results: true` to include available hits while indexing continues. " + "Use `search_status` with that ref to continue.";
+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).";
 function createSearchTool(service) {
   return {
     name: "search",
-    description: DESCRIPTION10,
-    schema: schema10,
+    description: DESCRIPTION12,
+    schema: schema12,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6480,10 +6877,10 @@ function createSearchTool(service) {
           targets: resolvedTargets?.filter(isResolvedCodeTarget),
           query: args.query,
           sources: args.sources?.map((entry) => entry.toUpperCase()),
-          kind: toSearchSymbolsKind(args.kind),
+          kind: toSymbolKind(args.kind),
           category: toSymbolCategory(args.category),
           pathPrefix: args.path_prefix,
-          fileIntent: toSearchSymbolsFileIntent(args.file_intent),
+          fileIntent: toFileIntent(args.file_intent),
           publicOnly: args.public_only,
           name: args.name,
           language: args.language,
@@ -6493,7 +6890,7 @@ function createSearchTool(service) {
           waitTimeoutMs: args.wait_timeout_ms
         });
         const outcome = await service.search(built.params);
-        const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, built.defaulted, outcome);
+        const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
         return textResult(JSON.stringify(payload));
       } catch (error2) {
         return errorResult(JSON.stringify(buildUnifiedSearchErrorPayload(error2)));
@@ -6505,45 +6902,36 @@ function isResolvedCodeTarget(target) {
   return !("content" in target);
 }
 // src/tools/search-language.ts
-import { z as z12 } from "zod";
-var schema11 = {
-  query: z12.string().min(1).describe('Language name or partial name to search for (e.g., "python", "type", "java")')
+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")')
 };
-var DESCRIPTION11 = `Search for a programming language supported by GitHits.
-
-Use this tool to find the correct language name before calling the search tool.
-Returns up to 5 matching languages.
-
-Args:
-    query: Language name or partial name to search for (e.g., "python", "type", "java")
-
-Returns:
-    List of matching languages with name and display_name`;
+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.`;
 function createSearchLanguageTool(service) {
   return {
     name: "search_language",
-    description: DESCRIPTION11,
-    schema: schema11,
+    description: DESCRIPTION13,
+    schema: schema13,
     handler: async (args) => {
       return withErrorHandling("search languages", async () => {
         const allLanguages = await service.getLanguages();
         const result = filterLanguages(allLanguages, args.query);
-        return textResult(JSON.stringify(result, null, 2));
+        return textResult(JSON.stringify(result));
       });
     }
   };
 }
 // src/tools/search-status.ts
-import { z as z13 } from "zod";
-var schema12 = {
-  search_ref: z13.string().min(1).describe("Search reference returned by search.")
+import { z as z15 } from "zod";
+var schema14 = {
+  search_ref: z15.string().min(1).describe("Search reference returned by search.")
 };
-var DESCRIPTION12 = "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 unified search. " + "Pass the search_ref returned by `search` when the original request did not complete within the wait window.";
 function createSearchStatusTool(service) {
   return {
     name: "search_status",
-    description: DESCRIPTION12,
-    schema: schema12,
+    description: DESCRIPTION14,
+    schema: schema14,
     annotations: { readOnlyHint: true },
     handler: async (args) => {
       try {
@@ -6556,79 +6944,27 @@ function createSearchStatusTool(service) {
     }
   };
 }
-// src/tools/search-symbols.ts
-import { z as z14 } from "zod";
-var schema13 = {
-  target: codeTargetSchema,
-  query: z14.string().max(500).optional().describe("Search keywords - exact source tokens, not natural language. Required if keywords not provided."),
-  keywords: z14.array(z14.string()).max(20).optional().describe("Search keywords (max 20). Combined using match_mode. Can be used alone or together with query."),
-  match_mode: z14.enum(["or", "and"]).optional().describe("How to combine keywords: or (any match) or and (all match)"),
-  category: z14.enum(["callable", "type", "module", "data", "documentation"]).optional().describe("Broad symbol category filter — the preferred surface for filtering. callable (function/method/constructor/getter/setter/operator), type (class/interface/trait/struct/enum/record/protocol/extension/etc.), module (module/namespace/package/object), data (field/property/event/constant), documentation (doc_section)."),
-  kind: z14.enum([
-    "function",
-    "method",
-    "constructor",
-    "getter",
-    "setter",
-    "operator",
-    "class",
-    "interface",
-    "trait",
-    "struct",
-    "enum",
-    "record",
-    "protocol",
-    "extension",
-    "delegate",
-    "mixin",
-    "actor",
-    "annotation",
-    "type",
-    "module",
-    "namespace",
-    "package",
-    "object",
-    "field",
-    "property",
-    "event",
-    "constant",
-    "doc_section"
-  ]).optional().describe("Precise symbol kind filter. Prefer `category` for broad filtering; use `kind` only when you need a specific construct (e.g. trait vs interface)."),
-  file_path: z14.string().optional().describe("Filter results to files whose path starts with this value (e.g., 'src/' for a directory)"),
-  limit: z14.coerce.number().int().min(1).max(50).optional().describe("Max results to return (max 50)"),
-  file_intent: z14.enum([
-    "production",
-    "test",
-    "benchmark",
-    "example",
-    "generated",
-    "fixture",
-    "build",
-    "vendor",
-    "all"
-  ]).optional().describe("File intent filter. Defaults to 'production' so top results are production source. Pass 'all' to include tests, benchmarks, examples, and other non-production files."),
-  wait_timeout_ms: z14.coerce.number().int().min(0).max(60000).optional().describe("Max milliseconds to wait for indexing before returning. Defaults to 20000 (20 seconds) to cover typical indexing (p50 ~11s). On an INDEXING response, retry with wait_timeout_ms up to 60000 to block until ready.")
-};
-var DESCRIPTION13 = "Search a dependency's source code by exact-token matches. Use for symbol lookup, not natural-language questions. " + 'Prefer unified `search` with `sources:["symbol"]` for new symbol-shaped workflows; use `search_symbols` when you specifically need this dedicated legacy contract. ' + "Package scope: pass target.registry + target.package_name. Repo scope: pass target.repo_url + target.git_ref. " + "`file_intent` defaults to 'production' so top results are production source; pass 'all' to include tests, examples, benchmarks. " + "`query` and `keywords` can combine; `match_mode` controls AND vs OR across keywords. " + "Filter by `category` (broad: callable/type/module/data/documentation — preferred) or `kind` (precise construct like trait/record/namespace). " + "Prefer `file_path` to scope to a directory (e.g., 'src/'). " + "Responses include each match's source code, line range, and unified `kind`/`category` classification. " + "If the response is an INDEXING error, the package is being indexed on-demand — retry the same call with `wait_timeout_ms: 60000` to block until ready.";
 // src/commands/mcp-instructions.ts
 var CORE_BLOCK = `GitHits surfaces verified, canonical code examples from global open source. Use it when you're stuck, the user is frustrated by repeated failed attempts, you need up-to-date API usage, or the user mentions GitHits.
 
-Workflow: call \`search_language\` first if the language name is uncertain → call \`get_example\` with one focused question → send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
+Workflow: call \`get_example\` with one focused question, optionally passing \`language\` when the desired language is known; call \`search_language\` first only if you need to force a language and the exact name is uncertain. Send \`feedback\` on the returned solution_id so quality improves. Each search addresses a single issue; reuse context from prior results before re-searching.`;
 var PACKAGE_TOOLS_PREAMBLE = `Package tools work with third-party dependency source plus registry metadata. Use them when a stack trace points into a dependency, you need to verify how a library actually works, or you're evaluating whether to add or upgrade a package.
 
 Package spec: \`registry:name[@version]\`.`;
-var PACKAGE_SUMMARY_BULLET = "- `package_summary` — instant package overview: latest version, license, downloads, quickstart, and active advisory count.";
-var PACKAGE_VULNERABILITIES_BULLET = "- `package_vulnerabilities` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages (optionally pinned to `@version`). Malicious-package advisories surface in a disjoint `malware` bucket; filter with `min_severity` or include retracted advisories with `include_withdrawn`.";
-var PACKAGE_DEPENDENCIES_BULLET = "- `package_dependencies` — direct runtime deps plus, when the backend has them, dev / peer / optional / feature groups. Pass `lifecycle` to filter groups server-side, `include_transitive` for the full graph, and `include_importers` when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
-var PACKAGE_CHANGELOG_BULLET = "- `package_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns the 10 most recent entries with full markdown bodies; `from_version` switches to range mode between two versions. Addressable via `registry` + `package_name` or `repo_url`. Set `include_bodies: false` for a version / date / URL timeline when bodies aren't needed.";
-var SEARCH_BULLET = "- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Production file intent is applied by default where supported, but some sources may ignore that filter and report it in `sourceStatus`. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.";
+var PKG_INFO_BULLET = "- `pkg_info` — instant package overview: latest version, license, downloads, quickstart, and active advisory count.";
+var DOCS_LIST_BULLET = "- `docs_list` — browse mixed package documentation pages from hosted docs and repository-backed docs. Each entry includes a stable pageId, source kind, source URL, and for repo docs exact file follow-up metadata.";
+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` — known CVE / OSV advisories for npm, PyPI, Hex, or Crates packages (optionally pinned to `@version`). Malicious-package advisories surface in a disjoint `malware` bucket; filter with `min_severity` or include retracted advisories with `include_withdrawn`.";
+var PKG_DEPS_BULLET = "- `pkg_deps` — direct runtime deps plus, when the backend has them, dev / peer / optional / feature groups. Pass `lifecycle` to filter groups server-side, `include_transitive` for the full graph, and `include_importers` when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, vcpkg, and Zig.";
+var PKG_CHANGELOG_BULLET = "- `pkg_changelog` — release notes for a package or GitHub repo, newest-first. Default latest mode returns the 10 most recent entries with full markdown bodies; `from_version` switches to range mode between two versions. Addressable via `registry` + `package_name` or `repo_url`. Set `include_bodies: false` for a version / date / URL timeline when bodies aren't needed.";
+var SEARCH_BULLET = "- `search` — unified search across indexed dependency code, docs, and explicit symbols. Structured fields are the primary UX; omit `sources` for AUTO. Returns only trustworthy complete results by default; opt into partial hits with `allow_partial_results: true`. If indexing is still in progress, the response carries a `searchRef`.";
 var SEARCH_STATUS_BULLET = "- `search_status` — follow up a prior unified search by `searchRef`. Use it after `search` returns incomplete state to check progress, fetch partial hits when the original request used `allow_partial_results: true`, or fetch final results.";
-var LIST_FILES_BULLET = "- `list_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory; the response includes each file's language, type, and byte size. Returned `path` values feed directly into `read_file` and help scope `grep_repo`.";
-var READ_FILE_BULLET = "- `read_file` — fetch a file's contents from a dependency. Pass the same `path` emitted by `list_files`. Default returns the full file; pass `start_line` / `end_line` for a bounded range. Binary files set `isBinary: true` and omit `content` — branch on the flag, not the null. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `list_files` for the actual path.";
-var GREP_REPO_BULLET = "- `grep_repo` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Returned `matches[].filePath` feeds directly into `read_file`.";
-var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `grep_repo` for deterministic text matching and `read_file` for full-file inspection.';
+var CODE_FILES_BULLET = "- `code_files` — discover what files a dependency ships. Use `path_prefix` to scope to a subdirectory; the response includes each file's language, type, and byte size. Returned `path` values feed directly into `code_read` and help scope `code_grep`.";
+var CODE_READ_BULLET = "- `code_read` — fetch a file's contents from a dependency. Pass the same `path` emitted by `code_files`. Default returns the full file; pass `start_line` / `end_line` for a bounded range. Binary files set `isBinary: true` and omit `content` — branch on the flag. A `FILE_NOT_FOUND` (or `NOT_FOUND`) response is the signal to call `code_files` for the actual path.";
+var CODE_GREP_BULLET = "- `code_grep` — deterministic text grep over indexed source files. Use it when you know the exact text or regex to match; use `search` for discovery. Whole-target grep is the default; narrow with `path`, `path_prefix`, `globs`, or `extensions`. Returned `matches[].filePath` feeds directly into `code_read`.";
+var SEARCH_VS_SYMBOLS_TIP = 'Prefer `get_example` for canonical example retrieval; prefer unified `search` for indexed dependency and repository discovery; use `sources:["symbol"]` when you want symbol-shaped results. Use `code_grep` for deterministic text matching and `code_read` for full-file inspection.';
 function isPackageToolsCapabilityOpen(deps) {
-  return deps.codeNavigationCapability === "enabled";
+  return deps.codeNavigationCliOverrideEnabled || deps.codeNavigationCapability === "enabled" || deps.codeNavigationCapability === "unknown" && deps.envApiToken !== undefined;
 }
 function buildMcpInstructions(deps) {
   const sections = [CORE_BLOCK];
@@ -6639,17 +6975,19 @@ function buildMcpInstructions(deps) {
   }
   const bullets = [];
   if (deps.packageIntelligenceService) {
-    bullets.push(PACKAGE_SUMMARY_BULLET);
-    bullets.push(PACKAGE_VULNERABILITIES_BULLET);
-    bullets.push(PACKAGE_DEPENDENCIES_BULLET);
-    bullets.push(PACKAGE_CHANGELOG_BULLET);
+    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);
   }
   if (deps.codeNavigationService) {
     bullets.push(SEARCH_BULLET);
     bullets.push(SEARCH_STATUS_BULLET);
-    bullets.push(LIST_FILES_BULLET);
-    bullets.push(READ_FILE_BULLET);
-    bullets.push(GREP_REPO_BULLET);
+    bullets.push(CODE_FILES_BULLET);
+    bullets.push(CODE_READ_BULLET);
+    bullets.push(CODE_GREP_BULLET);
   }
   if (bullets.length === 0) {
     return sections.join(`
@@ -6672,26 +7010,34 @@ function buildMcpInstructions(deps) {
 // src/commands/mcp.ts
 function getMcpToolDefinitions(deps) {
   const tools = [
-    createGetExampleTool(deps.githitsService),
-    createSearchLanguageTool(deps.githitsService),
-    createFeedbackTool(deps.githitsService)
+    eraseTool(createGetExampleTool(deps.githitsService)),
+    eraseTool(createSearchLanguageTool(deps.githitsService)),
+    eraseTool(createFeedbackTool(deps.githitsService))
   ];
   const gateOpen = isPackageToolsCapabilityOpen(deps);
   if (gateOpen && deps.codeNavigationService) {
-    tools.push(createSearchTool(deps.codeNavigationService));
-    tools.push(createSearchStatusTool(deps.codeNavigationService));
-    tools.push(createListFilesTool(deps.codeNavigationService));
-    tools.push(createReadFileTool(deps.codeNavigationService));
-    tools.push(createGrepRepoTool(deps.codeNavigationService));
+    tools.push(eraseTool(createSearchTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createSearchStatusTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createListFilesTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createReadFileTool(deps.codeNavigationService)));
+    tools.push(eraseTool(createGrepRepoTool(deps.codeNavigationService)));
   }
   if (gateOpen && deps.packageIntelligenceService) {
-    tools.push(createPackageSummaryTool(deps.packageIntelligenceService));
-    tools.push(createPackageVulnerabilitiesTool(deps.packageIntelligenceService));
-    tools.push(createPackageDependenciesTool(deps.packageIntelligenceService));
-    tools.push(createPackageChangelogTool(deps.packageIntelligenceService));
+    tools.push(eraseTool(createListPackageDocsTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createReadPackageDocTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageSummaryTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageVulnerabilitiesTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageDependenciesTool(deps.packageIntelligenceService)));
+    tools.push(eraseTool(createPackageChangelogTool(deps.packageIntelligenceService)));
   }
   return tools;
 }
+function eraseTool(tool) {
+  return {
+    ...tool,
+    handler: (args, extra) => tool.handler(args, extra)
+  };
+}
 function createMcpServer(deps) {
   const server = new McpServer({
     name: "githits",
@@ -7169,16 +7515,8 @@ function registerPkgVulnsCommand(pkgCommand) {
 
 // src/commands/pkg/index.ts
 async function registerPkgCommandGroup(program, options = {}) {
-  const codeNavigationUrl = options.codeNavigationUrl ?? getCodeNavigationUrl();
-  if (!codeNavigationUrl) {
-    return;
-  }
-  const overrideEnabled = options.overrideEnabled ?? isCodeNavigationCliOverrideEnabled();
-  const registrationState = options.capability !== undefined || options.expiredStoredAuth !== undefined ? {
-    capability: options.capability ?? "unknown",
-    expiredStoredAuth: options.expiredStoredAuth ?? false
-  } : await resolveStartupCodeNavigationRegistrationState();
-  if (!overrideEnabled && registrationState.capability !== "enabled" && !registrationState.expiredStoredAuth) {
+  const registration = await resolveGatedCommandGroupRegistrationState(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, vcpkg, and Zig: overviews, advisories, dependency graphs, and changelogs. For source-level operations inside a dependency, use `githits code`.");
@@ -7187,56 +7525,6 @@ async function registerPkgCommandGroup(program, options = {}) {
   registerPkgDepsCommand(pkgCommand);
   registerPkgChangelogCommand(pkgCommand);
 }
-// src/commands/example.ts
-import { Option as Option2 } from "commander";
-async function exampleAction(query, options, deps) {
-  requireAuth(deps);
-  try {
-    const result = await deps.githitsService.search({
-      query,
-      language: options.lang,
-      licenseMode: options.license,
-      includeExplanation: options.explain
-    });
-    if (options.json) {
-      console.log(JSON.stringify({ result }));
-    } else {
-      console.log(result);
-    }
-  } catch (error2) {
-    console.error(`Failed to get example: ${error2 instanceof Error ? error2.message : error2}`);
-    process.exit(1);
-  }
-}
-var EXAMPLE_DESCRIPTION = `Get verified, canonical code examples from global open source.
-
-This is the GitHits example-search surface. For dependency/package/repo source search,
-use 
-  githits search
-
-instead.
-
-Examples:
-  githits example "how to use express middleware" --lang javascript
-  githits example "async file reading" -l python --license yolo
-  githits example "react hooks patterns" -l typescript --explain
-  githits example "react hooks patterns" -l typescript --json`;
-function registerExampleCommand(program) {
-  program.command("example").summary("Get code examples from global open source").description(EXAMPLE_DESCRIPTION).argument("<query>", "Natural language example-search query").requiredOption("-l, --lang <language>", "Programming language").addOption(new Option2("--license <mode>", "License filter mode").choices(["strict", "yolo", "custom"]).default(undefined)).option("--explain", "Include AI-generated explanation").option("--json", "Output as JSON for piping").action(async (query, options) => {
-    try {
-      const deps = await loadContainer();
-      await exampleAction(query, options, deps);
-    } catch (error2) {
-      if (error2 instanceof AuthRequiredError)
-        process.exit(1);
-      throw error2;
-    }
-  });
-}
-async function loadContainer() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-cdx2gnrs.js");
-  return createContainer2();
-}
 // src/commands/search.ts
 import { Option as Option3 } from "commander";
 async function searchAction(query, options, deps) {
@@ -7247,20 +7535,20 @@ async function searchAction(query, options, deps) {
       targets: parseTargetSpecs(options.in),
       query,
       sources: parseSources(options.source),
-      kind: toSearchSymbolsKind(options.kind),
+      kind: toSymbolKind(options.kind),
       category: toSymbolCategory(options.category),
       pathPrefix: options.pathPrefix,
-      fileIntent: toSearchSymbolsFileIntent(options.intent),
+      fileIntent: toFileIntent(options.intent),
       publicOnly: options.public,
       name: options.name,
       language: options.lang,
       allowPartialResults: options.allowPartial,
-      limit: parseOptionalInt2(options.limit, "--limit", 1, 100),
-      offset: parseOptionalInt2(options.offset, "--offset", 0),
+      limit: parseOptionalInt(options.limit, "--limit", 1, 100),
+      offset: parseOptionalInt(options.offset, "--offset", 0),
       waitTimeoutMs: parseWaitMs(options.wait)
     });
     const outcome = await service.search(built.params);
-    const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, built.defaulted, outcome);
+    const payload = buildUnifiedSearchSuccessPayload(built.params, built.rawQuery, built.compiledQuery, outcome);
     if (options.json) {
       console.log(JSON.stringify(payload));
       return;
@@ -7298,32 +7586,16 @@ async function searchStatusAction(searchRef, options, deps) {
 }
 var SEARCH_DESCRIPTION = `Search code, docs, and symbols across indexed dependencies and repositories.
 
-Use repeatable --in targets in package form (npm:express[@version]) or repo
-form (https://github.com/org/repo[#ref]). Structured flags are AND-combined with
-the discovery query. Unified search defaults to production file intent where the
-backend supports that filter. Results are complete-by-default: if indexing is
-still in progress, search returns a searchRef instead of partial hits unless
---allow-partial is passed.
-
-Query syntax:
-  implicit AND   foo bar
-  OR             foo OR bar        (must be uppercase)
-  grouping       (foo OR bar) baz
-  exclude        foo -bar
-  phrase         "exact phrase"
-  qualifiers     kind: category: path: lang: name: intent:
-  routing        registry: package: version: repo:
+Repeatable --in targets accept package form (npm:express[@version]) or repo
+form (https://github.com/org/repo[#ref]). Structured flags are AND-combined
+with the query. Complete by default — if indexing is still running, returns
+a searchRef instead of partial hits unless --allow-partial is passed. Use
+\`githits example\` for canonical cross-project examples; \`--source symbol\`
+here returns symbol-shaped hits.
 
-Decision guide:
-  githits example ...                canonical cross-project examples
-  githits search ...                 indexed dependency/repository search
-  githits search --source symbol ... symbol-shaped unified search
-
-Plain output labels:
-  docs page   hosted documentation page
-  repo doc    documentation-like block from a repository file
-  repo code   code block from a repository file
-  repo symbol explicit symbol hit from the repository index
+The query supports implicit AND, uppercase OR, parens, unary -, "phrases",
+and qualifiers (kind:, category:, path:, lang:, name:, intent:, registry:,
+package:, version:, repo:).
 
 Examples:
   githits search "router middleware" --in npm:express
@@ -7337,9 +7609,9 @@ Pass the searchRef returned by githits search when the initial request could
 not complete within the wait window. This can return progress, partial hits when
 the original request used --allow-partial, or final results.`;
 function registerSearchCommand(program) {
-  program.command("search").summary("Search indexed dependency and repository code, docs, and symbols").description(SEARCH_DESCRIPTION).argument("<query>", "Search query").requiredOption("--in <target>", "Search target: registry:name[@version] or https://github.com/org/repo[#ref]", collectRepeatable3, []).addOption(new Option3("--source <source>", "Source to search (repeatable; default: auto)").choices(["docs", "code", "symbol"]).argParser((value, previous = []) => collectRepeatable3(value.toLowerCase(), previous)).default(undefined)).addOption(new Option3("--kind <kind>", "Precise symbol kind filter").choices([
+  program.command("search").summary("Search indexed dependency and repository code, docs, and symbols").description(SEARCH_DESCRIPTION).argument("<query>", "Search query").requiredOption("--in <target>", "Search target: registry:name[@version] or https://github.com/org/repo[#ref]", collectRepeatable2, []).addOption(new Option3("--source <source>", "Source to search (repeatable; default: auto)").choices(["docs", "code", "symbol"]).argParser((value, previous = []) => collectRepeatable2(value.toLowerCase(), previous)).default(undefined)).addOption(new Option3("--kind <kind>", "Precise symbol kind filter").choices([
     ...knownSymbolKindList()
-  ])).addOption(new Option3("--category <category>", "Broad symbol category filter").choices([...knownSymbolCategoryList()])).option("--path-prefix <prefix>", "Repository path prefix filter").addOption(new Option3("--intent <intent>", "File intent filter (default: production for AUTO/code/symbol, omitted for docs-only)").choices([
+  ])).addOption(new Option3("--category <category>", "Broad symbol category filter").choices([...knownSymbolCategoryList()])).option("--path-prefix <prefix>", "Repository path prefix filter").addOption(new Option3("--intent <intent>", "File intent filter (omit to search across all intents)").choices([
     "production",
     "test",
     "benchmark",
@@ -7379,11 +7651,11 @@ function requireSearchService(deps) {
   return deps.codeNavigationService;
 }
 async function loadContainer2() {
-  const { createContainer: createContainer2 } = await import("./shared/chunk-cdx2gnrs.js");
+  const { createContainer: createContainer2 } = await import("./shared/chunk-4drb8s8v.js");
   return createContainer2();
 }
 async function loadStartupCodeNavigationRegistrationState() {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-cdx2gnrs.js");
+  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-4drb8s8v.js");
   return resolveStartupCodeNavigationRegistrationState2();
 }
 function parseTargetSpecs(specs) {
@@ -7421,7 +7693,7 @@ function parseSources(values) {
     }
   });
 }
-function parseOptionalInt2(value, flag, min, max = Number.MAX_SAFE_INTEGER) {
+function parseOptionalInt(value, flag, min, max = Number.MAX_SAFE_INTEGER) {
   if (value === undefined)
     return;
   const parsed = Number.parseInt(value, 10);
@@ -7440,7 +7712,7 @@ function parseWaitMs(value) {
   }
   return seconds * 1000;
 }
-function collectRepeatable3(value, previous) {
+function collectRepeatable2(value, previous) {
   return [...previous, value];
 }
 function handleSearchError(error2, json, context = "search") {
@@ -7481,7 +7753,7 @@ function formatUnifiedSearchTerminal(payload) {
     lines.push("");
     lines.push("Partial results:");
   }
-  const sourceStatusNotes = formatSourceStatusNotes(payload.sourceStatus, payload.query.defaulted);
+  const sourceStatusNotes = formatSourceStatusNotes(payload.sourceStatus);
   if (payload.results.length === 0) {
     lines.push("No results.");
     if (sourceStatusNotes.length > 0) {
@@ -7504,6 +7776,10 @@ function formatUnifiedSearchTerminal(payload) {
     const location = formatUnifiedSearchLocation(entry.locator);
     const header = formatUnifiedSearchHeader(entry, useColors, location);
     lines.push(header);
+    const metadata = formatUnifiedSearchMetadata(entry, useColors);
+    if (metadata.length > 0) {
+      lines.push(...metadata);
+    }
     if (entry.summary) {
       lines.push(...formatUnifiedSearchSummary(entry.summary, entry.highlights?.summary, useColors));
     }
@@ -7560,45 +7836,40 @@ function formatSearchStatusHeadline(status) {
 function formatSearchStatusCompletedTerminal(payload) {
   return formatUnifiedSearchTerminal({
     completed: true,
-    returnedCount: payload.result.returnedCount,
     hasMore: payload.result.hasMore,
     nextOffset: payload.result.nextOffset,
     results: payload.result.results,
     searchRef: payload.searchRef,
     progress: undefined,
-    query: { warnings: payload.result.queryWarnings },
+    query: { warnings: payload.result.warnings },
     sourceStatus: payload.result.sourceStatus
   });
 }
 function formatSearchStatusPartialTerminal(payload) {
   return formatUnifiedSearchTerminal({
     completed: false,
-    returnedCount: payload.result.returnedCount,
     hasMore: payload.result.hasMore,
     nextOffset: payload.result.nextOffset,
     results: payload.result.results,
     searchRef: payload.searchRef,
     progress: payload.progress,
-    query: { warnings: payload.result.queryWarnings },
+    query: { warnings: payload.result.warnings },
     sourceStatus: payload.result.sourceStatus
   });
 }
-function formatSourceStatusNotes(sourceStatus, defaulted) {
+function formatSourceStatusNotes(sourceStatus) {
   const useColors = shouldUseColors();
   if (!sourceStatus) {
     return [];
   }
-  const defaultedSet = new Set(defaulted ?? []);
   const lines = [];
   for (const entry of sourceStatus) {
     const label = `${entry.source.toLowerCase()} on ${entry.targetLabel}`;
-    const ignoredFilters = entry.ignoredFilters.filter((name) => !defaultedSet.has(name));
-    if (ignoredFilters.length > 0) {
-      lines.push(dim(`Note: ${label} ignored filters: ${ignoredFilters.join(", ")}`, useColors));
+    if (entry.ignoredFilters && entry.ignoredFilters.length > 0) {
+      lines.push(dim(`Note: ${label} ignored filters: ${entry.ignoredFilters.join(", ")}`, useColors));
     }
-    const incompatibleFilters = entry.incompatibleFilters.filter((name) => !defaultedSet.has(name));
-    if (incompatibleFilters.length > 0) {
-      lines.push(dim(`Note: ${label} incompatible filters: ${incompatibleFilters.join(", ")}`, useColors));
+    if (entry.incompatibleFilters && entry.incompatibleFilters.length > 0) {
+      lines.push(dim(`Note: ${label} incompatible filters: ${entry.incompatibleFilters.join(", ")}`, useColors));
     }
     if (entry.ignoredQueryFeatures && entry.ignoredQueryFeatures.length > 0) {
       lines.push(dim(`Note: ${label} ignored query features: ${entry.ignoredQueryFeatures.join(", ")}`, useColors));
@@ -7606,6 +7877,9 @@ function formatSourceStatusNotes(sourceStatus, defaulted) {
     if (entry.incompatibleQueryFeatures && entry.incompatibleQueryFeatures.length > 0) {
       lines.push(dim(`Note: ${label} incompatible query features: ${entry.incompatibleQueryFeatures.join(", ")}`, useColors));
     }
+    if (entry.indexingStatus === "INDEXING") {
+      lines.push(dim(`Note: ${label} still indexing — re-run with the searchRef for full results.`, useColors));
+    }
     if (entry.note) {
       lines.push(dim(`Note: ${label}: ${entry.note}`, useColors));
     }
@@ -7623,11 +7897,12 @@ function dedupeSearchResultsForDisplay(results) {
       entry.title ?? "",
       (entry.summary ?? "").slice(0, 120)
     ].join("\x01");
-    if (seen.has(key)) {
+    const dedupeKey = `${key}\x01${entry.locator.pageId ?? entry.locator.filePath ?? ""}`;
+    if (seen.has(dedupeKey)) {
       duplicatesFolded += 1;
       continue;
     }
-    seen.add(key);
+    seen.add(dedupeKey);
     display.push(entry);
   }
   return { display, duplicatesFolded };
@@ -7682,7 +7957,7 @@ function formatUnifiedSearchSummary(summary, ranges, useColors) {
 }
 function formatUnifiedSearchLocation(locator) {
   if (!locator.filePath) {
-    return;
+    return locator.sourceUrl;
   }
   if (!locator.startLine) {
     return locator.filePath;
@@ -7690,11 +7965,29 @@ function formatUnifiedSearchLocation(locator) {
   return `${locator.filePath}:${locator.startLine}${locator.endLine && locator.endLine !== locator.startLine ? `-${locator.endLine}` : ""}`;
 }
 function formatUnifiedSearchHeader(entry, useColors, location) {
-  const primary = location ? `${entry.target} ${location}` : entry.target;
+  const primary = entry.type === "documentation_page" ? entry.target : location ? `${entry.target} ${location}` : entry.target;
   const badge = `[${formatUnifiedSearchResultLabel(entry.type)}]`;
   const title = entry.title ? highlightRanges(entry.title, entry.highlights?.title, useColors) : undefined;
   return `${highlight(primary, useColors)} ${dim(badge, useColors)}${title ? ` - ${title}` : ""}`;
 }
+function formatUnifiedSearchMetadata(entry, useColors) {
+  if (entry.type !== "documentation_page" && entry.type !== "repository_doc") {
+    return [];
+  }
+  const lines = [];
+  if (entry.locator.pageId) {
+    lines.push(`  ${dim("pageId:", useColors)} ${entry.locator.pageId}`);
+  }
+  const sourceBadge = entry.locator.sourceKind?.toLowerCase() === "repository" ? "[repo]" : entry.locator.sourceKind?.toLowerCase() === "crawled" ? "[crawled]" : undefined;
+  if (entry.locator.sourceUrl) {
+    lines.push(`  ${dim("source:", useColors)} ${sourceBadge ? `${sourceBadge} ` : ""}${entry.locator.sourceUrl}`);
+  }
+  if (entry.type === "repository_doc" && entry.locator.filePath) {
+    const ref = entry.locator.requestedRef ?? entry.locator.gitRef;
+    lines.push(`  ${dim("file:", useColors)} ${entry.locator.filePath}${ref ? ` @ ${ref}` : ""}`);
+  }
+  return lines;
+}
 // src/cli.ts
 var program = new Command;
 var commandSpans = new WeakMap;
@@ -7713,10 +8006,10 @@ program.name("githits").description("Code examples from global open source for y
   endTelemetrySpan(commandSpans.get(actionCommand));
 }).addHelpText("after", `
 Getting started:
-  githits init                           Set up MCP for your coding agents
-  githits login                          Authenticate with your GitHits account
-  githits mcp                            Start MCP server for your AI assistant
-  githits example "query" --lang python                  Get code examples
+  githits init                         Set up MCP for your coding agents
+  githits login                        Authenticate with your GitHits account
+  githits mcp                          Show MCP setup instructions
+  githits example "query"              Get code examples
 
 Learn more at https://githits.com
 Docs: https://app.githits.com/docs/
@@ -7729,28 +8022,34 @@ registerExampleCommand(program);
 registerLanguagesCommand(program);
 registerFeedbackCommand(program);
 var argv = process.argv.slice(2);
-var helpInvocation = isHelpInvocation(argv);
-var shouldLoadGatedHelpRegistration = needsGatedHelpRegistration(argv);
-var helpRegistrationOptions = shouldLoadGatedHelpRegistration ? await loadHelpRegistrationOptions() : undefined;
-if (shouldEagerLoadSearchCommands(argv)) {
+var registrationArgv = stripRootRegistrationOptions(argv);
+var shouldLoadGatedHelpRegistration = needsGatedHelpRegistration(registrationArgv);
+var helpRegistrationOptions = shouldLoadGatedHelpRegistration ? await loadHelpRegistrationOptions(registrationArgv) : undefined;
+if (shouldEagerLoadSearchCommands(registrationArgv)) {
   await withTelemetrySpan("cli.register.search", () => registerUnifiedSearchCommands(program, helpRegistrationOptions));
 }
-if (shouldEagerLoadGatedCommandGroup(argv, "code")) {
+if (shouldEagerLoadGatedCommandGroup(registrationArgv, "code")) {
   await withTelemetrySpan("cli.register.code-group", () => registerCodeCommandGroup(program, helpRegistrationOptions));
 }
-if (shouldEagerLoadGatedCommandGroup(argv, "pkg")) {
+if (shouldEagerLoadGatedCommandGroup(registrationArgv, "pkg")) {
   await withTelemetrySpan("cli.register.pkg-group", () => registerPkgCommandGroup(program, helpRegistrationOptions));
 }
+if (shouldEagerLoadGatedCommandGroup(registrationArgv, "docs")) {
+  await withTelemetrySpan("cli.register.docs-group", () => registerDocsCommandGroup(program, helpRegistrationOptions));
+}
 var authCommand = program.command("auth").summary("Manage authentication").description("Manage authentication with GitHits.");
 registerAuthStatusCommand(authCommand);
 await withTelemetrySpan("cli.parse", () => program.parseAsync());
+function stripRootRegistrationOptions(args) {
+  return args.filter((arg) => arg !== "--no-color");
+}
 function shouldEagerLoadGatedCommandGroup(args, groupName) {
   const [firstArg] = args;
-  return firstArg === groupName || firstArg === "help" && args[1] === groupName;
+  return args.length === 0 || firstArg === groupName || firstArg === "help" && (!args[1] || args[1] === groupName) || firstArg === "--help" || firstArg === "-h";
 }
 function shouldEagerLoadSearchCommands(args) {
   const [firstArg] = args;
-  return firstArg === "search" || firstArg === "search-status" || firstArg === "help" && isSearchHelpTarget(args[1]);
+  return args.length === 0 || firstArg === "search" || firstArg === "search-status" || firstArg === "--help" || firstArg === "-h" || firstArg === "help" && (!args[1] || isSearchHelpTarget(args[1]));
 }
 function isHelpInvocation(args) {
   return args.length === 0 || args[0] === "help" || args.includes("--help") || args.includes("-h");
@@ -7761,24 +8060,24 @@ function needsGatedHelpRegistration(args) {
   }
   const [firstArg, secondArg] = args;
   if (firstArg === "help") {
-    return isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg";
+    return isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs";
   }
-  return isSearchHelpTarget(firstArg) || firstArg === "code" || firstArg === "pkg";
+  return isSearchHelpTarget(firstArg) || firstArg === "code" || firstArg === "pkg" || firstArg === "docs";
 }
 function isSearchHelpTarget(value) {
   return value === "search" || value === "search-status";
 }
-async function loadHelpRegistrationOptions() {
-  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-cdx2gnrs.js");
+async function loadHelpRegistrationOptions(args) {
+  const { resolveStartupCodeNavigationRegistrationState: resolveStartupCodeNavigationRegistrationState2 } = await import("./shared/chunk-4drb8s8v.js");
   const registrationState = await resolveStartupCodeNavigationRegistrationState2();
   return {
     capability: registrationState.capability,
-    expiredStoredAuth: shouldUseExpiredStoredAuthFallbackForHelp(argv) ? registrationState.expiredStoredAuth : false
+    expiredStoredAuth: shouldUseExpiredStoredAuthFallbackForHelp(args) ? registrationState.expiredStoredAuth : false
   };
 }
 function shouldUseExpiredStoredAuthFallbackForHelp(args) {
   const [firstArg, secondArg] = args;
-  return firstArg === "search" || firstArg === "search-status" || firstArg === "code" || firstArg === "pkg" || firstArg === "help" && (isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg");
+  return firstArg === "search" || firstArg === "search-status" || firstArg === "code" || firstArg === "pkg" || firstArg === "docs" || firstArg === "help" && (isSearchHelpTarget(secondArg) || secondArg === "code" || secondArg === "pkg" || secondArg === "docs");
 }
 function getTelemetryCommandName(command) {
   const names = [];