github-search-cli 9.7.1 → 9.8.1

package/dist/cli.js

@@ -1538,7 +1538,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.7.1";
+    cached = "9.8.1";
     return cached;
   }
   try {
@@ -2309,6 +2309,12 @@ function removeBookmark(fullName) {
   const bookmarks = loadRaw().filter((b) => b.repo.fullName !== fullName);
   saveRaw(bookmarks);
 }
+function searchBookmarks(query) {
+  const q = query.toLowerCase();
+  return getBookmarks().filter(
+    (b) => b.repo.fullName.toLowerCase().includes(q) || (b.repo.description ?? "").toLowerCase().includes(q) || b.tags.some((t3) => t3.toLowerCase().includes(q))
+  );
+}
 function getLastSeen(fullName) {
   return loadRaw().find((b) => b.repo.fullName === fullName)?.lastSeenAt ?? 0;
 }
@@ -2382,8 +2388,8 @@ var PER_REPO = 5;
 function loadCache() {
   return readJSON(RELEASES_FILE, {});
 }
-function saveCache(cache) {
-  writeJSON(RELEASES_FILE, cache);
+function saveCache(cache2) {
+  writeJSON(RELEASES_FILE, cache2);
 }
 function toTracked(raw) {
   return raw.filter((r) => r.draft !== true).map((r) => ({
@@ -2414,13 +2420,13 @@ async function fetchReleases(fullName, etag, token) {
 }
 async function checkReleases(opts = {}) {
   const bookmarks = getBookmarks();
-  const cache = loadCache();
+  const cache2 = loadCache();
   const config = loadConfig();
   const token = opts.token ?? config.githubToken ?? process.env.GITHUB_TOKEN;
   const results2 = [];
   for (const bm of bookmarks) {
     try {
-      const prev = cache[bm.repo.fullName];
+      const prev = cache2[bm.repo.fullName];
       const lastSeen = getLastSeen(bm.repo.fullName);
       const isNew = (r) => !r.publishedAt || new Date(r.publishedAt).getTime() > lastSeen;
       const { status, etag, releases } = await fetchReleases(
@@ -2443,7 +2449,7 @@ async function checkReleases(opts = {}) {
         });
         continue;
       }
-      cache[bm.repo.fullName] = { checkedAt: Date.now(), etag, releases };
+      cache2[bm.repo.fullName] = { checkedAt: Date.now(), etag, releases };
       results2.push({
         fullName: bm.repo.fullName,
         newReleases: releases.filter(isNew)
@@ -2456,7 +2462,7 @@ async function checkReleases(opts = {}) {
       });
     }
   }
-  saveCache(cache);
+  saveCache(cache2);
   return results2;
 }
 async function checkAndNotify(opts = {}) {
@@ -2473,9 +2479,9 @@ async function checkAndNotify(opts = {}) {
   return results2;
 }
 function allCachedReleases() {
-  const cache = loadCache();
+  const cache2 = loadCache();
   const bookmarks = getBookmarks();
-  return Object.entries(cache).filter(([fullName]) => bookmarks.some((b) => b.repo.fullName === fullName)).flatMap(([fullName, s]) => s.releases.map((r) => ({ ...r, fullName }))).sort(
+  return Object.entries(cache2).filter(([fullName]) => bookmarks.some((b) => b.repo.fullName === fullName)).flatMap(([fullName, s]) => s.releases.map((r) => ({ ...r, fullName }))).sort(
     (a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime()
   );
 }
@@ -2946,15 +2952,15 @@ function buildDeepDiveText(data) {
 }
 
 // src/cli.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { join as join6, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync7 } from "fs";
+import { join as join7, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/tui.ts
 import {
   createCliRenderer as createCliRenderer3,
-  BoxRenderable as BoxRenderable4,
-  TextRenderable as TextRenderable4,
+  BoxRenderable as BoxRenderable5,
+  TextRenderable as TextRenderable5,
   InputRenderable,
   SelectRenderable,
   ScrollBoxRenderable as ScrollBoxRenderable3
@@ -3059,7 +3065,7 @@ function buildHelpSections() {
         { keys: "Limit", action: "Cycle limit: 10 \u2192 25 \u2192 50 \u2192 100" },
         { keys: "Refresh", action: "Re-run current search" },
         { keys: "Graph", action: "Toggle commit activity chart" },
-        { keys: "Readme", action: "Full README viewer" },
+        { keys: "Readme", action: "Full markdown README viewer" },
         { keys: "Deep-dive", action: "Languages + contributors + excerpt" },
         { keys: "Bookmark", action: "Save / unsave selected repo" },
         { keys: "Compare", action: "Add to / remove from comparison" },
@@ -3099,6 +3105,7 @@ function buildHelpSections() {
         { keys: "d", action: "Delete entry (history, saved)" },
         { keys: "\u2191 \u2193 / j k", action: "Navigate overlay list" },
         { keys: "\u2190 \u2192 / h l", action: "Navigate tabs / panels" },
+        { keys: "i", action: "Toggle inline images (README viewer)" },
         {
           keys: "PgUp/PgDn",
           action: "Scroll update notes; Home/End jump to ends"
@@ -3260,170 +3267,777 @@ function restoreSession() {
   return readJSON(SESSION_FILE, null);
 }
 
-// src/markdown-render.ts
-function renderMarkdown(md, opts = {}) {
-  const width = opts.width ?? 80;
-  const lines = md.split("\n");
-  const out = [];
-  let inCodeBlock = false;
-  let codeLang = "";
-  let codeLines = [];
-  let inTable = false;
-  let tableRows = [];
-  function flushCode() {
-    if (codeLines.length === 0) return;
-    const maxLen = Math.max(...codeLines.map((l) => l.length), codeLang.length);
-    const barW = Math.min(maxLen + 4, width - 2);
-    out.push(`\u250C${"\u2500".repeat(barW)}\u2510`);
-    if (codeLang) out.push(`\u2502 ${codeLang.padEnd(barW - 1)}\u2502`);
-    for (const cl of codeLines) {
-      out.push(`\u2502 ${cl.padEnd(barW - 1)}\u2502`);
-    }
-    out.push(`\u2514${"\u2500".repeat(barW)}\u2518`);
-    out.push("");
-    codeLines = [];
-    codeLang = "";
-  }
-  function flushTable() {
-    if (tableRows.length === 0) return;
-    const dataRows = tableRows.filter(
-      (r) => !r.every((c) => /^[\s\-:|]+$/.test(c))
+// src/markdown-view.ts
+import {
+  BoxRenderable as BoxRenderable3,
+  MarkdownRenderable,
+  RGBA,
+  StyledText as StyledText3,
+  SyntaxStyle,
+  TextRenderable as TextRenderable3,
+  createTextAttributes
+} from "@opentui/core";
+
+// src/png.ts
+import { inflateSync } from "zlib";
+var PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+function channelsForColorType(colorType) {
+  switch (colorType) {
+    case 0:
+      return 1;
+    // greyscale
+    case 2:
+      return 3;
+    // truecolour
+    case 3:
+      return 1;
+    // palette index
+    case 4:
+      return 2;
+    // greyscale + alpha
+    case 6:
+      return 4;
+    // truecolour + alpha
+    default:
+      throw new Error(`Unsupported PNG colour type ${colorType}`);
+  }
+}
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+function unfilter(raw, height, bytesPerRow, bytesPerPixel) {
+  const out = new Uint8Array(height * bytesPerRow);
+  let src = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[src++];
+    const rowStart = y * bytesPerRow;
+    const prevStart = rowStart - bytesPerRow;
+    for (let x = 0; x < bytesPerRow; x++) {
+      const value = raw[src + x];
+      const left = x >= bytesPerPixel ? out[rowStart + x - bytesPerPixel] : 0;
+      const up = y > 0 ? out[prevStart + x] : 0;
+      const upLeft = y > 0 && x >= bytesPerPixel ? out[prevStart + x - bytesPerPixel] : 0;
+      let result;
+      switch (filter) {
+        case 0:
+          result = value;
+          break;
+        case 1:
+          result = value + left;
+          break;
+        case 2:
+          result = value + up;
+          break;
+        case 3:
+          result = value + (left + up >> 1);
+          break;
+        case 4:
+          result = value + paeth(left, up, upLeft);
+          break;
+        default:
+          throw new Error(`Unsupported PNG filter type ${filter}`);
+      }
+      out[rowStart + x] = result & 255;
+    }
+    src += bytesPerRow;
+  }
+  return out;
+}
+function sampleAt(row, offsetInRow, index, bitDepth) {
+  if (bitDepth === 8) return row[offsetInRow + index];
+  if (bitDepth === 16) return row[offsetInRow + index * 2];
+  const bitOffset = index * bitDepth;
+  const byte = row[offsetInRow + (bitOffset >> 3)];
+  const shift = 8 - bitDepth - (bitOffset & 7);
+  return byte >> shift & (1 << bitDepth) - 1;
+}
+function decodePng(bytes) {
+  if (bytes.length < 8) throw new Error("PNG too short");
+  for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+    if (bytes[i] !== PNG_SIGNATURE[i]) throw new Error("Not a PNG file");
+  }
+  let width = 0;
+  let height = 0;
+  let bitDepth = 8;
+  let colorType = 6;
+  let interlace = 0;
+  let palette = null;
+  let transparency = null;
+  const idat = [];
+  let offset = 8;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  while (offset + 8 <= bytes.length) {
+    const length = view.getUint32(offset);
+    const type = String.fromCharCode(
+      bytes[offset + 4],
+      bytes[offset + 5],
+      bytes[offset + 6],
+      bytes[offset + 7]
     );
-    if (dataRows.length === 0) {
-      tableRows = [];
-      return;
-    }
-    const colCount = Math.max(...dataRows.map((r) => r.length));
-    const colW = [];
-    for (let ci = 0; ci < colCount; ci++) {
-      colW.push(Math.max(3, ...dataRows.map((r) => (r[ci] ?? "").length)));
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + length;
+    if (dataEnd > bytes.length) throw new Error("Truncated PNG chunk");
+    switch (type) {
+      case "IHDR": {
+        width = view.getUint32(dataStart);
+        height = view.getUint32(dataStart + 4);
+        bitDepth = bytes[dataStart + 8];
+        colorType = bytes[dataStart + 9];
+        interlace = bytes[dataStart + 12];
+        break;
+      }
+      case "PLTE":
+        palette = bytes.subarray(dataStart, dataEnd);
+        break;
+      case "tRNS":
+        transparency = bytes.subarray(dataStart, dataEnd);
+        break;
+      case "IDAT":
+        idat.push(bytes.subarray(dataStart, dataEnd));
+        break;
+      default:
+        break;
     }
-    const totalW = colW.reduce((a, b) => a + b, 0) + colCount * 3 - 1;
-    if (totalW > width) {
-      for (const row of dataRows) {
-        out.push(`  ${row.map((c) => c.trim()).join(" \u2502 ")}`);
+    offset = dataEnd + 4;
+    if (type === "IEND") break;
+  }
+  if (width === 0 || height === 0) throw new Error("PNG has no IHDR");
+  if (interlace !== 0) throw new Error("Interlaced PNG is not supported");
+  const channels = channelsForColorType(colorType);
+  const bitsPerPixel = channels * bitDepth;
+  const bytesPerRow = Math.ceil(width * bitsPerPixel / 8);
+  const bytesPerPixel = Math.max(1, Math.ceil(bitsPerPixel / 8));
+  const compressed = idat.length === 1 ? idat[0] : concat(idat);
+  const raw = new Uint8Array(inflateSync(compressed));
+  if (raw.length < height * (bytesPerRow + 1)) {
+    throw new Error("Truncated PNG pixel data");
+  }
+  const rows = unfilter(raw, height, bytesPerRow, bytesPerPixel);
+  const out = new Uint8Array(width * height * 4);
+  const maxSample = (1 << Math.min(bitDepth, 8)) - 1;
+  const scale = bitDepth === 16 ? 1 / 257 : 255 / maxSample;
+  for (let y = 0; y < height; y++) {
+    const row = rows.subarray(y * bytesPerRow, (y + 1) * bytesPerRow);
+    for (let x = 0; x < width; x++) {
+      const to8 = (sample) => bitDepth === 8 || bitDepth === 16 ? sample : Math.round(sample * scale);
+      let r;
+      let g;
+      let b;
+      let a = 255;
+      switch (colorType) {
+        case 0: {
+          const grey = to8(sampleAt(row, 0, x, bitDepth));
+          r = g = b = grey;
+          break;
+        }
+        case 2:
+          r = to8(sampleAt(row, 0, x * 3, bitDepth));
+          g = to8(sampleAt(row, 0, x * 3 + 1, bitDepth));
+          b = to8(sampleAt(row, 0, x * 3 + 2, bitDepth));
+          break;
+        case 3: {
+          const index = sampleAt(row, 0, x, bitDepth);
+          const p = index * 3;
+          if (!palette || p + 2 >= palette.length)
+            throw new Error("PNG palette entry missing");
+          r = palette[p];
+          g = palette[p + 1];
+          b = palette[p + 2];
+          if (transparency && index < transparency.length)
+            a = transparency[index];
+          break;
+        }
+        case 4: {
+          const grey = to8(sampleAt(row, 0, x * 2, bitDepth));
+          r = g = b = grey;
+          a = to8(sampleAt(row, 0, x * 2 + 1, bitDepth));
+          break;
+        }
+        default: {
+          r = to8(sampleAt(row, 0, x * 4, bitDepth));
+          g = to8(sampleAt(row, 0, x * 4 + 1, bitDepth));
+          b = to8(sampleAt(row, 0, x * 4 + 2, bitDepth));
+          a = to8(sampleAt(row, 0, x * 4 + 3, bitDepth));
+          break;
+        }
       }
-    } else {
-      const sep = `\u250C${colW.map((w) => "\u2500".repeat(w + 2)).join("\u252C")}\u2510`;
-      const mid = `\u251C${colW.map((w) => "\u2500".repeat(w + 2)).join("\u253C")}\u2524`;
-      const end = `\u2514${colW.map((w) => "\u2500".repeat(w + 2)).join("\u2534")}\u2518`;
-      out.push(sep);
-      dataRows.forEach((row, i) => {
-        const cells = colW.map((w, ci) => (row[ci] ?? "").trim().padEnd(w));
-        out.push(`\u2502 ${cells.map((c) => ` ${c} `).join("\u2502")}\u2502`);
-        if (i === 0) out.push(mid);
-      });
-      out.push(end);
-    }
-    out.push("");
-    tableRows = [];
-  }
-  function renderInline(line) {
-    line = line.replace(/\*\*(.+?)\*\*/g, "$1");
-    line = line.replace(/\*([^*]+?)\*/g, "$1");
-    line = line.replace(/`([^`]+)`/g, "\u27E8$1\u27E9");
-    line = line.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
-    line = line.replace(/!\[([^\]]*)\]\([^)]+\)/g, "\u{1F5BC} $1");
-    return line;
-  }
-  function wrapLine(line, maxW) {
-    if (line.length <= maxW) return [line];
-    const parts = [];
-    let remaining = line;
-    while (remaining.length > maxW) {
-      let breakAt = maxW;
-      const spaceIdx = remaining.lastIndexOf(" ", maxW);
-      if (spaceIdx > maxW / 2) breakAt = spaceIdx;
-      parts.push(remaining.slice(0, breakAt));
-      remaining = remaining.slice(breakAt).replace(/^ /, "");
-    }
-    if (remaining) parts.push(remaining);
-    return parts;
-  }
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (/^```/.test(line)) {
-      if (inCodeBlock) {
-        flushCode();
-        inCodeBlock = false;
-      } else {
-        inCodeBlock = true;
-        codeLang = line.slice(3).trim();
+      if (colorType === 0 && transparency && transparency.length >= 2) {
+        const key = transparency[0] << 8 | transparency[1];
+        const sample = sampleAt(row, 0, x, bitDepth);
+        if (sample === key) a = 0;
       }
-      continue;
-    }
-    if (inCodeBlock) {
-      codeLines.push(line);
-      continue;
+      const o = (y * width + x) * 4;
+      out[o] = r;
+      out[o + 1] = g;
+      out[o + 2] = b;
+      out[o + 3] = a;
     }
-    if (line.includes("|")) {
-      const cells = line.split("|").map((c) => c.trim()).filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
-      if (cells.length >= 2) {
-        inTable = true;
-        tableRows.push(cells);
+  }
+  return { width, height, data: out };
+}
+function concat(chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    merged.set(c, offset);
+    offset += c.length;
+  }
+  return merged;
+}
+
+// src/image-render.ts
+var DEFAULT_CELL_ASPECT = 0.5;
+var HALF_BLOCK = "\u2580";
+function fitImageToCells(imgWidth, imgHeight, opts) {
+  const cellAspect = opts.cellAspect ?? DEFAULT_CELL_ASPECT;
+  const minCols = Math.max(1, Math.min(opts.maxCols, 8));
+  if (imgWidth <= 0 || imgHeight <= 0) {
+    return { cols: minCols, rows: 1 };
+  }
+  const rowsPerCol = cellAspect * (imgHeight / imgWidth);
+  let cols = Math.max(minCols, Math.floor(opts.maxCols));
+  let rows = Math.max(1, Math.round(cols * rowsPerCol));
+  if (rows > opts.maxRows) {
+    rows = Math.max(1, opts.maxRows);
+    cols = Math.max(
+      minCols,
+      Math.min(cols, Math.floor(rows / Math.max(rowsPerCol, 1e-6)))
+    );
+  }
+  return { cols, rows };
+}
+function pixelAt(img, x, y, background) {
+  const o = (y * img.width + x) * 4;
+  const a = img.data[o + 3] / 255;
+  if (a >= 1) return [img.data[o], img.data[o + 1], img.data[o + 2]];
+  const mix = (channel, bg) => Math.round(channel * a + bg * (1 - a));
+  return [
+    mix(img.data[o], background[0]),
+    mix(img.data[o + 1], background[1]),
+    mix(img.data[o + 2], background[2])
+  ];
+}
+function toHalfBlocks(img, opts = {}) {
+  const background = opts.background ?? [0, 0, 0];
+  const cells = [];
+  for (let row = 0; row * 2 < img.height; row++) {
+    const cellsRow = [];
+    const topY = row * 2;
+    const bottomY = topY + 1;
+    for (let x = 0; x < img.width; x++) {
+      const top = pixelAt(img, x, topY, background);
+      const bottom = bottomY < img.height ? pixelAt(img, x, bottomY, background) : top;
+      cellsRow.push({ top, bottom });
+    }
+    cells.push(cellsRow);
+  }
+  return { cols: img.width, rows: cells.length, cells };
+}
+function toImageRuns(image) {
+  return image.cells.map((cells) => {
+    const runs = [];
+    for (const cell of cells) {
+      const last = runs[runs.length - 1];
+      if (last && last.top[0] === cell.top[0] && last.top[1] === cell.top[1] && last.top[2] === cell.top[2] && last.bottom[0] === cell.bottom[0] && last.bottom[1] === cell.bottom[1] && last.bottom[2] === cell.bottom[2]) {
+        last.text += HALF_BLOCK;
         continue;
       }
-    } else if (inTable) {
-      flushTable();
-      inTable = false;
+      runs.push({ text: HALF_BLOCK, top: cell.top, bottom: cell.bottom });
     }
-    if (/^(\s*[-*_]){3,}\s*$/.test(line)) {
-      out.push("\u2500".repeat(Math.min(width, 40)));
-      out.push("");
+    return runs;
+  });
+}
+var MAX_SOURCE_PIXELS = 2e7;
+async function rasterizeImage(bytes, opts) {
+  const ImageCtor = globalThis.Bun?.Image;
+  if (!ImageCtor) return null;
+  const source = new ImageCtor(bytes, { maxPixels: MAX_SOURCE_PIXELS });
+  try {
+    const meta = await source.metadata();
+    const { cols, rows } = fitImageToCells(meta.width, meta.height, opts);
+    const png = await source.resize(cols, rows * 2, { fit: "fill" }).png({ compressionLevel: 1 }).bytes();
+    return toHalfBlocks(decodePng(png), { background: opts.background });
+  } catch {
+    return null;
+  }
+}
+
+// src/image-loader.ts
+var MAX_IMAGE_BYTES = 6 * 1024 * 1024;
+var BADGE_HOST = /(^|\.)(shields\.io|badgen\.net|badge\.fury\.io|codecov\.io|coveralls\.io|travis-ci\.(org|com)|snyk\.io|sonarcloud\.io|david-dm\.(org|io))$/i;
+var RAW_HOSTS = /* @__PURE__ */ new Set([
+  "raw.githubusercontent.com",
+  "camo.githubusercontent.com",
+  "user-images.githubusercontent.com",
+  "private-user-images.githubusercontent.com",
+  "avatars.githubusercontent.com",
+  "objects.githubusercontent.com"
+]);
+var RASTER_EXT = /\.(png|jpe?g|webp|gif|bmp|avif|heic|tiff?)(?:[?#]|$)/i;
+var CACHE_LIMIT = 24;
+var MAX_CONCURRENT_IMAGE_FETCHES = 4;
+var cache = /* @__PURE__ */ new Map();
+var activeFetches = 0;
+var waiting = [];
+function releaseSlot() {
+  activeFetches--;
+  waiting.shift()?.();
+}
+async function withSlot(job) {
+  if (activeFetches >= MAX_CONCURRENT_IMAGE_FETCHES) {
+    await new Promise((resolve) => waiting.push(resolve));
+  }
+  activeFetches++;
+  try {
+    return await job();
+  } finally {
+    releaseSlot();
+  }
+}
+function decodeDataUri(uri) {
+  const match = /^data:([^;,]+)?(;base64)?,(.*)$/is.exec(uri);
+  if (!match) return null;
+  const mime = (match[1] ?? "").toLowerCase();
+  if (mime.includes("svg")) return null;
+  const payload = match[3];
+  try {
+    if (match[2]) return new Uint8Array(Buffer.from(payload, "base64"));
+    return new Uint8Array(Buffer.from(decodeURIComponent(payload), "binary"));
+  } catch {
+    return null;
+  }
+}
+function toRawGitHubUrl(url) {
+  if (url.hostname.toLowerCase() !== "github.com") return url;
+  const match = /^\/([^/]+)\/([^/]+)\/(?:blob|raw)\/(.+)$/.exec(url.pathname);
+  if (!match) return url;
+  const [, owner, repo, rest] = match;
+  return new URL(
+    `https://raw.githubusercontent.com/${owner}/${repo}/${rest}${url.search}`
+  );
+}
+function resolveRootRelative(path, base) {
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return null;
+  }
+  if (parsed.hostname.toLowerCase() !== "raw.githubusercontent.com") {
+    return null;
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length < 3) return null;
+  return new URL(`${parsed.origin}/${segments.slice(0, 3).join("/")}${path}`);
+}
+function resolveReadmeImageUrl(raw, base) {
+  const cleaned = raw.trim();
+  if (!cleaned) return null;
+  if (/^data:/i.test(cleaned)) {
+    return isRenderableImageUrl(cleaned) ? cleaned : null;
+  }
+  let url = null;
+  try {
+    url = cleaned.startsWith("/") ? resolveRootRelative(cleaned, base) : new URL(cleaned, base);
+  } catch {
+    return null;
+  }
+  if (!url) return null;
+  url = toRawGitHubUrl(url);
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  url.hash = "";
+  const resolved = url.toString();
+  return isRenderableImageUrl(resolved) ? resolved : null;
+}
+function isRenderableImageUrl(url) {
+  if (/^data:/i.test(url)) return !/svg/i.test(url.slice(0, 64));
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  if (BADGE_HOST.test(parsed.hostname)) return false;
+  const path = parsed.pathname.toLowerCase();
+  if (path.endsWith(".svg") || path.endsWith(".svgz")) return false;
+  if (parsed.hostname.toLowerCase().endsWith("github.com")) {
+    if (/^\/user-attachments\//.test(path)) return true;
+    if (!RAW_HOSTS.has(parsed.hostname)) {
+      return /\.(png|jpe?g|webp|gif|bmp|avif|heic|tiff?)$/i.test(path);
+    }
+  }
+  if (/\.[a-z0-9]{1,5}$/.test(path) && !RASTER_EXT.test(path)) return false;
+  return true;
+}
+function isGitHubHost(hostname) {
+  return /(^|\.)githubusercontent\.com$|(^|\.)github\.com$/i.test(hostname);
+}
+async function fetchImageBytes(url, opts = {}) {
+  const cached2 = cache.get(url);
+  if (cached2) return cached2;
+  const pending = withSlot(() => loadImageBytes(url, opts));
+  cache.set(url, pending);
+  while (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value;
+    if (oldest === void 0) break;
+    cache.delete(oldest);
+  }
+  return pending;
+}
+async function loadImageBytes(url, opts) {
+  if (/^data:/i.test(url)) return decodeDataUri(url);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = {
+      "User-Agent": "ghfind/1.0",
+      Accept: "image/*,*/*;q=0.5"
+    };
+    let host = "";
+    try {
+      host = new URL(url).hostname;
+    } catch {
+      return null;
+    }
+    if (opts.token && isGitHubHost(host)) {
+      headers.Authorization = `Bearer ${opts.token}`;
+    }
+    const res = await fetchImpl(url, { headers, signal: controller.signal });
+    if (!res.ok) return null;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType && !/^image\//i.test(contentType)) {
+      const githubHost = isGitHubHost(host);
+      if (!githubHost || !/octet-stream/i.test(contentType)) return null;
+    }
+    if (/svg/i.test(contentType)) return null;
+    const declared = Number(res.headers.get("content-length") ?? "0");
+    if (declared > MAX_IMAGE_BYTES) return null;
+    const buffer = new Uint8Array(await res.arrayBuffer());
+    if (buffer.byteLength === 0 || buffer.byteLength > MAX_IMAGE_BYTES) {
+      return null;
+    }
+    return buffer;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function readmeBaseUrl(owner, repo, branch, path = "README.md") {
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+}
+
+// src/markdown-images.ts
+var IMG_TAG = /<img\b[^>]*?src\s*=\s*["']([^"']+)["'][^>]*>/gi;
+var ALT_ATTR = /\balt\s*=\s*["']([^"']*)["']/i;
+var HTML_TAG = /<\/?[a-z][^>]*>/gi;
+function imagesFromHtml(raw) {
+  if (!raw || !/<img\b/i.test(raw)) return [];
+  const withoutTags = raw.replace(IMG_TAG, "").replace(/<\/?(?:p|div|center|br|a|picture|source)\b[^>]*>/gi, "").trim();
+  if (withoutTags) return [];
+  const refs = [];
+  for (const match of raw.matchAll(IMG_TAG)) {
+    const tag = match[0];
+    const alt = ALT_ATTR.exec(tag)?.[1] ?? "";
+    refs.push({ href: match[1], alt });
+  }
+  return refs;
+}
+function inlinePlainText(tokens) {
+  if (!tokens) return "";
+  let out = "";
+  for (const token of tokens) {
+    if (token.type === "image") continue;
+    if (token.type === "html") {
+      out += (token.raw ?? "").replace(HTML_TAG, "");
       continue;
     }
-    const headingMatch = line.match(/^(#{1,6})\s+(.+)/);
-    if (headingMatch) {
-      const level = headingMatch[1].length;
-      const text = renderInline(headingMatch[2]);
-      const prefix = "\u2588 ".repeat(level);
-      out.push("");
-      out.push(prefix + text);
-      out.push("");
+    if (token.type === "br") {
+      out += "\n";
       continue;
     }
-    const bqMatch = line.match(/^>\s?(.*)/);
-    if (bqMatch) {
-      const inner = renderInline(bqMatch[1]);
-      for (const wl of wrapLine(inner, width - 4)) {
-        out.push(`\u2502 ${wl}`);
-      }
+    if (token.text && (!token.tokens || token.tokens.length === 0)) {
+      out += token.text;
       continue;
     }
-    const ulMatch = line.match(/^(\s*)[-*+]\s+(.*)/);
-    if (ulMatch) {
-      const indent = ulMatch[1].length;
-      const depth = Math.floor(indent / 2);
-      const prefix = `${"  ".repeat(depth)}\u2022 `;
-      const inner = renderInline(ulMatch[2]);
-      for (const wl of wrapLine(inner, width - prefix.length)) {
-        out.push(prefix + wl);
-      }
+    if (token.tokens?.length) {
+      out += inlinePlainText(token.tokens);
       continue;
     }
-    const olMatch = line.match(/^(\s*)\d+\.\s+(.*)/);
-    if (olMatch) {
-      const indent = olMatch[1].length;
-      const depth = Math.floor(indent / 2);
-      const prefix = `${"  ".repeat(depth)}\u25E6 `;
-      const inner = renderInline(olMatch[2]);
-      for (const wl of wrapLine(inner, width - prefix.length)) {
-        out.push(prefix + wl);
+    if (token.raw) out += token.raw.replace(HTML_TAG, "");
+  }
+  return out;
+}
+function extractImageRefs(token) {
+  const images = [];
+  const collect = (inline2) => {
+    if (inline2.type === "image") {
+      if (inline2.href)
+        images.push({ href: inline2.href, alt: inline2.text ?? "" });
+      return true;
+    }
+    if (inline2.type === "html") {
+      const refs = imagesFromHtml(inline2.raw);
+      if (refs.length > 0) {
+        images.push(...refs);
+        return true;
       }
-      continue;
+      return !(inline2.raw ?? "").replace(HTML_TAG, "").trim();
     }
-    if (line.trim() === "") {
-      out.push("");
-      continue;
+    if (inline2.type === "text" || inline2.type === "escape") {
+      return !(inline2.text ?? "").trim();
+    }
+    return false;
+  };
+  if (token.type === "image" && token.href) {
+    return [{ href: token.href, alt: token.text ?? "" }];
+  }
+  if (token.type === "html") {
+    const refs = imagesFromHtml(token.raw);
+    return refs.length > 0 ? refs : null;
+  }
+  const inline = token.tokens ?? [];
+  if (inline.length === 0) return null;
+  for (const child of inline) {
+    if (!collect(child)) return null;
+  }
+  return images.length > 0 ? images : null;
+}
+
+// src/markdown-view.ts
+var MAX_IMAGE_ROWS = 24;
+var RASTER_CACHE_LIMIT = 32;
+function createMarkdownStyle(colors2) {
+  const surface = colors2.surface ?? colors2.bg;
+  return SyntaxStyle.fromStyles({
+    default: { fg: colors2.text ?? "#ffffff" },
+    conceal: { fg: colors2.muted ?? "#888888" },
+    "markup.heading": { fg: colors2.accent ?? colors2.blue, bold: true },
+    "markup.strong": { fg: colors2.text ?? "#ffffff", bold: true },
+    "markup.italic": { fg: colors2.text ?? "#ffffff", italic: true },
+    "markup.strikethrough": { fg: colors2.muted ?? "#888888", dim: true },
+    "markup.raw": { fg: colors2.green ?? "#a6e3a1", bg: surface },
+    "markup.raw.block": { fg: colors2.green ?? "#a6e3a1" },
+    "markup.link": { fg: colors2.accent ?? colors2.blue },
+    "markup.link.label": {
+      fg: colors2.accent ?? colors2.blue,
+      underline: true
+    },
+    "markup.link.url": { fg: colors2.muted ?? "#888888", underline: true },
+    "markup.quote": { fg: colors2.muted ?? "#888888", italic: true },
+    "markup.list": { fg: colors2.blue ?? colors2.accent }
+  });
+}
+function hexToRgb(hex) {
+  const fallback = [0, 0, 0];
+  if (!hex) return fallback;
+  const match = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!match) return fallback;
+  const value = Number.parseInt(match[1], 16);
+  return [value >> 16 & 255, value >> 8 & 255, value & 255];
+}
+function rgba(color) {
+  return RGBA.fromValues(color[0], color[1], color[2], 255);
+}
+function imageStyledText(image) {
+  const chunks = [];
+  toImageRuns(image).forEach((runs, rowIndex) => {
+    if (rowIndex > 0) chunks.push({ __isChunk: true, text: "\n" });
+    for (const run2 of runs) {
+      chunks.push({
+        __isChunk: true,
+        text: run2.text,
+        fg: rgba(run2.top),
+        bg: rgba(run2.bottom)
+      });
+    }
+  });
+  return new StyledText3(chunks);
+}
+function createMarkdownView(opts) {
+  const { renderer, colors: colors2 } = opts;
+  const maxImageRows = opts.maxImageRows ?? MAX_IMAGE_ROWS;
+  const rasterCache = /* @__PURE__ */ new Map();
+  let imagesEnabled = opts.images ?? true;
+  let imageBase = opts.imageBase;
+  const text = () => colors2.text ?? "#ffffff";
+  const bg = () => opts.background ?? colors2.bg ?? "#000000";
+  const muted = () => colors2.muted ?? "#888888";
+  const renderable = new MarkdownRenderable(renderer, {
+    content: "",
+    syntaxStyle: createMarkdownStyle(colors2),
+    fg: text(),
+    bg: bg(),
+    conceal: true,
+    streaming: true,
+    internalBlockMode: "top-level",
+    // Borderless columns are the top-level default; boxed tables read better
+    // for the multi-column tables READMEs use.
+    tableOptions: { style: "grid" },
+    width: "100%"
+  });
+  const caption = (label, color = muted()) => new TextRenderable3(renderer, {
+    content: `  ${label}`,
+    fg: color,
+    bg: bg(),
+    wrapMode: "word",
+    flexShrink: 0,
+    width: "100%"
+  });
+  const rasterize = (url) => {
+    const maxCols = Math.max(8, Math.floor(opts.getImageWidth?.() ?? 100));
+    const key = `${maxCols}|${url}`;
+    const cached2 = rasterCache.get(key);
+    if (cached2) return cached2;
+    const pending = (async () => {
+      const loader = opts.loadImage;
+      if (!loader) return null;
+      const bytes = await loader(url);
+      if (!bytes) return null;
+      return rasterizeImage(bytes, {
+        maxCols,
+        maxRows: maxImageRows,
+        background: hexToRgb(bg())
+      });
+    })();
+    rasterCache.set(key, pending);
+    while (rasterCache.size > RASTER_CACHE_LIMIT) {
+      const oldest = rasterCache.keys().next().value;
+      if (oldest === void 0) break;
+      rasterCache.delete(oldest);
+    }
+    return pending;
+  };
+  const imageNode = (image) => {
+    const label = `\u{1F5BC}  ${image.alt.trim() || "image"}`;
+    const url = imageBase ? resolveReadmeImageUrl(image.href, imageBase) : null;
+    if (!imagesEnabled || !url || !opts.loadImage) return caption(label);
+    const container = new BoxRenderable3(renderer, {
+      flexDirection: "column",
+      flexShrink: 0,
+      width: "100%"
+    });
+    const placeholder = caption(`${label}  (loading\u2026)`);
+    container.add(placeholder);
+    void rasterize(url).then(
+      (cells) => {
+        if (container.isDestroyed || !container.parent) return;
+        container.remove(placeholder);
+        placeholder.destroy();
+        container.add(caption(label));
+        if (cells) {
+          container.add(
+            new TextRenderable3(renderer, {
+              content: imageStyledText(cells),
+              bg: bg(),
+              wrapMode: "none",
+              selectable: false,
+              flexShrink: 0
+            })
+          );
+        }
+        renderable.requestRender();
+      },
+      (err) => {
+        void err;
+      }
+    );
+    return container;
+  };
+  const headingNode = (token) => {
+    const heading = inlinePlainText(token.tokens).trim();
+    if (!heading) return void 0;
+    const depth = token.depth ?? 1;
+    const color = depth <= 2 ? colors2.accent : colors2.teal ?? colors2.accent;
+    return new TextRenderable3(renderer, {
+      content: new StyledText3([
+        {
+          __isChunk: true,
+          text: heading,
+          fg: RGBA.fromHex(color ?? "#ffffff"),
+          attributes: createTextAttributes({
+            bold: true,
+            underline: depth === 1
+          })
+        }
+      ]),
+      bg: bg(),
+      wrapMode: "word",
+      flexShrink: 0,
+      width: "100%"
+    });
+  };
+  const buildRenderNode = () => (token, _context) => {
+    if (token.type === "heading") return headingNode(token);
+    const images = extractImageRefs(token);
+    if (images && images.length > 0) {
+      const box = new BoxRenderable3(renderer, {
+        flexDirection: "column",
+        flexShrink: 0,
+        width: "100%",
+        marginTop: 1
+      });
+      for (const image of images) box.add(imageNode(image));
+      return box;
     }
-    const rendered = renderInline(line);
-    for (const wl of wrapLine(rendered, width)) {
-      out.push(wl);
+    return void 0;
+  };
+  renderable.renderNode = buildRenderNode();
+  return {
+    renderable,
+    get imagesEnabled() {
+      return imagesEnabled;
+    },
+    setContent(markdown, base) {
+      if (base !== void 0) imageBase = base;
+      renderable.syntaxStyle = createMarkdownStyle(colors2);
+      renderable.fg = text();
+      renderable.bg = bg();
+      renderable.content = markdown;
+      renderable.streaming = false;
+      renderable.requestRender();
+    },
+    setImagesEnabled(enabled) {
+      if (imagesEnabled === enabled) return;
+      imagesEnabled = enabled;
+      renderable.renderNode = buildRenderNode();
+      renderable.requestRender();
     }
+  };
+}
+
+// src/readme.ts
+var CANDIDATES = [
+  ["main", "README.md"],
+  ["master", "README.md"],
+  ["main", "README.rst"]
+];
+async function fetchReadme(owner, repo, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const headers = { "User-Agent": "ghfind/1.0" };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+  const attempts = CANDIDATES.map(async ([branch, file]) => {
+    const url = readmeBaseUrl(owner, repo, branch, file);
+    const res = await fetchImpl(url, { headers });
+    if (!res.ok) throw new Error(`no readme at ${url}`);
+    return { text: await res.text(), sourceUrl: url };
+  });
+  try {
+    return await Promise.any(attempts);
+  } catch {
+    return null;
   }
-  if (inCodeBlock) flushCode();
-  if (inTable) flushTable();
-  return out.join("\n");
 }
 
 // src/explore.ts
@@ -3746,7 +4360,7 @@ function fetchReleaseNotes(version) {
 }
 
 // src/landing.ts
-import { BoxRenderable as BoxRenderable3, TextRenderable as TextRenderable3 } from "@opentui/core";
+import { BoxRenderable as BoxRenderable4, TextRenderable as TextRenderable4 } from "@opentui/core";
 function landingKeysActive(mode, overlay) {
   return mode === "landing" && overlay === "none";
 }
@@ -3878,13 +4492,13 @@ async function launchBrowser(theme_override) {
   let deepDiveActive = false;
   const compareList = [];
   const _quitArmed = false;
-  const header = new TextRenderable4(renderer, {
+  const header = new TextRenderable5(renderer, {
     content: " ghfind \u2014 GitHub repo browser   [/]search  [Space]menu  [\u2192]open  [?]help  [q]uit",
     bg: colors.bg,
     fg: colors.muted,
     height: 1
   });
-  const trendingTabBox = new BoxRenderable4(renderer, {
+  const trendingTabBox = new BoxRenderable5(renderer, {
     flexDirection: "row",
     height: 1,
     backgroundColor: colors.surface,
@@ -3899,7 +4513,7 @@ async function launchBrowser(theme_override) {
     TAB_NAMES.forEach((name, i) => {
       const isActive = name === trendingTab;
       const label = ` ${name} `;
-      const tt = new TextRenderable4(renderer, {
+      const tt = new TextRenderable5(renderer, {
         content: label,
         fg: isActive ? colors.bg : colors.muted,
         bg: isActive ? colors.blue : colors.bg,
@@ -3908,7 +4522,7 @@ async function launchBrowser(theme_override) {
       trendingTabTexts.push(tt);
       trendingTabBox.add(tt);
       if (i < TAB_NAMES.length - 1) {
-        const sp = new TextRenderable4(renderer, {
+        const sp = new TextRenderable5(renderer, {
           content: "  ",
           fg: colors.muted,
           bg: colors.bg,
@@ -3921,7 +4535,7 @@ async function launchBrowser(theme_override) {
   }
   root.add(header);
   root.add(trendingTabBox);
-  const searchBox = new BoxRenderable4(renderer, {
+  const searchBox = new BoxRenderable5(renderer, {
     visible: true,
     width: "100%",
     flexDirection: "row",
@@ -3940,7 +4554,7 @@ async function launchBrowser(theme_override) {
   });
   searchBox.add(searchInput);
   root.add(searchBox);
-  const toolbarText = new TextRenderable4(renderer, {
+  const toolbarText = new TextRenderable5(renderer, {
     content: formatToolbar(currentSort, currentLimit, totalCount),
     visible: true,
     // hidden in trending mode
@@ -3949,14 +4563,14 @@ async function launchBrowser(theme_override) {
     paddingX: 1
   });
   root.add(toolbarText);
-  const body = new BoxRenderable4(renderer, {
+  const body = new BoxRenderable5(renderer, {
     flexDirection: "row",
     flexGrow: 1,
     gap: 1,
     paddingY: 1,
     paddingX: 1
   });
-  const resultsBox = new BoxRenderable4(renderer, {
+  const resultsBox = new BoxRenderable5(renderer, {
     border: true,
     borderColor: colors.border,
     title: " Results ",
@@ -3985,7 +4599,7 @@ async function launchBrowser(theme_override) {
     itemSpacing: 0
   });
   resultsBox.add(resultsSelect);
-  const detailBox = new BoxRenderable4(renderer, {
+  const detailBox = new BoxRenderable5(renderer, {
     width: "50%",
     flexDirection: "column",
     paddingX: 1,
@@ -3993,7 +4607,7 @@ async function launchBrowser(theme_override) {
     focusable: false,
     backgroundColor: colors.surface
   });
-  const detailText = new TextRenderable4(renderer, {
+  const detailText = new TextRenderable5(renderer, {
     content: "",
     fg: colors.text,
     wrapMode: "none"
@@ -4002,7 +4616,7 @@ async function launchBrowser(theme_override) {
   body.add(resultsBox);
   body.add(detailBox);
   root.add(body);
-  const landingBox = new BoxRenderable4(renderer, {
+  const landingBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     flexDirection: "column",
@@ -4010,7 +4624,7 @@ async function launchBrowser(theme_override) {
     justifyContent: "center"
   });
   root.add(landingBox);
-  const landingBanner = new TextRenderable4(renderer, {
+  const landingBanner = new TextRenderable5(renderer, {
     content: [
       " \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ",
       "\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557",
@@ -4060,7 +4674,7 @@ async function launchBrowser(theme_override) {
   const landingCards = [];
   for (let i = 0; i < landingOptions.length; i++) {
     const opt = landingOptions[i];
-    const card = new BoxRenderable4(renderer, {
+    const card = new BoxRenderable5(renderer, {
       flexDirection: "column",
       height: 5,
       width: "60%",
@@ -4072,18 +4686,18 @@ async function launchBrowser(theme_override) {
     });
     landingCards.push(card);
     landingBox.add(card);
-    const spacerTop = new TextRenderable4(renderer, { content: "", height: 1 });
-    const titleLine = new TextRenderable4(renderer, {
+    const spacerTop = new TextRenderable5(renderer, { content: "", height: 1 });
+    const titleLine = new TextRenderable5(renderer, {
       content: opt.title,
       fg: i === 0 ? colors.accent : colors.text,
       height: 1
     });
-    const spacerBot = new TextRenderable4(renderer, { content: "", height: 1 });
+    const spacerBot = new TextRenderable5(renderer, { content: "", height: 1 });
     card.add(spacerTop);
     card.add(titleLine);
     card.add(spacerBot);
   }
-  const landingHint = new TextRenderable4(renderer, {
+  const landingHint = new TextRenderable5(renderer, {
     content: "   \u2191\u2193 Navigate  \u21E9 Select  [b]ookmarks  [?]help  [q]uit",
     fg: colors.muted,
     bg: colors.bg,
@@ -4226,7 +4840,7 @@ async function launchBrowser(theme_override) {
     renderer.requestRender();
   }
   const helpSections = buildHelpSections();
-  const helpBox = new BoxRenderable4(renderer, {
+  const helpBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg
@@ -4248,7 +4862,7 @@ async function launchBrowser(theme_override) {
     }
   });
   for (const section of helpSections) {
-    const sectionBox = new BoxRenderable4(renderer, {
+    const sectionBox = new BoxRenderable5(renderer, {
       title: section.title,
       titleColor: colors[section.titleColor] ?? section.titleColor,
       flexDirection: "column",
@@ -4260,7 +4874,7 @@ async function launchBrowser(theme_override) {
     for (const row of section.rows) {
       const keys = row.keys.padEnd(HELP_KEYS_COLUMN);
       sectionBox.add(
-        new TextRenderable4(renderer, {
+        new TextRenderable5(renderer, {
           content: `  ${keys} ${row.action}`,
           fg: colors.text
         })
@@ -4268,7 +4882,7 @@ async function launchBrowser(theme_override) {
     }
     if (section.note) {
       sectionBox.add(
-        new TextRenderable4(renderer, {
+        new TextRenderable5(renderer, {
           content: `  ${section.note}`,
           fg: colors.muted
         })
@@ -4278,7 +4892,7 @@ async function launchBrowser(theme_override) {
   }
   helpBox.add(helpScroll);
   root.add(helpBox);
-  const historyBox = new BoxRenderable4(renderer, {
+  const historyBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4313,7 +4927,7 @@ async function launchBrowser(theme_override) {
     }
     historySelect.setSelectedIndex(0);
   }
-  const bookmarksBox = new BoxRenderable4(renderer, {
+  const bookmarksBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4348,7 +4962,7 @@ async function launchBrowser(theme_override) {
     }
     bookmarksSelect.setSelectedIndex(0);
   }
-  const savedBox = new BoxRenderable4(renderer, {
+  const savedBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4368,7 +4982,7 @@ async function launchBrowser(theme_override) {
   });
   savedBox.add(savedSelect);
   root.add(savedBox);
-  const topicsBox = new BoxRenderable4(renderer, {
+  const topicsBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4403,7 +5017,7 @@ async function launchBrowser(theme_override) {
     }
     topicsSelect.setSelectedIndex(0);
   }
-  const exportBox = new BoxRenderable4(renderer, {
+  const exportBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4440,28 +5054,28 @@ async function launchBrowser(theme_override) {
   });
   exportBox.add(exportSelect);
   root.add(exportBox);
-  const compareBox = new BoxRenderable4(renderer, {
+  const compareBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
     title: " Comparison ",
     titleColor: colors.yellow
   });
-  const compareText = new TextRenderable4(renderer, {
+  const compareText = new TextRenderable5(renderer, {
     content: "",
     fg: colors.text,
     bg: colors.bg
   });
   compareBox.add(compareText);
   root.add(compareBox);
-  const notifsBox = new BoxRenderable4(renderer, {
+  const notifsBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
     title: " Notifications ",
     titleColor: colors.yellow
   });
-  const notifsText = new TextRenderable4(renderer, {
+  const notifsText = new TextRenderable5(renderer, {
     content: "(no notifications)",
     fg: colors.text,
     bg: colors.bg
@@ -4476,7 +5090,7 @@ async function launchBrowser(theme_override) {
       notifsText.content = notifs2.map((n) => `  ${n.icon} ${n.message}`).join("\n");
     }
   }
-  const shareBox = new BoxRenderable4(renderer, {
+  const shareBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.bg,
@@ -4535,7 +5149,7 @@ async function launchBrowser(theme_override) {
     }
     savedSelect.setSelectedIndex(0);
   }
-  const leaderDim = new BoxRenderable4(renderer, {
+  const leaderDim = new BoxRenderable5(renderer, {
     visible: false,
     position: "absolute",
     top: 0,
@@ -4546,7 +5160,7 @@ async function launchBrowser(theme_override) {
     // 60% opacity black (hex alpha: 0x99 ≈ 153/255)
   });
   root.add(leaderDim);
-  const leaderBox = new BoxRenderable4(renderer, {
+  const leaderBox = new BoxRenderable5(renderer, {
     visible: false,
     position: "absolute",
     width: "80%",
@@ -4578,7 +5192,7 @@ async function launchBrowser(theme_override) {
     selectedDescriptionColor: colors.selectionText,
     itemSpacing: 0
   });
-  const leaderFooter = new TextRenderable4(renderer, {
+  const leaderFooter = new TextRenderable5(renderer, {
     content: " \u2191\u2193 select   Enter run   Esc/q close ",
     fg: colors.muted,
     bg: colors.surfaceDim,
@@ -4589,7 +5203,7 @@ async function launchBrowser(theme_override) {
   leaderBox.add(leaderFooter);
   root.add(leaderDim);
   root.add(leaderBox);
-  const updateDim = new BoxRenderable4(renderer, {
+  const updateDim = new BoxRenderable5(renderer, {
     visible: false,
     position: "absolute",
     top: 0,
@@ -4599,7 +5213,7 @@ async function launchBrowser(theme_override) {
     backgroundColor: "#00000088"
   });
   root.add(updateDim);
-  const updateBox = new BoxRenderable4(renderer, {
+  const updateBox = new BoxRenderable5(renderer, {
     visible: false,
     position: "absolute",
     width: "55%",
@@ -4618,11 +5232,19 @@ async function launchBrowser(theme_override) {
     paddingLeft: 2,
     paddingRight: 2
   });
-  const updateText = new TextRenderable4(renderer, {
+  const updateHeader = new TextRenderable5(renderer, {
     content: "",
     fg: colors.accent,
     bg: colors.surfaceDim
   });
+  const updateNotes = createMarkdownView({
+    renderer,
+    colors,
+    // Notes ship with the release and are mostly prose/lists; skip the
+    // image pipeline in this narrow panel.
+    images: false,
+    background: colors.surfaceDim
+  });
   const updateScroll = new ScrollBoxRenderable3(renderer, {
     flexGrow: 1,
     backgroundColor: colors.surfaceDim,
@@ -4642,14 +5264,14 @@ async function launchBrowser(theme_override) {
     }
   });
   let updateSelectedOption = 0;
-  const updateOptionsRow = new BoxRenderable4(renderer, {
+  const updateOptionsRow = new BoxRenderable5(renderer, {
     flexDirection: "row",
     gap: 1,
     backgroundColor: colors.surfaceDim,
     height: 3,
     width: "100%"
   });
-  const updateNowBox = new BoxRenderable4(renderer, {
+  const updateNowBox = new BoxRenderable5(renderer, {
     border: true,
     borderColor: updateSelectedOption === 0 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -4658,13 +5280,13 @@ async function launchBrowser(theme_override) {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const updateNowText = new TextRenderable4(renderer, {
+  const updateNowText = new TextRenderable5(renderer, {
     content: "   Update Now  ",
     fg: updateSelectedOption === 0 ? colors.yellow : colors.text,
     bg: colors.surfaceDim
   });
   updateNowBox.add(updateNowText);
-  const laterBox = new BoxRenderable4(renderer, {
+  const laterBox = new BoxRenderable5(renderer, {
     border: true,
     borderColor: updateSelectedOption === 1 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -4673,13 +5295,13 @@ async function launchBrowser(theme_override) {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const laterText = new TextRenderable4(renderer, {
+  const laterText = new TextRenderable5(renderer, {
     content: "  Later",
     fg: updateSelectedOption === 1 ? colors.yellow : colors.text,
     bg: colors.surfaceDim
   });
   laterBox.add(laterText);
-  const neverBox = new BoxRenderable4(renderer, {
+  const neverBox = new BoxRenderable5(renderer, {
     border: true,
     borderColor: updateSelectedOption === 2 ? colors.yellow : colors.border,
     backgroundColor: colors.surfaceDim,
@@ -4688,7 +5310,7 @@ async function launchBrowser(theme_override) {
     paddingLeft: 1,
     paddingRight: 1
   });
-  const neverText = new TextRenderable4(renderer, {
+  const neverText = new TextRenderable5(renderer, {
     content: "  Don't show again",
     fg: updateSelectedOption === 2 ? colors.yellow : colors.text,
     bg: colors.surfaceDim
@@ -4705,7 +5327,7 @@ async function launchBrowser(theme_override) {
   }
   updateOptionsRow.add(updateNowBox);
   updateOptionsRow.add(laterBox);
-  const updateFooter = new TextRenderable4(renderer, {
+  const updateFooter = new TextRenderable5(renderer, {
     content: "  \u2191\u2193/jk/PgUp/PgDn scroll  \u2190\u2192 select  Enter  Esc/q close",
     fg: colors.muted,
     bg: colors.surfaceDim,
@@ -4713,7 +5335,8 @@ async function launchBrowser(theme_override) {
     paddingX: 1
   });
   updateBox.add(updateScroll);
-  updateScroll.add(updateText);
+  updateScroll.add(updateHeader);
+  updateScroll.add(updateNotes.renderable);
   updateBox.add(updateOptionsRow);
   updateBox.add(updateFooter);
   root.add(updateDim);
@@ -5061,15 +5684,12 @@ async function launchBrowser(theme_override) {
     if (!state.lastInstalledVersion) return;
     if (state.lastInstalledVersion === currentVersion) return;
     const notes = fetchReleaseNotes(currentVersion);
-    const notesWidth = Math.max(
-      30,
-      Math.floor((process.stdout.columns || 80) * 0.55) - 8
-    );
-    const notesBlock = notes ? renderMarkdown(notes, { width: notesWidth }) : "  No release notes found for this version.";
     updateSelectedOption = 0;
-    updateText.content = `  Updated ghfind ${state.lastInstalledVersion} \u2192 ${currentVersion}
-
-${notesBlock}`;
+    updateHeader.content = `  Updated ghfind ${state.lastInstalledVersion} \u2192 ${currentVersion}
+`;
+    updateNotes.setContent(
+      notes ?? "_No release notes found for this version._"
+    );
     renderUpdateOptions();
     showOverlay("update");
   }
@@ -5084,22 +5704,12 @@ ${notesBlock}`;
     if (latest) {
       updateSelectedOption = 0;
       const notes = fetchReleaseNotes(latest);
-      const notesWidth = Math.max(
-        30,
-        Math.floor((process.stdout.columns || 80) * 0.55) - 8
-      );
-      const notesBlock = notes ? renderMarkdown(notes, { width: notesWidth }) : `  A new version is available
-
-  Current: ${currentVersion}
-  Latest:   ${latest}
-
-  Run "npm install -g ghfind"`;
-      updateText.content = `  A new version is available
+      updateHeader.content = `  A new version is available
 
   Current: ${currentVersion}
   Latest:   ${latest}
-
-${notesBlock}`;
+`;
+      updateNotes.setContent(notes ?? "Run `npm install -g ghfind` to update.");
       renderUpdateOptions();
       showOverlay("update");
     } else {
@@ -5182,7 +5792,7 @@ ${notesBlock}`;
       renderer.requestRender();
     }
   }
-  const orgBox = new BoxRenderable4(renderer, {
+  const orgBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.surface,
@@ -5205,14 +5815,14 @@ ${notesBlock}`;
       }
     }
   });
-  const orgText = new TextRenderable4(renderer, {
+  const orgText = new TextRenderable5(renderer, {
     content: "",
     fg: colors.text,
     bg: colors.bg
   });
   orgScroll.add(orgText);
   orgBox.add(orgScroll);
-  const orgFooter = new TextRenderable4(renderer, {
+  const orgFooter = new TextRenderable5(renderer, {
     content: "  \u2191\u2193/jk scroll  Esc/q close",
     fg: colors.muted,
     bg: colors.bg,
@@ -5278,7 +5888,7 @@ ${notesBlock}`;
     }
     renderer.requestRender();
   }
-  const readmeBox = new BoxRenderable4(renderer, {
+  const readmeBox = new BoxRenderable5(renderer, {
     visible: false,
     flexGrow: 1,
     backgroundColor: colors.surface,
@@ -5301,15 +5911,17 @@ ${notesBlock}`;
       }
     }
   });
-  const readmeText = new TextRenderable4(renderer, {
-    content: "",
-    fg: colors.text,
-    bg: colors.bg
+  const readmeView = createMarkdownView({
+    renderer,
+    colors,
+    loadImage: (url) => fetchImageBytes(url, { token: githubToken }),
+    getImageWidth: () => Math.max(24, (process.stdout.columns || 80) - 12)
   });
-  readmeScroll.add(readmeText);
+  readmeScroll.add(readmeView.renderable);
   readmeBox.add(readmeScroll);
-  const readmeFooter = new TextRenderable4(renderer, {
-    content: "  \u2191\u2193/jk scroll  Esc/q close",
+  const readmeFooterText = () => `  \u2191\u2193/jk scroll  PgUp/PgDn page  i images: ${readmeView.imagesEnabled ? "on" : "off"}  Esc/q close`;
+  const readmeFooter = new TextRenderable5(renderer, {
+    content: readmeFooterText(),
     fg: colors.muted,
     bg: colors.bg,
     height: 1,
@@ -5324,37 +5936,25 @@ ${notesBlock}`;
       setStatus("No repo selected");
       return;
     }
-    readmeText.content = `  Loading README for ${repo.fullName}...`;
+    readmeView.setContent(`Loading README for ${repo.fullName}\u2026`);
+    readmeFooter.content = readmeFooterText();
+    readmeScroll.scrollTop = 0;
     showOverlay("readme");
     try {
-      const headers = { "User-Agent": "ghfind/1.0" };
-      if (githubToken) headers.Authorization = `Bearer ${githubToken}`;
-      let text = "";
-      for (const path of [
-        `${repo.owner}/${repo.name}/main/README.md`,
-        `${repo.owner}/${repo.name}/master/README.md`,
-        `${repo.owner}/${repo.name}/main/README.rst`
-      ]) {
-        const r = await fetch(`https://raw.githubusercontent.com/${path}`, {
-          headers
-        });
-        if (r.ok) {
-          text = await r.text();
-          break;
-        }
-      }
-      if (!text) {
-        readmeText.content = `  (no README found for ${repo.fullName})`;
+      const readme = await fetchReadme(repo.owner, repo.name, {
+        token: githubToken
+      });
+      if (readme) {
+        readmeView.setContent(readme.text, readme.sourceUrl);
       } else {
-        const termW = Math.max(40, (process.stdout.columns || 80) - 4);
-        readmeText.content = renderMarkdown(text, { width: termW });
+        readmeView.setContent(`_(no README found for ${repo.fullName})_`);
       }
     } catch {
-      readmeText.content = "  Failed to load README";
+      readmeView.setContent("_Failed to load README._");
     }
     renderer.requestRender();
   }
-  const statusBar = new TextRenderable4(renderer, {
+  const statusBar = new TextRenderable5(renderer, {
     content: " Ready. Press Enter to search.",
     fg: colors.muted,
     height: 1,
@@ -5835,6 +6435,17 @@ ${notesBlock}`;
       doSearch(searchInput.value);
     }
   });
+  searchInput.on("input", () => {
+    const v = searchInput.value;
+    if (v.length > 0) {
+      const t3 = v.trim();
+      if (t3.startsWith("{") && t3.endsWith("}") || t3.startsWith("[") && t3.endsWith("]")) {
+        searchInput.value = "";
+        setStatus("Ignored JSON paste \u2014 search queries accept plain text");
+        renderer.requestRender();
+      }
+    }
+  });
   resultsSelect.on("selectionChanged", () => {
     const opt = resultsSelect.getSelectedOption();
     if (currentMode === "packages") {
@@ -5917,6 +6528,14 @@ ${pack.description ?? ""}`;
         return;
       }
       if (currentOverlay === "readme") {
+        if (key.name === "i") {
+          readmeView.setImagesEnabled(!readmeView.imagesEnabled);
+          readmeFooter.content = readmeFooterText();
+          setStatus(
+            readmeView.imagesEnabled ? "README images on" : "README images off"
+          );
+          renderer.requestRender();
+        }
         return;
       }
       if (currentOverlay === "history") {
@@ -6350,6 +6969,12 @@ reported in text output and via the error message.
     ghfind deep-dive owner/repo --json
 Text output (no flag) prints the same sections formatted for the terminal.
 
+## Finding skills
+    ghfind skill search QUERY            # skills installed on this machine
+    ghfind skill search QUERY --remote   # the public skills.sh ecosystem
+Results carry path+description (local) or install command (registry, read-only --
+nothing is installed). The MCP server exposes the same search as
+ghfind_skill_search.
 ## Rate limits
 
 60 req/hr unauthenticated, 5,000 with GITHUB_TOKEN (env var or \`ghfind login\`).
@@ -6361,6 +6986,14 @@ Bookmarks live in ghfind's local state, not GitHub. An agent can read the
 release feed with:
     ghfind --releases --json
 Marking releases seen and editing bookmarks is a TUI action; skip it.
+## Local state (read-only)
+    ghfind bookmarks [QUERY] --json    # saved repos, newest first
+    ghfind history [QUERY] --json      # past searches
+    ghfind saved --json                # named searches
+    ghfind topics --json               # popular GitHub topics
+    ghfind readme owner/repo           # print a repo README
+    ghfind share owner/repo --as gh-cli|markdown|plain|short
+These never write local state; skip them when nothing needs reading.
 
 ## Token efficiency
 
@@ -6400,6 +7033,233 @@ function formatSkillCatalog() {
   ].join("\n");
 }
 
+// src/skill-finder.ts
+import { readdirSync, readFileSync as readFileSync6 } from "fs";
+import { homedir as homedir3 } from "os";
+import { delimiter, join as join6 } from "path";
+var REGISTRY_SEARCH_ENDPOINT = "https://skills.sh/api/search";
+var MIN_QUERY_LENGTH = 2;
+var MAX_SKILL_RESULTS = 100;
+function displayPath(path) {
+  const home = homedir3();
+  const normalized = path.replace(/\\/g, "/");
+  const homeNorm = home.replace(/\\/g, "/").replace(/\/$/, "");
+  if (normalized === homeNorm) return "~";
+  if (normalized.startsWith(`${homeNorm}/`)) {
+    return `~${normalized.slice(homeNorm.length)}`;
+  }
+  return normalized;
+}
+function defaultSkillRoots(cwd = process.cwd()) {
+  const home = homedir3();
+  return [
+    join6(home, ".codex", "skills"),
+    join6(home, ".agents", "skills"),
+    join6(cwd, ".codex", "skills"),
+    join6(cwd, ".github", "skills")
+  ];
+}
+function resolveSkillRoots(cwd = process.cwd()) {
+  const override = process.env.GHFIND_SKILL_ROOTS;
+  const paths = override?.trim() ? override.split(delimiter).filter((p) => p.trim()).map((p) => p.trim()) : defaultSkillRoots(cwd);
+  return paths.map((path) => ({ path, label: displayPath(path) }));
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+var MAX_DEPTH = 4;
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!match) return null;
+  const lines = match[1].split(/\r?\n/);
+  const fields = {};
+  for (let i = 0; i < lines.length; i++) {
+    const field = /^([A-Za-z_][\w-]*):[ \t]*(.*)$/.exec(lines[i]);
+    if (!field) continue;
+    const key = field[1].toLowerCase();
+    const inline = field[2].trim();
+    if (inline === ">" || inline === "|" || /^[>|][-+]?$/.test(inline)) {
+      const literal = inline.startsWith("|");
+      const parts = [];
+      while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      fields[key] = literal ? parts.join("\n") : parts.join(" ");
+    } else {
+      fields[key] = unquote(inline);
+    }
+  }
+  const name = fields.name ?? "";
+  if (!name) return null;
+  return { name, description: fields.description ?? "" };
+}
+function scanLocalSkills(roots = resolveSkillRoots()) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const root of roots) {
+    for (const dir of walkDirs(root.path)) {
+      const entries = listDir(dir);
+      if (!entries) continue;
+      if (!entries.some((e) => e.isFile() && e.name === "SKILL.md")) continue;
+      const file = join6(dir, "SKILL.md");
+      try {
+        const parsed = parseSkillFrontmatter(readFileSync6(file, "utf-8"));
+        if (!parsed || byName.has(parsed.name)) continue;
+        byName.set(parsed.name, {
+          name: parsed.name,
+          description: parsed.description.replace(/\s+/g, " ").trim(),
+          path: file,
+          origin: root.label
+        });
+      } catch {
+      }
+    }
+  }
+  return [...byName.values()];
+}
+function listDir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+}
+function* walkDirs(root) {
+  const queue = [[root, 0]];
+  while (queue.length > 0) {
+    const [dir, depth] = queue.shift();
+    const entries = listDir(dir);
+    if (!entries) continue;
+    yield dir;
+    if (depth >= MAX_DEPTH) continue;
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
+      queue.push([join6(dir, entry.name), depth + 1]);
+    }
+  }
+}
+function localMatchTier(hit, needle) {
+  const name = hit.name.toLowerCase();
+  if (name === needle) return 0;
+  if (name.startsWith(needle)) return 1;
+  if (name.includes(needle)) return 2;
+  if (hit.description.toLowerCase().includes(needle)) return 3;
+  return null;
+}
+function rankLocalSkills(hits, query, limit = MAX_SKILL_RESULTS) {
+  const needle = query.trim().toLowerCase();
+  return hits.map((hit) => ({ hit, tier: localMatchTier(hit, needle) })).filter(
+    (entry) => entry.tier !== null
+  ).sort((a, b) => a.tier - b.tier || a.hit.name.localeCompare(b.hit.name)).slice(0, clampLimit(limit)).map((entry) => entry.hit);
+}
+function clampLimit(limit) {
+  const n = Math.trunc(Number(limit));
+  if (!Number.isFinite(n)) return MAX_SKILL_RESULTS;
+  return Math.min(Math.max(n, 1), MAX_SKILL_RESULTS);
+}
+function assertSearchableQuery(query) {
+  const trimmed = query.trim();
+  if (trimmed.length < MIN_QUERY_LENGTH) {
+    throw new Error(
+      `Query must be at least ${MIN_QUERY_LENGTH} characters (got "${trimmed}").`
+    );
+  }
+  return trimmed;
+}
+function searchLocalSkills(query, opts = {}) {
+  const trimmed = assertSearchableQuery(query);
+  const skills = rankLocalSkills(
+    scanLocalSkills(opts.roots ?? resolveSkillRoots()),
+    trimmed,
+    opts.limit ?? MAX_SKILL_RESULTS
+  );
+  return { query: trimmed, source: "local", count: skills.length, skills };
+}
+function normalizeRegistrySkill(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw;
+  const source = typeof obj.source === "string" ? obj.source : "";
+  const skillId = typeof obj.skillId === "string" ? obj.skillId : "";
+  if (!source || !skillId) return null;
+  const name = typeof obj.name === "string" && obj.name.trim() ? obj.name : skillId;
+  const installs = typeof obj.installs === "number" ? obj.installs : 0;
+  const id = typeof obj.id === "string" && obj.id ? obj.id : `${source}/${skillId}`;
+  return {
+    id,
+    source,
+    skillId,
+    name,
+    installs,
+    installCommand: `npx skills add ${source}@${skillId}`,
+    url: `https://skills.sh/${source}/${skillId}`
+  };
+}
+async function searchRegistrySkills(query, opts = {}) {
+  const trimmed = assertSearchableQuery(query);
+  const limit = clampLimit(opts.limit ?? MAX_SKILL_RESULTS);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${REGISTRY_SEARCH_ENDPOINT}?q=${encodeURIComponent(trimmed)}&limit=${limit}`;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Accept: "application/json", "User-Agent": "ghfind/1.0" }
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach skills.sh: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(
+      `skills.sh returned HTTP ${res.status} for "${trimmed}". Retry, or search locally with --local.`
+    );
+  }
+  let payload;
+  try {
+    payload = await res.json();
+  } catch {
+    throw new Error("skills.sh returned a response that was not JSON.");
+  }
+  const items = payload?.skills ?? [];
+  const skills = items.map(normalizeRegistrySkill).filter((s) => s !== null).slice(0, limit);
+  return { query: trimmed, source: "registry", count: skills.length, skills };
+}
+async function searchSkills(query, opts = {}) {
+  if ((opts.source ?? "local") === "registry") {
+    return searchRegistrySkills(query, opts);
+  }
+  return searchLocalSkills(query, opts);
+}
+function formatSkillSearchJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+function shortDescription(description, width = 100) {
+  if (description.length <= width) return description;
+  return `${description.slice(0, width - 1).trimEnd()}\u2026`;
+}
+function formatSkillSearchText(result) {
+  if (result.count === 0) {
+    return result.source === "local" ? `No installed skills match "${result.query}". Try --remote to search the skills.sh ecosystem.` : `No skills.sh entries match "${result.query}".`;
+  }
+  if (result.source === "local") {
+    return result.skills.map(
+      (s) => `${s.name}  (${s.origin})
+  ${shortDescription(s.description)}`
+    ).join("\n");
+  }
+  return result.skills.map(
+    (s) => `${s.name}  ${s.installs.toLocaleString()} installs  [${s.source}]
+  ${s.installCommand}`
+  ).join("\n");
+}
+function formatSkillSearchNames(result) {
+  return result.skills.map((s) => s.name).join("\n");
+}
+
 // src/mcp-server.ts
 var SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
@@ -6462,6 +7322,7 @@ function asMcpToolError(err) {
 }
 var TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
 var REPO_SORTS = ["best-match", "stars", "updated", "forks"];
+var SKILL_SOURCES = ["local", "registry"];
 var TRENDING_SINCE = ["daily", "weekly", "monthly"];
 var PKG_SORTS = ["best-match", "score", "downloads", "name"];
 var TOOLS = [
@@ -6806,6 +7667,52 @@ Not found: ${missing.join(", ")}` : "");
         data: { name: "ghfind-cli" }
       };
     }
+  },
+  {
+    name: "ghfind_skill_search",
+    title: "Search agent skills",
+    description: "Search installed agent skills (SKILL.md files under the user's skill directories) or the public skills.sh ecosystem by keyword, and return matching skills with their descriptions. Read-only: it never installs anything - registry hits include the `npx skills add` command for the user to run deliberately. Use when the user asks to find a skill for a task, or asks what skills are available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Keyword to match against skill names and descriptions, e.g. "changelog" or "testing" (2+ characters).'
+        },
+        source: {
+          type: "string",
+          description: "Where to search: 'local' for skills installed on this machine (default), 'registry' for the public skills.sh ecosystem.",
+          enum: [...SKILL_SOURCES]
+        },
+        limit: {
+          type: "number",
+          description: "Max results, 1-100 (default 20).",
+          minimum: 1,
+          maximum: 100
+        }
+      },
+      required: ["query"]
+    },
+    async run(args) {
+      const source = coerceEnum(
+        args.source,
+        SKILL_SOURCES,
+        "local"
+      );
+      const limit = coerceInt(args.limit, 20, 1, 100);
+      const result = await searchSkills(
+        String(args.query ?? ""),
+        { source, limit }
+      );
+      const where = result.source === "local" ? "installed skills on this machine" : "the public skills.sh ecosystem";
+      const header = `${result.count} match(es) for "${result.query}" in ${where}:`;
+      return {
+        text: `${header}
+
+${formatSkillSearchText(result)}`,
+        data: { ...result }
+      };
+    }
   }
 ];
 function toolSummaries() {
@@ -6884,7 +7791,7 @@ async function processServerLine(line, state, config) {
             title: "ghfind \u2014 GitHub search for agents",
             version: getVersion()
           },
-          instructions: "ghfind gives agents GitHub search: repositories, trending, npm packages, org/user profiles, repo comparison and deep-dives. Call ghfind_skill for the full CLI guide. Unauthenticated requests are rate-limited to 60/hr; pass a token or set GITHUB_TOKEN for 5,000/hr."
+          instructions: "ghfind gives agents GitHub search: repositories, trending, npm packages, org/user profiles, repo comparison and deep-dives. ghfind_skill_search finds agent skills, either installed on this machine or in the public skills.sh ecosystem. Call ghfind_skill for the full CLI guide. Unauthenticated requests are rate-limited to 60/hr; pass a token or set GITHUB_TOKEN for 5,000/hr."
         })
       );
       return;
@@ -6988,7 +7895,7 @@ async function runMcpServer(options = {}) {
 // src/cli.ts
 process.env.GHFIND_CLI_RUN = "1";
 var __dirname3 = dirname4(fileURLToPath4(import.meta.url));
-var PKG_DIR3 = join6(__dirname3, "..");
+var PKG_DIR3 = join7(__dirname3, "..");
 function parseArgs(args) {
   const flags = {
     query: "",
@@ -7012,7 +7919,16 @@ function parseArgs(args) {
     registry: "npm",
     compare: [],
     doctor: false,
-    mcp: false
+    mcp: false,
+    bookmarks: false,
+    history: false,
+    topics: false,
+    saved: false,
+    remote: false,
+    local: false,
+    copy: false,
+    raw: false,
+    limitExplicit: false
   };
   const queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -7069,6 +7985,7 @@ function parseArgs(args) {
         break;
       case "--limit": {
         const parsed = parseInt(args[++i], 10);
+        flags.limitExplicit = true;
         if (Number.isNaN(parsed) || parsed < 1 || parsed > 100) {
           console.error(`Invalid limit: must be 1-100. Using default 50.`);
           flags.limit = 50;
@@ -7101,9 +8018,56 @@ function parseArgs(args) {
       case "--completion":
         flags.completion = args[++i];
         break;
+      case "--remote":
+        flags.remote = true;
+        break;
+      case "--local":
+        flags.local = true;
+        break;
+      case "--copy":
+        flags.copy = true;
+        break;
+      case "--raw":
+        flags.raw = true;
+        break;
+      case "--as":
+        flags.sharedAs = args[++i];
+        break;
       case "mcp":
         flags.mcp = true;
         break;
+      case "bookmarks":
+        flags.bookmarks = true;
+        break;
+      case "history":
+        flags.history = true;
+        break;
+      case "topics":
+        flags.topics = true;
+        break;
+      case "saved":
+        flags.saved = true;
+        break;
+      case "readme": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.readme = next;
+          i++;
+        } else {
+          flags.readme = "";
+        }
+        break;
+      }
+      case "share": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.share = next;
+          i++;
+        } else {
+          flags.share = "";
+        }
+        break;
+      }
       case "deep-dive": {
         const next = args[i + 1];
         if (next && !next.startsWith("-")) {
@@ -7114,6 +8078,17 @@ function parseArgs(args) {
       }
       case "skill": {
         const next = args[i + 1];
+        if (next === "search") {
+          i++;
+          const query = args[i + 1];
+          if (query && !query.startsWith("-")) {
+            flags.skillSearch = query;
+            i++;
+          } else {
+            flags.skillSearch = "";
+          }
+          break;
+        }
         if (next && !next.startsWith("-")) {
           flags.skill = next;
           i++;
@@ -7192,6 +8167,13 @@ Usage:
   ghfind pkg <query>               Search npm packages, text list
   ghfind mcp                       Run the MCP server for AI agents (stdio)
   ghfind skill [name]              Print the agent skill guide (or catalog)
+  ghfind bookmarks [query]         Saved repos, newest first
+  ghfind history [query]           Past searches, newest first
+  ghfind topics                    Browse popular GitHub topics
+  ghfind saved                     Named searches saved in the TUI
+  ghfind readme <owner/repo>       Print a repository README
+  ghfind share a/b --as gh-cli     Share snippet (--copy to clipboard)
+  ghfind skill search <query>      Find skills locally, or --remote
   ghfind --watch <query>           Watch mode (poll every Ns)
   ghfind init                      Run setup wizard
   ghfind login                     Import the gh CLI token or paste one
@@ -7216,14 +8198,19 @@ Options:
   --releases                           New-release feed for bookmarks
   --interval <s>                       Watch interval in seconds (default: 300)
   --completion <shell>                 Generate completions
+  --remote                             skill search: query skills.sh instead of this machine
+  --local                              skill search: force the local scan (default)
+  --as <fmt>                           share format: markdown|plain|gh-cli|short
+  --copy                               share: also copy the snippet to the clipboard
+  --raw                                readme: print the raw markdown with no header
 `);
     return;
   }
   if (flags.completion) {
     const shell = flags.completion;
     try {
-      const content = readFileSync6(
-        join6(PKG_DIR3, "completions", `ghfind.${shell}`),
+      const content = readFileSync7(
+        join7(PKG_DIR3, "completions", `ghfind.${shell}`),
         "utf-8"
       );
       console.log(content);
@@ -7245,10 +8232,38 @@ Options:
     await runMcpServer({ token: flags.token });
     return;
   }
+  if (flags.skillSearch !== void 0) {
+    await runSkillSearch(flags);
+    return;
+  }
   if (flags.skill !== void 0) {
     printAgentSkill(flags.skill);
     return;
   }
+  if (flags.bookmarks) {
+    runBookmarks(flags);
+    return;
+  }
+  if (flags.history) {
+    runHistory(flags);
+    return;
+  }
+  if (flags.saved) {
+    runSavedSearches(flags);
+    return;
+  }
+  if (flags.topics) {
+    await runTopics(flags);
+    return;
+  }
+  if (flags.readme !== void 0) {
+    await runReadme(flags);
+    return;
+  }
+  if (flags.share !== void 0) {
+    await runShare(flags);
+    return;
+  }
   if (flags.pkg) {
     const interactive = !flags.query && !flags.json && !flags.csv && !flags.markdown && !flags.count && !flags.format;
     if (interactive) {
@@ -7382,6 +8397,233 @@ async function runDeepDive(flags, outputFormat) {
     process.exit(1);
   }
 }
+async function runSkillSearch(flags) {
+  const query = flags.skillSearch ?? "";
+  if (!query.trim()) {
+    console.error(
+      "Usage: ghfind skill search <query> [--remote] [--limit <n>] [--json]"
+    );
+    process.exit(1);
+  }
+  if (flags.remote && flags.local) {
+    console.error(
+      "Contradictory flags: pass either --remote or --local, not both."
+    );
+    process.exit(1);
+  }
+  const source = flags.remote ? "registry" : "local";
+  try {
+    const result = await searchSkills(query, {
+      source,
+      limit: flags.limit
+    });
+    if (flags.json) {
+      console.log(formatSkillSearchJson(result));
+    } else if (flags.format === "names") {
+      console.log(formatSkillSearchNames(result));
+    } else {
+      console.log(formatSkillSearchText(result));
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+function runBookmarks(flags) {
+  const query = flags.query.trim();
+  const bookmarks = query ? searchBookmarks(query) : getBookmarks();
+  if (flags.json) {
+    console.log(JSON.stringify(bookmarks, null, 2));
+    return;
+  }
+  if (bookmarks.length === 0) {
+    console.log(
+      query ? `No bookmarks match "${query}".` : "No bookmarks yet. Press Space \u2192 Bookmark in the TUI to save one."
+    );
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["full_name", "stars", "language", "tags", "saved_at"];
+    const rows = bookmarks.map((b) => [
+      b.repo.fullName,
+      String(b.repo.stars),
+      b.repo.language ?? "",
+      b.tags.join(" "),
+      new Date(b.savedAt).toISOString().slice(0, 10)
+    ]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const b of bookmarks) {
+    const tags = b.tags.length > 0 ? `  [${b.tags.join(", ")}]` : "";
+    console.log(
+      `${b.repo.fullName}  \u2014 ${b.repo.stars.toLocaleString()}  ${b.repo.language ?? "n/a"}${tags}`
+    );
+  }
+}
+function runHistory(flags) {
+  const limit = flags.limitExplicit ? flags.limit : 20;
+  const query = flags.query.trim().toLowerCase();
+  const entries = readHistory().filter((e) => !query || e.query.toLowerCase().includes(query)).slice(0, limit);
+  if (flags.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  if (entries.length === 0) {
+    console.log(
+      query ? `No history matches "${query}".` : "No search history yet."
+    );
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["query", "mode", "results", "when"];
+    const rows = entries.map((e) => [
+      e.query,
+      e.mode,
+      String(e.resultCount),
+      new Date(e.timestamp).toISOString()
+    ]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const e of entries) {
+    const when = new Date(e.timestamp).toISOString().slice(0, 10);
+    console.log(
+      `${e.query}  \u2014 ${e.mode}  \u2014 ${e.resultCount} results  \u2014 ${when}`
+    );
+  }
+}
+function runSavedSearches(flags) {
+  const saved = getSavedSearches();
+  if (flags.json) {
+    console.log(JSON.stringify(saved, null, 2));
+    return;
+  }
+  if (saved.length === 0) {
+    console.log("No saved searches yet. Save one from the TUI command menu.");
+    return;
+  }
+  if (flags.csv || flags.markdown) {
+    const header = ["name", "query", "mode", "limit"];
+    const rows = saved.map((s) => [s.name, s.query, s.mode, String(s.limit)]);
+    console.log(
+      flags.csv ? rowsToCsv(header, rows) : rowsToMarkdown(header, rows)
+    );
+    return;
+  }
+  for (const s of saved) {
+    console.log(`${s.name}  \u2014 ${s.query}  \u2014 ${s.mode}  \u2014 limit ${s.limit}`);
+  }
+}
+function rowsToCsv(header, rows) {
+  const quote = (value) => /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+  return [header, ...rows].map((row) => row.map(quote).join(",")).join("\n");
+}
+function rowsToMarkdown(header, rows) {
+  return [
+    `| ${header.join(" | ")} |`,
+    `|${header.map(() => "---").join("|")}|`,
+    ...rows.map((row) => `| ${row.join(" | ")} |`)
+  ].join("\n");
+}
+function truncate2(text, width) {
+  if (text.length <= width) return text;
+  return `${text.slice(0, width - 1).trimEnd()}\u2026`;
+}
+function plainText(html) {
+  return html.replace(/<\/p>|<br\s*\/?>/gi, " ").replace(/<[^>]*>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+async function runTopics(flags) {
+  try {
+    const topics = (await fetchTopics()).slice(0, flags.limit);
+    if (flags.json) {
+      console.log(JSON.stringify(topics, null, 2));
+      return;
+    }
+    if (topics.length === 0) {
+      console.log("No topics returned.");
+      return;
+    }
+    for (const t3 of topics) {
+      const description = truncate2(plainText(t3.description), 140);
+      console.log(description ? `${t3.name}  ${description}` : t3.name);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function runReadme(flags) {
+  const ref = flags.readme ?? "";
+  if (!ref) {
+    console.error(
+      "Usage: ghfind readme <owner/repo> [--json] [--raw] [--token <t>]"
+    );
+    process.exit(1);
+  }
+  try {
+    const { owner, name } = repoFromRef(ref);
+    const readme = await fetchReadme(owner, name, { token: flags.token });
+    if (!readme) {
+      console.error(`No README found for ${owner}/${name}.`);
+      process.exit(1);
+    }
+    if (flags.json) {
+      console.log(
+        JSON.stringify(
+          { owner, name, sourceUrl: readme.sourceUrl, text: readme.text },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    if (!flags.raw) {
+      console.log(`# ${owner}/${name} README (${readme.sourceUrl})`);
+      console.log("");
+    }
+    console.log(readme.text);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function runShare(flags) {
+  const ref = flags.share ?? "";
+  if (!ref) {
+    console.error(
+      "Usage: ghfind share <owner/repo> [--as markdown|plain|gh-cli|short] [--copy]"
+    );
+    process.exit(1);
+  }
+  const SHARE_FORMATS = ["markdown", "plain", "gh-cli", "short"];
+  const as = flags.sharedAs ?? "markdown";
+  if (!SHARE_FORMATS.includes(as)) {
+    console.error(
+      `Invalid --as value: "${flags.sharedAs}" (use markdown|plain|gh-cli|short).`
+    );
+    process.exit(1);
+  }
+  try {
+    repoFromRef(ref);
+    const repo = await resolveRepoFromRef(ref, flags.token);
+    const text = formatShare(repo, as);
+    console.log(text);
+    if (flags.copy) {
+      const copied = await copyToClipboard(text);
+      console.error(
+        copied ? "Copied to clipboard." : "Could not copy to the clipboard on this platform."
+      );
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
 async function runPackageSearch(flags) {
   if (flags.registry !== "npm") {
     console.error(`Registry "${flags.registry}" not yet supported (only npm).`);