akm-cli 0.6.0-rc1 → 0.6.0-rc2

package/dist/{db-search.js → indexer/db-search.js}

@@ -1,29 +1,29 @@
 /**
- * Database-backed (SQLite + FTS5/vector) stash search implementation.
+ * Database-backed (SQLite + FTS5/vector) source search implementation.
  *
- * Extracted from stash-search.ts to break the circular import:
- *   stash-search.ts → stash-providers/filesystem.ts → db-search.ts (no cycle)
+ * Extracted from source-search.ts to break the circular import:
+ *   source-search.ts → sources/providers/filesystem.ts → db-search.ts (no cycle)
  *
- * stash-search.ts imports this module for the `searchLocal` export.
- * stash-providers/filesystem.ts also imports `searchLocal` from here.
+ * source-search.ts imports this module for the `searchLocal` export.
+ * sources/providers/filesystem.ts also imports `searchLocal` from here.
  *
  * Renamed from `local-search.ts` to signal that this is the DB-layer search
  * implementation, not a "local vs. remote" distinction.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { defaultRendererRegistry } from "./asset-registry";
-import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
+import { makeAssetRef } from "../core/asset-ref";
+import { defaultRendererRegistry } from "../core/asset-registry";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
 import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
-import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status";
-import { makeAssetRef } from "./stash-ref";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 export async function rendererForType(type, registry = defaultRendererRegistry) {
     const name = registry.rendererNameFor(type);
     return name ? getRenderer(name) : undefined;
@@ -45,7 +45,7 @@ function resolveSearchHitOrigin(source) {
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
-    const allStashDirs = sources.map((s) => s.path);
+    const allSourceDirs = sources.map((s) => s.path);
     const rawStatus = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
@@ -85,7 +85,7 @@ export async function searchLocal(input) {
                     }
                 }
                 if (entryCount > 0 && stashDirMatch) {
-                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources, rendererRegistry);
+                    const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry);
                     return {
                         hits,
                         tip: hits.length === 0
@@ -105,7 +105,7 @@ export async function searchLocal(input) {
     catch (error) {
         warn("Search index unavailable, falling back to substring search:", error instanceof Error ? error.message : String(error));
     }
-    const hitArrays = await Promise.all(allStashDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
+    const hitArrays = await Promise.all(allSourceDirs.map((dir) => substringSearch(query, searchType, limit, dir, sources, config, rendererRegistry)));
     const hits = hitArrays.flat().slice(0, limit);
     return {
         hits,
@@ -114,7 +114,7 @@ export async function searchLocal(input) {
     };
 }
 // ── Database search ─────────────────────────────────────────────────────────
-async function searchDatabase(db, query, searchType, limit, stashDir, allStashDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
+async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
     // Empty query: return all entries
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
@@ -135,7 +135,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             query,
             rankingMode: "fts",
             defaultStashDir: stashDir,
-            allStashDirs,
+            allSourceDirs,
             sources,
             config,
             rendererRegistry,
@@ -355,13 +355,19 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             item.utilityBoosted = true;
         }
     }
+    // ── minScore floor ──────────────────────────────────────────────────────
+    // Drop semantic-only hits (cosine-only, no FTS match) whose score falls
+    // below the configured floor. FTS hits and hybrid hits are always kept.
+    // Default floor: 0.2. Set search.minScore = 0 in config to disable.
+    const minScore = config.search?.minScore ?? 0.2;
+    const preFilter = minScore > 0 ? scored.filter((item) => item.rankingMode !== "semantic" || item.score >= minScore) : scored;
     // Deterministic tiebreaker on equal scores
-    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    preFilter.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 deduped = deduplicateByPath(preFilter);
     const rankMs = Date.now() - tRank0;
     const selected = deduped.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode, utilityBoosted }) => buildDbHit({
@@ -372,7 +378,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         query,
         rankingMode,
         defaultStashDir: stashDir,
-        allStashDirs,
+        allSourceDirs,
         sources,
         config,
         utilityBoosted,
@@ -389,7 +395,7 @@ async function tryVecScores(db, query, k, config) {
     if (hasEmbeddings !== "1")
         return null;
     try {
-        const { embed } = await import("./embedder.js");
+        const { embed } = await import("../llm/embedder.js");
         const queryEmbedding = await embed(query, config.embedding);
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();

package/dist/{db.js → indexer/db.js}

@@ -2,13 +2,13 @@ import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { cosineSimilarity } from "./embedders/types";
-import { getDbPath } from "./paths";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
+import { cosineSimilarity } from "../llm/embedders/types";
 import { buildSearchFields } from "./search-fields";
 import { ensureUsageEventsSchema } from "./usage-events";
-import { warn } from "./warn";
 // ── Constants ───────────────────────────────────────────────────────────────
-export const DB_VERSION = 8;
+export const DB_VERSION = 9;
 export const EMBEDDING_DIM = 384;
 // ── Database lifecycle ──────────────────────────────────────────────────────
 export function openDatabase(dbPath, options) {
@@ -19,6 +19,7 @@ export function openDatabase(dbPath, options) {
     }
     const db = new Database(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA busy_timeout = 5000");
     db.exec("PRAGMA foreign_keys = ON");
     // Try to load sqlite-vec extension
     loadVecExtension(db);
@@ -102,6 +103,22 @@ function ensureSchema(db, embeddingDim) {
 
     CREATE INDEX IF NOT EXISTS idx_entries_dir ON entries(dir_path);
     CREATE INDEX IF NOT EXISTS idx_entries_type ON entries(entry_type);
+  `);
+    // Validated WorkflowDocument JSON, one row per indexed workflow entry.
+    // Pure index data — fully rebuilt on each `akm index`. ON DELETE CASCADE
+    // means clearing entries (full rebuild or per-dir delete) drops these too.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_documents (
+      entry_id        INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE,
+      schema_version  INTEGER NOT NULL,
+      document_json   TEXT NOT NULL,
+      source_path     TEXT NOT NULL,
+      source_hash     TEXT NOT NULL,
+      updated_at      TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_workflow_documents_source_path
+      ON workflow_documents(source_path);
   `);
     // Set version immediately after table creation so a crash before the end of
     // ensureSchema() does not leave the database in a versionless state on next open.
@@ -145,6 +162,15 @@ function ensureSchema(db, embeddingDim) {
       updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
       FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
     );
+  `);
+    // FTS-dirty queue. Created here (not lazily on first upsert) so the
+    // per-entry write path doesn't issue a CREATE TABLE IF NOT EXISTS on
+    // every call — that DDL would fire thousands of times during a full
+    // index. See `markFtsDirty` and `rebuildFts({ incremental: true })`.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entries_fts_dirty (
+      entry_id INTEGER PRIMARY KEY
+    );
   `);
     // sqlite-vec table
     if (isVecAvailable(db)) {
@@ -280,45 +306,45 @@ export function setMeta(db, key, value) {
  * reflect the changes.
  */
 export function upsertEntry(db, entryKey, dirPath, filePath, stashDir, entry, searchText) {
-    const stmt = db.prepare(`
-    INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(entry_key) DO UPDATE SET
-      dir_path = excluded.dir_path,
-      file_path = excluded.file_path,
-      stash_dir = excluded.stash_dir,
-      entry_json = excluded.entry_json,
-      search_text = excluded.search_text,
-      entry_type = excluded.entry_type
-  `);
-    stmt.run(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type);
-    // Fetch the row id explicitly since last_insert_rowid() is unreliable for ON CONFLICT DO UPDATE
-    const row = db.prepare("SELECT id FROM entries WHERE entry_key = ?").get(entryKey);
-    if (!row)
+    // Hot path during indexing — cache the two prepared statements per
+    // database connection so we don't pay the SQL parse/compile cost on
+    // every call. The dirty-mark INSERT and the upsert-with-RETURNING
+    // share the same WeakMap so they live and die with the connection.
+    const stmts = getUpsertStmts(db);
+    const result = stmts.upsert.get(entryKey, dirPath, filePath, stashDir, JSON.stringify(entry), searchText, entry.type);
+    if (!result)
         throw new Error("upsertEntry: entry_key not found after upsert");
-    // Mark this entry as FTS-dirty so an incremental rebuild only revisits the
-    // entries that actually changed. Without this, every `akm index` run had to
-    // re-scan and re-insert every FTS row, even if only one entry was touched.
-    markFtsDirty(db, row.id);
-    return row.id;
-}
-/**
- * Mark an entry as needing FTS re-indexing on the next `rebuildFts` call.
- *
- * The list lives in a small `entries_fts_dirty` table — a per-entry-id queue
- * of work items. `rebuildFts({ incremental: true })` drains this list rather
- * than scanning the entire `entries` table.
- */
-function markFtsDirty(db, entryId) {
-    ensureFtsDirtyTable(db);
-    db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)").run(entryId);
-}
-function ensureFtsDirtyTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS entries_fts_dirty (
-      entry_id INTEGER PRIMARY KEY
-    );
-  `);
+    // Mark this entry as FTS-dirty so `rebuildFts({ incremental: true })`
+    // only revisits entries that actually changed. INSERT OR IGNORE is
+    // idempotent across multiple upserts of the same row.
+    stmts.markDirty.run(result.id);
+    return result.id;
+}
+const upsertStmtsByDb = new WeakMap();
+function getUpsertStmts(db) {
+    const existing = upsertStmtsByDb.get(db);
+    if (existing)
+        return existing;
+    const stmts = {
+        // RETURNING id handles ON CONFLICT DO UPDATE correctly — no second
+        // SELECT round-trip needed (last_insert_rowid() is unreliable for
+        // ON CONFLICT). Use `.get()` so a single row comes back.
+        upsert: db.prepare(`
+      INSERT INTO entries (entry_key, dir_path, file_path, stash_dir, entry_json, search_text, entry_type)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(entry_key) DO UPDATE SET
+        dir_path = excluded.dir_path,
+        file_path = excluded.file_path,
+        stash_dir = excluded.stash_dir,
+        entry_json = excluded.entry_json,
+        search_text = excluded.search_text,
+        entry_type = excluded.entry_type
+      RETURNING id
+    `),
+        markDirty: db.prepare("INSERT OR IGNORE INTO entries_fts_dirty (entry_id) VALUES (?)"),
+    };
+    upsertStmtsByDb.set(db, stmts);
+    return stmts;
 }
 export function deleteEntriesByDir(db, dirPath) {
     db.transaction(() => {
@@ -419,7 +445,6 @@ export function rebuildFts(db, options) {
     db.transaction(() => {
         let rows;
         if (incremental) {
-            ensureFtsDirtyTable(db);
             // Read the dirty queue and join against entries to get the JSON.
             // Then drop the matching rows from entries_fts so the INSERT below
             // doesn't double-up. The dirty list is drained at the end.
@@ -469,10 +494,8 @@ export function rebuildFts(db, options) {
             db.exec("DELETE FROM entries_fts_dirty");
         }
         else {
-            // Full path: only drop the dirty table if it exists. Use
-            // `CREATE IF NOT EXISTS` then DELETE so we don't error on databases
-            // that haven't run any upserts yet (e.g. fresh schema).
-            ensureFtsDirtyTable(db);
+            // Full path: drain the dirty queue too. The table is created by
+            // ensureSchema(), so it always exists at this point.
             db.exec("DELETE FROM entries_fts_dirty");
         }
     })();

package/dist/{file-context.js → indexer/file-context.js}

@@ -6,8 +6,8 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { toPosix } from "./common";
-import { parseFrontmatter } from "./frontmatter";
+import { toPosix } from "../core/common";
+import { parseFrontmatter } from "../core/frontmatter";
 /**
  * Build a FileContext from a stash root and an absolute file path.
  *
@@ -81,7 +81,7 @@ async function ensureBuiltinsRegistered() {
     if (!builtinsPromise) {
         builtinsPromise = (async () => {
             const { registerBuiltinMatchers } = await import("./matchers.js");
-            const { registerBuiltinRenderers } = await import("./renderers.js");
+            const { registerBuiltinRenderers } = await import("../output/renderers.js");
             registerBuiltinMatchers();
             registerBuiltinRenderers();
         })();

package/dist/{indexer.js → indexer/indexer.js}

@@ -1,27 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isHttpUrl, resolveStashDir } from "./common";
+import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
+import { takeWorkflowDocument } from "../workflows/document-cache";
 import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
-import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
 import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function akmIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
     const onProgress = options?.onProgress ?? (() => { });
     // Load config and resolve all stash sources
-    const { loadConfig } = await import("./config.js");
+    const { loadConfig } = await import("../core/config.js");
     const config = loadConfig();
     // Ensure git stash caches are extracted before resolving stash dirs,
     // so their content directories exist on disk for the walker to discover.
-    const { ensureStashCaches, resolveStashSources } = await import("./search-source.js");
-    await ensureStashCaches(config);
-    const allStashSources = resolveStashSources(stashDir, config);
-    const allStashDirs = allStashSources.map((s) => s.path);
+    const { ensureSourceCaches, resolveSourceEntries } = await import("./search-source.js");
+    await ensureSourceCaches(config);
+    const allSourceEntries = resolveSourceEntries(stashDir, config);
+    const allSourceDirs = allSourceEntries.map((s) => s.path);
     const t0 = Date.now();
     // Open database — pass embedding dimension from config if available
     const dbPath = getDbPath();
@@ -37,7 +38,7 @@ export async function akmIndex(options) {
             phase: "summary",
             message: buildIndexSummaryMessage({
                 mode: isIncremental ? "incremental" : "full",
-                stashSources: allStashDirs.length,
+                sourcesCount: allSourceDirs.length,
                 semanticSearchMode: config.semanticSearchMode,
                 embeddingProvider: getEmbeddingProvider(config.embedding),
                 llmEnabled: !!config.llm,
@@ -67,7 +68,7 @@ export async function akmIndex(options) {
                 catch {
                     warn("index_meta stashDirs value is corrupt JSON — treating as empty");
                 }
-                const currentSet = new Set(allStashDirs);
+                const currentSet = new Set(allSourceDirs);
                 for (const dir of prevStashDirs) {
                     if (!currentSet.has(dir)) {
                         deleteEntriesByStashDir(db, dir);
@@ -80,7 +81,7 @@ export async function akmIndex(options) {
         // doFullDelete=true merges the wipe into the same transaction as the
         // inserts so readers never see an empty database mid-rebuild.
         const doFullDelete = options?.full || !isIncremental;
-        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -130,7 +131,7 @@ export async function akmIndex(options) {
         // are read-only caches, and regenerating their indexes would mutate
         // cache content.
         try {
-            const { regenerateAllWikiIndexes } = await import("./wiki.js");
+            const { regenerateAllWikiIndexes } = await import("../wiki/wiki.js");
             regenerateAllWikiIndexes(stashDir);
         }
         catch {
@@ -142,7 +143,7 @@ export async function akmIndex(options) {
         // Update metadata
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
-        setMeta(db, "stashDirs", JSON.stringify(allStashDirs));
+        setMeta(db, "stashDirs", JSON.stringify(allSourceDirs));
         setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
         const totalEntries = getEntryCount(db);
         // Warn on every index run if using JS fallback with many entries
@@ -188,7 +189,7 @@ export async function akmIndex(options) {
     }
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
-async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete = false) {
+async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete = false) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
@@ -196,12 +197,12 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
-    for (const stashSource of allStashSources) {
-        const currentStashDir = stashSource.path;
+    for (const sourceAdded of allSourceEntries) {
+        const currentStashDir = sourceAdded.path;
         const fileContexts = walkStashFlat(currentStashDir);
         // Wiki-root stashes: all .md files are indexed as wiki pages under wikiName
-        if (stashSource.wikiName) {
-            const wikiName = stashSource.wikiName;
+        if (sourceAdded.wikiName) {
+            const wikiName = sourceAdded.wikiName;
             const wikiDirGroups = new Map();
             for (const ctx of fileContexts) {
                 if (ctx.ext !== ".md")
@@ -353,7 +354,13 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
-                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    const entryId = upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    if (entry.type === "workflow") {
+                        const doc = takeWorkflowDocument(entry);
+                        if (doc) {
+                            upsertWorkflowDocument(db, entryId, doc, fs.readFileSync(entryPath));
+                        }
+                    }
                 }
                 // Collect dirs needing LLM enhancement during the first walk
                 if (stash.entries.some((e) => e.quality === "generated")) {
@@ -428,7 +435,7 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
         setMeta(db, "hasEmbeddings", "0");
     }
     try {
-        const { embedBatch } = await import("./embedder.js");
+        const { embedBatch } = await import("../llm/embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
         if (allEntries.length === 0) {
             onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
@@ -486,10 +493,32 @@ function attachFileSize(entry, entryPath) {
         return entry;
     }
 }
+function upsertWorkflowDocument(db, entryId, doc, content) {
+    const sourceHash = computeSourceHash(content);
+    db.prepare(`INSERT INTO workflow_documents (entry_id, schema_version, document_json, source_path, source_hash, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(entry_id) DO UPDATE SET
+       schema_version = excluded.schema_version,
+       document_json = excluded.document_json,
+       source_path = excluded.source_path,
+       source_hash = excluded.source_hash,
+       updated_at = excluded.updated_at`).run(entryId, doc.schemaVersion, JSON.stringify(doc), doc.source.path, sourceHash, new Date().toISOString());
+}
+function computeSourceHash(content) {
+    // Cheap, stable identity for the source markdown — used by future
+    // incremental fast-paths that skip re-validation when content is unchanged.
+    // Not security-sensitive; FNV-1a over the bytes is sufficient.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < content.length; i++) {
+        hash ^= content[i];
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
 function buildIndexSummaryMessage(options) {
-    const stashSourceLabel = options.stashSources === 1 ? "stash source" : "stash sources";
+    const stashSourceLabel = options.sourcesCount === 1 ? "stash source" : "stash sources";
     const semanticDetail = getSemanticSearchLabel(options.semanticSearchMode, options.embeddingProvider, options.vecAvailable);
-    return `Starting ${options.mode} index (${options.stashSources} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
+    return `Starting ${options.mode} index (${options.sourcesCount} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
 }
 function getEmbeddingProvider(embedding) {
     return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
@@ -590,9 +619,8 @@ function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     return false;
 }
 async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
-    const { enhanceMetadata } = await import("./llm.js");
+    const { enhanceMetadata } = await import("../llm/metadata-enhance");
     const enhanced = [];
-    const seenSamples = new Set();
     for (const entry of stash.entries) {
         summary.attempted++;
         try {
@@ -621,10 +649,11 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
         }
         catch (err) {
             enhanced.push(entry);
-            const msg = err instanceof Error ? err.message : String(err);
-            if (summary.failureSamples.length < 3 && !seenSamples.has(msg)) {
+            const msg = toErrorMessage(err);
+            // failureSamples is bounded to 3 items, so a linear scan is cheaper
+            // than maintaining a parallel Set for membership checks (#177 review).
+            if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
                 summary.failureSamples.push(msg);
-                seenSamples.add(msg);
             }
         }
     }
@@ -667,10 +696,73 @@ export function matchEntryToFile(entryName, fileMap, files) {
     // Fallback to first file, or null if no files are available
     return files[0] || null;
 }
-// `buildSearchFields` and `buildSearchText` were previously re-exported from
-// here for backwards compatibility. Importers should now pull them directly
-// from `./search-fields` to avoid loading the indexer's full dependency
-// graph (LLM client, embedder facade) when only the text builder is needed.
+/**
+ * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
+ * reads the file from disk. The index is the source of truth for which
+ * file corresponds to which ref; the indexer walks `provider.path()` for
+ * every configured source, so this query covers all source kinds.
+ *
+ * Match rules:
+ *   - `ref.origin === undefined` → first match across all sources (primary
+ *     source first, then in declared order — same priority as the indexer's
+ *     write order).
+ *   - `ref.origin === "local"`   → primary source only (entry_key prefix is
+ *     the primary stash dir).
+ *   - `ref.origin === <name>`    → restrict to the matching source name. We
+ *     resolve the source's directory and match on `entry_key` prefix.
+ *
+ * Returns `null` when no row matches — callers translate that into a
+ * `NotFoundError` with their own messaging.
+ */
+export async function lookup(ref) {
+    const { loadConfig } = await import("../core/config.js");
+    const { resolveSourceEntries } = await import("./search-source.js");
+    const config = loadConfig();
+    const sources = resolveSourceEntries(undefined, config);
+    if (sources.length === 0)
+        return null;
+    const dbPath = getDbPath();
+    const db = openDatabase(dbPath);
+    try {
+        // entry_key shape: `${stashDir}:${type}:${name}`. Suffix-match on
+        // `:type:name` so we can scope by source dir as a prefix when origin is
+        // supplied. Use parameterised queries throughout — names may include
+        // user-supplied glob characters.
+        const escapeLike = (value) => value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+        const suffix = `:${ref.type}:${ref.name}`;
+        const escapedSuffix = escapeLike(suffix);
+        const candidateDirs = (() => {
+            if (!ref.origin)
+                return sources.map((s) => s.path);
+            if (ref.origin === "local")
+                return [sources[0].path];
+            const named = sources.find((s) => s.registryId === ref.origin);
+            return named ? [named.path] : [];
+        })();
+        if (candidateDirs.length === 0)
+            return null;
+        for (const dir of candidateDirs) {
+            const escapedDir = escapeLike(dir);
+            const row = db
+                .prepare("SELECT entry_key AS entryKey, file_path AS filePath, stash_dir AS stashDir, entry_type AS type FROM entries " +
+                "WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
+                .get(`${escapedDir}${escapedSuffix}`, ref.type);
+            if (row) {
+                return {
+                    entryKey: row.entryKey,
+                    filePath: row.filePath,
+                    stashDir: row.stashDir,
+                    type: row.type,
+                    name: ref.name,
+                };
+            }
+        }
+        return null;
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
 // ── Utility score recomputation ──────────────────────────────────────────────
 /** Retention window for usage events: events older than this are purged. */
 const USAGE_EVENT_RETENTION_DAYS = 90;

package/dist/{manifest.js → indexer/manifest.js}

@@ -8,16 +8,16 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { deriveCanonicalAssetNameFromStashRoot } from "./asset-spec";
-import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
+import { makeAssetRef } from "../core/asset-ref";
+import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
 import { closeDatabase, getAllEntries, getEntryCount, getMeta, openDatabase } from "./db";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
-import { getDbPath } from "./paths";
-import { resolveStashSources } from "./search-source";
-import { makeAssetRef } from "./stash-ref";
+import { resolveSourceEntries } from "./search-source";
 import { walkStashFlat } from "./walker";
-import { warn } from "./warn";
 const MAX_DESCRIPTION_LENGTH = 80;
 /**
  * Truncate a description string to a maximum length, appending "..." if truncated.
@@ -99,9 +99,9 @@ function getManifestFromDb(stashDir, config, sources, type) {
  * Get the manifest by walking the stash directory (fallback when no index).
  */
 async function getManifestFromWalker(sources, type) {
-    const allStashDirs = sources.map((s) => s.path);
+    const allSourceDirs = sources.map((s) => s.path);
     const entries = [];
-    for (const currentStashDir of allStashDirs) {
+    for (const currentStashDir of allSourceDirs) {
         const fileContexts = walkStashFlat(currentStashDir);
         // Group by parent directory
         const dirGroups = new Map();
@@ -154,7 +154,7 @@ export async function akmManifest(options) {
     const stashDir = options?.stashDir ?? resolveStashDir();
     const type = options?.type;
     const config = loadConfig();
-    const sources = resolveStashSources(stashDir, config);
+    const sources = resolveSourceEntries(stashDir, config);
     // Fast path: try database
     const dbEntries = getManifestFromDb(stashDir, config, sources, type);
     if (dbEntries !== null) {

package/dist/{matchers.js → indexer/matchers.js}

@@ -18,7 +18,8 @@
  * - `wikiMatcher` (20) -- classifies any `.md` under `wikis/<name>/…` as
  *   `wiki`. Registered last so the later-wins tiebreaker beats agent at 20.
  */
-import { SCRIPT_EXTENSIONS } from "./asset-spec";
+import { SCRIPT_EXTENSIONS } from "../core/asset-spec";
+import { looksLikeWorkflow } from "../workflows/parser";
 import { registerMatcher } from "./file-context";
 // ── extensionMatcher (specificity: 3) ────────────────────────────────────────
 /**
@@ -140,11 +141,7 @@ export function smartMdMatcher(ctx) {
     if (ctx.ext !== ".md")
         return null;
     const body = ctx.content();
-    const hasWorkflowSignals = /^#\s+Workflow:\s+/m.test(body) &&
-        /^##\s+Step:\s+/m.test(body) &&
-        /^Step ID:\s+/m.test(body) &&
-        /^###\s+Instructions\s*$/m.test(body);
-    if (hasWorkflowSignals) {
+    if (looksLikeWorkflow(body)) {
         return { type: "workflow", specificity: 19, renderer: "workflow-md" };
     }
     const fm = ctx.frontmatter();