github-search-cli 9.7.1 → 9.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-search-cli",
-  "version": "9.7.1",
+  "version": "9.8.1",
   "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",
@@ -84,5 +84,10 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "main": "index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "author": ""
 }

package/release-notes/9.8.0.md

@@ -0,0 +1,55 @@
+# What's New in ghfind 9.8.0
+
+The README viewer learned to render markdown properly — and to show the
+pictures inside it. Same menu item, same keys, but the overlay now shows a
+repository the way its authors wrote it, images included.
+
+### Added
+
+**Full markdown rendering in the README viewer**
+
+- The viewer used to approximate markdown with box-drawing text: heading
+  markers became `█` prefixes, tables were hand-drawn, and everything else
+  was inline-decorated plain text. It now drives OpenTUI's markdown
+  renderable with a syntax style derived from your theme, so headings,
+  emphasis, links, lists, blockquotes, boxed tables, and fenced code blocks
+  render as markdown.
+- Headings pick up the accent colour (H1 underlined), inline code the theme's
+  green, links the accent with dimmed URLs — all of it follows `t` theme
+  switching, and everything re-reads the palette when a README is opened.
+- The document keeps its own block layout: paragraphs, lists, and code stay
+  scrollable in the same overlay (`↑`/`↓`, `j`/`k`, `PgUp`/`PgDn`).
+
+**Images now render in the terminal**
+
+- README images — markdown `![]()` and standalone `<img>` tags — are fetched
+  and drawn inline as truecolor half blocks. No image protocol support
+  required: it works on any truecolor terminal, inside the normal cell
+  buffer, so it scrolls and clips like every other line.
+- Paths resolve the way GitHub resolves them: `docs/shot.png` and
+  `/assets/banner.webp` both resolve against the branch the README came
+  from, and `github.com/owner/repo/blob/<ref>/<path>` links are rewritten to
+  raw content first.
+- Images are cached per URL (so toggling or re-opening a README doesn't
+  re-download), capped at 6 MB and 20 megapixels, and skipped entirely when
+  they can't be shown usefully: SVG is vector text, badges are tiny
+  machine-generated images, and neither survives rasterising. Skipped and
+  failed images leave an `🖼 alt text` caption, so a README never silently
+  loses a section.
+- Press `i` in the viewer to toggle images off and on; the footer shows the
+  current state. On a runtime without `Bun.Image` (plain Node), images
+  degrade to those captions instead of erroring.
+
+### Changed
+
+- **The update panel's release notes render as markdown too.** The in-app
+  update modal used the same text approximation as the README viewer; it now
+  shares the same markdown view, so release notes show real headings, lists,
+  inline code, and tables. Inline images stay off there — the panel is
+  narrow and notes are prose.
+- With the viewer and the update panel both migrated, the old plain-text
+  markdown renderer is gone; the markdown view is the only renderer left.
+- Test coverage grew with the feature: a PNG decoder (colour types, bit
+  depths, `tRNS`, every scanline filter), the image-to-cells rasteriser,
+  README image URL resolution and fetch behaviour, and the markdown token
+  helpers — 414 tests total, no new dependencies.

package/release-notes/9.8.1.md

@@ -0,0 +1,74 @@
+# What's New in ghfind 9.8.1
+
+Agent skills and read-only CLI views for scripts.
+
+This is a patch release. It also corrects the v9.8.0 release notes, which
+claimed README image rendering worked. It does not, and this release does not
+fix it — see the note at the end.
+
+### Added
+
+**`ghfind skill search <query>`**
+
+- Finds agent skills by keyword and prints why each one matched.
+- Scans `SKILL.md` files under `~/.codex/skills`, `~/.agents/skills`,
+  `<project>/.codex/skills` and `<project>/.github/skills`, in that
+  priority order, de-duplicated by name.
+- `--remote` queries the public [skills.sh](https://skills.sh) ecosystem
+  instead, returning each hit's install count and `npx skills add` command.
+- `GHFIND_SKILL_ROOTS` overrides which directories are scanned.
+
+**MCP tool `ghfind_skill_search`**
+
+- Agents can search skills as soon as they connect: `source: "local"` (the
+  default) searches installed skills, `source: "registry"` searches
+  skills.sh. Read-only — it returns install commands and never writes to disk.
+
+**Read-only CLI views of local state**
+
+- `ghfind bookmarks [query]`, `ghfind history [query]`, `ghfind saved`
+  and `ghfind topics`, each with `--json` for agents. They print what the
+  TUI has stored and never modify it.
+
+**`ghfind readme <owner/repo>` and `ghfind share <owner/repo>`**
+
+- `ghfind readme` prints a repository's README (`--raw` skips the header,
+  `--json` returns `{ owner, name, sourceUrl, text }`), bringing the TUI's
+  README viewer to scripts and agents.
+- `ghfind share` prints a share snippet (`--as markdown|plain|gh-cli|short`),
+  with `--copy` to also put it on the clipboard.
+
+**Shell completions**
+
+- bash, zsh and fish completions cover every new subcommand and flag.
+
+### Changed
+
+- The bundled `ghfind-cli` agent skill documents skill search and the new
+  read-only commands, so CLI-first agents discover them without reading
+  `--help`.
+
+### Fixed
+
+**README image rendering is not working — please read this before upgrading**
+
+The 9.8.0 README viewer added inline image support. On real repositories it
+does not work reliably, and this release does not fix it. Known failures, all
+verified against live READMEs:
+
+- **An image wrapped in a link renders nothing.** `[![alt](shot.png)](url)`
+  is a common way to write a linked screenshot. The whole block is treated as
+  prose and the image is dropped. This affects repositories such as
+  `sst/opencode`.
+- **A README with hundreds of small images is unusable.** `openclaw/openclaw`
+  has 661 `<img>` tags, 648 of them 48x48 sponsor avatars. Each becomes a
+  full screen of terminal cells, so the document is 15,552 rows tall.
+- **An image smaller than 100px is skipped**, judged by the `width`/`height`
+  its `<img>` tag declares. A README that understates an image's size hides
+  that image.
+- **SVG is not rendered.**
+
+Plain `![]()` images and large banners do render, correctly and quickly. The
+v9.8.0 notes described image rendering as working; that was wrong, and it is
+corrected here. Measurements, root causes and the remaining work are tracked
+in `.issues/tickets/readme-image-rendering.md`.

