akm-cli 0.2.0 → 0.2.2

package/LICENSE

@@ -2,7 +2,6 @@ Mozilla Public License Version 2.0
 ==================================
 
 1. Definitions
-
 --------------
 
 1.1. "Contributor"
@@ -84,8 +83,7 @@ Mozilla Public License Version 2.0
     fifty percent (50%) of the outstanding shares or beneficial
     ownership of such entity.
 
-1. License Grants and Conditions
-
+2. License Grants and Conditions
 --------------------------------
 
 2.1. Grants
@@ -156,8 +154,7 @@ equivalents.
 Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
 in Section 2.1.
 
-1. Responsibilities
-
+3. Responsibilities
 -------------------
 
 3.1. Distribution of Source Form
@@ -219,8 +216,7 @@ indemnity or liability terms You offer. You may include additional
 disclaimers of warranty and limitations of liability specific to any
 jurisdiction.
 
-1. Inability to Comply Due to Statute or Regulation
-
+4. Inability to Comply Due to Statute or Regulation
 ---------------------------------------------------
 
 If it is impossible for You to comply with any of the terms of this
@@ -229,12 +225,12 @@ statute, judicial order, or regulation then You must: (a) comply with
 the terms of this License to the maximum extent possible; and (b)
 describe the limitations and the code they affect. Such description must
 be placed in a text file included with all distributions of the Covered
-Software under this License. Except to the extent prohibited by statute
-or regulation, such description must be sufficiently detailed for a
-recipient of ordinary skill to be able to understand it.
-
-1. Termination
+Software under the name "LEGAL", with additions for new restrictions
+placed at the end of the file. Except to the extent prohibited by
+statute or regulation, such description must be sufficiently detailed
+for a recipient of ordinary skill to be able to understand it.
 
+5. Termination
 --------------
 
 5.1. The rights granted under this License will terminate automatically
@@ -264,53 +260,48 @@ have been validly granted by You or Your distributors under this License
 prior to termination shall survive termination.
 
 ************************************************************************
-
 *                                                                      *
-* 1. Disclaimer of Warranty                                           *
-* -------------------------                                           *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
 *                                                                      *
-* Covered Software is provided under this License on an "as is"       *
-* basis, without warranty of any kind, either expressed, implied, or  *
-* statutory, including, without limitation, warranties that the       *
-* Covered Software is free of defects, merchantable, fit for a        *
-* particular purpose or non-infringing. The entire risk as to the     *
-* quality and performance of the Covered Software is with You.        *
-* Should any Covered Software prove defective in any respect, You     *
-* (not any Contributor) assume the cost of any necessary servicing,   *
-* repair, or correction. This disclaimer of warranty constitutes an   *
-* essential part of this License. No use of any Covered Software is   *
-* authorized under this License except under this disclaimer.         *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
 *                                                                      *
-
 ************************************************************************
 
 ************************************************************************
-
 *                                                                      *
-* 1. Limitation of Liability                                          *
-* --------------------------                                          *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
 *                                                                      *
-* Under no circumstances and under no legal theory, whether tort      *
-* (including negligence), contract, or otherwise, shall any           *
-* Contributor, or anyone who distributes Covered Software as          *
-* permitted above, be liable to You for any direct, indirect,         *
-* special, incidental, or consequential damages of any character      *
-* including, without limitation, damages for lost profits, loss of    *
-* goodwill, work stoppage, computer failure or malfunction, or any    *
-* and all other commercial damages or losses, even if such party      *
-* shall have been informed of the possibility of such damages. This   *
-* limitation of liability shall not apply to liability for death or   *
-* personal injury resulting from such party's negligence to the       *
-* extent applicable law prohibits such limitation. Some               *
-* jurisdictions do not allow the exclusion or limitation of           *
-* incidental or consequential damages, so this exclusion and          *
-* limitation may not apply to You.                                    *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
 *                                                                      *
-
 ************************************************************************
 
-1. Litigation
-
+8. Litigation
 -------------
 
 Any litigation relating to this License may be brought only in the
@@ -320,8 +311,7 @@ jurisdiction, without reference to its conflict-of-law provisions.
 Nothing in this Section shall prevent a party's ability to bring
 cross-claims or counter-claims.
 
-1. Miscellaneous
-
+9. Miscellaneous
 ----------------
 
 This License represents the complete agreement concerning the subject
