akm-cli 0.2.0 → 0.2.1

package/dist/cli.js

@@ -283,7 +283,13 @@ function formatPlain(command, result, detail) {
             return out;
         }
         case "index": {
-            return `Indexed ${r.totalEntries ?? 0} entries from ${r.directoriesScanned ?? 0} directories (mode: ${r.mode ?? "unknown"})`;
+            const indexResult = result;
+            let out = `Indexed ${indexResult.totalEntries ?? 0} entries from ${indexResult.directoriesScanned ?? 0} directories (mode: ${indexResult.mode ?? "unknown"})`;
+            const verification = indexResult.verification;
+            if (verification?.ok === false && verification.message) {
+                out += `\nVerification: ${String(verification.message)}`;
+            }
+            return out;
         }
         case "show": {
             const lines = [];
@@ -481,10 +487,14 @@ const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
         full: { type: "boolean", description: "Force full reindex", default: false },
+        verbose: { type: "boolean", description: "Print indexing summary and phase progress to stderr", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await akmIndex({ full: args.full });
+            const result = await akmIndex({
+                full: args.full,
+                onProgress: args.verbose ? ({ message }) => console.error(`[index] ${message}`) : undefined,
+            });
             output("index", result);
         });
     },

package/dist/common.js

@@ -5,6 +5,9 @@ import { ConfigError } from "./errors";
 import { getConfigPath, getDefaultStashDir } from "./paths";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