package/src/agent-skill.ts

@@ -77,6 +77,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\`).
@@ -88,6 +94,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
 

package/src/cli.ts

@@ -73,6 +73,20 @@ import {
 } from "./agent-skill";
 import type { SearchOptions } from "./types";
 import { SearchCliError } from "./errors";
+import { getBookmarks, searchBookmarks } from "./bookmarks";
+import { readHistory } from "./history";
+import { getSavedSearches } from "./saved-searches";
+import { fetchTopics } from "./explore";
+import { fetchReadme } from "./readme";
+import { copyToClipboard, formatShare, type ShareFormat } from "./share";
+import { repoFromRef } from "./deepdive";
+import {
+  formatSkillSearchJson,
+  formatSkillSearchNames,
+  formatSkillSearchText,
+  searchSkills,
+  type SkillSource,
+} from "./skill-finder";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_DIR = join(__dirname, "..");
@@ -109,6 +123,21 @@ interface CLIFlags {
   skill?: string; // agent skill guide (ghfind skill [name])
   deepDive?: string; // repo deep-dive (ghfind deep-dive <owner/repo>)
   language?: string; // trending language filter (--trending rust / ghfind trending rust)
+  // ?? Read-only local/skill surface (see README "Non-interactive") ??
+  bookmarks: boolean; // list bookmarks (ghfind bookmarks)
+  history: boolean; // list past searches (ghfind history)
+  topics: boolean; // browse popular GitHub topics (ghfind topics)
+  saved: boolean; // list saved searches (ghfind saved)
+  readme?: string; // print a repo README (ghfind readme <owner/repo>)
+  share?: string; // print a share snippet (ghfind share <owner/repo>)
+  skillSearch?: string; // skill search query (ghfind skill search <query>)
+  sharedAs?: string; // --as <format> for share
+  remote: boolean; // skill search: hit skills.sh instead of this machine
+  local: boolean; // skill search: force the local scan (the default)
+  copy: boolean; // share: also write the snippet to the clipboard
+  raw: boolean; // readme: print the raw markdown with no header
+  /** True when --limit was passed (history uses a smaller default than search). */
+  limitExplicit: boolean;
 }
 
 function parseArgs(args: string[]): CLIFlags {
@@ -135,6 +164,15 @@ function parseArgs(args: string[]): CLIFlags {
     compare: [],
     doctor: false,
     mcp: false,
+    bookmarks: false,
+    history: false,
+    topics: false,
+    saved: false,
+    remote: false,
+    local: false,
+    copy: false,
+    raw: false,
+    limitExplicit: false,
   };
 
   const queryParts: string[] = [];
@@ -199,6 +237,7 @@ function parseArgs(args: string[]): CLIFlags {
         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;
@@ -231,9 +270,58 @@ function parseArgs(args: string[]): CLIFlags {
       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": {
+        // Single repo ref; a following flag means none was given.
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.readme = next;
+          i++;
+        } else {
+          flags.readme = "";
+        }
+        break;
+      }
+      case "share": {
+        // Single repo ref; a following flag means none was given.
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.share = next;
+          i++;
+        } else {
+          flags.share = "";
+        }
+        break;
+      }
       case "deep-dive": {
         // Single repo ref (owner/name); a following flag means none.
         const next = args[i + 1];
@@ -244,8 +332,20 @@ function parseArgs(args: string[]): CLIFlags {
         break;
       }
       case "skill": {
-        // Optional skill id (ids contain no spaces); a following flag means none.
+        // `skill search <query>` searches the skill registry; plain `skill`
+        // lists the catalog and `skill <name>` prints one skill's guide.
         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++;
@@ -335,6 +435,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
@@ -359,6 +466,11 @@ 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;
   }
@@ -397,11 +509,43 @@ Options:
     return;
   }
 
+  // Skill search — find skills on this machine or in the skills.sh ecosystem
+  if (flags.skillSearch !== undefined) {
+    await runSkillSearch(flags);
+    return;
+  }
   // Agent skill guide — token-efficient usage doc for coding agents
   if (flags.skill !== undefined) {
     printAgentSkill(flags.skill);
     return;
   }
+  // Read-only local state: bookmarks / history / saved searches
+  if (flags.bookmarks) {
+    runBookmarks(flags);
+    return;
+  }
+  if (flags.history) {
+    runHistory(flags);
+    return;
+  }
+  if (flags.saved) {
+    runSavedSearches(flags);
+    return;
+  }
+  // Popular GitHub topics
+  if (flags.topics) {
+    await runTopics(flags);
+    return;
+  }
+  // README and share-snippet views (parity with the TUI `r` / `y` actions)
+  if (flags.readme !== undefined) {
+    await runReadme(flags);
+    return;
+  }
+  if (flags.share !== undefined) {
+    await runShare(flags);
+    return;
+  }
   // Package search (prototype, ticket 002-008)
   if (flags.pkg) {
     const interactive =
@@ -595,6 +739,274 @@ async function runDeepDive(
   }
 }
 
+/** `ghfind skill search <query>` — find skills locally, or in skills.sh with --remote. */
+async function runSkillSearch(flags: CLIFlags): Promise<void> {
+  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: SkillSource = 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);
+  }
+}
+
+/** `ghfind bookmarks [query]` — the saved repos, newest first. */
+function runBookmarks(flags: CLIFlags): void {
+  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 → 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}  — ${b.repo.stars.toLocaleString()}  ${b.repo.language ?? "n/a"}${tags}`,
+    );
+  }
+}
+
+/** `ghfind history [query]` — past searches, newest first. */
+function runHistory(flags: CLIFlags): void {
+  // History entries are short; 20 is plenty unless the caller says otherwise.
+  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}  — ${e.mode}  — ${e.resultCount} results  — ${when}`,
+    );
+  }
+}
+
+/** `ghfind saved` — named searches saved in the TUI. */
+function runSavedSearches(flags: CLIFlags): void {
+  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}  — ${s.query}  — ${s.mode}  — limit ${s.limit}`);
+  }
+}
+
+/** CSV for the small local-state tables (repos use output.ts's richer schema). */
+function rowsToCsv(header: string[], rows: string[][]): string {
+  const quote = (value: string) =>
+    /[",\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+  return [header, ...rows].map((row) => row.map(quote).join(",")).join("\n");
+}
+
+/** Markdown table for the same small local-state tables. */
+function rowsToMarkdown(header: string[], rows: string[][]): string {
+  return [
+    `| ${header.join(" | ")} |`,
+    `|${header.map(() => "---").join("|")}|`,
+    ...rows.map((row) => `| ${row.join(" | ")} |`),
+  ].join("\n");
+}
+
+/** Clip a string to `width` characters, ending on an ellipsis when cut. */
+function truncate(text: string, width: number): string {
+  if (text.length <= width) return text;
+  return `${text.slice(0, width - 1).trimEnd()}\u2026`;
+}
+
+/** GitHub topic blurbs are HTML; flatten them to one plain text line. */
+function plainText(html: string): string {
+  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();
+}
+
+/** `ghfind topics` — popular GitHub topics. */
+async function runTopics(flags: CLIFlags): Promise<void> {
+  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 t of topics) {
+      // Blurbs run to paragraphs; text output stays readable by clipping.
+      const description = truncate(plainText(t.description), 140);
+      console.log(description ? `${t.name}  ${description}` : t.name);
+    }
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+/** `ghfind readme <owner/repo>` — print a repository README. */
+async function runReadme(flags: CLIFlags): Promise<void> {
+  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); // validates the 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);
+  }
+}
+
+/** `ghfind share <owner/repo> [--as markdown|plain|gh-cli|short] [--copy]` */
+async function runShare(flags: CLIFlags): Promise<void> {
+  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: ShareFormat[] = ["markdown", "plain", "gh-cli", "short"];
+  const as = (flags.sharedAs ?? "markdown") as ShareFormat;
+  if (!SHARE_FORMATS.includes(as)) {
+    console.error(
+      `Invalid --as value: "${flags.sharedAs}" (use markdown|plain|gh-cli|short).`,
+    );
+    process.exit(1);
+  }
+  try {
+    repoFromRef(ref); // validate before the network round-trip
+    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);
+  }
+}
+
 /** `ghfind pkg "<query>"` — npm package search. Pass-through query to the registry. */
 async function runPackageSearch(flags: CLIFlags): Promise<void> {
   if (flags.registry !== "npm") {

package/src/help.ts

@@ -74,7 +74,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "Limit", action: "Cycle limit: 10 → 25 → 50 → 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" },
@@ -114,6 +114,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "d", action: "Delete entry (history, saved)" },
         { keys: "↑ ↓ / j k", action: "Navigate overlay list" },
         { keys: "← → / 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",