akm-cli 0.8.0-rc2 → 0.8.1

package/dist/cli.js

@@ -1,56 +1,123 @@
 #!/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);
+}
+// Global error handlers (#478) — route any async work outside the
+// `runWithJsonErrors` envelope through the same JSON shape so users never see
+// a raw stack trace. Background timers, fire-and-forget appendEvent writes,
+// and lazy `import()` failures are the typical sources. Registered before
+// any other top-level work so the startup IIFE banner and the stale-DB
+// cleanup are also covered.
+process.on("unhandledRejection", (reason) => {
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    console.error(JSON.stringify({
+        ok: false,
+        error: `Unhandled rejection: ${err.message}`,
+        code: "UNHANDLED_REJECTION",
+        hint: "Re-run with AKM_DEBUG=1 for a stack trace, or report at https://github.com/itlackey/akm/issues with the failing command.",
+    }, null, 2));
+    if (process.env.AKM_DEBUG === "1" && err.stack)
+        console.error(err.stack);
+    process.exit(1);
+});
+process.on("uncaughtException", (err) => {
+    console.error(JSON.stringify({
+        ok: false,
+        error: `Uncaught exception: ${err.message}`,
+        code: "UNCAUGHT_EXCEPTION",
+        hint: "Re-run with AKM_DEBUG=1 for a stack trace, or report at https://github.com/itlackey/akm/issues with the failing command.",
+    }, null, 2));
+    if (process.env.AKM_DEBUG === "1" && err.stack)
+        console.error(err.stack);
+    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 { hasSubcommand, parsePositiveIntFlag } from "./cli/parse-args";
+import { getStringArg, hasSubcommand, parsePositiveIntFlag } from "./cli/parse-args";
+import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared";
+import { addCommand, buildWebsiteOptions } from "./commands/add-cli";
 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 { akmDbBackups } from "./commands/db-cli";
 import { akmEventsList, akmEventsTail } from "./commands/events";
-import { akmGraphEntities, akmGraphExport, akmGraphRelated, akmGraphRelations, akmGraphSummary, } from "./commands/graph";
-import { akmHealth } from "./commands/health";
+import { extractCommand } from "./commands/extract-cli";
+import { feedbackCommand } from "./commands/feedback-cli";
+import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./commands/graph";
+import { akmHealth, parseWindowSpec, renderRunsDetailMd, renderWindowCompareMd, } from "./commands/health";
 import { akmHistory } from "./commands/history";
-import { akmImprove } from "./commands/improve";
+import { improveCommand } from "./commands/improve-cli";
 import { assembleInfo } from "./commands/info";
 import { akmInit } from "./commands/init";
 import { akmListSources, akmRemove, akmUpdate } from "./commands/installed-stashes";
 import { 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";
+import { registryCommand } from "./commands/registry-cli";
+import { rememberCommand } from "./commands/remember-cli";
+/**
+ * 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 { resolveImproveProfile } from "./commands/improve-profiles";
+import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalRevert, akmProposalShow, } from "./commands/proposal";
+import { drainProposals } from "./commands/proposal-drain";
+import { resolveDrainPolicy } from "./commands/proposal-drain-policies";
 import { akmPropose } from "./commands/propose";
-import { searchRegistry } from "./commands/registry-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, 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 { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset-spec";
-import { isHttpUrl, resolveStashDir } from "./core/common";
+import { isHttpUrl, isWithin, resolveStashDir, writeFileAtomic } from "./core/common";
 import { DEFAULT_CONFIG, loadConfig, loadUserConfig, resolveConfiguredSources, saveConfig } from "./core/config";
 import { ConfigError, NotFoundError, UsageError } from "./core/errors";
 import { appendEvent } from "./core/events";
 import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "./core/paths";
-import { clearLogFile, info, setLogFile, setQuiet, setVerbose, warn } from "./core/warn";
-import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
-import { ensureIndex } from "./indexer/ensure-index";
+import { plainize } from "./core/tty";
+import { clearLogFile, info, isQuiet, isVerbose, setLogFile, setQuiet, setVerbose, warn } from "./core/warn";
+import { closeDatabase, openExistingDatabase } from "./indexer/db";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
-import { insertUsageEvent } from "./indexer/usage-events";
+import { resolveTriageJudgmentRunner } from "./integrations/agent/runner";
 import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints";
-import { getHyphenatedArg, getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue, } from "./output/context";
-import { shapeForCommand } from "./output/shapes";
-import { formatEventLine, formatPlain, outputJsonl } from "./output/text";
-import { buildRegistryIndex, writeRegistryIndex } from "./registry/build-index";
+import { getHyphenatedArg, getHyphenatedBoolean, getOutputMode, hasBooleanFlag, initOutputMode, parseDetailLevel, parseFlagValue, } from "./output/context";
+import { formatEventLine } from "./output/text";
 import { resolveSourcesForOrigin } from "./registry/origin-resolve";
-import { saveGitStash } from "./sources/providers/git";
+import { resolveWritableOverride, saveGitStash } from "./sources/providers/git";
 import { resolveAssetPath } from "./sources/resolve";
 import { pkgVersion } from "./version";
 import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "./workflows/authoring";
@@ -59,7 +126,6 @@ import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkf
 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);
@@ -68,29 +134,6 @@ function applyEarlyStderrFlags(argv) {
         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,
- * so for repeatable CLI args (like `--tag foo --tag bar`) we read argv directly.
- * Supports both `--flag value` and `--flag=value` forms.
- */
-function parseAllFlagValues(flag) {
-    const values = [];
-    for (let i = 0; i < process.argv.length; i++) {
-        const arg = process.argv[i];
-        if (arg === flag && i + 1 < process.argv.length) {
-            values.push(process.argv[i + 1]);
-            // BUG-M4: skip the value index so `--tag --tag` (literal `--tag`
-            // value) does not double-count the second `--tag` as a separate
-            // flag occurrence.
-            i++;
-        }
-        else if (arg.startsWith(`${flag}=`)) {
-            values.push(arg.slice(flag.length + 1));
-        }
-    }
-    return values;
-}
 function resolveHelpMigrateVersionArg(version) {
     if (version === undefined)
         return undefined;
@@ -128,26 +171,29 @@ function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName)
         return false;
     return relevant[flagIndex] === flagName ? relevant[flagIndex + 1] === version : true;
 }
-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();
-    const shaped = shapeForCommand(command, result, mode.detail, mode.forAgent);
-    if (mode.format === "jsonl") {
-        outputJsonl(command, shaped);
+    if (mode.format !== "json" && mode.format !== "jsonl")
         return;
-    }
-    switch (mode.format) {
-        case "json":
-            console.log(JSON.stringify(shaped, null, 2));
-            return;
-        case "yaml":
-            console.log(yamlStringify(shaped));
-            return;
-        case "text": {
-            const plain = formatPlain(command, shaped, mode.detail);
-            console.log(plain ?? JSON.stringify(shaped, null, 2));
-            return;
-        }
-    }
+    if (isQuiet())
+        return;
+    if (!result?.stashDir)
+        return;
+    console.error(plainize(`\n✓ Stash created at ${result.stashDir}\n` +
+        `  Next: \`akm add github:itlackey/akm-stash\` then \`akm index\` to populate the stash.`));
 }
 /**
  * Module Naming:
@@ -166,6 +212,10 @@ const setupCommand = defineCommand({
             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,
@@ -184,7 +234,26 @@ const setupCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const noInit = getHyphenatedBoolean(args, "no-init");
-            if (args.config) {
+            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({
@@ -194,6 +263,7 @@ const setupCommand = defineCommand({
                     probe: args.probe,
                 });
                 output("setup", result);
+                printSetupTtyHint(result);
             }
             else if (args.yes) {
                 // Defaults mode — no prompts
@@ -204,6 +274,7 @@ const setupCommand = defineCommand({
                     probe: args.probe,
                 });
                 output("setup", result);
+                printSetupTtyHint(result);
             }
             else {
                 // Interactive wizard
@@ -235,7 +306,16 @@ 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 },
-        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 () => {
@@ -252,7 +332,8 @@ const indexCommand = defineCommand({
             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;
+            const verbose = isVerbose();
+            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
             }
@@ -260,10 +341,12 @@ const indexCommand = defineCommand({
             try {
                 const result = await akmIndex({
                     full: args.full,
+                    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) {
+                        if (verbose) {
                             info(`[index:${phase}] ${progressPrefix}${message}`);
                         }
                         else if (spin) {
@@ -293,7 +376,7 @@ const indexCommand = defineCommand({
     },
 });
 const infoCommand = defineCommand({
-    meta: { name: "info", description: "Show system capabilities, configuration, and index stats as JSON" },
+    meta: { name: "info", description: "Show system capabilities, configuration, and index stats" },
     run() {
         return runWithJsonErrors(() => {
             const result = assembleInfo();
@@ -308,12 +391,83 @@ const healthCommand = defineCommand({
             type: "string",
             description: "Rolling window start (ISO timestamp, date, epoch ms, or shorthand like 24h / 7d)",
         },
+        "group-by": {
+            type: "string",
+            description: "Group rows by: run (one row per improve_runs entry). Omit for the default summary.",
+        },
+        detail: {
+            type: "string",
+            description: "DEPRECATED: use --group-by run instead of --detail per-run (removed 0.9.0).",
+        },
+        "window-compare": {
+            type: "string",
+            description: "Compare current window vs prior window of the same duration (e.g. 24h, 7d, 30m)",
+        },
+        windows: {
+            type: "string",
+            description: "Explicit comparison window 'name=...,since=ISO,until=ISO' (repeatable, up to 4; mutually exclusive with --window-compare)",
+        },
     },
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = akmHealth({ since: args.since });
-            output("health", result);
+    async run({ args }) {
+        let resultStatus;
+        await runWithJsonErrors(() => {
+            // citty only surfaces the last value of a repeated flag, so read --windows
+            // directly from argv to support multi-window comparison.
+            const rawWindows = parseAllFlagValues("--windows");
+            const windows = rawWindows.length > 0 ? rawWindows.map((raw) => parseWindowSpec(raw)) : undefined;
+            const groupByRaw = args["group-by"];
+            const detailRaw = args.detail;
+            // Back-compat: `--detail per-run` → `--group-by run` (warns; removed 0.9.0).
+            let groupBy = groupByRaw;
+            if (detailRaw !== undefined) {
+                if (detailRaw === "per-run") {
+                    // Read --quiet from argv (not the warn-module singleton) so the
+                    // warning fires correctly even when the early-stderr flags were not
+                    // applied (e.g. the in-process test harness), matching the WS2
+                    // output-flag deprecations in src/output/context.ts.
+                    const quietRequested = process.argv.includes("--quiet") || process.argv.includes("-q");
+                    if (!quietRequested) {
+                        process.stderr.write("warning: '--detail per-run' is deprecated for 'akm health'; use '--group-by run'. Removed in 0.9.0.\n");
+                    }
+                    groupBy = groupBy ?? "run";
+                }
+                else {
+                    throw new UsageError(`Invalid value for --detail: ${detailRaw}. 'akm health' uses --group-by run (not --detail).`, "INVALID_DETAIL_VALUE");
+                }
+            }
+            const windowCompareRaw = args["window-compare"];
+            const result = akmHealth({
+                since: args.since,
+                groupBy: groupBy,
+                windowCompare: windowCompareRaw,
+                windows,
+            });
+            resultStatus = result.status;
+            // `--format md` is health-specific: render a TSV-shaped per-run or
+            // window-compare table to stdout instead of going through the JSON
+            // envelope. Other modes fall through to the standard output() path.
+            const mode = getOutputMode();
+            if (mode.format === "md") {
+                if (result.windows && result.windows.length > 0) {
+                    console.log(renderWindowCompareMd(result.windows, result.deltas));
+                }
+                else if (result.runs) {
+                    console.log(renderRunsDetailMd(result.runs));
+                }
+                else {
+                    output("health", result);
+                }
+            }
+            else {
+                output("health", result);
+            }
         });
+        if (resultStatus === "fail") {
+            process.exit(EXIT_GENERAL);
+        }
+        if (resultStatus === "warn") {
+            process.exit(EXIT_HEALTH_WARN);
+        }
     },
 });
 const graphCommand = defineCommand({
@@ -371,6 +525,35 @@ const graphCommand = defineCommand({
                 });
             },
         }),
+        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: {
@@ -388,6 +571,25 @@ const graphCommand = defineCommand({
                 });
             },
         }),
+        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(() => {
@@ -397,6 +599,36 @@ const graphCommand = defineCommand({
         });
     },
 });
+// 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: {
@@ -422,7 +654,12 @@ const searchCommand = defineCommand({
             default: "all",
         },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        "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 () => {
@@ -439,7 +676,21 @@ const searchCommand = defineCommand({
             const filters = parseScopeFilterFlags(filterTokens, "--filter");
             const includeProposed = args["include-proposed"] === true;
             const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
-            const result = await akmSearch({ query, type, limit, source, filters, includeProposed, belief });
+            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);
         });
     },
@@ -457,6 +708,12 @@ const curateCommand = defineCommand({
         },
         limit: { type: "string", description: "Maximum number of curated results", default: "4" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+        // Output-contract flags. The active values are read from the process-level
+        // singleton (parsed from argv at startup); these declarations make them
+        // visible in `akm curate --help` and document the supported axes.
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        shape: { type: "string", description: "Output projection (human|agent)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -472,137 +729,6 @@ const curateCommand = defineCommand({
         });
     },
 });
-const addCommand = defineCommand({
-    meta: {
-        name: "add",
-        description: "Add a source (local directory, website, npm package, GitHub repo, git URL, or remote provider)",
-    },
-    args: {
-        ref: {
-            type: "positional",
-            description: "Path, URL, or registry ref (website URL, npm package, owner/repo, git URL, or local directory)",
-            required: true,
-        },
-        provider: { type: "string", description: "Provider type (e.g. website, npm). Required for URL sources." },
-        options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
-        name: { type: "string", description: "Human-friendly name for the source" },
-        writable: {
-            type: "boolean",
-            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)",
-        },
-        "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)" },
-        "allow-insecure": {
-            type: "boolean",
-            description: "Allow a plain HTTP source URL (otherwise rejected for non-localhost hosts)",
-            default: false,
-        },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const ref = args.ref.trim();
-            const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
-            // URL with --provider → stash source (remote or git provider)
-            if (args.provider) {
-                if (shouldWarnOnPlainHttp(ref)) {
-                    if (!allowInsecure) {
-                        throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
-                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
-                    }
-                    warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
-                }
-                let parsedOptions;
-                if (args.options) {
-                    try {
-                        const parsed = JSON.parse(args.options);
-                        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                            throw new UsageError("--options must be a JSON object");
-                        }
-                        parsedOptions = parsed;
-                    }
-                    catch (err) {
-                        if (err instanceof UsageError)
-                            throw err;
-                        throw new UsageError("--options must be valid JSON");
-                    }
-                }
-                const result = addStash({
-                    target: ref,
-                    name: args.name,
-                    providerType: args.provider,
-                    options: parsedOptions,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
-            }
-            if (shouldWarnOnPlainHttp(ref)) {
-                if (!allowInsecure) {
-                    throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
-                        "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
-                }
-                warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
-            }
-            const websiteOptions = buildWebsiteOptions(args);
-            if (args.type === "wiki") {
-                const { registerWikiSource } = await import("./commands/source-add");
-                const result = await registerWikiSource({
-                    ref,
-                    name: args.name,
-                    options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                    trustThisInstall: args.trust,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
-            }
-            const result = await akmAdd({
-                ref,
-                name: args.name,
-                overrideType: args.type,
-                options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                trustThisInstall: args.trust,
-                writable: args.writable,
-            });
-            appendEvent({
-                eventType: "add",
-                metadata: {
-                    target: ref,
-                    name: args.name ?? null,
-                    overrideType: args.type ?? null,
-                    writable: args.writable === true,
-                },
-            });
-            output("add", result);
-        });
-    },
-});
-function buildWebsiteOptions(args) {
-    const websiteOptions = {};
-    if (typeof args["max-pages"] === "string" && args["max-pages"].length > 0)
-        websiteOptions.maxPages = args["max-pages"];
-    if (typeof args["max-depth"] === "string" && args["max-depth"].length > 0)
-        websiteOptions.maxDepth = args["max-depth"];
-    return websiteOptions;
-}
 const VALID_SOURCE_KINDS = new Set(["local", "managed", "remote"]);
 function parseKindFilter(raw) {
     if (!raw)
@@ -615,22 +741,6 @@ function parseKindFilter(raw) {
     }
     return kinds;
 }
-function shouldWarnOnPlainHttp(ref) {
-    if (!ref.startsWith("http://"))
-        return false;
-    try {
-        const hostname = new URL(ref).hostname.toLowerCase();
-        return (hostname !== "localhost" &&
-            hostname !== "127.0.0.1" &&
-            hostname !== "0.0.0.0" &&
-            hostname !== "::1" &&
-            hostname !== "[::1]" &&
-            !hostname.endsWith(".localhost"));
-    }
-    catch {
-        return true;
-    }
-}
 const listCommand = defineCommand({
     meta: { name: "list", description: "List all sources (local directories, managed packages, remote providers)" },
     args: {
@@ -648,9 +758,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",
@@ -731,7 +850,8 @@ const showCommand = defineCommand({
             required: true,
         },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
+        detail: { type: "string", description: "Detail level (brief|normal|full)" },
+        shape: { type: "string", description: "Output projection (human|agent|summary)" },
         scope: {
             type: "string",
             description: "Scope filter (repeatable): --scope user=<id> --scope agent=<id> --scope run=<id> --scope channel=<name>. Narrows resolution to assets whose frontmatter scope matches.",
@@ -741,9 +861,12 @@ const showCommand = defineCommand({
         await runWithJsonErrors(async () => {
             const subcommand = Array.isArray(args._) ? args._[0] : undefined;
             if (subcommand === "proposal") {
+                if (!isQuiet()) {
+                    process.stderr.write("warning: 'akm show proposal <id>' is deprecated and will be removed in 0.9.0. Use 'akm proposal show <id>'.\n");
+                }
                 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 new UsageError("Usage: akm proposal show <id>", "MISSING_REQUIRED_ARGUMENT");
                 }
                 const result = akmProposalShow({ id: proposalId.trim() });
                 output("proposal-show", result);
@@ -781,14 +904,24 @@ const showCommand = defineCommand({
                         throw new UsageError(`Unknown view mode: ${akmView}. Expected one of: full|toc|frontmatter|section|lines`);
                 }
             }
-            const cliDetail = getOutputMode().detail;
+            const cliShape = getOutputMode().shape;
             const explicitDetail = parseFlagValue(process.argv, "--detail");
-            const showDetail = explicitDetail === "brief" ? "brief" : cliDetail === "summary" ? "summary" : undefined;
+            // `--shape summary` selects the compact metadata projection for show
+            // (the legacy `--detail summary` spelling still maps here via the
+            // back-compat path in resolveOutputMode). `--detail brief` forces the
+            // brief response regardless of shape.
+            const showDetail = explicitDetail === "brief" ? "brief" : cliShape === "summary" ? "summary" : undefined;
             // `--scope` is repeatable — citty only exposes the last value, so read
             // 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);
         });
     },
@@ -862,12 +995,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));
+                    }
                 });
             },
         }),
@@ -875,12 +1032,83 @@ 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"]) });
+                });
+            },
+        }),
+        enable: defineCommand({
+            meta: { name: "enable", description: "Enable an optional component (skills.sh)" },
+            args: {
+                target: { type: "positional", description: "Component to enable (skills.sh)", required: true },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const result = toggleComponent(args.target, true);
+                    output("enable", result);
+                });
+            },
+        }),
+        disable: defineCommand({
+            meta: { name: "disable", description: "Disable an optional component (skills.sh)" },
+            args: {
+                target: { type: "positional", description: "Component to disable (skills.sh)", required: true },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    const result = toggleComponent(args.target, false);
+                    output("disable", result);
                 });
             },
         }),
@@ -897,15 +1125,51 @@ const configCommand = defineCommand({
         });
     },
 });
-const saveCommand = defineCommand({
+// Shared `save`/`sync` body. `sync` is the canonical spelling in 0.8; `save`
+// remains a deprecated alias (removed 0.9.0). Both share this implementation so
+// the git-commit/push logic and the `--format`-as-name workaround stay in one place.
+async function runSyncBody(args, verb) {
+    await runWithJsonErrors(async () => {
+        // Fix: citty can consume `--format json` (space-separated) as the
+        // positional `name` argument (e.g. `akm sync --format json` parses
+        // name="json"). Detect the mis-parse by checking argv order — only
+        // treat the positional as consumed by --format when --format appears
+        // before any standalone occurrence of the same value in the sync
+        // subcommand's argv slice. This preserves legitimate invocations
+        // like `akm sync json --format json`.
+        const parsedFormat = parseFlagValue(process.argv, "--format");
+        const effectiveName = args.name !== undefined &&
+            parsedFormat !== undefined &&
+            args.name === parsedFormat &&
+            wasFormatValueConsumedAsName(args.name, parsedFormat, verb)
+            ? undefined
+            : args.name;
+        let writable;
+        if (effectiveName === undefined) {
+            // Primary stash — honour the root-level writable flag from config.
+            writable = resolveWritableOverride(loadConfig());
+        }
+        const result = saveGitStash(effectiveName, args.message, writable, { push: args.push !== false });
+        appendEvent({
+            eventType: "save",
+            metadata: {
+                name: effectiveName ?? null,
+                message: args.message ?? null,
+                ok: result.ok !== false,
+            },
+        });
+        output("save", result);
+    });
+}
+const syncCommand = defineCommand({
     meta: {
-        name: "save",
-        description: "Save changes in a git-backed stash: commits (and pushes when writable + remote is configured). No-op for non-git stashes.",
+        name: "sync",
+        description: "Sync changes in a git-backed stash: commits (and pushes when writable + remote is configured). No-op for non-git stashes.",
     },
     args: {
         name: {
             type: "positional",
-            description: "Name of the git stash to save (default: primary stash directory)",
+            description: "Name of the git stash to sync (default: primary stash directory)",
             required: false,
         },
         message: {
@@ -913,56 +1177,59 @@ const saveCommand = defineCommand({
             alias: "m",
             description: "Commit message (default: timestamp)",
         },
+        push: {
+            type: "boolean",
+            description: "Push after commit when writable + remote configured (use --no-push to commit only). Default: true.",
+            default: true,
+        },
     },
     async run({ args }) {
-        await runWithJsonErrors(async () => {
-            // Fix: citty can consume `--format json` (space-separated) as the
-            // positional `name` argument (e.g. `akm save --format json` parses
-            // name="json"). Detect the mis-parse by checking argv order — only
-            // treat the positional as consumed by --format when --format appears
-            // before any standalone occurrence of the same value in the save
-            // subcommand's argv slice. This preserves legitimate invocations
-            // like `akm save json --format json`.
-            const parsedFormat = parseFlagValue(process.argv, "--format");
-            const effectiveName = args.name !== undefined &&
-                parsedFormat !== undefined &&
-                args.name === parsedFormat &&
-                wasFormatValueConsumedAsName(args.name, parsedFormat)
-                ? undefined
-                : args.name;
-            let writable;
-            if (effectiveName === undefined) {
-                // Primary stash — honour the root-level writable flag from config.
-                const cfg = loadConfig();
-                writable = cfg.writable === true ? true : undefined;
-            }
-            const result = saveGitStash(effectiveName, args.message, writable);
-            appendEvent({
-                eventType: "save",
-                metadata: {
-                    name: effectiveName ?? null,
-                    message: args.message ?? null,
-                    ok: result.ok !== false,
-                },
-            });
-            output("save", result);
-        });
+        await runSyncBody(args, "sync");
     },
 });
-/**
- * Detect whether `--format <value>` was consumed by citty as the optional
- * `name` positional of `akm save`. Returns true only when `--format` appears
- * in the save subcommand's argv slice AND the candidate name does NOT
- * appear as a standalone positional elsewhere (before or after the flag).
+// Deprecated alias (removed 0.9.0): `akm save` → `akm sync`.
+const saveCommand = defineCommand({
+    meta: {
+        name: "save",
+        description: "DEPRECATED — use `akm sync`. Removed in 0.9.0.",
+    },
+    args: {
+        name: {
+            type: "positional",
+            description: "Name of the git stash to save (default: primary stash directory)",
+            required: false,
+        },
+        message: {
+            type: "string",
+            alias: "m",
+            description: "Commit message (default: timestamp)",
+        },
+        push: {
+            type: "boolean",
+            description: "Push after commit when writable + remote configured (use --no-push to commit only). Default: true.",
+            default: true,
+        },
+    },
+    async run({ args }) {
+        emitCommandDeprecation("save", "sync");
+        await runSyncBody(args, "save");
+    },
+});
+/**
+ * Detect whether `--format <value>` was consumed by citty as the optional
+ * `name` positional of `akm save`. Returns true only when `--format` appears
+ * in the save subcommand's argv slice AND the candidate name does NOT
+ * appear as a standalone positional elsewhere (before or after the flag).
  *
- * This keeps `akm save json --format json` routing `json` as the stash name,
- * while `akm save --format json` (no separate positional) is treated as a
- * primary-stash save.
+ * This keeps `akm sync json --format json` routing `json` as the stash name,
+ * while `akm sync --format json` (no separate positional) is treated as a
+ * primary-stash sync. `verb` is the subcommand token to anchor on (`sync` or
+ * the deprecated `save`).
  */
-function wasFormatValueConsumedAsName(name, formatValue) {
+function wasFormatValueConsumedAsName(name, formatValue, verb) {
     const argv = process.argv.slice(2);
-    const saveIndex = argv.indexOf("save");
-    const tokens = saveIndex >= 0 ? argv.slice(saveIndex + 1) : argv;
+    const verbIndex = argv.indexOf(verb);
+    const tokens = verbIndex >= 0 ? argv.slice(verbIndex + 1) : argv;
     let formatIndex = -1;
     let formatConsumesNextToken = false;
     for (let i = 0; i < tokens.length; i += 1) {
@@ -1013,280 +1280,6 @@ const cloneCommand = defineCommand({
         });
     },
 });
-const registryCommand = defineCommand({
-    meta: { name: "registry", description: "Manage stash registries" },
-    subCommands: {
-        list: defineCommand({
-            meta: { name: "list", description: "List configured registries" },
-            run() {
-                return runWithJsonErrors(() => {
-                    const config = loadUserConfig();
-                    const registries = config.registries ?? DEFAULT_CONFIG.registries;
-                    output("registry-list", { registries });
-                });
-            },
-        }),
-        add: defineCommand({
-            meta: { name: "add", description: "Add a registry by URL" },
-            args: {
-                url: { type: "positional", description: "Registry index URL", required: true },
-                name: { type: "string", description: "Human-friendly name for the registry" },
-                provider: { type: "string", description: "Provider type (e.g. static-index, skills-sh)" },
-                options: { type: "string", description: 'Provider options as JSON (e.g. \'{"apiKey":"key"}\').' },
-                "allow-insecure": {
-                    type: "boolean",
-                    description: "Allow a plain HTTP registry URL (otherwise rejected)",
-                    default: false,
-                },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    if (!args.url.startsWith("http")) {
-                        throw new UsageError("Registry URL must start with http:// or https://");
-                    }
-                    if (args.url.startsWith("http://")) {
-                        const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
-                        if (!allowInsecure) {
-                            throw new UsageError("Registry URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious index. " +
-                                "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.");
-                        }
-                        warn("Warning: registry URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious index.");
-                    }
-                    const config = loadUserConfig();
-                    const registries = [...(config.registries ?? [])];
-                    // Deduplicate by URL
-                    if (registries.some((r) => r.url === args.url)) {
-                        output("registry-add", { registries, added: false, message: "Registry URL already configured" });
-                        return;
-                    }
-                    const entry = { url: args.url };
-                    if (args.name)
-                        entry.name = args.name;
-                    if (args.provider)
-                        entry.provider = args.provider;
-                    if (args.options) {
-                        try {
-                            entry.options = JSON.parse(args.options);
-                        }
-                        catch {
-                            throw new UsageError("--options must be valid JSON");
-                        }
-                    }
-                    registries.push(entry);
-                    saveConfig({ ...config, registries });
-                    output("registry-add", { registries, added: true });
-                });
-            },
-        }),
-        remove: defineCommand({
-            meta: { name: "remove", description: "Remove a registry by URL or name" },
-            args: {
-                target: { type: "positional", description: "Registry URL or name to remove", required: true },
-            },
-            run({ args }) {
-                return runWithJsonErrors(() => {
-                    const config = loadUserConfig();
-                    const registries = [...(config.registries ?? [])];
-                    const idx = registries.findIndex((r) => r.url === args.target || r.name === args.target);
-                    if (idx === -1) {
-                        output("registry-remove", { registries, removed: false, message: "No matching registry found" });
-                        return;
-                    }
-                    const removed = registries.splice(idx, 1)[0];
-                    saveConfig({ ...config, registries });
-                    output("registry-remove", { registries, removed: true, entry: removed });
-                });
-            },
-        }),
-        search: defineCommand({
-            meta: { name: "search", description: "Search enabled registries for stashes" },
-            args: {
-                query: { type: "positional", description: "Search query", required: true },
-                limit: { type: "string", description: "Maximum number of results" },
-                assets: { type: "boolean", description: "Include asset-level search results", default: false },
-            },
-            async run({ args }) {
-                await runWithJsonErrors(async () => {
-                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
-                    const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
-                    output("registry-search", result);
-                });
-            },
-        }),
-        "build-index": defineCommand({
-            meta: { name: "build-index", description: "Build a v2 registry index from discovery and manual entries" },
-            args: {
-                out: { type: "string", description: "Output path for the generated index" },
-                manual: { type: "string", description: "Manual entries JSON file" },
-                "npm-registry": { type: "string", description: "Override npm registry base URL" },
-                "github-api": { type: "string", description: "Override GitHub API base URL" },
-            },
-            async run({ args }) {
-                await runWithJsonErrors(async () => {
-                    const result = await buildRegistryIndex({
-                        manualEntriesPath: args.manual,
-                        npmRegistryBase: getHyphenatedArg(args, "npm-registry"),
-                        githubApiBase: getHyphenatedArg(args, "github-api"),
-                    });
-                    const outPath = writeRegistryIndex(result.index, args.out);
-                    output("registry-build-index", {
-                        outPath,
-                        version: result.index.version,
-                        updatedAt: result.index.updatedAt,
-                        totalKits: result.counts.total,
-                        counts: result.counts,
-                        manualEntriesPath: result.paths.manualEntriesPath,
-                    });
-                });
-            },
-        }),
-    },
-});
-const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
-const MAX_FEEDBACK_TAGS = 10;
-function validateFeedbackTags(raw) {
-    const seen = new Set();
-    const out = [];
-    for (const tag of raw) {
-        const parts = tag.split(":");
-        if (parts.length < 2 || parts[0] === "" || parts.slice(1).join("") === "") {
-            throw new UsageError(`Invalid tag "${tag}". Tags must be in key:value format where key matches [a-z_][a-z0-9_]* and value is non-empty.`, "INVALID_FLAG_VALUE");
-        }
-        const key = parts[0];
-        if (!TAG_KEY_RE.test(key)) {
-            throw new UsageError(`Invalid tag key "${key}" in "${tag}". Key must match [a-z_][a-z0-9_]*.`, "INVALID_FLAG_VALUE");
-        }
-        if (seen.has(tag))
-            continue;
-        seen.add(tag);
-        out.push(tag);
-    }
-    if (out.length > MAX_FEEDBACK_TAGS) {
-        throw new UsageError(`Too many tags: ${out.length}. Maximum is ${MAX_FEEDBACK_TAGS}.`, "INVALID_FLAG_VALUE");
-    }
-    return out;
-}
-const feedbackCommand = defineCommand({
-    meta: {
-        name: "feedback",
-        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 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.",
-    },
-    args: {
-        // Optional in citty so run() is invoked even when omitted; we re-validate
-        // and throw a structured UsageError below so exit code is 2 (USAGE) rather
-        // than citty's default 0 (help banner).
-        ref: { type: "positional", description: "Asset ref (type:name)", required: false },
-        positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
-        negative: {
-            type: "boolean",
-            description: "Record negative feedback (suppresses ranking after next `akm index`). " +
-                "Reindexing is required for the signal to affect search results.",
-            default: false,
-        },
-        reason: {
-            type: "string",
-            description: "Reason for the feedback (recommended for negative feedback, used by distillation)",
-        },
-        note: { type: "string", description: "Alias for --reason (backward-compatible, prefer --reason)" },
-        tag: {
-            type: "string",
-            description: "Tag to attach to the feedback (repeatable, e.g. --tag slice:train --tag team:platform)",
-        },
-    },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const ref = (args.ref ?? "").trim();
-            if (!ref) {
-                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
-            }
-            parseAssetRef(ref);
-            if (args.positive && args.negative) {
-                throw new UsageError("Specify either --positive or --negative, not both.");
-            }
-            if (!args.positive && !args.negative) {
-                throw new UsageError("Specify --positive or --negative.");
-            }
-            const signal = args.positive ? "positive" : "negative";
-            const reason = args.reason ?? args.note;
-            if (args.negative === true && !reason?.trim()) {
-                const cfg = loadConfig();
-                if (cfg.feedback?.requireReason === true) {
-                    throw new UsageError("Negative feedback requires --reason (feedback.requireReason is enabled).", "MISSING_REQUIRED_ARGUMENT");
-                }
-                else {
-                    warn("Warning: negative feedback without --reason provides less distillation signal.");
-                }
-            }
-            const rawTags = parseAllFlagValues("--tag");
-            const validatedTags = validateFeedbackTags(rawTags);
-            const metadataObj = {
-                signal,
-                ...(reason?.trim() ? { reason: reason.trim() } : {}),
-                ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
-            };
-            const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
-            // Auto-index when stale so the index is current before recording feedback.
-            const sources = resolveSourceEntries();
-            if (sources.length > 0) {
-                await ensureIndex(sources[0].path);
-            }
-            const db = openExistingDatabase();
-            try {
-                const entryId = findEntryIdByRef(db, ref);
-                if (entryId === undefined) {
-                    throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                        "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
-                }
-                // Persist the feedback signal into usage_events. For positive signals,
-                // the EMA utility score is updated immediately on the next read path.
-                // For negative signals, the score is adjusted the next time `akm index`
-                // runs — the signal is durable in the DB but does NOT suppress ranking
-                // in search results until after reindexing.
-                insertUsageEvent(db, {
-                    event_type: "feedback",
-                    entry_ref: ref,
-                    entry_id: entryId,
-                    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.
-                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;
-                    applyFeedbackToUtilityScore(db, entryId, pos, neg);
-                }
-                catch {
-                    // best-effort — feedback recording succeeds even if utility update fails
-                }
-            }
-            finally {
-                closeDatabase(db);
-            }
-            appendEvent({
-                eventType: "feedback",
-                ref,
-                metadata: metadataObj,
-            });
-            output("feedback", { ok: true, ref, signal, reason: reason?.trim() ?? null, tags: validatedTags });
-        });
-    },
-});
 const historyCommand = defineCommand({
     meta: {
         name: "history",
@@ -1300,20 +1293,49 @@ const historyCommand = defineCommand({
     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" },
+        generator: {
+            type: "string",
+            description: 'Filter by event generator: "user" (default) or "improve" (akm improve operations).',
+        },
+        source: {
+            type: "string",
+            description: "DEPRECATED — use --generator. Removed in 0.9.0.",
+        },
         "include-proposals": {
             type: "boolean",
             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 () => {
+            if (args.generator === undefined && args.source !== undefined) {
+                emitFlagDeprecation("--source", "--generator", "history");
+            }
+            const generatorFlag = (args.generator ?? args.source);
+            if (generatorFlag !== undefined && generatorFlag !== "user" && generatorFlag !== "improve") {
+                // Name the flag the user actually typed so the diagnostic points at
+                // their command line, not the canonical flag they may not have used.
+                const usedFlag = args.generator !== undefined ? "--generator" : "--source";
+                throw new UsageError(`Invalid ${usedFlag} value: "${generatorFlag}". 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: generatorFlag,
                 includeProposals: args["include-proposals"],
+                acceptRateBySource: args["accept-rate-by-source"],
+                stashDir,
             });
             output("history", result);
         });
@@ -1327,10 +1349,17 @@ const workflowStartCommand = defineCommand({
     args: {
         ref: { type: "positional", description: "Workflow ref (workflow:<name>)", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object" },
+        force: {
+            type: "boolean",
+            description: "Allow a parallel run when an active run already exists in this scope (#485)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await startWorkflowRun(args.ref, parseWorkflowJsonObject(args.params, "--params"));
+            const result = await startWorkflowRun(args.ref, parseWorkflowJsonObject(args.params, "--params"), {
+                force: args.force === true,
+            });
             output("workflow-start", result);
         });
     },
@@ -1343,11 +1372,14 @@ 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")) {
+            // `--dry-run` is intentionally NOT a declared arg (so it stays out of
+            // --help). The guard reads it straight from process.argv so existing
+            // callers still get a clear, actionable error instead of a generic
+            // "unknown flag" from citty.
+            if (hasBooleanFlag(process.argv, "--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;
@@ -1605,234 +1637,6 @@ const workflowCommand = defineCommand({
         });
     },
 });
-const rememberCommand = defineCommand({
-    meta: {
-        name: "remember",
-        description: "Record a memory in the default stash",
-    },
-    args: {
-        content: {
-            type: "positional",
-            description: "Memory content. Omit to read markdown from stdin.",
-            required: false,
-        },
-        name: {
-            type: "string",
-            description: "Memory name (defaults to a slug from the content)",
-        },
-        force: {
-            type: "boolean",
-            description: "Overwrite an existing memory with the same name",
-            default: false,
-        },
-        description: {
-            type: "string",
-            description: "Short description written to frontmatter (persisted as the memory's description field)",
-        },
-        tag: {
-            type: "string",
-            description: "Tag to add to the memory (repeatable: --tag foo --tag bar)",
-        },
-        expires: {
-            type: "string",
-            description: "Expiry duration shorthand (e.g. 30d, 12h, 6m). Resolved to an ISO date.",
-        },
-        source: {
-            type: "string",
-            description: "Source reference (URL, asset ref, file path, or any free-form string)",
-        },
-        auto: {
-            type: "boolean",
-            description: "Apply heuristic tagging (code, subjective, source, observed_at) from the body",
-            default: false,
-        },
-        enrich: {
-            type: "boolean",
-            description: "Call the configured LLM to propose tags and description (requires LLM config)",
-            default: false,
-        },
-        target: {
-            type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
-        },
-        user: {
-            type: "string",
-            description: "Scope this memory to a user id (persisted as `scope_user` frontmatter)",
-        },
-        agent: {
-            type: "string",
-            description: "Scope this memory to an agent id (persisted as `scope_agent` frontmatter)",
-        },
-        run: {
-            type: "string",
-            description: "Scope this memory to a run id (persisted as `scope_run` frontmatter)",
-        },
-        channel: {
-            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 () => {
-            const body = readMemoryContent(resolveRememberContentArg(args.content));
-            // Determine if the user has requested any structured metadata mode.
-            // Collect all --tag occurrences directly from process.argv because citty
-            // only exposes the last value for repeated string flags.
-            const rawTags = parseAllFlagValues("--tag");
-            // Collect scope flags. Scope alone counts as structured metadata so we
-            // emit frontmatter, but it does NOT trigger the "tags required" check —
-            // memory + scope (no tags) is a valid combination for multi-tenant use.
-            const scopeFields = {};
-            if (typeof args.user === "string" && args.user.trim())
-                scopeFields.user = args.user.trim();
-            if (typeof args.agent === "string" && args.agent.trim())
-                scopeFields.agent = args.agent.trim();
-            if (typeof args.run === "string" && args.run.trim())
-                scopeFields.run = args.run.trim();
-            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;
-            const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
-            if (!hasStructuredArgs) {
-                const result = await writeMarkdownAsset({
-                    type: "memory",
-                    content: body,
-                    name: args.name,
-                    fallbackPrefix: "memory",
-                    force: args.force,
-                    target: args.target,
-                });
-                appendEvent({
-                    eventType: "remember",
-                    ref: result.ref,
-                    metadata: { path: result.path, force: args.force === true },
-                });
-                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 ──────────────────────────
-            // Start with CLI args (Mode 1: always)
-            const tags = [...rawTags];
-            // --description is persisted as-is; LLM enrichment may fill it if absent.
-            let description = args.description || undefined;
-            let source = args.source;
-            let observed_at;
-            let expires;
-            let subjective;
-            // Resolve --expires to an ISO date string
-            if (args.expires) {
-                const durationMs = parseDuration(args.expires);
-                const expiresDate = new Date(Date.now() + durationMs);
-                expires = expiresDate.toISOString().slice(0, 10);
-            }
-            // Mode 2: --auto heuristics
-            if (args.auto) {
-                const auto = runAutoHeuristics(body);
-                for (const t of auto.tags) {
-                    if (!tags.includes(t))
-                        tags.push(t);
-                }
-                if (!source && auto.source)
-                    source = auto.source;
-                if (!observed_at && auto.observed_at)
-                    observed_at = auto.observed_at;
-                if (!subjective && auto.subjective)
-                    subjective = auto.subjective;
-            }
-            // Mode 3: --enrich LLM (fail-soft)
-            if (args.enrich) {
-                const enriched = await runLlmEnrich(body);
-                for (const t of enriched.tags) {
-                    if (!tags.includes(t))
-                        tags.push(t);
-                }
-                if (!description && enriched.description)
-                    description = enriched.description;
-                if (!observed_at && enriched.observed_at)
-                    observed_at = enriched.observed_at;
-            }
-            // ── Required-field check (before any write) ───────────────────────────
-            // Tags remain required when the user explicitly asked for tag-bearing
-            // metadata (--tag / --enrich / --description / --source / --expires).
-            // `--auto` alone is allowed even when its heuristics derive zero tags.
-            // Scope-only writes (`akm remember "..." --user u1`) also skip this
-            // check — scope is independent metadata and a memory with only scope is
-            // valid.
-            const missing = [];
-            if (hasTagRequiringArgs && tags.length === 0)
-                missing.push("tags");
-            if (missing.length > 0) {
-                throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
-                    "Provide them via --tag <value>, --auto (heuristics), or --enrich (LLM).");
-            }
-            // ── Build frontmatter and write ───────────────────────────────────────
-            const frontmatterBlock = buildMemoryFrontmatter({
-                description,
-                tags,
-                source,
-                observed_at,
-                expires,
-                subjective,
-                ...(hasScope ? { scope: scopeFields } : {}),
-            });
-            const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
-            const result = await writeMarkdownAsset({
-                type: "memory",
-                content: contentWithFrontmatter,
-                name: args.name,
-                fallbackPrefix: "memory",
-                force: args.force,
-                target: args.target,
-            });
-            appendEvent({
-                eventType: "remember",
-                ref: result.ref,
-                metadata: {
-                    path: result.path,
-                    force: args.force === true,
-                    tagCount: tags.length,
-                    enriched: args.enrich === true,
-                    auto: args.auto === true,
-                    ...(hasScope ? { scope: scopeFields } : {}),
-                },
-            });
-            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 });
-            }
-        });
-    },
-});
-/**
- * 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 } : {}) }));
-    }
-    catch {
-        return [];
-    }
-}
 const importKnowledgeCommand = defineCommand({
     meta: {
         name: "import",
@@ -1887,15 +1691,18 @@ const hintsCommand = defineCommand({
     args: {
         detail: {
             type: "string",
-            description: "Hints detail level — accepts only `normal` or `full`. Differs from the global --detail flag (brief|normal|full|summary|agent); other values are rejected with INVALID_DETAIL_VALUE.",
+            description: "Hints detail level (brief|normal|full). `brief` prints the short guide; `normal`/`full` print the complete guide.",
             default: "normal",
         },
     },
     run({ args }) {
-        if (args.detail !== "normal" && args.detail !== "full") {
-            throw new UsageError(`Invalid value for --detail: ${args.detail}. Expected one of: normal|full.`, "INVALID_DETAIL_VALUE");
-        }
-        process.stdout.write(loadHints(args.detail));
+        return runWithJsonErrors(() => {
+            // Let the global parser validate the value so an invalid `--detail`
+            // returns the standard JSON error envelope (exit 2) rather than a raw
+            // stack trace + exit 1. `brief` → short doc; `normal`/`full` → full doc.
+            const detail = parseDetailLevel(args.detail) ?? "normal";
+            process.stdout.write(loadHints(detail === "brief" ? "brief" : "full"));
+        });
     },
 });
 const helpCommand = defineCommand({
@@ -1997,38 +1804,44 @@ function toggleComponent(targetRaw, enabled) {
     // normalizeToggleTarget throws for any unsupported target; this is unreachable.
     throw new UsageError(`Unsupported target "${targetRaw}". Supported targets: skills.sh`);
 }
+// Deprecated top-level aliases (removed 0.9.0) — delegate to `config enable|disable`.
 const enableCommand = defineCommand({
-    meta: { name: "enable", description: "Enable an optional component (skills.sh)" },
+    meta: { name: "enable", description: "DEPRECATED — use `akm config enable`. Removed in 0.9.0." },
     args: {
         target: { type: "positional", description: "Component to enable (skills.sh)", required: true },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
+            emitCommandDeprecation("enable", "config enable");
             const result = toggleComponent(args.target, true);
             output("enable", result);
         });
     },
 });
 const disableCommand = defineCommand({
-    meta: { name: "disable", description: "Disable an optional component (skills.sh)" },
+    meta: { name: "disable", description: "DEPRECATED — use `akm config disable`. Removed in 0.9.0." },
     args: {
         target: { type: "positional", description: "Component to disable (skills.sh)", required: true },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
+            emitCommandDeprecation("disable", "config disable");
             const result = toggleComponent(args.target, false);
             output("disable", result);
         });
     },
 });
-// ── vault ───────────────────────────────────────────────────────────────────
+// ── env ───────────────────────────────────────────────────────────────────
 //
-// `akm vault` manages secrets stored in `.env` files under each stash's
-// vaults/ directory. Values are NEVER written to stdout or structured output.
-function parseVaultRef(ref) {
-    return parseAssetRef(ref.includes(":") ? ref : `vault:${ref}`);
+// `akm env` manages whole `.env` files under each stash's env/ directory.
+// Values are NEVER written to stdout or structured output — only key NAMES and
+// start-of-line comments are surfaced. akm does not manage individual entries;
+// you edit the `.env` file yourself and akm loads it. Replaces the deprecated
+// `vault` type (see the shim further below; removed in 0.9.0).
+function parseEnvRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `env:${ref}`);
 }
-function findVaultSource(origin) {
+function findEnvSource(origin) {
     const sources = resolveSourceEntries(undefined, loadConfig());
     if (sources.length === 0) {
         throw new UsageError("No stashes configured. Run `akm init` to create your working stash.");
@@ -2041,30 +1854,59 @@ function findVaultSource(origin) {
     }
     return named;
 }
-function makeVaultRef(name, source) {
-    return source?.registryId ? `${source.registryId}//vault:${name}` : `vault:${name}`;
+function makeEnvRef(name, source) {
+    return source?.registryId ? `${source.registryId}//env:${name}` : `env:${name}`;
 }
-function resolveVaultPath(ref) {
-    const parsed = parseVaultRef(ref);
-    if (parsed.type !== "vault") {
-        throw new UsageError(`Expected a vault ref (vault:<name>); got "${ref}".`);
+/**
+ * Resolve an env ref to an absolute `.env` path. Accepts `env:`, `environment:`
+ * (alias), and `vault:` (deprecated) refs as well as bare names. Prefers the
+ * `env/` directory; falls back to the legacy `vaults/` directory when the env
+ * file is absent there (handles an upgraded-but-not-yet-migrated stash). When
+ * neither exists the env path is returned (so `create` writes under `env/`).
+ */
+function resolveEnvPath(ref) {
+    const parsed = parseEnvRef(ref);
+    if (parsed.type !== "env" && parsed.type !== "vault") {
+        throw new UsageError(`Expected an env ref (env:<name>); got "${ref}".`);
+    }
+    const source = findEnvSource(parsed.origin);
+    const envRoot = path.join(source.path, "env");
+    const envPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the env 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(envPath, envRoot)) {
+        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+    }
+    const vaultRoot = path.join(source.path, "vaults");
+    const vaultPath = resolveAssetPathFromName("vault", vaultRoot, parsed.name);
+    if (!isWithin(vaultPath, vaultRoot)) {
+        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
     }
-    const source = findVaultSource(parsed.origin);
-    const typeRoot = path.join(source.path, "vaults");
-    const absPath = resolveAssetPathFromName("vault", typeRoot, parsed.name);
-    return { name: parsed.name, absPath, source, parsedRef: parsed };
+    // Prefer env/; fall back to the frozen vaults/ copy only when the env file
+    // is absent and the legacy vault file is present.
+    if (!fs.existsSync(envPath) && fs.existsSync(vaultPath)) {
+        return { name: parsed.name, absPath: vaultPath, source, parsedRef: parsed, dir: "vaults" };
+    }
+    return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
 }
 /**
- * Walk `vaults/` recursively and return one entry per `.env` file, using the
- * vault asset spec's canonical-name logic so listing matches what the
- * matcher/asset-spec actually resolves (e.g. `vaults/team/prod.env` →
- * `vault:team/prod`, `vaults/team/.env` → `vault:team/default`).
+ * Walk each stash's env files and return one entry per `.env` file, using the
+ * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
+ * `env:team/prod`, `env/team/.env` → `env:team/default`). When a stash has not
+ * yet migrated (no `env/` dir) the legacy `vaults/` dir is listed instead, so
+ * `env list` stays continuous across the upgrade.
  */
-function listVaultsRecursive(listKeysFn) {
+function listEnvsRecursive(listKeysFn) {
     const result = [];
     for (const source of resolveSourceEntries(undefined, loadConfig())) {
-        const vaultsDir = path.join(source.path, "vaults");
-        if (!fs.existsSync(vaultsDir))
+        const envDir = path.join(source.path, "env");
+        const legacyDir = path.join(source.path, "vaults");
+        // Prefer env/; only fall back to the frozen vaults/ copy when env/ is absent.
+        const scanType = fs.existsSync(envDir) ? "env" : "vault";
+        const root = scanType === "env" ? envDir : legacyDir;
+        if (!fs.existsSync(root))
             continue;
         const walk = (dir) => {
             for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -2077,227 +1919,730 @@ function listVaultsRecursive(listKeysFn) {
                     continue;
                 if (entry.name !== ".env" && !entry.name.endsWith(".env"))
                     continue;
-                const canonical = deriveCanonicalAssetName("vault", vaultsDir, full);
+                const canonical = deriveCanonicalAssetName(scanType, root, full);
                 if (!canonical)
                     continue;
-                // Skip sensitive vaults: presence of a sibling .sensitive marker file suppresses listing.
+                // Skip sensitive envs: 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 });
+                result.push({ ref: makeEnvRef(canonical, source), path: full, keys });
             }
         };
-        walk(vaultsDir);
+        walk(root);
     }
     return result;
 }
-function splitVaultRunTarget(target) {
-    const full = resolveVaultPath(target);
-    if (fs.existsSync(full.absPath)) {
-        return { ref: makeVaultRef(full.name, full.source) };
-    }
-    const slashIndex = target.lastIndexOf("/");
-    if (slashIndex <= 0) {
-        throw new NotFoundError(`Vault not found: ${target.includes(":") ? target : `vault:${target}`}`);
-    }
-    const refPart = target.slice(0, slashIndex);
-    const key = target.slice(slashIndex + 1).trim();
-    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)}`);
-    }
-    return { ref: makeVaultRef(resolved.name, resolved.source), key };
-}
-const vaultListCommand = defineCommand({
-    meta: { name: "list", description: "List all vaults across all stashes with their available key names (no values)" },
+const envListCommand = defineCommand({
+    meta: { name: "list", description: "List all env files across all stashes with their key names (no values)" },
     run() {
         return runWithJsonErrors(async () => {
-            const { listKeys } = await import("./commands/vault.js");
-            const vaults = listVaultsRecursive(listKeys);
-            output("vault-list", { vaults });
+            const { listKeys } = await import("./commands/env.js");
+            output("env-list", { envs: listEnvsRecursive(listKeys) });
         });
     },
 });
-const vaultCreateCommand = defineCommand({
-    meta: { name: "create", description: "Create an empty vault file (no-op if it already exists)" },
+const envCreateCommand = defineCommand({
+    meta: {
+        name: "create",
+        description: "Create an env file (empty by default; seed an existing `.env` with --from-file or --from-stdin). No-op if it already exists and no source is given.",
+    },
     args: {
-        name: { type: "positional", description: "Vault name (e.g. prod) — file becomes <name>.env", required: true },
+        name: { type: "positional", description: "Env name (e.g. prod) — file becomes <name>.env", required: true },
+        "from-file": { type: "string", description: "Seed the env file from an existing .env at this path" },
+        "from-stdin": { type: "boolean", description: "Seed the env file from stdin", default: false },
         sensitive: {
             type: "boolean",
-            description: "Exclude this vault from vault list output and the search index",
+            description: "Exclude this env file from env 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);
+            const { createEnv, writeEnv } = await import("./commands/env.js");
+            // `create` always targets env/, never the frozen vaults/ copy.
+            const parsed = parseEnvRef(args.name);
+            const source = findEnvSource(parsed.origin);
+            const envRoot = path.join(source.path, "env");
+            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+            if (!isWithin(absPath, envRoot)) {
+                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+            }
+            const fromFile = getHyphenatedArg(args, "from-file");
+            const fromStdin = getHyphenatedArg(args, "from-stdin") === true;
+            if (fromFile !== undefined && fromStdin) {
+                throw new UsageError("Pass only one of --from-file or --from-stdin.", "INVALID_FLAG_VALUE");
+            }
+            if (fromFile !== undefined || fromStdin) {
+                // Ingest path: never silently clobber an existing env file.
+                if (fs.existsSync(absPath)) {
+                    throw new UsageError(`Env "${makeEnvRef(parsed.name, source)}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
+                }
+                let content;
+                if (fromFile !== undefined) {
+                    if (!fs.existsSync(fromFile)) {
+                        throw new NotFoundError(`Source file not found: ${fromFile}`, "FILE_NOT_FOUND");
+                    }
+                    content = fs.readFileSync(fromFile, "utf8");
+                }
+                else {
+                    const MAX_ENV_BYTES = 1024 * 1024; // 1 MB
+                    let total = 0;
+                    const chunks = [];
+                    for await (const chunk of Bun.stdin.stream()) {
+                        total += chunk.byteLength;
+                        if (total > MAX_ENV_BYTES) {
+                            throw new UsageError("Env file exceeds 1 MB limit.", "INVALID_FLAG_VALUE");
+                        }
+                        chunks.push(chunk);
+                    }
+                    content = Buffer.concat(chunks).toString("utf8");
+                }
+                writeEnv(absPath, content);
+            }
+            else {
+                createEnv(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) });
+            output("env-create", { ref: makeEnvRef(parsed.name, source) });
         });
     },
 });
-const vaultSetCommand = defineCommand({
+const envPathCommand = defineCommand({
     meta: {
-        name: "set",
-        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".',
+        name: "path",
+        description: "Print the absolute env file path (Docker `_FILE` convention / `--env-file`). To inject values, use `akm env run <ref> -- <cmd>` — do NOT `source` the raw file.",
     },
     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)", 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",
-        },
+        ref: { type: "positional", description: "Env ref", required: true },
+        quiet: { type: "boolean", alias: "q", description: "Suppress the unsafe-source warning", default: false },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { setKey } = await import("./commands/vault.js");
-            const { name, absPath, source } = resolveVaultPath(args.ref);
-            const fromEnv = getHyphenatedArg(args, "from-env");
-            let realValue;
-            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;
+            const { name, absPath, source } = resolveEnvPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
             }
-            else {
-                const chunks = [];
-                for await (const chunk of Bun.stdin.stream()) {
-                    chunks.push(chunk);
+            // The raw `.env` may contain `X=$(cmd)`, which executes if `source`d.
+            // Warning goes to stderr (never contaminates the path on stdout) and is
+            // suppressed with --quiet for the legitimate `_FILE` / `--env-file` use.
+            if (args.quiet !== true) {
+                process.stderr.write(`warning: this is the raw file path. Do NOT \`source\` it (shell substitutions in the file would execute).\n` +
+                    `         To inject values run: akm env run ${args.ref} -- <command>\n`);
+            }
+            process.stdout.write(`${absPath}\n`);
+        });
+    },
+});
+const envExportCommand = defineCommand({
+    meta: {
+        name: "export",
+        description: "Write safe `export KEY='value'` lines to a file (mode 0600) for `source`-ing — requires --out <path>. Values are re-serialised single-quoted so a raw `.env` cannot execute on load, and are NEVER printed to stdout. To use values directly, prefer `akm env run <ref> -- <command>`.",
+    },
+    args: {
+        ref: { type: "positional", description: "Env ref", required: true },
+        out: { type: "string", alias: "o", description: "Destination file (required). Written at mode 0600." },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const outPath = getHyphenatedArg(args, "out");
+            if (!outPath) {
+                throw new UsageError("`akm env export` writes to a file — pass --out <path>.\n" +
+                    "       To use values directly, run `akm env run <ref> -- <command>` (or `-- $SHELL` for an interactive\n" +
+                    "       session). export never prints values to stdout, to avoid leaking them into a captured context.", "MISSING_REQUIRED_ARGUMENT");
+            }
+            const { name, absPath, source } = resolveEnvPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
+            }
+            const { buildShellExportScript } = await import("./commands/env.js");
+            const resolvedOut = path.resolve(outPath);
+            writeFileAtomic(resolvedOut, buildShellExportScript(absPath), 0o600);
+            output("env-export", { ref: makeEnvRef(name, source), out: resolvedOut });
+        });
+    },
+});
+/**
+ * Shared implementation for `env run` (and the deprecated `vault run` shim).
+ * Injects an entire env file's values into the child process env — never via a
+ * shell — after scanning the injected keys for process-hijacking variables.
+ */
+async function runEnvInjected(target, opts) {
+    const dashIndex = process.argv.indexOf("--");
+    if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
+        throw new UsageError("Missing command. Usage: akm env run <ref> -- <command>");
+    }
+    const command = process.argv.slice(dashIndex + 1);
+    const { name, absPath, source } = resolveEnvPath(target);
+    if (!fs.existsSync(absPath)) {
+        // Help users who reach for the removed single-key `ref/KEY` form.
+        const slash = target.lastIndexOf("/");
+        if (slash > 0) {
+            const maybeKey = target.slice(slash + 1);
+            if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(maybeKey)) {
+                let baseExists = false;
+                try {
+                    baseExists = fs.existsSync(resolveEnvPath(target.slice(0, slash)).absPath);
+                }
+                catch {
+                    baseExists = false;
+                }
+                if (baseExists) {
+                    throw new UsageError(`'akm env run' injects the whole file; the single-key '<ref>/${maybeKey}' form was removed.\n` +
+                        `       For one value use a secret: \`akm secret run secret:${maybeKey} ${maybeKey} -- <command>\`.`, "INVALID_FLAG_VALUE");
                 }
-                realValue = Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
             }
-            setKey(absPath, args.key, realValue, args.comment);
-            output("vault-set", { ref: makeVaultRef(name, source), key: args.key });
+        }
+        throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
+    }
+    const { loadEnv } = await import("./commands/env.js");
+    const allValues = loadEnv(absPath);
+    // Value-safe key filtering (--only / --except operate on key NAMES only).
+    let envValues = allValues;
+    if (opts.only && opts.except) {
+        throw new UsageError("Pass only one of --only or --except.", "INVALID_FLAG_VALUE");
+    }
+    if (opts.only) {
+        const wanted = new Set(opts.only);
+        const missing = opts.only.filter((k) => !(k in allValues));
+        if (missing.length > 0) {
+            process.stderr.write(`warning: --only key(s) not present in ${makeEnvRef(name, source)}: ${missing.join(", ")}\n`);
+        }
+        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => wanted.has(k)));
+    }
+    else if (opts.except) {
+        const excluded = new Set(opts.except);
+        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => !excluded.has(k)));
+    }
+    const keys = Object.keys(envValues);
+    // Scan injected keys for known process-hijacking variables (LD_PRELOAD,
+    // PATH, ...). Block for third-party-sourced stashes (origin has a registryId);
+    // warn for the operator's own first-party stash, where they own the file.
+    const { isDangerousEnvKey } = await import("./commands/lint/env-key-rules.js");
+    const dangerous = keys.filter(isDangerousEnvKey);
+    if (dangerous.length > 0) {
+        const detail = `Env "${makeEnvRef(name, source)}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
+        if (source.registryId) {
+            throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
+                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
+        }
+        process.stderr.write(`warning: ${detail} Injecting anyway (first-party stash).\n`);
+    }
+    const mergedEnv = { ...process.env };
+    for (const [envKey, envValue] of Object.entries(envValues)) {
+        mergedEnv[envKey] = envValue;
+    }
+    // Audit trail: keys only, never values. A single `env_access` event carries a
+    // `deprecatedAlias` marker when reached via the `vault run` shim, so log
+    // consumers see one stable event type without a doubled physical record.
+    appendEvent({
+        eventType: "env_access",
+        ref: makeEnvRef(name, source),
+        metadata: opts.viaVault ? { keys, deprecatedAlias: "vault_access" } : { keys },
+    });
+    const result = spawnSync(command[0], command.slice(1), {
+        stdio: "inherit",
+        env: mergedEnv,
+    });
+    if (result.error) {
+        // Classify spawn failures (#483). Raw ErrnoException leaks a bare
+        // "spawn ENOENT" with no hint — wrap it so consumers get a usable
+        // code + hint in the standard JSON envelope.
+        const err = result.error;
+        if (err.code === "ENOENT") {
+            throw new NotFoundError(`Command not found: ${command[0]}`, "FILE_NOT_FOUND", `Install '${command[0]}' or add its directory to PATH before invoking 'akm env run'.`);
+        }
+        if (err.code === "EACCES") {
+            throw new ConfigError(`Command not executable: ${command[0]}`, "STASH_DIR_UNREADABLE", `Add execute permission ('chmod +x ${command[0]}') or invoke via an interpreter.`);
+        }
+        throw err;
+    }
+    process.exit(result.status ?? 0);
+}
+/** Parse a comma/space-separated key list flag into a trimmed, non-empty array. */
+function parseKeyListFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const keys = raw
+        .split(/[,\s]+/)
+        .map((k) => k.trim())
+        .filter(Boolean);
+    return keys.length > 0 ? keys : undefined;
+}
+const envRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except.",
+    },
+    args: {
+        target: { type: "positional", description: "Env ref", required: true },
+        only: {
+            type: "string",
+            description: "Inject ONLY these keys (comma-separated). Mutually exclusive with --except.",
+        },
+        except: { type: "string", description: "Inject all keys EXCEPT these (comma-separated)." },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => runEnvInjected(args.target, {
+            viaVault: false,
+            only: parseKeyListFlag(getHyphenatedArg(args, "only")),
+            except: parseKeyListFlag(getHyphenatedArg(args, "except")),
+        }));
+    },
+});
+const envRemoveCommand = defineCommand({
+    meta: { name: "remove", description: "Remove an env file (and its .sensitive marker, if any)" },
+    args: {
+        ref: { type: "positional", description: "Env ref", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            // Resolve against env/ specifically — never delete the frozen vaults/ copy.
+            const parsed = parseEnvRef(args.ref);
+            const source = findEnvSource(parsed.origin);
+            const envRoot = path.join(source.path, "env");
+            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+            if (!isWithin(absPath, envRoot)) {
+                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+            }
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
+                yes: args.yes === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
+            }
+            const { removeEnv } = await import("./commands/env.js");
+            const removed = removeEnv(absPath);
+            output("env-remove", { ref: makeEnvRef(parsed.name, source), removed });
+        });
+    },
+});
+const envCommand = defineCommand({
+    meta: {
+        name: "env",
+        description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
+    },
+    subCommands: {
+        list: envListCommand,
+        path: envPathCommand,
+        export: envExportCommand,
+        run: envRunCommand,
+        create: envCreateCommand,
+        remove: envRemoveCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, ENV_SUBCOMMAND_SET))
+                return;
+            const { listKeys } = await import("./commands/env.js");
+            output("env-list", { envs: listEnvsRecursive(listKeys) });
+        });
+    },
+});
+// ── vault (DEPRECATED) ────────────────────────────────────────────────────────
+//
+// `akm vault` is deprecated in 0.8.0 and removed in 0.9.0. The verb now warns
+// to stderr and delegates to the `env` handlers. Entry management (`set` /
+// `unset`) and the single-key `run <ref>/KEY` form are hard-errors with a
+// signpost to `akm secret` — silent behaviour changes around secret material
+// are unacceptable.
+function emitVaultDeprecation(sub) {
+    process.stderr.write(`warning: 'akm vault ${sub}' is deprecated and will be removed in 0.9.0. Use 'akm env ${sub}'.\n` +
+        "         For single-value injection use 'akm secret'.\n");
+}
+function emitFlagDeprecation(oldFlag, newFlag, cmd) {
+    if (isQuiet())
+        return;
+    process.stderr.write(`warning: '${oldFlag}' is deprecated for 'akm ${cmd}'; use '${newFlag}'. Removed in 0.9.0.\n`);
+}
+/**
+ * Emit a stderr deprecation warning for a renamed top-level command. The old
+ * spelling keeps working in 0.8 (wrap-and-delegate) and is removed in 0.9.0.
+ * Suppressed under --quiet; never written to stdout so JSON consumers are
+ * unaffected.
+ */
+function emitCommandDeprecation(oldCmd, newCmd) {
+    if (isQuiet())
+        return;
+    process.stderr.write(`warning: 'akm ${oldCmd}' is deprecated and will be removed in 0.9.0. Use 'akm ${newCmd}'.\n`);
+}
+const vaultSetCommand = defineCommand({
+    meta: { name: "set", description: "DEPRECATED — removed. Edit the .env file directly, or use `akm secret set`." },
+    args: {
+        ref: { type: "positional", description: "(deprecated)", required: false },
+        key: { type: "positional", description: "(deprecated)", required: false },
+    },
+    run() {
+        return runWithJsonErrors(async () => {
+            throw new UsageError("'akm vault set' was removed: akm no longer manages individual env entries.\n" +
+                "       Edit the .env file directly (then run with `akm env run <ref> -- <cmd>`),\n" +
+                "       or store a single value as a secret: `akm secret set secret:<name>`.", "INVALID_FLAG_VALUE");
         });
     },
 });
 const vaultUnsetCommand = defineCommand({
-    meta: { name: "unset", description: "Remove a key from a vault" },
+    meta: { name: "unset", description: "DEPRECATED — removed. Edit the .env file directly." },
+    args: {
+        ref: { type: "positional", description: "(deprecated)", required: false },
+        key: { type: "positional", description: "(deprecated)", required: false },
+    },
+    run() {
+        return runWithJsonErrors(async () => {
+            throw new UsageError("'akm vault unset' was removed: akm no longer manages individual env entries.\n" +
+                "       Edit the .env file directly, or remove a secret with `akm secret remove secret:<name>`.", "INVALID_FLAG_VALUE");
+        });
+    },
+});
+const vaultListCommand = defineCommand({
+    meta: { name: "list", description: "DEPRECATED — use `akm env list`." },
+    run() {
+        return runWithJsonErrors(async () => {
+            emitVaultDeprecation("list");
+            const { listKeys } = await import("./commands/env.js");
+            output("env-list", { envs: listEnvsRecursive(listKeys) });
+        });
+    },
+});
+const vaultCreateCommand = defineCommand({
+    meta: { name: "create", description: "DEPRECATED — use `akm env create`." },
     args: {
-        ref: { type: "positional", description: "Vault ref", required: true },
-        key: { type: "positional", description: "Key name to remove", required: true },
+        name: { type: "positional", description: "Env name", required: true },
+        sensitive: { type: "boolean", description: "Exclude from list output and the search index", default: false },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { unsetKey } = await import("./commands/vault.js");
-            const { name, absPath, source } = resolveVaultPath(args.ref);
-            if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
+            emitVaultDeprecation("create");
+            const { createEnv } = await import("./commands/env.js");
+            const parsed = parseEnvRef(args.name);
+            const source = findEnvSource(parsed.origin);
+            const envRoot = path.join(source.path, "env");
+            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+            if (!isWithin(absPath, envRoot)) {
+                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
             }
-            const removed = unsetKey(absPath, args.key);
-            output("vault-unset", { ref: makeVaultRef(name, source), key: args.key, removed });
+            createEnv(absPath);
+            if (args.sensitive) {
+                const markerPath = absPath.replace(/\.env$/, ".sensitive");
+                if (!fs.existsSync(markerPath))
+                    fs.writeFileSync(markerPath, "", { mode: 0o600 });
+            }
+            output("env-create", { ref: makeEnvRef(parsed.name, source) });
         });
     },
 });
 const vaultPathCommand = defineCommand({
+    meta: { name: "path", description: "DEPRECATED — use `akm env path`." },
+    args: {
+        ref: { type: "positional", description: "Env ref", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            emitVaultDeprecation("path");
+            const { name, absPath, source } = resolveEnvPath(args.ref);
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
+            }
+            process.stderr.write(`warning: sourcing the raw file executes shell substitutions it contains. Use: akm env run ${args.ref} -- <command>\n`);
+            process.stdout.write(`${absPath}\n`);
+        });
+    },
+});
+const vaultRunCommand = defineCommand({
+    meta: { name: "run", description: "DEPRECATED — use `akm env run`. The single-key `<ref>/KEY` form was removed." },
+    args: {
+        target: { type: "positional", description: "Env ref", required: true },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            emitVaultDeprecation("run");
+            await runEnvInjected(args.target, { viaVault: true });
+        });
+    },
+});
+const vaultCommand = defineCommand({
+    meta: {
+        name: "vault",
+        description: "DEPRECATED (use `akm env`) — removed in 0.9.0. Manages whole `.env` files; values never printed.",
+    },
+    subCommands: {
+        list: vaultListCommand,
+        path: vaultPathCommand,
+        run: vaultRunCommand,
+        create: vaultCreateCommand,
+        set: vaultSetCommand,
+        unset: vaultUnsetCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, VAULT_SUBCOMMAND_SET))
+                return;
+            emitVaultDeprecation("list");
+            const { listKeys } = await import("./commands/env.js");
+            output("env-list", { envs: listEnvsRecursive(listKeys) });
+        });
+    },
+});
+// ── secret ──────────────────────────────────────────────────────────────────
+//
+// `akm secret` manages whole-file secrets under each stash's secrets/ directory.
+// Unlike vaults (.env key/value), the ENTIRE file is the secret value. The bytes
+// are NEVER written to stdout or structured output. Values reach a command only
+// via `akm secret run` (injected into a child env var) or `akm secret path`
+// (the Docker /run/secrets + `_FILE` convention).
+function parseSecretRef(ref) {
+    return parseAssetRef(ref.includes(":") ? ref : `secret:${ref}`);
+}
+function makeSecretRef(name, source) {
+    return source?.registryId ? `${source.registryId}//secret:${name}` : `secret:${name}`;
+}
+function resolveSecretPath(ref) {
+    const parsed = parseSecretRef(ref);
+    if (parsed.type !== "secret") {
+        throw new UsageError(`Expected a secret ref (secret:<name>); got "${ref}".`);
+    }
+    // Source resolution is identical for every asset type; reuse the env helper.
+    const source = findEnvSource(parsed.origin);
+    const typeRoot = path.join(source.path, "secrets");
+    const absPath = resolveAssetPathFromName("secret", typeRoot, parsed.name);
+    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
+    }
+    return { name: parsed.name, absPath, source };
+}
+/** Walk `secrets/` across all stashes, returning one entry per secret file. */
+function listSecretsRecursive() {
+    const result = [];
+    for (const source of resolveSourceEntries(undefined, loadConfig())) {
+        const secretsDir = path.join(source.path, "secrets");
+        if (!fs.existsSync(secretsDir))
+            continue;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (entry.name.endsWith(".lock") || entry.name.endsWith(".sensitive"))
+                    continue;
+                // A sibling `<name>.sensitive` marker suppresses listing.
+                if (fs.existsSync(`${full}.sensitive`))
+                    continue;
+                const canonical = deriveCanonicalAssetName("secret", secretsDir, full);
+                if (!canonical)
+                    continue;
+                result.push({ ref: makeSecretRef(canonical, source), path: full });
+            }
+        };
+        walk(secretsDir);
+    }
+    return result;
+}
+const secretListCommand = defineCommand({
+    meta: {
+        name: "list",
+        description: "List all secrets across all stashes by name (the file contents are never shown)",
+    },
+    run() {
+        return runWithJsonErrors(async () => {
+            output("secret-list", { secrets: listSecretsRecursive() });
+        });
+    },
+});
+const secretSetCommand = defineCommand({
+    meta: {
+        name: "set",
+        description: "Create or overwrite a secret. The value is read from stdin by default (never via argv). Use --from-file <path> to import an existing file byte-exact, or --from-env <VAR> to read from an environment variable. Multi-line values are allowed.",
+    },
+    args: {
+        ref: { type: "positional", description: "Secret ref (e.g. secret:deploy-key or just deploy-key)", required: true },
+        "from-file": { type: "string", description: "Read the value from this file (stored byte-exact)" },
+        "from-env": { type: "string", description: "Read the value from the named environment variable" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { setSecret } = await import("./commands/secret.js");
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            const fromEnv = getHyphenatedArg(args, "from-env");
+            const fromFile = getHyphenatedArg(args, "from-file");
+            if (fromEnv !== undefined && fromFile !== undefined) {
+                throw new UsageError("Pass only one of --from-file or --from-env (or use stdin).", "INVALID_FLAG_VALUE");
+            }
+            const MAX_SECRET_BYTES = 5 * 1024 * 1024; // 5 MB
+            let value;
+            if (fromFile !== undefined) {
+                if (!fs.existsSync(fromFile)) {
+                    throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
+                }
+                value = fs.readFileSync(fromFile);
+                if (value.byteLength > MAX_SECRET_BYTES) {
+                    throw new UsageError("Secret exceeds the 5 MB limit.");
+                }
+            }
+            else if (fromEnv !== undefined) {
+                const envVal = process.env[fromEnv];
+                if (envVal === undefined) {
+                    throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
+                }
+                value = Buffer.from(envVal, "utf8");
+            }
+            else {
+                if (process.stdin.isTTY) {
+                    process.stderr.write(`Enter value for secret "${name}" (Ctrl-D when done):\n`);
+                }
+                let totalBytes = 0;
+                const chunks = [];
+                for await (const chunk of Bun.stdin.stream()) {
+                    totalBytes += chunk.byteLength;
+                    if (totalBytes > MAX_SECRET_BYTES) {
+                        throw new UsageError("Secret exceeds the 5 MB limit.");
+                    }
+                    chunks.push(chunk);
+                }
+                // Strip a single trailing newline so `echo "$TOKEN" | akm secret set`
+                // stores the token without the shell-added newline. Use --from-file for
+                // byte-exact storage of multi-line material (PEM keys, certs).
+                value = Buffer.from(Buffer.concat(chunks).toString("utf8").replace(/\n$/, ""), "utf8");
+            }
+            setSecret(absPath, value);
+            output("secret-set", { ref: makeSecretRef(name, source) });
+        });
+    },
+});
+const secretPathCommand = defineCommand({
     meta: {
         name: "path",
-        description: 'Print the absolute vault file path so you can load it directly, e.g. `source "$(akm vault path vault:prod)"`.',
+        description: "Print the absolute secret file path for the Docker `_FILE` convention, e.g. `MY_SECRET_FILE=$(akm secret path secret:deploy-key)`.",
     },
     args: {
-        ref: { type: "positional", description: "Vault ref", required: true },
+        ref: { type: "positional", description: "Secret ref", required: true },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { name, absPath, source } = resolveVaultPath(args.ref);
+            const { name, absPath, source } = resolveSecretPath(args.ref);
             if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
             }
             process.stdout.write(`${absPath}\n`);
         });
     },
 });
