akm-cli 0.0.16 → 0.0.18

package/dist/cli.js

@@ -9,6 +9,7 @@ import { ConfigError, NotFoundError, UsageError } from "./errors";
 import { agentikitIndex } from "./indexer";
 import { agentikitInit } from "./init";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
+import { searchRegistry } from "./registry-search";
 import { checkForUpdate, performUpgrade } from "./self-update";
 import { agentikitAdd } from "./stash-add";
 import { agentikitClone } from "./stash-clone";
@@ -101,6 +102,8 @@ function shapeForCommand(command, result, detail) {
     switch (command) {
         case "search":
             return shapeSearchOutput(result, detail);
+        case "registry-search":
+            return shapeRegistrySearchOutput(result, detail);
         case "show":
             return shapeShowOutput(result, detail);
         default:
@@ -127,6 +130,22 @@ function shapeSearchOutput(result, detail) {
         ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
     };
 }
+function shapeRegistrySearchOutput(result, detail) {
+    const hits = Array.isArray(result.hits) ? result.hits : [];
+    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));
+    const shaped = {
+        hits: shapedKitHits,
+        ...(shapedAssetHits.length > 0 ? { assetHits: shapedAssetHits } : {}),
+        ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+    };
+    if (detail === "full") {
+        shaped.query = result.query;
+    }
+    return shaped;
+}
 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
@@ -139,6 +158,15 @@ function shapeSearchHit(hit, detail) {
             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;
+        if (detail === "normal") {
+            return pickFields(hit, ["type", "assetType", "assetName", "description", "kit", "registryName", "action"]);
+        }
+        return hit;
+    }
     const brief = withTruncatedDescription(pickFields(hit, ["type", "name", "description", "action"]));
     if (detail === "brief")
         return brief;
@@ -405,7 +433,7 @@ 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). 'tool' is accepted as alias for 'script'.",
+            description: "Asset type filter (skill|command|agent|knowledge|script|any).",
         },
         limit: { type: "string", description: "Maximum number of results" },
         source: { type: "string", description: "Search source (local|registry|both)", default: "local" },
