agentikit 0.0.14 → 0.0.15

package/README.md

@@ -1,5 +1,9 @@
 # Agent-i-Kit
 
+[![npm version](https://img.shields.io/npm/v/agentikit)](https://www.npmjs.com/package/agentikit)
+[![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/agentikit)](LICENSE)
+
 A package manager for AI agent capabilities — tools, skills, commands, agents,
 knowledge, and scripts — that works with any AI coding assistant that can run
 shell commands.
@@ -9,6 +13,11 @@ organize them into a searchable **stash**, share them as installable **kits**,
 and give any model a way to discover and use them through `akm` (Agent Kit
 Manager). No plugins required — just CLI output any tool-calling model can read.
 
+## Requirements
+
+Agent-i-Kit requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses
+Bun-specific APIs (`bun:sqlite`) that are **not available in Node.js**.
+
 ## Quick Start
 
 ```sh
@@ -46,10 +55,9 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, system prompt, or any instruction
 file to give your agent access to your stash without any additional setup:
 
 ~~~markdown
-## Agent-i-Kit
 
 You have access to a searchable library of tools, skills, commands, agents,
-and knowledge documents via `akm` (Agent Kit Manager). Use it to find and
+and knowledge documents via `akm`. Use it to find and
 use capabilities before writing something from scratch.
 
 **Finding assets:**
@@ -277,11 +285,10 @@ akm upgrade --check   # Check for updates without installing
 
 ## Status
 
-Agent-i-Kit is in early development (v0.0.x). The core CLI, stash model, and
-registry are functional and in daily use. Feedback, issues, and PRs welcome —
-especially around real-world usage patterns and integrations with different
-AI coding assistants.
+Agent-i-Kit is approaching v1.0. The core CLI, stash model, and registry are
+stable and in daily use. Feedback, issues, and PRs welcome — especially around
+real-world usage patterns and integrations with different AI coding assistants.
 
 ## License
 
-[CC-BY-4.0](LICENSE)
+[MPL-2.0](LICENSE)

package/dist/asset-spec.js

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { toPosix } from "./common";
 import { tryGetHandler } from "./asset-type-handler";
+import { toPosix } from "./common";
 export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
@@ -10,7 +10,16 @@ const markdownSpec = {
 /** Extended set of script extensions for the script asset type */
 export const SCRIPT_EXTENSIONS_BROAD = new Set([
     ...SCRIPT_EXTENSIONS,
-    ".py", ".rb", ".go", ".pl", ".php", ".lua", ".r", ".swift", ".kt", ".kts",
+    ".py",
+    ".rb",
+    ".go",
+    ".pl",
+    ".php",
+    ".lua",
+    ".r",
+    ".swift",
+    ".kt",
+    ".kts",
 ]);
 export const ASSET_SPECS = {
     tool: {

package/dist/asset-type-handler.js

@@ -1,3 +1,5 @@
+import { UsageError } from "./errors";
+import { registerBuiltinHandlers } from "./handlers/index";
 // ── Registry ─────────────────────────────────────────────────────────────────
 const handlers = new Map();
 let handlersInitialized = false;
@@ -5,8 +7,7 @@ function ensureHandlersRegistered() {
     if (handlersInitialized)
         return;
     handlersInitialized = true;
-    // Import handler registrations
-    require("./handlers/index");
+    registerBuiltinHandlers();
 }
 export function registerAssetType(handler) {
     handlers.set(handler.typeName, handler);
@@ -15,7 +16,7 @@ export function getHandler(type) {
     ensureHandlersRegistered();
     const handler = handlers.get(type);
     if (!handler) {
-        throw new Error(`Unknown asset type: "${type}"`);
+        throw new UsageError(`Unknown asset type: "${type}"`);
     }
     return handler;
 }

package/dist/cli.js

@@ -2,27 +2,56 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
+import { resolveStashDir } from "./common";
+import { getConfigPath, loadConfig, saveConfig } from "./config";
+import { getConfigValue, listConfig, listProviders, parseConfigValue, setConfigValue, unsetConfigValue, useProvider, } from "./config-cli";
+import { ConfigError, NotFoundError, UsageError } from "./errors";
+import { agentikitIndex } from "./indexer";
+import { agentikitInit } from "./init";
+import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
+import { checkForUpdate, performUpgrade } from "./self-update";
 import { agentikitAdd } from "./stash-add";
+import { agentikitClone } from "./stash-clone";
 import { agentikitList, agentikitRemove, agentikitUpdate } from "./stash-registry";
 import { agentikitSearch } from "./stash-search";
 import { agentikitShow } from "./stash-show";
-import { checkForUpdate, performUpgrade } from "./self-update";
-import { agentikitInit } from "./init";
-import { agentikitIndex } from "./indexer";
-import { agentikitClone } from "./stash-clone";
-import { agentikitSubmit } from "./submit";
 import { resolveStashSources } from "./stash-source";
-import { loadConfig, saveConfig, getConfigPath } from "./config";
-import { getConfigValue, listConfig, listProviders, parseConfigValue, setConfigValue, unsetConfigValue, useProvider, } from "./config-cli";
-import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
-import { resolveStashDir } from "./common";
-// Read version from package.json
-const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../package.json");
-const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
+import { agentikitSubmit } from "./submit";
+import { setQuiet, warn } from "./warn";
+// Version: prefer compile-time define, then package.json, then fallback
+const pkgVersion = (() => {
+    // Injected at compile time via `bun build --define`
+    if (typeof AKM_VERSION !== "undefined")
+        return AKM_VERSION;
+    try {
+        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../package.json");
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+    }
+    catch {
+        // swallow — running as compiled binary without package.json
+    }
+    return "0.0.0-dev";
+})();
 /** Check whether --json flag is present in argv */
 function isJsonMode() {
     return process.argv.includes("--json");
 }
+function hasBunYAML(b) {
+    // biome-ignore lint/suspicious/noExplicitAny: type guard for runtime feature detection
+    return typeof b.YAML?.stringify === "function";
+}
+/** Try Bun.YAML.stringify; fall back to JSON if the API is unavailable */
+function yamlStringify(obj) {
+    if (hasBunYAML(Bun)) {
+        return Bun.YAML.stringify(obj);
+    }
+    warn("YAML output not available, using JSON");
+    return JSON.stringify(obj, null, 2);
+}
 /** Output result: JSON if --json flag set, otherwise YAML (default) */
 function output(command, result) {
     if (isJsonMode()) {
@@ -35,7 +64,7 @@ function output(command, result) {
         console.log(plain);
         return;
     }
-    console.log(Bun.YAML.stringify(result, null, 4));
+    console.log(yamlStringify(result));
 }
 /**
  * Return a plain-text string for commands that are better as short messages,
@@ -117,7 +146,7 @@ function formatPlain(command, result) {
                 const lines = [
                     `Dry run: prepared registry entry ${entry?.name ?? entry?.id ?? "unknown"}`,
                     "",
-                    Bun.YAML.stringify(entry, null, 4),
+                    yamlStringify(entry),
                 ];
                 if (commands.length > 0) {
                     lines.push("", "Would run:");
@@ -139,7 +168,10 @@ function formatPlain(command, result) {
     }
 }
 const initCommand = defineCommand({
-    meta: { name: "init", description: "Initialize Agent-i-Kit's working stash directory and persist stashDir in config" },
+    meta: {
+        name: "init",
+        description: "Initialize Agent-i-Kit's working stash directory and persist stashDir in config",
+    },
     args: {
         dir: { type: "string", description: "Custom stash directory path (default: ~/agentikit)" },
     },
@@ -281,7 +313,7 @@ const showCommand = defineCommand({
                         view = { mode: args.view };
                         break;
                     default:
-                        throw new Error(`Unknown view mode: ${args.view}. Expected one of: full|toc|frontmatter|section|lines`);
+                        throw new UsageError(`Unknown view mode: ${args.view}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
             const result = await agentikitShow({ ref: args.ref, view });
@@ -424,7 +456,7 @@ const configCommand = defineCommand({
             if (args.set) {
                 const eqIndex = args.set.indexOf("=");
                 if (eqIndex === -1) {
-                    throw new Error("--set expects key=value format");
+                    throw new UsageError("--set expects key=value format");
                 }
                 const key = args.set.slice(0, eqIndex);
                 const value = args.set.slice(eqIndex + 1);
@@ -440,7 +472,10 @@ 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" },
+    meta: {
+        name: "clone",
+        description: "Clone an asset from any stash source into the working stash or a custom destination",
+    },
     args: {
         ref: { type: "positional", description: "Asset ref (e.g. @installed:pkg/tool:script.sh)", required: true },
         name: { type: "string", description: "New name for the cloned asset" },
@@ -462,7 +497,11 @@ const cloneCommand = defineCommand({
 const submitCommand = defineCommand({
     meta: { name: "submit", description: "Submit a kit to agentikit-registry by opening a pull request" },
     args: {
-        ref: { type: "positional", description: "Public ref to submit (npm package, owner/repo, or local kit directory)", required: false },
+        ref: {
+            type: "positional",
+            description: "Public ref to submit (npm package, owner/repo, or local kit directory)",
+            required: false,
+        },
         name: { type: "string", description: "Display name for the registry entry" },
         description: { type: "string", description: "Short description for the registry entry" },
         tags: { type: "string", description: "Comma-separated tags" },
@@ -470,8 +509,16 @@ const submitCommand = defineCommand({
         author: { type: "string", description: "Author name" },
         license: { type: "string", description: "License identifier" },
         homepage: { type: "string", description: "Homepage URL" },
-        "dry-run": { type: "boolean", description: "Preview the entry and gh commands without creating a pull request", default: false },
-        "cleanup-fork": { type: "boolean", description: "Show the fork cleanup command after the pull request is created (run it after the PR is merged)", default: false },
+        "dry-run": {
+            type: "boolean",
+            description: "Preview the entry and gh commands without creating a pull request",
+            default: false,
+        },
+        "cleanup-fork": {
+            type: "boolean",
+            description: "Show the fork cleanup command after the pull request is created (run it after the PR is merged)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -509,6 +556,7 @@ const main = defineCommand({
     },
     args: {
         json: { type: "boolean", description: "Output in JSON format", default: false },
+        quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
     },
     subCommands: {
         init: initCommand,
@@ -531,48 +579,43 @@ const SEARCH_SOURCES = ["local", "registry", "both"];
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset", "providers", "use"]);
 // citty reads process.argv directly and does not accept a custom argv array,
 // so we must replace process.argv with the normalized version before runMain.
-const normalizedArgv = [...process.argv];
-normalizeConfigArgv(normalizedArgv);
-process.argv = normalizedArgv;
+process.argv = normalizeConfigArgv(process.argv);
 runMain(main);
 function parseSearchUsageMode(value) {
     if (SEARCH_USAGE_MODES.includes(value))
         return value;
-    throw new Error(`Invalid value for --usage: ${value}. Expected one of: ${SEARCH_USAGE_MODES.join("|")}`);
+    throw new UsageError(`Invalid value for --usage: ${value}. Expected one of: ${SEARCH_USAGE_MODES.join("|")}`);
 }
 function parseSearchSource(value) {
     if (SEARCH_SOURCES.includes(value))
         return value;
-    throw new Error(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`);
+    throw new UsageError(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`);
 }
 // ── Exit codes ──────────────────────────────────────────────────────────────
 const EXIT_GENERAL = 1;
 const EXIT_USAGE = 2;
 const EXIT_CONFIG = 78;
-function classifyExitCode(message) {
-    // Usage / argument errors
-    if (message.includes("required") ||
-        message.includes("Invalid value for") ||
-        message.includes("Expected one of") ||
-        message.includes("expected JSON object")) {
+function classifyExitCode(error) {
+    if (error instanceof UsageError)
         return EXIT_USAGE;
-    }
-    // Configuration errors
-    if (message.includes("No stash directory found") ||
-        message.includes("Unable to determine") ||
-        message.includes("config")) {
+    if (error instanceof ConfigError)
         return EXIT_CONFIG;
-    }
+    if (error instanceof NotFoundError)
+        return EXIT_GENERAL;
     return EXIT_GENERAL;
 }
 async function runWithJsonErrors(fn) {
     try {
+        // Apply --quiet flag early so warnings inside the command are suppressed
+        if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
+            setQuiet(true);
+        }
         await fn();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         const hint = buildHint(message);
-        const exitCode = classifyExitCode(message);
+        const exitCode = classifyExitCode(error);
         console.error(JSON.stringify({ ok: false, error: message, hint }, null, 2));
         process.exit(exitCode);
     }
@@ -600,11 +643,12 @@ function buildHint(message) {
         return "Check that the npm package is published or the GitHub repository is public, then retry.";
     if (message.includes("already exists in agentikit-registry"))
         return "Update the existing registry entry instead of creating a duplicate, or choose a different public ref.";
-    if (message.includes("Unable to infer a public npm or GitHub ref") || message.includes("Unable to infer a publicly accessible npm package or GitHub repository")) {
+    if (message.includes("Unable to infer a public npm or GitHub ref") ||
+        message.includes("Unable to infer a publicly accessible npm package or GitHub repository")) {
         return "Run `akm submit <package-or-owner/repo>` explicitly, or add name/repository metadata to package.json.";
     }
     if (message.includes("expected JSON object with endpoint and model")) {
-        return "Quote JSON values in your shell, for example: akm config set embedding '{\"endpoint\":\"http://localhost:11434/v1/embeddings\",\"model\":\"nomic-embed-text\"}'.";
+        return 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.';
     }
     return undefined;
 }
@@ -618,7 +662,7 @@ function buildGhInstallHint() {
 function parseProviderScope(value) {
     if (value === "embedding" || value === "llm")
         return value;
-    throw new Error(`Invalid provider scope: ${value}. Expected one of: embedding|llm`);
+    throw new UsageError(`Invalid provider scope: ${value}. Expected one of: embedding|llm`);
 }
 function hasConfigSubcommand(args) {
     const command = Array.isArray(args._) ? args._[0] : undefined;
@@ -629,43 +673,37 @@ function hasConfigSubcommand(args) {
  * `akm config llm.maxTokens 512` and `akm config --get llm.maxTokens`
  * are normalized into the existing config subcommands.
  *
- * Operates on a copy of process.argv; the caller replaces process.argv
- * with the normalized result (safer than in-place splice).
+ * Returns a new array; the input is never modified.
  */
 function normalizeConfigArgv(argv) {
-    // Global flags (like --json) should not be treated as config subcommand arguments.
+    // Global flags (like --json, --quiet) should not be treated as config subcommand arguments.
     // We strip them from the analysis portion, normalize, then re-append them.
-    const GLOBAL_FLAGS = new Set(["--json"]);
+    const GLOBAL_FLAGS = new Set(["--json", "--quiet", "-q"]);
     const globalFlags = argv.slice(3).filter((a) => GLOBAL_FLAGS.has(a));
     const configArgs = argv.slice(3).filter((a) => !GLOBAL_FLAGS.has(a));
     const [command, argAfterCommand, argAfterKey, ...rest] = [argv[2], ...configArgs];
     if (command !== "config")
-        return;
+        return argv;
     if (!argAfterCommand)
-        return;
-    const replaceArgs = (...newArgs) => {
-        argv.splice(3, argv.length - 3, ...newArgs, ...globalFlags);
-    };
+        return argv;
+    const prefix = argv.slice(0, 3);
+    const buildResult = (...newArgs) => [...prefix, ...newArgs, ...globalFlags];
     if (argAfterCommand === "--list") {
-        replaceArgs("list");
-        return;
+        return buildResult("list");
     }
     if (argAfterCommand === "--get" && argAfterKey) {
-        replaceArgs("get", argAfterKey, ...rest);
-        return;
+        return buildResult("get", argAfterKey, ...rest);
     }
     if (argAfterCommand === "--unset" && argAfterKey) {
-        replaceArgs("unset", argAfterKey, ...rest);
-        return;
+        return buildResult("unset", argAfterKey, ...rest);
     }
     if (argAfterCommand.startsWith("-"))
-        return;
+        return argv;
     if (CONFIG_SUBCOMMAND_SET.has(argAfterCommand))
-        return;
+        return argv;
     // A single arg after `config` behaves like `git config <key>` and reads the value.
     if (argAfterKey === undefined) {
-        replaceArgs("get", argAfterCommand);
-        return;
+        return buildResult("get", argAfterCommand);
     }
-    replaceArgs("set", argAfterCommand, argAfterKey, ...rest);
+    return buildResult("set", argAfterCommand, argAfterKey, ...rest);
 }

package/dist/common.js

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
+import { ConfigError } from "./errors";
 import { getConfigPath, getDefaultStashDir } from "./paths";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
-export { SCRIPT_EXTENSIONS, TYPE_DIRS } from "./asset-spec";
 // ── Validators ──────────────────────────────────────────────────────────────
 export function isAssetType(type) {
     return type in TYPE_DIRS;
@@ -36,7 +36,7 @@ export function resolveStashDir(options) {
     if (isValidDirectory(defaultDir)) {
         return defaultDir;
     }
-    throw new Error(`No stash directory found. Run "akm init" to create one at ${defaultDir}, ` +
+    throw new ConfigError(`No stash directory found. Run "akm init" to create one at ${defaultDir}, ` +
         `or set stashDir in ${getConfigPath()}.`);
 }
 function validateStashDir(raw) {
@@ -46,10 +46,10 @@ function validateStashDir(raw) {
         stat = fs.statSync(stashDir);
     }
     catch {
-        throw new Error(`Unable to read stash directory at "${stashDir}".`);
+        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`);
     }
     if (!stat.isDirectory()) {
-        throw new Error(`Stash path must point to a directory: "${stashDir}".`);
+        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`);
     }
     return stashDir;
 }
@@ -165,7 +165,7 @@ export async function fetchWithRetry(url, init, options) {
             const response = await fetchWithTimeout(url, init, timeout);
             if (attempt < maxRetries && shouldRetry(response.status)) {
                 const retryAfter = parseRetryAfter(response);
-                const delay = retryAfter ?? baseDelay * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
+                const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
                 await new Promise((r) => setTimeout(r, delay));
                 continue;
             }
@@ -174,7 +174,7 @@ export async function fetchWithRetry(url, init, options) {
         catch (err) {
             if (attempt >= maxRetries)
                 throw err;
-            const delay = baseDelay * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
+            const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
             await new Promise((r) => setTimeout(r, delay));
         }
     }

package/dist/config-cli.js

@@ -1,5 +1,6 @@
 import { DEFAULT_CONFIG, } from "./config";
 import { EMBEDDING_DIM } from "./db";
+import { ConfigError, UsageError } from "./errors";
 const LOCAL_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_LLM_TEMPERATURE = 0.3;
 const DEFAULT_LLM_MAX_TOKENS = 512;
@@ -63,25 +64,25 @@ export function parseConfigValue(key, value) {
             return { stashDir: requireNonEmptyString(value, key) };
         case "semanticSearch":
             if (value !== "true" && value !== "false") {
-                throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`);
+                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 Error("expected JSON array");
+                    throw new UsageError("expected JSON array");
                 return { searchPaths: parsed.filter((d) => typeof d === "string") };
             }
             catch {
-                throw new Error(`Invalid value for searchPaths: expected JSON array (e.g. '["/path/a","/path/b"]')`);
+                throw new UsageError(`Invalid value for searchPaths: expected JSON array (e.g. '["/path/a","/path/b"]')`);
             }
         case "embedding":
             return { embedding: parseEmbeddingConnectionValue(value) };
         case "llm":
             return { llm: parseLlmConnectionValue(value) };
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function getConfigValue(config, key) {
@@ -119,7 +120,7 @@ export function getConfigValue(config, key) {
         case "llm.apiKey":
             return maskSecret(getLlmDisplayConfig(config).apiKey) ?? null;
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function setConfigValue(config, key, rawValue) {
@@ -207,7 +208,7 @@ export function setConfigValue(config, key, rawValue) {
                 },
             };
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function unsetConfigValue(config, key) {
@@ -247,7 +248,7 @@ export function unsetConfigValue(config, key) {
                 return config;
             return { ...config, llm: omitKey(config.llm, "provider") };
         default:
-            throw new Error(`Unknown or unsupported unset key: ${key}`);
+            throw new UsageError(`Unknown or unsupported unset key: ${key}`);
     }
 }
 export function listConfig(config) {
@@ -273,7 +274,7 @@ export function useProvider(config, scope, providerName) {
     if (scope === "embedding") {
         const preset = EMBEDDING_PROVIDER_PRESETS[providerName];
         if (!preset) {
-            throw new Error(`Unknown embedding provider: ${providerName}`);
+            throw new UsageError(`Unknown embedding provider: ${providerName}`);
         }
         if (!preset.config) {
             return { ...config, embedding: undefined };
@@ -282,7 +283,7 @@ export function useProvider(config, scope, providerName) {
     }
     const preset = LLM_PROVIDER_PRESETS[providerName];
     if (!preset) {
-        throw new Error(`Unknown llm provider: ${providerName}`);
+        throw new UsageError(`Unknown llm provider: ${providerName}`);
     }
     if (!preset.config) {
         return { ...config, llm: undefined };
@@ -388,68 +389,65 @@ function parseJsonObject(value, key, example) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new Error(`Invalid value for ${key}: expected JSON object with endpoint and model`
-            + ` (e.g. '{"endpoint":"${example.endpoint}","model":"${example.model}"}')`);
+        throw new UsageError(`Invalid value for ${key}: expected JSON object with endpoint and model` +
+            ` (e.g. '{"endpoint":"${example.endpoint}","model":"${example.model}"}')`);
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Invalid value for ${key}: expected a JSON object`);
+        throw new UsageError(`Invalid value for ${key}: expected a JSON object`);
     }
     return parsed;
 }
 function asRequiredString(value, key, field) {
     if (typeof value !== "string" || !value) {
-        throw new Error(`Invalid value for ${key}: "${field}" is a required string field`);
+        throw new UsageError(`Invalid value for ${key}: "${field}" is a required string field`);
     }
     return value;
 }
 function requireEmbeddingConfig(config) {
     if (!config.embedding) {
-        throw new Error("Embedding provider is using the built-in local default. Run `akm config use embedding <provider>` first.");
+        throw new ConfigError("Embedding provider is using the built-in local default. Run `akm config use embedding <provider>` first.");
     }
     return config.embedding;
 }
 function requireLlmConfig(config) {
     if (!config.llm) {
-        throw new Error("LLM provider is disabled. Run `akm config use llm <provider>` first.");
+        throw new ConfigError("LLM provider is disabled. Run `akm config use llm <provider>` first.");
     }
     return config.llm;
 }
 function requireNonEmptyString(value, key) {
     if (!value) {
-        throw new Error(`Invalid value for ${key}: expected a non-empty string`);
+        throw new UsageError(`Invalid value for ${key}: expected a non-empty string`);
     }
     return value;
 }
 function parseNumber(value, key) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed)) {
-        throw new Error(`Invalid value for ${key}: expected a number`);
+        throw new UsageError(`Invalid value for ${key}: expected a number`);
     }
     return parsed;
 }
 function parsePositiveInteger(value, key) {
     const trimmed = value.trim();
     if (!/^[1-9]\d*$/.test(trimmed)) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     const parsed = Number(trimmed);
     if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     return parsed;
 }
 function parseUnknownNumber(value, key) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new Error(`Invalid value for ${key}: expected a number`);
+        throw new UsageError(`Invalid value for ${key}: expected a number`);
     }
     return value;
 }
 function parseUnknownPositiveInteger(value, key) {
-    if (typeof value !== "number" ||
-        !Number.isFinite(value) ||
-        !Number.isInteger(value) ||
-        value <= 0) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     return value;
 }

package/dist/config.js

@@ -68,7 +68,9 @@ export function saveConfig(config) {
         try {
             fs.unlinkSync(tmpPath);
         }
-        catch { /* ignore cleanup failure */ }
+        catch {
+            /* ignore cleanup failure */
+        }
         throw err;
     }
 }