akm-cli 0.1.1 → 0.1.3

package/README.md

@@ -25,12 +25,15 @@ Upgrade in place with `akm upgrade`.
 ## Quick Start
 
 ```sh
-akm init                          # Initialize your working stash
+akm setup                         # Guided setup: configure, initialize, and index
 akm add github:owner/repo         # Add a kit from GitHub
 akm search "deploy"               # Find assets
 akm show script:deploy.sh         # View details and run command
 ```
 
+If you want to skip the wizard, `akm init --dir ~/custom-stash` initializes the
+working stash at a custom path.
+
 ## Features
 
 ### Works with Any AI Agent

package/dist/cli.js

@@ -41,6 +41,8 @@ const pkgVersion = (() => {
 const OUTPUT_FORMATS = ["json", "yaml", "text"];
 const DETAIL_LEVELS = ["brief", "normal", "full"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
+const CONTEXT_HUB_ALIAS_REF = "context-hub";
+const CONTEXT_HUB_ALIAS_URL = "https://github.com/andrewyng/context-hub";
 function hasBunYAML(b) {
     // biome-ignore lint/suspicious/noExplicitAny: type guard for runtime feature detection
     return typeof b.YAML?.stringify === "function";
@@ -403,6 +405,18 @@ function formatSearchPlain(r, detail) {
  * - registry-*  : Kit discovery from remote registries (npm, GitHub)
  * - installed-kits : Management of kits already installed locally
  */
+const setupCommand = defineCommand({
+    meta: {
+        name: "setup",
+        description: "Interactive configuration wizard for embeddings, LLM, registries, and stash sources",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const { runSetupWizard } = await import("./setup");
+            await runSetupWizard();
+        });
+    },
+});
 const initCommand = defineCommand({
     meta: {
         name: "init",
@@ -468,6 +482,15 @@ const addCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (args.ref.trim() === CONTEXT_HUB_ALIAS_REF) {
+                const result = addStash({
+                    target: CONTEXT_HUB_ALIAS_URL,
+                    providerType: "context-hub",
+                    name: "context-hub",
+                });
+                output("stash-add", result);
+                return;
+            }
             const result = await akmAdd({ ref: args.ref });
             output("add", result);
         });
@@ -966,6 +989,7 @@ const main = defineCommand({
         quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
     },
     subCommands: {
+        setup: setupCommand,
         init: initCommand,
         index: indexCommand,
         add: addCommand,
@@ -1143,6 +1167,7 @@ akm search "<query>" --type skill             # Filter by type
 akm search "<query>" --source both            # Also search registries for installable kits
 akm show <ref>                                # View asset details
 akm add <ref>                                 # Install a kit (npm, GitHub, git, local)
+akm add context-hub                           # Shortcut for adding Context Hub as a stash provider
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
 akm registry search "<query>"                 # Search all registries
 \`\`\`
@@ -1213,6 +1238,7 @@ akm add <ref>                                 # Install a kit (smart router: loc
 akm add @scope/kit                            # From npm
 akm add owner/repo                            # From GitHub
 akm add ./path/to/local/kit                   # From local directory (adds as stash)
+akm add context-hub                           # Add the official Context Hub stash
 akm kit add <ref>                             # Install a kit (explicit)
 akm kit list                                  # List installed kits
 akm kit remove <target>                       # Remove a kit

package/dist/db.js

@@ -385,17 +385,22 @@ export function searchFts(db, query, limit, entryType) {
         return [];
     }
 }
-function sanitizeFtsQuery(query) {
-    const tokens = query
-        .replace(/[^a-zA-Z0-9\s]/g, " ")
-        .split(/\s+/)
-        .filter((t) => t.length >= 2);
+export function sanitizeFtsQuery(query) {
+    // Allow only characters safe in FTS5 queries: letters, digits, underscores,
+    // and whitespace. Everything else (hyphens, dots, quotes, parens, asterisks,
+    // colons, carets, @, !, etc.) is replaced with a space so that compound
+    // identifiers like "code-review" or "k8s.setup" become AND-joined tokens
+    // ("code review", "k8s setup") rather than triggering FTS5 syntax errors.
+    let sanitized = query.replace(/[^a-zA-Z0-9_\s]/g, " ");
+    // Neutralize the NEAR operator (FTS5 proximity syntax)
+    sanitized = sanitized.replace(/\bNEAR\b/g, " ");
+    const tokens = sanitized.split(/\s+/).filter((t) => t.length >= 1);
     if (tokens.length === 0)
         return "";
-    // MD-1: Use OR so that any matching token returns results (better recall for
-    // exploratory search). Use unquoted tokens so the porter stemmer can
-    // normalize word forms.
-    return tokens.join(" OR ");
+    // Use implicit AND (space-separated tokens) for precision. FTS5 treats
+    // space-separated tokens as an implicit AND, matching only rows that
+    // contain ALL terms.
+    return tokens.join(" ");
 }
 // ── All entries ─────────────────────────────────────────────────────────────
 export function getAllEntries(db, entryType) {

package/dist/detect.js

@@ -0,0 +1,120 @@
+/**
+ * Service detection utilities for the setup wizard.
+ *
+ * Pure detection functions with no user interaction — each returns
+ * a result object describing what was found.
+ */
+import fs from "node:fs";
+import path from "node:path";
+// ── Ollama Detection ────────────────────────────────────────────────────────
+const OLLAMA_BASE = "http://localhost:11434";
+/**
+ * Detect if Ollama is running and list available models.
+ *
+ * Tries the HTTP API first (`/api/tags`), then falls back to `ollama list`
+ * via subprocess. Returns available models sorted alphabetically.
+ */
+export async function detectOllama() {
+    const result = { available: false, models: [], endpoint: OLLAMA_BASE };
+    // Try HTTP API first
+    try {
+        const response = await fetch(`${OLLAMA_BASE}/api/tags`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (response.ok) {
+            const data = (await response.json());
+            if (Array.isArray(data.models)) {
+                result.models = data.models
+                    .map((m) => (typeof m.name === "string" ? m.name.replace(/:latest$/, "") : ""))
+                    .filter(Boolean)
+                    .sort();
+                result.available = true;
+                return result;
+            }
+        }
+    }
+    catch {
+        // HTTP failed — try CLI fallback
+    }
+    // CLI fallback
+    try {
+        const proc = Bun.spawn(["ollama", "list"], {
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        const text = await new Response(proc.stdout).text();
+        const exitCode = await proc.exited;
+        if (exitCode === 0 && text.trim()) {
+            const lines = text.trim().split("\n").slice(1); // skip header
+            result.models = lines
+                .map((line) => {
+                const name = line.split(/\s+/)[0]?.replace(/:latest$/, "");
+                return name || "";
+            })
+                .filter(Boolean)
+                .sort();
+            result.available = true;
+        }
+    }
+    catch {
+        // Ollama not installed or not in PATH
+    }
+    return result;
+}
+// ── Agent Platform Detection ────────────────────────────────────────────────
+const AGENT_PLATFORMS = [
+    { name: "Claude Code", relPath: ".claude" },
+    { name: "OpenCode", relPath: ".config/opencode" },
+    { name: "Continue", relPath: ".continue" },
+    { name: "Codeium / Windsurf", relPath: ".codeium" },
+    { name: "Cursor", relPath: ".cursor" },
+    { name: "Codex CLI", relPath: ".codex" },
+];
+/**
+ * Scan the user's home directory for known agent platform config directories.
+ * Supports both HOME (Unix) and USERPROFILE (Windows).
+ */
+export function detectAgentPlatforms() {
+    const home = process.env.HOME?.trim() || process.env.USERPROFILE?.trim();
+    if (!home)
+        return [];
+    return AGENT_PLATFORMS.filter((p) => {
+        const fullPath = path.join(home, p.relPath);
+        try {
+            return fs.statSync(fullPath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }).map((p) => ({
+        name: p.name,
+        path: path.join(home, p.relPath),
+    }));
+}
+// ── OpenViking Detection ────────────────────────────────────────────────────
+/**
+ * Check if an OpenViking server is reachable at the given URL.
+ * Uses the lightweight /api/v1/fs/stat endpoint (GET) rather than
+ * the search endpoint which requires a running search index.
+ */
+export async function detectOpenViking(url) {
+    const normalized = url.replace(/\/+$/, "");
+    try {
+        // Any HTTP response (even non-2xx) from the API endpoint means the server is reachable.
+        // Only network errors / timeouts indicate the server is truly unavailable.
+        await fetch(`${normalized}/api/v1/fs/stat?uri=${encodeURIComponent("viking://")}`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        return { available: true, url: normalized };
+    }
+    catch {
+        // stat endpoint unreachable — try root URL as fallback
+        try {
+            await fetch(normalized, { signal: AbortSignal.timeout(5000) });
+            return { available: true, url: normalized };
+        }
+        catch {
+            return { available: false, url: normalized };
+        }
+    }
+}

package/dist/embedder.js

@@ -30,6 +30,19 @@ async function embedLocal(text) {
     const result = await model(text, { pooling: "mean", normalize: true });
     return Array.from(result.data);
 }
+// ── Vector normalization ─────────────────────────────────────────────────────
+/**
+ * L2-normalize a vector to unit length.
+ * Required for remote embeddings because the scoring pipeline's L2-to-cosine
+ * conversion formula (1 - distance^2/2) is only correct for unit vectors.
+ * The local embedder already normalizes via `normalize: true`.
+ */
+function l2Normalize(vec) {
+    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+    if (norm === 0)
+        return vec;
+    return vec.map((v) => v / norm);
+}
 // ── OpenAI-compatible remote embedder ───────────────────────────────────────
 async function embedRemote(text, config) {
     const headers = { "Content-Type": "application/json" };
@@ -56,7 +69,7 @@ async function embedRemote(text, config) {
     if (!json.data?.[0]?.embedding) {
         throw new Error("Unexpected embedding response format: missing data[0].embedding");
     }
-    return json.data[0].embedding;
+    return l2Normalize(json.data[0].embedding);
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
@@ -118,11 +131,13 @@ async function embedRemoteBatch(texts, config) {
         if (!json.data || json.data.length !== batch.length) {
             throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
         }
-        for (const [idx, d] of json.data.entries()) {
+        // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
+        const sorted = [...json.data].sort((a, b) => a.index - b.index);
+        for (const [idx, d] of sorted.entries()) {
             if (!Array.isArray(d.embedding)) {
                 throw new Error(`Unexpected embedding at batch index ${idx}: missing or invalid`);
             }
-            results.push(d.embedding);
+            results.push(l2Normalize(d.embedding));
         }
     }
     return results;

package/dist/indexer.js

@@ -162,6 +162,13 @@ async function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtM
         }
     }
     // Phase 2 (sync): write all pre-generated metadata inside a single transaction.
+    //
+    // Cross-stash dedup: track indexed assets by content identity
+    // (type + filename + description) so the same asset from a lower-priority
+    // stash root is skipped when a higher-priority root already covers it.
+    // Sources are ordered by priority (primary stash first), so the first
+    // occurrence wins.
+    const indexedAssetIdentities = new Set();
     const insertTransaction = db.transaction(() => {
         // HI-5: Perform the full-rebuild wipe as the FIRST step of the insert
         // transaction so delete and re-insert are atomic — a concurrent reader
@@ -190,8 +197,20 @@ async function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtM
             // Delete old entries for this dir (will be re-inserted)
             deleteEntriesByDir(db, dirPath);
             if (stash) {
+                // Build a lookup for matching filename-less entries to actual files
+                const fileBasenameMap = buildFileBasenameMap(files);
                 for (const entry of stash.entries) {
-                    const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+                    const entryPath = entry.filename
+                        ? path.join(dirPath, entry.filename)
+                        : matchEntryToFile(entry.name, fileBasenameMap, files);
+                    if (!entryPath)
+                        continue; // skip unresolvable entries
+                    // Skip if a higher-priority stash root already indexed this asset
+                    const basename = path.basename(entryPath);
+                    const identityKey = `${entry.type}\0${basename}\0${entry.description ?? ""}`;
+                    if (indexedAssetIdentities.has(identityKey))
+                        continue;
+                    indexedAssetIdentities.add(identityKey);
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
@@ -335,6 +354,43 @@ async function enhanceStashWithLlm(llmConfig, stash, _dirPath, files) {
     }
     return { entries: enhanced };
 }
+/**
+ * Build a map from base filename (without extension) to full path for quick lookups.
+ */
+export function buildFileBasenameMap(files) {
+    const map = new Map();
+    for (const file of files) {
+        const base = path.basename(file, path.extname(file));
+        // Only keep first match per base name to avoid ambiguity
+        if (!map.has(base))
+            map.set(base, file);
+    }
+    return map;
+}
+/**
+ * Try to match a filename-less entry to an actual file in the directory.
+ *
+ * Matching strategy (in priority order):
+ *   1. Exact basename match: entry.name === filename without extension
+ *   2. Last path segment match: for entries with names like "dir/sub-entry",
+ *      try matching the last segment
+ *   3. Fallback: first file in the directory, or null if no files are available
+ */
+export function matchEntryToFile(entryName, fileMap, files) {
+    // Exact match on entry name
+    const exact = fileMap.get(entryName);
+    if (exact)
+        return exact;
+    // Try last segment for hierarchical names (e.g. "corpus/agentic-patterns/foo")
+    const lastSegment = entryName.split("/").pop() ?? entryName;
+    if (lastSegment !== entryName) {
+        const segmentMatch = fileMap.get(lastSegment);
+        if (segmentMatch)
+            return segmentMatch;
+    }
+    // Fallback to first file, or null if no files are available
+    return files[0] || null;
+}
 export function buildSearchText(entry) {
     const parts = [entry.name.replace(/[-_]/g, " ")];
     if (entry.description)
@@ -347,6 +403,8 @@ export function buildSearchText(entry) {
         parts.push(entry.aliases.join(" "));
     if (entry.searchHints)
         parts.push(entry.searchHints.join(" "));
+    if (entry.usage)
+        parts.push(entry.usage.join(" "));
     if (entry.intent) {
         if (entry.intent.when)
             parts.push(entry.intent.when);

package/dist/local-search.js

@@ -99,7 +99,15 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
         const allEntries = getAllEntries(db, typeFilter);
-        const selected = allEntries.slice(0, limit);
+        // Deduplicate by file path — multiple entries can share the same file
+        const seenFilePaths = new Set();
+        const uniqueEntries = allEntries.filter((ie) => {
+            if (seenFilePaths.has(ie.filePath))
+                return false;
+            seenFilePaths.add(ie.filePath);
+            return true;
+        });
+        const selected = uniqueEntries.slice(0, limit);
         const hits = await Promise.all(selected.map((ie) => buildDbHit({
             entry: ie.entry,
             path: ie.filePath,
@@ -137,6 +145,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         }
     }
     // Merge results using RRF
+    // Issue #15: "hybrid" for results appearing in both FTS and vec results.
     const scored = [];
     const seenIds = new Set();
     // Process FTS results
@@ -146,7 +155,8 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         const embedRank = embedRankMap.get(id);
         const embedRrf = embedRank !== undefined ? 1 / (RRF_K + embedRank) : 0;
         const rrfScore = ftsRrf + embedRrf;
-        const rankingMode = embedRrf > 0 ? "semantic" : "fts";
+        // Issue #15: combined FTS+vec results are "hybrid", not "semantic"
+        const rankingMode = embedRrf > 0 ? "hybrid" : "fts";
         scored.push({ id, entry: result.entry, filePath: result.filePath, score: rrfScore, rankingMode });
     }
     // Add vec-only results not already in FTS results
@@ -172,45 +182,63 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             }
         }
     }
-    // Apply boosts as multiplicative factors
+    // Apply boosts as multiplicative factors (all boosts in a single phase
+    // so that sort order and displayed scores are always consistent — Issue #1).
     const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     for (const item of scored) {
         const entry = item.entry;
         let boostSum = 0;
-        // Tag boost
+        // Tag boost — capped at 0.30 (Issue #7)
         if (entry.tags) {
+            let tagBoost = 0;
             for (const tag of entry.tags) {
                 if (queryTokens.some((t) => tag.toLowerCase() === t)) {
-                    boostSum += 0.15;
+                    tagBoost += 0.15;
                 }
             }
+            boostSum += Math.min(0.3, tagBoost);
         }
-        // Search hint boost
+        // Search hint boost — capped at 0.24 (Issue #7)
         if (entry.searchHints) {
+            let hintBoost = 0;
             for (const hint of entry.searchHints) {
                 const hintLower = hint.toLowerCase();
                 for (const token of queryTokens) {
                     if (hintLower.includes(token)) {
-                        boostSum += 0.12;
+                        hintBoost += 0.12;
                         break;
                     }
                 }
             }
+            boostSum += Math.min(0.24, hintBoost);
         }
         // Name boost
         const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
         if (queryTokens.some((t) => nameLower.includes(t))) {
             boostSum += 0.1;
         }
+        // Quality boost (Issue #1: moved from buildDbHit to single-phase)
+        const qualityBoost = entry.quality === "generated" ? 0 : 0.05;
+        boostSum += qualityBoost;
+        // Confidence boost (Issue #1: moved from buildDbHit to single-phase)
+        const confidenceBoost = typeof entry.confidence === "number" ? Math.min(0.05, Math.max(0, entry.confidence) * 0.05) : 0;
+        boostSum += confidenceBoost;
         item.score = item.score * (1 + boostSum);
     }
-    scored.sort((a, b) => b.score - a.score);
+    // Issue #14: deterministic tiebreaker on equal scores
+    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    // Deduplicate by file path — keep only the highest-scored entry per file.
+    // Multiple .stash.json entries can map to the same file (e.g. entries without
+    // a filename field all collapse to files[0]). Showing the same path/ref
+    // multiple times clutters results.
+    const deduped = deduplicateByPath(scored);
     const rankMs = Date.now() - tRank0;
-    const selected = scored.slice(0, limit);
+    const selected = deduped.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode }) => buildDbHit({
         entry,
         path: filePath,
-        score: Math.round(score * 100) / 100,
+        // Issue #8: round to 4 decimal places instead of 2
+        score: Math.round(score * 10000) / 10000,
         query,
         rankingMode,
         defaultStashDir: stashDir,
@@ -233,9 +261,10 @@ async function tryVecScores(db, query, k, config) {
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();
         for (const { id, distance } of vecResults) {
-            // Convert L2 distance to cosine similarity (vectors are normalized)
-            const cosineSim = 1 - (distance * distance) / 2;
-            scores.set(id, Math.max(0, cosineSim));
+            // Convert L2 distance to cosine similarity (vectors are normalized).
+            // Issue #3: guard against NaN/Infinity from sqlite-vec edge cases.
+            const raw = 1 - (distance * distance) / 2;
+            scores.set(id, Number.isFinite(raw) ? Math.max(0, raw) : 0);
         }
         return scores;
     }
@@ -249,15 +278,18 @@ async function substringSearch(query, searchType, limit, stashDir, sources, conf
     const assets = await indexAssets(stashDir, searchType);
     const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
     if (!query) {
-        return Promise.all(matched
-            .sort(compareAssets)
-            .slice(0, limit)
-            .map((asset) => assetToSearchHit(asset, query, stashDir, sources, config)));
+        const sorted = matched.sort(compareAssets);
+        const unique = deduplicateAssetsByPath(sorted);
+        return Promise.all(unique.slice(0, limit).map((asset) => assetToSearchHit(asset, query, stashDir, sources, config)));
     }
     // Score and sort by relevance
     const scored = matched.map((asset) => ({ asset, score: scoreSubstringMatch(asset.entry, query) }));
     scored.sort((a, b) => b.score - a.score || compareAssets(a.asset, b.asset));
-    return Promise.all(scored.slice(0, limit).map(({ asset, score }) => assetToSearchHit(asset, query, stashDir, sources, config, score)));
+    // Deduplicate by path — keep highest-scored entry per file
+    const dedupedScored = deduplicateByPath(scored.map((s) => ({ ...s, filePath: s.asset.path })));
+    return Promise.all(dedupedScored
+        .slice(0, limit)
+        .map(({ asset, score }) => assetToSearchHit(asset, query, stashDir, sources, config, score)));
 }
 function scoreSubstringMatch(entry, query) {
     const tokens = query.split(/\s+/).filter(Boolean);
@@ -282,16 +314,22 @@ function scoreSubstringMatch(entry, query) {
     if (tokens.some((t) => descLower.includes(t))) {
         score += 0.05;
     }
-    return Math.round(Math.min(1, score) * 100) / 100;
+    // Issue #8: round to 4 decimal places instead of 2
+    return Math.round(Math.min(1, score) * 10000) / 10000;
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
     const canonical = deriveCanonicalAssetNameFromStashRoot(input.entry.type, entryStashDir, input.path);
     const refName = canonical && !canonical.startsWith("../") && !canonical.startsWith("..\\") ? canonical : input.entry.name;
+    // Issue #1: Quality and confidence boosts are now applied in the main scoring
+    // phase (searchDatabase). buildDbHit receives the already-final score and
+    // passes it through without further multiplication. We still compute the
+    // boost values here for buildWhyMatched reporting.
     const qualityBoost = input.entry.quality === "generated" ? 0 : 0.05;
     const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
-    const score = Math.round(input.score * (1 + qualityBoost + confidenceBoost) * 100) / 100;
+    // Issue #8: round to 4 decimal places, no boost multiplication
+    const score = Math.round(input.score * 10000) / 10000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost);
     const source = findSourceForPath(input.path, input.sources);
     const editable = isEditable(input.path, input.config);
@@ -316,13 +354,24 @@ export async function buildDbHit(input) {
     }
     return hit;
 }
-export function buildWhyMatched(entry, query, rankingMode, qualityBoost, confidenceBoost) {
-    const reasons = [rankingMode === "semantic" ? "semantic similarity" : "fts bm25 relevance"];
+export function buildWhyMatched(entry, query, 
+// Issue #15: added "hybrid" ranking mode
+rankingMode, qualityBoost, confidenceBoost) {
+    // Issue #15: "hybrid" label for combined FTS+vec results
+    const reasons = [
+        rankingMode === "hybrid"
+            ? "hybrid (fts + semantic)"
+            : rankingMode === "semantic"
+                ? "semantic similarity"
+                : "fts bm25 relevance",
+    ];
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const name = entry.name.toLowerCase();
     const tags = entry.tags?.join(" ").toLowerCase() ?? "";
     const searchHints = entry.searchHints?.join(" ").toLowerCase() ?? "";
     const aliases = entry.aliases?.join(" ").toLowerCase() ?? "";
+    // Issue #12: include description in match reasons
+    const desc = entry.description?.toLowerCase() ?? "";
     if (tokens.some((t) => name.includes(t)))
         reasons.push("matched name tokens");
     if (tokens.some((t) => tags.includes(t)))
@@ -331,6 +380,9 @@ export function buildWhyMatched(entry, query, rankingMode, qualityBoost, confide
         reasons.push("matched searchHints");
     if (tokens.some((t) => aliases.includes(t)))
         reasons.push("matched aliases");
+    // Issue #12: report description matches
+    if (tokens.some((t) => desc.includes(t)))
+        reasons.push("matched description");
     if (qualityBoost > 0)
         reasons.push("curated metadata boost");
     if (confidenceBoost > 0)
@@ -413,10 +465,27 @@ async function indexAssets(stashDir, type) {
                 continue;
             stash = generated;
         }
+        // Build a lookup for matching filename-less entries to actual files
+        const fileBasenameMap = new Map();
+        for (const file of files) {
+            const base = path.basename(file, path.extname(file));
+            if (!fileBasenameMap.has(base))
+                fileBasenameMap.set(base, file);
+        }
         for (const entry of stash.entries) {
             if (filterType && entry.type !== filterType)
                 continue;
-            const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+            let entryPath;
+            if (entry.filename) {
+                entryPath = path.join(dirPath, entry.filename);
+            }
+            else {
+                // Try matching entry name to a file by basename
+                entryPath =
+                    fileBasenameMap.get(entry.name) ??
+                        fileBasenameMap.get(entry.name.split("/").pop() ?? "") ??
+                        (files[0] || dirPath);
+            }
             assets.push({ entry, path: entryPath });
         }
     }
@@ -427,3 +496,31 @@ function compareAssets(a, b) {
         return a.entry.type.localeCompare(b.entry.type);
     return a.entry.name.localeCompare(b.entry.name);
 }
+/**
+ * Deduplicate scored results by file path, keeping only the highest-scored
+ * entry per unique path. Sorts by score descending internally to ensure the
+ * precondition is always met regardless of caller (Issue #4).
+ */
+function deduplicateByPath(items) {
+    // Issue #4: sort inside to enforce the descending-score precondition
+    const sorted = [...items].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const seen = new Set();
+    return sorted.filter((item) => {
+        if (seen.has(item.filePath))
+            return false;
+        seen.add(item.filePath);
+        return true;
+    });
+}
+/**
+ * Deduplicate IndexedAsset[] by path, keeping the first (highest-priority) entry.
+ */
+function deduplicateAssetsByPath(assets) {
+    const seen = new Set();
+    return assets.filter((asset) => {
+        if (seen.has(asset.path))
+            return false;
+        seen.add(asset.path);
+        return true;
+    });
+}