+export function isHttpUrl(value) {
+    return !!value && /^https?:\/\//.test(value);
+}
 // ── Validators ──────────────────────────────────────────────────────────────
 export function isAssetType(type) {
     return Object.hasOwn(TYPE_DIRS, type);

package/dist/config.js

@@ -460,7 +460,7 @@ function parseRegistryConfigEntry(value) {
         return undefined;
     const obj = value;
     const url = asNonEmptyString(obj.url);
-    if (!url || !url.startsWith("http"))
+    if (!url?.startsWith("http"))
         return undefined;
     const entry = { url };
     const name = asNonEmptyString(obj.name);

package/dist/db.js

@@ -535,6 +535,10 @@ export function getEntryCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
     return row.cnt;
 }
+export function getEmbeddingCount(db) {
+    const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
+    return row.cnt;
+}
 export function getEntryById(db, id) {
     const row = db.prepare("SELECT file_path, entry_json FROM entries WHERE id = ?").get(id);
     if (!row)

package/dist/embedder.js

@@ -1,4 +1,4 @@
-import { fetchWithTimeout } from "./common";
+import { fetchWithTimeout, isHttpUrl } from "./common";
 import { warn } from "./warn";
 // ── Default local model ─────────────────────────────────────────────────────
 /**
@@ -32,11 +32,11 @@ async function getLocalEmbedder(modelName) {
         localEmbedderPromise = (async () => {
             let pipeline;
             try {
-                const mod = await import("@xenova/transformers");
+                const mod = await import("@huggingface/transformers");
                 pipeline = mod.pipeline;
             }
             catch {
-                throw new Error("Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers");
+                throw new Error("Semantic search requires @huggingface/transformers. Install it with: npm install @huggingface/transformers");
             }
             const pipelineFn = pipeline;
             return pipelineFn("feature-extraction", resolvedModel);
@@ -103,7 +103,7 @@ async function embedRemote(text, config) {
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
 function hasRemoteEndpoint(config) {
-    return !!config.endpoint && (config.endpoint.startsWith("http://") || config.endpoint.startsWith("https://"));
+    return isHttpUrl(config.endpoint);
 }
 // ── LRU embedding cache ─────────────────────────────────────────────────────
 // Caches query embeddings to avoid redundant computation for repeated queries.
@@ -133,7 +133,7 @@ export function clearEmbeddingCache() {
 /**
  * Generate an embedding for the given text.
  * If embeddingConfig has a remote endpoint, uses the configured OpenAI-compatible endpoint.
- * Otherwise falls back to local @xenova/transformers using the model from
+ * Otherwise falls back to local @huggingface/transformers using the model from
  * `embeddingConfig.localModel` or `DEFAULT_LOCAL_MODEL`.
  *
  * Results are cached in an LRU cache (max ~100 entries) keyed by query text
@@ -244,21 +244,57 @@ export function cosineSimilarity(a, b) {
     return denom === 0 ? 0 : dot / denom;
 }
 // ── Availability check ──────────────────────────────────────────────────────
-export async function isEmbeddingAvailable(embeddingConfig) {
+/**
+ * Check whether the `@huggingface/transformers` package can be imported.
+ * Returns `true` if it can, `false` otherwise.
+ */
+export async function isTransformersAvailable() {
+    try {
+        await import("@huggingface/transformers");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether embedding is available with a detailed reason on failure.
+ */
+export async function checkEmbeddingAvailability(embeddingConfig) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         try {
             await embedRemote("test", embeddingConfig);
-            return true;
+            return { available: true };
         }
-        catch {
-            return false;
+        catch (err) {
+            return {
+                available: false,
+                reason: "remote-unreachable",
+                message: err instanceof Error ? err.message : String(err),
+            };
         }
     }
+    // Check if the package is importable before attempting the model download.
+    if (!(await isTransformersAvailable())) {
+        return {
+            available: false,
+            reason: "missing-package",
+            message: "@huggingface/transformers is not installed.",
+        };
+    }
     try {
         await getLocalEmbedder(embeddingConfig?.localModel);
-        return true;
+        return { available: true };
     }
-    catch {
-        return false;
+    catch (err) {
+        return {
+            available: false,
+            reason: "model-download-failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
     }
 }
+export async function isEmbeddingAvailable(embeddingConfig) {
+    const result = await checkEmbeddingAvailability(embeddingConfig);
+    return result.available;
+}

package/dist/indexer.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "./common";
-import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
+import { isHttpUrl, resolveStashDir } from "./common";
+import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
@@ -11,6 +11,7 @@ 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 config = loadConfig();
@@ -30,6 +31,17 @@ export async function akmIndex(options) {
         const prevBuiltAt = getMeta(db, "builtAt");
         const isIncremental = !options?.full && prevStashDir === stashDir && !!prevBuiltAt;
         const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
+        onProgress({
+            phase: "summary",
+            message: buildIndexSummaryMessage({
+                mode: isIncremental ? "incremental" : "full",
+                stashSources: allStashDirs.length,
+                semanticSearch: config.semanticSearch,
+                embeddingProvider: getEmbeddingProvider(config.embedding),
+                llmEnabled: !!config.llm,
+                vecAvailable: isVecAvailable(db),
+            }),
+        });
         if (options?.full || !isIncremental) {
             // The delete is now merged into the insert transaction inside
             // indexEntries() so that a reader never sees an empty database between
@@ -67,17 +79,28 @@ export async function akmIndex(options) {
         // inserts so readers never see an empty database mid-rebuild.
         const doFullDelete = options?.full || !isIncremental;
         const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = await indexEntries(db, allStashDirs, isIncremental, builtAtMs, doFullDelete);
+        onProgress({
+            phase: "scan",
+            message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
+        });
         const tWalkEnd = Date.now();
         // Enhance entries with LLM if configured
         await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
+        onProgress({
+            phase: "llm",
+            message: config.llm
+                ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
+                : "LLM enhancement disabled.",
+        });
         const tLlmEnd = Date.now();
         // Rebuild FTS after all inserts
         rebuildFts(db);
+        onProgress({ phase: "fts", message: "Rebuilt full-text search index." });
         const tFtsEnd = Date.now();
         // Recompute utility scores from usage_events after FTS rebuild
         recomputeUtilityScores(db);
         // Generate embeddings if semantic search is enabled
-        const hasEmbeddings = await generateEmbeddingsForDb(db, config);
+        const hasEmbeddings = await generateEmbeddingsForDb(db, config, onProgress);
         const tEmbedEnd = Date.now();
         // Update metadata
         setMeta(db, "builtAt", new Date().toISOString());
@@ -88,6 +111,8 @@ export async function akmIndex(options) {
         // Warn on every index run if using JS fallback with many entries
         warnIfVecMissing(db);
         const tEnd = Date.now();
+        const verification = verifyIndexState(db, config, totalEntries);
+        onProgress({ phase: "verify", message: verification.message });
         return {
             stashDir,
             totalEntries,
@@ -96,6 +121,7 @@ export async function akmIndex(options) {
             mode: isIncremental ? "incremental" : "full",
             directoriesScanned: scannedDirs,
             directoriesSkipped: skippedDirs,
+            verification,
             timing: {
                 totalMs: tEnd - t0,
                 walkMs: tWalkEnd - tWalkStart,
@@ -256,14 +282,22 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
         })();
     }
 }
-async function generateEmbeddingsForDb(db, config) {
-    if (!config.semanticSearch)
+async function generateEmbeddingsForDb(db, config, onProgress) {
+    if (!config.semanticSearch) {
+        onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
         return false;
+    }
     try {
         const { embedBatch } = await import("./embedder.js");
         const allEntries = getAllEntriesForEmbedding(db);
-        if (allEntries.length === 0)
+        if (allEntries.length === 0) {
+            onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
             return true;
+        }
+        onProgress({
+            phase: "embeddings",
+            message: `Generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}.`,
+        });
         const texts = allEntries.map((e) => e.searchText);
         const embeddings = await embedBatch(texts, config.embedding);
         // Wrap all embedding upserts in a single transaction so partial
@@ -273,10 +307,18 @@ async function generateEmbeddingsForDb(db, config) {
                 upsertEmbedding(db, allEntries[i].id, embeddings[i]);
             }
         })();
+        onProgress({
+            phase: "embeddings",
+            message: `Stored ${embeddings.length} embedding${embeddings.length === 1 ? "" : "s"}.`,
+        });
         return true;
     }
     catch (error) {
         warn("Embedding generation failed, continuing without:", error instanceof Error ? error.message : String(error));
+        onProgress({
+            phase: "embeddings",
+            message: `Embedding generation failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
         return false;
     }
 }
@@ -297,6 +339,69 @@ function attachFileSize(entry, entryPath) {
         return entry;
     }
 }
+function buildIndexSummaryMessage(options) {
+    const stashSourceLabel = options.stashSources === 1 ? "stash source" : "stash sources";
+    const semanticDetail = getSemanticSearchLabel(options.semanticSearch, options.embeddingProvider, options.vecAvailable);
+    return `Starting ${options.mode} index (${options.stashSources} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
+}
+function getEmbeddingProvider(embedding) {
+    return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
+}
+function getSemanticSearchLabel(semanticSearch, embeddingProvider, vecAvailable) {
+    if (!semanticSearch)
+        return "disabled";
+    return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
+}
+function verifyIndexState(db, config, totalEntries) {
+    const embeddingCount = getEmbeddingCount(db);
+    const vecAvailable = isVecAvailable(db);
+    const embeddingProvider = getEmbeddingProvider(config.embedding);
+    if (totalEntries === 0) {
+        return {
+            ok: true,
+            message: "Index ready. No assets were found yet.",
+            semanticSearchEnabled: config.semanticSearch,
+            embeddingProvider,
+            entryCount: totalEntries,
+            embeddingCount,
+            vecAvailable,
+        };
+    }
+    if (!config.semanticSearch) {
+        return {
+            ok: true,
+            message: "Keyword index ready. Semantic search is disabled.",
+            semanticSearchEnabled: false,
+            embeddingProvider,
+            entryCount: totalEntries,
+            embeddingCount,
+            vecAvailable,
+        };
+    }
+    if (embeddingCount >= totalEntries) {
+        return {
+            ok: true,
+            message: `Semantic search ready (${embeddingCount}/${totalEntries} embeddings, ${vecAvailable ? "sqlite-vec active" : "JS fallback active"}).`,
+            semanticSearchEnabled: true,
+            embeddingProvider,
+            entryCount: totalEntries,
+            embeddingCount,
+            vecAvailable,
+        };
+    }
+    return {
+        ok: false,
+        message: `Semantic search verification failed (${embeddingCount}/${totalEntries} embeddings available).`,
+        guidance: embeddingProvider === "remote"
+            ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
+            : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/configuration.md for local embedding dependency setup.",
+        semanticSearchEnabled: true,
+        embeddingProvider,
+        entryCount: totalEntries,
+        embeddingCount,
+        vecAvailable,
+    };
+}
 function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     // Check if file set changed (additions or deletions)
     const prevFileNames = new Set(previousEntries.map((ie) => ie.entry.filename).filter((e) => !!e));

package/dist/renderers.js

@@ -399,4 +399,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { skillMdRenderer, commandMdRenderer, agentMdRenderer, knowledgeMdRenderer, memoryMdRenderer, scriptSourceRenderer, INTERPRETER_MAP, SETUP_SIGNALS, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, };

package/dist/setup.js

@@ -6,8 +6,11 @@
  * Collects all choices and writes config once at the end.
  */
 import * as p from "@clack/prompts";
+import { isHttpUrl } from "./common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
+import { closeDatabase, isVecAvailable, openDatabase } from "./db";
 import { detectAgentPlatforms, detectOllama, detectOpenViking } from "./detect";
+import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedder";
 import { akmIndex } from "./indexer";
 import { akmInit } from "./init";
 import { getDefaultStashDir } from "./paths";
@@ -20,6 +23,11 @@ const RECOMMENDED_GITHUB_REPOS = [
         hint: "community knowledge",
     },
 ];
+// Approximate first-download sizes used in the setup note.
+// LOCAL_MODEL_APPROX_SIZE_MB tracks the default local model (DEFAULT_LOCAL_MODEL).
+const LOCAL_MODEL_APPROX_SIZE_MB = 130;
+// SQLITE_VEC_APPROX_SIZE_MB reflects the optional sqlite-vec install footprint.
+const SQLITE_VEC_APPROX_SIZE_MB = 5;
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function bail() {
     p.cancel("Setup cancelled. No changes were saved.");
@@ -70,6 +78,112 @@ async function promptOrBack(fn) {
         return null;
     return result;
 }
+function isRemoteEmbeddingConfig(embedding) {
+    return isHttpUrl(embedding?.endpoint);
+}
+/**
+ * @internal Exported for testing only.
+ */
+export function describeSemanticSearchAssets(embedding) {
+    if (isRemoteEmbeddingConfig(embedding)) {
+        return [
+            `• Embedding endpoint: ${embedding?.provider ?? "custom"} / ${embedding?.model} (no local model download)`,
+            `• sqlite-vec acceleration: optional native extension (~${SQLITE_VEC_APPROX_SIZE_MB} MB when installed separately)`,
+        ];
+    }
+    return [
+        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download on first use)`,
+        `• sqlite-vec acceleration: optional native extension (~${SQLITE_VEC_APPROX_SIZE_MB} MB when installed separately)`,
+    ];
+}
+export async function stepSemanticSearch(current, embedding) {
+    const enabled = await prompt(() => p.confirm({
+        message: "Enable semantic search?",
+        initialValue: current.semanticSearch,
+    }));
+    if (!enabled) {
+        return { enabled: false, prepareAssets: false };
+    }
+    p.note(describeSemanticSearchAssets(embedding).join("\n"), "Semantic Search Assets");
+    const prepareAssets = await prompt(() => p.confirm({
+        message: isRemoteEmbeddingConfig(embedding)
+            ? "Check the embedding endpoint and verify semantic search now?"
+            : "Download and verify semantic-search assets now?",
+        initialValue: true,
+    }));
+    return { enabled: true, prepareAssets };
+}
+async function prepareSemanticSearchAssets(config) {
+    const remote = isRemoteEmbeddingConfig(config.embedding);
+    // For local embeddings, ensure the required package is installed first.
+    if (!remote) {
+        if (!(await isTransformersAvailable())) {
+            const spin = p.spinner();
+            spin.start("Installing @huggingface/transformers...");
+            try {
+                const proc = Bun.spawn(["bun", "add", "@huggingface/transformers"], {
+                    stdout: "pipe",
+                    stderr: "pipe",
+                });
+                await proc.exited;
+                if (proc.exitCode !== 0) {
+                    const stderr = await new Response(proc.stderr).text();
+                    throw new Error(stderr || `exit code ${proc.exitCode}`);
+                }
+                spin.stop("@huggingface/transformers installed.");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                spin.stop("Could not install @huggingface/transformers.");
+                p.log.warn(`Automatic install failed: ${msg}\n` +
+                    "Install it manually with: bun add @huggingface/transformers\n" +
+                    "Then re-run `akm setup` or `akm index --full --verbose`.");
+                return false;
+            }
+        }
+    }
+    const spin = p.spinner();
+    spin.start(remote
+        ? "Checking remote embedding endpoint..."
+        : `Downloading local embedding model (${config.embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
+    const result = await checkEmbeddingAvailability(config.embedding);
+    if (!result.available) {
+        spin.stop("Semantic-search assets could not be prepared.");
+        if (result.reason === "remote-unreachable") {
+            p.log.warn("The remote embedding endpoint is not reachable. Check your endpoint and credentials, then retry `akm index --full --verbose`.");
+        }
+        else if (result.reason === "missing-package") {
+            p.log.warn("@huggingface/transformers is not installed. Install it with: bun add @huggingface/transformers\n" +
+                "Then re-run `akm setup` or `akm index --full --verbose`.");
+        }
+        else {
+            p.log.warn(`The local embedding model could not be downloaded: ${result.message}\n` +
+                "Retry `akm index --full --verbose` after confirming local model downloads are permitted.");
+        }
+        return false;
+    }
+    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
+    let db;
+    try {
+        db = openDatabase();
+        if (isVecAvailable(db)) {
+            p.log.info("sqlite-vec is available for fast vector search.");
+        }
+        else {
+            p.log.info("sqlite-vec is not available. Semantic search will use the JS fallback until the optional extension is installed.");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        p.log.warn(`Could not open the local database or check for sqlite-vec. Semantic search will use the JS fallback. (${message})\n` +
+            "Check file permissions and available disk space in the cache directory, or run `akm index --full --verbose` to diagnose.");
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    return true;
+}
 // ── Steps ───────────────────────────────────────────────────────────────────
 async function stepStashDir(current) {
     const defaultDir = current.stashDir ?? getDefaultStashDir();
@@ -431,14 +545,17 @@ export async function runSetupWizard() {
     // Step 2: Ollama / Embedding / LLM
     p.log.step("Step 2: Embedding & LLM");
     const { embedding, llm } = await stepOllama(current);
-    // Step 3: Registries
-    p.log.step("Step 3: Registries");
+    // Step 3: Semantic search assets
+    p.log.step("Step 3: Semantic Search");
+    const semanticSearch = await stepSemanticSearch(current, embedding);
+    // Step 4: Registries
+    p.log.step("Step 4: Registries");
     const registries = await stepRegistries(current);
-    // Step 4: Stash sources
-    p.log.step("Step 4: Stash Sources");
+    // Step 5: Stash sources
+    p.log.step("Step 5: Stash Sources");
     const stashes = await stepStashSources(current);
-    // Step 5: Agent platform detection
-    p.log.step("Step 5: Agent Platform Detection");
+    // Step 6: Agent platform detection
+    p.log.step("Step 6: Agent Platform Detection");
     const platformStashes = await stepAgentPlatforms(current);
     // Merge platform stashes into main stashes list
     const allStashes = [...stashes];
@@ -456,7 +573,7 @@ export async function runSetupWizard() {
         registries,
         stashes: allStashes.length > 0 ? allStashes : undefined,
         // Preserve existing fields
-        semanticSearch: current.semanticSearch,
+        semanticSearch: semanticSearch.enabled,
         installed: current.installed,
         output: current.output,
     };
@@ -466,6 +583,7 @@ export async function runSetupWizard() {
         `Stash directory:  ${stashDir}`,
         `Embedding:        ${embedding ? `${embedding.provider ?? "remote"} / ${embedding.model}` : "built-in local"}`,
         `LLM:              ${llm ? `${llm.provider ?? "remote"} / ${llm.model}` : "disabled"}`,
+        `Semantic search:  ${semanticSearch.enabled ? "enabled" : "disabled"}`,
         `Registries:       ${effectiveRegistries.filter((r) => r.enabled !== false).length} enabled`,
         `Stash sources:    ${allStashes.length}`,
     ].join("\n"), "Configuration Summary");
@@ -479,12 +597,38 @@ export async function runSetupWizard() {
     saveConfig(newConfig);
     // Initialize stash directory
     await akmInit({ dir: stashDir });
+    if (semanticSearch.enabled) {
+        if (semanticSearch.prepareAssets) {
+            const ready = await prepareSemanticSearchAssets(newConfig);
+            if (!ready) {
+                // Asset preparation failed: disable semantic search and persist the update.
+                newConfig.semanticSearch = false;
+                saveConfig(newConfig);
+                p.log.warn("Semantic search has been disabled in the saved configuration. Re-run `akm setup` or `akm index --full --verbose` once the issue is resolved.");
+            }
+        }
+        else {
+            p.log.info("Semantic search will be enabled, but asset preparation was skipped. Run `akm index --full --verbose` later to verify it.");
+        }
+    }
     // Build search index
+    p.log.info("Building search index...");
     const spin = p.spinner();
     spin.start("Building search index...");
     try {
         const indexResult = await akmIndex({ stashDir });
         spin.stop(`Indexed ${indexResult.totalEntries} assets.`);
+        if (newConfig.semanticSearch) {
+            if (indexResult.verification.ok) {
+                p.log.success(indexResult.verification.message);
+            }
+            else {
+                p.log.warn(indexResult.verification.message);
+                if (indexResult.verification.guidance) {
+                    p.log.info(indexResult.verification.guidance);
+                }
+            }
+        }
     }
     catch (err) {
         spin.stop("Indexing failed — you can run `akm index` manually later.");

package/dist/stash-providers/git.js

@@ -137,4 +137,4 @@ function parseGitRepoUrl(rawUrl) {
     };
 }
 // ── Exports ─────────────────────────────────────────────────────────────────
-export { GitStashProvider, ensureGitMirror, getCachePaths, parseGitRepoUrl };
+export { ensureGitMirror, GitStashProvider, getCachePaths, parseGitRepoUrl };

package/dist/stash-providers/openviking.js

@@ -345,4 +345,4 @@ function inferTypeFromUri(uri) {
     return OV_TYPE_MAP[firstSegment] ?? "knowledge";
 }
 // ── Exports for testing ─────────────────────────────────────────────────────
-export { OpenVikingStashProvider, refToVikingUri, parseOVSearchResponse };
+export { OpenVikingStashProvider, parseOVSearchResponse, refToVikingUri };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [
@@ -51,7 +51,6 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0",
     "sqlite-vec": "0.1.7-alpha.2"
   },
   "engines": {
@@ -59,6 +58,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
+    "@huggingface/transformers": "^3.8.1",
     "citty": "^0.2.1",
     "yaml": "^2.8.2"
   }