portawhip 0.1.0

package/core/registry/discover.mjs

@@ -0,0 +1,379 @@
+// Auto-discovers already-installed capabilities from live tool state, so
+// the registry links whatever is loaded — regardless of which host or tool
+// originally installed it — instead of only the entries someone remembered
+// to hand-type into recipe.yaml. This extends VISION.md's "cross-host/
+// cross-OS by detection, not by list" principle from host detection to
+// registry *content*.
+//
+// Delegates the actual detection to the same backends Step 1 already uses
+// (add-mcp, asm, mise) — this module owns zero install/config parsing logic.
+
+import spawnSync from "cross-spawn";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { readEnrichmentCache } from "./enrich.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, "..", "..");
+const DISCOVERY_MAX_BUFFER = 16 * 1024 * 1024;
+const SKILL_SCAN_MAX_DEPTH = 9;
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+const SURFACE_SKIP_DIRS = new Set(["docs"]);
+
+// Small, deliberately conservative stoplist: generic words that appear in
+// almost every skill description and would otherwise become high-frequency
+// noise triggers (the exact failure mode that made v1's hook misfire).
+const STOPWORDS = new Set([
+  "this", "that", "with", "from", "your", "have", "been", "using", "used",
+  "use", "when", "will", "into", "provides", "provide", "includes",
+  "include", "features", "feature", "across", "about", "these", "those",
+  "which", "where", "while", "then", "than", "also", "such", "only",
+  "some", "more", "most", "each", "every", "other", "make", "makes",
+  "making", "need", "needs", "needed", "help", "helps", "helping",
+  "user", "users", "their", "them", "they", "file", "files", "data",
+  "code", "tool", "tools", "agent", "agents", "claude", "system",
+  "essential", "developers", "developer", "building", "builds", "full",
+  "stack", "produces", "produce", "designed", "design", "applications",
+  "application",
+]);
+
+function extractKeywords(name, description, max = 6) {
+  const text = `${name} ${description || ""}`.toLowerCase();
+  const words = text.match(/[a-z][a-z-]{3,}/g) || [];
+  const nameLower = name.toLowerCase();
+  const freq = new Map();
+  for (const w of words) {
+    if (STOPWORDS.has(w) || w === nameLower) continue;
+    freq.set(w, (freq.get(w) || 0) + 1);
+  }
+  const ranked = [...freq.entries()].sort((a, b) => b[1] - a[1]).map(([w]) => w);
+  return [name, ...ranked.slice(0, max)];
+}
+
+function truncate(text, max = 160) {
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function parseSkillFrontmatter(text, fallbackName) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { name: fallbackName, description: "" };
+  const frontmatter = match[1];
+  const name = frontmatter.match(/^name:\s*(.+)$/m)?.[1]?.trim() ?? fallbackName;
+  const description =
+    frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
+  return { name, description };
+}
+
+function parseMarkdownFrontmatter(text, fallbackName) {
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const data = {};
+  if (match) {
+    for (const line of match[1].split(/\r?\n/)) {
+      const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+      if (!field) continue;
+      data[field[1]] = field[2].replace(/^["']|["']$/g, "").trim();
+    }
+  }
+  const heading = String(text ?? "").match(/^#\s+(.+)$/m)?.[1]?.trim();
+  return {
+    name: data.name || fallbackName,
+    description: data.description || heading || "",
+  };
+}
+
+function markdownFilesUnder(root, segmentName, maxDepth = SKILL_SCAN_MAX_DEPTH) {
+  const found = [];
+  if (!existsSync(root)) return found;
+  // When the root itself IS the segment dir (a host-native leaf like
+  // ~/.claude/commands), start already in-segment so its .md files are
+  // collected directly — without this, only the segment-walk case (a
+  // "commands"/"agents" dir nested in a plugin tree) is found, and the
+  // host-native user dirs are silently missed.
+  const startInSegment = root.split(/[\\/]/).pop() === segmentName;
+  const stack = [{ dir: root, depth: 0, inSegment: startInSegment }];
+  while (stack.length > 0) {
+    const { dir, depth, inSegment } = stack.pop();
+    let dirents;
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const dirent of dirents) {
+      const path = join(dir, dirent.name);
+      if (dirent.isFile() && inSegment && dirent.name.endsWith(".md")) {
+        found.push(path);
+        continue;
+      }
+      if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue;
+      if (SKIP_DIRS.has(dirent.name)) continue;
+      if (!inSegment && SURFACE_SKIP_DIRS.has(dirent.name)) continue;
+      if (depth >= maxDepth) continue;
+      stack.push({ dir: path, depth: depth + 1, inSegment: inSegment || dirent.name === segmentName });
+    }
+  }
+  return found;
+}
+
+function fileStem(path) {
+  return path.split(/[\\/]/).pop().replace(/\.md$/i, "");
+}
+
+function discoverMarkdownSurface(type, segmentName, roots = defaultPluginRoots()) {
+  const seen = new Map();
+  for (const root of roots) {
+    for (const path of markdownFilesUnder(root, segmentName)) {
+      try {
+        const fallback = fileStem(path);
+        const metadata = parseMarkdownFrontmatter(readFileSync(path, "utf8"), fallback);
+        const id = metadata.name || fallback;
+        if (seen.has(id)) continue;
+        const description = truncate(metadata.description || `${type}: ${id}`);
+        const slash = type === "command" ? `/${fallback}` : fallback;
+        seen.set(id, {
+          id,
+          type,
+          source: path,
+          path,
+          origin: `auto:${type}`,
+          route: {
+            triggers: [id, slash, ...extractKeywords(id, description)],
+            description,
+            when: ["user_prompt"],
+            inject: "hint",
+          },
+        });
+      } catch {
+        // A malformed markdown file should not block the whole surface scan.
+      }
+    }
+  }
+  return [...seen.values()];
+}
+
+export function defaultSkillRoots() {
+  return [
+    join(homedir(), ".codex", "skills"),
+    join(homedir(), ".agents", "skills"),
+    join(homedir(), ".claude", "skills"),
+    join(homedir(), ".claude", "plugins", "cache"),
+    join(homedir(), ".claude", "plugins", "marketplaces"),
+  ];
+}
+
+export function defaultPluginRoots() {
+  return [
+    join(homedir(), ".claude", "plugins", "cache"),
+    join(homedir(), ".claude", "plugins", "marketplaces"),
+  ];
+}
+
+// Host-native command/agent dirs (leaf dirs whose basename IS the segment, so
+// markdownFilesUnder collects them directly), on top of the plugin roots.
+// Data catalog, not decision logic — each path is a documented host
+// convention (Claude Code: ~/.claude/{commands,agents} + project .claude/…).
+// Codex prompts (~/.codex/prompts) use a different segment name and are added
+// once a codex install is present to verify against. cwd-relative project
+// dirs are resolved by the caller's process cwd, matching the router's
+// per-project behavior.
+export function defaultCommandRoots() {
+  return [
+    ...defaultPluginRoots(),
+    join(homedir(), ".claude", "commands"),
+    resolve(".claude", "commands"),
+  ];
+}
+
+export function defaultAgentRoots() {
+  return [
+    ...defaultPluginRoots(),
+    join(homedir(), ".claude", "agents"),
+    resolve(".claude", "agents"),
+  ];
+}
+
+function scanSkillDirs(root, maxDepth = SKILL_SCAN_MAX_DEPTH) {
+  const found = [];
+  if (!existsSync(root)) return found;
+  const stack = [{ dir: root, depth: 0 }];
+  while (stack.length > 0) {
+    const { dir, depth } = stack.pop();
+    const skillFile = join(dir, "SKILL.md");
+    if (existsSync(skillFile)) {
+      try {
+        if (!statSync(skillFile).isFile()) continue;
+        const frontmatter = parseSkillFrontmatter(readFileSync(skillFile, "utf8"), dir.split(/[\\/]/).pop());
+        found.push({
+          name: frontmatter.name,
+          description: frontmatter.description,
+          path: dir,
+        });
+      } catch {
+        // A broken symlink or unreadable skill should not break all discovery.
+      }
+      continue;
+    }
+    if (depth >= maxDepth) continue;
+    let dirents;
+    try {
+      dirents = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const dirent of dirents) {
+      if (!dirent.isDirectory() && !dirent.isSymbolicLink()) continue;
+      if (SKIP_DIRS.has(dirent.name)) continue;
+      stack.push({ dir: join(dir, dirent.name), depth: depth + 1 });
+    }
+  }
+  return found;
+}
+
+export function discoverSkillsFromDirs(roots = defaultSkillRoots()) {
+  const found = [];
+  for (const root of roots) {
+    found.push(...scanSkillDirs(root));
+  }
+  return found;
+}
+
+function runJsonCommand(candidates) {
+  let lastError = null;
+  for (const [command, args] of candidates) {
+    const result = spawnSync.sync(command, args, {
+      encoding: "utf8",
+      maxBuffer: DISCOVERY_MAX_BUFFER,
+    });
+    if (result.status === 0) return { ok: true, stdout: result.stdout };
+    lastError = result.error ?? new Error(result.stderr || `status ${result.status}`);
+  }
+  return { ok: false, error: lastError };
+}
+
+export async function discoverMcp(enrichCachePath) {
+  const { listInstalledServers } = await import("add-mcp");
+  const cache = enrichCachePath ? readEnrichmentCache(enrichCachePath) : {};
+  const hosts = await listInstalledServers({ global: true });
+  const seen = new Map();
+  for (const host of hosts) {
+    for (const server of host.servers ?? []) {
+      if (seen.has(server.serverName)) continue;
+      // `router-cli enrich` (core/enrich.mjs) precomputes real triggers by
+      // connecting to the server and asking its own tools/list — a bare
+      // server name alone only ever matches a prompt that names the server
+      // literally. Falls back to the bare name when nothing's cached yet
+      // (unenriched behavior, unchanged).
+      const enriched = cache[server.serverName];
+      seen.set(server.serverName, {
+        id: server.serverName,
+        type: "mcp",
+        source: server.identity,
+        path: null,
+        origin: "auto:mcp",
+        route: {
+          triggers: enriched?.triggers ?? [server.serverName],
+          description: enriched?.description ?? `MCP server: ${server.serverName}`,
+          when: ["user_prompt"],
+          inject: "hint",
+        },
+      });
+    }
+  }
+  return [...seen.values()];
+}
+
+export function discoverSkills() {
+  const localAsm = resolve(ROOT, "node_modules", "agent-skill-manager", "dist", "agent-skill-manager.js");
+  const candidates = existsSync(localAsm)
+    ? [[process.execPath, [localAsm, "list", "--json"]]]
+    : [];
+  candidates.push(["npx", ["--yes", "agent-skill-manager", "list", "--json"]]);
+
+  const result = runJsonCommand(candidates);
+  let skills = discoverSkillsFromDirs();
+  if (!result.ok) {
+    // Filesystem discovery above is the fallback source of truth.
+  } else {
+    try {
+      skills = [...JSON.parse(result.stdout), ...skills];
+    } catch {
+      // Keep filesystem discovery if ASM returns malformed JSON.
+    }
+  }
+  // The same skill is commonly installed under the same name in several
+  // hosts (e.g. Claude Code, Codex, Cursor all carry "pdf") — one real
+  // capability, so one entry; first-seen wins, same as discoverMcp.
+  const seen = new Map();
+  for (const s of skills) {
+    if (seen.has(s.name)) continue;
+    seen.set(s.name, {
+      id: s.name,
+      type: "skill",
+      source: s.path,
+      path: s.path ?? null,
+      origin: "auto:skill",
+      route: {
+        triggers: extractKeywords(s.name, s.description),
+        description: truncate(s.description),
+        when: ["user_prompt"],
+        inject: "hint",
+      },
+    });
+  }
+  return [...seen.values()];
+}
+
+export function discoverCli(enrichCachePath) {
+  const result = spawnSync.sync("mise", ["ls", "--json"], { encoding: "utf8" });
+  if (result.status !== 0) return [];
+  let tools;
+  try {
+    tools = JSON.parse(result.stdout);
+  } catch {
+    return [];
+  }
+  const cache = enrichCachePath ? readEnrichmentCache(enrichCachePath) : {};
+  return Object.keys(tools).map((name) => {
+    const enriched = cache[name];
+    return {
+      id: name,
+      type: "cli",
+      source: name,
+      path: null,
+      origin: "auto:cli",
+      route: {
+        triggers: enriched?.triggers ?? [name],
+        description: enriched?.description ?? `CLI tool: ${name}`,
+        when: ["user_prompt"],
+        inject: "hint",
+      },
+    };
+  });
+}
+
+export function discoverCommands(roots = defaultCommandRoots()) {
+  return discoverMarkdownSurface("command", "commands", roots);
+}
+
+export function discoverAgents(roots = defaultAgentRoots()) {
+  return discoverMarkdownSurface("agent", "agents", roots);
+}
+
+export async function discoverAll({ enrichCachePath } = {}) {
+  const [mcp, skills, cli, commands, agents] = await Promise.all([
+    discoverMcp(enrichCachePath),
+    Promise.resolve(discoverSkills()),
+    Promise.resolve(discoverCli(enrichCachePath)),
+    Promise.resolve(discoverCommands()),
+    Promise.resolve(discoverAgents()),
+  ]);
+  const byId = new Map();
+  for (const entry of [...mcp, ...skills, ...cli, ...commands, ...agents]) {
+    if (byId.has(entry.id)) continue;
+    byId.set(entry.id, entry);
+  }
+  return [...byId.values()];
+}

package/core/registry/enrich.mjs

@@ -0,0 +1,213 @@
+// Enriches bare-name auto-discovered MCP/CLI tools with real
+// triggers/descriptions. Runs at init/update time ONLY, via
+// `router-cli enrich` — never inside loadIndex()/discoverAll(), which
+// rebuild and re-discover on every single route() call. Connecting to
+// every installed MCP server (and shelling out to package registries for
+// CLI tools) on every prompt would make the router itself the bottleneck
+// it exists to avoid.
+//
+// Found live 2026-07-06: add-mcp/mise only ever return a bare server/tool
+// NAME with no description, so discover.mjs's auto:mcp/auto:cli entries end
+// up with `triggers:[name]` — they only ever fire when a prompt names the
+// tool literally ("use playwright to..."), and stay dead on the natural
+// phrasing a real task actually uses ("open a browser and click login").
+//
+// Grounded-first ladder, LLM fallback deliberately NOT built yet (see
+// memory: dead-auto-tools-enrichment.md) — spiked and confirmed this covers
+// the large majority without one:
+//   MCP: add-mcp's own launch config -> @modelcontextprotocol/sdk listTools()
+//   CLI: `--help` first meaningful line -> `pip show` summary for pipx-
+//        installed tools only (a bare npm-view-by-name fallback was tried
+//        and dropped: no reliable name-to-package mapping without a
+//        registry/ecosystem hint mise doesn't expose, and it produced a
+//        real wrong-description collision - see enrichCli below) ->
+//        (LLM(name), future work, not built)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import spawnSync from "cross-spawn";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { enrichCliLadder } from "./cli-enrich.mjs";
+
+export const DEFAULT_CACHE_PATH = join(".hp-state", "tool-descriptions.json");
+const MAX_DESCRIPTION_CHARS = 300;
+const MAX_MCP_SUBTOOL_TRIGGERS = 20;
+
+export function readEnrichmentCache(cachePath = DEFAULT_CACHE_PATH) {
+  if (!existsSync(cachePath)) return {};
+  try {
+    return JSON.parse(readFileSync(cachePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeEnrichmentCache(entries, cachePath = DEFAULT_CACHE_PATH) {
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(entries, null, 2));
+}
+
+// --- MCP: connect via the launch config add-mcp already gave us, ask the
+// server itself what its tools do. Fails closed (returns null, leaving the
+// bare-name entry as-is) on anything unreachable/slow/misconfigured — this
+// is best-effort enrichment, never a requirement for the tool to route at
+// all (VISION.md: live-probe, never overclaim).
+
+async function enrichMcpServer(server, { timeoutMs = 8000 } = {}) {
+  const { serverName, config } = server;
+  if (!config) return null;
+  let client;
+  try {
+    const transport = config.url
+      ? new StreamableHTTPClientTransport(new URL(config.url))
+      : new StdioClientTransport({ command: config.command, args: config.args ?? [] });
+    client = new Client({ name: "portawhip-enrich", version: "0.1.0" }, { capabilities: {} });
+    await Promise.race([
+      client.connect(transport),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("enrich timeout")), timeoutMs)),
+    ]);
+    const { tools } = await client.listTools();
+    const names = tools.map((t) => t.name).filter(Boolean);
+    const descriptions = tools.map((t) => t.description).filter(Boolean);
+    const description = descriptions.length
+      ? `MCP server: ${serverName} — ${descriptions.slice(0, 3).join("; ")}`.slice(0, MAX_DESCRIPTION_CHARS)
+      : `MCP server: ${serverName}${names.length ? ` (tools: ${names.slice(0, 8).join(", ")})` : ""}`;
+    return {
+      triggers: [serverName, ...names].slice(0, MAX_MCP_SUBTOOL_TRIGGERS),
+      description,
+    };
+  } catch {
+    return null;
+  } finally {
+    if (client) {
+      try {
+        await client.close();
+      } catch {
+        // best-effort teardown only
+      }
+    }
+  }
+}
+
+export async function enrichMcp({ timeoutMs = 8000 } = {}) {
+  const { listInstalledServers } = await import("add-mcp");
+  const hosts = await listInstalledServers({ global: true });
+  const seen = new Map();
+  for (const host of hosts) {
+    for (const server of host.servers ?? []) {
+      if (!seen.has(server.serverName)) seen.set(server.serverName, server);
+    }
+  }
+  const results = {};
+  for (const server of seen.values()) {
+    const enriched = await enrichMcpServer(server, { timeoutMs });
+    if (enriched) {
+      results[server.serverName] = { type: "mcp", ...enriched, enrichedAt: new Date().toISOString() };
+    }
+  }
+  return results;
+}
+
+// --- CLI: `--help` gives a real one-line description for some tools
+// (jq/gitleaks/biome/hyperfine) but for many others the first line is just
+// usage syntax or a version/author banner (pandoc/node/ripgrep) — those
+// patterns are filtered out rather than accepted as a "description".
+
+const NOT_A_DESCRIPTION = [
+  /^usage[:\s]/i,
+  /^\[options?\]/i,
+  /^[\w.-]+\.exe\b/i,
+  /^[\w.-]+ v?\d+(\.\d+)+/i, // "ripgrep 15.1.0", "tool v2.3"
+  /^-[\w-]+[,\s]/, // a bare flag list line
+];
+
+// Exported for unit testing without shelling out — no other module needs it.
+export function firstMeaningfulLine(text) {
+  for (const raw of String(text ?? "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (NOT_A_DESCRIPTION.some((pattern) => pattern.test(line))) return null;
+    return line;
+  }
+  return null;
+}
+
+function runCapture(command, args, { timeout = 6000 } = {}) {
+  const result = spawnSync.sync(command, args, { encoding: "utf8", timeout });
+  if (result.error || (result.status !== 0 && result.status !== null)) return null;
+  return (result.stdout || result.stderr || "").toString();
+}
+
+// Exported for unit testing — no other module needs it.
+export function cliBinary(id) {
+  // "pipx:markitdown" -> "markitdown"; plain names pass through unchanged.
+  return id.includes(":") ? id.split(":").pop() : id;
+}
+
+// Same rule core/capability-docs.mjs's pointerFor() already established for
+// resolving a mise-installed CLI at all: a bare binary name only resolves
+// if the invoking shell happens to have `mise activate` wired in. Found
+// live here too — bare `biome --help` failed with ENOENT even though
+// `mise exec -- biome --help` works fine. `mise exec --` always works, on
+// every OS, with zero setup.
+function tryHelp(bin) {
+  const out = runCapture("mise", ["exec", "--", bin, "--help"]);
+  return out ? firstMeaningfulLine(out) : null;
+}
+
+function tryPipShow(bin) {
+  const out = runCapture("pip", ["show", bin]);
+  const match = out?.match(/^Summary:\s*(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+// No blind npm-view fallback: found live that "rust" (a mise-installed
+// language toolchain) collides with an unrelated npm package literally
+// named "rust" ("Install the rust toolchain using npm"), producing a
+// plausible-looking but WRONG description. `mise ls --json` exposes no
+// ecosystem/backend field to confirm a bare tool name is actually the npm
+// package of the same name, so there's no safe way to gate this — a wrong
+// description actively misleads future matches, which is worse than the
+// bare-name fallback. `pip show` stays safe because pipx installs are
+// always a 1:1 name-to-PyPI-package mapping, never a name collision.
+
+export function enrichCli(ids) {
+  const results = {};
+  for (const id of ids) {
+    const bin = cliBinary(id);
+    const description = tryHelp(bin) ?? (id.startsWith("pipx:") ? tryPipShow(bin) : null);
+    if (!description) continue;
+    results[id] = {
+      type: "cli",
+      triggers: [id, bin],
+      description: `CLI tool: ${bin} — ${description}`.slice(0, MAX_DESCRIPTION_CHARS),
+      enrichedAt: new Date().toISOString(),
+    };
+  }
+  return results;
+}
+
+function discoveredCliIds() {
+  const result = spawnSync.sync("mise", ["ls", "--json"], { encoding: "utf8" });
+  if (result.status !== 0) return [];
+  try {
+    return Object.keys(JSON.parse(result.stdout || "{}"));
+  } catch {
+    return [];
+  }
+}
+
+export async function runEnrichment({ cachePath = DEFAULT_CACHE_PATH, cliIds = null, timeoutMs = 8000, cliLadder = true } = {}) {
+  const existing = readEnrichmentCache(cachePath);
+  const mcp = await enrichMcp({ timeoutMs });
+  // CLI enrichment ladder (Phase S1b): mise-registry identity -> package
+  // registry JSON -> tldr -> --help/subcommands -> pip show. Falls back to the
+  // legacy --help/pip-only sync path if the ladder is explicitly disabled.
+  const ids = cliIds ?? discoveredCliIds();
+  const cli = cliLadder ? await enrichCliLadder(ids, { timeoutMs }) : enrichCli(ids);
+  const merged = { ...existing, ...mcp, ...cli };
+  writeEnrichmentCache(merged, cachePath);
+  return merged;
+}

package/core/registry/enrich.test.mjs

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { firstMeaningfulLine, cliBinary, readEnrichmentCache } from "./enrich.mjs";
+
+// enrichMcp/enrichCli/runEnrichment do real IO (spawn processes, connect to
+// MCP servers) and are deliberately NOT unit-tested here — same boundary
+// core/discover.mjs's own discoverMcp/discoverCli already draw (router.test.mjs
+// only covers the filesystem-scan discovery functions). Verified live instead
+// via `node core/router-cli.mjs enrich` against real installed tools.
+
+test("firstMeaningfulLine: accepts a real one-line description", () => {
+  assert.equal(
+    firstMeaningfulLine("Biome official CLI. Use it to check the health of your project."),
+    "Biome official CLI. Use it to check the health of your project.",
+  );
+});
+
+test("firstMeaningfulLine: rejects a Usage: line", () => {
+  assert.equal(firstMeaningfulLine("Usage: node [options] [script.js]"), null);
+});
+
+test("firstMeaningfulLine: rejects a bare version+author banner", () => {
+  assert.equal(firstMeaningfulLine("ripgrep 15.1.0 (rev af60c2de9d)\nAndrew Gallant"), null);
+});
+
+test("firstMeaningfulLine: rejects a .exe usage line", () => {
+  assert.equal(firstMeaningfulLine("pandoc.exe [OPTIONS] [FILES]"), null);
+});
+
+test("firstMeaningfulLine: skips blank lines to find the first real content", () => {
+  assert.equal(firstMeaningfulLine("\n\nA command-line benchmarking tool.\nUsage: ..."), "A command-line benchmarking tool.");
+});
+
+test("cliBinary: strips a pipx: backend prefix", () => {
+  assert.equal(cliBinary("pipx:markitdown"), "markitdown");
+});
+
+test("cliBinary: passes a plain name through unchanged", () => {
+  assert.equal(cliBinary("ripgrep"), "ripgrep");
+});
+
+test("readEnrichmentCache: missing file returns empty object, not an error", () => {
+  const dir = mkdtempSync(join(tmpdir(), "enrich-cache-test-"));
+  try {
+    const cache = readEnrichmentCache(join(dir, "does-not-exist.json"));
+    assert.deepEqual(cache, {});
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});