akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/cli.js

@@ -1,40 +1,83 @@
 #!/usr/bin/env bun
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+// Runtime guard: akm-cli 0.8 is Bun-only. The `preinstall` hook in
+// package.json blocks `npm install`, but it does not protect against a
+// stale node-resolved shebang, a wrong PATH entry, or someone running
+// `node dist/cli.js` directly from a clone. In any of those cases the
+// next line — `import { spawnSync } from "node:child_process";` — would
+// itself succeed under node, only to die a few imports later with a
+// confusing `ERR_MODULE_NOT_FOUND` for our extensionless internal paths.
+// Catch the wrong-runtime case here with a friendly message instead of
+// a stack trace. Cross-runtime support is planned for 0.9 (issue #465).
+if (typeof globalThis.Bun === "undefined") {
+    console.error("\n  ERROR: akm-cli 0.8 requires the Bun runtime (https://bun.sh) or the prebuilt binary.\n" +
+        "  Running under Node.js is not supported in this release.\n" +
+        "  Install options:\n" +
+        "    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\n" +
+        "    2. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n" +
+        "  Cross-runtime support is planned for 0.9.0.\n");
+    process.exit(1);
+}
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
+import { getStringArg, hasSubcommand, parseAutoAcceptFlag, parseNonNegativeIntFlag, parsePositiveIntFlag, } from "./cli/parse-args";
+import { akmAgentDispatch } from "./commands/agent-dispatch";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./commands/config-cli";
 import { akmCurate } from "./commands/curate";
-import { akmDistill } from "./commands/distill";
+import { akmDbBackups } from "./commands/db-cli";
 import { akmEventsList, akmEventsTail } from "./commands/events";
+import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./commands/graph";
+import { akmHealth } from "./commands/health";
 import { akmHistory } from "./commands/history";
+import { akmImprove } from "./commands/improve";
+import { buildImproveRunId, relativeImproveResultPath, writeImproveResultFile } from "./commands/improve-result-file";
 import { assembleInfo } from "./commands/info";
 import { akmInit } from "./commands/init";
 import { akmListSources, akmRemove, akmUpdate } from "./commands/installed-stashes";
+import { inferAssetName, readKnowledgeInput, writeMarkdownAsset } from "./commands/knowledge";
+import { akmLint } from "./commands/lint";
 import { renderMigrationHelp } from "./commands/migration-help";
-import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalShow, } from "./commands/proposal";
+/**
+ * Resolve the event source from the environment. When `AKM_EVENT_SOURCE` is
+ * set (e.g. by `akm improve` for agent subprocesses), events are tagged so
+ * they can be filtered out of user-facing history.
+ */
+function resolveEventSource() {
+    const raw = process.env.AKM_EVENT_SOURCE;
+    if (raw === "improve")
+        return "improve";
+    if (raw === "user")
+        return "user";
+    return undefined;
+}
+import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalRevert, akmProposalShow, } from "./commands/proposal";
 import { akmPropose } from "./commands/propose";
-import { akmReflect } from "./commands/reflect";
 import { searchRegistry } from "./commands/registry-search";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich, } from "./commands/remember";
