akm-cli 0.3.1 → 0.4.1

package/dist/cli.js

@@ -2,15 +2,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { resolveStashDir } from "./common";
+import { resolveAssetPathFromName } from "./asset-spec";
+import { isWithin, resolveStashDir } from "./common";
 import { generateBashCompletions, installBashCompletions } from "./completions";
-import { DEFAULT_CONFIG, getConfigPath, loadConfig, saveConfig } from "./config";
+import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, 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 { formatInstallAuditSummary } from "./install-audit";
 import { akmListSources, akmRemove, akmUpdate } from "./installed-kits";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
 import { buildRegistryIndex, writeRegistryIndex } from "./registry-build-index";
@@ -27,8 +29,12 @@ import { setQuiet, warn } from "./warn";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
 const DETAIL_LEVELS = ["brief", "normal", "full", "summary"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
+const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 const CONTEXT_HUB_ALIAS_REF = "context-hub";
 const CONTEXT_HUB_ALIAS_URL = "https://github.com/andrewyng/context-hub";
+const SKILLS_SH_NAME = "skills.sh";
+const SKILLS_SH_URL = "https://skills.sh";
+const SKILLS_SH_PROVIDER = "skills-sh";
 import { stringify as yamlStringify } from "yaml";
 function parseOutputFormat(value) {
     if (!value)
@@ -338,6 +344,9 @@ function formatPlain(command, result, detail) {
         case "search": {
             return formatSearchPlain(r, detail);
         }
+        case "curate": {
+            return formatCuratePlain(r, detail);
+        }
         case "list": {
             const sources = Array.isArray(r.sources) ? r.sources : [];
             if (sources.length === 0)
@@ -356,7 +365,13 @@ function formatPlain(command, result, detail) {
             const index = r.index;
             const scanned = index?.directoriesScanned ?? 0;
             const total = index?.totalEntries ?? 0;
-            return `Installed ${r.ref} (${scanned} directories scanned, ${total} total assets indexed)`;
+            const lines = [`Installed ${r.ref} (${scanned} directories scanned, ${total} total assets indexed)`];
+            const installed = r.installed;
+            const audit = installed?.audit;
+            if (audit && typeof audit === "object") {
+                lines.push(formatInstallAuditSummary(audit));
+            }
+            return lines.join("\n");
         }
         case "remove": {
             const target = r.target ?? r.ref ?? "";
@@ -464,6 +479,275 @@ function formatSearchPlain(r, detail) {
     }
     return lines.join("\n").trimEnd();
 }
+function formatCuratePlain(r, detail) {
+    const query = typeof r.query === "string" ? r.query : "";
+    const summary = typeof r.summary === "string" ? r.summary : "";
+    const items = Array.isArray(r.items) ? r.items : [];
+    const lines = [`Curated results for "${query}"`];
+    if (summary)
+        lines.push(summary);
+    if (items.length === 0) {
+        if (r.tip)
+            lines.push(String(r.tip));
+        return lines.join("\n");
+    }
+    for (const item of items) {
+        const type = typeof item.type === "string" ? item.type : "unknown";
+        const name = typeof item.name === "string" ? item.name : "unnamed";
+        lines.push("");
+        lines.push(`[${type}] ${name}`);
+        if (item.description)
+            lines.push(`  ${String(item.description)}`);
+        if (item.preview)
+            lines.push(`  preview: ${String(item.preview)}`);
+        if (item.ref)
+            lines.push(`  ref: ${String(item.ref)}`);
+        if (item.id)
+            lines.push(`  id: ${String(item.id)}`);
+        if (Array.isArray(item.parameters) && item.parameters.length > 0) {
+            lines.push(`  parameters: ${item.parameters.join(", ")}`);
+        }
+        if (item.run)
+            lines.push(`  run: ${String(item.run)}`);
+        if (item.followUp)
+            lines.push(`  show: ${String(item.followUp)}`);
+        if (detail !== "brief" && item.reason)
+            lines.push(`  why: ${String(item.reason)}`);
+    }
+    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
+    if (warnings.length > 0) {
+        lines.push("");
+        lines.push("Warnings:");
+        for (const warning of warnings) {
+            lines.push(`- ${String(warning)}`);
+        }
+    }
+    return lines.join("\n");
+}
+const CURATE_FALLBACK_FILTER_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "for",
+    "how",
+    "i",
+    "in",
+    "of",
+    "or",
+    "the",
+    "to",
+    "with",
+]);
+const CURATED_TYPE_FALLBACK_ORDER = ["skill", "command", "script", "knowledge", "agent", "memory"];
+const CURATED_TYPE_FALLBACK_INDEX = new Map(CURATED_TYPE_FALLBACK_ORDER.map((type, index) => [type, index]));
+const MIN_CURATE_FALLBACK_TOKEN_LENGTH = 3;
+const MAX_CURATE_FALLBACK_KEYWORDS = 6;
+const CURATE_SEARCH_LIMIT_MULTIPLIER = 4;
+const MIN_CURATE_SEARCH_LIMIT = 12;
+async function curateSearchResults(query, result, limit, selectedType) {
+    const stashHits = result.hits.filter((hit) => hit.type !== "registry");
+    const registryHits = result.registryHits ?? [];
+    let selectedStashHits;
+    if (selectedType && selectedType !== "any") {
+        selectedStashHits = stashHits.slice(0, limit);
+    }
+    else {
+        const bestByType = new Map();
+        for (const hit of stashHits) {
+            if (!bestByType.has(hit.type))
+                bestByType.set(hit.type, hit);
+        }
+        const orderedTypes = orderCuratedTypes(query, Array.from(bestByType.keys()));
+        selectedStashHits = orderedTypes
+            .map((type) => bestByType.get(type))
+            .filter((hit) => Boolean(hit));
+    }
+    const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, Math.min(2, limit - selectedStashHits.length));
+    const items = [
+        ...(await Promise.all(selectedStashHits.slice(0, limit).map((hit) => enrichCuratedStashHit(query, hit)))),
+        ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
+    ].slice(0, limit);
+    return {
+        query,
+        summary: buildCurateSummary(query, items),
+        items,
+        ...(result.warnings?.length ? { warnings: result.warnings } : {}),
+        ...(result.tip ? { tip: result.tip } : {}),
+    };
+}
+function orderCuratedTypes(query, types) {
+    const lower = query.toLowerCase();
+    const boosts = new Map();
+    const addBoost = (type, amount) => boosts.set(type, (boosts.get(type) ?? 0) + amount);
+    if (/(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower)) {
+        addBoost("script", 6);
+        addBoost("command", 4);
+    }
+    if (/(guide|docs?|readme|reference|how|explain|learn|why)/.test(lower)) {
+        addBoost("knowledge", 6);
+        addBoost("skill", 4);
+    }
+    if (/(agent|assistant|planner|review|analy[sz]e|architect|prompt)/.test(lower)) {
+        addBoost("agent", 6);
+        addBoost("skill", 3);
+    }
+    if (/(config|template|release|generate|command)/.test(lower)) {
+        addBoost("command", 5);
+    }
+    if (/(memory|context|recall|remember)/.test(lower)) {
+        addBoost("memory", 6);
+    }
+    return [...types].sort((a, b) => {
+        const boostDiff = (boosts.get(b) ?? 0) - (boosts.get(a) ?? 0);
+        if (boostDiff !== 0)
+            return boostDiff;
+        return ((CURATED_TYPE_FALLBACK_INDEX.get(a) ?? Number.MAX_SAFE_INTEGER) -
+            (CURATED_TYPE_FALLBACK_INDEX.get(b) ?? Number.MAX_SAFE_INTEGER));
+    });
+}
+async function enrichCuratedStashHit(query, hit) {
+    let shown;
+    try {
+        shown = await akmShowUnified({ ref: hit.ref });
+    }
+    catch {
+        shown = undefined;
+    }
+    const description = shown?.description ?? hit.description;
+    const preview = buildCuratedPreview(shown, hit);
+    return {
+        source: "stash",
+        type: shown?.type ?? hit.type,
+        name: shown?.name ?? hit.name,
+        ref: hit.ref,
+        ...(description ? { description } : {}),
+        ...(preview ? { preview } : {}),
+        ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
+        ...(shown?.run ? { run: shown.run } : {}),
+        followUp: `akm show ${hit.ref}`,
+        reason: buildCuratedReason(query, shown?.type ?? hit.type),
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+    };
+}
+function buildCuratedRegistryItem(query, hit) {
+    return {
+        source: "registry",
+        type: "registry",
+        name: hit.name,
+        id: hit.id,
+        ...(hit.description ? { description: hit.description } : {}),
+        followUp: hit.action ?? `akm add ${hit.id}`,
+        reason: `Useful external source to explore for ${query}.`,
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+    };
+}
+function firstNonEmpty(values) {
+    return values.find((value) => typeof value === "string" && value.trim().length > 0);
+}
+function buildCuratedPreview(shown, hit) {
+    if (shown?.run)
+        return truncateDescription(`run ${shown.run}`, 160);
+    const payload = firstNonEmpty([shown?.template, shown?.prompt, shown?.content, hit.description])
+        ?.replace(/\s+/g, " ")
+        .trim();
+    return payload ? truncateDescription(payload, 160) : undefined;
+}
+function buildCuratedReason(query, type) {
+    switch (type) {
+        case "script":
+            return `Best runnable script match for "${query}".`;
+        case "command":
+            return `Best reusable command/template match for "${query}".`;
+        case "knowledge":
+            return `Best reference document match for "${query}".`;
+        case "skill":
+            return `Best instructions/workflow match for "${query}".`;
+        case "agent":
+            return `Best specialized agent prompt match for "${query}".`;
+        case "memory":
+            return `Best saved context match for "${query}".`;
+        default:
+            return `Best ${type} match for "${query}".`;
+    }
+}
+function buildCurateSummary(query, items) {
+    if (items.length === 0) {
+        return `No curated assets were selected for "${query}".`;
+    }
+    const labels = items.map((item) => `${item.type}:${item.name}`);
+    return `Selected ${items.length} high-signal result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
+}
+function hasSearchResults(result) {
+    return result.hits.length > 0 || (result.registryHits?.length ?? 0) > 0;
+}
+/**
+ * Extract a small set of fallback keywords when a prompt-style curate query
+ * returns no hits as a whole phrase.
+ *
+ * We keep up to MAX_CURATE_FALLBACK_KEYWORDS distinct keywords and drop short
+ * or common filler words so follow-up searches stay inexpensive while focusing
+ * on higher-signal terms.
+ */
+function deriveCurateFallbackQueries(query) {
+    return Array.from(new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .map((token) => token.trim())
+        // Keep longer tokens so fallback stays focused on higher-signal terms
+        // and avoids broad one- and two-letter matches that overwhelm curation.
+        .filter((token) => token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH && !CURATE_FALLBACK_FILTER_WORDS.has(token)))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+}
+function mergeCurateSearchResponses(base, extras) {
+    const hitsByRef = new Map();
+    for (const hit of base.hits.filter((entry) => entry.type !== "registry")) {
+        hitsByRef.set(hit.ref, hit);
+    }
+    for (const result of extras) {
+        for (const hit of result.hits.filter((entry) => entry.type !== "registry")) {
+            const existing = hitsByRef.get(hit.ref);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
+                hitsByRef.set(hit.ref, hit);
+            }
+        }
+    }
+    const registryById = new Map();
+    for (const hit of base.registryHits ?? []) {
+        registryById.set(hit.id, hit);
+    }
+    for (const result of extras) {
+        for (const hit of result.registryHits ?? []) {
+            const existing = registryById.get(hit.id);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
+                registryById.set(hit.id, hit);
+            }
+        }
+    }
+    const warnings = Array.from(new Set([...(base.warnings ?? []), ...extras.flatMap((result) => result.warnings ?? [])]));
+    const mergedHits = [...hitsByRef.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const mergedRegistryHits = [...registryById.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    return {
+        ...base,
+        hits: mergedHits,
+        ...(mergedRegistryHits.length > 0 ? { registryHits: mergedRegistryHits } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
+        ...(mergedHits.length > 0 || mergedRegistryHits.length > 0 ? { tip: undefined } : {}),
+    };
+}
+async function searchForCuration(input) {
+    const initial = await akmSearch(input);
+    if (hasSearchResults(initial))
+        return initial;
+    const fallbackQueries = deriveCurateFallbackQueries(input.query);
+    if (fallbackQueries.length <= 1)
+        return initial;
+    const fallbackResults = await Promise.all(fallbackQueries.map((token) => akmSearch({
+        query: token,
+        type: input.type,
+        limit: input.limit,
+        source: input.source,
+    })));
+    return mergeCurateSearchResponses(initial, fallbackResults);
+}
 /**
  * Module Naming:
  * - stash-*          : Asset operations (search, show, add, clone)
@@ -550,6 +834,39 @@ const searchCommand = defineCommand({
         });
     },
 });
+const curateCommand = defineCommand({
+    meta: { name: "curate", description: "Curate the best matching assets for a task or prompt" },
+    args: {
+        query: { type: "positional", description: "Task or prompt to curate assets for", required: true },
+        type: {
+            type: "string",
+            description: "Asset type filter (e.g. skill, command, agent, knowledge, script, memory, or any).",
+        },
+        limit: { type: "string", description: "Maximum number of curated results", default: "4" },
+        source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const type = args.type;
+            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 && limitRaw > 0 ? limitRaw : 4;
+            const source = parseSearchSource(args.source ?? "stash");
+            const searchResult = await searchForCuration({
+                query: args.query,
+                type,
+                // Search deeper than the final curated count so we can pick one strong
+                // match per type and still have room for fallback retries.
+                limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
+                source,
+            });
+            const curated = await curateSearchResults(args.query, searchResult, limit, type);
+            output("curate", curated);
+        });
+    },
+});
 const addCommand = defineCommand({
     meta: {
         name: "add",
@@ -826,7 +1143,7 @@ const configCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const updated = setConfigValue(loadConfig(), args.key, args.value);
+                    const updated = setConfigValue(loadUserConfig(), args.key, args.value);
                     saveConfig(updated);
                     output("config", listConfig(updated));
                 });
@@ -839,7 +1156,7 @@ const configCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const updated = unsetConfigValue(loadConfig(), args.key);
+                    const updated = unsetConfigValue(loadUserConfig(), args.key);
                     saveConfig(updated);
                     output("config", listConfig(updated));
                 });
@@ -888,7 +1205,7 @@ const registryCommand = defineCommand({
             meta: { name: "list", description: "List configured registries" },
             run() {
                 return runWithJsonErrors(() => {
-                    const config = loadConfig();
+                    const config = loadUserConfig();
                     const registries = config.registries ?? DEFAULT_CONFIG.registries;
                     output("registry-list", { registries });
                 });
@@ -910,7 +1227,7 @@ const registryCommand = defineCommand({
                     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 config = loadUserConfig();
                     const registries = [...(config.registries ?? [])];
                     // Deduplicate by URL
                     if (registries.some((r) => r.url === args.url)) {
@@ -943,7 +1260,7 @@ const registryCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const config = loadConfig();
+                    const config = loadUserConfig();
                     const registries = [...(config.registries ?? [])];
                     const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
                     if (idx === -1) {
@@ -1044,6 +1361,164 @@ const feedbackCommand = defineCommand({
         });
     },
 });
+function tryReadStdinText() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const input = fs.readFileSync(0, "utf8");
+    return input.length > 0 ? input : undefined;
+}
+function normalizeMarkdownAssetName(name, fallback) {
+    const trimmed = (name ?? fallback)
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.md$/i, "");
+    if (!trimmed)
+        throw new UsageError("Asset name cannot be empty.");
+    const segments = trimmed.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new UsageError("Asset name must be a relative path without '.' or '..' segments.");
+    }
+    return trimmed;
+}
+function slugifyAssetName(value, fallbackPrefix) {
+    const slug = value
+        .toLowerCase()
+        .replace(/^[#>\-\s]+/, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_CAPTURED_ASSET_SLUG_LENGTH);
+    return slug || `${fallbackPrefix}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+}
+function inferAssetName(content, fallbackPrefix, preferred) {
+    const firstNonEmptyLine = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    const basis = preferred?.trim() || firstNonEmptyLine || fallbackPrefix;
+    return slugifyAssetName(basis, fallbackPrefix);
+}
+function readMemoryContent(contentArg) {
+    const content = contentArg ?? tryReadStdinText();
+    if (!content?.trim()) {
+        throw new UsageError("Memory content is required. Pass quoted text or pipe markdown into stdin.");
+    }
+    return content;
+}
+function readKnowledgeContent(source) {
+    if (source === "-") {
+        const content = tryReadStdinText();
+        if (!content?.trim()) {
+            throw new UsageError("No stdin content received. Pipe a document into stdin or pass a file path.");
+        }
+        return { content };
+    }
+    const resolvedSource = path.resolve(source);
+    let stat;
+    try {
+        stat = fs.statSync(resolvedSource);
+    }
+    catch {
+        throw new UsageError(`Knowledge source not found: "${source}". Pass a readable file path or "-" for stdin.`);
+    }
+    if (!stat.isFile()) {
+        throw new UsageError(`Knowledge source must be a file: "${source}".`);
+    }
+    return {
+        content: fs.readFileSync(resolvedSource, "utf8"),
+        preferredName: path.basename(resolvedSource, path.extname(resolvedSource)),
+    };
+}
+function writeMarkdownAsset(options) {
+    const stashDir = resolveStashDir();
+    const typeRoot = path.join(stashDir, options.type === "knowledge" ? "knowledge" : "memories");
+    fs.mkdirSync(typeRoot, { recursive: true });
+    const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    const assetPath = resolveAssetPathFromName(options.type, typeRoot, normalizedName);
+    if (!isWithin(assetPath, typeRoot)) {
+        throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
+    }
+    if (fs.existsSync(assetPath) && !options.force) {
+        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`);
+    }
+    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+    fs.writeFileSync(assetPath, options.content.endsWith("\n") ? options.content : `${options.content}\n`, "utf8");
+    return {
+        ref: `${options.type}:${normalizedName}`,
+        path: assetPath,
+        stashDir,
+    };
+}
+const rememberCommand = defineCommand({
+    meta: {
+        name: "remember",
+        description: "Record a memory in the default stash",
+    },
+    args: {
+        content: {
+            type: "positional",
+            description: "Memory content. Omit to read markdown from stdin.",
+            required: false,
+        },
+        name: {
+            type: "string",
+            description: "Memory name (defaults to a slug from the content)",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing memory with the same name",
+            default: false,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = writeMarkdownAsset({
+                type: "memory",
+                content: readMemoryContent(args.content),
+                name: args.name,
+                fallbackPrefix: "memory",
+                force: args.force,
+            });
+            output("remember", { ok: true, ...result });
+        });
+    },
+});
+const importKnowledgeCommand = defineCommand({
+    meta: {
+        name: "import",
+        description: "Import a knowledge document into the default stash",
+    },
+    args: {
+        source: {
+            type: "positional",
+            description: 'Source file path, or "-" to read from stdin',
+            required: true,
+        },
+        name: {
+            type: "string",
+            description: "Knowledge name (defaults to the source filename or content slug)",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing knowledge document with the same name",
+            default: false,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const { content, preferredName } = readKnowledgeContent(args.source);
+            const result = writeMarkdownAsset({
+                type: "knowledge",
+                content,
+                name: args.name,
+                fallbackPrefix: "knowledge",
+                preferredName,
+                force: args.force,
+            });
+            output("import", { ok: true, source: args.source, ...result });
+        });
+    },
+});
 const hintsCommand = defineCommand({
     meta: {
         name: "hints",
@@ -1089,6 +1564,83 @@ const completionsCommand = defineCommand({
         }
     },
 });
+function normalizeToggleTarget(target) {
+    const normalized = target.trim().toLowerCase();
+    if (normalized === "skills.sh" || normalized === "skills-sh")
+        return "skills.sh";
+    if (normalized === "context-hub")
+        return "context-hub";
+    throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh, context-hub`);
+}
+function toggleSkillsShRegistry(enabled) {
+    const config = loadUserConfig();
+    const registries = (config.registries ?? DEFAULT_CONFIG.registries ?? []).map((registry) => ({ ...registry }));
+    const idx = registries.findIndex((registry) => registry.provider === SKILLS_SH_PROVIDER || registry.name === SKILLS_SH_NAME || registry.url === SKILLS_SH_URL);
+    if (idx >= 0) {
+        const existing = registries[idx];
+        const wasEnabled = existing.enabled !== false;
+        existing.enabled = enabled;
+        saveConfig({ ...config, registries });
+        return { changed: wasEnabled !== enabled, component: SKILLS_SH_NAME, enabled };
+    }
+    if (!enabled) {
+        // Materialize the skills.sh registry explicitly if absent.
+        registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: false });
+        saveConfig({ ...config, registries });
+        return { changed: true, component: SKILLS_SH_NAME, enabled: false };
+    }
+    registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled: true });
+    saveConfig({ ...config, registries });
+    return { changed: true, component: SKILLS_SH_NAME, enabled: true };
+}
+function toggleContextHubStash(enabled) {
+    const config = loadUserConfig();
+    const stashes = [...(config.stashes ?? [])];
+    const idx = stashes.findIndex((stash) => stash.name === CONTEXT_HUB_ALIAS_REF || stash.url === CONTEXT_HUB_ALIAS_URL);
+    if (idx >= 0) {
+        const existing = stashes[idx];
+        const wasEnabled = existing.enabled !== false;
+        existing.enabled = enabled;
+        saveConfig({ ...config, stashes });
+        return { changed: wasEnabled !== enabled, component: CONTEXT_HUB_ALIAS_REF, enabled };
+    }
+    if (!enabled) {
+        return { changed: false, component: CONTEXT_HUB_ALIAS_REF, enabled: false };
+    }
+    stashes.push({ type: "git", url: CONTEXT_HUB_ALIAS_URL, name: CONTEXT_HUB_ALIAS_REF, enabled: true });
+    saveConfig({ ...config, stashes });
+    return { changed: true, component: CONTEXT_HUB_ALIAS_REF, enabled: true };
+}
+function toggleComponent(targetRaw, enabled) {
+    const target = normalizeToggleTarget(targetRaw);
+    if (target === "skills.sh")
+        return toggleSkillsShRegistry(enabled);
+    return toggleContextHubStash(enabled);
+}
+const enableCommand = defineCommand({
+    meta: { name: "enable", description: "Enable an optional component (skills.sh or context-hub)" },
+    args: {
+        target: { type: "positional", description: "Component to enable (skills.sh|context-hub)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = toggleComponent(args.target, true);
+            output("enable", result);
+        });
+    },
+});
+const disableCommand = defineCommand({
+    meta: { name: "disable", description: "Disable an optional component (skills.sh or context-hub)" },
+    args: {
+        target: { type: "positional", description: "Component to disable (skills.sh|context-hub)", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = toggleComponent(args.target, false);
+            output("disable", result);
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -1111,10 +1663,15 @@ const main = defineCommand({
         update: updateCommand,
         upgrade: upgradeCommand,
         search: searchCommand,
+        curate: curateCommand,
         show: showCommand,
+        remember: rememberCommand,
+        import: importKnowledgeCommand,
         clone: cloneCommand,
         registry: registryCommand,
         config: configCommand,
+        enable: enableCommand,
+        disable: disableCommand,
         feedback: feedbackCommand,
         hints: hintsCommand,
         completions: completionsCommand,
@@ -1275,9 +1832,13 @@ You have access to a searchable library of scripts, skills, commands, agents, an
 
 \`\`\`sh
 akm search "<query>"                          # Search all sources
+akm curate "<task>"                          # Curate the best matches for a task
 akm search "<query>" --type skill             # Filter by type
 akm search "<query>" --source both            # Also search registries
 akm show <ref>                                # View asset details
+akm remember "Deployment needs VPN access"    # Record a memory in your stash
+akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
+akm feedback <ref> --positive|--negative      # Record whether an asset helped
 akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
 akm registry search "<query>"                 # Search all registries
@@ -1292,6 +1853,10 @@ akm registry search "<query>"                 # Search all registries
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
 | knowledge | A reference doc (use \`toc\` or \`section "..."\` to navigate) |
+| memory | Recalled context (read the content for background information) |
+
+When an asset meaningfully helps or fails, record that with \`akm feedback\` so
+future search ranking can learn from real usage.
 
 Run \`akm -h\` for the full command reference.
 `;
@@ -1303,6 +1868,7 @@ You have access to a searchable library of scripts, skills, commands, agents, an
 
 \`\`\`sh
 akm search "<query>"                          # Search all sources
+akm curate "<task>"                          # Curate the best matches for a task
 akm search "<query>" --type skill             # Filter by asset type
 akm search "<query>" --source both            # Also search registries
 akm search "<query>" --source registry        # Search registries only
@@ -1319,6 +1885,16 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 | \`--detail\` | \`brief\`, \`normal\`, \`full\`, \`summary\` | \`brief\` |
 | \`--for-agent\` | boolean | \`false\` |
 
+## Curate
+
+Combine search + follow-up hints into a dense summary for a task or prompt.
+
+\`\`\`sh
+akm curate "plan a release"                   # Pick top matches across asset types
+akm curate "deploy a Bun app" --limit 3       # Keep the summary shorter
+akm curate "review architecture" --type skill # Restrict to one asset type
+\`\`\`
+
 ## Show
 
 Display an asset by ref. Knowledge assets support view modes as positional arguments.
@@ -1343,6 +1919,20 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
 | memory | \`content\` (recalled context) |
 
+## Capture Knowledge While You Work
+
+\`\`\`sh
+akm remember "Deployment needs VPN access"     # Record a memory in your stash
+akm remember --name release-retro < notes.md   # Save multiline memory from stdin
+akm import ./docs/auth-flow.md                 # Import a file as knowledge
+akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
+akm feedback skill:code-review --positive      # Record that an asset helped
+akm feedback agent:reviewer --negative         # Record that an asset missed the mark
+\`\`\`
+
+Use \`akm feedback\` whenever an asset materially helps or fails so future search
+ranking can learn from actual usage.
+
 ## Add & Manage Sources
 
 \`\`\`sh
@@ -1350,6 +1940,10 @@ akm add <ref>                                 # Add a source
 akm add @scope/kit                            # From npm (managed)
 akm add owner/repo                            # From GitHub (managed)
 akm add ./path/to/local/kit                   # Local directory
+akm enable skills.sh                          # Enable the skills.sh registry
+akm disable skills.sh                         # Disable the skills.sh registry
+akm enable context-hub                        # Add/enable the context-hub source
+akm disable context-hub                       # Disable the context-hub source
 akm list                                      # List all sources
 akm list --kind managed                       # List managed sources only
 akm remove <target>                           # Remove by id, ref, path, or name