akm-cli 0.9.0-rc.13 → 0.9.0-rc.15

package/dist/cli.js

@@ -60,6 +60,7 @@ import { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "ci
 import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
 import { retiredCommandHint } from "./cli/retired-commands.js";
 import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
+import { assertKnownFlags, closestMatch } from "./cli/unknown-flags.js";
 import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
 import { configCommand } from "./commands/config-cli.js";
@@ -236,7 +237,13 @@ const setupCommand = defineCommand({
                 printSetupTtyHint(result);
             }
             else {
-                // Interactive wizard
+                // Interactive wizard. Guard the TTY first: the wizard's prompts read
+                // from stdin, so a piped/redirected/CI invocation would render the
+                // first prompt and then block forever instead of failing — and `akm
+                // setup` is the first command users automate.
+                if (process.stdin.isTTY !== true) {
+                    throw new UsageError("Interactive setup requires a TTY. Pass --yes to accept defaults, or --config <json> / --from <file> to configure non-interactively.", "NON_INTERACTIVE_REQUIRES_YES");
+                }
                 const { runSetupWizard } = await import("./setup/setup.js");
                 await runSetupWizard({ dir: args.dir, noInit });
             }
@@ -818,40 +825,9 @@ function findUnknownCommandAttempt(rawArgs) {
         args = args.slice(idx + 1);
     }
 }
-/**
- * Standard edit-distance DP, single-row-at-a-time (sizes here are always
- * short command-name strings). Builds each row left-to-right, appending as
- * it goes, so every index read below is already-populated — the `?? 0`
- * fallbacks only satisfy `noUncheckedIndexedAccess`, they never fire.
- */
-function levenshteinDistance(a, b) {
-    let previousRow = Array.from({ length: b.length + 1 }, (_, j) => j);
-    for (let i = 1; i <= a.length; i++) {
-        const currentRow = [i];
-        for (let j = 1; j <= b.length; j++) {
-            const substitutionCost = a[i - 1] === b[j - 1] ? 0 : 1;
-            const deletion = (previousRow[j] ?? 0) + 1;
-            const insertion = (currentRow[j - 1] ?? 0) + 1;
-            const substitution = (previousRow[j - 1] ?? 0) + substitutionCost;
-            currentRow.push(Math.min(deletion, insertion, substitution));
-        }
-        previousRow = currentRow;
-    }
-    return previousRow[b.length] ?? 0;
-}
-/** Closest candidate within a length-scaled distance threshold, or undefined when nothing is close enough to be worth suggesting. */
+/** Closest command within a length-scaled distance threshold (shared DP in cli/unknown-flags.ts). */
 function closestCommandMatch(attempted, candidates) {
-    let best;
-    let bestDistance = Number.POSITIVE_INFINITY;
-    for (const candidate of candidates) {
-        const distance = levenshteinDistance(attempted, candidate);
-        if (distance < bestDistance) {
-            bestDistance = distance;
-            best = candidate;
-        }
-    }
-    const threshold = Math.max(2, Math.ceil(attempted.length / 2));
-    return best !== undefined && bestDistance <= threshold ? best : undefined;
+    return closestMatch(attempted, candidates, Math.max(2, Math.ceil(attempted.length / 2)));
 }
 const CLI_HELP_POINTER = "Run `akm --help` for usage.";
 /**
@@ -898,6 +874,10 @@ function toUsageErrorFromCliError(error, rawArgs) {
     const message = error.message.replace(/\x1b\[[0-9;]*m/g, "");
     return new UsageError(message, code, hint);
 }
+/** Normalize citty's private CLIError for the real entrypoint and in-process test harness. */
+export function normalizeCittyCliError(error, rawArgs) {
+    return isCittyCliError(error) ? toUsageErrorFromCliError(error, rawArgs) : error;
+}
 /**
  * The CLI's real startup sequence, extracted into a function so error paths
  * can `return` early — top-level `return` is a syntax error in an ES module,
@@ -1016,6 +996,10 @@ async function runCli() {
             console.log(pkgVersion);
             return;
         }
+        // citty's parseArgs (strict: false) silently ignores undeclared flags, so
+        // a typo used to run the command with defaults and exit 0. Checked here, after --help and
+        // --version, so those keep working on any command.
+        assertKnownFlags(main, rawArgs);
         await runCommand(main, { rawArgs });
     }
     catch (error) {
@@ -1027,7 +1011,7 @@ async function runCli() {
             // + raw `console.error(message)` — a one-line diagnosis plus a short
             // hint (with a did-you-mean suggestion when applicable), not a ~46KB
             // usage dump.
-            emitJsonError(toUsageErrorFromCliError(error, rawArgs));
+            emitJsonError(normalizeCittyCliError(error, rawArgs));
             return;
         }
         // Anything else escaping here is a genuinely unexpected failure outside

package/dist/commands/agent/agent-dispatch.js

@@ -16,6 +16,7 @@
 import fs from "node:fs";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 /**
@@ -60,10 +61,13 @@ async function resolveAssetBody(ref) {
 export async function akmAgentDispatch(options) {
     if (!options.agentConfig)
         throw new UsageError("agent requires a valid config with an agent engine.", "MISSING_REQUIRED_ARGUMENT");
-    const engineName = options.engine ?? options.agentConfig.defaults?.engine;
+    // Same implicit opencode-sdk fallback the workflow and task surfaces apply,
+    // so an engine-less install is usable everywhere or nowhere — not a mix.
+    const { config: agentConfig } = withEngineFallback(options.agentConfig);
+    const engineName = options.engine ?? agentConfig.defaults?.engine;
     if (!engineName)
-        throw new UsageError("agent requires --engine or defaults.engine.", "MISSING_REQUIRED_ARGUMENT");
-    const runner = resolveEngine(engineName, options.agentConfig);
+        throw new UsageError(`agent ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "MISSING_REQUIRED_ARGUMENT");
+    const runner = resolveEngine(engineName, agentConfig);
     if (runner.kind === "llm") {
         throw new UsageError(`Engine "${engineName}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
     }

package/dist/commands/agent/contribute-cli.js

@@ -25,6 +25,7 @@ import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { getHyphenatedBoolean } from "../../output/context.js";
 import { akmLint } from "../lint/index.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
@@ -132,8 +133,19 @@ export const lintCommand = defineCommand({
         ...GLOBAL_OUTPUT_ARGS,
         fix: {
             type: "boolean",
-            alias: "auto-fix",
-            description: "Apply auto-fixes in place (alias: --auto-fix)",
+            description: "Apply auto-fixes in place",
+            default: false,
+        },
+        // Declared as its own arg rather than `alias: "auto-fix"`: citty's alias
+        // handling (node:util parseArgs `short` options) only supports
+        // SINGLE-character aliases. A
+        // multi-char alias rendered in help as `-auto-fix` (one dash) and parsed
+        // as a pile of junk single-char flags, so BOTH advertised spellings —
+        // `-auto-fix` and `--auto-fix` — silently ran a plain lint while claiming
+        // to fix. Two real boolean args, OR'd at the call site, work and render.
+        "auto-fix": {
+            type: "boolean",
+            description: "Apply auto-fixes in place (same as --fix)",
             default: false,
         },
         dir: { type: "string", description: "Override bundle root directory (default: from config)" },
@@ -151,7 +163,7 @@ export const lintCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = akmLint({
-                fix: args.fix ?? false,
+                fix: args.fix === true || getHyphenatedBoolean(args, "auto-fix"),
                 dir: getStringArg(args, "dir"),
                 typeFilter: getStringArg(args, "type"),
             });

package/dist/commands/feedback-cli.js

@@ -9,7 +9,7 @@ import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatt
 import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
 import { isWithin, writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
-import { UsageError } from "../core/errors.js";
+import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { resolveMutationTarget } from "../core/mutation-target.js";
 import { getDbPath } from "../core/paths.js";
@@ -311,8 +311,11 @@ export const feedbackCommand = defineJsonCommand({
             const lookupRef = makeBundleRef(parsedRef.bundle, parsedRef.conceptId);
             const entryId = findEntryIdByRef(db, lookupRef, requestedSource?.path);
             if (entryId === undefined) {
-                throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                    "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
+                // NotFoundError (exit 1), not UsageError (exit 2): the flags parsed
+                // fine, the asset just isn't there. The documented exit-code table
+                // reserves 1 for "requested resource missing", and scripts branch on it.
+                throw new NotFoundError(`Ref "${ref}" is not in the index. ` +
+                    "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.", "ASSET_NOT_FOUND");
             }
             // Persist the feedback signal into usage_events. Both positive and
             // negative signals apply the EMA utility update immediately — no

package/dist/commands/health/checks.js

@@ -2,8 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../../integrations/agent/model-aliases.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
@@ -28,7 +28,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
         let packageAvailable = false;
         try {
-            const resolvePackage = deps.resolvePackage ?? ((name) => createRequire(import.meta.url).resolve(name));
+            const resolvePackage = deps.resolvePackage ?? ((name) => import.meta.resolve(name));
             resolvePackage("@opencode-ai/sdk");
             packageAvailable = true;
         }
@@ -170,7 +170,10 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     }
 }
 export function runDefaultEngineProbe(deps = {}) {
-    const config = deps.loadConfig?.() ?? loadConfig();
+    // Probe the effective view: an install with no `defaults.engine` but a usable
+    // opencode binary DOES have a working default, and reporting otherwise would
+    // contradict what `workflow run` / `task run` actually do.
+    const { config } = withEngineFallback(deps.loadConfig?.() ?? loadConfig(), deps.which);
     return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
 }
 export function runDefaultLlmEngineProbe(deps = {}) {

package/dist/commands/improve/collapse-detector.js

@@ -15,9 +15,8 @@
  * hardcoded 0 from the 0.9.0 confidence-gate deletion onward), so the alert
  * could never fire. See the design doc's status note for the removal
  * rationale. `improve_cycle_metrics.accepted_actions` stays in the schema and
- * is written as 0: its migration body is released, and 0.8 ships `state.db`,
- * so a deployed ledger may already have sealed that body's checksum. Editing
- * it would fail those installs closed.
+ * is written as 0 because deployed `state.db` files already contain it and
+ * removing it would be a destructive schema change.
  *
  * Hard invariants: deterministic only (FTS BM25 + hashing — never an LLM,
  * never an embedding model); bounded storage (< 2 KB per qualifying cycle,

package/dist/commands/improve/reflect.js

@@ -37,6 +37,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { lookup } from "../../indexer/indexer.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
 import { materializeLlmRunnerConnection, resolveImproveProcessRunner, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
@@ -1185,11 +1186,12 @@ function resolveReflectRunner(options) {
         runnerSpec = processRunner;
     }
     else {
-        const defaultEngine = config.defaults?.engine;
+        const { config: engineConfig } = withEngineFallback(config);
+        const defaultEngine = engineConfig.defaults?.engine;
         if (!defaultEngine) {
-            throw new ConfigError("reflect requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
+            throw new ConfigError(`reflect ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
         }
-        runnerSpec = resolveEngine(defaultEngine, config);
+        runnerSpec = resolveEngine(defaultEngine, engineConfig);
     }
     if (options.eventSource === "improve" && !runnerIsLlm(runnerSpec)) {
         throw new ConfigError(`Unattended improve requires an LLM engine for reflect; engine "${runnerSpec.engine ?? options.engine ?? "unknown"}" is tool-capable.`, "INVALID_CONFIG_FILE", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine to an LLM engine.");

package/dist/commands/lint/base-linter.js

@@ -35,15 +35,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
+import { spliceFrontmatterLine } from "../../core/asset/frontmatter.js";
 import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { localDateStamp } from "../../core/common.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
-function formatDate(d) {
-    const y = d.getFullYear();
-    const m = String(d.getMonth() + 1).padStart(2, "0");
-    const day = String(d.getDate()).padStart(2, "0");
-    return `${y}-${m}-${day}`;
-}
 function checkUnquotedColon(frontmatterText) {
     if (!frontmatterText)
         return null;
@@ -86,15 +82,7 @@ function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
 }
 function fixMissingUpdated(raw, mtime) {
-    const dateStr = formatDate(mtime);
-    const lines = raw.split(/\r?\n/);
-    if (lines[0]?.trim() !== "---")
-        return raw;
-    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
-    if (closeIdx === -1)
-        return raw;
-    lines.splice(closeIdx, 0, `updated: ${dateStr}`);
-    return lines.join("\n");
+    return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
 function checkStalePath(body) {
@@ -529,7 +517,7 @@ export function runBaseChecks(ctx) {
             issues.push({
                 file: ctx.relPath,
                 issue: "missing-updated",
-                detail: `stamped updated: ${formatDate(mtime)}`,
+                detail: `stamped updated: ${localDateStamp(mtime)}`,
                 fixed: true,
             });
         }

package/dist/commands/lint/index.js

@@ -6,7 +6,9 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { factDiagnostics, matchWorkflowPlaceholder, memoryOrphanStubApplies, nameOrTypeDiagnostics, ORPHANED_STUB_DETAIL, taskDiagnostics, workflowStructureDiagnostics, } from "../../core/adapter/adapters/akm-lint.js";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../../core/asset/frontmatter.js";
+import { conceptIdForStashFile, displayRefForConceptId } from "../../core/asset/resolve-ref.js";
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig, primaryBundlePath } from "../../core/config/config.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -321,23 +323,21 @@ export function akmLint(options = {}) {
     // keys that are known to enable process-execution hijacking. Warn-only —
     // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
+    const bundleIdByRoot = new Map(sources.map((source) => [path.resolve(source.path), source.registryId]));
     for (const root of envRoots) {
-        // The `env` assets live under `env/` (ref prefix `env:`); whole-file
-        // `secret` assets live under `secrets/` (canonical ref prefix `secret:`,
-        // singular). Map the scan directory to its canonical ref prefix so the
-        // finding's `Ref:` field matches what `akm show`/`akm secret` accept.
-        for (const { scanSubdir, refPrefix } of [
-            { scanSubdir: "env", refPrefix: "env" },
-            { scanSubdir: "secrets", refPrefix: "secret" },
-        ]) {
-            const dir = path.join(root, scanSubdir);
+        const bundleId = bundleIdByRoot.get(path.resolve(root));
+        // `env` assets live under `env/`, whole-file `secret` assets under
+        // `secrets/`. `displayRefForConceptId` owns the short-default /
+        // qualified-secondary `Ref:` spelling `akm show` emits — the old
+        // hand-built `env:<base>` colon grammar is rejected by the 0.9.0 ref
+        // parser, which dead-ended a user copying the ref off a security finding.
+        for (const assetType of ["env", "secret"]) {
+            const dir = path.join(root, stashDirFor(assetType));
             if (!fs.existsSync(dir))
                 continue;
             for (const envPath of collectEnvFiles(dir)) {
-                const baseName = path.basename(envPath, ".env");
-                // A dotfile literally named `.env` has an empty baseName — use the full
-                // basename so it doesn't collide with `default.env` → refPrefix:default.
-                const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+                const conceptId = conceptIdForStashFile(assetType, root, envPath);
+                const ref = displayRefForConceptId(conceptId, bundleId, cfg.defaultBundle);
                 const relPath = path.relative(root, envPath);
                 for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
                     flagged.push(issue);

package/dist/commands/log.js

@@ -16,6 +16,7 @@
  * other caller and was removed with it.
  */
 import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
+import { loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
 import { parseSinceToIso } from "../core/time.js";
@@ -49,7 +50,11 @@ function validateRef(ref) {
         throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
     }
     const parsed = parseBundleRef(trimmed);
-    return makeBundleRef(parsed.bundle, parsed.conceptId);
+    // Deliberately shallow qualification: a bare conceptId is assumed to mean
+    // the default bundle, without the full priority-walk `resolveRef` performs —
+    // event refs are recorded fully qualified, so the default is the only
+    // spelling a short --ref can usefully mean here.
+    return makeBundleRef(parsed.bundle ?? loadConfig().defaultBundle, parsed.conceptId);
 }
 function validateRunId(run) {
     if (run === undefined)

package/dist/commands/migration-tool.js

@@ -7,8 +7,8 @@ import { fileURLToPath } from "node:url";
 import { NotFoundError } from "../core/errors.js";
 function migrationEntryPoint() {
     const candidates = [
-        fileURLToPath(new URL("../../scripts/akm-migrate.ts", import.meta.url)),
-        fileURLToPath(new URL("../scripts/akm-migrate.js", import.meta.url)),
+        fileURLToPath(new URL(process.versions.bun ? "../scripts/akm-migrate.js" : "../scripts/akm-migrate-node.js", import.meta.url)),
+        ...(process.versions.bun ? [fileURLToPath(new URL("../../scripts/akm-migrate.ts", import.meta.url))] : []),
     ];
     return candidates.find((candidate) => fs.existsSync(candidate));
 }
@@ -27,14 +27,13 @@ export async function runMigrationTool(args) {
     // `scripts/akm-standalone.ts`, which embeds the migrator and dispatches to
     // it when `AKM_MIGRATE_ENTRY=1` — so re-exec ourselves with the marker.
     // (src must not import scripts/: the dist build's tsc has `rootDir: src`.)
-    const runtime = process.versions.bun ? process.execPath : "bun";
-    const result = spawnSync(runtime, entry ? [entry, ...args] : [...args], {
+    const result = spawnSync(process.execPath, entry ? [entry, ...args] : [...args], {
         encoding: "utf8",
         env: entry ? process.env : { ...process.env, AKM_MIGRATE_ENTRY: "1" },
         maxBuffer: 16 * 1024 * 1024,
     });
     if (result.error) {
-        throw new NotFoundError(`Cannot start the standalone akm-migrate tool: ${result.error.message}`, "FILE_NOT_FOUND", "Install Bun, then run akm-migrate directly.");
+        throw new NotFoundError(`Cannot start the standalone akm-migrate tool: ${result.error.message}`, "FILE_NOT_FOUND", "Reinstall akm-cli, or use a runtime-free standalone release binary.");
     }
     if (result.stdout)
         process.stdout.write(result.stdout);

package/dist/commands/observability-cli.js

@@ -72,7 +72,7 @@ export const logCommand = defineJsonCommand({
         ref: { type: "string", description: "Filter by asset ref ([bundle//]conceptId)" },
         run: {
             type: "string",
-            description: "Filter to a workflow run's events (metadata.runId), e.g. the id from `akm workflow start`",
+            description: "Filter to a workflow run's events (metadata.runId), e.g. the id from `akm workflow run`",
         },
         "exclude-tags": {
             type: "string",

package/dist/commands/proposal/propose.js

@@ -21,6 +21,7 @@ import { appendEvent } from "../../core/events.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { deriveEntryProvenance } from "../../indexer/installations.js";
+import { NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
 import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
@@ -83,10 +84,11 @@ export async function akmPropose(options) {
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
     const target = resolveProposalQueueTarget(stash, config);
     emitProposeInvoked(target.source, options);
-    const engineName = options.engine ?? config.defaults?.engine;
+    const { config: engineConfig } = withEngineFallback(config);
+    const engineName = options.engine ?? engineConfig.defaults?.engine;
     if (!engineName)
-        throw new ConfigError("propose requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
-    const runner = resolveEngine(engineName, config);
+        throw new ConfigError(`propose ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    const runner = resolveEngine(engineName, engineConfig);
     const profile = runner.kind === "llm" ? undefined : runner.profile;
     // 3. Build prompt.
     // Synthesize a temp draft path so opencode can write the asset content

package/dist/commands/proposal/repository.js

@@ -168,7 +168,7 @@ function persistProposalUpdate(db, proposal, stashDir) {
         .prepare("SELECT metadata_json FROM proposals WHERE id = ? AND stash_dir = ?")
         .get(proposal.id, stashDir);
     if (!row)
-        throw new NotFoundError(`Proposal "${proposal.id}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${proposal.id}" not found.`, "PROPOSAL_NOT_FOUND");
     const metadata = JSON.parse(row.metadata_json);
     for (const field of [
         "sourceRun",
@@ -572,7 +572,7 @@ export function getProposal(stashDir, id, ctx) {
 function requireProposal(db, stashDir, id) {
     const proposal = getStateProposal(db, id, stashDir);
     if (!proposal) {
-        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${id}" not found.`, "PROPOSAL_NOT_FOUND");
     }
     return proposal;
 }
@@ -588,7 +588,7 @@ function requireProposal(db, stashDir, id) {
 function requireProposalLenient(db, stashDir, id) {
     const proposal = getStateProposalLenient(db, id, stashDir);
     if (!proposal) {
-        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${id}" not found.`, "PROPOSAL_NOT_FOUND");
     }
     return proposal;
 }
@@ -623,7 +623,7 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
             const archived = byRecency(forConcept());
             if (archived)
                 return archived;
-            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "FILE_NOT_FOUND");
+            throw new NotFoundError(`No proposal found for ref "${idOrRef}".`, "PROPOSAL_NOT_FOUND");
         }
         // 3. UUID prefix (pending queue only).
         const prefixMatches = listStateProposalIdsByPrefix(db, stashDir, idOrRef);
@@ -632,7 +632,7 @@ export function resolveProposalId(stashDir, idOrRef, ctx) {
         if (prefixMatches.length > 1) {
             throw new UsageError(`Ambiguous prefix "${idOrRef}" — matches: ${prefixMatches.join(", ")}`, "INVALID_FLAG_VALUE");
         }
-        throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "FILE_NOT_FOUND");
+        throw new NotFoundError(`Proposal "${idOrRef}" not found.`, "PROPOSAL_NOT_FOUND");
     });
 }
 /**

package/dist/commands/read/knowledge.js

@@ -27,6 +27,7 @@ import { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath,
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations, slugForPath } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { storeSecretResolver } from "../../sources/snapshot-fetchers/secret-seam.js";
 import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests, } from "../../sources/snapshot-fetchers/website-ingest.js";
 import { writeSupersededEdge } from "../improve/memory/memory-belief.js";
 import { refToRelPath, resolveRefPathInStash } from "../lint/base-linter.js";
@@ -119,6 +120,7 @@ export async function readKnowledgeInput(source, options) {
         return readKnowledgeContent(source);
     const snapshot = await fetchWebsiteMarkdownSnapshot(source, {
         stashDir: options?.stashDir,
+        resolveSecret: storeSecretResolver.resolveSecret,
         allowPrivateHosts: options?.allowPrivateHosts ?? shouldAllowPrivateWebsiteUrlForTests(source),
     });
     return { content: snapshot.content, preferredName: snapshot.preferredName };

package/dist/commands/registry-cli.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { getEffectiveRegistries, loadUserConfig, mutateConfig } from "../core/config/config.js";
-import { UsageError } from "../core/errors.js";
+import { NotFoundError, UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
 export const registryCommand = defineGroupCommand({
     meta: { name: "registry", description: "Manage bundle registries" },
@@ -82,8 +82,10 @@ export const registryCommand = defineGroupCommand({
                 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;
+                    // Was a success envelope with `removed: false` and exit 0, so
+                    // `akm registry remove typo && ...` proceeded as if it had removed
+                    // something. A missing target is exit 1, like every other not-found.
+                    throw new NotFoundError(`No registry matching "${args.target}" is configured.`, "SOURCE_NOT_FOUND", "Run `akm registry list` to see configured registries.");
                 }
                 const { confirmDestructive } = await import("../cli/confirm.js");
                 const confirmed = await confirmDestructive(`Remove registry "${args.target}"? This cannot be undone.`, {

package/dist/commands/sources/add-cli.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import * as p from "../../cli/clack.js";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineJsonCommand, output } from "../../cli/shared.js";
 import { decideDangerousKeyInstall } from "../../core/activation-policy.js";
 import { UsageError } from "../../core/errors.js";
@@ -14,12 +15,11 @@ import { akmAdd } from "./source-add.js";
 import { addStash } from "./source-manage.js";
 // ── Shared website-options helper ──────────
 export function buildWebsiteOptions(args) {
-    const websiteOptions = {};
-    if (typeof args["max-pages"] === "string" && args["max-pages"].length > 0)
-        websiteOptions.maxPages = args["max-pages"];
-    if (typeof args["max-depth"] === "string" && args["max-depth"].length > 0)
-        websiteOptions.maxDepth = args["max-depth"];
-    return websiteOptions;
+    // getStringArg maps absent/blank to undefined; parsePositiveIntFlag maps
+    // undefined to undefined — so an unsupplied flag simply omits the key.
+    const maxPages = parsePositiveIntFlag(getStringArg(args, "max-pages"), "--max-pages");
+    const maxDepth = parsePositiveIntFlag(getStringArg(args, "max-depth"), "--max-depth");
+    return { ...(maxPages !== undefined ? { maxPages } : {}), ...(maxDepth !== undefined ? { maxDepth } : {}) };
 }
 // ── HTTP safety check ─────────────────────────────────────────────────────────
 export function shouldWarnOnPlainHttp(ref) {

package/dist/commands/sources/init.js

@@ -87,7 +87,7 @@ async function akmInitReal(options) {
     for (const sub of stashDirNames()) {
         const subDir = path.join(stashDir, sub);
         if (!fs.existsSync(subDir)) {
-            fs.mkdirSync(subDir, { recursive: true });
+            fs.mkdirSync(subDir, { recursive: true, mode: sub === "env" || sub === "secrets" ? 0o700 : undefined });
         }
     }
     // Ensure the default stash is a local git repo (no remote required)