@@ -331,8 +321,7 @@ necessary to make it enforceable. Any law or regulation which provides
 that the language of a contract shall be construed against the drafter
 shall not be used to construe this License against a Contributor.
 
-1. Versions of the License
-
+10. Versions of the License
 ---------------------------
 
 10.1. New Versions
@@ -369,7 +358,7 @@ Exhibit A - Source Code Form License Notice
 
   This Source Code Form is subject to the terms of the Mozilla Public
   License, v. 2.0. If a copy of the MPL was not distributed with this
-  file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 If it is not possible or desirable to put the notice in a particular
 file, then You may include the notice in a location (such as a LICENSE

package/README.md

@@ -1,112 +1,53 @@
-# Agent Kit Manager
+# akm -- Agent Kit Manager
 
-> **akm** — Agent Kit Manager
+> **akm** (Agent Kit Manager) -- A package manager for AI agent skills, commands, tools, and knowledge.
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
-[![CI](https://github.com/itlackey/agentikit/actions/workflows/ci.yml/badge.svg)](https://github.com/itlackey/agentikit/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/akm-cli)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/akm-cli)](https://www.npmjs.com/package/akm-cli)
+[![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
-A package manager for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, and memories -- that works with any AI coding assistant that
-can run shell commands.
+`akm` is a package manager for AI agent capabilities -- scripts, skills, commands,
+agents, knowledge, and memories. It works with any AI coding assistant that can
+run shell commands, including [Claude Code](https://claude.ai/code),
+[OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
 ## Install
 
 ```sh
-# Standalone binary (no runtime dependencies)
-curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
-
-# Or via Bun
 bun install -g akm-cli
 ```
 
-Upgrade in place with `akm upgrade`.
+Requires [Bun](https://bun.sh) runtime. Upgrade in place with `akm upgrade`.
 
 ## Quick Start
 
 ```sh
 akm setup                         # Guided setup: configure, initialize, and index
 akm add github:owner/repo         # Add a kit from GitHub
-akm search "deploy"               # Find assets
+akm search "deploy"               # Find assets across all sources
 akm show script:deploy.sh         # View details and run command
 ```
 
-If you want to skip the wizard, `akm init --dir ~/custom-stash` initializes the
-working stash at a custom path.
+## Why akm?
 
-## Features
+- **Works with any AI agent** -- No plugins or SDKs required. Any model that can run shell commands can use `akm`.
+- **One command to search everything** -- Local stash, registries, and community skills from [skills.sh](https://skills.sh) in a single query.
+- **Install kits from anywhere** -- npm, GitHub, GitLab, local directories.
+- **Semantic search** -- Optional local embeddings (via Ollama or HuggingFace) for finding assets by meaning, not just keywords.
+- **Private registries** -- Host your own registry for team or enterprise use.
 
-### Works with Any AI Agent
+## Agent Integration
 
-Any model that can run shell commands can use `akm`. Add this to your
-`AGENTS.md`, `CLAUDE.md`, or system prompt:
+Add this to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 
-~~~markdown
+```markdown
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
 knowledge, and memories via the `akm` CLI. Use `akm -h` for details.
-~~~
-
-No plugins, SDKs, or integration code required. Platform-specific plugins
-(e.g., [OpenCode](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode))
-are available for tighter integration but purely optional.
-
-### Clone Assets Anywhere
-
-`akm clone` copies any asset from your stash or a remote source into a
-target directory for local editing:
-
-```sh
-akm clone script:deploy.sh                              # Clone to your stash
-akm clone script:deploy.sh --dest ./project/.claude     # Clone to a specific directory
-akm clone script:deploy.sh --name my-deploy.sh          # Clone with a new name
-akm clone "npm:@scope/pkg//script:deploy.sh" --force    # Clone from a remote package
-```
-
-Key behaviors:
-- Type subdirectories are appended automatically (e.g., `--dest ./project/.claude` becomes `./project/.claude/scripts/deploy.sh`)
-- Skills clone as entire directories; scripts/commands clone as single files
-- Remote packages are fetched on-demand without registering as installed kits
-- `--force` overwrites existing assets
-
-### skills.sh Integration
-
-`akm` includes [skills.sh](https://skills.sh) as a built-in registry. Community
-skills from skills.sh are searchable out of the box alongside the official
-registry -- no setup required:
-
-```sh
-akm search "code review"             # Searches skills.sh and official registry
-akm registry search "code review"    # Search registries directly
 ```
 
-Results include install counts and link back to skills.sh for details. The
-provider caches queries for 15 minutes with a 24-hour stale fallback.
-
-### Registries and Private Registry Support
-
-Registries are indexes of available kits. The official
-[akm-registry](https://github.com/itlackey/akm-registry) is pre-configured.
-
-```sh
-akm registry search "code review"                                        # Search registries
-akm registry add https://example.com/registry/index.json --name team     # Add a registry
-akm stash add http://host:1933 --provider openviking \
-  --options '{"apiKey":"key"}'                                            # Add an OpenViking stash source
-akm registry list                                                        # List configured registries
-akm show viking://resources/my-doc                                       # Fetch remote content from OpenViking
-```
-
-Private access is supported through:
-- **GitHub tokens** -- Set `GITHUB_TOKEN` to access private GitHub repos when installing kits
-- **Provider options** -- `--options` flag accepts JSON for provider-specific configuration (API keys, custom headers)
-- **Pluggable providers** -- Built-in registry providers include `static-index` and `skills-sh`; stash providers include `filesystem` and `openviking`; custom providers can implement their own authentication
-
-See the [Registry docs](docs/registry.md) for hosting your own registry and
-the v2 index format.
-
-### Install Kits from Anywhere
+## Install Kits from Anywhere
 
 ```sh
 akm add @scope/my-kit                       # npm
@@ -117,26 +58,23 @@ akm add ./path/to/local/kit                 # Local directory
 
 Manage kits with `akm list`, `akm update --all`, and `akm remove`.
 
-### Publish Your Own Kit
+## Publish Your Own Kit
 
 1. Organize your assets into a directory
-2. Add `"akm"` to `keywords` in `package.json` or the `akm` topic to your GitHub repo
+2. Add `"akm"` to `keywords` in `package.json`
 3. Optionally add `akm.include` in `package.json` to control what gets installed
 4. Publish to npm or push to GitHub
 
-See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
-
 ## Documentation
 
-| Doc | Description |
-| --- | --- |
-| [Getting Started](docs/getting-started.md) | Quick setup guide |
-| [CLI Reference](docs/cli.md) | All commands and flags |
-| [Configuration](docs/configuration.md) | Settings, providers, and Ollama setup |
-| [Concepts](docs/concepts.md) | Stashes, kits, registries, asset types |
-| [Kit Maker's Guide](docs/kit-makers.md) | Build and share kits |
-| [Registry](docs/registry.md) | Registries, search, and the v2 index format |
+Full docs, CLI reference, and guides are available on [GitHub](https://github.com/itlackey/akm):
+
+- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/getting-started.md)
+- [CLI Reference](https://github.com/itlackey/akm/blob/main/docs/cli.md)
+- [Configuration](https://github.com/itlackey/akm/blob/main/docs/configuration.md)
+- [Kit Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/kit-makers.md)
+- [Registry](https://github.com/itlackey/akm/blob/main/docs/registry.md)
 
 ## License
 
-[MPL-2.0](LICENSE)
+[MPL-2.0](https://github.com/itlackey/akm/blob/main/LICENSE)

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

@@ -46,7 +46,7 @@ function loadVecExtension(db) {
 export function isVecAvailable(db) {
     return vecStatus.get(db) ?? false;
 }
-const VEC_DOCS_URL = "https://github.com/itlackey/agentikit/blob/main/docs/configuration.md#sqlite-vec-extension";
+const VEC_DOCS_URL = "https://github.com/itlackey/akm/blob/main/docs/configuration.md#sqlite-vec-extension";
 const VEC_FALLBACK_THRESHOLD = 10_000;
 // Per-database warning state: tracks which databases have already emitted the
 // vec-missing warning so we don't spam on every openDatabase() call.
@@ -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/registry-build-index.js

@@ -13,7 +13,7 @@ const DEFAULT_MANUAL_ENTRIES_PATH = path.resolve("manual-entries.json");
 const DEFAULT_OUTPUT_PATH = path.resolve("index.json");
 const REQUIRED_KEYWORDS = ["akm-kit"];
 const GITHUB_TOPICS = ["akm-kit"];
-const EXCLUDED_REPOS = new Set(["itlackey/agentikit"]);
+const EXCLUDED_REPOS = new Set(["itlackey/akm"]);
 const EXCLUDED_NPM_PACKAGES = new Set(["akm-cli"]);
 const EMPTY_INSPECTION = {};
 export async function buildRegistryIndex(options) {

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/self-update.js

@@ -3,16 +3,35 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS } from "./common";
 import { githubHeaders } from "./github";
-const REPO = "itlackey/agentikit";
-export function detectInstallMethod() {
-    // Bun-compiled binaries: Bun.main equals process.execPath
-    if (typeof Bun !== "undefined" && Bun.main === process.execPath) {
-        return "binary";
-    }
+const REPO = "itlackey/akm";
+/** Read live runtime signals. */
+export function getInstallSignals() {
+    return {
+        bunMain: typeof Bun !== "undefined" ? Bun.main : undefined,
+        importMetaDir: import.meta.dir ?? undefined,
+        hasAkmVersion: typeof AKM_VERSION !== "undefined",
+    };
+}
+// AKM_VERSION ambient type is declared in globals.d.ts
+export function detectInstallMethod(signals) {
+    const s = signals ?? getInstallSignals();
     // npm/bun global install: import.meta.dir contains node_modules
-    if (import.meta.dir?.includes("node_modules")) {
+    if (s.importMetaDir?.includes("node_modules")) {
         return "npm";
     }
+    // Bun-compiled binaries: Bun.main points to a virtual /$bunfs/ path,
+    // NOT process.execPath. The old check (Bun.main === process.execPath) was
+    // always false for compiled binaries, causing "unknown" for every binary user.
+    if (s.bunMain !== undefined) {
+        // Primary check: compiled binaries embed sources under /$bunfs/
+        if (s.bunMain.startsWith("/$bunfs/")) {
+            return "binary";
+        }
+        // Secondary check: AKM_VERSION is defined only in compiled builds (via --define)
+        if (s.hasAkmVersion) {
+            return "binary";
+        }
+    }
     return "unknown";
 }
 export function getAkmBinaryName() {
@@ -79,7 +98,7 @@ export async function performUpgrade(check, opts) {
         };
     }
     if (!latestVersion) {
-        throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/agentikit/releases");
+        throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
     }
     const tag = `v${latestVersion}`;
     const binaryName = getAkmBinaryName();

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/dist/version.js

@@ -18,3 +18,4 @@ export const pkgVersion = (() => {
     }
     return "0.0.0-dev";
 })();
+// AKM_VERSION ambient type is declared in globals.d.ts

package/package.json

@@ -1,26 +1,34 @@
 {
   "name": "akm-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
-  "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
+  "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
     "akm",
-    "akm-kit",
+    "agent-kit-manager",
+    "akm-cli",
     "ai-agent",
+    "ai-tools",
     "agent-framework",
+    "package-manager",
     "developer-tools",
     "cli",
-    "tools",
     "skills",
-    "commands"
+    "commands",
+    "claude-code",
+    "opencode",
+    "mcp",
+    "ai-coding-assistant",
+    "agent-skills",
+    "skill-management"
   ],
-  "homepage": "https://github.com/itlackey/agentikit#readme",
+  "homepage": "https://github.com/itlackey/akm#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/itlackey/agentikit.git"
+    "url": "git+https://github.com/itlackey/akm.git"
   },
   "bugs": {
-    "url": "https://github.com/itlackey/agentikit/issues"
+    "url": "https://github.com/itlackey/akm/issues"
   },
   "license": "MPL-2.0",
   "files": [
@@ -39,7 +47,8 @@
     "lint": "bunx biome check src/ tests/",
     "lint:fix": "bunx biome check --write src/ tests/",
     "format": "bunx biome format --write src/ tests/",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",
+    "postpublish": "git checkout -- README.md"
   },
   "publishConfig": {
     "access": "public"
@@ -51,7 +60,6 @@
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0",
     "sqlite-vec": "0.1.7-alpha.2"
   },
   "engines": {
@@ -60,6 +68,7 @@
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "citty": "^0.2.1",
+    "@huggingface/transformers": "^3.8.1",
     "yaml": "^2.8.2"
   }
 }