akm-cli 0.2.2 → 0.3.0-rc2

package/dist/cli.js

@@ -11,16 +11,16 @@ import { ConfigError, NotFoundError, UsageError } from "./errors";
 import { akmIndex } from "./indexer";
 import { assembleInfo } from "./info";
 import { akmInit } from "./init";
-import { akmList, akmRemove, akmUpdate } from "./installed-kits";
+import { akmListSources, akmRemove, akmUpdate } from "./installed-kits";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
 import { buildRegistryIndex, writeRegistryIndex } from "./registry-build-index";
 import { searchRegistry } from "./registry-search";
 import { checkForUpdate, performUpgrade } from "./self-update";
-import { akmAdd, akmKitAdd } from "./stash-add";
+import { akmAdd } from "./stash-add";
 import { akmClone } from "./stash-clone";
 import { akmSearch, parseSearchSource } from "./stash-search";
 import { akmShowUnified } from "./stash-show";
-import { addStash, listStashes, removeStash } from "./stash-source-manage";
+import { addStash } from "./stash-source-manage";
 import { insertUsageEvent } from "./usage-events";
 import { pkgVersion } from "./version";
 import { setQuiet, warn } from "./warn";
@@ -138,6 +138,7 @@ function shapeSearchOutput(result, detail, forAgent = false) {
             source: result.source,
             hits: shapedHits,
             ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
+            ...(result.semanticSearch ? { semanticSearch: result.semanticSearch } : {}),
             ...(result.tip ? { tip: result.tip } : {}),
             ...(result.warnings ? { warnings: result.warnings } : {}),
             ...(result.timing ? { timing: result.timing } : {}),
@@ -146,8 +147,8 @@ function shapeSearchOutput(result, detail, forAgent = false) {
     return {
         hits: shapedHits,
         ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
-        ...(result.tip ? { tip: result.tip } : {}),
         ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        ...(result.tip ? { tip: result.tip } : {}),
     };
 }
 function shapeRegistrySearchOutput(result, detail) {
@@ -337,6 +338,20 @@ function formatPlain(command, result, detail) {
         case "search": {
             return formatSearchPlain(r, detail);
         }
+        case "list": {
+            const sources = Array.isArray(r.sources) ? r.sources : [];
+            if (sources.length === 0)
+                return "No sources configured. Use `akm add` to add a source.";
+            const lines = [];
+            for (const src of sources) {
+                const kind = typeof src.kind === "string" ? src.kind : "unknown";
+                const name = typeof src.name === "string" ? src.name : "unnamed";
+                const ver = typeof src.version === "string" ? ` v${src.version}` : "";
+                const prov = typeof src.provider === "string" ? ` (${src.provider})` : "";
+                lines.push(`[${kind}] ${name}${ver}${prov}`);
+            }
+            return lines.join("\n");
+        }
         case "add": {
             const index = r.index;
             const scanned = index?.directoriesScanned ?? 0;
@@ -450,11 +465,11 @@ function formatSearchPlain(r, detail) {
     return lines.join("\n").trimEnd();
 }
 /**
- * Naming Conventions:
- * - stash-*     : Operations on the user's local asset store (stash-show, stash-add, stash-clone)
+ * Module Naming:
+ * - stash-*          : Asset operations (search, show, add, clone)
  * - stash-provider-* : Runtime data source providers (filesystem, openviking)
- * - registry-*  : Kit discovery from remote registries (npm, GitHub)
- * - installed-kits : Management of kits already installed locally
+ * - registry-*       : Discovery from remote registries (npm, GitHub)
+ * - installed-kits   : Unified source operations (list, remove, update)
  */
 const setupCommand = defineCommand({
     meta: {
@@ -536,17 +551,25 @@ const searchCommand = defineCommand({
     },
 });
 const addCommand = defineCommand({
-    meta: { name: "add", description: "Install a kit from npm, GitHub, any git host, or a local directory" },
+    meta: {
+        name: "add",
+        description: "Add a source (local directory, npm package, GitHub repo, git URL, or remote provider)",
+    },
     args: {
         ref: {
             type: "positional",
-            description: "Registry ref (npm package, owner/repo, git URL, or local directory)",
+            description: "Path, URL, or registry ref (npm package, owner/repo, git URL, or local directory)",
             required: true,
         },
+        provider: { type: "string", description: "Provider type (e.g. openviking). Required for URL sources." },
+        options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
+        name: { type: "string", description: "Human-friendly name for the source" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            if (args.ref.trim() === CONTEXT_HUB_ALIAS_REF) {
+            const ref = args.ref.trim();
+            // Context-hub convenience alias
+            if (ref === CONTEXT_HUB_ALIAS_REF) {
                 const result = addStash({
                     target: CONTEXT_HUB_ALIAS_URL,
                     providerType: "context-hub",
@@ -555,24 +578,69 @@ const addCommand = defineCommand({
                 output("stash-add", result);
                 return;
             }
-            const result = await akmAdd({ ref: args.ref });
+            // URL with --provider → stash source (remote or git provider)
+            if (args.provider) {
+                if (ref.startsWith("http://")) {
+                    warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                }
+                let parsedOptions;
+                if (args.options) {
+                    try {
+                        const parsed = JSON.parse(args.options);
+                        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                            throw new UsageError("--options must be a JSON object");
+                        }
+                        parsedOptions = parsed;
+                    }
+                    catch (err) {
+                        if (err instanceof UsageError)
+                            throw err;
+                        throw new UsageError("--options must be valid JSON");
+                    }
+                }
+                const result = addStash({
+                    target: ref,
+                    name: args.name,
+                    providerType: args.provider,
+                    options: parsedOptions,
+                });
+                output("stash-add", result);
+                return;
+            }
+            const result = await akmAdd({ ref });
             output("add", result);
         });
     },
 });
+const VALID_SOURCE_KINDS = new Set(["local", "managed", "remote"]);
+function parseKindFilter(raw) {
+    if (!raw)
+        return undefined;
+    const kinds = raw.split(",").map((s) => s.trim());
+    for (const k of kinds) {
+        if (!VALID_SOURCE_KINDS.has(k)) {
+            throw new UsageError(`Invalid --kind value: "${k}". Expected one of: local, managed, remote`);
+        }
+    }
+    return kinds;
+}
 const listCommand = defineCommand({
-    meta: { name: "list", description: "List installed kits" },
-    async run() {
+    meta: { name: "list", description: "List all sources (local directories, managed packages, remote providers)" },
+    args: {
+        kind: { type: "string", description: "Filter by source kind (local, managed, remote). Comma-separated." },
+    },
+    async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await akmList();
+            const kind = parseKindFilter(args.kind);
+            const result = await akmListSources({ kind });
             output("list", result);
         });
     },
 });
 const removeCommand = defineCommand({
-    meta: { name: "remove", description: "Remove an installed kit by id or ref" },
+    meta: { name: "remove", description: "Remove a source by id, ref, path, URL, or name" },
     args: {
-        target: { type: "positional", description: "Installed target (id or ref)", required: true },
+        target: { type: "positional", description: "Source to remove (id, ref, path, URL, or name)", required: true },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -582,9 +650,9 @@ const removeCommand = defineCommand({
     },
 });
 const updateCommand = defineCommand({
-    meta: { name: "update", description: "Update one or all installed kits" },
+    meta: { name: "update", description: "Update one or all managed sources" },
     args: {
-        target: { type: "positional", description: "Installed target (id or ref)", required: false },
+        target: { type: "positional", description: "Source to update (id or ref)", required: false },
         all: { type: "boolean", description: "Update all installed entries", default: false },
         force: { type: "boolean", description: "Force fresh download even if version is unchanged", default: false },
     },
@@ -595,31 +663,6 @@ const updateCommand = defineCommand({
         });
     },
 });
-const kitAddCommand = defineCommand({
-    meta: { name: "add", description: "Install a kit from npm, GitHub, or any git host" },
-    args: {
-        ref: {
-            type: "positional",
-            description: "Registry ref (npm package, owner/repo, or git URL)",
-            required: true,
-        },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const result = await akmKitAdd({ ref: args.ref });
-            output("add", result);
-        });
-    },
-});
-const kitCommand = defineCommand({
-    meta: { name: "kit", description: "Manage installed kits" },
-    subCommands: {
-        add: kitAddCommand,
-        list: listCommand,
-        remove: removeCommand,
-        update: updateCommand,
-    },
-});
 const upgradeCommand = defineCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
     args: {
@@ -930,75 +973,6 @@ const registryCommand = defineCommand({
         }),
     },
 });
-/**
- * Subcommand definitions for managing additional stashes.
- */
-function buildSourceSubCommands(outputPrefix) {
-    return {
-        list: defineCommand({
-            meta: { name: "list", description: "List all stashes in search order" },
-            run() {
-                return runWithJsonErrors(() => {
-                    output(`${outputPrefix}`, listStashes());
-                });
-            },
-        }),
-        add: defineCommand({
-            meta: { name: "add", description: "Register an additional stash (filesystem path or remote URL)" },
-            args: {
-                target: { type: "positional", description: "Path or URL to add", required: true },
-                name: { type: "string", description: "Human-friendly name for the source" },
-                provider: { type: "string", description: "Provider type (e.g. openviking). Required for URLs." },
-                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    if (args.target.startsWith("http://")) {
-                        warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
-                    }
-                    let parsedOptions;
-                    if (args.options) {
-                        try {
-                            const parsed = JSON.parse(args.options);
-                            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                                throw new UsageError("--options must be a JSON object");
-                            }
-                            parsedOptions = parsed;
-                        }
-                        catch (err) {
-                            if (err instanceof UsageError)
-                                throw err;
-                            throw new UsageError("--options must be valid JSON");
-                        }
-                    }
-                    const result = addStash({
-                        target: args.target,
-                        name: args.name,
-                        providerType: args.provider,
-                        options: parsedOptions,
-                    });
-                    output(`${outputPrefix}-add`, result);
-                });
-            },
-        }),
-        remove: defineCommand({
-            meta: { name: "remove", description: "Remove an additional stash by URL, path, or name" },
-            args: {
-                target: { type: "positional", description: "Source URL, path, or name to remove", required: true },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    const result = removeStash(args.target);
-                    output(`${outputPrefix}-remove`, result);
-                });
-            },
-        }),
-    };
-}
-const stashCommand = defineCommand({
-    meta: { name: "stash", description: "Manage additional stashes (local directories and remote providers)" },
-    subCommands: buildSourceSubCommands("stash"),
-});
 const feedbackCommand = defineCommand({
     meta: {
         name: "feedback",
@@ -1105,12 +1079,10 @@ const main = defineCommand({
         list: listCommand,
         remove: removeCommand,
         update: updateCommand,
-        kit: kitCommand,
         upgrade: upgradeCommand,
         search: searchCommand,
         show: showCommand,
         clone: cloneCommand,
-        stash: stashCommand,
         registry: registryCommand,
         config: configCommand,
         feedback: feedbackCommand,
@@ -1160,8 +1132,8 @@ function buildHint(message) {
         return "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg`.";
     if (message.includes("Specify either <target> or --all"))
         return "Use only one: a positional target or `--all`.";
-    if (message.includes("No installed kit matched target"))
-        return "Run `akm list` to view installed ids/refs, then retry with one of those values.";
+    if (message.includes("No matching source"))
+        return "Run `akm list` to view your sources, then retry with one of those values.";
     if (message.includes("remote package fetched but asset not found"))
         return "The remote package was fetched but doesn't contain the requested asset. Check the asset name and type.";
     if (message.includes("Invalid value for --source"))
@@ -1267,17 +1239,16 @@ function loadHints(detail = "normal") {
 }
 const EMBEDDED_HINTS = `# akm CLI
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your stashes first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your sources first before writing something from scratch.
 
 ## Quick Reference
 
 \`\`\`sh
-akm search "<query>"                          # Search your stashes and installed kits
+akm search "<query>"                          # Search all sources
 akm search "<query>" --type skill             # Filter by type
-akm search "<query>" --source both            # Also search registries for installable kits
+akm search "<query>" --source both            # Also search registries
 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 add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 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
 \`\`\`
@@ -1296,14 +1267,14 @@ Run \`akm -h\` for the full command reference.
 `;
 const EMBEDDED_HINTS_FULL = `# akm CLI — Full Reference
 
-You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your stashes first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search your sources first before writing something from scratch.
 
 ## Search
 
 \`\`\`sh
-akm search "<query>"                          # Search your stashes and installed kits
+akm search "<query>"                          # Search all sources
 akm search "<query>" --type skill             # Filter by asset type
-akm search "<query>" --source both            # Also search registries for installable kits
+akm search "<query>" --source both            # Also search registries
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
 akm search "<query>" --detail full            # Include scores, paths, timing
@@ -1342,21 +1313,17 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
 | memory | \`content\` (recalled context) |
 
-## Install & Manage Kits
+## Add & Manage Sources
 
 \`\`\`sh
-akm add <ref>                                 # Install a kit (smart router: local dirs become stash adds)
-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
-akm kit update --all                          # Update all kits
-akm list                                      # List installed kits
-akm remove <target>                           # Remove by id or ref
-akm update --all                              # Update all installed kits
+akm add <ref>                                 # Add a source
+akm add @scope/kit                            # From npm (managed)
+akm add owner/repo                            # From GitHub (managed)
+akm add ./path/to/local/kit                   # Local directory
+akm list                                      # List all sources
+akm list --kind managed                       # List managed sources only
+akm remove <target>                           # Remove by id, ref, path, or name
+akm update --all                              # Update all managed sources
 akm update <target> --force                   # Force re-download
 \`\`\`
 
@@ -1404,8 +1371,7 @@ akm config path --all                         # Show all config paths
 akm init                                      # Initialize working stash
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
-akm stash                                     # List all stashes
-akm kit                                       # Kit management (add, list, remove, update)
+akm list                                      # List all sources
 akm upgrade                                   # Upgrade akm binary
 akm upgrade --check                           # Check for updates
 akm hints                                     # Print this reference

package/dist/config-cli.js

@@ -4,11 +4,16 @@ export function parseConfigValue(key, value) {
     switch (key) {
         case "stashDir":
             return { stashDir: requireNonEmptyString(value, key) };
-        case "semanticSearch":
-            if (value !== "true" && value !== "false") {
-                throw new UsageError(`Invalid value for semanticSearch: expected "true" or "false"`);
+        case "semanticSearchMode":
+            // Accept legacy boolean-style strings from CLI
+            if (value === "true")
+                return { semanticSearchMode: "auto" };
+            if (value === "false")
+                return { semanticSearchMode: "off" };
+            if (value !== "off" && value !== "auto") {
+                throw new UsageError(`Invalid value for semanticSearchMode: expected "off" or "auto"`);
             }
-            return { semanticSearch: value === "true" };
+            return { semanticSearchMode: value };
         case "embedding":
             return { embedding: parseEmbeddingConnectionValue(value) };
         case "llm":
@@ -29,8 +34,8 @@ export function getConfigValue(config, key) {
     switch (key) {
         case "stashDir":
             return config.stashDir ?? null;
-        case "semanticSearch":
-            return config.semanticSearch;
+        case "semanticSearchMode":
+            return config.semanticSearchMode;
         case "embedding":
             return config.embedding ?? null;
         case "llm":
@@ -50,7 +55,7 @@ export function getConfigValue(config, key) {
 export function setConfigValue(config, key, rawValue) {
     switch (key) {
         case "stashDir":
-        case "semanticSearch":
+        case "semanticSearchMode":
         case "embedding":
         case "llm":
         case "registries":
@@ -84,7 +89,7 @@ export function unsetConfigValue(config, key) {
 }
 export function listConfig(config) {
     const result = {
-        semanticSearch: config.semanticSearch,
+        semanticSearchMode: config.semanticSearchMode,
         registries: config.registries ?? DEFAULT_CONFIG.registries ?? [],
         output: mergeOutputConfig(DEFAULT_CONFIG.output, config.output) ?? null,
         stashDir: config.stashDir ?? null,
@@ -163,6 +168,17 @@ function parseEmbeddingConnectionValue(value) {
         endpoint: "http://localhost:11434/v1/embeddings",
         model: "nomic-embed-text",
     });
+    const localModel = typeof parsed.localModel === "string" && parsed.localModel ? parsed.localModel : undefined;
+    const endpoint = typeof parsed.endpoint === "string" ? parsed.endpoint : "";
+    if (!endpoint) {
+        if (!localModel) {
+            throw new UsageError(`Invalid value for embedding: endpoint/model are required for remote embeddings, or provide localModel`);
+        }
+        const localOnly = { endpoint: "", model: "", localModel };
+        if (typeof parsed.provider === "string" && parsed.provider)
+            localOnly.provider = parsed.provider;
+        return localOnly;
+    }
     const result = {
         endpoint: asRequiredString(parsed.endpoint, "embedding", "endpoint"),
         model: asRequiredString(parsed.model, "embedding", "model"),
@@ -173,6 +189,8 @@ function parseEmbeddingConnectionValue(value) {
         result.dimension = parseUnknownPositiveInteger(parsed.dimension, "embedding.dimension");
     if (typeof parsed.apiKey === "string" && parsed.apiKey)
         result.apiKey = parsed.apiKey;
+    if (localModel)
+        result.localModel = localModel;
     return result;
 }
 function parseLlmConnectionValue(value) {

package/dist/config.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
-    semanticSearch: true,
+    semanticSearchMode: "auto",
     registries: [
         { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" },
         { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh" },
@@ -122,8 +122,17 @@ function pickKnownKeys(raw) {
     if (typeof raw.stashDir === "string" && raw.stashDir.trim()) {
         config.stashDir = raw.stashDir.trim();
     }
-    if (typeof raw.semanticSearch === "boolean") {
-        config.semanticSearch = raw.semanticSearch;
+    // Backward compatibility: coerce legacy boolean values to string
+    if (typeof raw.semanticSearchMode === "boolean") {
+        config.semanticSearchMode = raw.semanticSearchMode ? "auto" : "off";
+    }
+    else if (raw.semanticSearchMode === "off" || raw.semanticSearchMode === "auto") {
+        config.semanticSearchMode = raw.semanticSearchMode;
+    }
+    else if (typeof raw.semanticSearch === "boolean") {
+        // Legacy config: older versions used `semanticSearch` (boolean) instead of `semanticSearchMode`
+        const legacySemanticSearch = raw.semanticSearch;
+        config.semanticSearchMode = legacySemanticSearch ? "auto" : "off";
     }
     // Migrate legacy searchPaths into stashes
     if (Array.isArray(raw.searchPaths)) {

package/dist/db.js

@@ -82,9 +82,19 @@ function ensureSchema(db, embeddingDim) {
       value TEXT NOT NULL
     );
   `);
-    // Check stored version — if it differs from DB_VERSION, drop and recreate all tables
+    // Check stored version — if it differs from DB_VERSION, drop and recreate all tables.
+    // Usage events are preserved across version upgrades so that utility score
+    // history is not silently lost.
     const storedVersion = getMeta(db, "version");
     if (storedVersion && storedVersion !== String(DB_VERSION)) {
+        // Back up usage_events before dropping tables
+        let usageBackup = [];
+        try {
+            usageBackup = db.prepare("SELECT * FROM usage_events").all();
+        }
+        catch {
+            /* table may not exist in older versions */
+        }
         db.exec("DROP TABLE IF EXISTS utility_scores");
         db.exec("DROP TABLE IF EXISTS usage_events");
         db.exec("DROP TABLE IF EXISTS embeddings");
@@ -94,6 +104,9 @@ function ensureSchema(db, embeddingDim) {
         db.exec("DROP INDEX IF EXISTS idx_entries_type");
         db.exec("DROP TABLE IF EXISTS entries");
         db.exec("DELETE FROM index_meta");
+        // Store backup for restoration after ensureUsageEventsSchema runs
+        db.__usageBackup = usageBackup;
+        console.warn("[akm] Index rebuilt due to version upgrade. Run 'akm index' to repopulate.");
     }
     db.exec(`
     CREATE TABLE IF NOT EXISTS entries (
@@ -172,6 +185,7 @@ function ensureSchema(db, embeddingDim) {
             catch {
                 /* ignore */
             }
+            setMeta(db, "hasEmbeddings", "0");
         }
         const vecExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'").get();
         if (!vecExists) {
@@ -187,8 +201,51 @@ function ensureSchema(db, embeddingDim) {
         }
         setMeta(db, "embeddingDim", String(embeddingDim));
     }
+    else {
+        // Also purge BLOB embeddings on dimension change (JS fallback path).
+        // When sqlite-vec is unavailable, entries_vec doesn't exist but the BLOB
+        // embeddings table still stores vectors. If the configured dimension
+        // changes, those stored BLOBs become silently incompatible.
+        const storedDim = getMeta(db, "embeddingDim");
+        if (storedDim && storedDim !== String(embeddingDim)) {
+            try {
+                db.exec("DELETE FROM embeddings");
+            }
+            catch {
+                /* ignore */
+            }
+            setMeta(db, "hasEmbeddings", "0");
+        }
+        setMeta(db, "embeddingDim", String(embeddingDim));
+    }
     // Usage telemetry table
     ensureUsageEventsSchema(db);
+    // Restore usage_events that were backed up during a version upgrade.
+    // Wrapped in outer try/catch because schema changes across versions may
+    // make the backup incompatible with the new table definition.
+    const dbAny = db;
+    const backup = dbAny.__usageBackup;
+    if (backup && backup.length > 0) {
+        try {
+            db.transaction(() => {
+                const cols = Object.keys(backup[0]);
+                const placeholders = cols.map(() => "?").join(", ");
+                const insert = db.prepare(`INSERT INTO usage_events (${cols.join(", ")}) VALUES (${placeholders})`);
+                for (const row of backup) {
+                    try {
+                        insert.run(...cols.map((c) => row[c]));
+                    }
+                    catch {
+                        /* skip rows that fail */
+                    }
+                }
+            })();
+        }
+        catch {
+            /* schema changed too much — discard backup gracefully */
+        }
+        delete dbAny.__usageBackup;
+    }
 }
 // ── Meta helpers ────────────────────────────────────────────────────────────
 export function getMeta(db, key) {

package/dist/embedder.js

@@ -1,4 +1,6 @@
+import path from "node:path";
 import { fetchWithTimeout, isHttpUrl } from "./common";
+import { getCacheDir } from "./paths";
 import { warn } from "./warn";
 // ── Default local model ─────────────────────────────────────────────────────
 /**
@@ -15,6 +17,8 @@ export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
 function getLocalModelName(overrideModel) {
     return overrideModel || DEFAULT_LOCAL_MODEL;
 }
+const LOCAL_EMBEDDER_DTYPE = "fp32";
+const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
 // Cache the promise itself (not the resolved result) so concurrent calls share
 // the same initialisation work and never download the model twice.
 // The cache is keyed by model name so switching models gets a fresh pipeline.
@@ -30,16 +34,25 @@ async function getLocalEmbedder(modelName) {
     if (!localEmbedderPromise) {
         localEmbedderModelName = resolvedModel;
         localEmbedderPromise = (async () => {
+            // Ensure HuggingFace model cache lives in a stable location outside
+            // node_modules so it survives package reinstalls.
+            if (!process.env.HF_HOME) {
+                process.env.HF_HOME = path.join(getCacheDir(), "models");
+            }
             let pipeline;
             try {
                 const mod = await import("@huggingface/transformers");
                 pipeline = mod.pipeline;
             }
-            catch {
-                throw new Error("Semantic search requires @huggingface/transformers. Install it with: npm install @huggingface/transformers");
+            catch (importError) {
+                const msg = importError instanceof Error ? importError.message : String(importError);
+                if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
+                    throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
+                }
+                throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
             }
             const pipelineFn = pipeline;
-            return pipelineFn("feature-extraction", resolvedModel);
+            return createLocalPipeline(pipelineFn, resolvedModel);
         })();
         // HI-13: Clear the cached promise on failure so the next call retries
         // instead of permanently rejecting every subsequent call with the same error.
@@ -50,6 +63,22 @@ async function getLocalEmbedder(modelName) {
     }
     return localEmbedderPromise;
 }
+async function createLocalPipeline(pipelineFn, modelName) {
+    try {
+        return await pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_DTYPE });
+    }
+    catch (error) {
+        if (!shouldRetryWithoutExplicitDtype(error)) {
+            throw error;
+        }
+        warn('Local embedding model "%s" rejected explicit dtype "%s"; retrying with explicit fallback dtype "%s".', modelName, LOCAL_EMBEDDER_DTYPE, LOCAL_EMBEDDER_FALLBACK_DTYPE);
+        return pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_FALLBACK_DTYPE });
+    }
+}
+function shouldRetryWithoutExplicitDtype(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /dtype|fp32|precision|quant/i.test(message);
+}
 export function resetLocalEmbedder() {
     localEmbedderPromise = undefined;
     localEmbedderModelName = undefined;