-import { akmSearch, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "./commands/remember";
+import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
 import { checkForUpdate, performUpgrade } from "./commands/self-update";
-import { akmShowUnified } from "./commands/show";
+import { akmShowUnified, normalizeShowArgv } from "./commands/show";
 import { akmAdd } from "./commands/source-add";
 import { akmClone } from "./commands/source-clone";
 import { addStash } from "./commands/source-manage";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./commands/tasks";
 import { parseAssetRef } from "./core/asset-ref";
+import { assembleAsset } from "./core/asset-serialize";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset-spec";
-import { isHttpUrl, isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
-import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./core/config";
+import { isHttpUrl, isWithin, resolveStashDir, writeFileAtomic } from "./core/common";
+import { DEFAULT_CONFIG, FEEDBACK_FAILURE_MODES, loadConfig, loadUserConfig, resolveConfiguredSources, saveConfig, } from "./core/config";
 import { ConfigError, NotFoundError, UsageError } from "./core/errors";
 import { appendEvent } from "./core/events";
-import { getCacheDir, getDbPath, getDefaultStashDir } from "./core/paths";
-import { setQuiet, setVerbose, warn } from "./core/warn";
-import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
-import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
+import { parseFrontmatter, parseFrontmatterBlock } from "./core/frontmatter";
+import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "./core/paths";
+import { clearLogFile, info, isQuiet, setLogFile, setQuiet, setVerbose, warn } from "./core/warn";
+import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
 import { ensureIndex } from "./indexer/ensure-index";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
@@ -47,16 +90,22 @@ 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 { fetchWebsiteMarkdownSnapshot } from "./sources/website-ingest";
 import { pkgVersion } from "./version";
 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";
 const SKILLS_SH_PROVIDER = "skills-sh";
 import { stringify as yamlStringify } from "yaml";
+function applyEarlyStderrFlags(argv) {
+    if (argv.includes("--quiet") || argv.includes("-q")) {
+        setQuiet(true);
+    }
+    if (argv.includes("--verbose")) {
+        setVerbose(true);
+    }
+}
 /**
  * Collect all occurrences of a repeatable flag from process.argv.
  * Citty's StringArgDef only exposes the last value when a flag is repeated,
@@ -80,6 +129,43 @@ function parseAllFlagValues(flag) {
     }
     return values;
 }
+function resolveHelpMigrateVersionArg(version) {
+    if (version === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        version === parsedFormat &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        version === parsedDetail &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return version;
+}
+function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const helpIndex = argv.indexOf("help");
+    const tokens = helpIndex >= 0 ? argv.slice(helpIndex + 1) : argv;
+    const migrateIndex = tokens.indexOf("migrate");
+    const relevant = migrateIndex >= 0 ? tokens.slice(migrateIndex + 1) : tokens;
+    let flagIndex = -1;
+    for (let i = 0; i < relevant.length; i += 1) {
+        const token = relevant[i];
+        if (token === flagName || token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (relevant.slice(0, flagIndex).includes(version))
+        return false;
+    return relevant[flagIndex] === flagName ? relevant[flagIndex + 1] === version : true;
+}
 function output(command, result) {
     const mode = getOutputMode();
     const shaped = shapeForCommand(command, result, mode.detail, mode.forAgent);
@@ -101,6 +187,30 @@ function output(command, result) {
         }
     }
 }
+/**
+ * Stderr-only human-friendly hint after a non-interactive `setup` invocation.
+ * Default --format is `json`, so a CI or piped consumer sees only the JSON on
+ * stdout. But an interactive user running `akm setup --yes` would otherwise
+ * see only the JSON blob with no obvious next step. When stderr is a TTY and
+ * the JSON went to stdout, print a two-line summary to stderr telling the
+ * user (a) where the stash landed and (b) what to run next.
+ *
+ * Silent when: stderr is not a TTY (CI, pipes), --format=text/yaml (the user
+ * already gets readable output), --quiet, or the result is missing fields.
+ */
+function printSetupTtyHint(result) {
+    if (!process.stderr.isTTY)
+        return;
+    const mode = getOutputMode();
+    if (mode.format !== "json" && mode.format !== "jsonl")
+        return;
+    if (isQuiet())
+        return;
+    if (!result?.stashDir)
+        return;
+    console.error(`\n✓ Stash created at ${result.stashDir}\n` +
+        `  Next: \`akm add github:itlackey/akm-stash\` then \`akm index\` to populate the stash.`);
+}
 /**
  * Module Naming:
  * - sources/*           : Asset operations (search, show, add, clone)
@@ -111,12 +221,82 @@ function output(command, result) {
 const setupCommand = defineCommand({
     meta: {
         name: "setup",
-        description: "Interactive configuration wizard: detects services and walks you through embeddings, LLM, registries, sources, and agent profiles. Writes config once at the end.",
+        description: "Interactive configuration wizard. Configures embeddings/LLM connections (for indexing/enrichment), agent profiles (CLI agent, embedded SDK, or none), sources, and registries. Shows which features are enabled at the end. Use --config <json> or --yes for non-interactive/scripting mode.",
     },
-    async run() {
+    args: {
+        config: {
+            type: "string",
+            description: 'Config JSON to apply non-interactively, e.g. \'{"llm":{"endpoint":"...","model":"..."}}\'',
+        },
+        from: {
+            type: "string",
+            description: "Path to a config file (JSON or YAML) to bootstrap from. Skips prompts for keys present in the file.",
+        },
+        yes: {
+            type: "boolean",
+            default: false,
+            description: "Accept all defaults, skip all prompts. Idempotent — safe to run in CI.",
+        },
+        dir: {
+            type: "string",
+            description: "Stash directory path (overrides stashDir in config or --config JSON)",
+        },
+        probe: {
+            type: "boolean",
+            default: false,
+            description: "Probe LLM/embedding endpoints after writing config to verify connectivity",
+        },
+    },
+    async run({ args }) {
         await runWithJsonErrors(async () => {
-            const { runSetupWizard } = await import("./setup/setup");
-            await runSetupWizard();
+            const noInit = getHyphenatedBoolean(args, "no-init");
+            if (args.from && args.config) {
+                throw new UsageError("Pass either --from <file> or --config <json>, not both.", "INVALID_FLAG_VALUE");
+            }
+            if (args.from) {
+                // File-based bootstrap. `loadSetupConfigFromFile` expands a leading
+                // `~`, resolves relative paths against cwd, picks the YAML or JSON
+                // parser based on the file extension, and surfaces any
+                // read/parse/shape errors as ConfigError("INVALID_CONFIG_FILE").
+                const { loadSetupConfigFromFile, runSetupFromConfig } = await import("./setup/setup");
+                const loaded = await loadSetupConfigFromFile(args.from);
+                const result = await runSetupFromConfig({
+                    configJson: loaded.configJson,
+                    dir: args.dir,
+                    noInit,
+                    probe: args.probe,
+                });
+                output("setup", result);
+                printSetupTtyHint(result);
+            }
+            else if (args.config) {
+                // Non-interactive config mode
+                const { runSetupFromConfig } = await import("./setup/setup");
+                const result = await runSetupFromConfig({
+                    configJson: args.config,
+                    dir: args.dir,
+                    noInit,
+                    probe: args.probe,
+                });
+                output("setup", result);
+                printSetupTtyHint(result);
+            }
+            else if (args.yes) {
+                // Defaults mode — no prompts
+                const { runSetupWithDefaults } = await import("./setup/setup");
+                const result = await runSetupWithDefaults({
+                    dir: args.dir,
+                    noInit,
+                    probe: args.probe,
+                });
+                output("setup", result);
+                printSetupTtyHint(result);
+            }
+            else {
+                // Interactive wizard
+                const { runSetupWizard } = await import("./setup/setup");
+                await runSetupWizard({ dir: args.dir, noInit });
+            }
         });
     },
 });
@@ -142,16 +322,33 @@ const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
         full: { type: "boolean", description: "Force full reindex", default: false },
-        enrich: { type: "boolean", description: "Enable LLM inference and enrichment passes", default: false },
         verbose: { type: "boolean", description: "Print phase-by-phase indexing progress to stderr", default: false },
+        clean: {
+            type: "boolean",
+            description: "After indexing, remove any entries whose source file no longer exists on disk.",
+            default: false,
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "When combined with --clean, report stale entries without deleting them.",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (getHyphenatedBoolean(args, "enrich") || parseFlagValue(process.argv, "--enrich") !== undefined) {
+                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+            }
+            if (getHyphenatedBoolean(args, "re-enrich") || parseFlagValue(process.argv, "--re-enrich") !== undefined) {
+                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+            }
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
             process.once("SIGINT", abort);
             process.once("SIGTERM", abort);
+            const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(indexLogFile);
             const spin = !args.verbose && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
@@ -160,12 +357,13 @@ const indexCommand = defineCommand({
             try {
                 const result = await akmIndex({
                     full: args.full,
-                    enrich: args.enrich,
-                    onProgress: ({ message, processed, total }) => {
+                    clean: args.clean,
+                    dryRun: args["dry-run"],
+                    onProgress: ({ phase, message, processed, total }) => {
                         latestMessage = message;
                         const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
                         if (args.verbose) {
-                            console.error(`[index] ${progressPrefix}${message}`);
+                            info(`[index:${phase}] ${progressPrefix}${message}`);
                         }
                         else if (spin) {
                             spin.stop(`${progressPrefix}${message}`);
@@ -186,6 +384,7 @@ const indexCommand = defineCommand({
                 throw error;
             }
             finally {
+                clearLogFile();
                 process.off("SIGINT", abort);
                 process.off("SIGTERM", abort);
             }
@@ -201,6 +400,193 @@ const infoCommand = defineCommand({
         });
     },
 });
+const healthCommand = defineCommand({
+    meta: { name: "health", description: "Check akm runtime health, artifacts, and improve metrics" },
+    args: {
+        since: {
+            type: "string",
+            description: "Rolling window start (ISO timestamp, date, epoch ms, or shorthand like 24h / 7d)",
+        },
+    },
+    async run({ args }) {
+        // Capture the health result so we can propagate its overall status into the
+        // process exit code AFTER the JSON envelope is flushed to stdout. The
+        // CHANGELOG advertises `akm health` as a CI/runtime monitoring command —
+        // callers rely on `akm health && deploy` style chaining, which requires
+        // non-zero exit on failure (and parseable JSON on stdout for diagnostics).
+        let resultStatus;
+        await runWithJsonErrors(() => {
+            const result = akmHealth({ since: args.since });
+            resultStatus = result.status;
+            output("health", result);
+        });
+        if (resultStatus === "fail") {
+            process.exit(EXIT_GENERAL);
+        }
+        if (resultStatus === "warn") {
+            process.exit(EXIT_HEALTH_WARN);
+        }
+    },
+});
+const graphCommand = defineCommand({
+    meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
+    subCommands: {
+        summary: defineCommand({
+            meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-summary", akmGraphSummary({ source: args.source }));
+                });
+            },
+        }),
+        entities: defineCommand({
+            meta: { name: "entities", description: "List entities with per-file occurrence counts" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum entities to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-entities", akmGraphEntities({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
+                });
+            },
+        }),
+        relations: defineCommand({
+            meta: { name: "relations", description: "List relations with occurrence counts" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum relations to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-relations", akmGraphRelations({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
+                });
+            },
+        }),
+        related: defineCommand({
+            meta: { name: "related", description: "Show graph-related neighboring assets for a ref" },
+            args: {
+                ref: { type: "positional", description: "Asset ref", required: true },
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum related assets to return" },
+            },
+            async run({ args }) {
+                return runWithJsonErrors(async () => {
+                    output("graph-related", await akmGraphRelated({
+                        ref: args.ref ?? "",
+                        source: args.source,
+                        limit: parsePositiveIntFlag(args.limit ?? undefined),
+                    }));
+                });
+            },
+        }),
+        entity: defineCommand({
+            meta: { name: "entity", description: "List assets that contain the given entity" },
+            args: {
+                name: { type: "positional", description: "Entity name", required: true },
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum matches to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-entity", akmGraphEntity({
+                        name: args.name ?? "",
+                        source: args.source,
+                        limit: parsePositiveIntFlag(args.limit ?? undefined),
+                    }));
+                });
+            },
+        }),
+        orphans: defineCommand({
+            meta: { name: "orphans", description: "List assets with no extracted graph entities" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum orphans to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-orphans", akmGraphOrphans({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
+                });
+            },
+        }),
+        export: defineCommand({
+            meta: { name: "export", description: "Export graph artifact as JSON or JSONL" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                out: { type: "string", description: "Output path" },
+                format: { type: "string", description: "Export format (json|jsonl)", default: "json" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-export", akmGraphExport({
+                        source: args.source,
+                        out: args.out ?? "",
+                        format: args.format,
+                    }));
+                });
+            },
+        }),
+        update: defineCommand({
+            meta: { name: "update", description: "Re-run graph extraction, optionally scoped to specific asset refs" },
+            args: {
+                refs: {
+                    type: "positional",
+                    description: "Zero or more asset refs to scope extraction (omit for a full re-extract)",
+                    required: false,
+                    default: "",
+                },
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+            },
+            async run({ args }) {
+                return runWithJsonErrors(async () => {
+                    // `refs` is a single positional; collect remaining argv tokens as well.
+                    const rawRefs = [args.refs, ...(Array.isArray(args._) ? args._ : [])].filter((r) => typeof r === "string" && r.trim().length > 0);
+                    output("graph-update", await akmGraphUpdate({ refs: rawRefs.length > 0 ? rawRefs : undefined, source: args.source }));
+                });
+            },
+        }),
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            if (hasSubcommand(args, GRAPH_SUBCOMMAND_SET))
+                return;
+            output("graph-summary", akmGraphSummary());
+        });
+    },
+});
+// MVP DB administration. Currently only `akm db backups`; restore is manual —
+// stop akm and run `scripts/migrations/restore-data-dir.sh <backup>`.
+const DB_SUBCOMMAND_SET = new Set(["backups"]);
+const dbCommand = defineCommand({
+    meta: {
+        name: "db",
+        description: "Inspect the AKM SQLite data directory. Currently exposes `backups`; to restore from a snapshot, stop akm and run scripts/migrations/restore-data-dir.sh against the chosen backup.",
+    },
+    subCommands: {
+        backups: defineCommand({
+            meta: {
+                name: "backups",
+                description: "List pre-upgrade snapshots of the data directory (newest first). Backups are created automatically before destructive DB version upgrades unless AKM_DB_BACKUP=0.",
+            },
+            run() {
+                return runWithJsonErrors(() => {
+                    output("db-backups", akmDbBackups());
+                });
+            },
+        }),
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            if (hasSubcommand(args, DB_SUBCOMMAND_SET))
+                return;
+            // Default action: list backups.
+            output("db-backups", akmDbBackups());
+        });
+    },
+});
 const searchCommand = defineCommand({
     meta: { name: "search", description: "Search the stash" },
     args: {
@@ -220,29 +606,49 @@ const searchCommand = defineCommand({
             description: 'Include entries with quality:"proposed" in the result set. Excluded by default (v1 spec §4.2).',
             default: false,
         },
+        belief: {
+            type: "string",
+            description: "Memory belief filter: all|current|historical. current keeps active memory beliefs; historical keeps contradicted/superseded/archived memory beliefs.",
+            default: "all",
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
         detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
+        "no-project-context": {
+            type: "boolean",
+            description: "Disable the automatic project-context ranking boost (also disabled by AKM_DISABLE_PROJECT_CONTEXT=1).",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            // An empty query enumerates all indexed assets (list mode).
-            // The guard that rejected empty queries was removed; akmSearch handles
-            // empty strings end-to-end via getAllEntries (DB path) and the
-            // substring-search fallback's query-less branch.
             const query = (args.query ?? "").trim();
-            const type = args.type;
-            const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-            if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
+            if (!query) {
+                throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Pass a query like `akm search "docker"` or `akm search "code review" --type skill`.');
             }
-            const limit = limitRaw;
+            const type = args.type;
+            const limit = parsePositiveIntFlag(args.limit ?? undefined);
             const source = parseSearchSource(args.source);
             // Repeatable; citty exposes only the last `--filter` value, so read all
             // occurrences directly from argv (same pattern as `--tag`).
             const filterTokens = parseAllFlagValues("--filter");
             const filters = parseScopeFilterFlags(filterTokens, "--filter");
             const includeProposed = args["include-proposed"] === true;
-            const result = await akmSearch({ query, type, limit, source, filters, includeProposed });
+            const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
+            const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
+            // --no-project-context sets env so searchDatabase picks it up without
+            // threading the flag through the entire call stack.
+            if (noProjectContext)
+                process.env.AKM_DISABLE_PROJECT_CONTEXT = "1";
+            const result = await akmSearch({
+                query,
+                type,
+                limit,
+                source,
+                filters,
+                includeProposed,
+                belief,
+                eventSource: resolveEventSource(),
+            });
             output("search", result);
         });
     },
@@ -267,11 +673,8 @@ const curateCommand = defineCommand({
                 throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
             }
             const type = args.type;
-            const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-            if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
-            }
-            const limit = limitRaw && limitRaw > 0 ? limitRaw : 4;
+            const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
+            const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
             const source = parseSearchSource(args.source ?? "stash");
             const curated = await akmCurate({ query: args.query, type, limit, source });
             output("curate", curated);
@@ -297,11 +700,6 @@ const addCommand = defineCommand({
             description: "Mark a git stash as writable so changes can be pushed back",
             default: false,
         },
-        trust: {
-            type: "boolean",
-            description: "Bypass install-audit blocking for this add invocation only",
-            default: false,
-        },
         type: {
             type: "string",
             description: "Override asset type for all files in this stash (currently supports: wiki)",
@@ -310,7 +708,7 @@ const addCommand = defineCommand({
         "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
         "allow-insecure": {
             type: "boolean",
-            description: "Allow a plain HTTP source URL (otherwise rejected for non-localhost hosts)",
+            description: "Allow a plain HTTP source URL and skip confirmation for dangerous vault keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the stash.",
             default: false,
         },
     },
@@ -318,6 +716,7 @@ const addCommand = defineCommand({
         await runWithJsonErrors(async () => {
             const ref = args.ref.trim();
             const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
+            const allowDangerousKeys = allowInsecure;
             // URL with --provider → stash source (remote or git provider)
             if (args.provider) {
                 if (shouldWarnOnPlainHttp(ref)) {
@@ -370,7 +769,6 @@ const addCommand = defineCommand({
                     ref,
                     name: args.name,
                     options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                    trustThisInstall: args.trust,
                     writable: args.writable,
                 });
                 appendEvent({
@@ -385,7 +783,6 @@ const addCommand = defineCommand({
                 name: args.name,
                 overrideType: args.type,
                 options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                trustThisInstall: args.trust,
                 writable: args.writable,
             });
             appendEvent({
@@ -397,6 +794,120 @@ const addCommand = defineCommand({
                     writable: args.writable === true,
                 },
             });
+            // ── Post-install vault key audit ────────────────────────────────────────
+            // Resolve the stash root from the install result and scan any vault files
+            // for dangerous env var keys.  When findings are present the install is
+            // gated: TTY → interactive confirmation prompt; non-TTY without
+            // --allow-insecure → hard failure (exit 1).  Pass
+            // --allow-insecure to skip the prompt non-interactively.
+            try {
+                const installedStashRoot = result.installed?.stashRoot ??
+                    (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+                if (installedStashRoot) {
+                    const { checkVaultForDangerousKeys } = await import("./commands/lint/vault-key-rules.js");
+                    const vaultsDir = path.join(installedStashRoot, "vaults");
+                    if (fs.existsSync(vaultsDir)) {
+                        const envFiles = fs.readdirSync(vaultsDir).filter((f) => f.endsWith(".env"));
+                        // Collect all dangerous-key findings across every vault file.
+                        const allFindings = [];
+                        for (const envFile of envFiles) {
+                            const vaultPath = path.join(vaultsDir, envFile);
+                            const baseName = path.basename(envFile, ".env");
+                            const vaultRef = baseName === "" ? "vault:default" : `vault:${baseName}`;
+                            const relPath = path.join("vaults", envFile);
+                            const findings = checkVaultForDangerousKeys(vaultPath, relPath, vaultRef);
+                            for (const finding of findings) {
+                                // Extract the key name from the detail string for the summary line.
+                                const keyMatch = finding.detail.match(/Vault key `([^`]+)`/);
+                                const keyName = keyMatch ? keyMatch[1] : finding.file;
+                                allFindings.push({ vaultRef, keyName, relPath });
+                            }
+                        }
+                        if (allFindings.length > 0) {
+                            if (allowDangerousKeys) {
+                                // Operator has explicitly accepted the risk — warn and continue.
+                                for (const f of allFindings) {
+                                    warn(`[dangerous-vault-key] ${f.relPath}: key \`${f.keyName}\` in ${f.vaultRef} can hijack process execution via \`akm vault run\`. Proceeding because --allow-insecure was set.`);
+                                }
+                            }
+                            else if (process.stdin.isTTY) {
+                                // Interactive path: show findings and ask the user to confirm.
+                                // Guard on stdin (not stdout) because p.confirm() reads from stdin;
+                                // stdout may be a TTY while stdin is piped, which would cause a hang.
+                                const stashLabel = ref;
+                                const groupedByVault = new Map();
+                                for (const f of allFindings) {
+                                    const existing = groupedByVault.get(f.vaultRef) ?? [];
+                                    existing.push(f.keyName);
+                                    groupedByVault.set(f.vaultRef, existing);
+                                }
+                                for (const [vaultRef, keys] of groupedByVault) {
+                                    warn(`[warn] Vault "${vaultRef}" in stash "${stashLabel}" contains potentially dangerous keys:`);
+                                    for (const key of keys) {
+                                        warn(`  - ${key}: can hijack process execution via \`akm vault run\``);
+                                    }
+                                }
+                                const confirmed = await p.confirm({
+                                    message: "Install anyway?",
+                                    initialValue: false,
+                                });
+                                if (p.isCancel(confirmed) || confirmed !== true) {
+                                    // Roll back the install before aborting.
+                                    // Use the canonical installed id (most reliably resolved by akmRemove) rather
+                                    // than the raw user-supplied ref which may not match after URL normalisation.
+                                    const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+                                    let rollbackWarning;
+                                    try {
+                                        await akmRemove({ target: rollbackTarget });
+                                    }
+                                    catch (_rollbackErr) {
+                                        rollbackWarning =
+                                            `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                                `Remove it manually with: akm remove ${rollbackTarget}`;
+                                    }
+                                    console.error(JSON.stringify({
+                                        ok: false,
+                                        error: "Install aborted: stash contains dangerous vault keys. Remove the keys or re-run with --allow-insecure to bypass.",
+                                        code: "DANGEROUS_VAULT_KEY",
+                                        ...(rollbackWarning ? { rollbackWarning } : {}),
+                                    }, null, 2));
+                                    process.exit(1);
+                                }
+                            }
+                            else {
+                                // Non-interactive path without bypass flag: fail hard.
+                                // Roll back the install before exiting.
+                                // Use the canonical installed id (most reliably resolved by akmRemove) rather
+                                // than the raw user-supplied ref which may not match after URL normalisation.
+                                const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+                                let rollbackWarning;
+                                try {
+                                    await akmRemove({ target: rollbackTarget });
+                                }
+                                catch (_rollbackErr) {
+                                    rollbackWarning =
+                                        `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                            `Remove it manually with: akm remove ${rollbackTarget}`;
+                                }
+                                const keyList = allFindings.map((f) => `  - ${f.keyName} (${f.vaultRef})`).join("\n");
+                                console.error(JSON.stringify({
+                                    ok: false,
+                                    error: `Install blocked: stash "${ref}" contains dangerous vault keys that can hijack process execution via \`akm vault run\`:\n${keyList}\nRe-run with --allow-insecure to bypass this check after reviewing the vault.`,
+                                    code: "DANGEROUS_VAULT_KEY",
+                                    ...(rollbackWarning ? { rollbackWarning } : {}),
+                                }, null, 2));
+                                process.exit(1);
+                            }
+                        }
+                    }
+                }
+            }
+            catch (auditErr) {
+                // Only swallow errors that are NOT our intentional process.exit calls.
+                if (auditErr instanceof Error && auditErr.message === "process.exit called")
+                    throw auditErr;
+                // Vault key audit is best-effort; never fail the install on unexpected audit errors.
+            }
             output("add", result);
         });
     },
@@ -454,9 +965,18 @@ const removeCommand = defineCommand({
     meta: { name: "remove", description: "Remove a source by id, ref, path, URL, or name" },
     args: {
         target: { type: "positional", description: "Source to remove (id, ref, path, URL, or name)", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove source "${args.target}"? This cannot be undone.`, {
+                yes: args.yes === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
             const result = await akmRemove({ target: args.target });
             appendEvent({
                 eventType: "remove",
@@ -545,15 +1065,17 @@ const showCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            try {
-                parseAssetRef(args.ref);
-            }
-            catch (error) {
-                if (error instanceof UsageError && error.code === "MISSING_REQUIRED_ARGUMENT") {
-                    throw new UsageError(error.message, "INVALID_FLAG_VALUE", error.hint());
+            const subcommand = Array.isArray(args._) ? args._[0] : undefined;
+            if (subcommand === "proposal") {
+                const proposalId = Array.isArray(args._) ? args._[1] : undefined;
+                if (typeof proposalId !== "string" || !proposalId.trim()) {
+                    throw new UsageError("Usage: akm show proposal <id>", "MISSING_REQUIRED_ARGUMENT");
                 }
-                throw error;
+                const result = akmProposalShow({ id: proposalId.trim() });
+                output("proposal-show", result);
+                return;
             }
+            parseAssetRef(args.ref);
             // The knowledge-view positional syntax (`akm show knowledge:foo section "Auth"`)
             // is rewritten to `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
             // by `normalizeShowArgv` before citty parses argv. We read those values
@@ -592,7 +1114,13 @@ const showCommand = defineCommand({
             // every occurrence directly from argv (same pattern as `--filter`).
             const scopeTokens = parseAllFlagValues("--scope");
             const scope = parseScopeFilterFlags(scopeTokens, "--scope");
-            const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail, scope });
+            const result = await akmShowUnified({
+                ref: args.ref,
+                view,
+                detail: showDetail,
+                scope,
+                eventSource: resolveEventSource(),
+            });
             output("show", result);
         });
     },
@@ -642,6 +1170,14 @@ const configCommand = defineCommand({
                 });
             },
         }),
+        show: defineCommand({
+            meta: { name: "show", description: "Alias for `akm config list` — list current configuration" },
+            run() {
+                return runWithJsonErrors(() => {
+                    output("config", listConfig(loadConfig()));
+                });
+            },
+        }),
         get: defineCommand({
             meta: { name: "get", description: "Get a configuration value by key" },
             args: {
@@ -658,12 +1194,36 @@ const configCommand = defineCommand({
             args: {
                 key: { type: "positional", required: true, description: "Config key (for example: embedding, llm)" },
                 value: { type: "positional", required: true, description: "Config value" },
+                // #463: stable machine-friendly entry point for plugins / hooks.
+                // `--silent` suppresses the config dump on stdout so hook-driven
+                // writes don't pollute their host's output stream.
+                silent: {
+                    type: "boolean",
+                    description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
+                    default: false,
+                },
+                // #463: explicit layer flag for forward-compat. User layer is the only
+                // settable layer today; the flag exists so plugin authors can encode
+                // intent and the surface stays stable if project-layer writes return.
+                layer: {
+                    type: "string",
+                    description: "Config layer to write to. Currently only `user` is supported.",
+                    default: "user",
+                },
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const updated = setConfigValue(loadUserConfig(), args.key, args.value);
+                    if (args.layer && args.layer !== "user") {
+                        throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
+                    }
+                    // Use loadConfig (not loadUserConfig) so the project-config
+                    // deprecation warning fires consistently with `akm config get`
+                    // (#457). Effective merged shape is identical post-0.8.0.
+                    const updated = setConfigValue(loadConfig(), args.key, args.value);
                     saveConfig(updated);
-                    output("config", listConfig(updated));
+                    if (!args.silent) {
+                        output("config", listConfig(updated));
+                    }
                 });
             },
         }),
@@ -671,19 +1231,66 @@ const configCommand = defineCommand({
             meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/llm section" },
             args: {
                 key: { type: "positional", required: true, description: "Config key to unset" },
+                silent: {
+                    type: "boolean",
+                    description: "Suppress the post-write config dump on stdout.",
+                    default: false,
+                },
+                layer: {
+                    type: "string",
+                    description: "Config layer to write to. Currently only `user` is supported.",
+                    default: "user",
+                },
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    const updated = unsetConfigValue(loadUserConfig(), args.key);
+                    if (args.layer && args.layer !== "user") {
+                        throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.8.0.`, "INVALID_FLAG_VALUE");
+                    }
+                    const updated = unsetConfigValue(loadConfig(), args.key);
                     saveConfig(updated);
-                    output("config", listConfig(updated));
+                    if (!args.silent) {
+                        output("config", listConfig(updated));
+                    }
+                });
+            },
+        }),
+        validate: defineCommand({
+            meta: {
+                name: "validate",
+                description: "Validate the on-disk config file against the schema. Exits non-zero on errors.",
+            },
+            async run() {
+                return runWithJsonErrors(async () => {
+                    const { runConfigValidate } = await import("./cli/config-validate.js");
+                    await runConfigValidate();
+                });
+            },
+        }),
+        migrate: defineCommand({
+            meta: {
+                name: "migrate",
+                description: "Migrate the config file to the current schema version. Use --dry-run to preview without writing.",
+            },
+            args: {
+                "dry-run": { type: "boolean", description: "Preview the migration result without writing.", default: false },
+                "print-diff": {
+                    type: "boolean",
+                    description: "Print a unified diff of old vs new config alongside the migration output.",
+                    default: false,
+                },
+            },
+            async run({ args }) {
+                return runWithJsonErrors(async () => {
+                    const { runConfigMigrate } = await import("./cli/config-migrate.js");
+                    await runConfigMigrate({ dryRun: Boolean(args["dry-run"]), printDiff: Boolean(args["print-diff"]) });
                 });
             },
         }),
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            if (hasConfigSubcommand(args))
+            if (hasSubcommand(args, CONFIG_SUBCOMMAND_SET))
                 return;
             if (args.list) {
                 output("config", listConfig(loadConfig()));
@@ -903,10 +1510,7 @@ const registryCommand = defineCommand({
             },
             async run({ args }) {
                 await runWithJsonErrors(async () => {
-                    const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-                    if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                        throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
-                    }
+                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
                     const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
                     output("registry-search", result);
                 });
@@ -971,7 +1575,7 @@ const feedbackCommand = defineCommand({
         description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
             "Positive feedback boosts an asset's EMA utility score, making it rank higher\n" +
             "in future searches without requiring a full reindex.\n\n" +
-            "Negative feedback records a negative signal in usage_events and events.jsonl.\n" +
+            "Negative feedback records a negative signal in usage_events and state.db events.\n" +
             "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
             "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
             "after recording negative feedback to have it reflected in search results.",
@@ -988,11 +1592,27 @@ const feedbackCommand = defineCommand({
                 "Reindexing is required for the signal to affect search results.",
             default: false,
         },
-        note: { type: "string", description: "Optional note to attach to the feedback" },
+        reason: {
+            type: "string",
+            description: "Reason for the feedback (required for negative feedback by default; used by distillation)",
+        },
+        note: { type: "string", description: "Alias for --reason (backward-compatible, prefer --reason)" },
+        "failure-mode": {
+            type: "string",
+            description: `Structured failure-mode taxonomy for negative feedback (F-3 / #384). ` +
+                `Accepted values: ${FEEDBACK_FAILURE_MODES.join(", ")}. ` +
+                "Stored alongside --reason in event metadata for aggregation by the distill pipeline.",
+        },
         tag: {
             type: "string",
             description: "Tag to attach to the feedback (repeatable, e.g. --tag slice:train --tag team:platform)",
         },
+        "applied-to": {
+            type: "string",
+            description: "Credit a lesson that helped resolve this task. Accepts a `lesson:<name>` ref. " +
+                "When combined with --positive, appends this feedback ref to the target lesson's " +
+                "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
@@ -1008,11 +1628,39 @@ const feedbackCommand = defineCommand({
                 throw new UsageError("Specify --positive or --negative.");
             }
             const signal = args.positive ? "positive" : "negative";
+            const reason = args.reason ?? args.note;
+            // F-3 / #384: Validate --failure-mode against the curated enum.
+            const failureMode = args["failure-mode"]?.trim() || undefined;
+            if (failureMode) {
+                if (args.positive) {
+                    throw new UsageError("--failure-mode is only valid for negative feedback.", "INVALID_FLAG_VALUE", "Remove --failure-mode or switch to --negative.");
+                }
+                const cfg = loadConfig();
+                const allowedModes = cfg.feedback?.allowedFailureModes ?? FEEDBACK_FAILURE_MODES;
+                if (allowedModes.length > 0 && !allowedModes.includes(failureMode)) {
+                    throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
+                }
+            }
+            if (args.negative === true && !reason?.trim()) {
+                // F-3 / #384: Default requireReason is now true. Load config to allow
+                // operators to opt out via feedback.requireReason: false in akm.json.
+                const cfg = loadConfig();
+                const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
+                if (requireReason) {
+                    throw new UsageError("Negative feedback requires --reason (structured failure signals are needed for distillation). " +
+                        "Use --failure-mode for a curated taxonomy or --reason for free text. " +
+                        "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "..." [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
+                }
+                else {
+                    warn("Warning: negative feedback without --reason provides less distillation signal.");
+                }
+            }
             const rawTags = parseAllFlagValues("--tag");
             const validatedTags = validateFeedbackTags(rawTags);
             const metadataObj = {
                 signal,
-                ...(args.note ? { note: args.note } : {}),
+                ...(reason?.trim() ? { reason: reason.trim() } : {}),
+                ...(failureMode ? { failureMode } : {}),
                 ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
             };
             const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
@@ -1021,6 +1669,7 @@ const feedbackCommand = defineCommand({
             if (sources.length > 0) {
                 await ensureIndex(sources[0].path);
             }
+            let utilityResult;
             const db = openExistingDatabase();
             try {
                 const entryId = findEntryIdByRef(db, ref);
@@ -1040,6 +1689,26 @@ const feedbackCommand = defineCommand({
                     signal,
                     metadata: metadataStr,
                 });
+                // Apply feedback-derived utility score adjustment immediately so that
+                // positive/negative signals influence search ranking without requiring
+                // a full reindex. We query the total accumulated feedback counts from
+                // usage_events so the delta reflects the entire signal history.
+                // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
+                try {
+                    const counts = db
+                        .prepare(`SELECT
+                 SUM(CASE WHEN signal = 'positive' THEN 1 ELSE 0 END) AS pos,
+                 SUM(CASE WHEN signal = 'negative' THEN 1 ELSE 0 END) AS neg
+               FROM usage_events
+               WHERE event_type = 'feedback' AND entry_id = ?`)
+                        .get(entryId);
+                    const pos = counts?.pos ?? 0;
+                    const neg = counts?.neg ?? 0;
+                    utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
+                }
+                catch {
+                    // best-effort — feedback recording succeeds even if utility update fails
+                }
             }
             finally {
                 closeDatabase(db);
@@ -1049,129 +1718,187 @@ const feedbackCommand = defineCommand({
                 ref,
                 metadata: metadataObj,
             });
-            output("feedback", { ok: true, ref, signal, note: args.note ?? null, tags: validatedTags });
-        });
-    },
-});
-const historyCommand = defineCommand({
-    meta: {
-        name: "history",
-        description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
-            "Event sources:\n" +
+            // F-5 / #386: When a high-utility asset crosses below the review threshold,
+            // auto-create a review-needed escalation proposal so a human can confirm
+            // whether the negative feedback is valid before the asset falls out of
+            // the improve loop. Best-effort — failure is logged but does not fail the
+            // feedback command.
+            // Emit a structured event rather than a proposal so the review-needed
+            // signal is queryable via `akm events list --type improve_review_needed`
+            // without risking accidental asset overwrite if the proposal is accepted.
+            if (utilityResult?.crossedReviewThreshold) {
+                try {
+                    appendEvent({
+                        eventType: "improve_review_needed",
+                        ref,
+                        metadata: {
+                            previousUtility: utilityResult.previousUtility,
+                            nextUtility: utilityResult.nextUtility,
+                            reason: reason?.trim() ?? null,
+                            failureMode: failureMode ?? null,
+                        },
+                    });
+                }
+                catch (escalationErr) {
+                    warn(`[feedback] Could not emit review-needed event for ${ref}: ${escalationErr instanceof Error ? escalationErr.message : String(escalationErr)}`);
+                }
+            }
+            // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
+            // target is a `lesson:<name>` ref and the signal is positive, append
+            // the feedback ref to the target lesson's `lessonStrength[]`
+            // frontmatter array (dedup, idempotent). Non-lesson targets are
+            // ignored. Failures here are warnings — feedback recording is the
+            // primary contract and must not regress on lesson-write errors.
+            const appliedToRaw = args["applied-to"]?.trim();
+            let appliedToResult = null;
+            if (appliedToRaw && signal === "positive") {
+                try {
+                    const parsedApplied = parseAssetRef(appliedToRaw);
+                    if (parsedApplied.type === "lesson") {
+                        const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
+                        if (updated) {
+                            appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
+                        }
+                    }
+                }
+                catch (err) {
+                    warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else if (appliedToRaw && signal !== "positive") {
+                warn("[feedback] --applied-to is ignored without --positive; lesson credit is only recorded on positive signals.");
+            }
+            output("feedback", {
+                ok: true,
+                ref,
+                signal,
+                reason: reason?.trim() ?? null,
+                failureMode: failureMode ?? null,
+                tags: validatedTags,
+                ...(appliedToResult
+                    ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
+                    : {}),
+            });
+        });
+    },
+});
+/**
+ * Phase 7A: append a feedback ref to a lesson's `lessonStrength[]`
+ * frontmatter array. Returns `{ strength }` (post-update count) on success,
+ * or `null` when the lesson cannot be located. Idempotent: if the ref is
+ * already credited, no write occurs.
+ *
+ * The function looks up the lesson's file via the indexer DB so the write
+ * targets the canonical on-disk location. Frontmatter is rewritten in
+ * place (no asset-spec round-trip) because we're modifying a single key on
+ * an existing asset — the same pattern memory-inference uses for
+ * `inferenceProcessed`.
+ */
+function appendLessonStrength(type, name, feedbackRef) {
+    const ref = `${type}:${name}`;
+    let filePath;
+    const db = openExistingDatabase();
+    try {
+        const entryId = findEntryIdByRef(db, ref);
+        if (entryId === undefined) {
+            warn(`[feedback] --applied-to: lesson ${ref} is not in the index.`);
+            return null;
+        }
+        const row = db.prepare("SELECT file_path FROM entries WHERE id = ?").get(entryId);
+        if (!row?.file_path) {
+            warn(`[feedback] --applied-to: cannot resolve file path for ${ref}.`);
+            return null;
+        }
+        filePath = row.file_path;
+    }
+    finally {
+        closeDatabase(db);
+    }
+    if (!filePath || !fs.existsSync(filePath)) {
+        warn(`[feedback] --applied-to: lesson file missing on disk for ${ref}.`);
+        return null;
+    }
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const data = { ...parsed.data };
+    const existing = data.lessonStrength;
+    const strengthList = Array.isArray(existing)
+        ? existing.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim())
+        : typeof existing === "string" && existing.trim().length > 0
+            ? [existing.trim()]
+            : [];
+    if (strengthList.includes(feedbackRef)) {
+        // Already credited — idempotent no-op.
+        return { strength: strengthList.length };
+    }
+    strengthList.push(feedbackRef);
+    data.lessonStrength = strengthList;
+    const block = parseFrontmatterBlock(raw);
+    const body = block?.content ?? raw;
+    const next = assembleAsset(data, body);
+    try {
+        // Preserve the existing file's permission bits (markdown assets are
+        // typically 0o644); writeFileAtomic defaults to 0o600 otherwise.
+        const mode = fs.statSync(filePath).mode & 0o777;
+        writeFileAtomic(filePath, next, mode);
+    }
+    catch (err) {
+        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    return { strength: strengthList.length };
+}
+const historyCommand = defineCommand({
+    meta: {
+        name: "history",
+        description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
+            "Event sources:\n" +
             "  usage_events (default): search, show, and feedback events from the local index.\n" +
-            "  events.jsonl (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
-            "    emitted by `akm proposal accept` / `akm proposal reject`.\n\n" +
+            "  state.db events (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
+            "    emitted by `akm accept` / `akm reject`.\n\n" +
             "Results from all active sources are merged and sorted chronologically.",
     },
     args: {
         ref: { type: "string", description: "Asset ref (type:name). Omit for stash-wide history." },
         since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
+        source: {
+            type: "string",
+            description: 'Filter by event source: "user" (default) or "improve" (akm improve operations).',
+        },
         "include-proposals": {
             type: "boolean",
-            description: "Also include proposal lifecycle events (promoted, rejected) from events.jsonl. " +
+            description: "Also include proposal lifecycle events (promoted, rejected) from state.db events. " +
                 "Default: false (usage_events only).",
             default: false,
         },
+        "accept-rate-by-source": {
+            type: "boolean",
+            description: "Compute accept-rate-per-source metrics from the proposal store and include them in the output (F-4 / #385). " +
+                "Useful for measuring which generators (reflect, distill, …) produce the most accepted proposals.",
+            default: false,
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
+            const sourceFlag = args.source;
+            if (sourceFlag !== undefined && sourceFlag !== "user" && sourceFlag !== "improve") {
+                throw new UsageError(`Invalid --source value: "${args.source}". Must be "user" or "improve".`, "INVALID_FLAG_VALUE");
+            }
+            const sources = resolveSourceEntries();
+            const stashDir = sources[0]?.path;
             const result = await akmHistory({
                 ref: args.ref,
                 since: args.since,
+                source: sourceFlag,
                 includeProposals: args["include-proposals"],
+                acceptRateBySource: args["accept-rate-by-source"],
+                stashDir,
             });
             output("history", result);
         });
     },
 });
-function normalizeMarkdownAssetName(name, fallback) {
-    const trimmed = (name ?? fallback)
-        .trim()
-        .replace(/\\/g, "/")
-        .replace(/^\/+|\/+$/g, "")
-        .replace(/\.md$/i, "");
-    if (!trimmed)
-        throw new UsageError("Asset name cannot be empty.");
-    const segments = trimmed.split("/");
-    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
-        throw new UsageError("Asset name must be a relative path without '.' or '..' segments.");
-    }
-    return trimmed;
-}
-function slugifyAssetName(value, fallbackPrefix) {
-    const slug = value
-        .toLowerCase()
-        .replace(/^[#>\-\s]+/, "")
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, MAX_CAPTURED_ASSET_SLUG_LENGTH);
-    return slug || `${fallbackPrefix}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
-}
-function inferAssetName(content, fallbackPrefix, preferred) {
-    const firstNonEmptyLine = content
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .find((line) => line.length > 0);
-    const basis = preferred?.trim() || firstNonEmptyLine || fallbackPrefix;
-    return slugifyAssetName(basis, fallbackPrefix);
-}
-function readKnowledgeContent(source) {
-    if (source === "-") {
-        const content = tryReadStdinText();
-        if (!content?.trim()) {
-            throw new UsageError("No stdin content received. Pipe a document into stdin or pass a file path.");
-        }
-        return { content };
-    }
-    const resolvedSource = path.resolve(source);
-    let stat;
-    try {
-        stat = fs.statSync(resolvedSource);
-    }
-    catch {
-        throw new UsageError(`Knowledge source not found: "${source}". Pass a readable file path or "-" for stdin.`);
-    }
-    if (!stat.isFile()) {
-        throw new UsageError(`Knowledge source must be a file: "${source}".`);
-    }
-    return {
-        content: fs.readFileSync(resolvedSource, "utf8"),
-        preferredName: path.basename(resolvedSource, path.extname(resolvedSource)),
-    };
-}
-async function readKnowledgeInput(source) {
-    if (!isHttpUrl(source))
-        return readKnowledgeContent(source);
-    const snapshot = await fetchWebsiteMarkdownSnapshot(source);
-    return { content: snapshot.content, preferredName: snapshot.preferredName };
-}
-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.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    // 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: result.ref,
-        path: result.path,
-        stashDir: source.path,
-    };
-}
 const workflowStartCommand = defineCommand({
     meta: {
         name: "start",
@@ -1196,16 +1923,20 @@ const workflowNextCommand = defineCommand({
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+        "dry-run": { type: "boolean", description: "Not supported — rejected with an error", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (getHyphenatedBoolean(args, "dry-run")) {
+                throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
+            }
             const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
             // If the target looks like a UUID-style run id (no `:` and matches the
             // run-id shape), short-circuit with a structured WORKFLOW_NOT_FOUND
             // error before parseAssetRef gets to throw an unhelpful ref-parse error.
             if (looksLikeWorkflowRunId(args.target)) {
                 const { hasWorkflowRun } = await import("./workflows/runs.js");
-                if (!hasWorkflowRun(args.target)) {
+                if (!(await hasWorkflowRun(args.target))) {
                     throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
                 }
             }
@@ -1250,7 +1981,7 @@ const workflowCompleteCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = completeWorkflowStep({
+            const result = await completeWorkflowStep({
                 runId: args.runId,
                 stepId: args.step,
                 status: parseWorkflowStepState(args.state),
@@ -1270,7 +2001,7 @@ const workflowStatusCommand = defineCommand({
         target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
+        return runWithJsonErrors(async () => {
             const target = args.target;
             // Check if target looks like a workflow ref
             const parsed = (() => {
@@ -1283,18 +2014,18 @@ const workflowStatusCommand = defineCommand({
             })();
             if (parsed?.type === "workflow") {
                 const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-                const { runs } = listWorkflowRuns({ workflowRef: ref });
+                const { runs } = await listWorkflowRuns({ workflowRef: ref });
                 if (runs.length === 0) {
                     throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
                 }
                 const mostRecent = runs[0];
                 if (!mostRecent)
                     throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-                const result = getWorkflowStatus(mostRecent.id);
+                const result = await getWorkflowStatus(mostRecent.id);
                 output("workflow-status", result);
             }
             else {
-                const result = getWorkflowStatus(target);
+                const result = await getWorkflowStatus(target);
                 output("workflow-status", result);
             }
         });
@@ -1310,8 +2041,8 @@ const workflowListCommand = defineCommand({
         active: { type: "boolean", description: "Only show active runs", default: false },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
+        return runWithJsonErrors(async () => {
+            const result = await listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
             output("workflow-list", result);
         });
     },
@@ -1424,8 +2155,8 @@ const workflowResumeCommand = defineCommand({
         runId: { type: "positional", description: "Workflow run id", required: true },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = resumeWorkflowRun(args.runId);
+        return runWithJsonErrors(async () => {
+            const result = await resumeWorkflowRun(args.runId);
             output("workflow-resume", result);
         });
     },
@@ -1447,10 +2178,10 @@ const workflowCommand = defineCommand({
         validate: workflowValidateCommand,
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
+        return runWithJsonErrors(async () => {
             if (hasWorkflowSubcommand(args))
                 return;
-            output("workflow-list", listWorkflowRuns({ activeOnly: true }));
+            output("workflow-list", await listWorkflowRuns({ activeOnly: true }));
         });
     },
 });
@@ -1520,6 +2251,10 @@ const rememberCommand = defineCommand({
             type: "string",
             description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
         },
+        showSimilar: {
+            type: "boolean",
+            description: "Return top-3 similar existing memories in output (opt-in)",
+        },
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
@@ -1541,14 +2276,25 @@ const rememberCommand = defineCommand({
             if (typeof args.channel === "string" && args.channel.trim())
                 scopeFields.channel = args.channel.trim();
             const hasScope = Object.keys(scopeFields).length > 0;
-            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.enrich;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
             const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
             if (!hasStructuredArgs) {
+                // Phase 1B / Rec 7: even the zero-flag hot-path emits
+                // `captureMode: hot` + `beliefState: asserted` so user-supplied
+                // memories outrank background-derived ones during ranking.
+                const frontmatterBlock = buildMemoryFrontmatter({
+                    captureMode: "hot",
+                    beliefState: "asserted",
+                });
+                const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
+                // Derive the asset slug from the body (not the frontmatter block);
+                // otherwise inferAssetName would key off the leading `---` delimiter.
                 const result = await writeMarkdownAsset({
                     type: "memory",
-                    content: body,
+                    content: contentWithFrontmatter,
                     name: args.name,
                     fallbackPrefix: "memory",
+                    preferredName: inferAssetName(body, "memory"),
                     force: args.force,
                     target: args.target,
                 });
@@ -1557,7 +2303,13 @@ const rememberCommand = defineCommand({
                     ref: result.ref,
                     metadata: { path: result.path, force: args.force === true },
                 });
-                output("remember", { ok: true, ...result });
+                if (args.showSimilar) {
+                    const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
+                    output("remember", { ok: true, ...result, similar });
+                }
+                else {
+                    output("remember", { ok: true, ...result });
+                }
                 return;
             }
             // ── Accumulate metadata from all three modes ──────────────────────────
@@ -1616,6 +2368,10 @@ const rememberCommand = defineCommand({
                     "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
             }
             // ── Build frontmatter and write ───────────────────────────────────────
+            // Phase 1B / Rec 7: the hot-path CLI write always marks the memory as
+            // `captureMode: hot` and `beliefState: asserted`. Ranking applies a
+            // hot-capture boost so user-supplied memories outrank otherwise-equal
+            // background-derived ones.
             const frontmatterBlock = buildMemoryFrontmatter({
                 description,
                 tags,
@@ -1623,6 +2379,8 @@ const rememberCommand = defineCommand({
                 observed_at,
                 expires,
                 subjective,
+                captureMode: "hot",
+                beliefState: "asserted",
                 ...(hasScope ? { scope: scopeFields } : {}),
             });
             const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
@@ -1646,53 +2404,31 @@ const rememberCommand = defineCommand({
                     ...(hasScope ? { scope: scopeFields } : {}),
                 },
             });
-            output("remember", { ok: true, ...result });
+            if (args.showSimilar) {
+                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                output("remember", { ok: true, ...result, similar });
+            }
+            else {
+                output("remember", { ok: true, ...result });
+            }
         });
     },
 });
-function resolveRememberContentArg(content) {
-    if (content === undefined)
-        return undefined;
-    const parsedFormat = parseFlagValue(process.argv, "--format");
-    if (parsedFormat !== undefined &&
-        content === parsedFormat &&
-        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
-        return undefined;
-    }
-    const parsedDetail = parseFlagValue(process.argv, "--detail");
-    if (parsedDetail !== undefined &&
-        content === parsedDetail &&
-        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
-        return undefined;
+/**
+ * Best-effort top-3 similar memory search for `--show-similar`.
+ * Scoped to memory: type; excludes the just-written ref.
+ */
+async function fetchSimilarMemories(query, excludeRef) {
+    try {
+        const result = await akmSearch({ query, type: "memory", limit: 4 });
+        return (result.hits ?? [])
+            .filter((h) => "ref" in h && h.ref !== excludeRef)
+            .slice(0, 3)
+            .map((h) => ({ ref: h.ref, ...(h.name ? { title: h.name } : {}) }));
     }
-    return content;
-}
-function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
-    const argv = process.argv.slice(2);
-    const rememberIndex = argv.indexOf("remember");
-    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
-    let flagIndex = -1;
-    let flagConsumesNextToken = false;
-    for (let i = 0; i < tokens.length; i += 1) {
-        const token = tokens[i];
-        if (token === flagName) {
-            flagIndex = i;
-            flagConsumesNextToken = true;
-            break;
-        }
-        if (token === `${flagName}=${flagValue}`) {
-            flagIndex = i;
-            break;
-        }
+    catch {
+        return [];
     }
-    if (flagIndex === -1)
-        return false;
-    if (tokens.slice(0, flagIndex).includes(content))
-        return false;
-    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
-    if (tokens.slice(firstTokenAfterFlag).includes(content))
-        return false;
-    return true;
 }
 const importKnowledgeCommand = defineCommand({
     meta: {
@@ -1782,10 +2518,11 @@ const helpCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    if (!args.version || !String(args.version).trim()) {
+                    const version = resolveHelpMigrateVersionArg(typeof args.version === "string" ? args.version : undefined);
+                    if (!version?.trim()) {
                         throw new UsageError("Usage: akm help migrate <version>.", "MISSING_REQUIRED_ARGUMENT", "Pass a version like `0.6.0`, `v0.6.0`, `0.6.0-rc1`, or `latest`.");
                     }
-                    process.stdout.write(renderMigrationHelp(args.version));
+                    process.stdout.write(renderMigrationHelp(version));
                 });
             },
         }),
@@ -1815,8 +2552,8 @@ const completionsCommand = defineCommand({
         const script = generateBashCompletions(main);
         if (args.install) {
             const dest = installBashCompletions(script);
-            console.error(`Completions installed to ${dest}`);
-            console.error(`Restart your shell or run:  source ${dest}`);
+            info(`Completions installed to ${dest}`);
+            info(`Restart your shell or run:  source ${dest}`);
         }
         else {
             process.stdout.write(script);
@@ -1912,6 +2649,13 @@ function resolveVaultPath(ref) {
     const source = findVaultSource(parsed.origin);
     const typeRoot = path.join(source.path, "vaults");
     const absPath = resolveAssetPathFromName("vault", typeRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the vaults directory.
+    // validateName already rejects traversal patterns like "../../foo", but an
+    // absolute-path override or symlink-based attack could still escape without
+    // this second check.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Vault name "${parsed.name}" escapes the vault directory.`);
+    }
     return { name: parsed.name, absPath, source, parsedRef: parsed };
 }
 /**
@@ -1940,6 +2684,10 @@ function listVaultsRecursive(listKeysFn) {
                 const canonical = deriveCanonicalAssetName("vault", vaultsDir, full);
                 if (!canonical)
                     continue;
+                // Skip sensitive vaults: presence of a sibling .sensitive marker file suppresses listing.
+                const markerPath = full.replace(/\.env$/, ".sensitive");
+                if (fs.existsSync(markerPath))
+                    continue;
                 const { keys } = listKeysFn(full);
                 result.push({ ref: makeVaultRef(canonical, source), path: full, keys });
             }
@@ -1962,6 +2710,9 @@ function splitVaultRunTarget(target) {
     if (!key) {
         throw new UsageError("Expected vault run target in the form <ref> or <ref/KEY>.");
     }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        throw new UsageError(`"${key}" is not a valid environment variable name.`, "INVALID_FLAG_VALUE");
+    }
     const resolved = resolveVaultPath(refPart);
     if (!fs.existsSync(resolved.absPath)) {
         throw new NotFoundError(`Vault not found: ${makeVaultRef(resolved.name, resolved.source)}`);
@@ -1982,48 +2733,100 @@ const vaultCreateCommand = defineCommand({
     meta: { name: "create", description: "Create an empty vault file (no-op if it already exists)" },
     args: {
         name: { type: "positional", description: "Vault name (e.g. prod) — file becomes <name>.env", required: true },
+        sensitive: {
+            type: "boolean",
+            description: "Exclude this vault from vault list output and the search index",
+            default: false,
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { createVault } = await import("./commands/vault.js");
             const { name, absPath, source } = resolveVaultPath(args.name);
             createVault(absPath);
-            output("vault-create", { ref: makeVaultRef(name, source), path: absPath });
+            if (args.sensitive) {
+                const markerPath = absPath.replace(/\.env$/, ".sensitive");
+                if (!fs.existsSync(markerPath)) {
+                    fs.writeFileSync(markerPath, "", { mode: 0o600 });
+                }
+            }
+            output("vault-create", { ref: makeVaultRef(name, source) });
         });
     },
 });
 const vaultSetCommand = defineCommand({
     meta: {
         name: "set",
-        description: 'Set a key in a vault. Value is written to disk and never echoed back. Accepts KEY=VALUE combined form or separate KEY VALUE args. Optionally attach a comment with --comment "description".',
+        description: 'Set a key in a vault. Value is read from stdin by default (never via argv, avoiding /proc/cmdline exposure). Use --from-env <VAR> to read from an environment variable instead. Optionally attach a comment with --comment "description".',
     },
     args: {
         ref: { type: "positional", description: "Vault ref (e.g. vault:prod or just prod)", required: true },
-        key: { type: "positional", description: "Key name (e.g. DB_URL) or KEY=VALUE combined form", required: true },
-        value: {
-            type: "positional",
-            description: "Value to store (omit when using KEY=VALUE combined form)",
-            required: false,
-        },
+        key: { type: "positional", description: "Key name (e.g. DB_URL)", required: true },
         comment: { type: "string", description: "Optional comment written above the key line", required: false },
+        "from-env": {
+            type: "string",
+            description: "Read value from the named environment variable instead of stdin",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
+            // Trap the legacy 3-positional / KEY=VALUE forms removed in 0.8.0.
+            //
+            // Without this trap, citty silently accepts the extra positional and the
+            // command falls through to read stdin. In cron/CI where stdin is empty,
+            // the existing secret would be silently overwritten with an empty string
+            // (silent data loss). Detect both removed forms and hard-error before
+            // touching the vault file.
+            //
+            // Case 1: `akm vault set <ref> KEY=VALUE` — the second positional
+            //         contains `=`. Argv looks like:
+            //           [..., "vault", "set", "<ref>", "KEY=VALUE", ...]
+            //         citty binds `args.key = "KEY=VALUE"`.
+            // Case 2: `akm vault set <ref> KEY VALUE` — a third positional follows
+            //         the key. citty mirrors every positional (including the
+            //         declared ones) into `args._`, so we detect this by length:
+            //         more than 2 positionals means an extra `<VALUE>` was passed.
+            const allPositionals = Array.isArray(args._) ? args._.filter((v) => typeof v === "string") : [];
+            const hasExtraPositional = allPositionals.length > 2;
+            const keyHasEquals = typeof args.key === "string" && args.key.includes("=");
+            if (hasExtraPositional || keyHasEquals) {
+                throw new UsageError("'akm vault set' no longer accepts the value via argv (removed in 0.8.0 for security).\n" +
+                    "       Pass the value via stdin or --from-env <VAR> instead:\n" +
+                    "         printf '%s' \"$SECRET\" | akm vault set <ref> <KEY>\n" +
+                    '         AKM_VALUE="$SECRET" akm vault set <ref> <KEY> --from-env AKM_VALUE', "INVALID_FLAG_VALUE");
+            }
             const { setKey } = await import("./commands/vault.js");
             const { name, absPath, source } = resolveVaultPath(args.ref);
-            let realKey;
+            const fromEnv = getHyphenatedArg(args, "from-env");
             let realValue;
-            if ((args.value === undefined || args.value === "") && args.key.includes("=")) {
-                const eqIdx = args.key.indexOf("=");
-                realKey = args.key.slice(0, eqIdx);
-                realValue = args.key.slice(eqIdx + 1);
+            if (fromEnv !== undefined) {
+                const envVal = process.env[fromEnv];
+                if (envVal === undefined) {
+                    throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
+                }
+                realValue = envVal;
             }
             else {
-                realKey = args.key;
-                realValue = args.value ?? "";
+                // Print a prompt when stdin is attached to a terminal so an
+                // interactive invocation doesn't silently hang with no indication
+                // that input is being awaited.
+                if (process.stdin.isTTY) {
+                    process.stderr.write(`Enter value for "${args.key}" (Ctrl-D when done):\n`);
+                }
+                const MAX_VAULT_VALUE_BYTES = 1024 * 1024; // 1 MB
+                let totalBytes = 0;
+                const chunks = [];
+                for await (const chunk of Bun.stdin.stream()) {
+                    totalBytes += chunk.byteLength;
+                    if (totalBytes > MAX_VAULT_VALUE_BYTES) {
+                        throw new UsageError("Vault value exceeds 1 MB limit. Values must be provided via stdin.");
+                    }
+                    chunks.push(chunk);
+                }
+                realValue = Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
             }
-            setKey(absPath, realKey, realValue, args.comment);
-            output("vault-set", { ref: makeVaultRef(name, source), key: realKey, path: absPath });
+            setKey(absPath, args.key, realValue, args.comment);
+            output("vault-set", { ref: makeVaultRef(name, source), key: args.key });
         });
     },
 });
@@ -2032,16 +2835,24 @@ const vaultUnsetCommand = defineCommand({
     args: {
         ref: { type: "positional", description: "Vault ref", required: true },
         key: { type: "positional", description: "Key name to remove", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { unsetKey } = await import("./commands/vault.js");
+            // Validate path first so traversal errors surface before the confirmation prompt.
             const { name, absPath, source } = resolveVaultPath(args.ref);
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove key "${args.key}" from vault "${args.ref}"? This cannot be undone.`, { yes: args.yes === true });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
+            const { unsetKey } = await import("./commands/vault.js");
             if (!fs.existsSync(absPath)) {
                 throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
             }
             const removed = unsetKey(absPath, args.key);
-            output("vault-unset", { ref: makeVaultRef(name, source), key: args.key, removed, path: absPath });
+            output("vault-unset", { ref: makeVaultRef(name, source), key: args.key, removed });
         });
     },
 });
@@ -2097,6 +2908,15 @@ const vaultRunCommand = defineCommand({
                     mergedEnv[envKey] = envValue;
                 }
             }
+            // Emit vault access event (keys only, no values) for audit trail.
+            // Best-effort: never block vault run on event write failure.
+            appendEvent({
+                eventType: "vault_access",
+                ref: makeVaultRef(name, source),
+                metadata: {
+                    keys: key ? [key] : Object.keys(envValues),
+                },
+            });
             const result = spawnSync(command[0], command.slice(1), {
                 stdio: "inherit",
                 env: mergedEnv,
@@ -2122,7 +2942,7 @@ const vaultCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (hasVaultSubcommand(args))
+            if (hasSubcommand(args, VAULT_SUBCOMMAND_SET))
                 return;
             // Default action: list all vaults
             const { listKeys } = await import("./commands/vault.js");
@@ -2158,11 +2978,6 @@ const wikiRegisterCommand = defineCommand({
             description: "Mark a git-backed source as writable so changes can be pushed back",
             default: false,
         },
-        trust: {
-            type: "boolean",
-            description: "Bypass install-audit blocking for this registration only",
-            default: false,
-        },
         "max-pages": { type: "string", description: "Maximum pages to crawl for website sources (default: 50)" },
         "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
     },
@@ -2173,7 +2988,6 @@ const wikiRegisterCommand = defineCommand({
                 ref: args.ref.trim(),
                 name: args.name,
                 options: Object.keys(buildWebsiteOptions(args)).length > 0 ? buildWebsiteOptions(args) : undefined,
-                trustThisInstall: args.trust,
                 writable: args.writable,
             });
             output("wiki-register", result);
@@ -2286,12 +3100,39 @@ const wikiStashCommand = defineCommand({
         name: { type: "positional", description: "Wiki name", required: true },
         source: { type: "positional", description: "Source file path, URL, or '-' to read from stdin", required: true },
         as: { type: "string", description: "Preferred slug base (defaults to source filename or first-line slug)" },
+        target: {
+            type: "string",
+            description: "Name of a writable stash source to write into instead of the default stash. Must match a configured source name (run `akm list` to see sources).",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { stashRaw } = await import("./wiki/wiki.js");
-            const { content, preferredName } = await readKnowledgeInput(args.source);
-            const stashDir = resolveStashDir();
+            const { content, preferredName } = await (async () => {
+                if (!isHttpUrl(args.source))
+                    return readKnowledgeInput(args.source);
+                const { fetchWebsiteMarkdownSnapshot } = await import("./sources/website-ingest");
+                const snapshot = await fetchWebsiteMarkdownSnapshot(args.source);
+                return { content: snapshot.content, preferredName: args.as ?? snapshot.preferredName };
+            })();
+            let stashDir;
+            if (args.target) {
+                // Resolve the named source to its filesystem path.
+                const cfg = loadConfig();
+                const sources = resolveConfiguredSources(cfg);
+                const match = sources.find((s) => s.name === args.target);
+                if (!match) {
+                    throw new UsageError(`--target must reference a configured source name. No source named "${args.target}" found. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+                }
+                const spec = match.source;
+                if (spec.type !== "filesystem" && spec.type !== "local") {
+                    throw new ConfigError(`Source "${args.target}" is not a filesystem source and cannot be used as a wiki stash target.`, "INVALID_CONFIG_FILE", `Use a source with type "filesystem" or "local", or omit --target to use the default stash.`);
+                }
+                stashDir = spec.path;
+            }
+            else {
+                stashDir = resolveStashDir();
+            }
             const result = stashRaw({
                 stashDir,
                 wikiName: args.name,
@@ -2327,17 +3168,52 @@ const wikiLintCommand = defineCommand({
 const wikiIngestCommand = defineCommand({
     meta: {
         name: "ingest",
-        description: "Print the ingest workflow for this wiki. Does not perform the ingest; instructs the agent to.",
+        description: "Dispatch an agent to execute the ingest workflow for this wiki. Uses --profile or config.defaults.agent.",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
+        profile: {
+            type: "string",
+            description: "Agent profile to use (default: config.defaults.agent).",
+        },
+        model: {
+            type: "string",
+            description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs.",
+        },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds." },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { buildIngestWorkflow } = await import("./wiki/wiki.js");
             const stashDir = resolveStashDir();
-            const result = buildIngestWorkflow(stashDir, args.name);
-            output("wiki-ingest", result);
+            const built = buildIngestWorkflow(stashDir, args.name);
+            const config = loadConfig();
+            const profileName = getStringArg(args, "profile") ?? config.defaults?.agent;
+            if (!profileName) {
+                throw new UsageError("akm wiki ingest requires an agent profile. Pass --profile <name> or set defaults.agent in config.", "MISSING_REQUIRED_ARGUMENT", "Available profiles are listed under profiles.agent in your config. Run `akm config get profiles.agent` to inspect.");
+            }
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const model = getStringArg(args, "model");
+            const { getDefaultLlmConfig } = await import("./core/config.js");
+            const dispatchResult = await akmAgentDispatch({
+                profileName,
+                agentConfig: config,
+                llmConfig: getDefaultLlmConfig(config),
+                prompt: built.workflow,
+                dispatch: {
+                    prompt: built.workflow,
+                    ...(model !== undefined ? { model } : {}),
+                },
+                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+            });
+            output("wiki-ingest", {
+                wiki: built.wiki,
+                path: built.path,
+                schemaPath: built.schemaPath,
+                dispatched: true,
+                profile: profileName,
+                agentResult: dispatchResult,
+            });
         });
     },
 });
@@ -2360,7 +3236,7 @@ const wikiCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (hasWikiSubcommand(args))
+            if (hasSubcommand(args, WIKI_SUBCOMMAND_SET))
                 return;
             // Default action: list wikis
             const { listWikis } = await import("./wiki/wiki.js");
@@ -2369,15 +3245,15 @@ const wikiCommand = defineCommand({
     },
 });
 // ── `akm events` ────────────────────────────────────────────────────────────
-// Append-only events stream surface (#204). `list` reads `events.jsonl`
-// with optional --since/--type/--ref filters; `tail` follows the file via
+// Append-only events stream surface (#204). `list` reads state.db events
+// with optional --since/--type/--ref filters; `tail` follows the table via
 // a polling loop and prints each event as a single JSONL line.
 const eventsListCommand = defineCommand({
-    meta: { name: "list", description: "List events from the append-only events.jsonl stream" },
+    meta: { name: "list", description: "List events from the append-only state.db events stream" },
     args: {
         since: {
             type: "string",
-            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-cursor (resume across processes)",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
         },
         type: { type: "string", description: "Filter by event type (add, remove, remember, feedback, ...)" },
         ref: { type: "string", description: "Filter by asset ref (type:name)" },
@@ -2406,11 +3282,11 @@ const eventsListCommand = defineCommand({
     },
 });
 const eventsTailCommand = defineCommand({
-    meta: { name: "tail", description: "Follow the append-only events.jsonl stream (polling)" },
+    meta: { name: "tail", description: "Follow the append-only state.db events stream (polling)" },
     args: {
         since: {
             type: "string",
-            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-cursor (resume across processes)",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
         },
         type: { type: "string", description: "Filter by event type" },
         ref: { type: "string", description: "Filter by asset ref (type:name)" },
@@ -2428,9 +3304,9 @@ const eventsTailCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const intervalMs = parsePositiveInt(getHyphenatedArg(args, "interval-ms"), "--interval-ms");
-            const maxDurationMs = parsePositiveInt(getHyphenatedArg(args, "max-duration-ms"), "--max-duration-ms");
-            const maxEvents = parsePositiveInt(getHyphenatedArg(args, "max-events"), "--max-events");
+            const intervalMs = parsePositiveIntFlag(getHyphenatedArg(args, "interval-ms"), "--interval-ms");
+            const maxDurationMs = parsePositiveIntFlag(getHyphenatedArg(args, "max-duration-ms"), "--max-duration-ms");
+            const maxEvents = parsePositiveIntFlag(getHyphenatedArg(args, "max-events"), "--max-events");
             const mode = getOutputMode();
             // In streaming text mode we want each event to print as soon as it
             // arrives. The polling loop emits via `onEvent`; the final result is
@@ -2484,39 +3360,102 @@ const eventsTailCommand = defineCommand({
         });
     },
 });
-function parsePositiveInt(raw, flag) {
-    if (raw === undefined)
-        return undefined;
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return undefined;
-    const value = Number.parseInt(trimmed, 10);
-    if (Number.isNaN(value) || value <= 0) {
-        throw new UsageError(`Invalid ${flag} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
-    }
-    return value;
-}
 const eventsCommand = defineCommand({
     meta: {
         name: "events",
-        description: "Read or follow the append-only events.jsonl stream (mutations, feedback, indexing)",
+        description: "Read or follow the append-only state.db events stream (mutations, feedback, indexing)",
     },
     subCommands: {
         list: eventsListCommand,
         tail: eventsTailCommand,
     },
 });
+// ── lessons subcommands (Phase 7A / Advantage D4c) ──────────────────────────
+const lessonsCoverageCommand = defineCommand({
+    meta: {
+        name: "coverage",
+        description: "Report tags that exist on indexed assets but are NOT yet covered by any lesson.\n\n" +
+            "Useful for spotting topics where the stash has skills/commands/scripts but no\n" +
+            "crystallized lesson — a signal that the team has tacit knowledge worth distilling.\n\n" +
+            "Default output is JSON: { uncoveredTags: string[], lessonTagCount: number, totalTagCount: number }.\n" +
+            "Pass --format text for a plain-text bulleted list.",
+    },
+    args: {},
+    run() {
+        return runWithJsonErrors(() => {
+            const db = openExistingDatabase();
+            try {
+                const allTagSet = collectTagSetFromEntries(db, undefined);
+                const lessonTagSet = collectTagSetFromEntries(db, "lesson");
+                const uncovered = [];
+                for (const tag of allTagSet) {
+                    if (!lessonTagSet.has(tag))
+                        uncovered.push(tag);
+                }
+                uncovered.sort((a, b) => a.localeCompare(b));
+                output("lessons-coverage", {
+                    ok: true,
+                    uncoveredTags: uncovered,
+                    lessonTagCount: lessonTagSet.size,
+                    totalTagCount: allTagSet.size,
+                });
+            }
+            finally {
+                closeDatabase(db);
+            }
+        });
+    },
+});
+/**
+ * Walk indexed entries and collect a deduplicated set of tags. When
+ * `entryType` is provided, only entries of that type contribute tags.
+ *
+ * Pure read; never mutates the DB. Used by `akm lessons coverage` (Phase 7A)
+ * to compute the diff between all-asset tags and lesson tags.
+ */
+function collectTagSetFromEntries(db, entryType) {
+    const tags = new Set();
+    const stmt = entryType
+        ? db.prepare("SELECT entry_json FROM entries WHERE entry_type = ?")
+        : db.prepare("SELECT entry_json FROM entries");
+    const rows = (entryType ? stmt.all(entryType) : stmt.all());
+    for (const row of rows) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.entry_json);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(parsed.tags))
+            continue;
+        for (const tag of parsed.tags) {
+            if (typeof tag === "string" && tag.trim().length > 0) {
+                tags.add(tag.trim().toLowerCase());
+            }
+        }
+    }
+    return tags;
+}
+const lessonsCommand = defineCommand({
+    meta: {
+        name: "lessons",
+        description: "Lesson-asset tooling: tag-coverage gaps, strength queries.",
+    },
+    subCommands: {
+        coverage: lessonsCoverageCommand,
+    },
+});
 // ── proposal substrate (#225) ────────────────────────────────────────────────
