agentikit 0.0.3 → 0.0.7

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export type { AgentikitAssetType, AgentikitSearchType, SearchHit, SearchResponse
 export { agentikitIndex } from "./src/indexer";
 export type { IndexResponse } from "./src/indexer";
 export type { StashEntry, StashFile, StashIntent } from "./src/metadata";
+export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
+export type { EnsureRgResult } from "./src/ripgrep";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { plugin } from "./src/plugin";
 export { agentikitSearch, agentikitOpen, agentikitRun, agentikitInit } from "./src/stash";
 export { agentikitIndex } from "./src/indexer";
+export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";

package/dist/src/ripgrep.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolve the path to a usable ripgrep binary.
+ * Checks in order:
+ *   1. stashDir/bin/rg
+ *   2. system PATH (rg)
+ * Returns null if ripgrep is not available.
+ */
+export declare function resolveRg(stashDir?: string): string | null;
+/**
+ * Check if ripgrep is available (either in stash/bin or system PATH).
+ */
+export declare function isRgAvailable(stashDir?: string): boolean;
+export interface RgCandidateResult {
+    matchedFiles: string[];
+    usedRg: boolean;
+}
+/**
+ * Use ripgrep to find .stash.json files that match query tokens.
+ * Returns paths to matching .stash.json files.
+ *
+ * If ripgrep is not available or the query is empty, returns null
+ * to signal that the caller should skip pre-filtering.
+ */
+export declare function rgFilterCandidates(query: string, searchDir: string, stashDir?: string): RgCandidateResult | null;
+export interface EnsureRgResult {
+    rgPath: string;
+    installed: boolean;
+    version: string;
+}
+/**
+ * Ensure ripgrep is available. If not found on PATH or in stash/bin,
+ * download and install it to stash/bin.
+ *
+ * Returns the path to the ripgrep binary and whether it was newly installed.
+ */
+export declare function ensureRg(stashDir: string): EnsureRgResult;

package/dist/src/ripgrep.js

@@ -0,0 +1,262 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+// ── ripgrep Resolution ──────────────────────────────────────────────────────
+const IS_WINDOWS = process.platform === "win32";
+const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg";
+function canExecute(filePath) {
+    if (!fs.existsSync(filePath))
+        return false;
+    if (IS_WINDOWS)
+        return true;
+    try {
+        fs.accessSync(filePath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveFromPath() {
+    const rawPath = process.env.PATH;
+    if (!rawPath)
+        return null;
+    const pathEntries = rawPath.split(path.delimiter).filter(Boolean);
+    if (IS_WINDOWS) {
+        const pathext = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+            .split(";")
+            .filter(Boolean)
+            .map((ext) => ext.toLowerCase());
+        for (const entry of pathEntries) {
+            const directCandidate = path.join(entry, "rg");
+            if (canExecute(directCandidate))
+                return directCandidate;
+            for (const ext of pathext) {
+                const candidate = path.join(entry, `rg${ext}`);
+                if (canExecute(candidate))
+                    return candidate;
+            }
+        }
+        return null;
+    }
+    for (const entry of pathEntries) {
+        const candidate = path.join(entry, "rg");
+        if (canExecute(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Resolve the path to a usable ripgrep binary.
+ * Checks in order:
+ *   1. stashDir/bin/rg
+ *   2. system PATH (rg)
+ * Returns null if ripgrep is not available.
+ */
+export function resolveRg(stashDir) {
+    // Check stash bin directory first
+    if (stashDir) {
+        const stashRg = path.join(stashDir, "bin", RG_BINARY);
+        if (canExecute(stashRg))
+            return stashRg;
+    }
+    return resolveFromPath();
+}
+/**
+ * Check if ripgrep is available (either in stash/bin or system PATH).
+ */
+export function isRgAvailable(stashDir) {
+    return resolveRg(stashDir) !== null;
+}
+/**
+ * Use ripgrep to find .stash.json files that match query tokens.
+ * Returns paths to matching .stash.json files.
+ *
+ * If ripgrep is not available or the query is empty, returns null
+ * to signal that the caller should skip pre-filtering.
+ */
+export function rgFilterCandidates(query, searchDir, stashDir) {
+    if (!query.trim())
+        return null;
+    const rgPath = resolveRg(stashDir);
+    if (!rgPath)
+        return null;
+    // Tokenize the query into an OR pattern for ripgrep
+    const tokens = query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 1);
+    if (tokens.length === 0)
+        return null;
+    const pattern = tokens.join("|");
+    const result = spawnSync(rgPath, [
+        "-i", // case insensitive
+        "-l", // files-with-matches only
+        "--hidden", // include hidden files such as .stash.json
+        "--no-ignore", // include ignored files to ensure metadata is searchable
+        "--glob", ".stash.json", // only search .stash.json files
+        pattern,
+        searchDir,
+    ], {
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    if (result.status !== 0 && result.status !== 1) {
+        // rg exit code 1 = no matches (normal), anything else = error
+        return null;
+    }
+    const files = (result.stdout || "")
+        .trim()
+        .split(/\r?\n/)
+        .filter((f) => f.length > 0);
+    return { matchedFiles: files, usedRg: true };
+}
+// ── ripgrep Installation ────────────────────────────────────────────────────
+/**
+ * Platform and architecture detection for ripgrep binary downloads.
+ */
+function getRgPlatformTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === "linux" && arch === "x64") {
+        return { platform: "x86_64-unknown-linux-musl", arch: "x64", ext: ".tar.gz" };
+    }
+    if (platform === "linux" && arch === "arm64") {
+        return { platform: "aarch64-unknown-linux-gnu", arch: "arm64", ext: ".tar.gz" };
+    }
+    if (platform === "darwin" && arch === "x64") {
+        return { platform: "x86_64-apple-darwin", arch: "x64", ext: ".tar.gz" };
+    }
+    if (platform === "darwin" && arch === "arm64") {
+        return { platform: "aarch64-apple-darwin", arch: "arm64", ext: ".tar.gz" };
+    }
+    if (platform === "win32" && arch === "x64") {
+        return { platform: "x86_64-pc-windows-msvc", arch: "x64", ext: ".zip" };
+    }
+    return null;
+}
+const RG_VERSION = "14.1.1";
+/**
+ * Ensure ripgrep is available. If not found on PATH or in stash/bin,
+ * download and install it to stash/bin.
+ *
+ * Returns the path to the ripgrep binary and whether it was newly installed.
+ */
+export function ensureRg(stashDir) {
+    // Already available?
+    const existing = resolveRg(stashDir);
+    if (existing) {
+        return { rgPath: existing, installed: false, version: getRgVersion(existing) };
+    }
+    // Determine platform
+    const target = getRgPlatformTarget();
+    if (!target) {
+        throw new Error(`Unsupported platform for ripgrep auto-install: ${process.platform}/${process.arch}. ` +
+            `Install ripgrep manually: https://github.com/BurntSushi/ripgrep#installation`);
+    }
+    const binDir = path.join(stashDir, "bin");
+    if (!fs.existsSync(binDir)) {
+        fs.mkdirSync(binDir, { recursive: true });
+    }
+    const archiveName = `ripgrep-${RG_VERSION}-${target.platform}`;
+    const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${archiveName}${target.ext}`;
+    const destBinary = path.join(binDir, RG_BINARY);
+    if (target.ext === ".tar.gz") {
+        downloadAndExtractTarGz(url, archiveName, destBinary);
+    }
+    else {
+        downloadAndExtractZip(url, archiveName, destBinary);
+    }
+    // Make executable
+    if (!IS_WINDOWS) {
+        fs.chmodSync(destBinary, 0o755);
+    }
+    return { rgPath: destBinary, installed: true, version: RG_VERSION };
+}
+function downloadAndExtractTarGz(url, archiveName, destBinary) {
+    const destDir = path.dirname(destBinary);
+    const tmpTarGz = path.join(destDir, "rg-download.tar.gz");
+    try {
+        // Download archive to a temporary file without using a shell
+        const curlResult = spawnSync("curl", ["-fsSL", "-o", tmpTarGz, url], {
+            encoding: "utf8",
+            timeout: 60_000,
+        });
+        if (curlResult.status !== 0) {
+            const err = curlResult.stderr?.trim() || curlResult.error?.message || "unknown error";
+            throw new Error(`Failed to download ripgrep from ${url}: ${err}`);
+        }
+        // Extract the specific binary from the archive into destDir
+        const tarResult = spawnSync("tar", [
+            "xzf",
+            tmpTarGz,
+            "--strip-components=1",
+            "-C",
+            destDir,
+            `${archiveName}/rg`,
+        ], {
+            encoding: "utf8",
+            timeout: 60_000,
+        });
+        if (tarResult.status !== 0) {
+            const err = tarResult.stderr?.trim() || tarResult.error?.message || "unknown error";
+            throw new Error(`Failed to extract ripgrep from ${url}: ${err}`);
+        }
+        if (!fs.existsSync(destBinary)) {
+            throw new Error(`ripgrep binary not found at ${destBinary} after extraction`);
+        }
+    }
+    finally {
+        // Best-effort cleanup of temporary archive
+        try {
+            if (fs.existsSync(tmpTarGz)) {
+                fs.unlinkSync(tmpTarGz);
+            }
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+function downloadAndExtractZip(url, archiveName, destBinary) {
+    const destDir = path.dirname(destBinary);
+    const tmpZip = path.join(destDir, "rg-download.zip");
+    const expandedDir = path.join(destDir, archiveName);
+    try {
+        // Download
+        const dlResult = spawnSync("curl", ["-fsSL", "-o", tmpZip, url], {
+            encoding: "utf8",
+            timeout: 60_000,
+        });
+        if (dlResult.status !== 0) {
+            throw new Error(dlResult.stderr?.trim() || "download failed");
+        }
+        // Extract just the rg.exe
+        const extractResult = spawnSync("powershell", [
+            "-Command",
+            `Expand-Archive -Path "${tmpZip}" -DestinationPath "${destDir}" -Force; ` +
+                `Move-Item -Force "${path.join(destDir, archiveName, "rg.exe")}" "${destBinary}"`,
+        ], {
+            encoding: "utf8",
+            timeout: 60_000,
+        });
+        if (extractResult.status !== 0) {
+            throw new Error(extractResult.stderr?.trim() || "extraction failed");
+        }
+    }
+    finally {
+        if (fs.existsSync(tmpZip))
+            fs.unlinkSync(tmpZip);
+        if (fs.existsSync(expandedDir))
+            fs.rmSync(expandedDir, { recursive: true, force: true });
+    }
+}
+function getRgVersion(rgPath) {
+    const result = spawnSync(rgPath, ["--version"], { encoding: "utf8", timeout: 5_000 });
+    if (result.status === 0 && result.stdout) {
+        const match = result.stdout.match(/ripgrep\s+([\d.]+)/);
+        return match ? match[1] : "unknown";
+    }
+    return "unknown";
+}

package/dist/src/similarity.js

@@ -148,18 +148,33 @@ export class TfIdfAdapter {
     }
     substringFallback(query, limit, typeFilter) {
         const q = query.toLowerCase();
+        const tokens = tokenize(q);
         return this.documents
-            .filter((d) => {
+            .map((d) => {
             if (typeFilter && typeFilter !== "any" && d.entry.entry.type !== typeFilter)
-                return false;
-            return d.entry.text.includes(q) || d.entry.entry.name.toLowerCase().includes(q);
+                return null;
+            // Check if any query token matches the document text or name
+            const text = d.entry.text;
+            const name = d.entry.entry.name.toLowerCase();
+            let matchCount = 0;
+            for (const token of tokens) {
+                if (text.includes(token) || name.includes(token))
+                    matchCount++;
+            }
+            // Also check full substring match
+            if (text.includes(q) || name.includes(q))
+                matchCount = Math.max(matchCount, tokens.length);
+            if (matchCount === 0)
+                return null;
+            return {
+                entry: d.entry.entry,
+                path: d.entry.path,
+                score: Math.round((matchCount / Math.max(tokens.length, 1)) * 500) / 1000,
+            };
         })
-            .slice(0, limit)
-            .map((d) => ({
-            entry: d.entry.entry,
-            path: d.entry.path,
-            score: 0.5,
-        }));
+            .filter((d) => d !== null)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
     }
 }
 // ── Tokenization ────────────────────────────────────────────────────────────

package/dist/src/stash.d.ts

@@ -54,5 +54,10 @@ export interface InitResponse {
     created: boolean;
     envSet: boolean;
     profileUpdated?: string;
+    ripgrep?: {
+        rgPath: string;
+        installed: boolean;
+        version: string;
+    };
 }
 export declare function agentikitInit(): InitResponse;

package/dist/src/stash.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { loadSearchIndex, buildSearchText } from "./indexer";
 import { TfIdfAdapter } from "./similarity";
+import { rgFilterCandidates, ensureRg } from "./ripgrep";
 const IS_WINDOWS = process.platform === "win32";
 const TOOL_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
 const DEFAULT_LIMIT = 20;
@@ -57,28 +58,56 @@ function trySemanticSearch(query, searchType, limit, stashDir) {
         return null;
     if (index.stashDir !== stashDir)
         return null;
-    const scoredEntries = index.entries.map((ie) => ({
+    // Stage 1: ripgrep candidate filtering
+    // Use rg to pre-filter .stash.json files that contain query tokens,
+    // then only run TF-IDF ranking on those candidates.
+    let candidateEntries = index.entries;
+    if (query) {
+        const rgResult = rgFilterCandidates(query, stashDir, stashDir);
+        if (rgResult && rgResult.usedRg) {
+            const matchedDirs = new Set(rgResult.matchedFiles.map((f) => path.dirname(f)));
+            candidateEntries = index.entries.filter((ie) => matchedDirs.has(ie.dirPath));
+            // If rg found nothing but we have a query, still fall through to TF-IDF
+            // on all entries — rg is a fast pre-filter, not the final authority
+            if (candidateEntries.length === 0) {
+                candidateEntries = index.entries;
+            }
+        }
+    }
+    // Stage 2: TF-IDF semantic ranking
+    const scoredEntries = candidateEntries.map((ie) => ({
         id: `${ie.entry.type}:${ie.entry.name}`,
         text: buildSearchText(ie.entry),
         entry: ie.entry,
         path: ie.path,
     }));
     let adapter;
-    if (index.tfidf) {
-        adapter = TfIdfAdapter.deserialize(index.tfidf, scoredEntries);
+    if (index.tfidf && !query) {
+        // Use cached TF-IDF state for empty queries (listing all)
+        const allScored = index.entries.map((ie) => ({
+            id: `${ie.entry.type}:${ie.entry.name}`,
+            text: buildSearchText(ie.entry),
+            entry: ie.entry,
+            path: ie.path,
+        }));
+        adapter = TfIdfAdapter.deserialize(index.tfidf, allScored);
     }
     else {
+        // Rebuild adapter from candidate subset
         adapter = new TfIdfAdapter();
         adapter.buildIndex(scoredEntries);
     }
     const typeFilter = searchType === "any" ? undefined : searchType;
     const results = adapter.search(query, limit, typeFilter);
     return results.map((r) => {
+        // Derive the openRef name from the filesystem path, not the stash entry name,
+        // because agentikitOpen resolves assets by their relative path under the type root.
+        const openRefName = deriveOpenRefName(r.entry.type, r.path, stashDir);
         const hit = {
             type: r.entry.type,
             name: r.entry.name,
             path: r.path,
-            openRef: makeOpenRef(r.entry.type, r.entry.name),
+            openRef: makeOpenRef(r.entry.type, openRefName),
             description: r.entry.description,
             tags: r.entry.tags,
             score: r.score,
@@ -96,6 +125,21 @@ function trySemanticSearch(query, searchType, limit, stashDir) {
         return hit;
     });
 }
+/**
+ * Derive the correct openRef name for a semantic search result.
+ * Tools use their relative file path (e.g., "deploy/deploy-k8s.sh"),
+ * skills use directory name, commands/agents use relative .md path.
+ */
+function deriveOpenRefName(type, filePath, stashDir) {
+    const indexer = ASSET_INDEXERS[type];
+    const root = path.join(stashDir, indexer.dir);
+    if (type === "skill") {
+        // Skills resolve by directory name relative to skills/
+        const rel = toPosix(path.dirname(path.relative(root, filePath)));
+        return rel === "." ? path.basename(path.dirname(filePath)) : rel;
+    }
+    return toPosix(path.relative(root, filePath));
+}
 export function agentikitOpen(input) {
     const parsed = parseOpenRef(input.ref);
     const stashDir = resolveStashDir();
@@ -571,7 +615,16 @@ export function agentikitInit() {
         }
     }
     process.env.AGENTIKIT_STASH_DIR = stashDir;
-    return { stashDir, created, envSet, profileUpdated };
+    // Ensure ripgrep is available (install to stash/bin if needed)
+    let ripgrep;
+    try {
+        const rgResult = ensureRg(stashDir);
+        ripgrep = rgResult;
+    }
+    catch {
+        // Non-fatal: ripgrep is optional, search works without it
+    }
+    return { stashDir, created, envSet, profileUpdated, ripgrep };
 }
 function hasErrnoCode(error, code) {
     if (typeof error !== "object" || error === null || !("code" in error))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentikit",
-  "version": "0.0.3",
+  "version": "0.0.7",
   "type": "module",
   "description": "Search, open, and run extension assets from a stash directory. Works as both an OpenCode plugin and a Claude Code plugin.",
   "keywords": [

package/skills/stash/SKILL.md

@@ -28,7 +28,7 @@ Run this after adding new extensions to enable semantic search ranking.
 
 ### Search the stash
 
-Find assets by semantic similarity (if indexed) or name substring. Returns JSON with matching hits including `openRef` identifiers.
+Find assets using a two-stage search pipeline: ripgrep pre-filters `.stash.json` metadata files for fast candidate discovery, then TF-IDF ranks results by semantic relevance. Falls back to name substring matching when no index exists.
 
 ```bash
 agentikit search [query] [--type tool|skill|command|agent|any] [--limit N]
@@ -58,11 +58,16 @@ agentikit run <openRef>
 
 Returns the tool's stdout/stderr output and exit code.
 
+## Dependencies
+
+`agentikit init` will auto-install [ripgrep](https://github.com/BurntSushi/ripgrep) to `stash/bin/` if not already on PATH. Ripgrep is used for fast candidate filtering during search.
+
 ## Workflow
 
-1. Build the index: `agentikit index`
-2. Search for assets: `agentikit search "deploy" --type tool`
-3. Inspect a result: `agentikit open <openRef>`
-4. Run a tool: `agentikit run <openRef>`
+1. Initialize: `agentikit init` (creates stash dirs, installs ripgrep)
+2. Build the index: `agentikit index`
+3. Search for assets: `agentikit search "deploy" --type tool`
+4. Inspect a result: `agentikit open <openRef>`
+5. Run a tool: `agentikit run <openRef>`
 
 All output is JSON for easy parsing.

package/src/ripgrep.ts

@@ -0,0 +1,315 @@
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+
+// ── ripgrep Resolution ──────────────────────────────────────────────────────
+
+const IS_WINDOWS = process.platform === "win32"
+const RG_BINARY = IS_WINDOWS ? "rg.exe" : "rg"
+
+function canExecute(filePath: string): boolean {
+  if (!fs.existsSync(filePath)) return false
+  if (IS_WINDOWS) return true
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function resolveFromPath(): string | null {
+  const rawPath = process.env.PATH
+  if (!rawPath) return null
+
+  const pathEntries = rawPath.split(path.delimiter).filter(Boolean)
+
+  if (IS_WINDOWS) {
+    const pathext = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+      .split(";")
+      .filter(Boolean)
+      .map((ext) => ext.toLowerCase())
+
+    for (const entry of pathEntries) {
+      const directCandidate = path.join(entry, "rg")
+      if (canExecute(directCandidate)) return directCandidate
+
+      for (const ext of pathext) {
+        const candidate = path.join(entry, `rg${ext}`)
+        if (canExecute(candidate)) return candidate
+      }
+    }
+    return null
+  }
+
+  for (const entry of pathEntries) {
+    const candidate = path.join(entry, "rg")
+    if (canExecute(candidate)) return candidate
+  }
+
+  return null
+}
+
+/**
+ * Resolve the path to a usable ripgrep binary.
+ * Checks in order:
+ *   1. stashDir/bin/rg
+ *   2. system PATH (rg)
+ * Returns null if ripgrep is not available.
+ */
+export function resolveRg(stashDir?: string): string | null {
+  // Check stash bin directory first
+  if (stashDir) {
+    const stashRg = path.join(stashDir, "bin", RG_BINARY)
+    if (canExecute(stashRg)) return stashRg
+  }
+
+  return resolveFromPath()
+}
+
+/**
+ * Check if ripgrep is available (either in stash/bin or system PATH).
+ */
+export function isRgAvailable(stashDir?: string): boolean {
+  return resolveRg(stashDir) !== null
+}
+
+// ── ripgrep Candidate Filtering ─────────────────────────────────────────────
+
+export interface RgCandidateResult {
+  matchedFiles: string[]
+  usedRg: boolean
+}
+
+/**
+ * Use ripgrep to find .stash.json files that match query tokens.
+ * Returns paths to matching .stash.json files.
+ *
+ * If ripgrep is not available or the query is empty, returns null
+ * to signal that the caller should skip pre-filtering.
+ */
+export function rgFilterCandidates(
+  query: string,
+  searchDir: string,
+  stashDir?: string,
+): RgCandidateResult | null {
+  if (!query.trim()) return null
+
+  const rgPath = resolveRg(stashDir)
+  if (!rgPath) return null
+
+  // Tokenize the query into an OR pattern for ripgrep
+  const tokens = query
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 1)
+
+  if (tokens.length === 0) return null
+
+  const pattern = tokens.join("|")
+
+  const result = spawnSync(rgPath, [
+    "-i",                        // case insensitive
+    "-l",                        // files-with-matches only
+    "--hidden",                  // include hidden files such as .stash.json
+    "--no-ignore",               // include ignored files to ensure metadata is searchable
+    "--glob", ".stash.json",     // only search .stash.json files
+    pattern,
+    searchDir,
+  ], {
+    encoding: "utf8",
+    timeout: 10_000,
+  })
+
+  if (result.status !== 0 && result.status !== 1) {
+    // rg exit code 1 = no matches (normal), anything else = error
+    return null
+  }
+
+  const files = (result.stdout || "")
+    .trim()
+    .split(/\r?\n/)
+    .filter((f) => f.length > 0)
+
+  return { matchedFiles: files, usedRg: true }
+}
+
+// ── ripgrep Installation ────────────────────────────────────────────────────
+
+/**
+ * Platform and architecture detection for ripgrep binary downloads.
+ */
+function getRgPlatformTarget(): { platform: string; arch: string; ext: string } | null {
+  const platform = process.platform
+  const arch = process.arch
+
+  if (platform === "linux" && arch === "x64") {
+    return { platform: "x86_64-unknown-linux-musl", arch: "x64", ext: ".tar.gz" }
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return { platform: "aarch64-unknown-linux-gnu", arch: "arm64", ext: ".tar.gz" }
+  }
+  if (platform === "darwin" && arch === "x64") {
+    return { platform: "x86_64-apple-darwin", arch: "x64", ext: ".tar.gz" }
+  }
+  if (platform === "darwin" && arch === "arm64") {
+    return { platform: "aarch64-apple-darwin", arch: "arm64", ext: ".tar.gz" }
+  }
+  if (platform === "win32" && arch === "x64") {
+    return { platform: "x86_64-pc-windows-msvc", arch: "x64", ext: ".zip" }
+  }
+
+  return null
+}
+
+const RG_VERSION = "14.1.1"
+
+export interface EnsureRgResult {
+  rgPath: string
+  installed: boolean
+  version: string
+}
+
+/**
+ * Ensure ripgrep is available. If not found on PATH or in stash/bin,
+ * download and install it to stash/bin.
+ *
+ * Returns the path to the ripgrep binary and whether it was newly installed.
+ */
+export function ensureRg(stashDir: string): EnsureRgResult {
+  // Already available?
+  const existing = resolveRg(stashDir)
+  if (existing) {
+    return { rgPath: existing, installed: false, version: getRgVersion(existing) }
+  }
+
+  // Determine platform
+  const target = getRgPlatformTarget()
+  if (!target) {
+    throw new Error(
+      `Unsupported platform for ripgrep auto-install: ${process.platform}/${process.arch}. ` +
+      `Install ripgrep manually: https://github.com/BurntSushi/ripgrep#installation`
+    )
+  }
+
+  const binDir = path.join(stashDir, "bin")
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true })
+  }
+
+  const archiveName = `ripgrep-${RG_VERSION}-${target.platform}`
+  const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${archiveName}${target.ext}`
+  const destBinary = path.join(binDir, RG_BINARY)
+
+  if (target.ext === ".tar.gz") {
+    downloadAndExtractTarGz(url, archiveName, destBinary)
+  } else {
+    downloadAndExtractZip(url, archiveName, destBinary)
+  }
+
+  // Make executable
+  if (!IS_WINDOWS) {
+    fs.chmodSync(destBinary, 0o755)
+  }
+
+  return { rgPath: destBinary, installed: true, version: RG_VERSION }
+}
+
+function downloadAndExtractTarGz(url: string, archiveName: string, destBinary: string): void {
+  const destDir = path.dirname(destBinary)
+  const tmpTarGz = path.join(destDir, "rg-download.tar.gz")
+
+  try {
+    // Download archive to a temporary file without using a shell
+    const curlResult = spawnSync(
+      "curl",
+      ["-fsSL", "-o", tmpTarGz, url],
+      {
+        encoding: "utf8",
+        timeout: 60_000,
+      }
+    )
+
+    if (curlResult.status !== 0) {
+      const err = curlResult.stderr?.trim() || curlResult.error?.message || "unknown error"
+      throw new Error(`Failed to download ripgrep from ${url}: ${err}`)
+    }
+
+    // Extract the specific binary from the archive into destDir
+    const tarResult = spawnSync(
+      "tar",
+      [
+        "xzf",
+        tmpTarGz,
+        "--strip-components=1",
+        "-C",
+        destDir,
+        `${archiveName}/rg`,
+      ],
+      {
+        encoding: "utf8",
+        timeout: 60_000,
+      }
+    )
+
+    if (tarResult.status !== 0) {
+      const err = tarResult.stderr?.trim() || tarResult.error?.message || "unknown error"
+      throw new Error(`Failed to extract ripgrep from ${url}: ${err}`)
+    }
+
+    if (!fs.existsSync(destBinary)) {
+      throw new Error(`ripgrep binary not found at ${destBinary} after extraction`)
+    }
+  } finally {
+    // Best-effort cleanup of temporary archive
+    try {
+      if (fs.existsSync(tmpTarGz)) {
+        fs.unlinkSync(tmpTarGz)
+      }
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+function downloadAndExtractZip(url: string, archiveName: string, destBinary: string): void {
+  const destDir = path.dirname(destBinary)
+  const tmpZip = path.join(destDir, "rg-download.zip")
+  const expandedDir = path.join(destDir, archiveName)
+  try {
+    // Download
+    const dlResult = spawnSync("curl", ["-fsSL", "-o", tmpZip, url], {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    if (dlResult.status !== 0) {
+      throw new Error(dlResult.stderr?.trim() || "download failed")
+    }
+
+    // Extract just the rg.exe
+    const extractResult = spawnSync("powershell", [
+      "-Command",
+      `Expand-Archive -Path "${tmpZip}" -DestinationPath "${destDir}" -Force; ` +
+      `Move-Item -Force "${path.join(destDir, archiveName, "rg.exe")}" "${destBinary}"`,
+    ], {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    if (extractResult.status !== 0) {
+      throw new Error(extractResult.stderr?.trim() || "extraction failed")
+    }
+  } finally {
+    if (fs.existsSync(tmpZip)) fs.unlinkSync(tmpZip)
+    if (fs.existsSync(expandedDir)) fs.rmSync(expandedDir, { recursive: true, force: true })
+  }
+}
+
+function getRgVersion(rgPath: string): string {
+  const result = spawnSync(rgPath, ["--version"], { encoding: "utf8", timeout: 5_000 })
+  if (result.status === 0 && result.stdout) {
+    const match = result.stdout.match(/ripgrep\s+([\d.]+)/)
+    return match ? match[1] : "unknown"
+  }
+  return "unknown"
+}

package/src/similarity.ts

@@ -208,17 +208,29 @@ export class TfIdfAdapter implements SearchAdapter {
 
   private substringFallback(query: string, limit: number, typeFilter?: string): ScoredResult[] {
     const q = query.toLowerCase()
+    const tokens = tokenize(q)
     return this.documents
-      .filter((d) => {
-        if (typeFilter && typeFilter !== "any" && d.entry.entry.type !== typeFilter) return false
-        return d.entry.text.includes(q) || d.entry.entry.name.toLowerCase().includes(q)
+      .map((d) => {
+        if (typeFilter && typeFilter !== "any" && d.entry.entry.type !== typeFilter) return null
+        // Check if any query token matches the document text or name
+        const text = d.entry.text
+        const name = d.entry.entry.name.toLowerCase()
+        let matchCount = 0
+        for (const token of tokens) {
+          if (text.includes(token) || name.includes(token)) matchCount++
+        }
+        // Also check full substring match
+        if (text.includes(q) || name.includes(q)) matchCount = Math.max(matchCount, tokens.length)
+        if (matchCount === 0) return null
+        return {
+          entry: d.entry.entry,
+          path: d.entry.path,
+          score: Math.round((matchCount / Math.max(tokens.length, 1)) * 500) / 1000,
+        }
       })
+      .filter((d): d is ScoredResult => d !== null)
+      .sort((a, b) => b.score - a.score)
       .slice(0, limit)
-      .map((d) => ({
-        entry: d.entry.entry,
-        path: d.entry.path,
-        score: 0.5,
-      }))
   }
 }
 

package/src/stash.ts

@@ -3,6 +3,7 @@ import fs from "node:fs"
 import path from "node:path"
 import { loadSearchIndex, buildSearchText } from "./indexer"
 import { TfIdfAdapter, type ScoredEntry } from "./similarity"
+import { rgFilterCandidates, ensureRg } from "./ripgrep"
 
 export type AgentikitAssetType = "tool" | "skill" | "command" | "agent"
 export type AgentikitSearchType = AgentikitAssetType | "any"
@@ -134,7 +135,25 @@ function trySemanticSearch(
   if (!index || !index.entries || index.entries.length === 0) return null
   if (index.stashDir !== stashDir) return null
 
-  const scoredEntries: ScoredEntry[] = index.entries.map((ie) => ({
+  // Stage 1: ripgrep candidate filtering
+  // Use rg to pre-filter .stash.json files that contain query tokens,
+  // then only run TF-IDF ranking on those candidates.
+  let candidateEntries = index.entries
+  if (query) {
+    const rgResult = rgFilterCandidates(query, stashDir, stashDir)
+    if (rgResult && rgResult.usedRg) {
+      const matchedDirs = new Set(rgResult.matchedFiles.map((f) => path.dirname(f)))
+      candidateEntries = index.entries.filter((ie) => matchedDirs.has(ie.dirPath))
+      // If rg found nothing but we have a query, still fall through to TF-IDF
+      // on all entries — rg is a fast pre-filter, not the final authority
+      if (candidateEntries.length === 0) {
+        candidateEntries = index.entries
+      }
+    }
+  }
+
+  // Stage 2: TF-IDF semantic ranking
+  const scoredEntries: ScoredEntry[] = candidateEntries.map((ie) => ({
     id: `${ie.entry.type}:${ie.entry.name}`,
     text: buildSearchText(ie.entry),
     entry: ie.entry,
@@ -142,9 +161,17 @@ function trySemanticSearch(
   }))
 
   let adapter: TfIdfAdapter
-  if (index.tfidf) {
-    adapter = TfIdfAdapter.deserialize(index.tfidf as any, scoredEntries)
+  if (index.tfidf && !query) {
+    // Use cached TF-IDF state for empty queries (listing all)
+    const allScored: ScoredEntry[] = index.entries.map((ie) => ({
+      id: `${ie.entry.type}:${ie.entry.name}`,
+      text: buildSearchText(ie.entry),
+      entry: ie.entry,
+      path: ie.path,
+    }))
+    adapter = TfIdfAdapter.deserialize(index.tfidf as any, allScored)
   } else {
+    // Rebuild adapter from candidate subset
     adapter = new TfIdfAdapter()
     adapter.buildIndex(scoredEntries)
   }
@@ -153,11 +180,15 @@ function trySemanticSearch(
   const results = adapter.search(query, limit, typeFilter)
 
   return results.map((r): SearchHit => {
+    // Derive the openRef name from the filesystem path, not the stash entry name,
+    // because agentikitOpen resolves assets by their relative path under the type root.
+    const openRefName = deriveOpenRefName(r.entry.type, r.path, stashDir)
+
     const hit: SearchHit = {
       type: r.entry.type,
       name: r.entry.name,
       path: r.path,
-      openRef: makeOpenRef(r.entry.type, r.entry.name),
+      openRef: makeOpenRef(r.entry.type, openRefName),
       description: r.entry.description,
       tags: r.entry.tags,
       score: r.score,
@@ -177,6 +208,26 @@ function trySemanticSearch(
   })
 }
 
+/**
+ * Derive the correct openRef name for a semantic search result.
+ * Tools use their relative file path (e.g., "deploy/deploy-k8s.sh"),
+ * skills use directory name, commands/agents use relative .md path.
+ */
+function deriveOpenRefName(
+  type: AgentikitAssetType,
+  filePath: string,
+  stashDir: string,
+): string {
+  const indexer = ASSET_INDEXERS[type]
+  const root = path.join(stashDir, indexer.dir)
+  if (type === "skill") {
+    // Skills resolve by directory name relative to skills/
+    const rel = toPosix(path.dirname(path.relative(root, filePath)))
+    return rel === "." ? path.basename(path.dirname(filePath)) : rel
+  }
+  return toPosix(path.relative(root, filePath))
+}
+
 export function agentikitOpen(input: { ref: string }): OpenResponse {
   const parsed = parseOpenRef(input.ref)
   const stashDir = resolveStashDir()
@@ -622,6 +673,11 @@ export interface InitResponse {
   created: boolean
   envSet: boolean
   profileUpdated?: string
+  ripgrep?: {
+    rgPath: string
+    installed: boolean
+    version: string
+  }
 }
 
 export function agentikitInit(): InitResponse {
@@ -686,7 +742,16 @@ export function agentikitInit(): InitResponse {
 
   process.env.AGENTIKIT_STASH_DIR = stashDir
 
-  return { stashDir, created, envSet, profileUpdated }
+  // Ensure ripgrep is available (install to stash/bin if needed)
+  let ripgrep: InitResponse["ripgrep"]
+  try {
+    const rgResult = ensureRg(stashDir)
+    ripgrep = rgResult
+  } catch {
+    // Non-fatal: ripgrep is optional, search works without it
+  }
+
+  return { stashDir, created, envSet, profileUpdated, ripgrep }
 }
 
 function hasErrnoCode(error: unknown, code: string): boolean {