@@ -439,7 +467,7 @@ const addCommand = defineCommand({
     },
 });
 const listCommand = defineCommand({
-    meta: { name: "list", description: "List installed registry packages from config" },
+    meta: { name: "list", description: "List installed kits" },
     async run() {
         await runWithJsonErrors(async () => {
             const result = await agentikitList();
@@ -448,7 +476,7 @@ const listCommand = defineCommand({
     },
 });
 const removeCommand = defineCommand({
-    meta: { name: "remove", description: "Remove an installed registry package by id or ref" },
+    meta: { name: "remove", description: "Remove an installed kit by id or ref" },
     args: {
         target: { type: "positional", description: "Installed target (id or ref)", required: true },
     },
@@ -460,7 +488,7 @@ const removeCommand = defineCommand({
     },
 });
 const updateCommand = defineCommand({
-    meta: { name: "update", description: "Update one or all installed registry packages" },
+    meta: { name: "update", description: "Update one or all installed kits" },
     args: {
         target: { type: "positional", description: "Installed target (id or ref)", required: false },
         all: { type: "boolean", description: "Update all installed entries", default: false },
@@ -500,35 +528,33 @@ const showCommand = defineCommand({
         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)" },
-        // These flags are kept for backward compatibility (--view toc still works)
-        // but the preferred syntax is positional: akm show ref toc
-        view: { type: "string", description: "Knowledge view mode (full|toc|frontmatter|section|lines)" },
-        heading: { type: "string", description: "Section heading (for section view)" },
-        start: { type: "string", description: "Start line (for lines view)" },
-        end: { type: "string", description: "End line (for lines view)" },
+        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" },
+        akmEnd: { type: "string", description: "Internal positional end-line parser" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             let view;
-            if (args.view) {
-                switch (args.view) {
+            if (args.akmView) {
+                switch (args.akmView) {
                     case "section":
-                        view = { mode: "section", heading: args.heading ?? "" };
+                        view = { mode: "section", heading: args.akmHeading ?? "" };
                         break;
                     case "lines":
                         view = {
                             mode: "lines",
-                            start: Number(args.start ?? "1"),
-                            end: args.end ? parseInt(args.end, 10) : Number.MAX_SAFE_INTEGER,
+                            start: Number(args.akmStart ?? "1"),
+                            end: args.akmEnd ? parseInt(args.akmEnd, 10) : Number.MAX_SAFE_INTEGER,
                         };
                         break;
                     case "toc":
                     case "frontmatter":
                     case "full":
-                        view = { mode: args.view };
+                        view = { mode: args.akmView };
                         break;
                     default:
-                        throw new UsageError(`Unknown view mode: ${args.view}. Expected one of: full|toc|frontmatter|section|lines`);
+                        throw new UsageError(`Unknown view mode: ${args.akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
             const result = await agentikitShow({ ref: args.ref, view });
@@ -540,9 +566,6 @@ const configCommand = defineCommand({
     meta: { name: "config", description: "Show and manage configuration" },
     args: {
         list: { type: "boolean", description: "List current configuration", default: false },
-        get: { type: "string", description: "Get a configuration value by key" },
-        unset: { type: "string", description: "Unset an optional configuration key or whole embedding/llm section" },
-        set: { type: "string", description: "Back-compat alias for updating a key (key=value format)" },
     },
     subCommands: {
         path: defineCommand({
@@ -631,30 +654,7 @@ const configCommand = defineCommand({
                 output("config", listConfig(loadConfig()));
                 return;
             }
-            if (args.get) {
-                output("config", getConfigValue(loadConfig(), args.get));
-                return;
-            }
-            if (args.unset) {
-                const updated = unsetConfigValue(loadConfig(), args.unset);
-                saveConfig(updated);
-                output("config", listConfig(updated));
-                return;
-            }
-            if (args.set) {
-                const eqIndex = args.set.indexOf("=");
-                if (eqIndex === -1) {
-                    throw new UsageError("--set expects key=value format");
-                }
-                const key = args.set.slice(0, eqIndex);
-                const value = args.set.slice(eqIndex + 1);
-                const config = setConfigValue(loadConfig(), key, value);
-                saveConfig(config);
-                output("config", listConfig(config));
-            }
-            else {
-                output("config", listConfig(loadConfig()));
-            }
+            output("config", listConfig(loadConfig()));
         });
     },
 });
@@ -664,7 +664,7 @@ const cloneCommand = defineCommand({
         description: "Clone an asset from any stash source into the working stash or a custom destination",
     },
     args: {
-        ref: { type: "positional", description: "Asset ref (e.g. @installed:pkg/tool:script.sh)", required: true },
+        ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//script:deploy.sh)", required: true },
         name: { type: "string", description: "New name for the cloned asset" },
         force: { type: "boolean", description: "Overwrite if asset already exists in working stash", default: false },
         dest: { type: "string", description: "Destination directory (default: working stash)" },
@@ -681,15 +681,110 @@ const cloneCommand = defineCommand({
         });
     },
 });
+const registryCommand = defineCommand({
+    meta: { name: "registry", description: "Manage kit registries" },
+    subCommands: {
+        list: defineCommand({
+            meta: { name: "list", description: "List configured registries" },
+            run() {
+                return runWithJsonErrors(() => {
+                    const config = loadConfig();
+                    const registries = config.registries ?? [];
+                    output("registry-list", { registries });
+                });
+            },
+        }),
+        add: defineCommand({
+            meta: { name: "add", description: "Add a registry by URL" },
+            args: {
+                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)" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    if (!args.url.startsWith("http")) {
+                        throw new UsageError("Registry URL must start with http:// or https://");
+                    }
+                    const config = loadConfig();
+                    const registries = [...(config.registries ?? [])];
+                    // Deduplicate by URL
+                    if (registries.some((r) => r.url === args.url)) {
+                        output("registry-add", { registries, added: false, message: "Registry URL already configured" });
+                        return;
+                    }
+                    const entry = { url: args.url };
+                    if (args.name)
+                        entry.name = args.name;
+                    if (args.provider)
+                        entry.provider = args.provider;
+                    registries.push(entry);
+                    saveConfig({ ...config, registries });
+                    output("registry-add", { registries, added: true });
+                });
+            },
+        }),
+        remove: defineCommand({
+            meta: { name: "remove", description: "Remove a registry by URL or name" },
+            args: {
+                target: { type: "positional", description: "Registry URL or name to remove", required: true },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const config = loadConfig();
+                    const registries = [...(config.registries ?? [])];
+                    const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
+                    if (idx === -1) {
+                        output("registry-remove", { registries, removed: false, message: "No matching registry found" });
+                        return;
+                    }
+                    const removed = registries.splice(idx, 1)[0];
+                    saveConfig({ ...config, registries });
+                    output("registry-remove", { registries, removed: true, entry: removed });
+                });
+            },
+        }),
+        search: defineCommand({
+            meta: { name: "search", description: "Search enabled registries for kits" },
+            args: {
+                query: { type: "positional", description: "Search query", required: true },
+                limit: { type: "string", description: "Maximum number of results" },
+                assets: { type: "boolean", description: "Include asset-level search results", default: false },
+            },
+            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 });
+                    output("registry-search", result);
+                });
+            },
+        }),
+    },
+});
 const sourcesCommand = defineCommand({
     meta: { name: "sources", description: "List all stash search paths and their status" },
     run() {
         return runWithJsonErrors(() => {
+            const config = loadConfig();
             const sources = resolveStashSources();
-            output("sources", { sources });
+            const registries = config.registries ?? [];
+            output("sources", { sources, registries });
         });
     },
 });
+const hintsCommand = defineCommand({
+    meta: {
+        name: "hints",
+        description: "Print agent instructions on how to use akm, use --detail full for a complete guide",
+    },
+    args: {
+        detail: { type: "string", description: "Detail level (normal|full)", default: "normal" },
+    },
+    run({ args }) {
+        const detail = args.detail === "full" ? "full" : "normal";
+        process.stdout.write(loadHints(detail));
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -713,7 +808,9 @@ const main = defineCommand({
         show: showCommand,
         clone: cloneCommand,
         sources: sourcesCommand,
+        registry: registryCommand,
         config: configCommand,
+        hints: hintsCommand,
     },
 });
 const SEARCH_SOURCES = ["local", "registry", "both"];
@@ -721,7 +818,7 @@ 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(normalizeConfigArgv(process.argv));
+process.argv = normalizeShowArgv(process.argv);
 runMain(main);
 function parseSearchSource(value) {
     if (SEARCH_SOURCES.includes(value))
@@ -764,7 +861,7 @@ function buildHint(message) {
         return "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg`.";
     if (message.includes("Specify either <target> or --all"))
         return "Use only one: a positional target or `--all`.";
-    if (message.includes("No installed registry entry matched target"))
+    if (message.includes("No installed kit matched target"))
         return "Run `akm list` to view installed ids/refs, then retry with one of those values.";
     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.";
@@ -783,83 +880,25 @@ function hasConfigSubcommand(args) {
     const command = Array.isArray(args._) ? args._[0] : undefined;
     return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command);
 }
-/**
- * Normalize argv before citty parses it so git-style config forms like
- * `akm config llm.maxTokens 512` and `akm config --get llm.maxTokens`
- * are normalized into the existing config subcommands.
- *
- * Returns a new array; the input is never modified.
- */
-function normalizeConfigArgv(argv) {
-    // Global flags should not be treated as config subcommand arguments.
-    // We strip them from the analysis portion, normalize, then re-append them.
-    const globalFlags = [];
-    const configArgs = [];
-    for (let i = 3; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "--quiet" || arg === "-q") {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg === "--format" || arg === "--detail") {
-            globalFlags.push(arg);
-            if (argv[i + 1] !== undefined) {
-                globalFlags.push(argv[i + 1]);
-                i++;
-            }
-            continue;
-        }
-        configArgs.push(arg);
-    }
-    const [command, argAfterCommand, argAfterKey, ...rest] = [argv[2], ...configArgs];
-    if (command !== "config")
-        return argv;
-    if (!argAfterCommand)
-        return argv;
-    const prefix = argv.slice(0, 3);
-    const buildResult = (...newArgs) => [...prefix, ...newArgs, ...globalFlags];
-    if (argAfterCommand === "--list") {
-        return buildResult("list");
-    }
-    if (argAfterCommand === "--get" && argAfterKey) {
-        return buildResult("get", argAfterKey, ...rest);
-    }
-    if (argAfterCommand === "--unset" && argAfterKey) {
-        return buildResult("unset", argAfterKey, ...rest);
-    }
-    if (argAfterCommand.startsWith("-"))
-        return argv;
-    if (CONFIG_SUBCOMMAND_SET.has(argAfterCommand))
-        return argv;
-    // A single arg after `config` behaves like `git config <key>` and reads the value.
-    if (argAfterKey === undefined) {
-        return buildResult("get", argAfterCommand);
-    }
-    return buildResult("set", argAfterCommand, argAfterKey, ...rest);
-}
 /**
  * Normalize argv so positional view-mode arguments after the asset ref
- * are rewritten into the flag form that citty can parse.
+ * are rewritten into internal flags that citty can parse.
  *
  * Converts:
- *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --view toc
- *   akm show knowledge:guide.md section Auth  → akm show knowledge:guide.md --view section --heading Auth
- *   akm show knowledge:guide.md lines 1 50    → akm show knowledge:guide.md --view lines --start 1 --end 50
+ *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --akmView toc
+ *   akm show knowledge:guide.md section Auth → akm show knowledge:guide.md --akmView section --akmHeading Auth
+ *   akm show knowledge:guide.md lines 1 50   → akm show knowledge:guide.md --akmView lines --akmStart 1 --akmEnd 50
  *
- * If --view is already present the argv is returned unchanged (backward compat).
+ * Legacy `--view` is intentionally unsupported.
  * Returns a new array; the input is never modified.
  */
 function normalizeShowArgv(argv) {
     // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
     if (argv[2] !== "show")
         return argv;
-    // If --view is already present, pass through unchanged
-    if (argv.includes("--view"))
-        return argv;
+    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
+        throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
+    }
     // Separate global flags from positional/show-specific args
     const prefix = argv.slice(0, 3); // [bun, script, show]
     const rest = argv.slice(3);
@@ -891,22 +930,186 @@ function normalizeShowArgv(argv) {
     if (!ref || !viewMode || !SHOW_VIEW_MODES.has(viewMode)) {
         return argv;
     }
-    const result = [...prefix, ref, "--view", viewMode];
+    const result = [...prefix, ref, "--akmView", viewMode];
     if (viewMode === "section") {
         // Next arg is the heading name; pass empty string when missing so the
         // show handler can produce a clear "section not found" error.
         const heading = showArgs[2] ?? "";
-        result.push("--heading", heading);
+        result.push("--akmHeading", heading);
     }
     else if (viewMode === "lines") {
         // Next two args are start and end
         const start = showArgs[2];
         const end = showArgs[3];
         if (start)
-            result.push("--start", start);
+            result.push("--akmStart", start);
         if (end)
-            result.push("--end", end);
+            result.push("--akmEnd", end);
     }
     result.push(...globalFlags);
     return result;
 }
+// ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
+function loadHints(detail = "normal") {
+    const filename = detail === "full" ? "AGENTS.full.md" : "AGENTS.md";
+    const fallback = detail === "full" ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
+    // Try reading from the docs/ directory (works in dev and when installed via npm)
+    try {
+        const docsPath = path.resolve(import.meta.dir ?? __dirname, `../docs/${filename}`);
+        if (fs.existsSync(docsPath)) {
+            return fs.readFileSync(docsPath, "utf8");
+        }
+    }
+    catch {
+        // fall through
+    }
+    // Fallback for compiled binary — inline content
+    return fallback;
+}
+const EMBEDDED_HINTS = `# akm CLI
+
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+
+## Quick Reference
+
+\`\`\`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 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)
+akm registry search "<query>"                 # Search all registries
+\`\`\`
+
+## Primary Asset Types
+
+| Type | What \`akm show\` returns |
+| --- | --- |
+| script | A \`run\` command you can execute directly |
+| skill | Instructions to follow (read the full content) |
+| 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) |
+
+Run \`akm -h\` for the full command reference.
+`;
+const EMBEDDED_HINTS_FULL = `# akm CLI — Full Reference
+
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via \`akm\`. Search the stash first before writing something from scratch.
+
+## Search
+
+\`\`\`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 registry        # Search registries only
+akm search "<query>" --limit 10               # Limit results
+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\` |
+| \`--limit\` | number | \`20\` |
+| \`--format\` | \`json\`, \`text\`, \`yaml\` | \`json\` |
+| \`--detail\` | \`brief\`, \`normal\`, \`full\` | \`brief\` |
+
+## Show
+
+Display an asset by ref. Knowledge assets support view modes as positional arguments.
+
+\`\`\`sh
+akm show script:deploy.sh                     # Show script (returns run command)
+akm show skill:code-review                    # Show skill (returns full content)
+akm show command:release                      # Show command (returns template)
+akm show agent:architect                      # Show agent (returns system prompt)
+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
+\`\`\`
+
+| Type | Key fields returned |
+| --- | --- |
+| script | \`run\`, \`setup\`, \`cwd\` |
+| skill | \`content\` (full SKILL.md) |
+| command | \`template\`, \`description\`, \`parameters\` |
+| agent | \`prompt\`, \`description\`, \`modelHint\`, \`toolPolicy\` |
+| knowledge | \`content\` (with view modes: \`full\`, \`toc\`, \`frontmatter\`, \`section\`, \`lines\`) |
+
+## Install & Manage Kits
+
+\`\`\`sh
+akm add <ref>                                 # Install a kit
+akm add @scope/kit                            # From npm
+akm add owner/repo                            # From GitHub
+akm add ./path/to/local/kit                   # From local directory
+akm list                                      # List installed kits
+akm remove <target>                           # Remove by id or ref
+akm update --all                              # Update all installed kits
+akm update <target> --force                   # Force re-download
+\`\`\`
+
+## Clone
+
+Copy an asset to the working stash or a custom destination for editing.
+
+\`\`\`sh
+akm clone <ref>                               # Clone to working stash
+akm clone <ref> --name new-name               # Rename on clone
+akm clone <ref> --dest ./project/.claude       # Clone to custom location
+akm clone <ref> --force                       # Overwrite existing
+akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
+\`\`\`
+
+When \`--dest\` is provided, \`akm init\` is not required first.
+
+## Registries
+
+\`\`\`sh
+akm registry list                             # List configured registries
+akm registry add <url>                        # Add a registry
+akm registry add <url> --name my-team         # Add with label
+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
+\`\`\`
+
+## Configuration
+
+\`\`\`sh
+akm config list                               # Show current config
+akm config get <key>                          # Read a value
+akm config set <key> <value>                  # Set a value
+akm config unset <key>                        # Remove a key
+akm config path --all                         # Show all config paths
+\`\`\`
+
+## Other Commands
+
+\`\`\`sh
+akm init                                      # Initialize stash directory
+akm index                                     # Rebuild search index
+akm index --full                              # Full reindex
+akm sources                                   # List stash search paths
+akm upgrade                                   # Upgrade akm binary
+akm upgrade --check                           # Check for updates
+akm hints                                     # Print this reference
+\`\`\`
+
+## Output Control
+
+All commands accept \`--format\` and \`--detail\` flags:
+
+- \`--format json\` (default) — structured JSON
+- \`--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
+
+Run \`akm -h\` or \`akm <command> -h\` for per-command help.
+`;

package/dist/common.js

@@ -3,13 +3,6 @@ import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
 import { ConfigError } from "./errors";
 import { getConfigPath, getDefaultStashDir } from "./paths";
-/**
- * Normalize an asset type for output purposes.
- * "tool" is a transparent alias for "script" -- all output should use "script".
- */
-export function normalizeAssetType(type) {
-    return type === "tool" ? "script" : type;
-}
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
 // ── Validators ──────────────────────────────────────────────────────────────