-const vaultRunCommand = defineCommand({
+const secretRunCommand = defineCommand({
     meta: {
         name: "run",
-        description: "Run a command with env injected from a vault or a single vault key: `akm vault run <ref[/KEY]> -- <command>`",
+        description: "Run a command with a secret's value injected into an env var: `akm secret run <ref> <VAR> -- <command>`. The value is set as $VAR in the child process only.",
     },
     args: {
-        target: { type: "positional", description: "Vault ref or ref/key target", required: true },
+        ref: { type: "positional", description: "Secret ref", required: true },
+        var: { type: "positional", description: "Environment variable name to inject the value into", required: true },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
+            // Validate the target env var name FIRST (before the command split) so a
+            // dangerous/invalid name is rejected regardless of how the command is
+            // supplied — and so the failure does not depend on argv parsing.
+            const varName = args.var;
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) {
+                throw new UsageError(`"${varName}" is not a valid environment variable name.`, "INVALID_FLAG_VALUE");
+            }
+            const { isDangerousEnvKey } = await import("./commands/lint/env-key-rules.js");
+            if (isDangerousEnvKey(varName)) {
+                throw new UsageError(`Refusing to inject a secret into "${varName}": it is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`, "INVALID_FLAG_VALUE");
+            }
             const dashIndex = process.argv.indexOf("--");
             if (dashIndex < 0 || dashIndex === process.argv.length - 1) {
-                throw new UsageError("Missing command. Usage: akm vault run <ref[/KEY]> -- <command>");
+                throw new UsageError("Missing command. Usage: akm secret run <ref> <VAR> -- <command>");
             }
             const command = process.argv.slice(dashIndex + 1);
-            const { loadEnv } = await import("./commands/vault.js");
-            const { ref, key } = splitVaultRunTarget(args.target);
-            const { name, absPath, source } = resolveVaultPath(ref);
+            const { name, absPath, source } = resolveSecretPath(args.ref);
             if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
             }
-            const envValues = loadEnv(absPath);
+            const { readValue } = await import("./commands/secret.js");
             const mergedEnv = { ...process.env };
-            if (key) {
-                if (!(key in envValues)) {
-                    throw new NotFoundError(`Key not found in ${makeVaultRef(name, source)}: ${key}`);
-                }
-                mergedEnv[key] = envValues[key];
-            }
-            else {
-                for (const [envKey, envValue] of Object.entries(envValues)) {
-                    mergedEnv[envKey] = envValue;
-                }
-            }
-            // Emit vault access event (keys only, no values) for audit trail.
-            // Best-effort: never block vault run on event write failure.
+            mergedEnv[varName] = readValue(absPath).toString("utf8");
+            // Audit trail: record access by ref + var name only — never the value.
             appendEvent({
-                eventType: "vault_access",
-                ref: makeVaultRef(name, source),
-                metadata: {
-                    keys: key ? [key] : Object.keys(envValues),
-                },
+                eventType: "secret_access",
+                ref: makeSecretRef(name, source),
+                metadata: { var: varName },
             });
             const result = spawnSync(command[0], command.slice(1), {
                 stdio: "inherit",
                 env: mergedEnv,
             });
-            if (result.error)
-                throw result.error;
+            if (result.error) {
+                const err = result.error;
+                if (err.code === "ENOENT") {
+                    throw new NotFoundError(`Command not found: ${command[0]}`, "FILE_NOT_FOUND", `Install '${command[0]}' or add its directory to PATH before invoking 'akm secret run'.`);
+                }
+                if (err.code === "EACCES") {
+                    throw new ConfigError(`Command not executable: ${command[0]}`, "STASH_DIR_UNREADABLE", `Add execute permission ('chmod +x ${command[0]}') or invoke via an interpreter.`);
+                }
+                throw err;
+            }
             process.exit(result.status ?? 0);
         });
     },
 });
