akm-cli 0.1.2 → 0.2.0

package/README.md

@@ -25,12 +25,15 @@ Upgrade in place with `akm upgrade`.
 ## Quick Start
 
 ```sh
-akm init                          # Initialize your working stash
+akm setup                         # Guided setup: configure, initialize, and index
 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
 ```
 
+If you want to skip the wizard, `akm init --dir ~/custom-stash` initializes the
+working stash at a custom path.
+
 ## Features
 
 ### Works with Any AI Agent

package/dist/asset-registry.js

@@ -0,0 +1,48 @@
+/**
+ * Central registry for asset type renderer and action builder maps.
+ *
+ * Previously these maps lived in `local-search.ts` and were wired into
+ * `asset-spec.ts` via a fragile `_setAssetTypeHooks` deferred callback
+ * pattern. If `local-search.ts` was imported after `registerAssetType()`
+ * calls, hooks would be silently dropped.
+ *
+ * This module is a simple singleton that both `asset-spec.ts` and
+ * `local-search.ts` import from, eliminating the import-order dependency
+ * entirely.
+ */
+/** Map asset types to their primary renderer names. */
+export const TYPE_TO_RENDERER = {
+    script: "script-source",
+    skill: "skill-md",
+    command: "command-md",
+    agent: "agent-md",
+    knowledge: "knowledge-md",
+    memory: "memory-md",
+};
+/** Map asset types to action builder functions for search results. */
+export const ACTION_BUILDERS = {
+    script: (ref) => `akm show ${ref} -> execute the run command`,
+    skill: (ref) => `akm show ${ref} -> follow the instructions`,
+    command: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
+    agent: (ref) => `akm show ${ref} -> dispatch with full prompt`,
+    knowledge: (ref) => `akm show ${ref} -> read reference material`,
+    memory: (ref) => `akm show ${ref} -> recall context`,
+};
+/**
+ * Register a type-to-renderer mapping.
+ *
+ * Called by `registerAssetType()` in `asset-spec.ts` when a spec includes
+ * `rendererName`, or directly by extension code.
+ */
+export function registerTypeRenderer(type, rendererName) {
+    TYPE_TO_RENDERER[type] = rendererName;
+}
+/**
+ * Register an action builder for an asset type.
+ *
+ * Called by `registerAssetType()` in `asset-spec.ts` when a spec includes
+ * `actionBuilder`, or directly by extension code.
+ */
+export function registerActionBuilder(type, builder) {
+    ACTION_BUILDERS[type] = builder;
+}