-const proposalListCommand = defineCommand({
-    meta: { name: "list", description: "List pending proposals (use --include-archive to see decided ones)" },
+const proposalsCommand = defineCommand({
+    meta: { name: "proposals", description: "List proposal queue entries" },
     args: {
-        status: { type: "string", description: "Filter by status (pending|accepted|rejected)" },
-        ref: { type: "string", description: "Filter by asset ref (type:name)" },
-        "include-archive": {
-            type: "boolean",
-            description: "Include accepted/rejected proposals from the archive",
-            default: false,
+        status: {
+            type: "string",
+            description: "Filter by status (pending|accepted|rejected|reverted)",
         },
+        ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        type: { type: "string", description: "Filter by asset type" },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
@@ -2524,54 +3463,203 @@ const proposalListCommand = defineCommand({
             const result = akmProposalList({
                 status,
                 ref: args.ref,
-                includeArchive: getHyphenatedBoolean(args, "include-archive"),
+                includeArchive: status === "accepted" || status === "rejected" || status === "reverted",
             });
             output("proposal-list", result);
         });
     },
 });
-const proposalShowCommand = defineCommand({
-    meta: { name: "show", description: "Show a proposal's metadata, payload, and validation report" },
-    args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
-    },
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = akmProposalShow({ id: args.id });
-            output("proposal-show", result);
-        });
-    },
-});
-const proposalAcceptCommand = defineCommand({
-    meta: { name: "accept", description: "Validate and promote a proposal to a real asset" },
+const acceptCommand = defineCommand({
+    meta: { name: "accept", description: "Accept a proposal and promote it into the stash" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --source is provided.",
+            required: false,
+        },
         target: { type: "string", description: "Override the write target by source name" },
+        // F-6 / #393: Batch accept by source, diff size, or age.
+        source: {
+            type: "string",
+            description: "F-6: Bulk-accept all pending proposals from this source (e.g. reflect, distill). Requires no positional id.",
+        },
+        "max-diff-lines": {
+            type: "string",
+            description: "F-6: When bulk-accepting, only accept proposals whose content is <= this many lines. Skips larger proposals.",
+        },
+        "older-than": {
+            type: "string",
+            description: "F-6: When bulk-accepting, only accept proposals created more than this many days ago (e.g. '7' for 7 days).",
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "F-6: List proposals that would be bulk-accepted without accepting them.",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            // F-6 / #393: Bulk-accept when --source is provided without a positional id.
+            if (args.source && !args.id) {
+                const { listProposals } = await import("./core/proposals");
+                const stashDir = resolveStashDir();
+                const rawMaxDiff = args["max-diff-lines"] ? Number.parseInt(String(args["max-diff-lines"]), 10) : undefined;
+                if (rawMaxDiff !== undefined && (Number.isNaN(rawMaxDiff) || rawMaxDiff < 0)) {
+                    throw new UsageError("--max-diff-lines must be a non-negative integer", "INVALID_FLAG_VALUE");
+                }
+                const rawOlderThan = args["older-than"] ? Number.parseInt(String(args["older-than"]), 10) : undefined;
+                if (rawOlderThan !== undefined && (Number.isNaN(rawOlderThan) || rawOlderThan < 0)) {
+                    throw new UsageError("--older-than must be a non-negative integer (days)", "INVALID_FLAG_VALUE");
+                }
+                const maxDiffLines = rawMaxDiff;
+                const olderThanMs = rawOlderThan !== undefined ? rawOlderThan * 86_400_000 : undefined;
+                const pending = listProposals(stashDir, { status: "pending" }).filter((p) => {
+                    if (p.source !== args.source)
+                        return false;
+                    if (maxDiffLines !== undefined) {
+                        const lines = (p.payload.content ?? "").split("\n").length;
+                        if (lines > maxDiffLines)
+                            return false;
+                    }
+                    if (olderThanMs !== undefined) {
+                        const age = Date.now() - new Date(p.createdAt).getTime();
+                        if (age < olderThanMs)
+                            return false;
+                    }
+                    return true;
+                });
+                const results = [];
+                for (const proposal of pending) {
+                    if (args["dry-run"]) {
+                        results.push({ id: proposal.id, ref: proposal.ref, source: proposal.source, dryRun: true });
+                    }
+                    else {
+                        const result = await akmProposalAccept({ id: proposal.id, target: args.target });
+                        results.push(result);
+                    }
+                }
+                output("proposal-accept-batch", { accepted: results.length, results, dryRun: args["dry-run"] });
+                return;
+            }
+            if (!args.id) {
+                throw new UsageError("Usage: akm accept <id>  OR  akm accept --source <source>", "MISSING_REQUIRED_ARGUMENT");
+            }
             const result = await akmProposalAccept({ id: args.id, target: args.target });
             output("proposal-accept", result);
         });
     },
 });
