akm-cli 0.6.0-rc1 → 0.6.0

package/dist/cli.js

@@ -2,41 +2,45 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./asset-spec";
-import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./cli-hints";
-import { isWithin, resolveStashDir, tryReadStdinText } from "./common";
-import { generateBashCompletions, installBashCompletions } from "./completions";
-import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./config";
-import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./config-cli";
-import { akmCurate } from "./curate";
-import { closeDatabase, openDatabase } from "./db";
-import { ConfigError, NotFoundError, UsageError } from "./errors";
-import { akmIndex } from "./indexer";
-import { assembleInfo } from "./info";
-import { akmInit } from "./init";
-import { akmListSources, akmRemove, akmUpdate } from "./installed-stashes";
-import { renderMigrationHelp } from "./migration-help";
-import { getOutputMode, initOutputMode, parseFlagValue } from "./output-context";
-import { shapeForCommand } from "./output-shapes";
-import { formatPlain, outputJsonl } from "./output-text";
-import { getCacheDir, getDbPath, getDefaultStashDir } from "./paths";
-import { buildRegistryIndex, writeRegistryIndex } from "./registry-build-index";
-import { searchRegistry } from "./registry-search";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich } from "./remember";
-import { checkForUpdate, performUpgrade } from "./self-update";
-import { akmAdd } from "./stash-add";
-import { akmClone } from "./stash-clone";
-import { saveGitStash } from "./stash-providers/git";
-import { parseAssetRef } from "./stash-ref";
-import { akmSearch, parseSearchSource } from "./stash-search";
-import { akmShowUnified } from "./stash-show";
-import { addStash } from "./stash-source-manage";
-import { insertUsageEvent } from "./usage-events";
+import { generateBashCompletions, installBashCompletions } from "./commands/completions";
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./commands/config-cli";
+import { akmCurate } from "./commands/curate";
+import { assembleInfo } from "./commands/info";
+import { akmInit } from "./commands/init";
+import { akmListSources, akmRemove, akmUpdate } from "./commands/installed-stashes";
+import { renderMigrationHelp } from "./commands/migration-help";
+import { searchRegistry } from "./commands/registry-search";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich, } from "./commands/remember";
+import { akmSearch, parseSearchSource } from "./commands/search";
+import { checkForUpdate, performUpgrade } from "./commands/self-update";
+import { akmShowUnified } from "./commands/show";
+import { akmAdd } from "./commands/source-add";
+import { akmClone } from "./commands/source-clone";
+import { addStash } from "./commands/source-manage";
+import { parseAssetRef } from "./core/asset-ref";
+import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset-spec";
+import { isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
+import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./core/config";
+import { ConfigError, NotFoundError, UsageError } from "./core/errors";
+import { getCacheDir, getDbPath, getDefaultStashDir } from "./core/paths";
+import { setQuiet, warn } from "./core/warn";
+import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
+import { closeDatabase, findEntryIdByRef, openDatabase } from "./indexer/db";
+import { akmIndex } from "./indexer/indexer";
+import { resolveSourceEntries } from "./indexer/search-source";
+import { insertUsageEvent } from "./indexer/usage-events";
+import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints";
+import { getHyphenatedArg, getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue, } from "./output/context";
+import { shapeForCommand } from "./output/shapes";
+import { formatPlain, outputJsonl } from "./output/text";
+import { buildRegistryIndex, writeRegistryIndex } from "./registry/build-index";
+import { resolveSourcesForOrigin } from "./registry/origin-resolve";
+import { saveGitStash } from "./sources/providers/git";
+import { resolveAssetPath } from "./sources/resolve";
 import { pkgVersion } from "./version";
-import { setQuiet, warn } from "./warn";
-import { createWorkflowAsset, getWorkflowTemplate } from "./workflow-authoring";
-import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "./workflow-cli";
-import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "./workflow-runs";
+import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "./workflows/authoring";
+import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "./workflows/cli";
+import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "./workflows/runs";
 const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 const SKILLS_SH_NAME = "skills.sh";
 const SKILLS_SH_URL = "https://skills.sh";
@@ -84,9 +88,9 @@ function output(command, result) {
 }
 /**
  * Module Naming:
- * - stash-*          : Asset operations (search, show, add, clone)
- * - stash-provider-* : Runtime data source providers (filesystem, openviking)
- * - registry-*       : Discovery from remote registries (npm, GitHub)
+ * - sources/*           : Asset operations (search, show, add, clone)
+ * - sources/providers/* : Runtime data source providers (filesystem, git, website, npm)
+ * - registry/*          : Discovery from remote registries (npm, GitHub)
  * - installed-stashes   : Unified source operations (list, remove, update)
  */
 const setupCommand = defineCommand({
@@ -96,7 +100,7 @@ const setupCommand = defineCommand({
     },
     async run() {
         await runWithJsonErrors(async () => {
-            const { runSetupWizard } = await import("./setup");
+            const { runSetupWizard } = await import("./setup/setup");
             await runSetupWizard();
         });
     },
@@ -111,7 +115,10 @@ const initCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await akmInit({ dir: args.dir });
+            // Accept both historical spellings for backwards compatibility with
+            // older docs/scripts that used `--stashDir`.
+            const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
+            const result = await akmInit({ dir: args.dir ?? legacyDir });
             output("init", result);
         });
     },
@@ -156,6 +163,10 @@ const searchCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            const query = (args.query ?? "").trim();
+            if (!query) {
+                throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT");
+            }
             const type = args.type;
             const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
             if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
@@ -163,7 +174,7 @@ const searchCommand = defineCommand({
             }
             const limit = limitRaw;
             const source = parseSearchSource(args.source);
-            const result = await akmSearch({ query: args.query, type, limit, source });
+            const result = await akmSearch({ query, type, limit, source });
             output("search", result);
         });
     },