package/dist/asset-spec.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
 import { toPosix } from "./common";
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
@@ -56,28 +57,6 @@ const ASSET_SPECS_INTERNAL = {
     memory: { stashDir: "memories", ...markdownSpec },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
-/**
- * Deferred hooks set by `local-search.ts` at module init time to avoid a
- * circular dependency (asset-spec → local-search → asset-spec).
- *
- * When `registerAssetType` is called with a spec that includes `rendererName`
- * or `actionBuilder`, these hooks are invoked automatically so callers only
- * need a single `registerAssetType(type, spec)` call to fully register a new
- * asset type — no separate `registerTypeRenderer`/`registerActionBuilder` calls
- * are required.
- */
-let _registerTypeRenderer;
-let _registerActionBuilder;
-/**
- * Called once by `local-search.ts` during module initialization to wire in the
- * renderer and action-builder registration hooks.
- *
- * @internal — not part of the public extension API; use `registerAssetType` instead.
- */
-export function _setAssetTypeHooks(rendererHook, actionBuilderHook) {
-    _registerTypeRenderer = rendererHook;
-    _registerActionBuilder = actionBuilderHook;
-}
 /**
  * Register a custom asset type with the akm asset system.
  *
@@ -109,27 +88,27 @@ export function _setAssetTypeHooks(rendererHook, actionBuilderHook) {
  * });
  * ```
  *
- * If `rendererName` or `actionBuilder` is provided but the hooks have not yet
- * been wired (i.e. `local-search.ts` has not been imported), the values are
- * stored in the spec and will take effect once the hooks are set.
+ * Renderer and action builder registration is handled directly via the
+ * `asset-registry` singleton — no deferred hooks or import-order concerns.
  */
 export function registerAssetType(type, spec) {
     ASSET_SPECS_INTERNAL[type] = spec;
     TYPE_DIRS[type] = spec.stashDir;
-    ASSET_TYPES = getAssetTypes();
+    ASSET_TYPES.length = 0;
+    ASSET_TYPES.push(...getAssetTypes());
     // Auto-register renderer and action builder if provided in spec
-    if (spec.rendererName && _registerTypeRenderer) {
-        _registerTypeRenderer(type, spec.rendererName);
+    if (spec.rendererName) {
+        registerTypeRenderer(type, spec.rendererName);
     }
-    if (spec.actionBuilder && _registerActionBuilder) {
-        _registerActionBuilder(type, spec.actionBuilder);
+    if (spec.actionBuilder) {
+        registerActionBuilder(type, spec.actionBuilder);
     }
 }
 export function getAssetTypes() {
     return Object.keys(ASSET_SPECS_INTERNAL);
 }
-/** Warning: mutable `let` — stale if captured before `registerAssetType()` calls. Prefer `getAssetTypes()`. */
-export let ASSET_TYPES = getAssetTypes();
+/** Warning: mutable array — stale if captured before `registerAssetType()` calls. Prefer `getAssetTypes()`. */
+export const ASSET_TYPES = getAssetTypes();
 export const TYPE_DIRS = Object.fromEntries(Object.entries(ASSET_SPECS_INTERNAL).map(([type, spec]) => [type, spec.stashDir]));
 export function isRelevantAssetFile(assetType, fileName) {
     return ASSET_SPECS[assetType]?.isRelevantFile(fileName) ?? false;

package/dist/cli.js

@@ -6,8 +6,10 @@ import { resolveStashDir } from "./common";
 import { generateBashCompletions, installBashCompletions } from "./completions";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./config-cli";
+import { closeDatabase, openDatabase } from "./db";
 import { ConfigError, NotFoundError, UsageError } from "./errors";
 import { akmIndex } from "./indexer";
+import { assembleInfo } from "./info";
 import { akmInit } from "./init";
 import { akmList, akmRemove, akmUpdate } from "./installed-kits";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
@@ -19,42 +21,15 @@ 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 { insertUsageEvent } from "./usage-events";
+import { pkgVersion } from "./version";
 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";
-})();
-const OUTPUT_FORMATS = ["json", "yaml", "text"];
-const DETAIL_LEVELS = ["brief", "normal", "full"];
+const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
+const DETAIL_LEVELS = ["brief", "normal", "full", "summary"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
 const CONTEXT_HUB_ALIAS_REF = "context-hub";
 const CONTEXT_HUB_ALIAS_URL = "https://github.com/andrewyng/context-hub";
-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);
-}
+import { stringify as yamlStringify } from "yaml";
 function parseOutputFormat(value) {
     if (!value)
         return undefined;
@@ -79,15 +54,25 @@ function parseFlagValue(flag) {
     }
     return undefined;
 }
+// Uses process.argv directly because the global output() function (called by all
+// commands) needs this flag but doesn't have access to citty's parsed args.
+function hasBooleanFlag(flag) {
+    return process.argv.some((arg) => arg === flag || arg === `${flag}=true`);
+}
 function resolveOutputMode() {
     const config = loadConfig();
     const format = parseOutputFormat(parseFlagValue("--format")) ?? config.output?.format ?? "json";
     const detail = parseDetailLevel(parseFlagValue("--detail")) ?? config.output?.detail ?? "brief";
-    return { format, detail };
+    const forAgent = hasBooleanFlag("--for-agent");
+    return { format, detail, forAgent };
 }
 function output(command, result) {
     const mode = resolveOutputMode();
-    const shaped = shapeForCommand(command, result, mode.detail);
+    const shaped = shapeForCommand(command, result, mode.detail, mode.forAgent);
+    if (mode.format === "jsonl") {
+        outputJsonl(command, shaped);
+        return;
+    }
     switch (mode.format) {
         case "json":
             console.log(JSON.stringify(shaped, null, 2));
@@ -102,27 +87,57 @@ function output(command, result) {
         }
     }
 }
-function shapeForCommand(command, result, detail) {
+function outputJsonl(command, shaped) {
+    if (command === "search" || command === "registry-search") {
+        const r = shaped;
+        const hits = Array.isArray(r.hits) ? r.hits : [];
+        for (const hit of hits) {
+            console.log(JSON.stringify(hit));
+        }
+        const registryHits = Array.isArray(r.registryHits) ? r.registryHits : [];
+        for (const hit of registryHits) {
+            console.log(JSON.stringify(hit));
+        }
+        return;
+    }
+    // For non-search commands, output the whole object as a single JSONL line
+    console.log(JSON.stringify(shaped));
+}
+function shapeForCommand(command, result, detail, forAgent = false) {
     switch (command) {
         case "search":
-            return shapeSearchOutput(result, detail);
+            return shapeSearchOutput(result, detail, forAgent);
         case "registry-search":
             return shapeRegistrySearchOutput(result, detail);
         case "show":
-            return shapeShowOutput(result, detail);
+            return shapeShowOutput(result, detail, forAgent);
         default:
             return result;
     }
 }
-function shapeSearchOutput(result, detail) {
+function shapeSearchOutput(result, detail, forAgent = false) {
     const hits = Array.isArray(result.hits) ? result.hits : [];
-    const shapedHits = hits.map((hit) => shapeSearchHit(hit, detail));
+    const registryHits = Array.isArray(result.registryHits) ? result.registryHits : [];
+    const shapedHits = forAgent
+        ? hits.map((hit) => shapeSearchHitForAgent(hit))
+        : hits.map((hit) => shapeSearchHit(hit, detail));
+    const shapedRegistryHits = forAgent
+        ? registryHits.map((hit) => shapeSearchHitForAgent(hit))
+        : registryHits.map((hit) => shapeSearchHit(hit, detail));
+    if (forAgent) {
+        return {
+            hits: shapedHits,
+            ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
+            ...(result.tip ? { tip: result.tip } : {}),
+        };
+    }
     if (detail === "full") {
         return {
             schemaVersion: result.schemaVersion,
             stashDir: result.stashDir,
             source: result.source,
             hits: shapedHits,
+            ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
             ...(result.tip ? { tip: result.tip } : {}),
             ...(result.warnings ? { warnings: result.warnings } : {}),
             ...(result.timing ? { timing: result.timing } : {}),
@@ -130,6 +145,7 @@ function shapeSearchOutput(result, detail) {
     }
     return {
         hits: shapedHits,
+        ...(shapedRegistryHits.length > 0 ? { registryHits: shapedRegistryHits } : {}),
         ...(result.tip ? { tip: result.tip } : {}),
         ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
     };
@@ -153,9 +169,9 @@ function shapeRegistrySearchOutput(result, detail) {
 }
 function shapeAssetHit(hit, detail) {
     if (detail === "brief")
-        return pickFields(hit, ["assetName", "assetType", "action"]);
+        return pickFields(hit, ["assetName", "assetType", "action", "estimatedTokens"]);
     if (detail === "normal") {
-        return capDescription(pickFields(hit, ["assetName", "assetType", "description", "kit", "action"]), NORMAL_DESCRIPTION_LIMIT);
+        return capDescription(pickFields(hit, ["assetName", "assetType", "description", "kit", "action", "estimatedTokens"]), NORMAL_DESCRIPTION_LIMIT);
     }
     return hit;
 }
@@ -170,12 +186,17 @@ function shapeSearchHit(hit, detail) {
     }
     // Stash hit (local or remote)
     if (detail === "brief")
-        return pickFields(hit, ["type", "name", "action"]);
+        return pickFields(hit, ["type", "name", "action", "estimatedTokens"]);
     if (detail === "normal") {
-        return capDescription(pickFields(hit, ["type", "name", "description", "action", "score"]), NORMAL_DESCRIPTION_LIMIT);
+        return capDescription(pickFields(hit, ["type", "name", "description", "action", "score", "estimatedTokens"]), NORMAL_DESCRIPTION_LIMIT);
     }
     return hit;
 }
+/** Agent-optimized search hit: only fields an LLM agent needs to decide and act */
+function shapeSearchHitForAgent(hit) {
+    const picked = pickFields(hit, ["name", "ref", "type", "description", "action", "score", "estimatedTokens"]);
+    return capDescription(picked, NORMAL_DESCRIPTION_LIMIT);
+}
 function capDescription(hit, limit) {
     if (typeof hit.description !== "string")
         return hit;
@@ -190,13 +211,35 @@ function truncateDescription(description, limit) {
     const safe = lastSpace >= Math.floor(limit * 0.6) ? truncated.slice(0, lastSpace) : truncated;
     return `${safe.trimEnd()}...`;
 }
-function shapeShowOutput(result, detail) {
+function shapeShowOutput(result, detail, forAgent = false) {
+    if (forAgent) {
+        return pickFields(result, [
+            "type",
+            "name",
+            "description",
+            "action",
+            "content",
+            "template",
+            "prompt",
+            "run",
+            "setup",
+            "cwd",
+            "toolPolicy",
+            "modelHint",
+            "agent",
+            "parameters",
+        ]);
+    }
+    if (detail === "summary") {
+        return pickFields(result, ["type", "name", "description", "tags", "parameters", "action", "run", "origin"]);
+    }
     const base = pickFields(result, [
         "type",
         "name",
         "origin",
         "action",
         "description",
+        "tags",
         "content",
         "template",
         "prompt",
@@ -342,11 +385,13 @@ function formatPlain(command, result, detail) {
 }
 function formatSearchPlain(r, detail) {
     const hits = r.hits ?? [];
-    if (hits.length === 0) {
+    const registryHits = r.registryHits ?? [];
+    const allHits = [...hits, ...registryHits];
+    if (allHits.length === 0) {
         return r.tip ? String(r.tip) : "No results found.";
     }
     const lines = [];
-    for (const hit of hits) {
+    for (const hit of allHits) {
         const type = hit.type ?? "unknown";
         const name = hit.name ?? "unnamed";
         const score = hit.score != null ? ` (score: ${hit.score})` : "";
@@ -405,6 +450,18 @@ function formatSearchPlain(r, detail) {
  * - registry-*  : Kit discovery from remote registries (npm, GitHub)
  * - installed-kits : Management of kits already installed locally
  */
+const setupCommand = defineCommand({
+    meta: {
+        name: "setup",
+        description: "Interactive configuration wizard for embeddings, LLM, registries, and stash sources",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const { runSetupWizard } = await import("./setup");
+            await runSetupWizard();
+        });
+    },
+});
 const initCommand = defineCommand({
     meta: {
         name: "init",
@@ -432,6 +489,15 @@ const indexCommand = defineCommand({
         });
     },
 });
+const infoCommand = defineCommand({
+    meta: { name: "info", description: "Show system capabilities, configuration, and index stats as JSON" },
+    run() {
+        return runWithJsonErrors(() => {
+            const result = assembleInfo();
+            output("info", result);
+        });
+    },
+});
 const searchCommand = defineCommand({
     meta: { name: "search", description: "Search the stash" },
     args: {
@@ -442,8 +508,8 @@ const searchCommand = defineCommand({
         },
         limit: { type: "string", description: "Maximum number of results" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
-        format: { type: "string", description: "Output format (json|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full|summary)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -574,8 +640,8 @@ const showCommand = defineCommand({
     },
     args: {
         ref: { type: "positional", description: "Asset ref (type:name)", required: true },
-        format: { type: "string", description: "Output format (json|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full|summary)" },
         akmView: { type: "string", description: "Internal positional knowledge view mode parser" },
         akmHeading: { type: "string", description: "Internal positional section heading parser" },
         akmStart: { type: "string", description: "Internal positional start-line parser" },
@@ -605,7 +671,10 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${args.akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            const result = await akmShowUnified({ ref: args.ref, view });
+            // Map CLI detail level to ShowDetailLevel for the show function
+            const cliDetail = resolveOutputMode().detail;
+            const showDetail = cliDetail === "summary" ? "summary" : undefined;
+            const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail });
             output("show", result);
         });
     },
@@ -920,6 +989,47 @@ const stashCommand = defineCommand({
     meta: { name: "stash", description: "Manage additional stashes (local directories and remote providers)" },
     subCommands: buildSourceSubCommands("stash"),
 });
+const feedbackCommand = defineCommand({
+    meta: {
+        name: "feedback",
+        description: "Record positive or negative feedback for a stash asset",
+    },
+    args: {
+        ref: { type: "positional", description: "Asset ref (type:name)", required: true },
+        positive: { type: "boolean", description: "Record positive feedback", default: false },
+        negative: { type: "boolean", description: "Record negative feedback", default: false },
+        note: { type: "string", description: "Optional note to attach to the feedback" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const ref = args.ref.trim();
+            if (!ref) {
+                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative");
+            }
+            if (args.positive && args.negative) {
+                throw new UsageError("Specify either --positive or --negative, not both.");
+            }
+            if (!args.positive && !args.negative) {
+                throw new UsageError("Specify --positive or --negative.");
+            }
+            const signal = args.positive ? "positive" : "negative";
+            const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
+            const db = openDatabase();
+            try {
+                insertUsageEvent(db, {
+                    event_type: "feedback",
+                    entry_ref: ref,
+                    signal,
+                    metadata,
+                });
+            }
+            finally {
+                closeDatabase(db);
+            }
+            output("feedback", { ok: true, ref, signal, note: args.note ?? null });
+        });
+    },
+});
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -977,8 +1087,10 @@ const main = defineCommand({
         quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
     },
     subCommands: {
+        setup: setupCommand,
         init: initCommand,
         index: indexCommand,
+        info: infoCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -991,6 +1103,7 @@ const main = defineCommand({
         stash: stashCommand,
         registry: registryCommand,
         config: configCommand,
+        feedback: feedbackCommand,
         hints: hintsCommand,
         completions: completionsCommand,
     },
@@ -1044,9 +1157,9 @@ function buildHint(message) {
     if (message.includes("Invalid value for --source"))
         return "Pick one of: stash, registry, both.";
     if (message.includes("Invalid value for --format"))
-        return "Pick one of: json, text, yaml.";
+        return "Pick one of: json, jsonl, text, yaml.";
     if (message.includes("Invalid value for --detail"))
-        return "Pick one of: brief, normal, full.";
+        return "Pick one of: brief, normal, full, summary.";
     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"}\'.';
     }
@@ -1082,7 +1195,7 @@ function normalizeShowArgv(argv) {
     const showArgs = [];
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
-        if (arg === "--quiet" || arg === "-q") {
+        if (arg === "--quiet" || arg === "-q" || arg === "--for-agent" || arg === "--for-agent=true") {
             globalFlags.push(arg);
             continue;
         }
@@ -1191,8 +1304,9 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 | \`--type\` | \`skill\`, \`command\`, \`agent\`, \`knowledge\`, \`script\`, \`memory\`, \`any\` | \`any\` |
 | \`--source\` | \`stash\`, \`registry\`, \`both\` | \`stash\` |
 | \`--limit\` | number | \`20\` |
-| \`--format\` | \`json\`, \`text\`, \`yaml\` | \`json\` |
-| \`--detail\` | \`brief\`, \`normal\`, \`full\` | \`brief\` |
+| \`--format\` | \`json\`, \`jsonl\`, \`text\`, \`yaml\` | \`json\` |
+| \`--detail\` | \`brief\`, \`normal\`, \`full\`, \`summary\` | \`brief\` |
+| \`--for-agent\` | boolean | \`false\` |
 
 ## Show
 
@@ -1206,7 +1320,7 @@ akm show agent:architect                      # Show agent (returns system promp
 akm show knowledge:guide toc                  # Table of contents
 akm show knowledge:guide section "Auth"       # Specific section
 akm show knowledge:guide lines 10 30          # Line range
-akm show viking://resources/my-doc           # Show remote OpenViking content
+akm show knowledge:my-doc                    # Show content (local or remote)
 \`\`\`
 
 | Type | Key fields returned |
@@ -1294,11 +1408,14 @@ akm completions --install                     # Install completions
 All commands accept \`--format\` and \`--detail\` flags:
 
 - \`--format json\` (default) — structured JSON
+- \`--format jsonl\` — one JSON object per line (streaming-friendly)
 - \`--format text\` — human-readable plain text
 - \`--format yaml\` — YAML output
 - \`--detail brief\` (default) — compact output
 - \`--detail normal\` — adds tags, refs, origins
 - \`--detail full\` — includes scores, paths, timing, debug info
+- \`--detail summary\` — metadata only (no content/template/prompt), under 200 tokens
+- \`--for-agent\` — agent-optimized output: strips non-actionable fields (takes precedence over \`--detail\`)
 
 Run \`akm -h\` or \`akm <command> -h\` for per-command help.
 `;

package/dist/completions.js

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { getAssetTypes } from "./asset-spec";
 // ── Known flag values ────────────────────────────────────────────────────────
 const FLAG_VALUES = {
     "--format": ["json", "text", "yaml"],
     "--detail": ["brief", "normal", "full"],
-    "--type": ["skill", "command", "agent", "knowledge", "script", "memory", "any"],
+    "--type": () => [...getAssetTypes(), "any"],
     "--source": ["stash", "registry", "both"],
     "--shell": ["bash"],
 };
@@ -57,7 +58,8 @@ export function generateBashCompletions(cmd) {
     }
     // Build flag-value completion cases
     const valueCases = [];
-    for (const [flag, values] of Object.entries(FLAG_VALUES)) {
+    for (const [flag, valuesOrFn] of Object.entries(FLAG_VALUES)) {
+        const values = typeof valuesOrFn === "function" ? valuesOrFn() : valuesOrFn;
         valueCases.push(`    ${flag})
       COMPREPLY=( $(compgen -W "${values.join(" ")}" -- "\${cur}") )
       return 0

package/dist/config.js

@@ -22,6 +22,9 @@ export function getConfigPath() {
 }
 // ── Load / Save / Update ────────────────────────────────────────────────────
 let cachedConfig;
+export function resetConfigCache() {
+    cachedConfig = undefined;
+}
 export function loadConfig() {
     const configPath = getConfigPath();
     let stat;
@@ -184,10 +187,11 @@ const URL_FIELD_NAMES = new Set(["url", "endpoint", "artifactUrl"]);
  */
 function expandEnvVars(value, fieldName) {
     if (typeof value === "string") {
-        // Skip URL-type fields by name or by value prefix
-        if ((fieldName !== undefined && URL_FIELD_NAMES.has(fieldName)) ||
-            value.startsWith("http://") ||
-            value.startsWith("https://")) {
+        // Skip URL-type fields by name or by value prefix, unless they contain ${VAR} syntax
+        if (!value.includes("${") &&
+            ((fieldName !== undefined && URL_FIELD_NAMES.has(fieldName)) ||
+                value.startsWith("http://") ||
+                value.startsWith("https://"))) {
             return value;
         }
         return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
@@ -274,14 +278,35 @@ function parseEmbeddingConfig(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
-    if (typeof obj.endpoint !== "string" || !obj.endpoint)
+    // Extract localModel early — it's valid even without a remote endpoint
+    const localModel = typeof obj.localModel === "string" && obj.localModel ? obj.localModel : undefined;
+    // If no endpoint is provided, the config is only valid when localModel is set
+    // (local-only embedding configuration).
+    // Sentinel: { endpoint: "", model: "" } means "local-only" — use hasRemoteEndpoint()
+    // (in embedder.ts) to distinguish from a real remote config. Do NOT check
+    // endpoint/model directly in consuming code.
+    if (typeof obj.endpoint !== "string" || !obj.endpoint) {
+        if (localModel) {
+            return { endpoint: "", model: "", localModel };
+        }
         return undefined;
+    }
     if (!obj.endpoint.startsWith("http://") && !obj.endpoint.startsWith("https://")) {
         console.warn(`[akm] Ignoring embedding config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
+        // Still return localModel-only config if localModel was set
+        if (localModel) {
+            return { endpoint: "", model: "", localModel };
+        }
         return undefined;
     }
-    if (typeof obj.model !== "string" || !obj.model)
+    if (typeof obj.model !== "string" || !obj.model) {
+        // No remote model, but localModel may still be valid
+        if (localModel) {
+            console.warn(`[akm] Embedding endpoint "${obj.endpoint}" ignored: model is required for remote embeddings. Using local model only.`);
+            return { endpoint: "", model: "", localModel };
+        }
         return undefined;
+    }
     const result = {
         endpoint: obj.endpoint,
         model: obj.model,
@@ -301,6 +326,9 @@ function parseEmbeddingConfig(value) {
     if (typeof obj.apiKey === "string" && obj.apiKey) {
         result.apiKey = obj.apiKey;
     }
+    if (localModel) {
+        result.localModel = localModel;
+    }
     return result;
 }
 function parseLlmConfig(value) {