-const proposalRejectCommand = defineCommand({
-    meta: { name: "reject", description: "Archive a pending proposal with an optional reason" },
+const rejectCommand = defineCommand({
+    meta: { name: "reject", description: "Reject a proposal and record the reason" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
-        reason: { type: "string", description: "Reason for rejection (recorded in the archived proposal)" },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --source is provided.",
+            required: false,
+        },
+        reason: { type: "string", description: "Reason for rejection (required)" },
+        // F-6 / #393: Batch reject by source, diff size, or age.
+        source: {
+            type: "string",
+            description: "F-6: Bulk-reject all pending proposals from this source (e.g. reflect, distill). Requires no positional id.",
+        },
+        "max-diff-lines": {
+            type: "string",
+            description: "F-6: When bulk-rejecting, only reject proposals whose content is <= this many lines. Skips larger proposals.",
+        },
+        "older-than": {
+            type: "string",
+            description: "F-6: When bulk-rejecting, only reject proposals created more than this many days ago (e.g. '7' for 7 days).",
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "F-6: List proposals that would be bulk-rejected without rejecting them.",
+            default: false,
+        },
+        yes: {
+            type: "boolean",
+            alias: "y",
+            description: "Skip confirmation prompt (required in non-interactive mode)",
+            default: false,
+        },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = akmProposalReject({ id: args.id, reason: args.reason });
-            output("proposal-reject", result);
+        return runWithJsonErrors(async () => {
+            if (!args.reason || !String(args.reason).trim()) {
+                throw new UsageError("Usage: akm reject <id> --reason '<reason>'  OR  akm reject --source <source> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
+            }
+            // F-6 / #393: Bulk-reject when --source is provided without a positional id.
+            if (args.source && !args.id) {
+                const { confirmDestructive } = await import("./cli/confirm.js");
+                const confirmed = await confirmDestructive(`Bulk-reject all matching proposals from source "${args.source}"? This cannot be undone.`, { yes: args.yes === true || args["dry-run"] === true });
+                if (!confirmed) {
+                    process.stderr.write("Aborted.\n");
+                    return;
+                }
+                const { listProposals } = await import("./core/proposals");
+                const stashDir = resolveStashDir();
+                const rawMaxDiff = args["max-diff-lines"] ? Number.parseInt(String(args["max-diff-lines"]), 10) : undefined;
+                if (rawMaxDiff !== undefined && (Number.isNaN(rawMaxDiff) || rawMaxDiff < 0)) {
+                    throw new UsageError("--max-diff-lines must be a non-negative integer", "INVALID_FLAG_VALUE");
+                }
+                const rawOlderThan = args["older-than"] ? Number.parseInt(String(args["older-than"]), 10) : undefined;
+                if (rawOlderThan !== undefined && (Number.isNaN(rawOlderThan) || rawOlderThan < 0)) {
+                    throw new UsageError("--older-than must be a non-negative integer (days)", "INVALID_FLAG_VALUE");
+                }
+                const maxDiffLines = rawMaxDiff;
+                const olderThanMs = rawOlderThan !== undefined ? rawOlderThan * 86_400_000 : undefined;
+                const pending = listProposals(stashDir, { status: "pending" }).filter((p) => {
+                    if (p.source !== args.source)
+                        return false;
+                    if (maxDiffLines !== undefined) {
+                        const lines = (p.payload.content ?? "").split("\n").length;
+                        if (lines > maxDiffLines)
+                            return false;
+                    }
+                    if (olderThanMs !== undefined) {
+                        const age = Date.now() - new Date(p.createdAt).getTime();
+                        if (age < olderThanMs)
+                            return false;
+                    }
+                    return true;
+                });
+                const results = [];
+                for (const proposal of pending) {
+                    if (args["dry-run"]) {
+                        results.push({ id: proposal.id, ref: proposal.ref, source: proposal.source, dryRun: true });
+                    }
+                    else {
+                        const result = akmProposalReject({ id: proposal.id, reason: String(args.reason) });
+                        results.push(result);
+                    }
+                }
+                output("proposal-reject-batch", { rejected: results.length, results, dryRun: args["dry-run"] });
+                return;
+            }
+            if (!args.id) {
+                throw new UsageError("Usage: akm reject <id> --reason '<reason>'  OR  akm reject --source <source> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
+            }
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Reject proposal "${args.id}"? This cannot be undone.`, {
+                yes: args.yes === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
+            const result = akmProposalReject({ id: args.id, reason: String(args.reason) });
+            output("proposal-reject", result);
         });
     },
 });
-const proposalDiffCommand = defineCommand({
-    meta: { name: "diff", description: "Show the diff between an existing asset and a pending proposal" },
+const diffCommand = defineCommand({
+    meta: { name: "diff", description: "Show the diff for a proposal (accepts full UUID, UUID prefix, or asset ref)" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            required: true,
+        },
         target: { type: "string", description: "Override the write target by source name" },
     },
     run({ args }) {
@@ -2581,152 +3669,327 @@ const proposalDiffCommand = defineCommand({
         });
     },
 });
-const proposalCommand = defineCommand({
-    meta: {
-        name: "proposal",
-        description: "Review and promote queued asset proposals (durable storage under .akm/proposals/)",
-    },
-    subCommands: {
-        list: proposalListCommand,
-        show: proposalShowCommand,
-        accept: proposalAcceptCommand,
-        reject: proposalRejectCommand,
-        diff: proposalDiffCommand,
-    },
-});
-// ── distill (#228) ──────────────────────────────────────────────────────────
-const distillCommand = defineCommand({
+// Phase 6C (Advantage D6c): revert an accepted proposal.
+//
+// Exit codes (mapped by `runWithJsonErrors` from the typed errors thrown by
+// `akmProposalRevert` / `revertProposal`):
+//   0 — success; prior content restored.
+//   1 — generic error (also used by `UsageError("INVALID_FLAG_VALUE")` and
+//       `UsageError("MISSING_REQUIRED_ARGUMENT")` when the proposal is not
+//       accepted, or no backup is available).
+//   1 — `NotFoundError("FILE_NOT_FOUND")` when the proposal id does not resolve.
+const revertCommand = defineCommand({
     meta: {
-        name: "distill",
-        description: "Distil feedback for an asset into a queued lesson proposal (gated on llm.features.feedback_distillation)",
+        name: "revert",
+        description: "Revert an accepted proposal: restore the prior asset content from the backup captured at promotion time. " +
+            "Errors if the proposal is not accepted or has no backup (new-asset proposals leave no backup). " +
+            "Accepts the full proposal UUID or the asset ref. UUID prefixes are not supported for archived proposals — use the full UUID.",
     },
     args: {
-        ref: { type: "positional", description: "Asset ref (type:name) to distil from", required: true },
-        "source-run": {
-            type: "string",
-            description: "Optional run id propagated onto the queued proposal for traceability",
-        },
-        "exclude-feedback-from": {
-            type: "string",
-            description: "Comma-separated asset refs whose feedback events MUST be filtered out before the LLM input is built. Falls back to AKM_DISTILL_EXCLUDE_FEEDBACK_FROM when omitted.",
-        },
-        "exclude-tags": {
-            type: "string",
-            description: "Exclude feedback events matching these tags (repeatable, e.g. --exclude-tags slice:eval)",
-        },
-        "include-tags": {
-            type: "string",
-            description: "Only include feedback events with ALL these tags (repeatable)",
+        id: {
+            type: "positional",
+            description: "Proposal id (full uuid) or asset ref (e.g. skill:akm-dream). UUID prefixes are not supported for archived proposals — use the full UUID.",
+            required: true,
         },
+        target: { type: "string", description: "Override the write target by source name" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const excludeFlag = getHyphenatedArg(args, "exclude-feedback-from");
-            const excludeEnv = process.env.AKM_DISTILL_EXCLUDE_FEEDBACK_FROM;
-            // CLI flag takes precedence over the env var when both are present.
-            const excludeRaw = excludeFlag ?? excludeEnv;
-            const excludeFeedbackFromRefs = parseExcludeFeedbackFromRefs(excludeRaw);
-            const excludeTagsRaw = parseAllFlagValues("--exclude-tags");
-            const excludeTagsEnv = process.env.AKM_DISTILL_EXCLUDE_TAGS;
-            const excludeTags = [
-                ...new Set([
-                    ...excludeTagsRaw,
-                    ...(excludeTagsEnv
-                        ? excludeTagsEnv
-                            .split(",")
-                            .map((s) => s.trim())
-                            .filter(Boolean)
-                        : []),
-                ]),
-            ];
-            const includeTagsRaw = parseAllFlagValues("--include-tags");
-            const includeTagsEnv = process.env.AKM_DISTILL_INCLUDE_TAGS;
-            const includeTags = [
-                ...new Set([
-                    ...includeTagsRaw,
-                    ...(includeTagsEnv
-                        ? includeTagsEnv
-                            .split(",")
-                            .map((s) => s.trim())
-                            .filter(Boolean)
-                        : []),
-                ]),
-            ];
-            const result = await akmDistill({
-                ref: args.ref,
-                sourceRun: getHyphenatedArg(args, "source-run"),
-                ...(excludeFeedbackFromRefs.length > 0 ? { excludeFeedbackFromRefs } : {}),
-                ...(excludeTags.length > 0 ? { excludeTags } : {}),
-                ...(includeTags.length > 0 ? { includeTags } : {}),
+            const result = await akmProposalRevert({
+                id: args.id,
+                target: args.target,
             });
-            output("distill", result);
+            output("proposal-revert", result);
         });
     },
 });
-/**
- * Parse a comma-separated list of asset refs (#267 — `--exclude-feedback-from`
- * and `AKM_DISTILL_EXCLUDE_FEEDBACK_FROM`). Each entry is validated against
- * the canonical `[origin//]type:name` grammar via `parseAssetRef`; an
- * invalid entry surfaces as a UsageError → exit 2.
- */
-function parseExcludeFeedbackFromRefs(raw) {
-    if (raw === undefined || raw.trim() === "")
-        return [];
-    const refs = raw
-        .split(",")
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0);
-    for (const ref of refs) {
-        try {
-            parseAssetRef(ref);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            throw new UsageError(`Invalid --exclude-feedback-from ref "${ref}": ${message}`, "INVALID_FLAG_VALUE", "Each ref must match `[origin//]type:name`, e.g. skill:deploy or team//memory:auth-tips.");
-        }
-    }
-    return refs;
-}
+// ── distill (#228) ──────────────────────────────────────────────────────────
 function parseProposalStatus(raw) {
     if (raw === undefined)
         return undefined;
     const trimmed = raw.trim();
     if (!trimmed)
         return undefined;
-    if (trimmed === "pending" || trimmed === "accepted" || trimmed === "rejected")
+    if (trimmed === "pending" || trimmed === "accepted" || trimmed === "rejected" || trimmed === "reverted") {
         return trimmed;
-    throw new UsageError(`Invalid --status value: "${raw}". Expected one of: pending, accepted, rejected.`, "INVALID_FLAG_VALUE");
+    }
+    throw new UsageError(`Invalid --status value: "${raw}". Expected one of: pending, accepted, rejected, reverted.`, "INVALID_FLAG_VALUE");
 }
-// ── reflect / propose (agent proposal-producers, #226) ──────────────────────
-const reflectCommand = defineCommand({
+const agentCommand = defineCommand({
     meta: {
-        name: "reflect",
-        description: "Ask the configured agent CLI to review an asset (or recent feedback) and queue a revised proposal",
+        name: "agent",
+        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a stash agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
     },
     args: {
-        ref: {
+        profile: {
             type: "positional",
-            description: "Asset ref (type:name) to reflect on. Optional — omit to reflect across recent feedback.",
+            description: "Agent profile / platform to use (opencode, claude, …)",
             required: false,
         },
-        task: { type: "string", description: "Optional task hint passed into the reflection prompt" },
-        profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
+        "agent-ref": {
+            type: "positional",
+            description: "Optional agent asset ref (e.g. agent:code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
+            required: false,
+        },
+        prompt: { type: "string", description: "Task prompt to pass to the agent" },
+        command: { type: "string", description: "Load prompt from a command: asset" },
+        workflow: { type: "string", description: "Load prompt from a workflow: asset" },
+        model: {
+            type: "string",
+            description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
+        },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
-            const result = await akmReflect({
-                ref: typeof args.ref === "string" && args.ref.trim() ? args.ref : undefined,
-                task: typeof args.task === "string" && args.task.trim() ? args.task : undefined,
-                profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
+            if (!args.profile) {
+                throw new UsageError("Usage: akm agent <profile> [<agent-ref>] [--prompt <text>] [--model <model>]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in profiles.agent.");
+            }
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const config = loadConfig();
+            const { getDefaultLlmConfig } = await import("./core/config.js");
+            // After 0.8.0 the agent block IS the loaded AkmConfig.
+            const agentConfig = config;
+            // Resolve agent asset ref → extract system prompt, model, and tool policy.
+            const agentRef = getStringArg(args, "agent-ref");
+            let systemPrompt;
+            let assetModel;
+            let assetTools;
+            if (agentRef) {
+                const { akmShowUnified } = await import("./commands/show.js");
+                const asset = await akmShowUnified({ ref: agentRef, detail: "full" });
+                systemPrompt = typeof asset.content === "string" ? asset.content : undefined;
+                assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
+                assetTools = asset.toolPolicy;
+            }
+            // --model flag wins over the asset's modelHint.
+            const model = getStringArg(args, "model") ?? assetModel;
+            const promptText = getStringArg(args, "prompt");
+            const commandRef = getStringArg(args, "command");
+            const workflowRef = getStringArg(args, "workflow");
+            // Only build a dispatch request when there is something to dispatch — a
+            // prompt, an agent asset, or a model override. When none of these are
+            // present the agent is launched interactively (no injected prompt, no
+            // platform-specific flags beyond the profile's base args).
+            const hasDispatchContent = !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
+            const result = await akmAgentDispatch({
+                profileName: String(args.profile),
+                prompt: promptText,
+                commandRef,
+                workflowRef,
+                agentConfig,
+                llmConfig: getDefaultLlmConfig(config),
+                ...(hasDispatchContent
+                    ? {
+                        dispatch: {
+                            prompt: promptText ?? "",
+                            systemPrompt,
+                            model,
+                            tools: assetTools,
+                        },
+                    }
+                    : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });
-            output("reflect", result);
-            if (result.ok === false) {
+            output("agent-result", result);
+            if (!result.ok) {
+                process.exit(EXIT_GENERAL);
+            }
+        });
+    },
+});
+const lintCommand = defineCommand({
+    meta: {
+        name: "lint",
+        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues.",
+    },
+    args: {
+        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        dir: { type: "string", description: "Override stash root directory (default: from config)" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = akmLint({
+                fix: args.fix ?? false,
+                dir: getStringArg(args, "dir"),
+            });
+            output("lint", result);
+            if (!result.ok)
                 process.exit(EXIT_GENERAL);
+        });
+    },
+});
+const improveCommand = defineCommand({
+    meta: {
+        name: "improve",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true",
+    },
+    args: {
+        scope: {
+            type: "positional",
+            description: "Optional asset type or asset ref to improve",
+            required: false,
+        },
+        task: { type: "string", description: "Add extra guidance for this improvement pass" },
+        "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
+        target: { type: "string", description: "Override the write target for accepted proposals" },
+        "auto-accept": {
+            type: "string",
+            description: "Auto-accept proposals at or above this confidence threshold (0-100). Default: disabled. Pass a value 0-100 to enable. 'safe' is an alias for 90. Pass 'false' to be explicit.",
+        },
+        limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
+        "timeout-ms": {
+            type: "string",
+            description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
+        },
+        "ignore-cooldown": {
+            type: "boolean",
+            description: "Ignore all cooldown periods (equivalent to --reflect-cooldown-days 0 --distill-cooldown-days 0 --consolidate-cooldown-days 0)",
+            default: false,
+        },
+        "reflect-cooldown-days": {
+            type: "string",
+            description: "Override reflect cooldown for this run only, applying uniformly to all asset types. Per-type defaults (memory=2d, lesson=7d, workflow/skill/agent/command/knowledge/script/wiki=30d, task=60d) can be configured via profiles.improve.<name>.processes.reflect.cooldownByType. Set 0 to disable.",
+        },
+        "distill-cooldown-days": {
+            type: "string",
+            description: "Override distill cooldown for this run only (default: 1, 0 to disable)",
+        },
+        "consolidate-cooldown-days": {
+            type: "string",
+            description: "Override consolidate cooldown for this run only (default: 14, 0 to disable)",
+        },
+        "consolidate-recovery": {
+            type: "string",
+            description: "How to handle stale/incomplete consolidation journals: abort (default) or clean (remove stale journal artifacts)",
+        },
+        "require-feedback-signal": {
+            type: "boolean",
+            description: "Only process assets with recent feedback signals (disables retrieval fallback)",
+            default: false,
+        },
+        "min-retrieval-count": {
+            type: "string",
+            description: "Minimum retrieval count for zero-feedback fallback eligibility (default: 1, set 0 to include all assets regardless of retrieval history)",
+        },
+        "json-to-stdout": {
+            type: "boolean",
+            description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
+            default: false,
+        },
+        profile: {
+            type: "string",
+            description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus). Controls which sub-processes run and which asset types are processed.",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const formatFlagValue = parseFlagValue(process.argv, "--format");
+            if (formatFlagValue !== undefined) {
+                throw new UsageError(`akm improve does not accept --format. That flag controls output formatting for other commands (search, show, etc.).\n` +
+                    `Did you mean: akm improve (no --format flag)?`, "INVALID_FLAG_VALUE");
+            }
+            const jsonToStdout = getHyphenatedBoolean(args, "json-to-stdout");
+            const autoAcceptRaw = getHyphenatedArg(args, "auto-accept");
+            const autoAccept = parseAutoAcceptFlag(autoAcceptRaw);
+            const targetArg = getStringArg(args, "target");
+            const taskArg = getStringArg(args, "task");
+            const dryRun = getHyphenatedBoolean(args, "dry-run");
+            const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const ignoreCooldown = getHyphenatedBoolean(args, "ignore-cooldown");
+            const reflectCooldownRaw = getHyphenatedArg(args, "reflect-cooldown-days");
+            const reflectCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(reflectCooldownRaw, "--reflect-cooldown-days");
+            const distillCooldownRaw = getHyphenatedArg(args, "distill-cooldown-days");
+            const distillCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(distillCooldownRaw, "--distill-cooldown-days");
+            const consolidateCooldownRaw = getHyphenatedArg(args, "consolidate-cooldown-days");
+            const consolidateCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(consolidateCooldownRaw, "--consolidate-cooldown-days");
+            const consolidateRecoveryRaw = getHyphenatedArg(args, "consolidate-recovery");
+            const consolidateRecovery = consolidateRecoveryRaw === undefined
+                ? undefined
+                : consolidateRecoveryRaw.trim().toLowerCase();
+            if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
+                throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
+            }
+            const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
+            const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
+            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const profileArg = getStringArg(args, "profile");
+            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(improveLogFile);
+            const startedAtMs = Date.now();
+            let improveResult;
+            try {
+                improveResult = await akmImprove({
+                    scope: getStringArg(args, "scope"),
+                    task: taskArg,
+                    dryRun,
+                    target: targetArg,
+                    autoAccept,
+                    ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(reflectCooldownDays !== undefined ? { reflectCooldownDays } : {}),
+                    ...(distillCooldownDays !== undefined ? { distillCooldownDays } : {}),
+                    ...(consolidateCooldownDays !== undefined ? { consolidateCooldownDays } : {}),
+                    ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
+                    ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(profileArg !== undefined ? { profile: profileArg } : {}),
+                    consolidateOptions: {
+                        target: targetArg,
+                        dryRun,
+                        autoAccept,
+                        task: taskArg,
+                        ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
+                    },
+                });
+            }
+            finally {
+                clearLogFile();
             }
+            const durationMs = Date.now() - startedAtMs;
+            if (jsonToStdout) {
+                // Legacy / escape-hatch mode: full JSON on stdout, no file write.
+                // Kept for scripts/agents that already pipe to jq.
+                output("improve", improveResult);
+                process.exit(0);
+            }
+            // Default mode (0.8.0+): persist the full result as a row in the
+            // `improve_runs` table of state.db (migration 003) and emit NOTHING
+            // on stdout. The verbose JSON would otherwise scroll earlier progress
+            // logs out of the terminal buffer. The existing `[improve] ...`
+            // progress log lines on stderr remain the canonical console UX —
+            // do NOT add any new console output here.
+            //
+            // Pre-0.8.0 wrote `<stash>/.akm/runs/<run-id>/improve-result.json`;
+            // those files are no longer authored. Query recent runs with:
+            //   sqlite3 "$AKM_DATA_DIR/state.db" \
+            //     "SELECT id, started_at, ok, dry_run FROM improve_runs \
+            //      ORDER BY started_at DESC LIMIT 10"
+            const runId = buildImproveRunId();
+            const primaryStashDir = resolveSourceEntries(undefined, loadConfig())[0]?.path;
+            const resultRef = relativeImproveResultPath(runId);
+            if (primaryStashDir) {
+                try {
+                    writeImproveResultFile(primaryStashDir, runId, improveResult);
+                }
+                catch (err) {
+                    // Stderr warning on the failure path is preferable to crashing
+                    // the run after all the work has completed.
+                    process.stderr.write(`warning: failed to record improve run ${resultRef}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            else {
+                process.stderr.write(`warning: no writable stash directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
+            }
+            // durationMs reserved for future use (no console emission today).
+            void durationMs;
+            process.exit(0);
         });
     },
 });
@@ -2742,6 +4005,7 @@ const proposeCommand = defineCommand({
         type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
         name: { type: "positional", description: "Asset name (slug or path under the type dir)", required: false },
         task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
         profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
     },
@@ -2750,17 +4014,22 @@ const proposeCommand = defineCommand({
             // citty silently shows help and exits 0 when required positionals are
             // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
             // structured JSON error reaches scripted callers.
-            if (!args.type || !args.name || !args.task) {
-                throw new UsageError("Usage: akm propose <type> <name> --task '<task>'.", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and a --task description, e.g. `akm propose skill deploy --task 'Deploy a service'`.");
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm propose <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
+            }
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
             }
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
             const result = await akmPropose({
                 type: String(args.type),
                 name: String(args.name),
-                task: String(args.task ?? ""),
-                profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
-                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+                task: taskText,
+                profile: getStringArg(args, "profile"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("propose", result);
             if (result.ok === false) {
@@ -2769,6 +4038,207 @@ const proposeCommand = defineCommand({
         });
     },
 });
+const TASKS_SUBCOMMAND_SET = new Set([
+    "add",
+    "list",
+    "show",
+    "remove",
+    "enable",
+    "disable",
+    "run",
+    "history",
+    "sync",
+    "doctor",
+]);
+const GRAPH_SUBCOMMAND_SET = new Set([
+    "summary",
+    "entities",
+    "entity",
+    "relations",
+    "related",
+    "orphans",
+    "export",
+    "update",
+]);
+const tasksAddCommand = defineCommand({
+    meta: { name: "add", description: "Register a new scheduled task and install it in the OS scheduler" },
+    args: {
+        id: { type: "positional", description: "Task id (used as filename and scheduler entry)", required: true },
+        schedule: { type: "string", description: 'Cron-style schedule, e.g. "0 9 * * *" or "@daily"', required: true },
+        workflow: { type: "string", description: "Workflow ref to invoke (e.g. workflow:my-flow)" },
+        prompt: {
+            type: "string",
+            description: "Prompt for the configured agent harness — inline text, an asset ref like agent:foo, or ./path.md",
+        },
+        command: {
+            type: "string",
+            description: 'Shell command to run on the schedule (no AI agent), e.g. "akm improve --auto-accept safe". Split on whitespace; quote the whole flag value.',
+        },
+        profile: { type: "string", description: "Agent profile to use for prompt targets (default: defaults.agent)" },
+        params: { type: "string", description: "Workflow params as a JSON object" },
+        name: { type: "string", description: "Human-readable name for the task" },
+        "when-to-use": { type: "string", description: "Guidance on when this task runs or should be used" },
+        description: { type: "string", description: "Human-readable description" },
+        tags: { type: "string", description: "Comma-separated tags" },
+        disabled: { type: "boolean", description: "Register but leave disabled in the OS scheduler", default: false },
+        force: { type: "boolean", description: "Overwrite an existing task with the same id", default: false },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksAdd({
+                id: args.id,
+                schedule: args.schedule,
+                workflow: args.workflow,
+                prompt: args.prompt,
+                command: args.command,
+                profile: args.profile,
+                params: args.params,
+                name: args.name,
+                when_to_use: getHyphenatedArg(args, "when-to-use"),
+                description: args.description,
+                tags: args.tags
+                    ? args.tags
+                        .split(/[\s,]+/)
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : undefined,
+                disabled: args.disabled === true,
+                force: args.force === true,
+            });
+            output("tasks-add", result);
+        });
+    },
+});
+const tasksListCommand = defineCommand({
+    meta: { name: "list", description: "List scheduled tasks in the stash" },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});
+const tasksShowCommand = defineCommand({
+    meta: { name: "show", description: "Show a parsed task definition" },
+    args: { id: { type: "positional", description: "Task id or task:<id>", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksShow(id);
+            output("tasks-show", result);
+        });
+    },
+});
+const tasksRemoveCommand = defineCommand({
+    meta: { name: "remove", description: "Delete a task file and uninstall it from the OS scheduler" },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksRemove(id);
+            output("tasks-remove", result);
+        });
+    },
+});
+function makeTasksToggleCommand(enabled) {
+    const verb = enabled ? "enable" : "disable";
+    const description = enabled
+        ? "Enable a previously-disabled task"
+        : "Disable a task in the OS scheduler without removing the file";
+    return defineCommand({
+        meta: { name: verb, description },
+        args: { id: { type: "positional", description: "Task id", required: true } },
+        async run({ args }) {
+            await runWithJsonErrors(async () => {
+                const { id } = parseTaskRef(args.id);
+                const result = await akmTasksSetEnabled(id, enabled);
+                output(`tasks-${verb}`, result);
+            });
+        },
+    });
+}
+const tasksEnableCommand = makeTasksToggleCommand(true);
+const tasksDisableCommand = makeTasksToggleCommand(false);
+const tasksRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Execute a task now (this is what cron / launchd / schtasks invoke at the scheduled time)",
+    },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const envelope = await akmTasksRun(id);
+            output("tasks-run", envelope);
+            if (envelope.exitCode !== 0)
+                process.exit(envelope.exitCode);
+        });
+    },
+});
+const tasksHistoryCommand = defineCommand({
+    meta: { name: "history", description: "Show recent task run history" },
+    args: {
+        id: { type: "string", description: "Filter to one task id" },
+        limit: { type: "string", description: "Maximum rows to return (default 50)" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const limit = parsePositiveIntFlag(args.limit ?? undefined);
+            const result = await akmTasksHistory({ id: args.id, limit });
+            output("tasks-history", result);
+        });
+    },
+});
+const tasksSyncCommand = defineCommand({
+    meta: {
+        name: "sync",
+        description: "Reconcile the on-disk task files with the OS scheduler",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksSync();
+            output("tasks-sync", result);
+        });
+    },
+});
+const tasksDoctorCommand = defineCommand({
+    meta: {
+        name: "doctor",
+        description: "Report the active scheduler backend, akm bin path, log dir, and supported schedule subset",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksDoctor();
+            output("tasks-doctor", result);
+        });
+    },
+});
+const tasksCommand = defineCommand({
+    meta: {
+        name: "tasks",
+        description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
+    },
+    subCommands: {
+        add: tasksAddCommand,
+        list: tasksListCommand,
+        show: tasksShowCommand,
+        remove: tasksRemoveCommand,
+        enable: tasksEnableCommand,
+        disable: tasksDisableCommand,
+        run: tasksRunCommand,
+        history: tasksHistoryCommand,
+        sync: tasksSyncCommand,
+        doctor: tasksDoctorCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
+                return;
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -2777,8 +4247,21 @@ const main = defineCommand({
     },
     args: {
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)", default: "json" },
-        detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)", default: "brief" },
-        quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
+        detail: {
+            type: "string",
+            description: "Detail level. Stable: brief|normal|full. Experimental: summary|agent " +
+                "(supported on a subset of commands; coverage will expand or these will be replaced — " +
+                "see STABILITY.md). Default: brief.",
+            default: "brief",
+        },
+        quiet: {
+            type: "boolean",
+            alias: "q",
+            description: "Suppress non-essential stderr output (banners, spinners, progress info). " +
+                "Safety-critical output is never suppressed: errors, destructive-action confirmation prompts, " +
+                "and auto-migration banners always appear regardless of --quiet.",
+            default: false,
+        },
         verbose: {
             type: "boolean",
             description: "Print per-spec diagnostics to stderr (also honours AKM_VERBOSE env var)",
@@ -2789,7 +4272,10 @@ const main = defineCommand({
         setup: setupCommand,
         init: initCommand,
         index: indexCommand,
+        health: healthCommand,
         info: infoCommand,
+        graph: graphCommand,
+        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -2810,18 +4296,25 @@ const main = defineCommand({
         feedback: feedbackCommand,
         history: historyCommand,
         events: eventsCommand,
-        proposal: proposalCommand,
-        reflect: reflectCommand,
+        lessons: lessonsCommand,
+        agent: agentCommand,
+        lint: lintCommand,
+        improve: improveCommand,
         propose: proposeCommand,
-        distill: distillCommand,
+        proposals: proposalsCommand,
+        accept: acceptCommand,
+        reject: rejectCommand,
+        diff: diffCommand,
+        revert: revertCommand,
         help: helpCommand,
         hints: hintsCommand,
         completions: completionsCommand,
         vault: vaultCommand,
         wiki: wikiCommand,
+        tasks: tasksCommand,
     },
 });
-const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
+const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset"]);
 const VAULT_SUBCOMMAND_SET = new Set(["list", "path", "run", "create", "set", "unset"]);
 const WIKI_SUBCOMMAND_SET = new Set([
     "create",
@@ -2835,10 +4328,13 @@ const WIKI_SUBCOMMAND_SET = new Set([
     "lint",
     "ingest",
 ]);
-const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
 // ── Exit codes ──────────────────────────────────────────────────────────────
 const EXIT_GENERAL = 1;
 const EXIT_USAGE = 2;
+/** `akm health` warn status — emitted when overall status is "warn" (advisories
+ *  fired but no hard failure). Chosen as 4 to avoid colliding with EXIT_GENERAL
+ *  (1 / fail) and EXIT_USAGE (2). CI monitors can map: 0=pass, 4=warn, 1=fail. */
+const EXIT_HEALTH_WARN = 4;
 const EXIT_CONFIG = 78;
 // citty reads process.argv directly and does not accept a custom argv array,
 // so we must replace process.argv with the normalized version before runMain.
@@ -2849,18 +4345,52 @@ process.argv = normalizeShowArgv(process.argv);
 // invalid; surface it through the same JSON-error path the rest of the CLI uses
 // rather than letting the raw exception escape with a stack trace.
 try {
+    applyEarlyStderrFlags(process.argv);
     initOutputMode(process.argv, loadConfig().output ?? {});
 }
 catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const hint = extractHint(error);
-    const exitCode = classifyExitCode(error);
-    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-        ? error.code
-        : undefined;
-    console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
-    process.exit(exitCode);
+    emitJsonError(error);
 }
+// One-time cleanup of stale 0.7.x index file at the old cache location.
+// 0.8.0 moved the index to $XDG_DATA_HOME/akm/index.db (getDataDir()).
+// If the old file exists at $XDG_CACHE_HOME/akm/index.db, remove it so the
+// user isn't confused by a phantom DB. Best-effort; never fatal.
+try {
+    const oldIndexPath = path.join(getCacheDir(), "index.db");
+    if (fs.existsSync(oldIndexPath)) {
+        fs.rmSync(oldIndexPath, { force: true });
+        fs.rmSync(`${oldIndexPath}-shm`, { force: true });
+        fs.rmSync(`${oldIndexPath}-wal`, { force: true });
+        warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
+    }
+}
+catch {
+    // Non-fatal; one-time warning only.
+}
+// First-time-user breadcrumb: when run with no subcommand AND no config
+// exists yet AND stderr is a TTY, print a friendly pointer to `akm setup`
+// above citty's auto-generated usage block. Triggers only when stdin/stderr
+// are interactive (so JSON-output users / CI consumers see nothing extra)
+// and stays silent for any flag-only invocation citty would handle itself
+// (--help, --version).
+(function maybePrintFirstTimeBanner() {
+    const argv = process.argv.slice(2);
+    // Fire only on completely bare `akm` invocation. Any explicit flag or
+    // subcommand means the user knows what they want.
+    if (argv.length > 0)
+        return;
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        if (fs.existsSync(getConfigPath()))
+            return;
+    }
+    catch {
+        // If we can't resolve the config path, assume non-fresh and stay silent.
+        return;
+    }
+    console.error("👋 First time with akm? Run `akm setup` to get started.\n" + "   Docs: https://github.com/itlackey/akm#readme\n");
+})();
 runMain(main);
 function classifyExitCode(error) {
     if (error instanceof UsageError)
@@ -2871,33 +4401,6 @@ function classifyExitCode(error) {
         return EXIT_GENERAL;
     return EXIT_GENERAL;
 }
-async function runWithJsonErrors(fn) {
-    try {
-        // Apply --quiet flag early so warnings inside the command are suppressed
-        if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
-            setQuiet(true);
-        }
-        // Apply --verbose flag early so per-spec diagnostics (gated behind
-        // `isVerbose()` in src/core/warn.ts) are restored. The `AKM_VERBOSE`
-        // env var still wins regardless — see warn.ts for the precedence rule.
-        if (process.argv.includes("--verbose")) {
-            setVerbose(true);
-        }
-        await fn();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        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.
-        const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-            ? error.code
-            : undefined;
-        console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
-        process.exit(exitCode);
-    }
-}
 /**
  * Extract an actionable hint from an error instance. Hints live on the error
  * classes themselves (see src/errors.ts) — either supplied explicitly at the
@@ -2909,86 +4412,27 @@ function extractHint(error) {
     }
     return undefined;
 }
-function hasConfigSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command);
-}
-function hasVaultSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && VAULT_SUBCOMMAND_SET.has(command);
-}
-function hasWikiSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && WIKI_SUBCOMMAND_SET.has(command);
-}
 /**
- * Normalize argv so positional view-mode arguments after the asset ref
- * are rewritten into internal flags that citty can parse.
- *
- * Converts:
- *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --akmView toc
- *   akm show knowledge:guide.md section Auth → akm show knowledge:guide.md --akmView section --akmHeading Auth
- *   akm show knowledge:guide.md lines 1 50   → akm show knowledge:guide.md --akmView lines --akmStart 1 --akmEnd 50
- *
- * Legacy `--view` is intentionally unsupported.
- * Returns a new array; the input is never modified.
+ * Serialize an error to the standard JSON envelope and exit.
+ * Used in both the startup try/catch and `runWithJsonErrors`.
  */
-function normalizeShowArgv(argv) {
-    // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
-    if (argv[2] !== "show")
-        return argv;
-    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
-        throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
-    }
-    // Separate global flags from positional/show-specific args
-    const prefix = argv.slice(0, 3); // [bun, script, show]
-    const rest = argv.slice(3);
-    const globalFlags = [];
-    const showArgs = [];
-    for (let i = 0; i < rest.length; i++) {
-        const arg = rest[i];
-        if (arg === "--quiet" || arg === "-q" || arg === "--for-agent" || arg === "--for-agent=true") {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg === "--format" || arg === "--detail") {
-            globalFlags.push(arg);
-            if (rest[i + 1] !== undefined) {
-                globalFlags.push(rest[i + 1]);
-                i++;
-            }
-            continue;
-        }
-        showArgs.push(arg);
-    }
-    // showArgs[0] = ref, showArgs[1] = potential view mode, showArgs[2..] = view params
-    const ref = showArgs[0];
-    const viewMode = showArgs[1];
-    if (!ref || !viewMode || !SHOW_VIEW_MODES.has(viewMode)) {
-        return argv;
-    }
-    const result = [...prefix, ref, "--akmView", viewMode];
-    if (viewMode === "section") {
-        // Next arg is the heading name; pass empty string when missing so the
-        // show handler can produce a clear "section not found" error.
-        const heading = showArgs[2] ?? "";
-        result.push("--akmHeading", heading);
+function emitJsonError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const hint = extractHint(error);
+    const exitCode = classifyExitCode(error);
+    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
+        ? error.code
+        : undefined;
+    console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
+    process.exit(exitCode);
+}
+async function runWithJsonErrors(fn) {
+    try {
+        await fn();
     }
-    else if (viewMode === "lines") {
-        // Next two args are start and end
-        const start = showArgs[2];
-        const end = showArgs[3];
-        if (start)
-            result.push("--akmStart", start);
-        if (end)
-            result.push("--akmEnd", end);
+    catch (error) {
+        emitJsonError(error);
     }
-    result.push(...globalFlags);
-    return result;
 }
 // ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
 function loadHints(detail = "normal") {