@@ -204,7 +215,7 @@ const addCommand = defineCommand({
             description: "Path, URL, or registry ref (website URL, npm package, owner/repo, git URL, or local directory)",
             required: true,
         },
-        provider: { type: "string", description: "Provider type (e.g. openviking). Required for URL sources." },
+        provider: { type: "string", description: "Provider type (e.g. website, npm). Required for URL sources." },
         options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
         name: { type: "string", description: "Human-friendly name for the source" },
         writable: {
@@ -262,7 +273,7 @@ const addCommand = defineCommand({
             }
             const websiteOptions = buildWebsiteOptions(args);
             if (args.type === "wiki") {
-                const { registerWikiSource } = await import("./stash-add");
+                const { registerWikiSource } = await import("./commands/source-add");
                 const result = await registerWikiSource({
                     ref,
                     name: args.name,
@@ -370,6 +381,11 @@ const upgradeCommand = defineCommand({
             description: "Skip checksum verification (not recommended)",
             default: false,
         },
+        "skip-post-upgrade": {
+            type: "boolean",
+            description: "Skip the post-upgrade `akm index` rebuild (config auto-migration still runs on next `akm` invocation)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -378,8 +394,9 @@ const upgradeCommand = defineCommand({
                 output("upgrade", check);
                 return;
             }
-            const skipChecksum = Boolean(args["skip-checksum"]);
-            const result = await performUpgrade(check, { force: args.force, skipChecksum });
+            const skipChecksum = getHyphenatedBoolean(args, "skip-checksum");
+            const skipPostUpgrade = getHyphenatedBoolean(args, "skip-post-upgrade");
+            const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
             output("upgrade", result);
         });
     },
@@ -427,7 +444,6 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            // Map CLI detail level to ShowDetailLevel for the show function
             const cliDetail = getOutputMode().detail;
             const showDetail = cliDetail === "summary" ? "summary" : undefined;
             const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail });
@@ -671,7 +687,7 @@ const registryCommand = defineCommand({
                         throw new UsageError("Registry URL must start with http:// or https://");
                     }
                     if (args.url.startsWith("http://")) {
-                        const allowInsecure = Boolean(args["allow-insecure"]);
+                        const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
                         if (!allowInsecure) {
                             throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
                                 "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
@@ -752,11 +768,10 @@ const registryCommand = defineCommand({
             },
             async run({ args }) {
                 await runWithJsonErrors(async () => {
-                    const argsRecord = args;
                     const result = await buildRegistryIndex({
                         manualEntriesPath: args.manual,
-                        npmRegistryBase: typeof argsRecord["npm-registry"] === "string" ? argsRecord["npm-registry"] : undefined,
-                        githubApiBase: typeof argsRecord["github-api"] === "string" ? argsRecord["github-api"] : undefined,
+                        npmRegistryBase: getHyphenatedArg(args, "npm-registry"),
+                        githubApiBase: getHyphenatedArg(args, "github-api"),
                     });
                     const outPath = writeRegistryIndex(result.index, args.out);
                     output("registry-build-index", {
@@ -775,7 +790,7 @@ const registryCommand = defineCommand({
 const feedbackCommand = defineCommand({
     meta: {
         name: "feedback",
-        description: "Record positive or negative feedback for a stash asset",
+        description: "Record positive or negative feedback for any indexed stash asset",
     },
     args: {
         ref: { type: "positional", description: "Asset ref (type:name)", required: true },
@@ -789,6 +804,7 @@ const feedbackCommand = defineCommand({
             if (!ref) {
                 throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative");
             }
+            parseAssetRef(ref);
             if (args.positive && args.negative) {
                 throw new UsageError("Specify either --positive or --negative, not both.");
             }
@@ -799,9 +815,14 @@ const feedbackCommand = defineCommand({
             const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
             const db = openDatabase();
             try {
+                const entryId = findEntryIdByRef(db, ref);
+                if (entryId === undefined) {
+                    throw new UsageError(`Ref "${ref}" is not in the current index. Run "akm index" and try again.`);
+                }
                 insertUsageEvent(db, {
                     event_type: "feedback",
                     entry_ref: ref,
+                    entry_id: entryId,
                     signal,
                     metadata,
                 });
@@ -868,24 +889,30 @@ function readKnowledgeContent(source) {
         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 });
+async function writeMarkdownAsset(options) {
+    // Resolve write target via the v1 precedence chain (`--target` →
+    // `defaultWriteTarget` → working stash). Per spec §10 step 5, this is the
+    // single dispatch point — `core/write-source.ts` owns all kind-branching.
+    const cfg = loadConfig();
+    const { source, config } = resolveWriteTarget(cfg, options.target);
+    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
     const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
+    // Pre-flight: existence + force semantics. The helper itself overwrites
+    // unconditionally; the CLI surfaces a friendlier UsageError before any
+    // disk activity when --force is absent.
     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.`);
+        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
-    fs.mkdirSync(path.dirname(assetPath), { recursive: true });
-    fs.writeFileSync(assetPath, options.content.endsWith("\n") ? options.content : `${options.content}\n`, "utf8");
+    // Delegate the actual write (and optional git commit/push) to the helper.
+    const result = await writeAssetToSource(source, config, { type: options.type, name: normalizedName }, options.content);
     return {
-        ref: `${options.type}:${normalizedName}`,
-        path: assetPath,
-        stashDir,
+        ref: result.ref,
+        path: result.path,
+        stashDir: source.path,
     };
 }
 const workflowStartCommand = defineCommand({
@@ -1023,8 +1050,8 @@ const workflowCreateCommand = defineCommand({
             default: false,
         },
     },
-    run({ args }) {
-        return runWithJsonErrors(() => {
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
             const namePattern = /^[a-z0-9][a-z0-9._/-]*$/;
             if (!namePattern.test(args.name)) {
                 throw new UsageError("Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, dots, underscores, and slashes.");
@@ -1037,6 +1064,10 @@ const workflowCreateCommand = defineCommand({
                 from: args.from,
                 force: args.force,
             });
+            // Index the newly-written workflow so `akm workflow start` can resolve
+            // a workflowEntryId without requiring an explicit `akm index` call
+            // first. Uses the same incremental index path that `akm add` uses.
+            await akmIndex({ stashDir: result.stashDir });
             output("workflow-create", { ok: true, ...result });
         });
     },
@@ -1050,6 +1081,55 @@ const workflowTemplateCommand = defineCommand({
         process.stdout.write(getWorkflowTemplate());
     },
 });
+const workflowValidateCommand = defineCommand({
+    meta: {
+        name: "validate",
+        description: "Validate a workflow markdown file or ref and print any errors",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md",
+            required: true,
+        },
+    },
+    async run({ args }) {
+        return runWithJsonErrors(async () => {
+            const filePath = await resolveWorkflowFilePath(args.target);
+            const { parse } = validateWorkflowSource(filePath);
+            if (parse.ok) {
+                output("workflow-validate", {
+                    ok: true,
+                    path: filePath,
+                    title: parse.document.title,
+                    stepCount: parse.document.steps.length,
+                });
+                return;
+            }
+            throw new UsageError(formatWorkflowErrors(filePath, parse.errors));
+        });
+    },
+});
+async function resolveWorkflowFilePath(target) {
+    if (!target.startsWith("workflow:"))
+        return target;
+    const parsed = parseAssetRef(target);
+    if (parsed.type !== "workflow") {
+        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${target}".`);
+    }
+    const config = loadConfig();
+    const allSources = resolveSourceEntries(undefined, config);
+    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    for (const source of searchSources) {
+        try {
+            return await resolveAssetPath(source.path, "workflow", parsed.name);
+        }
+        catch {
+            /* try next source */
+        }
+    }
+    throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
+}
 const workflowResumeCommand = defineCommand({
     meta: {
         name: "resume",
@@ -1079,6 +1159,7 @@ const workflowCommand = defineCommand({
         create: workflowCreateCommand,
         template: workflowTemplateCommand,
         resume: workflowResumeCommand,
+        validate: workflowValidateCommand,
     },
     run({ args }) {
         return runWithJsonErrors(() => {
@@ -1108,6 +1189,10 @@ const rememberCommand = defineCommand({
             description: "Overwrite an existing memory with the same name",
             default: false,
         },
+        description: {
+            type: "string",
+            description: "Short description written to frontmatter (persisted as the memory's description field)",
+        },
         tag: {
             type: "string",
             description: "Tag to add to the memory (repeatable: --tag foo --tag bar)",
@@ -1130,6 +1215,10 @@ const rememberCommand = defineCommand({
             description: "Call the configured LLM to propose tags and description (requires LLM config)",
             default: false,
         },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
@@ -1138,15 +1227,15 @@ const rememberCommand = defineCommand({
             // Collect all --tag occurrences directly from process.argv because citty
             // only exposes the last value for repeated string flags.
             const rawTags = parseAllFlagValues("--tag");
-            const hasStructuredArgs = rawTags.length > 0 || !!args.expires || !!args.source || args.auto || args.enrich;
-            // Zero-flag path: write bare memory (no frontmatter). Preserve existing behaviour.
+            const hasStructuredArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.auto || args.enrich;
             if (!hasStructuredArgs) {
-                const result = writeMarkdownAsset({
+                const result = await writeMarkdownAsset({
                     type: "memory",
                     content: body,
                     name: args.name,
                     fallbackPrefix: "memory",
                     force: args.force,
+                    target: args.target,
                 });
                 output("remember", { ok: true, ...result });
                 return;
@@ -1154,7 +1243,8 @@ const rememberCommand = defineCommand({
             // ── Accumulate metadata from all three modes ──────────────────────────
             // Start with CLI args (Mode 1: always)
             const tags = [...rawTags];
-            let description;
+            // --description is persisted as-is; LLM enrichment may fill it if absent.
+            let description = args.description || undefined;
             let source = args.source;
             let observed_at;
             let expires;
@@ -1209,12 +1299,13 @@ const rememberCommand = defineCommand({
                 subjective,
             });
             const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
-            const result = writeMarkdownAsset({
+            const result = await writeMarkdownAsset({
                 type: "memory",
                 content: contentWithFrontmatter,
                 name: args.name,
                 fallbackPrefix: "memory",
                 force: args.force,
+                target: args.target,
             });
             output("remember", { ok: true, ...result });
         });
@@ -1240,17 +1331,22 @@ const importKnowledgeCommand = defineCommand({
             description: "Overwrite an existing knowledge document with the same name",
             default: false,
         },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
             const { content, preferredName } = readKnowledgeContent(args.source);
-            const result = writeMarkdownAsset({
+            const result = await writeMarkdownAsset({
                 type: "knowledge",
                 content,
                 name: args.name,
                 fallbackPrefix: "knowledge",
                 preferredName,
                 force: args.force,
+                target: args.target,
             });
             output("import", { ok: true, source: args.source, ...result });
         });
@@ -1266,7 +1362,7 @@ const hintsCommand = defineCommand({
     },
     run({ args }) {
         if (args.detail !== "normal" && args.detail !== "full") {
-            throw new UsageError(`Invalid value for --detail: ${args.detail}. Expected one of: normal|full.`);
+            throw new UsageError(`Invalid value for --detail: ${args.detail}. Expected one of: normal|full.`, "INVALID_DETAIL_VALUE");
         }
         process.stdout.write(loadHints(args.detail));
     },
@@ -1446,14 +1542,14 @@ const vaultListCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { listKeys } = await import("./vault.js");
+            const { listKeys, listEntries } = await import("./commands/vault.js");
             if (args.ref) {
                 const { name, absPath } = resolveVaultPath(args.ref);
                 if (!fs.existsSync(absPath)) {
                     throw new NotFoundError(`Vault not found: vault:${name}`);
                 }
-                const { keys, comments } = listKeys(absPath);
-                output("vault-list", { ref: `vault:${name}`, path: absPath, keys, comments });
+                const entries = listEntries(absPath);
+                output("vault-list", { ref: `vault:${name}`, path: absPath, entries });
                 return;
             }
             const vaults = listVaultsRecursive(listKeys);
@@ -1468,7 +1564,7 @@ const vaultCreateCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { createVault } = await import("./vault.js");
+            const { createVault } = await import("./commands/vault.js");
             const { name, absPath } = resolveVaultPath(args.name);
             createVault(absPath);
             output("vault-create", { ref: `vault:${name}`, path: absPath });
@@ -1492,7 +1588,7 @@ const vaultSetCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { setKey } = await import("./vault.js");
+            const { setKey } = await import("./commands/vault.js");
             const { name, absPath } = resolveVaultPath(args.ref);
             let realKey;
             let realValue;
@@ -1518,7 +1614,7 @@ const vaultUnsetCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { unsetKey } = await import("./vault.js");
+            const { unsetKey } = await import("./commands/vault.js");
             const { name, absPath } = resolveVaultPath(args.ref);
             if (!fs.existsSync(absPath)) {
                 throw new NotFoundError(`Vault not found: vault:${name}`);
@@ -1544,7 +1640,7 @@ const vaultLoadCommand = defineCommand({
             if (!fs.existsSync(absPath)) {
                 throw new NotFoundError(`Vault not found: vault:${name}`);
             }
-            const { buildShellExportScript } = await import("./vault.js");
+            const { buildShellExportScript } = await import("./commands/vault.js");
             const crypto = await import("node:crypto");
             const os = await import("node:os");
             // Parse via dotenv (no expansion, no code execution) and build a
@@ -1575,13 +1671,13 @@ const vaultShowCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { listKeys } = await import("./vault.js");
+            const { listEntries } = await import("./commands/vault.js");
             const { name, absPath } = resolveVaultPath(args.ref);
             if (!fs.existsSync(absPath)) {
                 throw new NotFoundError(`Vault not found: vault:${name}`);
             }
-            const { keys, comments } = listKeys(absPath);
-            output("vault-list", { ref: `vault:${name}`, path: absPath, keys, comments });
+            const entries = listEntries(absPath);
+            output("vault-list", { ref: `vault:${name}`, path: absPath, entries });
         });
     },
 });
@@ -1603,7 +1699,7 @@ const vaultCommand = defineCommand({
             if (hasVaultSubcommand(args))
                 return;
             // Default action: list all vaults
-            const { listKeys } = await import("./vault.js");
+            const { listKeys } = await import("./commands/vault.js");
             output("vault-list", { vaults: listVaultsRecursive(listKeys) });
         });
     },
@@ -1616,7 +1712,7 @@ const wikiCreateCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { createWiki } = await import("./wiki.js");
+            const { createWiki } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const result = createWiki(stashDir, args.name);
             output("wiki-create", result);
@@ -1646,7 +1742,7 @@ const wikiRegisterCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { registerWikiSource } = await import("./stash-add");
+            const { registerWikiSource } = await import("./commands/source-add");
             const result = await registerWikiSource({
                 ref: args.ref.trim(),
                 name: args.name,
@@ -1662,7 +1758,7 @@ const wikiListCommand = defineCommand({
     meta: { name: "list", description: "List wikis with page/raw counts and last-modified timestamps" },
     run() {
         return runWithJsonErrors(async () => {
-            const { listWikis } = await import("./wiki.js");
+            const { listWikis } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const wikis = listWikis(stashDir);
             output("wiki-list", { wikis });
@@ -1676,7 +1772,7 @@ const wikiShowCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { showWiki } = await import("./wiki.js");
+            const { showWiki } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const result = showWiki(stashDir, args.name);
             output("wiki-show", result);
@@ -1706,9 +1802,9 @@ const wikiRemoveCommand = defineCommand({
             if (!args.force) {
                 throw new UsageError("Refusing to remove without --force. Pass `--force` to confirm.");
             }
-            const withSources = Boolean(args["with-sources"]);
-            const { removeWiki } = await import("./wiki.js");
-            const { akmIndex } = await import("./indexer");
+            const withSources = getHyphenatedBoolean(args, "with-sources");
+            const { removeWiki } = await import("./wiki/wiki.js");
+            const { akmIndex } = await import("./indexer/indexer");
             const stashDir = resolveStashDir();
             const result = removeWiki(stashDir, args.name, { withSources });
             await akmIndex({ stashDir });
@@ -1726,7 +1822,7 @@ const wikiPagesCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { listPages } = await import("./wiki.js");
+            const { listPages } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const pages = listPages(stashDir, args.name);
             output("wiki-pages", { wiki: args.name, pages });
@@ -1745,7 +1841,7 @@ const wikiSearchCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { resolveWikiSource, searchInWiki } = await import("./wiki.js");
+            const { resolveWikiSource, searchInWiki } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             resolveWikiSource(stashDir, args.name);
             const parsedLimit = args.limit ? Number(args.limit) : undefined;
@@ -1767,7 +1863,7 @@ const wikiStashCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { stashRaw } = await import("./wiki.js");
+            const { stashRaw } = await import("./wiki/wiki.js");
             const { content, preferredName } = readKnowledgeContent(args.source);
             const stashDir = resolveStashDir();
             const result = stashRaw({
@@ -1792,7 +1888,7 @@ const wikiLintCommand = defineCommand({
     async run({ args }) {
         let findingCount = 0;
         await runWithJsonErrors(async () => {
-            const { lintWiki } = await import("./wiki.js");
+            const { lintWiki } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const report = lintWiki(stashDir, args.name);
             output("wiki-lint", report);
@@ -1812,7 +1908,7 @@ const wikiIngestCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { buildIngestWorkflow } = await import("./wiki.js");
+            const { buildIngestWorkflow } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
             const result = buildIngestWorkflow(stashDir, args.name);
             output("wiki-ingest", result);
@@ -1841,7 +1937,7 @@ const wikiCommand = defineCommand({
             if (hasWikiSubcommand(args))
                 return;
             // Default action: list wikis
-            const { listWikis } = await import("./wiki.js");
+            const { listWikis } = await import("./wiki/wiki.js");
             output("wiki-list", { wikis: listWikis(resolveStashDir()) });
         });
     },
@@ -1919,7 +2015,7 @@ try {
 }
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const hint = buildHint(message);
+    const hint = extractHint(error);
     const exitCode = classifyExitCode(error);
     const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
         ? error.code
@@ -1947,7 +2043,7 @@ async function runWithJsonErrors(fn) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        const hint = buildHint(message);
+        const hint = extractHint(error);
         const exitCode = classifyExitCode(error);
         // Surface machine-readable error code from typed errors when present so
         // scripts can branch on `.code` instead of message-string matching.
@@ -1958,25 +2054,14 @@ async function runWithJsonErrors(fn) {
         process.exit(exitCode);
     }
 }
-function buildHint(message) {
-    if (message.includes("No stash directory found"))
-        return "Run `akm init` to create the default stash, or set stashDir in your config.";
-    if (message.includes("Either <target> or --all is required"))
-        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 matching source"))
-        return "Run `akm list` to view your sources, 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.";
-    if (message.includes("Invalid value for --source"))
-        return "Pick one of: stash, registry, both.";
-    if (message.includes("Invalid value for --format"))
-        return "Pick one of: json, jsonl, text, yaml.";
-    if (message.includes("Invalid value for --detail"))
-        return "Pick one of: brief, normal, full, summary, agent.";
-    if (message.includes("expected JSON object with endpoint and model")) {
-        return 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.';
+/**
+ * Extract an actionable hint from an error instance. Hints live on the error
+ * classes themselves (see src/errors.ts) — either supplied explicitly at the
+ * throw site, or derived from the error code via the per-class default mapping.
+ */
+function extractHint(error) {
+    if (error instanceof Error && "hint" in error && typeof error.hint === "function") {
+        return error.hint();
     }
     return undefined;
 }