akm-cli 0.0.21 → 0.0.23

package/README.md

@@ -7,8 +7,8 @@
 [![license](https://img.shields.io/npm/l/akm-cli)](LICENSE)
 
 A package manager for AI agent capabilities -- scripts, skills, commands,
-agents, and knowledge -- that works with any AI coding assistant that can run
-shell commands.
+agents, knowledge, and memories -- that works with any AI coding assistant that
+can run shell commands.
 
 ## Install
 
@@ -42,7 +42,7 @@ Any model that can run shell commands can use `akm`. Add this to your
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
-and knowledge documents via the `akm` CLI. Use `akm -h` for details.
+knowledge, and memories via the `akm` CLI. Use `akm -h` for details.
 ~~~
 
 No plugins, SDKs, or integration code required. Platform-specific plugins
@@ -89,13 +89,16 @@ 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 \
+  --options '{"apiKey":"key"}'                                            # Add an OpenViking stash source
 akm registry list                                                        # List configured registries
+akm show viking://resources/my-doc                                       # Fetch remote content from OpenViking
 ```
 
 Private access is supported through:
 - **GitHub tokens** -- Set `GITHUB_TOKEN` to access private GitHub repos when installing kits
-- **Provider options** -- Each registry entry supports an `options` field for provider-specific configuration (tokens, custom headers)
-- **Pluggable providers** -- Custom registry providers can implement their own authentication
+- **Provider options** -- `--options` flag accepts JSON for provider-specific configuration (API keys, custom headers)
+- **Pluggable providers** -- Built-in registry providers include `static-index` and `skills-sh`; stash providers include `filesystem` and `openviking`; custom providers can implement their own authentication
 
 See the [Registry docs](docs/registry.md) for hosting your own registry and
 the v2 index format.

package/dist/asset-spec.js

@@ -37,7 +37,7 @@ const scriptSpec = {
     toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
     toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 };
-export const ASSET_SPECS = {
+const ASSET_SPECS_INTERNAL = {
     skill: {
         stashDir: "skills",
         isRelevantFile: (fileName) => fileName === "SKILL.md",
@@ -53,24 +53,105 @@ export const ASSET_SPECS = {
     agent: { stashDir: "agents", ...markdownSpec },
     knowledge: { stashDir: "knowledge", ...markdownSpec },
     script: { stashDir: "scripts", ...scriptSpec },
+    memory: { stashDir: "memories", ...markdownSpec },
 };
-export const ASSET_TYPES = Object.keys(ASSET_SPECS);
-export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
-    acc[type] = ASSET_SPECS[type].stashDir;
-    return acc;
-}, {});
+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 Agentikit asset system.
+ *
+ * ## Full extension registration API
+ *
+ * Providing `rendererName` and/or `actionBuilder` in the spec automatically
+ * registers the renderer and action builder so that search results and `show`
+ * output work out of the box without additional calls.
+ *
+ * ### Minimal registration (filesystem layout only)
+ * ```ts
+ * registerAssetType("widget", {
+ *   stashDir: "widgets",
+ *   isRelevantFile: (f) => f.endsWith(".widget"),
+ *   toCanonicalName: (root, fp) => path.basename(fp, ".widget"),
+ *   toAssetPath: (root, name) => path.join(root, `${name}.widget`),
+ * });
+ * ```
+ *
+ * ### Full registration (filesystem + renderer + action)
+ * ```ts
+ * registerAssetType("widget", {
+ *   stashDir: "widgets",
+ *   isRelevantFile: (f) => f.endsWith(".widget"),
+ *   toCanonicalName: (root, fp) => path.basename(fp, ".widget"),
+ *   toAssetPath: (root, name) => path.join(root, `${name}.widget`),
+ *   rendererName: "widget-md",        // registered via registerRenderer() separately
+ *   actionBuilder: (ref) => `akm show ${ref} -> use widget`,
+ * });
+ * ```
+ *
+ * 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.
+ */
+export function registerAssetType(type, spec) {
+    ASSET_SPECS_INTERNAL[type] = spec;
+    TYPE_DIRS[type] = spec.stashDir;
+    ASSET_TYPES = getAssetTypes();
+    // Auto-register renderer and action builder if provided in spec
+    if (spec.rendererName && _registerTypeRenderer) {
+        _registerTypeRenderer(type, spec.rendererName);
+    }
+    if (spec.actionBuilder && _registerActionBuilder) {
+        _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();
+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);
+    return ASSET_SPECS[assetType]?.isRelevantFile(fileName) ?? false;
 }
 export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
-    return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
+    return ASSET_SPECS[assetType]?.toCanonicalName(typeRoot, filePath);
 }
 export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, filePath) {
     const relPath = toPosix(path.relative(stashRoot, filePath));
-    const firstSegment = relPath.split("/").filter(Boolean)[0];
+    const segments = relPath.split("/").filter(Boolean);
+    const firstSegment = segments[0];
+    // When the first segment matches the canonical type dir (e.g. "agents"),
+    // use it as the type root so canonical names are relative to it.
+    // Otherwise fall back to stashRoot — this preserves the full relative path
+    // as the canonical name, which is correct for installed kits that live
+    // under custom directories (e.g. "tools/agents/svelte-file-editor").
     const typeRoot = firstSegment === TYPE_DIRS[assetType] ? path.join(stashRoot, firstSegment) : stashRoot;
     return deriveCanonicalAssetName(assetType, typeRoot, filePath);
 }
 export function resolveAssetPathFromName(assetType, typeRoot, name) {
-    return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
+    const spec = ASSET_SPECS[assetType];
+    if (!spec)
+        throw new Error(`Unknown asset type: "${assetType}"`);
+    return spec.toAssetPath(typeRoot, name);
 }

package/dist/cli.js

@@ -3,20 +3,21 @@ 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 { 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 { 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 { agentikitList, agentikitRemove, agentikitUpdate } from "./stash-registry";
-import { agentikitSearch } from "./stash-search";
-import { agentikitShow } from "./stash-show";
-import { resolveStashSources } from "./stash-source";
+import { agentikitSearch, parseSearchSource } from "./stash-search";
+import { agentikitShowUnified } from "./stash-show";
+import { addStashSource, listStashSources, removeStashSource } from "./stash-source-manage";
 import { setQuiet, warn } from "./warn";
 // Version: prefer compile-time define, then package.json, then fallback
 const pkgVersion = (() => {
@@ -38,7 +39,7 @@ const pkgVersion = (() => {
 })();
 const OUTPUT_FORMATS = ["json", "yaml", "text"];
 const DETAIL_LEVELS = ["brief", "normal", "full"];
-const BRIEF_DESCRIPTION_LIMIT = 160;
+const NORMAL_DESCRIPTION_LIMIT = 250;
 function hasBunYAML(b) {
     // biome-ignore lint/suspicious/noExplicitAny: type guard for runtime feature detection
     return typeof b.YAML?.stringify === "function";
@@ -135,7 +136,8 @@ function shapeRegistrySearchOutput(result, detail) {
     const assetHits = Array.isArray(result.assetHits) ? result.assetHits : [];
     // Shape kit hits as registry type
     const shapedKitHits = hits.map((hit) => shapeSearchHit({ ...hit, type: "registry" }, detail));
-    const shapedAssetHits = assetHits.map((hit) => shapeSearchHit(hit, detail));
+    // Shape asset hits by detail level
+    const shapedAssetHits = assetHits.map((hit) => shapeAssetHit(hit, detail));
     const shaped = {
         hits: shapedKitHits,
         ...(shapedAssetHits.length > 0 ? { assetHits: shapedAssetHits } : {}),
@@ -146,42 +148,35 @@ function shapeRegistrySearchOutput(result, detail) {
     }
     return shaped;
 }
+function shapeAssetHit(hit, detail) {
+    if (detail === "brief")
+        return pickFields(hit, ["assetName", "assetType", "action"]);
+    if (detail === "normal") {
+        return capDescription(pickFields(hit, ["assetName", "assetType", "description", "kit", "action"]), NORMAL_DESCRIPTION_LIMIT);
+    }
+    return hit;
+}
 function shapeSearchHit(hit, detail) {
-    // Keep local and registry hit models separate internally so search and
-    // ranking logic can carry source-specific metadata. Normalize the external
-    // contract here so default CLI output stays compact and consistent.
     if (hit.type === "registry") {
-        const brief = withTruncatedDescription(pickFields(hit, ["type", "name", "id", "description", "action", "curated"]));
         if (detail === "brief")
-            return brief;
-        if (detail === "normal")
-            return pickFields(hit, ["type", "name", "id", "description", "tags", "action", "curated"]);
-        return hit;
-    }
-    if (hit.type === "registry-asset") {
-        const brief = withTruncatedDescription(pickFields(hit, ["type", "assetType", "assetName", "description", "kit", "action"]));
-        if (detail === "brief")
-            return brief;
+            return pickFields(hit, ["name", "action"]);
         if (detail === "normal") {
-            return pickFields(hit, ["type", "assetType", "assetName", "description", "kit", "registryName", "action"]);
+            return capDescription(pickFields(hit, ["name", "description", "action", "curated"]), NORMAL_DESCRIPTION_LIMIT);
         }
         return hit;
     }
-    const brief = withTruncatedDescription(pickFields(hit, ["type", "name", "description", "action"]));
+    // Stash hit (local or remote)
     if (detail === "brief")
-        return brief;
+        return pickFields(hit, ["type", "name", "action"]);
     if (detail === "normal") {
-        return pickFields(hit, ["type", "name", "ref", "origin", "description", "tags", "size", "action", "run"]);
+        return capDescription(pickFields(hit, ["type", "name", "description", "action", "score"]), NORMAL_DESCRIPTION_LIMIT);
     }
     return hit;
 }
-function withTruncatedDescription(hit) {
+function capDescription(hit, limit) {
     if (typeof hit.description !== "string")
         return hit;
-    return {
-        ...hit,
-        description: truncateDescription(hit.description, BRIEF_DESCRIPTION_LIMIT),
-    };
+    return { ...hit, description: truncateDescription(hit.description, limit) };
 }
 function truncateDescription(description, limit) {
     const normalized = description.replace(/\s+/g, " ").trim();
@@ -400,6 +395,13 @@ function formatSearchPlain(r, detail) {
     }
     return lines.join("\n").trimEnd();
 }
+/**
+ * Naming Conventions:
+ * - stash-*     : Operations on the user's local asset store (stash-show, stash-add, stash-clone)
+ * - stash-provider-* : Runtime data source providers (filesystem, openviking)
+ * - registry-*  : Kit discovery from remote registries (npm, GitHub)
+ * - installed-kits : Management of kits already installed locally
+ */
 const initCommand = defineCommand({
     meta: {
         name: "init",
@@ -433,17 +435,21 @@ const searchCommand = defineCommand({
         query: { type: "positional", description: "Search query (omit to list all assets)", required: false, default: "" },
         type: {
             type: "string",
-            description: "Asset type filter (skill|command|agent|knowledge|script|any).",
+            description: "Asset type filter (e.g. skill, command, agent, knowledge, script, memory, or any).",
         },
         limit: { type: "string", description: "Maximum number of results" },
-        source: { type: "string", description: "Search source (local|registry|both)", default: "local" },
+        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)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const type = args.type;
-            const limit = args.limit ? parseInt(args.limit, 10) : undefined;
+            const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
+            if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
+                throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
+            }
+            const limit = limitRaw;
             const source = parseSearchSource(args.source);
             const result = await agentikitSearch({ query: args.query, type, limit, source });
             output("search", result);
@@ -506,6 +512,11 @@ const upgradeCommand = defineCommand({
     args: {
         check: { type: "boolean", description: "Check for updates without installing", default: false },
         force: { type: "boolean", description: "Force upgrade even if on latest", default: false },
+        skipChecksum: {
+            type: "boolean",
+            description: "Skip checksum verification (not recommended)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -514,7 +525,7 @@ const upgradeCommand = defineCommand({
                 output("upgrade", check);
                 return;
             }
-            const result = await performUpgrade(check, { force: args.force });
+            const result = await performUpgrade(check, { force: args.force, skipChecksum: args.skipChecksum });
             output("upgrade", result);
         });
     },
@@ -557,7 +568,7 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${args.akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            const result = await agentikitShow({ ref: args.ref, view });
+            const result = await agentikitShowUnified({ ref: args.ref, view });
             output("show", result);
         });
     },
@@ -689,7 +700,7 @@ const registryCommand = defineCommand({
             run() {
                 return runWithJsonErrors(() => {
                     const config = loadConfig();
-                    const registries = config.registries ?? [];
+                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
                     output("registry-list", { registries });
                 });
             },
@@ -700,12 +711,16 @@ const registryCommand = defineCommand({
                 url: { type: "positional", description: "Registry index URL", required: true },
                 name: { type: "string", description: "Human-friendly name for the registry" },
                 provider: { type: "string", description: "Provider type (e.g. static-index, skills-sh)" },
+                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
                     if (!args.url.startsWith("http")) {
                         throw new UsageError("Registry URL must start with http:// or https://");
                     }
+                    if (args.url.startsWith("http://")) {
+                        warn("Warning: registry URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                    }
                     const config = loadConfig();
                     const registries = [...(config.registries ?? [])];
                     // Deduplicate by URL
@@ -718,6 +733,14 @@ const registryCommand = defineCommand({
                         entry.name = args.name;
                     if (args.provider)
                         entry.provider = args.provider;
+                    if (args.options) {
+                        try {
+                            entry.options = JSON.parse(args.options);
+                        }
+                        catch {
+                            throw new UsageError("--options must be valid JSON");
+                        }
+                    }
                     registries.push(entry);
                     saveConfig({ ...config, registries });
                     output("registry-add", { registries, added: true });
@@ -753,24 +776,117 @@ const registryCommand = defineCommand({
             },
             async run({ args }) {
                 await runWithJsonErrors(async () => {
-                    const limit = args.limit ? parseInt(args.limit, 10) : undefined;
-                    const result = await searchRegistry(args.query, { limit, includeAssets: args.assets });
+                    const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
+                    if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
+                        throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
+                    }
+                    const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
                     output("registry-search", result);
                 });
             },
         }),
+        "build-index": defineCommand({
+            meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
+            args: {
+                out: { type: "string", description: "Output path for the generated index", default: "index.json" },
+                manual: { type: "string", description: "Manual entries JSON file", default: "manual-entries.json" },
+                npmRegistry: { type: "string", description: "Override npm registry base URL" },
+                githubApi: { type: "string", description: "Override GitHub API base URL" },
+            },
+            async run({ args }) {
+                await runWithJsonErrors(async () => {
+                    const result = await buildRegistryIndex({
+                        manualEntriesPath: args.manual,
+                        npmRegistryBase: args.npmRegistry,
+                        githubApiBase: args.githubApi,
+                    });
+                    const outPath = writeRegistryIndex(result.index, args.out);
+                    output("registry-build-index", {
+                        outPath,
+                        version: result.index.version,
+                        updatedAt: result.index.updatedAt,
+                        totalKits: result.counts.total,
+                        counts: result.counts,
+                        manualEntriesPath: result.paths.manualEntriesPath,
+                    });
+                });
+            },
+        }),
     },
 });
+/**
+ * Shared subcommand definitions for stash source management.
+ * Used by both `akm stash` (preferred) and `akm sources` (legacy alias).
+ */
+function buildSourceSubCommands(outputPrefix) {
+    return {
+        list: defineCommand({
+            meta: { name: "list", description: "List all stash sources" },
+            run() {
+                return runWithJsonErrors(() => {
+                    output(`${outputPrefix}`, listStashSources());
+                });
+            },
+        }),
+        add: defineCommand({
+            meta: { name: "add", description: "Add a stash source (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" },
+                provider: { type: "string", description: "Provider type (e.g. openviking). Required for URLs." },
+                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    if (args.target.startsWith("http://")) {
+                        warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                    }
+                    let parsedOptions;
+                    if (args.options) {
+                        try {
+                            const parsed = JSON.parse(args.options);
+                            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                                throw new UsageError("--options must be a JSON object");
+                            }
+                            parsedOptions = parsed;
+                        }
+                        catch (err) {
+                            if (err instanceof UsageError)
+                                throw err;
+                            throw new UsageError("--options must be valid JSON");
+                        }
+                    }
+                    const result = addStashSource({
+                        target: args.target,
+                        name: args.name,
+                        providerType: args.provider,
+                        options: parsedOptions,
+                    });
+                    output(`${outputPrefix}-add`, result);
+                });
+            },
+        }),
+        remove: defineCommand({
+            meta: { name: "remove", description: "Remove a stash source 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);
+                    output(`${outputPrefix}-remove`, result);
+                });
+            },
+        }),
+    };
+}
+const stashCommand = defineCommand({
+    meta: { name: "stash", description: "Manage stash sources (local paths and remote providers)" },
+    subCommands: buildSourceSubCommands("stash"),
+});
 const sourcesCommand = defineCommand({
-    meta: { name: "sources", description: "List all stash search paths and their status" },
-    run() {
-        return runWithJsonErrors(() => {
-            const config = loadConfig();
-            const sources = resolveStashSources();
-            const registries = config.registries ?? [];
-            output("sources", { sources, registries });
-        });
-    },
+    meta: { name: "sources", description: "Manage stash sources (alias for 'akm stash')" },
+    subCommands: buildSourceSubCommands("sources"),
 });
 const hintsCommand = defineCommand({
     meta: {
@@ -807,24 +923,19 @@ const main = defineCommand({
         search: searchCommand,
         show: showCommand,
         clone: cloneCommand,
+        stash: stashCommand,
         sources: sourcesCommand,
         registry: registryCommand,
         config: configCommand,
         hints: hintsCommand,
     },
 });
-const SEARCH_SOURCES = ["local", "registry", "both"];
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
 const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
 // 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.
 process.argv = normalizeShowArgv(process.argv);
 runMain(main);
-function parseSearchSource(value) {
-    if (SEARCH_SOURCES.includes(value))
-        return value;
-    throw new UsageError(`Invalid value for --source: ${value}. Expected one of: ${SEARCH_SOURCES.join("|")}`);
-}
 // ── Exit codes ──────────────────────────────────────────────────────────────
 const EXIT_GENERAL = 1;
 const EXIT_USAGE = 2;
@@ -866,7 +977,7 @@ function buildHint(message) {
     if (message.includes("remote package fetched but asset not found"))
         return "The remote package was fetched but doesn't contain the requested asset. Check the asset name and type.";
     if (message.includes("Invalid value for --source"))
-        return "Pick one of: local, registry, both.";
+        return "Pick one of: stash, registry, both.";
     if (message.includes("Invalid value for --format"))
         return "Pick one of: json, text, yaml.";
     if (message.includes("Invalid value for --detail"))
@@ -975,7 +1086,7 @@ You have access to a searchable library of scripts, skills, commands, agents, an
 \`\`\`sh
 akm search "<query>"                          # Search for assets
 akm search "<query>" --type skill             # Filter by type
-akm search "<query>" --source both            # Search registries and local stashes for assets
+akm search "<query>" --source both            # Search stash providers and registries for assets
 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)
@@ -1003,7 +1114,7 @@ You have access to a searchable library of scripts, skills, commands, agents, an
 \`\`\`sh
 akm search "<query>"                          # Search local stash
 akm search "<query>" --type skill             # Filter by asset type
-akm search "<query>" --source both            # Search local stash and registries
+akm search "<query>" --source both            # Search all stash providers and registries
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
 akm search "<query>" --detail full            # Include scores, paths, timing
@@ -1011,8 +1122,8 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 
 | Flag | Values | Default |
 | --- | --- | --- |
-| \`--type\` | \`skill\`, \`command\`, \`agent\`, \`knowledge\`, \`script\`, \`any\` | \`any\` |
-| \`--source\` | \`local\`, \`registry\`, \`both\` | \`local\` |
+| \`--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\` |
@@ -1029,6 +1140,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
 \`\`\`
 
 | Type | Key fields returned |
@@ -1038,6 +1150,7 @@ akm show knowledge:guide lines 10 30          # Line range
 | command | \`template\`, \`description\`, \`parameters\` |
 | agent | \`prompt\`, \`description\`, \`modelHint\`, \`toolPolicy\` |
 | knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
+| memory | \`content\` (recalled context) |
 
 ## Install & Manage Kits
 
@@ -1076,6 +1189,8 @@ akm registry add <url> --provider skills-sh   # Specify provider type
 akm registry remove <url-or-name>             # Remove a registry
 akm registry search "<query>"                 # Search all registries
 akm registry search "<query>" --assets        # Include asset-level results
+akm registry build-index                      # Build ./index.json
+akm registry build-index --out dist/index.json # Build to a custom path
 \`\`\`
 
 ## Configuration

package/dist/common.js

@@ -7,7 +7,7 @@ import { getConfigPath, getDefaultStashDir } from "./paths";
 export const IS_WINDOWS = process.platform === "win32";
 // ── Validators ──────────────────────────────────────────────────────────────
 export function isAssetType(type) {
-    return type in TYPE_DIRS;
+    return Object.hasOwn(TYPE_DIRS, type);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
 /**
@@ -16,6 +16,11 @@ export function isAssetType(type) {
  *   2. stashDir field in config.json
  *   3. Platform default (~/akm or ~/Documents/akm on Windows)
  *
+ * WARNING: May write to config file as a side effect when AKM_STASH_DIR is set.
+ * Specifically, when AKM_STASH_DIR is set and `options.readOnly` is not true,
+ * this function calls `persistStashDirToConfig()` which writes the resolved
+ * path into config.json on disk.
+ *
  * Throws if no valid stash directory is found.
  */
 export function resolveStashDir(options) {
@@ -82,6 +87,11 @@ function readStashDirFromConfig() {
 /**
  * Persist stashDir to config.json if not already set, so users can
  * transition away from relying on the AKM_STASH_DIR env var.
+ *
+ * WARNING: This function writes to disk (config.json). It is called as a side
+ * effect of `resolveStashDir()` when AKM_STASH_DIR is set and `readOnly` is
+ * not true. Callers that must not touch the filesystem should pass
+ * `{ readOnly: true }` to `resolveStashDir()`.
  */
 function persistStashDirToConfig(stashDir) {
     try {
@@ -101,7 +111,7 @@ function persistStashDirToConfig(stashDir) {
             raw.stashDir = stashDir;
             const dir = path.dirname(configPath);
             fs.mkdirSync(dir, { recursive: true });
-            const tmpPath = `${configPath}.tmp.${process.pid}`;
+            const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
             fs.writeFileSync(tmpPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
             fs.renameSync(tmpPath, configPath);
         }
@@ -196,3 +206,6 @@ function parseRetryAfter(response) {
     const seconds = parseInt(header, 10);
     return Number.isNaN(seconds) ? undefined : seconds * 1000;
 }
+export function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}