akm-cli 0.6.1 → 0.7.0

package/dist/{core → src/core}/config.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { parseAgentConfig } from "../integrations/agent/config";
 import { filterNonEmptyStrings } from "./common";
 import { ConfigError } from "./errors";
 import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
@@ -73,7 +74,7 @@ export function loadUserConfig() {
         cachedUserConfig.contentHash === contentHash) {
         return cachedUserConfig.config;
     }
-    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfigFromText(configPath, text));
+    const config = mergeLoadedConfig(DEFAULT_CONFIG, readNormalizedConfigFromText(text));
     const finalConfig = applyRuntimeEnvApiKeys(config);
     cachedUserConfig = {
         config: finalConfig,
@@ -144,6 +145,14 @@ export function updateConfig(partial) {
     if (current.llm && partial.llm && partial.llm !== current.llm) {
         merged.llm = { ...current.llm, ...partial.llm };
     }
+    // Deep-merge index per-pass entries so partial updates don't wipe siblings.
+    if (current.index && partial.index && partial.index !== current.index) {
+        const mergedIndex = { ...current.index };
+        for (const [passName, passOverride] of Object.entries(partial.index)) {
+            mergedIndex[passName] = { ...(mergedIndex[passName] ?? {}), ...passOverride };
+        }
+        merged.index = mergedIndex;
+    }
     if (current.security && partial.security && partial.security !== current.security) {
         merged.security = mergeSecurityConfig(current.security, partial.security);
     }
@@ -160,6 +169,9 @@ export function updateConfig(partial) {
  */
 function pickKnownKeys(raw) {
     const config = {};
+    if (Array.isArray(raw.stashes)) {
+        throw new ConfigError("The legacy `stashes[]` config key is no longer supported; rename it to `sources[]`.", "INVALID_CONFIG_FILE", `Edit ${_getConfigPath()} and replace \`stashes\` with \`sources\`.`);
+    }
     if (typeof raw.stashDir === "string" && raw.stashDir.trim()) {
         config.stashDir = raw.stashDir.trim();
     }
@@ -170,59 +182,28 @@ function pickKnownKeys(raw) {
     else if (raw.semanticSearchMode === "off" || raw.semanticSearchMode === "auto") {
         config.semanticSearchMode = raw.semanticSearchMode;
     }
-    else if (typeof raw.semanticSearch === "boolean") {
-        // Legacy config: older versions used `semanticSearch` (boolean) instead of `semanticSearchMode`
-        const legacySemanticSearch = raw.semanticSearch;
-        config.semanticSearchMode = legacySemanticSearch ? "auto" : "off";
-    }
-    // Migrate legacy searchPaths into sources
-    if (Array.isArray(raw.searchPaths)) {
-        const legacyPaths = raw.searchPaths.filter((d) => typeof d === "string");
-        if (legacyPaths.length > 0) {
-            const existing = config.sources ?? [];
-            const migrated = legacyPaths
-                .filter((p) => !existing.some((s) => s.type === "filesystem" && s.path === p))
-                .map((p) => ({ type: "filesystem", path: p }));
-            if (migrated.length > 0) {
-                config.sources = [...existing, ...migrated];
-            }
-        }
-    }
     const embedding = parseEmbeddingConfig(raw.embedding);
     if (embedding)
         config.embedding = embedding;
     const llm = parseLlmConfig(raw.llm);
     if (llm)
         config.llm = llm;
+    const index = parseIndexConfig(raw.index);
+    if (index)
+        config.index = index;
     const installed = parseInstalledEntries(raw.installed);
     if (installed)
         config.installed = installed;
     const registries = parseRegistriesConfig(raw.registries);
     if (registries)
         config.registries = registries;
-    // Prefer the new `stashInheritance` field; fall back to the legacy boolean
-    // `disableGlobalStashes` so existing config files keep working unchanged.
     if (raw.stashInheritance === "replace" || raw.stashInheritance === "merge") {
         config.stashInheritance = raw.stashInheritance;
     }
-    else if (typeof raw.disableGlobalStashes === "boolean") {
-        config.stashInheritance = raw.disableGlobalStashes ? "replace" : "merge";
-        config.disableGlobalStashes = raw.disableGlobalStashes;
-    }
-    // Load `sources` (new key) first, then fall back to legacy `stashes` key.
-    const sources = parseStashesConfig(raw.sources);
+    const sources = parseSourcesConfig(raw.sources);
     if (sources) {
         config.sources = sources;
     }
-    else {
-        const legacyStashes = parseStashesConfig(raw.stashes);
-        if (legacyStashes) {
-            // Backwards-compat fallback: configs that still carry `stashes[]` are
-            // normalized to `sources[]` after the raw file loader has had a chance to
-            // auto-migrate the on-disk key.
-            config.sources = legacyStashes;
-        }
-    }
     const security = parseSecurityConfig(raw.security);
     if (security)
         config.security = security;
@@ -235,6 +216,11 @@ function pickKnownKeys(raw) {
     if (typeof raw.defaultWriteTarget === "string" && raw.defaultWriteTarget.trim()) {
         config.defaultWriteTarget = raw.defaultWriteTarget.trim();
     }
+    if ("agent" in raw) {
+        const agent = parseAgentConfig(raw.agent);
+        if (agent)
+            config.agent = agent;
+    }
     if (typeof raw.search === "object" && raw.search !== null && !Array.isArray(raw.search)) {
         const searchRaw = raw.search;
         const searchConfig = {};
@@ -248,16 +234,14 @@ function pickKnownKeys(raw) {
 }
 function readNormalizedConfig(configPath) {
     const raw = readConfigObject(configPath);
-    const migrated = raw ? maybeAutoMigrateLegacyStashes(configPath, raw) : undefined;
-    const expanded = migrated ? expandEnvVars(migrated) : undefined;
+    const expanded = raw ? expandEnvVars(raw) : undefined;
     return expanded ? pickKnownKeys(expanded) : undefined;
 }
-function readNormalizedConfigFromText(configPath, text) {
+function readNormalizedConfigFromText(text) {
     const raw = parseConfigObjectFromText(text);
     if (!raw)
         return undefined;
-    const migrated = maybeAutoMigrateLegacyStashes(configPath, raw);
-    const expanded = expandEnvVars(migrated);
+    const expanded = expandEnvVars(raw);
     return pickKnownKeys(expanded);
 }
 function parseOutputConfig(value) {
@@ -337,31 +321,6 @@ function parseConfigObjectFromText(text) {
         return undefined;
     }
 }
-/**
- * Best-effort on-disk config migration for the legacy `stashes` key.
- *
- * When a config file still uses `stashes` and does not already define
- * `sources`, rewrite the file in place with `sources` replacing `stashes`,
- * emit a one-time notice on success, and return the migrated object. If the
- * rewrite fails, emit a warning and return the original object so the loader
- * can still continue with an in-memory fallback.
- */
-function maybeAutoMigrateLegacyStashes(configPath, raw) {
-    if (Object.hasOwn(raw, "sources") || !Object.hasOwn(raw, "stashes")) {
-        return raw;
-    }
-    const migrated = Object.fromEntries(Object.entries(raw).map(([key, value]) => (key === "stashes" ? ["sources", value] : [key, value])));
-    try {
-        writeConfigObject(configPath, migrated);
-        warn('Config migrated: "stashes" → "sources" in config.json');
-        return migrated;
-    }
-    catch {
-        warn('Failed to migrate "stashes" → "sources" in config.json; continuing with the legacy key in memory. ' +
-            "Check file permissions or rename the key manually if this persists.");
-        return raw;
-    }
-}
 function writeConfigObject(configPath, config) {
     const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
     try {
@@ -443,7 +402,7 @@ function parseEmbeddingConfig(value) {
         return undefined;
     }
     if (!obj.endpoint.startsWith("http://") && !obj.endpoint.startsWith("https://")) {
-        console.warn(`[akm] Ignoring embedding config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
+        warn(`[akm] Ignoring embedding config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         // Still return localModel-only config if localModel was set
         if (localModel) {
             return { endpoint: "", model: "", localModel };
@@ -453,7 +412,7 @@ function parseEmbeddingConfig(value) {
     if (typeof obj.model !== "string" || !obj.model) {
         // No remote model, but localModel may still be valid
         if (localModel) {
-            console.warn(`[akm] Embedding endpoint "${obj.endpoint}" ignored: model is required for remote embeddings. Using local model only.`);
+            warn(`[akm] Embedding endpoint "${obj.endpoint}" ignored: model is required for remote embeddings. Using local model only.`);
             return { endpoint: "", model: "", localModel };
         }
         return undefined;
@@ -480,6 +439,28 @@ function parseEmbeddingConfig(value) {
     if (localModel) {
         result.localModel = localModel;
     }
+    if ("contextLength" in obj) {
+        if (typeof obj.contextLength !== "number" ||
+            !Number.isFinite(obj.contextLength) ||
+            !Number.isInteger(obj.contextLength) ||
+            obj.contextLength <= 0) {
+            return undefined;
+        }
+        result.contextLength = obj.contextLength;
+    }
+    if (typeof obj.ollamaOptions === "object" && obj.ollamaOptions !== null && !Array.isArray(obj.ollamaOptions)) {
+        const opts = obj.ollamaOptions;
+        const parsed = {};
+        if (typeof opts.num_ctx === "number" &&
+            Number.isFinite(opts.num_ctx) &&
+            Number.isInteger(opts.num_ctx) &&
+            opts.num_ctx > 0) {
+            parsed.num_ctx = opts.num_ctx;
+        }
+        if (Object.keys(parsed).length > 0) {
+            result.ollamaOptions = parsed;
+        }
+    }
     return result;
 }
 function parseLlmConfig(value) {
@@ -489,7 +470,7 @@ function parseLlmConfig(value) {
     if (typeof obj.endpoint !== "string" || !obj.endpoint)
         return undefined;
     if (!obj.endpoint.startsWith("http://") && !obj.endpoint.startsWith("https://")) {
-        console.warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
+        warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
     const model = typeof obj.model === "string" ? obj.model : "";
@@ -515,26 +496,122 @@ function parseLlmConfig(value) {
     if (typeof obj.apiKey === "string" && obj.apiKey) {
         result.apiKey = obj.apiKey;
     }
-    if (typeof obj.contextWindow === "number" &&
-        Number.isFinite(obj.contextWindow) &&
-        Number.isInteger(obj.contextWindow) &&
-        obj.contextWindow > 0) {
-        result.contextWindow = obj.contextWindow;
-    }
     if (typeof obj.capabilities === "object" && obj.capabilities !== null && !Array.isArray(obj.capabilities)) {
         const capsRaw = obj.capabilities;
         const caps = {};
         if (typeof capsRaw.structuredOutput === "boolean")
             caps.structuredOutput = capsRaw.structuredOutput;
-        if (typeof capsRaw.longContext === "boolean")
-            caps.longContext = capsRaw.longContext;
-        if (typeof capsRaw.toolUse === "boolean")
-            caps.toolUse = capsRaw.toolUse;
         if (Object.keys(caps).length > 0)
             result.capabilities = caps;
     }
+    if (typeof obj.features === "object" && obj.features !== null && !Array.isArray(obj.features)) {
+        const features = parseLlmFeatures(obj.features);
+        if (Object.keys(features).length > 0)
+            result.features = features;
+    }
     return result;
 }
+/**
+ * v1 spec §14 — locked feature keys. Defined here so unknown keys can
+ * be warn-and-ignored at load time (per spec §14.3 / §9.2). The set is
+ * deliberately the *full* locked table even though only a subset has
+ * runtime parsing today; this lets users author future-flagged configs
+ * without spurious warnings.
+ */
+const LOCKED_LLM_FEATURE_KEYS = new Set([
+    "curate_rerank",
+    "feedback_distillation",
+    "memory_inference",
+    "graph_extraction",
+]);
+function parseLlmFeatures(raw) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!LOCKED_LLM_FEATURE_KEYS.has(key)) {
+            warn(`[akm] Ignoring unknown llm.features key "${key}".`);
+            continue;
+        }
+        if (typeof value !== "boolean") {
+            warn(`[akm] Ignoring llm.features.${key}: expected boolean, got ${typeof value}.`);
+            continue;
+        }
+        switch (key) {
+            case "memory_inference":
+                out.memory_inference = value;
+                break;
+            case "graph_extraction":
+                out.graph_extraction = value;
+                break;
+            case "curate_rerank":
+                out.curate_rerank = value;
+                break;
+            case "feedback_distillation":
+                out.feedback_distillation = value;
+                break;
+            // No default: LOCKED_LLM_FEATURE_KEYS is the source of truth for which
+            // keys are accepted. Adding a new locked key requires an arm here AND a
+            // field on LlmFeatureFlags above.
+        }
+    }
+    return out;
+}
+/**
+ * Keys that, if present anywhere under `index.<pass>`, indicate the user is
+ * trying to supply a parallel LLM provider configuration. Per #208 this is
+ * deliberately rejected at load time so there is exactly one place to
+ * configure the LLM (`akm.llm`).
+ */
+const PROVIDER_CONFIG_KEYS = new Set([
+    "endpoint",
+    "model",
+    "provider",
+    "apiKey",
+    "baseUrl",
+    "temperature",
+    "maxTokens",
+    "capabilities",
+]);
+/**
+ * Parse the `index` config block. Each entry is a pass name → small object
+ * `{ llm?: boolean }`. Anything richer (a parallel provider config, unknown
+ * keys, non-boolean `llm`) throws `ConfigError("INVALID_CONFIG_FILE")` at
+ * load time so the failure is visible at startup, not on the next index run.
+ */
+function parseIndexConfig(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new ConfigError('Invalid `index` config: expected an object keyed by pass name (e.g. `{ "enrichment": { "llm": false } }`).', "INVALID_CONFIG_FILE");
+    }
+    const out = {};
+    for (const [passName, raw] of Object.entries(value)) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            throw new ConfigError(`Invalid \`index.${passName}\` config: expected an object like \`{ "llm": false }\`.`, "INVALID_CONFIG_FILE");
+        }
+        const passRaw = raw;
+        // Reject any provider-shaped key — there must be exactly one place to
+        // configure the LLM (#208). This is the duplicate-provider guard.
+        for (const key of Object.keys(passRaw)) {
+            if (PROVIDER_CONFIG_KEYS.has(key)) {
+                throw new ConfigError(`Duplicate LLM provider configuration: \`index.${passName}.${key}\` is not allowed. ` +
+                    "Configure provider/model/endpoint under top-level `llm` only; per-pass entries support `{ llm: false }` opt-out.", "INVALID_CONFIG_FILE", 'Move provider settings to the top-level "llm" block, then set `index.<pass>.llm = false` to opt a single pass out.');
+            }
+            if (key !== "llm") {
+                throw new ConfigError(`Unknown key \`index.${passName}.${key}\`. Per-pass entries only support \`llm\` (boolean opt-out).`, "INVALID_CONFIG_FILE");
+            }
+        }
+        const passConfig = {};
+        if ("llm" in passRaw) {
+            const llmFlag = passRaw.llm;
+            if (typeof llmFlag !== "boolean") {
+                throw new ConfigError(`Invalid \`index.${passName}.llm\`: expected a boolean (true to use \`akm.llm\`, false to opt out). Got ${typeof llmFlag}.`, "INVALID_CONFIG_FILE", "Per-pass alternative provider config is intentionally unsupported in v1 (#208). Use `false` to disable LLM for this pass.");
+            }
+            passConfig.llm = llmFlag;
+        }
+        out[passName] = passConfig;
+    }
+    return out;
+}
 function parseInstalledEntries(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -567,6 +644,9 @@ function parseInstalledStashEntry(value) {
     };
     if (typeof obj.writable === "boolean")
         entry.writable = obj.writable;
+    if (entry.writable === true && entry.source !== "git") {
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.source}" on installed entry "${entry.id}").`, "INVALID_CONFIG_FILE", "Remove `writable: true` from the installed entry or re-add it as a git source instead.");
+    }
     const resolvedVersion = asNonEmptyString(obj.resolvedVersion);
     if (resolvedVersion)
         entry.resolvedVersion = resolvedVersion;
@@ -604,7 +684,7 @@ function parseRegistriesConfig(value) {
     // which overrides the default. Only return undefined if the field was not an array.
     return entries;
 }
-function parseStashesConfig(value) {
+function parseSourcesConfig(value) {
     if (!Array.isArray(value))
         return undefined;
     const entries = value
@@ -669,28 +749,17 @@ function parseInstallAuditAllowedFinding(value) {
         finding.reason = reason;
     return finding;
 }
-/**
- * Legacy stash type aliases that are normalized to canonical types at
- * config-load time. Both "context-hub" and "github" were never distinct
- * provider types — they were always git stashes — so we normalize them in
- * memory to "git" without rewriting `config.json` on disk.
- */
-const STASH_TYPE_ALIASES = {
-    "context-hub": "git",
-    github: "git",
-};
 function parseSourceConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
     const obj = value;
-    const rawType = asNonEmptyString(obj.type);
-    if (!rawType)
+    const type = asNonEmptyString(obj.type);
+    if (!type)
         return undefined;
-    if (rawType === "openviking") {
+    if (type === "openviking") {
         const name = asNonEmptyString(obj.name) ?? "unnamed";
         throw new ConfigError(`openviking is not supported in akm v1. API-backed sources will return as a\nseparate QuerySource tier post-v1. Remove the source named "${name}" from your config file\nor downgrade to 0.6.x. See docs/migration/v1.md.`, "INVALID_CONFIG_FILE", `Run \`akm remove ${name}\` then re-run, or edit your config file directly at ${_getConfigPath()} to remove the openviking entry.`);
     }
-    const type = STASH_TYPE_ALIASES[rawType] ?? rawType;
     const entry = { type };
     const entryPath = asNonEmptyString(obj.path);
     if (entryPath)
@@ -746,19 +815,15 @@ function deriveStashEntryName(entry) {
  * entry is missing the fields its provider type requires (e.g. a
  * `filesystem` entry with no `path`); callers should drop or warn for those.
  *
- * Unknown provider types fall back to `{ type: "filesystem", path: ... }` so
- * legacy aliases (`"context-hub"`, `"github"` for git) still produce a usable
- * runtime value when a path/url is supplied.
+ * Unknown provider types fall back to `{ type: "filesystem", path: ... }` when
+ * a `path` is supplied, so future provider types still produce a usable
+ * runtime value.
  */
 export function parseSourceSpec(entry) {
     switch (entry.type) {
         case "filesystem":
             return entry.path ? { type: "filesystem", path: entry.path } : undefined;
         case "git":
-        case "context-hub":
-        case "github":
-            // Note: a configured `github` provider entry historically meant "git
-            // repo over the GitHub web URL", not the registry-install `github:` ref.
             return entry.url ? { type: "git", url: entry.url } : undefined;
         case "website":
             return entry.url
@@ -792,11 +857,9 @@ export function parseSourceSpec(entry) {
  */
 export function resolveConfiguredSources(config) {
     const entries = [];
-    // `sources` is the canonical key. `stashes` is the legacy key that the loader
-    // migrates in-memory; only one of the two should be set at runtime.
-    const stashes = config.sources ?? config.stashes ?? [];
+    const sources = config.sources ?? [];
     // (1) Primary entry: explicit `primary: true` wins; fall back to top-level stashDir.
-    let primary = stashes.find((entry) => entry.primary === true);
+    let primary = sources.find((entry) => entry.primary === true);
     if (!primary && config.stashDir) {
         primary = { type: "filesystem", path: config.stashDir, primary: true };
     }
@@ -805,8 +868,8 @@ export function resolveConfiguredSources(config) {
         if (runtime)
             entries.push(runtime);
     }
-    // (2) Declared stashes (skip the primary entry — already added).
-    for (const entry of stashes) {
+    // (2) Declared sources (skip the primary entry — already added).
+    for (const entry of sources) {
         if (entry === primary)
             continue;
         const runtime = toConfiguredSource(entry, false);
@@ -862,6 +925,20 @@ function parseRegistryConfigEntry(value) {
     }
     return entry;
 }
+function mergeAgentConfig(base, override) {
+    const merged = { ...base, ...override };
+    const baseProfiles = base.profiles;
+    const overrideProfiles = override.profiles;
+    if (baseProfiles && overrideProfiles) {
+        const profiles = { ...baseProfiles };
+        for (const [name, entry] of Object.entries(overrideProfiles)) {
+            const existing = baseProfiles[name];
+            profiles[name] = existing ? { ...existing, ...entry } : entry;
+        }
+        merged.profiles = profiles;
+    }
+    return merged;
+}
 function mergeSecurityConfig(base, override) {
     if (!base && !override)
         return undefined;
@@ -882,9 +959,8 @@ function mergeInstallAuditConfig(base, override) {
  *
  * Scalar fields follow normal override semantics. Known nested objects are
  * deep-merged so project config files can override individual fields without
- * clobbering sibling settings. `stashes` are additive by default, but a later
- * layer can set `stashInheritance: "replace"` (or the legacy
- * `disableGlobalStashes: true`) to drop inherited stashes first.
+ * clobbering sibling settings. `sources` are additive by default, but a later
+ * layer can set `stashInheritance: "replace"` to drop inherited sources first.
  */
 function mergeLoadedConfig(base, override) {
     if (!override)
@@ -902,18 +978,26 @@ function mergeLoadedConfig(base, override) {
     if (base.llm && override.llm) {
         merged.llm = { ...base.llm, ...override.llm };
     }
+    if (base.index || override.index) {
+        // Deep-merge per-pass entries so a project layer can opt one pass out
+        // without dropping siblings configured in user config.
+        const mergedIndex = { ...(base.index ?? {}) };
+        for (const [passName, passOverride] of Object.entries(override.index ?? {})) {
+            mergedIndex[passName] = { ...(mergedIndex[passName] ?? {}), ...passOverride };
+        }
+        if (Object.keys(mergedIndex).length > 0)
+            merged.index = mergedIndex;
+    }
     if (base.security && override.security) {
         merged.security = mergeSecurityConfig(base.security, override.security);
     }
-    // The new `stashInheritance` field wins; fall back to the legacy
-    // `disableGlobalStashes` boolean so old config files behave identically.
-    const replaceStashes = override.stashInheritance === "replace" ||
-        (override.stashInheritance === undefined && override.disableGlobalStashes === true);
-    // Merge `sources` (canonical key). Legacy `stashes` key is handled via the
-    // pickKnownKeys migration which promotes it to `sources` at load time.
-    const overrideSources = override.sources ?? override.stashes ?? [];
-    const baseSources = base.sources ?? base.stashes ?? [];
-    if (replaceStashes) {
+    if (base.agent && override.agent) {
+        merged.agent = mergeAgentConfig(base.agent, override.agent);
+    }
+    const replaceSources = override.stashInheritance === "replace";
+    const overrideSources = override.sources ?? [];
+    const baseSources = base.sources ?? [];
+    if (replaceSources) {
         merged.sources = [...overrideSources];
     }
     else if (overrideSources.length > 0) {
@@ -922,8 +1006,6 @@ function mergeLoadedConfig(base, override) {
     else if (baseSources.length > 0) {
         merged.sources = [...baseSources];
     }
-    // Clear deprecated stashes field on the merged result — sources is canonical.
-    delete merged.stashes;
     return merged;
 }
 function applyRuntimeEnvApiKeys(config) {

package/dist/{core → src/core}/errors.js

@@ -28,6 +28,7 @@ const CONFIG_HINTS = {
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {
+    INVALID_FLAG_VALUE: "Run `akm <command> --help` to see accepted values.",
     INVALID_SOURCE_VALUE: "Pick one of: stash, registry, both.",
     INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, text, yaml.",
     INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full, summary, agent.",
@@ -38,7 +39,10 @@ const USAGE_HINTS = {
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {
+    ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
     SOURCE_NOT_FOUND: "Run `akm list` to view your sources, then retry with one of those values.",
+    WORKFLOW_NOT_FOUND: "Run `akm workflow list --active` to see runs.",
+    FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
 /** Raised when configuration or environment is invalid or missing. */
 export class ConfigError extends Error {