-const vaultCommand = defineCommand({
+const secretRemoveCommand = defineCommand({
+    meta: { name: "remove", description: "Remove a secret (and its .sensitive marker, if any)" },
+    args: {
+        ref: { type: "positional", description: "Secret ref", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const { name, absPath, source } = resolveSecretPath(args.ref);
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove secret "${args.ref}"? This cannot be undone.`, {
+                yes: args.yes === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
+            }
+            const { removeSecret } = await import("./commands/secret.js");
+            if (!fs.existsSync(absPath)) {
+                throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
+            }
+            const removed = removeSecret(absPath);
+            output("secret-remove", { ref: makeSecretRef(name, source), removed });
+        });
+    },
+});
+const secretCommand = defineCommand({
     meta: {
-        name: "vault",
-        description: "Manage secret vaults (.env files). Keys are visible, values stay on disk and never appear in structured output.",
+        name: "secret",
+        description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
     },
     subCommands: {
-        list: vaultListCommand,
-        path: vaultPathCommand,
-        run: vaultRunCommand,
-        create: vaultCreateCommand,
-        set: vaultSetCommand,
-        unset: vaultUnsetCommand,
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, VAULT_SUBCOMMAND_SET))
+            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
                 return;
-            // Default action: list all vaults
-            const { listKeys } = await import("./commands/vault.js");
-            output("vault-list", { vaults: listVaultsRecursive(listKeys) });
+            output("secret-list", { secrets: listSecretsRecursive() });
         });
     },
 });
@@ -2329,11 +2674,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)" },
     },
@@ -2344,7 +2684,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);
@@ -2383,9 +2722,15 @@ const wikiRemoveCommand = defineCommand({
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
+        yes: {
+            type: "boolean",
+            alias: "y",
+            description: "Skip confirmation prompt (required in non-interactive shells)",
+            default: false,
+        },
         force: {
             type: "boolean",
-            description: "Remove without prompting (required in non-interactive shells)",
+            description: "DEPRECATED — use -y/--yes. Removed in 0.9.0.",
             default: false,
         },
         "with-sources": {
@@ -2396,8 +2741,16 @@ const wikiRemoveCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (!args.force) {
-                throw new UsageError("Refusing to remove without --force. Pass `--force` to confirm.");
+            if (args.yes !== true && args.force === true) {
+                emitFlagDeprecation("--force", "-y/--yes", "wiki remove");
+            }
+            const { confirmDestructive } = await import("./cli/confirm.js");
+            const confirmed = await confirmDestructive(`Remove wiki "${args.name}"? This cannot be undone.`, {
+                yes: args.yes === true || args.force === true,
+            });
+            if (!confirmed) {
+                process.stderr.write("Aborted.\n");
+                return;
             }
             const withSources = getHyphenatedBoolean(args, "with-sources");
             const { removeWiki } = await import("./wiki/wiki.js");
@@ -2525,17 +2878,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,
+            });
         });
     },
 });
@@ -2626,9 +3014,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
@@ -2663,121 +3051,631 @@ const eventsTailCommand = defineCommand({
             if (!stream) {
                 output("events-tail", result);
             }
-            else if (mode.format === "jsonl") {
-                // Final discriminated trailer row so jsonl consumers can resume.
-                const trailer = {
-                    _kind: "trailer",
-                    schemaVersion: 1,
-                    nextOffset: result.nextOffset,
-                    totalCount: result.totalCount,
-                    reason: result.reason,
-                };
-                console.log(JSON.stringify(trailer));
+            else if (mode.format === "jsonl") {
+                // Final discriminated trailer row so jsonl consumers can resume.
+                const trailer = {
+                    _kind: "trailer",
+                    schemaVersion: 1,
+                    nextOffset: result.nextOffset,
+                    totalCount: result.totalCount,
+                    reason: result.reason,
+                };
+                console.log(JSON.stringify(trailer));
+            }
+            else {
+                // text mode: keep stdout pristine for line-oriented parsers and
+                // emit the trailer on stderr.
+                process.stderr.write(`[events-tail] reason=${result.reason} nextOffset=${result.nextOffset} total=${result.totalCount}\n`);
+            }
+        });
+    },
+});
+const eventsCommand = defineCommand({
+    meta: {
+        name: "events",
+        alias: "log",
+        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",
+        alias: "lesson",
+        description: "Lesson-asset tooling: tag-coverage gaps, strength queries.",
+    },
+    subCommands: {
+        coverage: lessonsCoverageCommand,
+    },
+});
+// ── proposal substrate (#225) ────────────────────────────────────────────────
+const proposalListCommand = defineCommand({
+    meta: { name: "list", description: "List proposal queue entries" },
+    args: {
+        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(() => {
+            const status = parseProposalStatus(args.status);
+            const result = akmProposalList({
+                status,
+                ref: args.ref,
+                type: args.type,
+                includeArchive: status === "accepted" || status === "rejected" || status === "reverted",
+            });
+            output("proposal-list", result);
+        });
+    },
+});
+const proposalAcceptCommand = defineCommand({
+    meta: { name: "accept", description: "Accept a proposal and promote it into the stash" },
+    args: {
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --generator is provided.",
+            required: false,
+        },
+        target: { type: "string", description: "Override the write target by source name" },
+        // F-6 / #393: Batch accept by generator, diff size, or age.
+        generator: {
+            type: "string",
+            description: "F-6: Bulk-accept all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
+        },
+        source: {
+            type: "string",
+            description: "DEPRECATED — use --generator. Removed in 0.9.0.",
+        },
+        "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,
+        },
+        yes: {
+            type: "boolean",
+            alias: "y",
+            description: "Skip confirmation prompt (required in non-interactive mode for bulk accept)",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            if (args.generator === undefined && args.source !== undefined) {
+                emitFlagDeprecation("--source", "--generator", "proposal accept");
+            }
+            const generator = (args.generator ?? args.source);
+            // F-6 / #393: Bulk-accept when --generator is provided without a positional id.
+            if (generator && !args.id) {
+                const { confirmDestructive } = await import("./cli/confirm.js");
+                const confirmed = await confirmDestructive(`Bulk-accept all matching proposals from generator "${generator}"? 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 !== generator)
+                        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 proposal accept <id>  OR  akm proposal accept --generator <generator>", "MISSING_REQUIRED_ARGUMENT");
+            }
+            const result = await akmProposalAccept({ id: args.id, target: args.target });
+            output("proposal-accept", result);
+        });
+    },
+});
+const proposalRejectCommand = defineCommand({
+    meta: { name: "reject", description: "Reject a proposal and record the reason" },
+    args: {
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream). Optional when --generator is provided.",
+            required: false,
+        },
+        reason: { type: "string", description: "Reason for rejection (required)" },
+        // F-6 / #393: Batch reject by generator, diff size, or age.
+        generator: {
+            type: "string",
+            description: "F-6: Bulk-reject all pending proposals from this generator (e.g. reflect, distill). Requires no positional id.",
+        },
+        source: {
+            type: "string",
+            description: "DEPRECATED — use --generator. Removed in 0.9.0.",
+        },
+        "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(async () => {
+            if (args.generator === undefined && args.source !== undefined) {
+                emitFlagDeprecation("--source", "--generator", "proposal reject");
+            }
+            const generator = (args.generator ?? args.source);
+            if (!args.reason || !String(args.reason).trim()) {
+                throw new UsageError("Usage: akm proposal reject <id> --reason '<reason>'  OR  akm proposal reject --generator <generator> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
+            }
+            // F-6 / #393: Bulk-reject when --generator is provided without a positional id.
+            if (generator && !args.id) {
+                const { confirmDestructive } = await import("./cli/confirm.js");
+                const confirmed = await confirmDestructive(`Bulk-reject all matching proposals from generator "${generator}"? 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 !== generator)
+                        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 proposal reject <id> --reason '<reason>'  OR  akm proposal reject --generator <generator> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
             }
-            else {
-                // text mode: keep stdout pristine for line-oriented parsers and
-                // emit the trailer on stderr.
-                process.stderr.write(`[events-tail] reason=${result.reason} nextOffset=${result.nextOffset} total=${result.totalCount}\n`);
+            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);
         });
     },
 });
-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 state.db events stream (mutations, feedback, indexing)",
-    },
-    subCommands: {
-        list: eventsListCommand,
-        tail: eventsTailCommand,
-    },
-});
-// ── proposal substrate (#225) ────────────────────────────────────────────────
-const proposalsCommand = defineCommand({
-    meta: { name: "proposals", description: "List proposal queue entries" },
+const proposalDiffCommand = defineCommand({
+    meta: { name: "diff", description: "Show the diff for a proposal (accepts full UUID, UUID prefix, or asset ref)" },
     args: {
-        status: { type: "string", description: "Filter by status (pending|accepted|rejected)" },
-        ref: { type: "string", description: "Filter by asset ref (type:name)" },
-        type: { type: "string", description: "Filter by asset type" },
+        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 }) {
         return runWithJsonErrors(() => {
-            const status = parseProposalStatus(args.status);
-            const result = akmProposalList({
-                status,
-                ref: args.ref,
-                includeArchive: status === "accepted" || status === "rejected",
-            });
-            output("proposal-list", result);
+            const result = akmProposalDiff({ id: args.id, target: args.target });
+            output("proposal-diff", result);
         });
     },
 });
-const acceptCommand = defineCommand({
-    meta: { name: "accept", description: "Accept a proposal and promote it into the stash" },
+// 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 proposalRevertCommand = defineCommand({
+    meta: {
+        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: {
         id: {
             type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            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 result = await akmProposalAccept({ id: args.id, target: args.target });
-            output("proposal-accept", result);
+            const result = await akmProposalRevert({
+                id: args.id,
+                target: args.target,
+            });
+            output("proposal-revert", result);
         });
     },
 });
-const rejectCommand = defineCommand({
-    meta: { name: "reject", description: "Reject a proposal and record the reason" },
+// `proposal show` (#225): show a single proposal with its validation findings.
+// `akmProposalShow` already backs `akm show proposal <id>` (now deprecated); this
+// is the canonical noun-group entry point.
+const proposalShowCommand = defineCommand({
+    meta: { name: "show", description: "Show a single proposal and its validation findings" },
     args: {
         id: {
             type: "positional",
             description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
             required: true,
         },
-        reason: { type: "string", description: "Reason for rejection (required)" },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            if (!args.reason || !String(args.reason).trim()) {
-                throw new UsageError("Usage: akm reject <id> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
+            const result = akmProposalShow({ id: args.id });
+            output("proposal-show", result);
+        });
+    },
+});
+const proposalDrainCommand = defineCommand({
+    meta: {
+        name: "drain",
+        description: "Drain the standing pending proposal backlog using a deterministic triage policy",
+    },
+    args: {
+        policy: {
+            type: "string",
+            description: "Built-in preset (personal-stash|conservative|manual) or path to a policy file",
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "List what would be accepted/rejected/deferred without writing.",
+            default: false,
+        },
+        yes: {
+            type: "boolean",
+            alias: "y",
+            description: "Skip confirmation prompt (required in non-interactive mode for promotion).",
+            default: false,
+        },
+        "max-accepts": {
+            type: "string",
+            description: "Hard per-run accept ceiling. Accepts beyond this are reported as skippedByCap.",
+        },
+        "max-diff-lines": {
+            type: "string",
+            description: "Defer (never promote) accepts whose proposed content exceeds this many lines.",
+        },
+        "older-than": {
+            type: "string",
+            description: "Only consider proposals created more than this many days ago.",
+        },
+        promote: {
+            type: "boolean",
+            description: "Promote (accept) matching proposals. Default is queue mode (stage only, no writes to assets).",
+            default: false,
+        },
+        judgment: {
+            type: "boolean",
+            description: "Opt into the judgment tier (llm by default; agent/sdk per config) for deferred items. No-op with a logged triage_deferred summary when no runner is configured.",
+            default: false,
+        },
+        profile: {
+            type: "string",
+            description: "Read the triage block (policy, applyMode, ceilings, judgment) from this improve profile.",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const stashDir = resolveStashDir();
+            const cfg = loadConfig();
+            // Phase 2: read the triage block from the named improve profile. CLI flags
+            // always override config; config supplies defaults for any flag omitted.
+            const triageConfig = args.profile !== undefined ? resolveImproveProfile(args.profile, cfg).processes?.triage : undefined;
+            const policy = resolveDrainPolicy(args.policy ?? triageConfig?.policy);
+            const dryRun = args["dry-run"] === true;
+            const applyMode = args.promote === true ? "promote" : (triageConfig?.applyMode ?? "queue");
+            const maxAccepts = parsePositiveIntFlag(args["max-accepts"], "--max-accepts") ??
+                triageConfig?.maxAcceptsPerRun ??
+                25;
+            const maxDiffLines = parsePositiveIntFlag(args["max-diff-lines"], "--max-diff-lines") ??
+                triageConfig?.maxDiffLines;
+            const rawOlderThan = parsePositiveIntFlag(args["older-than"], "--older-than");
+            const olderThanMs = rawOlderThan !== undefined ? rawOlderThan * 86_400_000 : undefined;
+            // Promotion in promote mode is destructive (commits to git, no batch revert).
+            if (applyMode === "promote" && !dryRun) {
+                const { confirmDestructive } = await import("./cli/confirm.js");
+                const confirmed = await confirmDestructive(`Drain and promote matching pending proposals under policy "${policy.name}"? Promotions commit to git and cannot be batch-reverted.`, { yes: args.yes === true });
+                if (!confirmed) {
+                    process.stderr.write("Aborted.\n");
+                    return;
+                }
             }
-            const result = akmProposalReject({ id: args.id, reason: args.reason });
-            output("proposal-reject", result);
+            // `--older-than` is applied here as a pre-filter on excludeIds: ids that
+            // are too fresh are excluded so the engine never touches them. This reads
+            // the pending set once here; drainProposals reads the pending set again
+            // internally, so a future engine-level olderThan option could remove this
+            // second read (engine API owned by another agent — not changed here).
+            let excludeIds;
+            if (olderThanMs !== undefined) {
+                const { listProposals } = await import("./core/proposals");
+                const now = Date.now();
+                excludeIds = new Set(listProposals(stashDir, { status: "pending" })
+                    // Fail SAFE: exclude a proposal when its age cannot be computed
+                    // (NaN createdAt) OR it is too fresh. An unparseable createdAt must
+                    // never be treated as old enough to drain/promote.
+                    .filter((proposal) => {
+                    const age = now - new Date(proposal.createdAt).getTime();
+                    return Number.isNaN(age) || age < olderThanMs;
+                })
+                    .map((proposal) => proposal.id));
+            }
+            // Phase 3: resolve the judgment runner when --judgment is set. Default
+            // mode is llm; falls back to defaults.llm when the triage block sets
+            // neither mode nor profile (mirrors resolveValidationRunner). null when
+            // nothing is configured → the engine leaves deferred items unresolved and
+            // emits triage_deferred.
+            const judgment = args.judgment === true ? resolveTriageJudgmentRunner(triageConfig?.judgment, cfg) : null;
+            const result = await drainProposals({
+                stashDir,
+                policy,
+                applyMode,
+                maxAccepts,
+                dryRun,
+                ...(maxDiffLines !== undefined ? { maxDiffLines } : {}),
+                ...(excludeIds ? { excludeIds } : {}),
+                judgment,
+            });
+            output("proposal-drain", {
+                schemaVersion: 1,
+                ok: true,
+                policy: policy.name,
+                applyMode,
+                dryRun,
+                promoted: result.promoted,
+                rejected: result.rejected,
+                deferred: result.deferred,
+                skippedByCap: result.skippedByCap,
+            });
         });
     },
 });
-const diffCommand = defineCommand({
-    meta: { name: "diff", description: "Show the diff for a proposal (accepts full UUID, UUID prefix, or asset ref)" },
+// ── proposal noun group (#225 / 0.8 CLI stabilization) ────────────────────────
+//
+// `akm proposal <verb>` is the canonical grammar in 0.8. The flat verbs
+// (`proposals`/`accept`/`reject`/`diff`/`revert`) remain as deprecated aliases
+// that warn to stderr and delegate to the same command bodies; they are removed
+// in 0.9.0. Bare `akm proposal` behaves as `proposal list` (mirrors `akm env`).
+const PROPOSAL_SUBCOMMAND_SET = new Set(["list", "show", "diff", "accept", "reject", "revert", "drain"]);
+function emitProposalVerbDeprecation(oldVerb, canonical) {
+    if (isQuiet())
+        return;
+    process.stderr.write(`warning: 'akm ${oldVerb}' is deprecated and will be removed in 0.9.0. Use 'akm ${canonical}'.\n`);
+}
+const proposalCommand = defineCommand({
+    meta: { name: "proposal", description: "Manage the proposal queue: list, show, diff, accept, reject, revert" },
     args: {
-        id: {
-            type: "positional",
-            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
-            required: true,
+        status: {
+            type: "string",
+            description: "Filter by status (pending|accepted|rejected|reverted)",
         },
-        target: { type: "string", description: "Override the write target by source name" },
+        ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        type: { type: "string", description: "Filter by asset type" },
+    },
+    subCommands: {
+        list: proposalListCommand,
+        show: proposalShowCommand,
+        diff: proposalDiffCommand,
+        accept: proposalAcceptCommand,
+        reject: proposalRejectCommand,
+        revert: proposalRevertCommand,
+        drain: proposalDrainCommand,
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            const result = akmProposalDiff({ id: args.id, target: args.target });
-            output("proposal-diff", result);
+            // citty runs the group body even after a subcommand; short-circuit so the
+            // default-to-list body only fires for bare `akm proposal [--status …]`.
+            if (hasSubcommand(args, PROPOSAL_SUBCOMMAND_SET))
+                return;
+            const status = parseProposalStatus(args.status);
+            const result = akmProposalList({
+                status,
+                ref: args.ref,
+                type: args.type,
+                includeArchive: status === "accepted" || status === "rejected" || status === "reverted",
+            });
+            output("proposal-list", result);
         });
     },
 });
+// Deprecated flat-verb aliases (removed 0.9.0). Each wraps the canonical command
+// body so bulk/guard logic is not duplicated.
+const proposalsCommand = defineCommand({
+    meta: { name: "proposals", description: "DEPRECATED — use `akm proposal list`. Removed in 0.9.0." },
+    args: proposalListCommand.args,
+    run(ctx) {
+        emitProposalVerbDeprecation("proposals", "proposal list");
+        return proposalListCommand.run?.(ctx);
+    },
+});
+const acceptCommand = defineCommand({
+    meta: { name: "accept", description: "DEPRECATED — use `akm proposal accept`. Removed in 0.9.0." },
+    args: proposalAcceptCommand.args,
+    run(ctx) {
+        emitProposalVerbDeprecation("accept", "proposal accept");
+        return proposalAcceptCommand.run?.(ctx);
+    },
+});
+const rejectCommand = defineCommand({
+    meta: { name: "reject", description: "DEPRECATED — use `akm proposal reject`. Removed in 0.9.0." },
+    args: proposalRejectCommand.args,
+    run(ctx) {
+        emitProposalVerbDeprecation("reject", "proposal reject");
+        return proposalRejectCommand.run?.(ctx);
+    },
+});
+const diffCommand = defineCommand({
+    meta: { name: "diff", description: "DEPRECATED — use `akm proposal diff`. Removed in 0.9.0." },
+    args: proposalDiffCommand.args,
+    run(ctx) {
+        emitProposalVerbDeprecation("diff", "proposal diff");
+        return proposalDiffCommand.run?.(ctx);
+    },
+});
+const revertCommand = defineCommand({
+    meta: { name: "revert", description: "DEPRECATED — use `akm proposal revert`. Removed in 0.9.0." },
+    args: proposalRevertCommand.args,
+    run(ctx) {
+        emitProposalVerbDeprecation("revert", "proposal revert");
+        return proposalRevertCommand.run?.(ctx);
+    },
+});
 // ── distill (#228) ──────────────────────────────────────────────────────────
 function parseProposalStatus(raw) {
     if (raw === undefined)
@@ -2785,50 +3683,85 @@ function parseProposalStatus(raw) {
     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");
 }
 const agentCommand = defineCommand({
     meta: {
         name: "agent",
-        description: "Dispatch an agent by named profile, optionally injecting a prompt from inline text, a stash command: asset, or a stash workflow: asset",
+        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: {
         profile: {
             type: "positional",
-            description: "Agent profile name (from config.agent.profiles or a built-in)",
+            description: "Agent profile / platform to use (opencode, claude, …)",
+            required: false,
+        },
+        "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: "Inline prompt text to pass to the agent" },
-        command: { type: "string", description: "Load the body of a command: asset from the index and use as the prompt" },
-        workflow: {
+        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: "Load the body of a workflow: asset from the index and use as the prompt",
+            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 () => {
             if (!args.profile) {
-                throw new UsageError("Usage: akm agent <profile> [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in config.agent.profiles.");
+                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.");
             }
-            // Collect extra positional args (forwarded to the agent and used as
-            // template placeholders when a command/workflow ref is specified).
-            const extraArgs = Array.isArray(args._) ? args._.filter((a) => a !== args.profile) : [];
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
             const config = loadConfig();
-            const { parseAgentConfig } = await import("./integrations/agent/config.js");
-            const agentConfig = parseAgentConfig(config.agent);
+            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: typeof args.prompt === "string" ? args.prompt : undefined,
-                commandRef: typeof args.command === "string" && args.command.trim() ? args.command.trim() : undefined,
-                workflowRef: typeof args.workflow === "string" && args.workflow.trim() ? args.workflow.trim() : undefined,
-                args: extraArgs.length > 0 ? extraArgs : undefined,
+                prompt: promptText,
+                commandRef,
+                workflowRef,
                 agentConfig,
-                llmConfig: config.llm,
+                llmConfig: getDefaultLlmConfig(config),
+                ...(hasDispatchContent
+                    ? {
+                        dispatch: {
+                            prompt: promptText ?? "",
+                            systemPrompt,
+                            model,
+                            tools: assetTools,
+                        },
+                    }
+                    : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });
             output("agent-result", result);
@@ -2841,159 +3774,29 @@ const agentCommand = defineCommand({
 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.",
+        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. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
         fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
         dir: { type: "string", description: "Override stash root directory (default: from config)" },
+        "fail-on-flagged": {
+            type: "boolean",
+            description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = akmLint({
                 fix: args.fix ?? false,
-                dir: typeof args.dir === "string" && args.dir.trim() ? args.dir.trim() : undefined,
+                dir: getStringArg(args, "dir"),
             });
             output("lint", result);
-            if (!result.ok)
+            if (args["fail-on-flagged"] && result.summary.flagged > 0)
                 process.exit(EXIT_GENERAL);
         });
     },
 });
-const improveCommand = defineCommand({
-    meta: {
-        name: "improve",
-        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when llm.features.memory_consolidation is enabled",
-    },
-    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: "Automatically accept low-risk proposals (only 'safe' is supported)",
-        },
-        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 (default: 7, 0 to disable)",
-        },
-        "distill-cooldown-days": {
-            type: "string",
-            description: "Override distill cooldown for this run only (default: 30, 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: 5)",
-        },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const autoAcceptRaw = getHyphenatedArg(args, "auto-accept");
-            if (autoAcceptRaw !== undefined && autoAcceptRaw !== "safe") {
-                throw new UsageError("--auto-accept only supports the value 'safe'.", "INVALID_FLAG_VALUE");
-            }
-            const targetArg = typeof args.target === "string" && args.target.trim() ? args.target.trim() : undefined;
-            const taskArg = typeof args.task === "string" && args.task.trim() ? args.task : undefined;
-            const dryRun = getHyphenatedBoolean(args, "dry-run");
-            const autoAccept = autoAcceptRaw === "safe" ? "safe" : undefined;
-            const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
-            const timeoutRaw = getHyphenatedArg(args, "timeout-ms");
-            const timeoutMs = timeoutRaw !== undefined ? parseInt(timeoutRaw, 10) : undefined;
-            if (timeoutMs !== undefined && (Number.isNaN(timeoutMs) || timeoutMs <= 0)) {
-                throw new UsageError(`Invalid --timeout-ms value: "${timeoutRaw}". Must be a positive integer.`);
-            }
-            const parseNonNegativeCooldownDays = (raw, flagName) => {
-                if (raw === undefined)
-                    return undefined;
-                if (!/^\d+$/.test(raw.trim())) {
-                    throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a non-negative integer.`);
-                }
-                return parseInt(raw, 10);
-            };
-            const ignoreCooldown = getHyphenatedBoolean(args, "ignore-cooldown");
-            const reflectCooldownRaw = getHyphenatedArg(args, "reflect-cooldown-days");
-            const reflectCooldownDays = ignoreCooldown
-                ? 0
-                : parseNonNegativeCooldownDays(reflectCooldownRaw, "--reflect-cooldown-days");
-            const distillCooldownRaw = getHyphenatedArg(args, "distill-cooldown-days");
-            const distillCooldownDays = ignoreCooldown
-                ? 0
-                : parseNonNegativeCooldownDays(distillCooldownRaw, "--distill-cooldown-days");
-            const consolidateCooldownRaw = getHyphenatedArg(args, "consolidate-cooldown-days");
-            const consolidateCooldownDays = ignoreCooldown
-                ? 0
-                : parseNonNegativeCooldownDays(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 = parseNonNegativeCooldownDays(minRetrievalCountRaw, "--min-retrieval-count");
-            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
-            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
-            setLogFile(improveLogFile);
-            let improveResult;
-            try {
-                improveResult = await akmImprove({
-                    scope: typeof args.scope === "string" && args.scope.trim() ? args.scope : undefined,
-                    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 } : {}),
-                    consolidateOptions: {
-                        target: targetArg,
-                        dryRun,
-                        autoAccept,
-                        task: taskArg,
-                        ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
-                    },
-                });
-            }
-            finally {
-                clearLogFile();
-            }
-            output("improve", improveResult);
-            process.exit(0);
-        });
-    },
-});
 const proposeCommand = defineCommand({
     meta: {
         name: "propose",
@@ -3024,14 +3827,13 @@ const proposeCommand = defineCommand({
                 throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
             }
             const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
             const result = await akmPropose({
                 type: String(args.type),
                 name: String(args.name),
                 task: taskText,
-                profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
-                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+                profile: getStringArg(args, "profile"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("propose", result);
             if (result.ok === false) {
@@ -3052,7 +3854,16 @@ const TASKS_SUBCOMMAND_SET = new Set([
     "sync",
     "doctor",
 ]);
-const GRAPH_SUBCOMMAND_SET = new Set(["summary", "entities", "relations", "related", "export"]);
+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: {
@@ -3063,8 +3874,14 @@ const tasksAddCommand = defineCommand({
             type: "string",
             description: "Prompt for the configured agent harness — inline text, an asset ref like agent:foo, or ./path.md",
         },
-        profile: { type: "string", description: "Agent profile to use for prompt targets (default: config.agent.default)" },
+        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 },
@@ -3077,8 +3894,11 @@ const tasksAddCommand = defineCommand({
                 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
@@ -3124,28 +3944,25 @@ const tasksRemoveCommand = defineCommand({
         });
     },
 });
-const tasksEnableCommand = defineCommand({
-    meta: { name: "enable", description: "Enable a previously-disabled task" },
-    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, true);
-            output("tasks-enable", result);
-        });
-    },
-});
-const tasksDisableCommand = defineCommand({
-    meta: { name: "disable", description: "Disable a task in the OS scheduler without removing the file" },
-    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, false);
-            output("tasks-disable", 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",
@@ -3203,6 +4020,7 @@ const tasksDoctorCommand = defineCommand({
 const tasksCommand = defineCommand({
     meta: {
         name: "tasks",
+        alias: "task",
         description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
     },
     subCommands: {
@@ -3226,16 +4044,43 @@ const tasksCommand = defineCommand({
         });
     },
 });
-const main = defineCommand({
+export const main = defineCommand({
     meta: {
         name: "akm",
         version: pkgVersion,
-        description: "Agent Kit Manager — search, show, and manage assets from your stash.",
+        description: "Agent Knowledge Management — search, show, and manage assets from your stash.\n\n" +
+            "Exit codes:\n" +
+            "  0   success\n" +
+            "  1   general error / not found\n" +
+            "  2   usage error\n" +
+            "  4   health warn (akm health only)\n" +
+            "  78  config error",
     },
     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 (verbosity): brief|normal|full. Default: brief.",
+            default: "brief",
+        },
+        shape: {
+            type: "string",
+            description: "Output projection: human|agent|summary. 'agent' trims to agent-essential fields; " +
+                "'summary' is only valid on 'akm show'. Default: human.",
+        },
+        "for-agent": {
+            type: "boolean",
+            description: "DEPRECATED alias for '--shape agent' (removed 0.9.0).",
+            default: false,
+        },
+        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)",
@@ -3249,6 +4094,7 @@ const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
+        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -3260,6 +4106,8 @@ const main = defineCommand({
         workflow: workflowCommand,
         remember: rememberCommand,
         import: importKnowledgeCommand,
+        sync: syncCommand,
+        // Deprecated alias (removed 0.9.0) — delegates to `sync`.
         save: saveCommand,
         clone: cloneCommand,
         registry: registryCommand,
@@ -3269,24 +4117,33 @@ const main = defineCommand({
         feedback: feedbackCommand,
         history: historyCommand,
         events: eventsCommand,
+        lessons: lessonsCommand,
         agent: agentCommand,
         lint: lintCommand,
         improve: improveCommand,
+        extract: extractCommand,
         propose: proposeCommand,
+        proposal: proposalCommand,
+        // Deprecated flat verbs (removed 0.9.0) — delegate to `proposal <verb>`.
         proposals: proposalsCommand,
         accept: acceptCommand,
         reject: rejectCommand,
         diff: diffCommand,
+        revert: revertCommand,
         help: helpCommand,
         hints: hintsCommand,
         completions: completionsCommand,
+        env: envCommand,
         vault: vaultCommand,
+        secret: secretCommand,
         wiki: wikiCommand,
         tasks: tasksCommand,
     },
 });
-const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset"]);
+const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset", "enable", "disable"]);
+const ENV_SUBCOMMAND_SET = new Set(["list", "path", "export", "run", "create", "remove"]);
 const VAULT_SUBCOMMAND_SET = new Set(["list", "path", "run", "create", "set", "unset"]);
+const SECRET_SUBCOMMAND_SET = new Set(["list", "path", "run", "set", "remove"]);
 const WIKI_SUBCOMMAND_SET = new Set([
     "create",
     "register",
@@ -3300,74 +4157,90 @@ const WIKI_SUBCOMMAND_SET = new Set([
     "ingest",
 ]);
 // ── Exit codes ──────────────────────────────────────────────────────────────
-const EXIT_GENERAL = 1;
-const EXIT_USAGE = 2;
-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.
-process.argv = normalizeShowArgv(process.argv);
-// Resolve output mode once at startup from the (normalized) argv and persisted
-// config. All subsequent output() calls read from this in-memory singleton.
-// `initOutputMode` can throw a UsageError when --format/--detail values are
-// 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);
-}
-runMain(main);
-function classifyExitCode(error) {
-    if (error instanceof UsageError)
-        return EXIT_USAGE;
-    if (error instanceof ConfigError)
-        return EXIT_CONFIG;
-    if (error instanceof NotFoundError)
-        return EXIT_GENERAL;
-    return EXIT_GENERAL;
-}
-async function runWithJsonErrors(fn) {
+// Canonical table lives in `src/cli/shared.ts` (EXIT_CODES). These aliases keep
+// the local call sites terse. EXIT_HEALTH_WARN (4) is the `akm health` "warn"
+// status — advisories fired but no hard failure; chosen to avoid colliding with
+// GENERAL (1) and USAGE (2). CI monitors can map: 0=pass, 4=warn, 1=fail.
+const EXIT_GENERAL = EXIT_CODES.GENERAL;
+const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
+// Only run the CLI when this module is the direct entry point. When it is
+// imported (e.g. by the in-process test harness in tests/_helpers/cli.ts),
+// `import.meta.main` is false and we skip all startup side effects (argv
+// mutation, output-mode init, index cleanup, banner, runMain) so importers
+// can drive the `main` command themselves without the process exiting.
+if (import.meta.main) {
+    // citty reads process.argv directly and does not accept a custom argv array,
+    // so we must replace process.argv with the normalized version before runMain.
+    process.argv = normalizeShowArgv(process.argv);
+    // Resolve output mode once at startup from the (normalized) argv and persisted
+    // config. All subsequent output() calls read from this in-memory singleton.
+    // `initOutputMode` can throw a UsageError when --format/--detail values are
+    // 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);
-        await fn();
+        initOutputMode(process.argv, loadConfig().output ?? {});
     }
     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);
+        emitJsonError(error);
     }
-}
-/**
- * Extract an actionable hint from an error instance. Hints live on the error
- * classes themselves (see src/errors.ts) — either supplied explicitly at the
- * throw site, or derived from the error code via the per-class default mapping.
- */
-function extractHint(error) {
-    if (error instanceof Error && "hint" in error && typeof error.hint === "function") {
-        return error.hint();
+    // `--shape summary` is only meaningful on `akm show`. Reject it up front for
+    // every other command so a write command (e.g. `akm proposal accept …`)
+    // fails fast BEFORE performing its mutation, rather than throwing at
+    // output-shaping time after the side effect has already happened. The
+    // shape-registry gate in shapeForCommand() remains as defense-in-depth (and
+    // covers the in-process test harness, which skips this startup block).
+    if (getOutputMode().shape === "summary" && process.argv[2] !== "show") {
+        emitJsonError(new UsageError("'--shape summary' is only valid on 'akm show'.", "INVALID_SHAPE_VALUE"));
     }
-    return undefined;
+    // 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(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
+    })();
+    runMain(main);
 }
 // ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
 function loadHints(detail = "normal") {
-    const filename = detail === "full" ? "AGENTS.full.md" : "AGENTS.md";
-    const fallback = detail === "full" ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
+    // `brief` → the short AGENTS.md guide; `normal`/`full` → the complete guide.
+    const wantFull = detail !== "brief";
+    const filename = wantFull ? "AGENTS.full.md" : "AGENTS.md";
+    const fallback = wantFull ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
     // Try reading from the docs/ directory (works in dev and when installed via npm)
     try {
         const docsPath = path.resolve(import.meta.dir ?? __dirname, `../docs/agents/${filename}`);