akm-cli 0.0.23 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Agent Kit Manager
 
-> Agent-i-Kit
+> **akm** — Agent Kit Manager
 
 [![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)
@@ -25,7 +25,7 @@ Upgrade in place with `akm upgrade`.
 ## Quick Start
 
 ```sh
-akm init                          # Initialize your stash
+akm init                          # Initialize your working stash
 akm add github:owner/repo         # Add a kit from GitHub
 akm search "deploy"               # Find assets
 akm show script:deploy.sh         # View details and run command
@@ -89,7 +89,7 @@ Registries are indexes of available kits. The official
 ```sh
 akm registry search "code review"                                        # Search registries
 akm registry add https://example.com/registry/index.json --name team     # Add a registry
-akm sources add http://host:1933 --provider openviking \
+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
@@ -130,7 +130,7 @@ See the [Kit Maker's Guide](docs/kit-makers.md) for a full walkthrough.
 | [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) | Asset types, classification, stash model |
+| [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 |
 

package/dist/asset-spec.js

@@ -79,7 +79,7 @@ export function _setAssetTypeHooks(rendererHook, actionBuilderHook) {
     _registerActionBuilder = actionBuilderHook;
 }
 /**
- * Register a custom asset type with the Agentikit asset system.
+ * Register a custom asset type with the akm asset system.
  *
  * ## Full extension registration API
  *

package/dist/cli.js

@@ -6,18 +6,18 @@ import { resolveStashDir } from "./common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./config-cli";
 import { ConfigError, NotFoundError, UsageError } from "./errors";
-import { agentikitIndex } from "./indexer";
-import { agentikitInit } from "./init";
-import { agentikitList, agentikitRemove, agentikitUpdate } from "./installed-kits";
+import { akmIndex } from "./indexer";
+import { akmInit } from "./init";
+import { akmList, 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 { agentikitAdd } from "./stash-add";
-import { agentikitClone } from "./stash-clone";
-import { agentikitSearch, parseSearchSource } from "./stash-search";
-import { agentikitShowUnified } from "./stash-show";
-import { addStashSource, listStashSources, removeStashSource } from "./stash-source-manage";
+import { akmAdd, akmKitAdd } 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 { setQuiet, warn } from "./warn";
 // Version: prefer compile-time define, then package.json, then fallback
 const pkgVersion = (() => {
@@ -405,14 +405,14 @@ function formatSearchPlain(r, detail) {
 const initCommand = defineCommand({
     meta: {
         name: "init",
-        description: "Initialize Agent-i-Kit's working stash directory and persist stashDir in config",
+        description: "Initialize akm's working stash directory and persist stashDir in config",
     },
     args: {
         dir: { type: "string", description: "Custom stash directory path (default: ~/akm)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitInit({ dir: args.dir });
+            const result = await akmInit({ dir: args.dir });
             output("init", result);
         });
     },
@@ -424,7 +424,7 @@ const indexCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitIndex({ full: args.full });
+            const result = await akmIndex({ full: args.full });
             output("index", result);
         });
     },
@@ -451,7 +451,7 @@ const searchCommand = defineCommand({
             }
             const limit = limitRaw;
             const source = parseSearchSource(args.source);
-            const result = await agentikitSearch({ query: args.query, type, limit, source });
+            const result = await akmSearch({ query: args.query, type, limit, source });
             output("search", result);
         });
     },
@@ -467,7 +467,7 @@ const addCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitAdd({ ref: args.ref });
+            const result = await akmAdd({ ref: args.ref });
             output("add", result);
         });
     },
@@ -476,7 +476,7 @@ const listCommand = defineCommand({
     meta: { name: "list", description: "List installed kits" },
     async run() {
         await runWithJsonErrors(async () => {
-            const result = await agentikitList();
+            const result = await akmList();
             output("list", result);
         });
     },
@@ -488,7 +488,7 @@ const removeCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitRemove({ target: args.target });
+            const result = await akmRemove({ target: args.target });
             output("remove", result);
         });
     },
@@ -502,11 +502,36 @@ const updateCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitUpdate({ target: args.target, all: args.all, force: args.force });
+            const result = await akmUpdate({ target: args.target, all: args.all, force: args.force });
             output("update", result);
         });
     },
 });
+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: {
@@ -568,7 +593,7 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${args.akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            const result = await agentikitShowUnified({ ref: args.ref, view });
+            const result = await akmShowUnified({ ref: args.ref, view });
             output("show", result);
         });
     },
@@ -672,7 +697,7 @@ const configCommand = defineCommand({
 const cloneCommand = defineCommand({
     meta: {
         name: "clone",
-        description: "Clone an asset from any stash source into the working stash or a custom destination",
+        description: "Clone an asset from any source into the working stash or a custom destination",
     },
     args: {
         ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//script:deploy.sh)", required: true },
@@ -682,7 +707,7 @@ const cloneCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await agentikitClone({
+            const result = await akmClone({
                 sourceRef: args.ref,
                 newName: args.name,
                 force: args.force,
@@ -815,21 +840,20 @@ const registryCommand = defineCommand({
     },
 });
 /**
- * Shared subcommand definitions for stash source management.
- * Used by both `akm stash` (preferred) and `akm sources` (legacy alias).
+ * Subcommand definitions for managing additional stashes.
  */
 function buildSourceSubCommands(outputPrefix) {
     return {
         list: defineCommand({
-            meta: { name: "list", description: "List all stash sources" },
+            meta: { name: "list", description: "List all stashes in search order" },
             run() {
                 return runWithJsonErrors(() => {
-                    output(`${outputPrefix}`, listStashSources());
+                    output(`${outputPrefix}`, listStashes());
                 });
             },
         }),
         add: defineCommand({
-            meta: { name: "add", description: "Add a stash source (filesystem path or remote URL)" },
+            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" },
@@ -856,7 +880,7 @@ function buildSourceSubCommands(outputPrefix) {
                             throw new UsageError("--options must be valid JSON");
                         }
                     }
-                    const result = addStashSource({
+                    const result = addStash({
                         target: args.target,
                         name: args.name,
                         providerType: args.provider,
@@ -867,13 +891,13 @@ function buildSourceSubCommands(outputPrefix) {
             },
         }),
         remove: defineCommand({
-            meta: { name: "remove", description: "Remove a stash source by URL, path, or name" },
+            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 = removeStashSource(args.target);
+                    const result = removeStash(args.target);
                     output(`${outputPrefix}-remove`, result);
                 });
             },
@@ -881,13 +905,9 @@ function buildSourceSubCommands(outputPrefix) {
     };
 }
 const stashCommand = defineCommand({
-    meta: { name: "stash", description: "Manage stash sources (local paths and remote providers)" },
+    meta: { name: "stash", description: "Manage additional stashes (local directories and remote providers)" },
     subCommands: buildSourceSubCommands("stash"),
 });
-const sourcesCommand = defineCommand({
-    meta: { name: "sources", description: "Manage stash sources (alias for 'akm stash')" },
-    subCommands: buildSourceSubCommands("sources"),
-});
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -905,7 +925,7 @@ const main = defineCommand({
     meta: {
         name: "akm",
         version: pkgVersion,
-        description: "CLI tool to search, open, and manage assets from Agent-i-Kit stash.",
+        description: "Agent Kit Manager — search, show, and manage assets from your stash.",
     },
     args: {
         format: { type: "string", description: "Output format (json|text|yaml)" },
@@ -919,12 +939,12 @@ const main = defineCommand({
         list: listCommand,
         remove: removeCommand,
         update: updateCommand,
+        kit: kitCommand,
         upgrade: upgradeCommand,
         search: searchCommand,
         show: showCommand,
         clone: cloneCommand,
         stash: stashCommand,
-        sources: sourcesCommand,
         registry: registryCommand,
         config: configCommand,
         hints: hintsCommand,
@@ -1079,14 +1099,14 @@ 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 the stash 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 stashes first before writing something from scratch.
 
 ## Quick Reference
 
 \`\`\`sh
-akm search "<query>"                          # Search for assets
+akm search "<query>"                          # Search your stashes and installed kits
 akm search "<query>" --type skill             # Filter by type
-akm search "<query>" --source both            # Search stash providers and registries for assets
+akm search "<query>" --source both            # Also search registries for installable kits
 akm show <ref>                                # View asset details
 akm add <ref>                                 # Install a kit (npm, GitHub, git, local)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
@@ -1107,14 +1127,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 the stash 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 stashes first before writing something from scratch.
 
 ## Search
 
 \`\`\`sh
-akm search "<query>"                          # Search local stash
+akm search "<query>"                          # Search your stashes and installed kits
 akm search "<query>" --type skill             # Filter by asset type
-akm search "<query>" --source both            # Search all stash providers and registries
+akm search "<query>" --source both            # Also search registries for installable kits
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
 akm search "<query>" --detail full            # Include scores, paths, timing
@@ -1155,10 +1175,14 @@ akm show viking://resources/my-doc           # Show remote OpenViking content
 ## Install & Manage Kits
 
 \`\`\`sh
-akm add <ref>                                 # Install a kit
+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
+akm add ./path/to/local/kit                   # From local directory (adds as 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
@@ -1206,10 +1230,11 @@ akm config path --all                         # Show all config paths
 ## Other Commands
 
 \`\`\`sh
-akm init                                      # Initialize stash directory
+akm init                                      # Initialize working stash
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
-akm sources                                   # List stash search paths
+akm stash                                     # List all stashes
+akm kit                                       # Kit management (add, list, remove, update)
 akm upgrade                                   # Upgrade akm binary
 akm upgrade --check                           # Check for updates
 akm hints                                     # Print this reference

package/dist/config-cli.js

@@ -9,16 +9,6 @@ export function parseConfigValue(key, value) {
                 throw new UsageError(`Invalid value for semanticSearch: expected "true" or "false"`);
             }
             return { semanticSearch: value === "true" };
-        case "searchPaths":
-            try {
-                const parsed = JSON.parse(value);
-                if (!Array.isArray(parsed))
-                    throw new UsageError("expected JSON array");
-                return { searchPaths: parsed.filter((d) => typeof d === "string") };
-            }
-            catch {
-                throw new UsageError(`Invalid value for searchPaths: expected JSON array (e.g. '["/path/a","/path/b"]')`);
-            }
         case "embedding":
             return { embedding: parseEmbeddingConnectionValue(value) };
         case "llm":
@@ -41,8 +31,6 @@ export function getConfigValue(config, key) {
             return config.stashDir ?? null;
         case "semanticSearch":
             return config.semanticSearch;
-        case "searchPaths":
-            return [...config.searchPaths];
         case "embedding":
             return config.embedding ?? null;
         case "llm":
@@ -63,7 +51,6 @@ export function setConfigValue(config, key, rawValue) {
     switch (key) {
         case "stashDir":
         case "semanticSearch":
-        case "searchPaths":
         case "embedding":
         case "llm":
         case "registries":
@@ -108,8 +95,6 @@ export function listConfig(config) {
         result.embedding = config.embedding;
     if (config.llm)
         result.llm = config.llm;
-    if (config.searchPaths?.length)
-        result.searchPaths = config.searchPaths;
     return result;
 }
 function mergeConfigValue(config, partial) {

package/dist/config.js

@@ -4,7 +4,6 @@ import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearch: true,
-    searchPaths: [],
     registries: [
         { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "official" },
         { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh" },
@@ -93,8 +92,6 @@ function sanitizeConfigForWrite(config) {
         sanitized.llm = rest;
     }
     // Drop empty keys to keep config clean
-    if (!config.searchPaths?.length)
-        delete sanitized.searchPaths;
     return sanitized;
 }
 export function updateConfig(partial) {
@@ -125,8 +122,18 @@ function pickKnownKeys(raw) {
     if (typeof raw.semanticSearch === "boolean") {
         config.semanticSearch = raw.semanticSearch;
     }
+    // Migrate legacy searchPaths into stashes
     if (Array.isArray(raw.searchPaths)) {
-        config.searchPaths = raw.searchPaths.filter((d) => typeof d === "string");
+        const legacyPaths = raw.searchPaths.filter((d) => typeof d === "string");
+        if (legacyPaths.length > 0) {
+            const existing = config.stashes ?? [];
+            const migrated = legacyPaths
+                .filter((p) => !existing.some((s) => s.type === "filesystem" && s.path === p))
+                .map((p) => ({ type: "filesystem", path: p }));
+            if (migrated.length > 0) {
+                config.stashes = [...existing, ...migrated];
+            }
+        }
     }
     const embedding = parseEmbeddingConfig(raw.embedding);
     if (embedding)
@@ -270,7 +277,7 @@ function parseEmbeddingConfig(value) {
     if (typeof obj.endpoint !== "string" || !obj.endpoint)
         return undefined;
     if (!obj.endpoint.startsWith("http://") && !obj.endpoint.startsWith("https://")) {
-        console.warn(`[agentikit] Ignoring embedding config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
+        console.warn(`[akm] Ignoring embedding config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
     if (typeof obj.model !== "string" || !obj.model)
@@ -303,7 +310,7 @@ function parseLlmConfig(value) {
     if (typeof obj.endpoint !== "string" || !obj.endpoint)
         return undefined;
     if (!obj.endpoint.startsWith("http://") && !obj.endpoint.startsWith("https://")) {
-        console.warn(`[agentikit] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
+        console.warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
     if (typeof obj.model !== "string" || !obj.model)

package/dist/github.js

@@ -1,12 +1,31 @@
 export const GITHUB_API_BASE = "https://api.github.com";
-export function githubHeaders() {
+const GITHUB_TOKEN_DOMAINS = new Set(["api.github.com", "github.com", "uploads.github.com"]);
+/**
+ * Build headers for GitHub API requests.
+ * When a `url` is provided, the Authorization header is only included if the
+ * URL points to a known GitHub domain, preventing token leakage on redirects
+ * to third-party hosts.
+ */
+export function githubHeaders(url) {
     const token = process.env.GITHUB_TOKEN?.trim();
     const headers = {
         Accept: "application/vnd.github+json",
         "User-Agent": "akm-registry",
     };
-    if (token)
-        headers.Authorization = `Bearer ${token}`;
+    if (token) {
+        let includeToken = true;
+        if (url) {
+            try {
+                const hostname = new URL(url).hostname;
+                includeToken = GITHUB_TOKEN_DOMAINS.has(hostname);
+            }
+            catch {
+                includeToken = false;
+            }
+        }
+        if (includeToken)
+            headers.Authorization = `Bearer ${token}`;
+    }
     return headers;
 }
 export function asRecord(value) {

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.0",
   "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",