akm-cli 0.0.23 → 0.1.1

package/dist/indexer.js

@@ -7,12 +7,12 @@ import { getDbPath } from "./paths";
 import { walkStashFlat } from "./walker";
 import { warn } from "./warn";
 // ── Indexer ──────────────────────────────────────────────────────────────────
-export async function agentikitIndex(options) {
+export async function akmIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
     // Load config and resolve all stash sources
     const { loadConfig } = await import("./config.js");
     const config = loadConfig();
-    const { resolveAllStashDirs } = await import("./stash-source.js");
+    const { resolveAllStashDirs } = await import("./search-source.js");
     const allStashDirs = resolveAllStashDirs(stashDir);
     const t0 = Date.now();
     // Open database — pass embedding dimension from config if available

package/dist/init.js

@@ -10,7 +10,7 @@ import { TYPE_DIRS } from "./asset-spec";
 import { getConfigPath, loadConfig, saveConfig } from "./config";
 import { getBinDir, getDefaultStashDir } from "./paths";
 import { ensureRg } from "./ripgrep-install";
-export async function agentikitInit(options) {
+export async function akmInit(options) {
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
     let created = false;
     if (!fs.existsSync(stashDir)) {

package/dist/installed-kits.js

@@ -13,11 +13,11 @@ import fs from "node:fs";
 import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 import { NotFoundError, UsageError } from "./errors";
-import { agentikitIndex } from "./indexer";
+import { akmIndex } from "./indexer";
 import { removeLockEntry, upsertLockEntry } from "./lockfile";
 import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
-export async function agentikitList(input) {
+export async function akmList(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const installed = config.installed ?? [];
@@ -34,22 +34,22 @@ export async function agentikitList(input) {
         totalInstalled: installed.length,
     };
 }
-export async function agentikitRemove(input) {
+export async function akmRemove(input) {
     const target = input.target.trim();
     if (!target)
-        throw new UsageError("Target is required.");
+        throw new UsageError("Target is required. Provide the kit id or ref (e.g. `akm remove npm:@scope/kit` or `akm remove owner/repo`).");
     const stashDir = input.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const installed = config.installed ?? [];
     const entry = resolveInstalledTarget(installed, target);
     const updatedConfig = removeInstalledRegistryEntry(entry.id);
-    removeLockEntry(entry.id);
+    await removeLockEntry(entry.id);
     // Only clean up cache for non-local sources — local sources point to the
     // user's real directory on disk and must never be deleted.
     if (entry.source !== "local") {
         cleanupDirectoryBestEffort(entry.cacheDir);
     }
-    const index = await agentikitIndex({ stashDir });
+    const index = await akmIndex({ stashDir });
     return {
         schemaVersion: 1,
         stashDir,
@@ -62,7 +62,7 @@ export async function agentikitRemove(input) {
             stashRoot: entry.stashRoot,
         },
         config: {
-            searchPaths: updatedConfig.searchPaths,
+            stashCount: updatedConfig.stashes?.length ?? 0,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -73,7 +73,7 @@ export async function agentikitRemove(input) {
         },
     };
 }
-export async function agentikitUpdate(input) {
+export async function akmUpdate(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const target = input?.target?.trim();
     const all = input?.all === true;
@@ -117,7 +117,7 @@ export async function agentikitUpdate(input) {
             },
         });
     }
-    const index = await agentikitIndex({ stashDir });
+    const index = await akmIndex({ stashDir });
     const config = loadConfig();
     return {
         schemaVersion: 1,
@@ -126,7 +126,7 @@ export async function agentikitUpdate(input) {
         all,
         processed,
         config: {
-            searchPaths: config.searchPaths,
+            stashCount: config.stashes?.length ?? 0,
             installedKitCount: config.installed?.length ?? 0,
         },
         index: {

package/dist/kit-include.js

@@ -2,8 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { isWithin } from "./common";
 // ── Helpers ─────────────────────────────────────────────────────────────────
-/** Keys to check in package.json for akm include configuration. */
-const INCLUDE_CONFIG_KEYS = ["akm", "agentikit"];
+/** Key to check in package.json for akm include configuration. */
+const INCLUDE_CONFIG_KEYS = ["akm"];
 function readPackageJsonAt(dirPath) {
     try {
         const raw = fs.readFileSync(path.join(dirPath, "package.json"), "utf8");
@@ -39,7 +39,7 @@ function extractIncludeList(pkg) {
 // ── Public API ───────────────────────────────────────────────────────────────
 /**
  * Walk up the directory tree from `startDir` to `boundary` (inclusive) looking
- * for a package.json that declares an `akm.include` or `agentikit.include` list.
+ * for a package.json that declares an `akm.include` list.
  * Returns the first config found, or `undefined` if none is found within the
  * boundary.
  */

package/dist/local-search.js

@@ -15,8 +15,8 @@ import { getRenderer } from "./file-context";
 import { buildSearchText } from "./indexer";
 import { generateMetadataFlat, loadStashFile } from "./metadata";
 import { getDbPath } from "./paths";
+import { buildEditHint, findSourceForPath, isEditable } from "./search-source";
 import { makeAssetRef } from "./stash-ref";
-import { buildEditHint, findSourceForPath, isEditable } from "./stash-source";
 import { walkStashFlat } from "./walker";
 import { warn } from "./warn";
 // ── Type renderer/action maps (re-exported so stash-search.ts can register) ──

package/dist/lockfile.js

@@ -23,6 +23,10 @@ async function acquireLockSentinel() {
         catch (err) {
             if (err.code !== "EEXIST")
                 throw err;
+            // Check for stale lock — if the owning PID is no longer running, reclaim it
+            if (tryReclaimStaleSentinel(sentinelPath)) {
+                continue; // Sentinel removed — retry immediately
+            }
             // Another process holds the lock — wait briefly before retrying
             if (attempt < LOCK_MAX_RETRIES - 1) {
                 await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
@@ -32,6 +36,34 @@ async function acquireLockSentinel() {
     // Best-effort: proceed without the lock rather than failing the install
     return false;
 }
+/**
+ * Check if the sentinel was left by a dead process and remove it if so.
+ * Returns true if the sentinel was reclaimed (removed).
+ */
+function tryReclaimStaleSentinel(sentinelPath) {
+    try {
+        const content = fs.readFileSync(sentinelPath, "utf8").trim();
+        const pid = parseInt(content, 10);
+        if (Number.isNaN(pid) || pid <= 0) {
+            // Invalid PID in sentinel — reclaim it
+            fs.unlinkSync(sentinelPath);
+            return true;
+        }
+        // Check if the process is still alive (signal 0 doesn't kill, just checks)
+        try {
+            process.kill(pid, 0);
+            return false; // Process is alive — lock is valid
+        }
+        catch {
+            // Process is dead — reclaim the stale lock
+            fs.unlinkSync(sentinelPath);
+            return true;
+        }
+    }
+    catch {
+        return false; // Can't read or remove — leave it alone
+    }
+}
 function releaseLockSentinel() {
     try {
         fs.unlinkSync(getLockSentinelPath());
@@ -84,9 +116,16 @@ export async function upsertLockEntry(entry) {
             releaseLockSentinel();
     }
 }
-export function removeLockEntry(id) {
-    const entries = readLockfile();
-    writeLockfile(entries.filter((e) => e.id !== id));
+export async function removeLockEntry(id) {
+    const acquired = await acquireLockSentinel();
+    try {
+        const entries = readLockfile();
+        writeLockfile(entries.filter((e) => e.id !== id));
+    }
+    finally {
+        if (acquired)
+            releaseLockSentinel();
+    }
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function isValidLockfileEntry(value) {

package/dist/registry-build-index.js

@@ -11,17 +11,10 @@ import { walkStashFlat } from "./walker";
 const DEFAULT_NPM_REGISTRY_BASE = "https://registry.npmjs.org";
 const DEFAULT_MANUAL_ENTRIES_PATH = path.resolve("manual-entries.json");
 const DEFAULT_OUTPUT_PATH = path.resolve("index.json");
-const REQUIRED_KEYWORDS = ["agentikit", "akm-kit"];
-const GITHUB_TOPICS = ["agentikit", "akm-kit"];
-const EXCLUDED_REPOS = new Set(["itlackey/agentikit-plugins", "itlackey/agentikit"]);
-const EXCLUDED_NPM_PACKAGES = new Set([
-    "agentikit",
-    "agentikit-claude",
-    "agentikit-opencode",
-    "agentikit-plugins",
-    "akm-cli",
-    "akm-opencode",
-]);
+const REQUIRED_KEYWORDS = ["akm-kit"];
+const GITHUB_TOPICS = ["akm-kit"];
+const EXCLUDED_REPOS = new Set(["itlackey/agentikit"]);
+const EXCLUDED_NPM_PACKAGES = new Set(["akm-cli"]);
 const EMPTY_INSPECTION = {};
 export async function buildRegistryIndex(options) {
     const manualEntriesPath = path.resolve(options?.manualEntriesPath ?? DEFAULT_MANUAL_ENTRIES_PATH);

package/dist/registry-install.js

@@ -60,7 +60,7 @@ export async function installRegistryRef(ref, options) {
         integrity = await computeFileHash(archivePath);
         extractTarGzSecure(archivePath, extractedDir);
         provisionalKitRoot = detectStashRoot(extractedDir);
-        installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
     }
     catch (err) {
@@ -118,7 +118,7 @@ async function installGitRegistryRef(parsed, options) {
     if (isDirectory(extractedDir)) {
         try {
             const provisionalKitRoot = detectStashRoot(extractedDir);
-            const installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+            const installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
             const stashRoot = detectStashRoot(installRoot);
             if (stashRoot) {
                 return {
@@ -164,7 +164,7 @@ async function installGitRegistryRef(parsed, options) {
         // Clean up the clone dir
         fs.rmSync(cloneDir, { recursive: true, force: true });
         provisionalKitRoot = detectStashRoot(extractedDir);
-        installRoot = applyAgentikitIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
+        installRoot = applyAkmIncludeConfig(provisionalKitRoot, cacheDir, extractedDir) ?? provisionalKitRoot;
         stashRoot = detectStashRoot(installRoot);
     }
     catch (err) {
@@ -226,10 +226,6 @@ export function detectStashRoot(extractedDir) {
     if (hasStashDirs(root)) {
         return root;
     }
-    const opencodeDir = path.join(root, "opencode");
-    if (hasStashDirs(opencodeDir)) {
-        return opencodeDir;
-    }
     const shallowest = findShallowestStashRoot(root);
     if (shallowest)
         return shallowest;
@@ -242,7 +238,7 @@ function buildInstallCacheDir(cacheRootDir, source, id, version) {
         : (version?.replace(/[^a-zA-Z0-9_.-]+/g, "-") ?? `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`);
     return path.join(cacheRootDir, slug || source, versionSlug);
 }
-function applyAgentikitIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
+function applyAkmIncludeConfig(sourceRoot, cacheDir, searchRoot = sourceRoot) {
     const includeConfig = findNearestIncludeConfig(sourceRoot, searchRoot);
     if (!includeConfig)
         return undefined;
@@ -400,13 +396,15 @@ function countStashDirs(dirPath) {
  *
  * Skips `root` itself since the caller already checked it via `hasStashDirs`.
  */
+const BFS_MAX_DEPTH = 5;
 function findShallowestStashRoot(root) {
-    const queue = [root];
+    const queue = [{ dir: root, depth: 0 }];
     while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current) {
+        const item = queue.shift();
+        if (!item) {
             continue;
         }
+        const { dir: current, depth } = item;
         if (current !== root) {
             // .stash directory is a strong stash marker
             if (isDirectory(path.join(current, ".stash"))) {
@@ -418,6 +416,8 @@ function findShallowestStashRoot(root) {
                 return current;
             }
         }
+        if (depth >= BFS_MAX_DEPTH)
+            continue;
         let children;
         try {
             children = fs.readdirSync(current, { withFileTypes: true });
@@ -430,7 +430,7 @@ function findShallowestStashRoot(root) {
                 continue;
             if (child.name === ".git" || child.name === "node_modules")
                 continue;
-            queue.push(path.join(current, child.name));
+            queue.push({ dir: path.join(current, child.name), depth: depth + 1 });
         }
     }
     return undefined;

package/dist/registry-resolve.js

@@ -422,7 +422,7 @@ function fileUriToPath(ref) {
 }
 /**
  * Build a human-readable local ID from an absolute path.
- *   /home/user/.hyphn/skills  → ~/.hyphn/skills
+ *   /home/user/akm/skills     → ~/akm/skills
  *   /tmp/my-kit               → /tmp/my-kit
  */
 function toReadableLocalId(absolutePath) {

package/dist/registry-search.js

@@ -70,7 +70,7 @@ export function resolveRegistries(configRegistries) {
             if (!url)
                 continue;
             if (!url.startsWith("http://") && !url.startsWith("https://")) {
-                console.warn(`[agentikit] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
+                console.warn(`[akm] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
                 continue;
             }
             entries.push({ url });

package/dist/{stash-source.js → search-source.js}

@@ -5,13 +5,13 @@ import { loadConfig } from "./config";
 import { warn } from "./warn";
 // ── Resolution ──────────────────────────────────────────────────────────────
 /**
- * Build the ordered list of stash sources (search paths):
+ * Build the ordered list of stash sources:
  *   1. Primary stash dir (user's own, destination for clone)
- *   2. Additional search paths (user-configured)
+ *   2. Additional stashes (filesystem and remote providers)
  *   3. Installed kit paths (cache-managed, from registry)
  *
  * The first entry is always the primary stash. Additional entries come
- * from `searchPaths` config and `installed` kit entries.
+ * from `stashes` config and `installed` kit entries.
  */
 export function resolveStashSources(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
@@ -30,10 +30,6 @@ export function resolveStashSources(overrideStashDir, existingConfig) {
             sources.push({ path: resolved, ...(registryId ? { registryId } : {}) });
         }
     };
-    // Legacy: searchPaths[]
-    for (const dir of config.searchPaths) {
-        addSource(dir);
-    }
     // Filesystem entries from stashes[]
     for (const entry of config.stashes ?? []) {
         if (entry.type === "filesystem" && entry.path && entry.enabled !== false) {
@@ -78,7 +74,7 @@ export function getPrimarySource(sources) {
  * managed by the package manager (`installed[].cacheDir`). These
  * will be overwritten by `akm update` without warning.
  *
- * Everything else — working stash, search paths, local project dirs — is
+ * Everything else — working stash, additional stashes, local project dirs — is
  * the user's domain to manage.
  */
 export function isEditable(filePath, config) {

package/dist/stash-add.js

@@ -3,14 +3,33 @@ import path from "node:path";
 import { resolveStashDir } from "./common";
 import { loadConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
-import { agentikitIndex } from "./indexer";
+import { akmIndex } from "./indexer";
 import { upsertLockEntry } from "./lockfile";
 import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
-export async function agentikitAdd(input) {
+export async function akmKitAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
-        throw new UsageError("Install ref or local directory is required.");
+        throw new UsageError("Registry ref is required. " + "Examples: `akm kit add @scope/kit`, `akm kit add github:owner/repo`");
+    const stashDir = resolveStashDir();
+    try {
+        const parsed = parseRegistryRef(ref);
+        if (parsed.source === "local") {
+            throw new UsageError(`Local directories should be added as stashes, not kits. Use \`akm stash add ${ref}\` instead.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw err;
+        // Not a local ref — fall through to registry install
+    }
+    return addRegistryKit(ref, stashDir);
+}
+export async function akmAdd(input) {
+    const ref = input.ref.trim();
+    if (!ref)
+        throw new UsageError("Install ref or local directory is required. " +
+            "Examples: `akm add @scope/kit`, `akm add github:owner/repo`, `akm add ./local/path`");
     const stashDir = resolveStashDir();
     // Detect local directory refs and route them to stashes[] instead of installed[]
     try {
@@ -44,7 +63,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir) {
         stashes.push(entry);
         saveConfig({ ...config, stashes });
     }
-    const index = await agentikitIndex({ stashDir });
+    const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
@@ -57,7 +76,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir) {
             stashRoot: resolvedPath,
         },
         config: {
-            searchPaths: updatedConfig.searchPaths,
+            stashCount: updatedConfig.stashes?.length ?? 0,
             installedKitCount: updatedConfig.installed?.length ?? 0,
         },
         index: {
@@ -102,7 +121,7 @@ async function addRegistryKit(ref, stashDir) {
             // Best-effort cleanup only.
         }
     }
-    const index = await agentikitIndex({ stashDir });
+    const index = await akmIndex({ stashDir });
     return {
         schemaVersion: 1,
         stashDir,
@@ -120,7 +139,7 @@ async function addRegistryKit(ref, stashDir) {
             installedAt: installed.installedAt,
         },
         config: {
-            searchPaths: config.searchPaths,
+            stashCount: config.stashes?.length ?? 0,
             installedKitCount: config.installed?.length ?? 0,
         },
         index: {

package/dist/stash-clone.js

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
+import { UsageError } from "./errors";
 import { isRemoteOrigin, resolveSourcesForOrigin } from "./origin-resolve";
 import { installRegistryRef } from "./registry-install";
+import { findSourceForPath, getPrimarySource, resolveStashSources } from "./search-source";
 import { makeAssetRef, parseAssetRef } from "./stash-ref";
 import { resolveAssetPath } from "./stash-resolve";
-import { findSourceForPath, getPrimarySource, resolveStashSources } from "./stash-source";
-export async function agentikitClone(options) {
+export async function akmClone(options) {
     const parsed = parseAssetRef(options.sourceRef);
     // When --dest is provided, the working stash is optional
     let allSources;
@@ -61,6 +62,31 @@ export async function agentikitClone(options) {
     const sourceSource = findSourceForPath(sourcePath, allSources);
     const destName = options.newName ?? parsed.name;
     const typeDir = TYPE_DIRS[parsed.type];
+    // Validate destName to prevent path traversal (parsed.name is already
+    // validated by parseAssetRef, but newName comes directly from user input).
+    // Run whenever newName is provided, including empty string.
+    if (options.newName !== undefined) {
+        if (destName === "") {
+            throw new UsageError("Clone name must not be empty.");
+        }
+        const normalized = path.posix.normalize(destName.replace(/\\/g, "/"));
+        if (path.isAbsolute(destName) ||
+            normalized === "." ||
+            normalized.startsWith("../") ||
+            normalized === ".." ||
+            destName.includes("\0")) {
+            throw new UsageError(`Unsafe clone name "${destName}": must not contain path traversal or absolute paths.`);
+        }
+        // Ensure the resolved destination is strictly inside the type directory,
+        // not equal to it (which can happen with crafted multi-segment names).
+        // path.relative() is used instead of startsWith() for cross-platform safety.
+        const destTypeDir = path.resolve(path.join(destRoot, typeDir));
+        const resolvedDest = path.resolve(path.join(destRoot, typeDir, destName));
+        const rel = path.relative(destTypeDir, resolvedDest);
+        if (rel === "" || rel.startsWith("..")) {
+            throw new UsageError(`Unsafe clone name "${destName}": resolves outside the target type directory.`);
+        }
+    }
     const destLabel = options.dest ? "at destination" : "in working stash";
     // Guard against self-clone
     if (parsed.type === "skill") {

package/dist/stash-providers/filesystem.js

@@ -1,9 +1,9 @@
 import { resolveStashDir } from "../common";
 import { loadConfig } from "../config";
 import { searchLocal } from "../local-search";
+import { resolveStashSources } from "../search-source";
 import { registerStashProvider } from "../stash-provider-factory";
 import { showLocal } from "../stash-show";
-import { resolveStashSources } from "../stash-source";
 class FilesystemStashProvider {
     type = "filesystem";
     name;

package/dist/stash-providers/openviking.js

@@ -16,7 +16,7 @@ const QUERY_CACHE_TTL_MS = 5 * 60 * 1000;
 /** Maximum age before query cache is considered stale but still usable (1 hour). */
 const QUERY_CACHE_STALE_MS = 60 * 60 * 1000;
 /**
- * Single source of truth for OpenViking type → agentikit asset type mapping.
+ * Single source of truth for OpenViking type → akm asset type mapping.
  * Used by both search hit mapping and show response mapping.
  */
 const OV_TYPE_MAP = {

package/dist/stash-search.js

@@ -5,9 +5,9 @@ import { resolveStashProviders } from "./stash-provider-factory";
 import "./stash-providers/index";
 import { UsageError } from "./errors";
 import { searchRegistry } from "./registry-search";
-import { resolveStashSources } from "./stash-source";
+import { resolveStashSources } from "./search-source";
 const DEFAULT_LIMIT = 20;
-export async function agentikitSearch(input) {
+export async function akmSearch(input) {
     const t0 = Date.now();
     const query = input.query.trim();
     const normalizedQuery = query.toLowerCase();
@@ -24,7 +24,7 @@ export async function agentikitSearch(input) {
             stashDir: "",
             source,
             hits: [],
-            warnings: ["No stash sources configured. Run `akm init` first."],
+            warnings: ["No stashes configured. Run `akm init` to create your working stash."],
             timing: { totalMs: Date.now() - t0 },
         };
     }

package/dist/stash-show.js

@@ -2,17 +2,17 @@ import { loadConfig } from "./config";
 import { NotFoundError, UsageError } from "./errors";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
 import { resolveSourcesForOrigin } from "./origin-resolve";
+import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./search-source";
 import { resolveStashProviders } from "./stash-provider-factory";
 import { parseAssetRef } from "./stash-ref";
 import { resolveAssetPath } from "./stash-resolve";
-import { buildEditHint, findSourceForPath, isEditable, resolveStashSources } from "./stash-source";
 // Eagerly import stash providers to trigger self-registration
 import "./stash-providers/index";
 /**
  * Unified show: routes to the first stash provider that can handle the ref.
  * viking:// refs are handled by OpenViking provider; everything else by filesystem show.
  */
-export async function agentikitShowUnified(input) {
+export async function akmShowUnified(input) {
     const ref = input.ref.trim();
     // Try stash providers first (e.g. OpenViking for viking:// URIs)
     const config = loadConfig();
@@ -23,7 +23,7 @@ export async function agentikitShowUnified(input) {
     // Default: local filesystem show
     return showLocal(input);
 }
-/** @internal Use agentikitShowUnified() for all external callers. */
+/** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseAssetRef(input.ref);
     const displayType = parsed.type;
@@ -48,12 +48,15 @@ export async function showLocal(input) {
             `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`);
     }
     if (!assetPath) {
-        throw lastError ?? new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}`);
+        throw (lastError ??
+            new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
+                "Check the name with `akm search` or verify the asset exists in your stash."));
     }
     const source = findSourceForPath(assetPath, allSources);
     const sourceStashDir = source?.path ?? allStashDirs[0];
     if (!sourceStashDir) {
-        throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}`);
+        throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
+            "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
     const match = await runMatchers(fileCtx);

package/dist/stash-source-manage.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { loadConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
-import { resolveStashSources } from "./stash-source";
+import { resolveStashSources } from "./search-source";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
  * Add a stash source (filesystem path or remote provider URL) to config.
@@ -10,7 +10,7 @@ import { resolveStashSources } from "./stash-source";
  * `http://` or `https://`. URL sources require a `providerType` option
  * (e.g. "openviking").
  */
-export function addStashSource(opts) {
+export function addStash(opts) {
     const { target, name, providerType, options: providerOptions } = opts;
     const config = loadConfig();
     const stashes = [...(config.stashes ?? [])];
@@ -48,7 +48,7 @@ export function addStashSource(opts) {
  * Remove a stash source by URL, path, or name.
  * Match priority: URL > path > name (most specific first).
  */
-export function removeStashSource(target) {
+export function removeStash(target) {
     const config = loadConfig();
     const stashes = [...(config.stashes ?? [])];
     const isUrl = target.startsWith("http://") || target.startsWith("https://");
@@ -74,7 +74,7 @@ export function removeStashSource(target) {
 /**
  * List all stash sources (local filesystem + configured stashes).
  */
-export function listStashSources() {
+export function listStashes() {
     const config = loadConfig();
     const localSources = resolveStashSources();
     const stashes = config.stashes ?? [];

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "akm-cli",
-  "version": "0.0.23",
+  "version": "0.1.1",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [
     "akm",
-    "agent-i-kit",
+    "akm-kit",
     "ai-agent",
     "agent-framework",
     "developer-tools",