akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/cli.js

@@ -1,39 +1,46 @@
 #!/usr/bin/env bun
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { defineCommand, runMain } from "citty";
+import { getStringArg, hasSubcommand, parseNonNegativeIntFlag, parsePositiveIntFlag } from "./cli/parse-args";
+import { akmAgentDispatch } from "./commands/agent-dispatch";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions";
 import { getConfigValue, listConfig, setConfigValue, unsetConfigValue } from "./commands/config-cli";
 import { akmCurate } from "./commands/curate";
-import { akmDistill } from "./commands/distill";
 import { akmEventsList, akmEventsTail } from "./commands/events";
+import { akmGraphEntities, akmGraphExport, akmGraphRelated, akmGraphRelations, akmGraphSummary, } from "./commands/graph";
+import { akmHealth } from "./commands/health";
 import { akmHistory } from "./commands/history";
+import { akmImprove } from "./commands/improve";
 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 { akmPropose } from "./commands/propose";
-import { akmReflect } from "./commands/reflect";
 import { searchRegistry } from "./commands/registry-search";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich, } from "./commands/remember";
-import { akmSearch, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "./commands/remember";
+import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
 import { checkForUpdate, performUpgrade } from "./commands/self-update";
-import { akmShowUnified } from "./commands/show";
+import { akmShowUnified, normalizeShowArgv } from "./commands/show";
 import { akmAdd } from "./commands/source-add";
 import { akmClone } from "./commands/source-clone";
 import { addStash } from "./commands/source-manage";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./commands/tasks";
 import { parseAssetRef } from "./core/asset-ref";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset-spec";
-import { isHttpUrl, isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
-import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, saveConfig } from "./core/config";
+import { isHttpUrl, isWithin, resolveStashDir } 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, getDbPath, getDefaultStashDir } from "./core/paths";
-import { setQuiet, setVerbose, warn } from "./core/warn";
-import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
-import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "./indexer/db";
+import { 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 { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
 import { insertUsageEvent } from "./indexer/usage-events";
@@ -45,16 +52,22 @@ import { buildRegistryIndex, writeRegistryIndex } from "./registry/build-index";
 import { resolveSourcesForOrigin } from "./registry/origin-resolve";
 import { saveGitStash } from "./sources/providers/git";
 import { resolveAssetPath } from "./sources/resolve";
-import { fetchWebsiteMarkdownSnapshot } from "./sources/website-ingest";
 import { pkgVersion } from "./version";
 import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "./workflows/authoring";
 import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "./workflows/cli";
 import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "./workflows/runs";
-const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 const SKILLS_SH_NAME = "skills.sh";
 const SKILLS_SH_URL = "https://skills.sh";
 const SKILLS_SH_PROVIDER = "skills-sh";
 import { stringify as yamlStringify } from "yaml";
+function applyEarlyStderrFlags(argv) {
+    if (argv.includes("--quiet") || argv.includes("-q")) {
+        setQuiet(true);
+    }
+    if (argv.includes("--verbose")) {
+        setVerbose(true);
+    }
+}
 /**
  * Collect all occurrences of a repeatable flag from process.argv.
  * Citty's StringArgDef only exposes the last value when a flag is repeated,
@@ -78,6 +91,43 @@ function parseAllFlagValues(flag) {
     }
     return values;
 }
+function resolveHelpMigrateVersionArg(version) {
+    if (version === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined &&
+        version === parsedFormat &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined &&
+        version === parsedDetail &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return version;
+}
+function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName) {
+    const argv = process.argv.slice(2);
+    const helpIndex = argv.indexOf("help");
+    const tokens = helpIndex >= 0 ? argv.slice(helpIndex + 1) : argv;
+    const migrateIndex = tokens.indexOf("migrate");
+    const relevant = migrateIndex >= 0 ? tokens.slice(migrateIndex + 1) : tokens;
+    let flagIndex = -1;
+    for (let i = 0; i < relevant.length; i += 1) {
+        const token = relevant[i];
+        if (token === flagName || token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (relevant.slice(0, flagIndex).includes(version))
+        return false;
+    return relevant[flagIndex] === flagName ? relevant[flagIndex + 1] === version : true;
+}
 function output(command, result) {
     const mode = getOutputMode();
     const shaped = shapeForCommand(command, result, mode.detail, mode.forAgent);
@@ -109,12 +159,57 @@ function output(command, result) {
 const setupCommand = defineCommand({
     meta: {
         name: "setup",
-        description: "Interactive configuration wizard: detects services and walks you through embeddings, LLM, registries, sources, and agent profiles. Writes config once at the end.",
+        description: "Interactive configuration wizard. Configures embeddings/LLM connections (for indexing/enrichment), agent profiles (CLI agent, embedded SDK, or none), sources, and registries. Shows which features are enabled at the end. Use --config <json> or --yes for non-interactive/scripting mode.",
     },
-    async run() {
+    args: {
+        config: {
+            type: "string",
+            description: 'Config JSON to apply non-interactively, e.g. \'{"llm":{"endpoint":"...","model":"..."}}\'',
+        },
+        yes: {
+            type: "boolean",
+            default: false,
+            description: "Accept all defaults, skip all prompts. Idempotent — safe to run in CI.",
+        },
+        dir: {
+            type: "string",
+            description: "Stash directory path (overrides stashDir in config or --config JSON)",
+        },
+        probe: {
+            type: "boolean",
+            default: false,
+            description: "Probe LLM/embedding endpoints after writing config to verify connectivity",
+        },
+    },
+    async run({ args }) {
         await runWithJsonErrors(async () => {
-            const { runSetupWizard } = await import("./setup/setup");
-            await runSetupWizard();
+            const noInit = getHyphenatedBoolean(args, "no-init");
+            if (args.config) {
+                // Non-interactive config mode
+                const { runSetupFromConfig } = await import("./setup/setup");
+                const result = await runSetupFromConfig({
+                    configJson: args.config,
+                    dir: args.dir,
+                    noInit,
+                    probe: args.probe,
+                });
+                output("setup", result);
+            }
+            else if (args.yes) {
+                // Defaults mode — no prompts
+                const { runSetupWithDefaults } = await import("./setup/setup");
+                const result = await runSetupWithDefaults({
+                    dir: args.dir,
+                    noInit,
+                    probe: args.probe,
+                });
+                output("setup", result);
+            }
+            else {
+                // Interactive wizard
+                const { runSetupWizard } = await import("./setup/setup");
+                await runSetupWizard({ dir: args.dir, noInit });
+            }
         });
     },
 });
@@ -140,16 +235,23 @@ const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
         full: { type: "boolean", description: "Force full reindex", default: false },
-        enrich: { type: "boolean", description: "Enable LLM inference and enrichment passes", default: false },
         verbose: { type: "boolean", description: "Print phase-by-phase indexing progress to stderr", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (getHyphenatedBoolean(args, "enrich") || parseFlagValue(process.argv, "--enrich") !== undefined) {
+                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+            }
+            if (getHyphenatedBoolean(args, "re-enrich") || parseFlagValue(process.argv, "--re-enrich") !== undefined) {
+                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+            }
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
             process.once("SIGINT", abort);
             process.once("SIGTERM", abort);
+            const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(indexLogFile);
             const spin = !args.verbose && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
@@ -158,12 +260,11 @@ const indexCommand = defineCommand({
             try {
                 const result = await akmIndex({
                     full: args.full,
-                    enrich: args.enrich,
-                    onProgress: ({ message, processed, total }) => {
+                    onProgress: ({ phase, message, processed, total }) => {
                         latestMessage = message;
                         const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
                         if (args.verbose) {
-                            console.error(`[index] ${progressPrefix}${message}`);
+                            info(`[index:${phase}] ${progressPrefix}${message}`);
                         }
                         else if (spin) {
                             spin.stop(`${progressPrefix}${message}`);
@@ -184,6 +285,7 @@ const indexCommand = defineCommand({
                 throw error;
             }
             finally {
+                clearLogFile();
                 process.off("SIGINT", abort);
                 process.off("SIGTERM", abort);
             }
@@ -199,6 +301,102 @@ const infoCommand = defineCommand({
         });
     },
 });
+const healthCommand = defineCommand({
+    meta: { name: "health", description: "Check akm runtime health, artifacts, and improve metrics" },
+    args: {
+        since: {
+            type: "string",
+            description: "Rolling window start (ISO timestamp, date, epoch ms, or shorthand like 24h / 7d)",
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = akmHealth({ since: args.since });
+            output("health", result);
+        });
+    },
+});
+const graphCommand = defineCommand({
+    meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
+    subCommands: {
+        summary: defineCommand({
+            meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-summary", akmGraphSummary({ source: args.source }));
+                });
+            },
+        }),
+        entities: defineCommand({
+            meta: { name: "entities", description: "List entities with per-file occurrence counts" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum entities to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-entities", akmGraphEntities({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
+                });
+            },
+        }),
+        relations: defineCommand({
+            meta: { name: "relations", description: "List relations with occurrence counts" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum relations to return" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-relations", akmGraphRelations({ source: args.source, limit: parsePositiveIntFlag(args.limit ?? undefined) }));
+                });
+            },
+        }),
+        related: defineCommand({
+            meta: { name: "related", description: "Show graph-related neighboring assets for a ref" },
+            args: {
+                ref: { type: "positional", description: "Asset ref", required: true },
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                limit: { type: "string", description: "Maximum related assets to return" },
+            },
+            async run({ args }) {
+                return runWithJsonErrors(async () => {
+                    output("graph-related", await akmGraphRelated({
+                        ref: args.ref ?? "",
+                        source: args.source,
+                        limit: parsePositiveIntFlag(args.limit ?? undefined),
+                    }));
+                });
+            },
+        }),
+        export: defineCommand({
+            meta: { name: "export", description: "Export graph artifact as JSON or JSONL" },
+            args: {
+                source: { type: "string", description: "Source name/path (default: primary stash source)" },
+                out: { type: "string", description: "Output path" },
+                format: { type: "string", description: "Export format (json|jsonl)", default: "json" },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    output("graph-export", akmGraphExport({
+                        source: args.source,
+                        out: args.out ?? "",
+                        format: args.format,
+                    }));
+                });
+            },
+        }),
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            if (hasSubcommand(args, GRAPH_SUBCOMMAND_SET))
+                return;
+            output("graph-summary", akmGraphSummary());
+        });
+    },
+});
 const searchCommand = defineCommand({
     meta: { name: "search", description: "Search the stash" },
     args: {
@@ -218,29 +416,30 @@ const searchCommand = defineCommand({
             description: 'Include entries with quality:"proposed" in the result set. Excluded by default (v1 spec §4.2).',
             default: false,
         },
+        belief: {
+            type: "string",
+            description: "Memory belief filter: all|current|historical. current keeps active memory beliefs; historical keeps contradicted/superseded/archived memory beliefs.",
+            default: "all",
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
         detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            // An empty query enumerates all indexed assets (list mode).
-            // The guard that rejected empty queries was removed; akmSearch handles
-            // empty strings end-to-end via getAllEntries (DB path) and the
-            // substring-search fallback's query-less branch.
             const query = (args.query ?? "").trim();
-            const type = args.type;
-            const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-            if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
+            if (!query) {
+                throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Pass a query like `akm search "docker"` or `akm search "code review" --type skill`.');
             }
-            const limit = limitRaw;
+            const type = args.type;
+            const limit = parsePositiveIntFlag(args.limit ?? undefined);
             const source = parseSearchSource(args.source);
             // Repeatable; citty exposes only the last `--filter` value, so read all
             // occurrences directly from argv (same pattern as `--tag`).
             const filterTokens = parseAllFlagValues("--filter");
             const filters = parseScopeFilterFlags(filterTokens, "--filter");
             const includeProposed = args["include-proposed"] === true;
-            const result = await akmSearch({ query, type, limit, source, filters, includeProposed });
+            const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
+            const result = await akmSearch({ query, type, limit, source, filters, includeProposed, belief });
             output("search", result);
         });
     },
@@ -265,11 +464,8 @@ const curateCommand = defineCommand({
                 throw new UsageError('A curate query is required. Usage: akm curate "<task or prompt>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", 'Describe the task you want assets for, e.g. `akm curate "deploy to prod"`.');
             }
             const type = args.type;
-            const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-            if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
-            }
-            const limit = limitRaw && limitRaw > 0 ? limitRaw : 4;
+            const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
+            const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
             const source = parseSearchSource(args.source ?? "stash");
             const curated = await akmCurate({ query: args.query, type, limit, source });
             output("curate", curated);
@@ -308,7 +504,7 @@ const addCommand = defineCommand({
         "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
         "allow-insecure": {
             type: "boolean",
-            description: "Allow a plain HTTP source URL (otherwise rejected for non-localhost hosts)",
+            description: "Allow a plain HTTP source URL and skip confirmation for dangerous vault keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the stash.",
             default: false,
         },
     },
@@ -316,6 +512,7 @@ const addCommand = defineCommand({
         await runWithJsonErrors(async () => {
             const ref = args.ref.trim();
             const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
+            const allowDangerousKeys = allowInsecure;
             // URL with --provider → stash source (remote or git provider)
             if (args.provider) {
                 if (shouldWarnOnPlainHttp(ref)) {
@@ -395,6 +592,118 @@ const addCommand = defineCommand({
                     writable: args.writable === true,
                 },
             });
+            // ── Post-install vault key audit ────────────────────────────────────────
+            // Resolve the stash root from the install result and scan any vault files
+            // for dangerous env var keys.  When findings are present the install is
+            // gated: TTY → interactive confirmation prompt; non-TTY without
+            // --allow-insecure → hard failure (exit 1).  Pass
+            // --allow-insecure to skip the prompt non-interactively.
+            try {
+                const installedStashRoot = result.installed?.stashRoot ??
+                    (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+                if (installedStashRoot) {
+                    const { checkVaultForDangerousKeys } = await import("./commands/lint/vault-key-rules.js");
+                    const vaultsDir = path.join(installedStashRoot, "vaults");
+                    if (fs.existsSync(vaultsDir)) {
+                        const envFiles = fs.readdirSync(vaultsDir).filter((f) => f.endsWith(".env"));
+                        // Collect all dangerous-key findings across every vault file.
+                        const allFindings = [];
+                        for (const envFile of envFiles) {
+                            const vaultPath = path.join(vaultsDir, envFile);
+                            const baseName = path.basename(envFile, ".env");
+                            const vaultRef = baseName === "" ? "vault:default" : `vault:${baseName}`;
+                            const relPath = path.join("vaults", envFile);
+                            const findings = checkVaultForDangerousKeys(vaultPath, relPath, vaultRef);
+                            for (const finding of findings) {
+                                // Extract the key name from the detail string for the summary line.
+                                const keyMatch = finding.detail.match(/Vault key `([^`]+)`/);
+                                const keyName = keyMatch ? keyMatch[1] : finding.file;
+                                allFindings.push({ vaultRef, keyName, relPath });
+                            }
+                        }
+                        if (allFindings.length > 0) {
+                            if (allowDangerousKeys) {
+                                // Operator has explicitly accepted the risk — warn and continue.
+                                for (const f of allFindings) {
+                                    warn(`[dangerous-vault-key] ${f.relPath}: key \`${f.keyName}\` in ${f.vaultRef} can hijack process execution via \`akm vault run\`. Proceeding because --allow-insecure was set.`);
+                                }
+                            }
+                            else if (process.stdout.isTTY) {
+                                // Interactive path: show findings and ask the user to confirm.
+                                const stashLabel = ref;
+                                const groupedByVault = new Map();
+                                for (const f of allFindings) {
+                                    const existing = groupedByVault.get(f.vaultRef) ?? [];
+                                    existing.push(f.keyName);
+                                    groupedByVault.set(f.vaultRef, existing);
+                                }
+                                for (const [vaultRef, keys] of groupedByVault) {
+                                    warn(`[warn] Vault "${vaultRef}" in stash "${stashLabel}" contains potentially dangerous keys:`);
+                                    for (const key of keys) {
+                                        warn(`  - ${key}: can hijack process execution via \`akm vault run\``);
+                                    }
+                                }
+                                const confirmed = await p.confirm({
+                                    message: "Install anyway?",
+                                    initialValue: false,
+                                });
+                                if (p.isCancel(confirmed) || confirmed !== true) {
+                                    // Roll back the install before aborting.
+                                    // Use the canonical installed id (most reliably resolved by akmRemove) rather
+                                    // than the raw user-supplied ref which may not match after URL normalisation.
+                                    const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+                                    let rollbackWarning;
+                                    try {
+                                        await akmRemove({ target: rollbackTarget });
+                                    }
+                                    catch (_rollbackErr) {
+                                        rollbackWarning =
+                                            `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                                `Remove it manually with: akm remove ${rollbackTarget}`;
+                                    }
+                                    console.error(JSON.stringify({
+                                        ok: false,
+                                        error: "Install aborted: stash contains dangerous vault keys. Remove the keys or re-run with --allow-insecure to bypass.",
+                                        code: "DANGEROUS_VAULT_KEY",
+                                        ...(rollbackWarning ? { rollbackWarning } : {}),
+                                    }, null, 2));
+                                    process.exit(1);
+                                }
+                            }
+                            else {
+                                // Non-interactive path without bypass flag: fail hard.
+                                // Roll back the install before exiting.
+                                // Use the canonical installed id (most reliably resolved by akmRemove) rather
+                                // than the raw user-supplied ref which may not match after URL normalisation.
+                                const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+                                let rollbackWarning;
+                                try {
+                                    await akmRemove({ target: rollbackTarget });
+                                }
+                                catch (_rollbackErr) {
+                                    rollbackWarning =
+                                        `Rollback failed — stash may still be installed at ${installedStashRoot}. ` +
+                                            `Remove it manually with: akm remove ${rollbackTarget}`;
+                                }
+                                const keyList = allFindings.map((f) => `  - ${f.keyName} (${f.vaultRef})`).join("\n");
+                                console.error(JSON.stringify({
+                                    ok: false,
+                                    error: `Install blocked: stash "${ref}" contains dangerous vault keys that can hijack process execution via \`akm vault run\`:\n${keyList}\nRe-run with --allow-insecure to bypass this check after reviewing the vault.`,
+                                    code: "DANGEROUS_VAULT_KEY",
+                                    ...(rollbackWarning ? { rollbackWarning } : {}),
+                                }, null, 2));
+                                process.exit(1);
+                            }
+                        }
+                    }
+                }
+            }
+            catch (auditErr) {
+                // Only swallow errors that are NOT our intentional process.exit calls.
+                if (auditErr instanceof Error && auditErr.message === "process.exit called")
+                    throw auditErr;
+                // Vault key audit is best-effort; never fail the install on unexpected audit errors.
+            }
             output("add", result);
         });
     },
@@ -543,15 +852,17 @@ const showCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            try {
-                parseAssetRef(args.ref);
-            }
-            catch (error) {
-                if (error instanceof UsageError && error.code === "MISSING_REQUIRED_ARGUMENT") {
-                    throw new UsageError(error.message, "INVALID_FLAG_VALUE", error.hint());
+            const subcommand = Array.isArray(args._) ? args._[0] : undefined;
+            if (subcommand === "proposal") {
+                const proposalId = Array.isArray(args._) ? args._[1] : undefined;
+                if (typeof proposalId !== "string" || !proposalId.trim()) {
+                    throw new UsageError("Usage: akm show proposal <id>", "MISSING_REQUIRED_ARGUMENT");
                 }
-                throw error;
+                const result = akmProposalShow({ id: proposalId.trim() });
+                output("proposal-show", result);
+                return;
             }
+            parseAssetRef(args.ref);
             // The knowledge-view positional syntax (`akm show knowledge:foo section "Auth"`)
             // is rewritten to `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
             // by `normalizeShowArgv` before citty parses argv. We read those values
@@ -640,6 +951,14 @@ const configCommand = defineCommand({
                 });
             },
         }),
+        show: defineCommand({
+            meta: { name: "show", description: "Alias for `akm config list` — list current configuration" },
+            run() {
+                return runWithJsonErrors(() => {
+                    output("config", listConfig(loadConfig()));
+                });
+            },
+        }),
         get: defineCommand({
             meta: { name: "get", description: "Get a configuration value by key" },
             args: {
@@ -681,7 +1000,7 @@ const configCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            if (hasConfigSubcommand(args))
+            if (hasSubcommand(args, CONFIG_SUBCOMMAND_SET))
                 return;
             if (args.list) {
                 output("config", listConfig(loadConfig()));
@@ -725,7 +1044,7 @@ const saveCommand = defineCommand({
                 ? undefined
                 : args.name;
             let writable;
-            if (!effectiveName) {
+            if (effectiveName === undefined) {
                 // Primary stash — honour the root-level writable flag from config.
                 const cfg = loadConfig();
                 writable = cfg.writable === true ? true : undefined;
@@ -901,10 +1220,7 @@ const registryCommand = defineCommand({
             },
             async run({ args }) {
                 await runWithJsonErrors(async () => {
-                    const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
-                    if (limitRaw !== undefined && Number.isNaN(limitRaw)) {
-                        throw new UsageError(`Invalid --limit value: "${args.limit}". Must be a positive integer.`);
-                    }
+                    const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
                     const result = await searchRegistry(args.query, { limit: limitRaw, includeAssets: args.assets });
                     output("registry-search", result);
                 });
@@ -939,13 +1255,37 @@ const registryCommand = defineCommand({
         }),
     },
 });
+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 events.jsonl.\n" +
+            "Negative feedback records a negative signal in usage_events and state.db events.\n" +
             "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
             "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
             "after recording negative feedback to have it reflected in search results.",
@@ -962,10 +1302,18 @@ const feedbackCommand = defineCommand({
                 "Reindexing is required for the signal to affect search results.",
             default: false,
         },
-        note: { type: "string", description: "Optional note to attach to the feedback" },
+        reason: {
+            type: "string",
+            description: "Reason for the feedback (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(() => {
+        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.");
@@ -978,12 +1326,35 @@ const feedbackCommand = defineCommand({
                 throw new UsageError("Specify --positive or --negative.");
             }
             const signal = args.positive ? "positive" : "negative";
-            const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
+            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 current index. Run "akm index" and try again.`);
+                    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.
@@ -995,8 +1366,27 @@ const feedbackCommand = defineCommand({
                     entry_ref: ref,
                     entry_id: entryId,
                     signal,
-                    metadata,
+                    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);
@@ -1004,9 +1394,9 @@ const feedbackCommand = defineCommand({
             appendEvent({
                 eventType: "feedback",
                 ref,
-                metadata: { signal, ...(args.note ? { note: args.note } : {}) },
+                metadata: metadataObj,
             });
-            output("feedback", { ok: true, ref, signal, note: args.note ?? null });
+            output("feedback", { ok: true, ref, signal, reason: reason?.trim() ?? null, tags: validatedTags });
         });
     },
 });
@@ -1016,8 +1406,8 @@ const historyCommand = defineCommand({
         description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
             "Event sources:\n" +
             "  usage_events (default): search, show, and feedback events from the local index.\n" +
-            "  events.jsonl (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
-            "    emitted by `akm proposal accept` / `akm proposal reject`.\n\n" +
+            "  state.db events (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
+            "    emitted by `akm accept` / `akm reject`.\n\n" +
             "Results from all active sources are merged and sorted chronologically.",
     },
     args: {
@@ -1025,7 +1415,7 @@ const historyCommand = defineCommand({
         since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
         "include-proposals": {
             type: "boolean",
-            description: "Also include proposal lifecycle events (promoted, rejected) from events.jsonl. " +
+            description: "Also include proposal lifecycle events (promoted, rejected) from state.db events. " +
                 "Default: false (usage_events only).",
             default: false,
         },
@@ -1042,97 +1432,10 @@ const historyCommand = defineCommand({
         });
     },
 });
-function normalizeMarkdownAssetName(name, fallback) {
-    const trimmed = (name ?? fallback)
-        .trim()
-        .replace(/\\/g, "/")
-        .replace(/^\/+|\/+$/g, "")
-        .replace(/\.md$/i, "");
-    if (!trimmed)
-        throw new UsageError("Asset name cannot be empty.");
-    const segments = trimmed.split("/");
-    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
-        throw new UsageError("Asset name must be a relative path without '.' or '..' segments.");
-    }
-    return trimmed;
-}
-function slugifyAssetName(value, fallbackPrefix) {
-    const slug = value
-        .toLowerCase()
-        .replace(/^[#>\-\s]+/, "")
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, MAX_CAPTURED_ASSET_SLUG_LENGTH);
-    return slug || `${fallbackPrefix}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
-}
-function inferAssetName(content, fallbackPrefix, preferred) {
-    const firstNonEmptyLine = content
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .find((line) => line.length > 0);
-    const basis = preferred?.trim() || firstNonEmptyLine || fallbackPrefix;
-    return slugifyAssetName(basis, fallbackPrefix);
-}
-function readKnowledgeContent(source) {
-    if (source === "-") {
-        const content = tryReadStdinText();
-        if (!content?.trim()) {
-            throw new UsageError("No stdin content received. Pipe a document into stdin or pass a file path.");
-        }
-        return { content };
-    }
-    const resolvedSource = path.resolve(source);
-    let stat;
-    try {
-        stat = fs.statSync(resolvedSource);
-    }
-    catch {
-        throw new UsageError(`Knowledge source not found: "${source}". Pass a readable file path or "-" for stdin.`);
-    }
-    if (!stat.isFile()) {
-        throw new UsageError(`Knowledge source must be a file: "${source}".`);
-    }
-    return {
-        content: fs.readFileSync(resolvedSource, "utf8"),
-        preferredName: path.basename(resolvedSource, path.extname(resolvedSource)),
-    };
-}
-async function readKnowledgeInput(source) {
-    if (!isHttpUrl(source))
-        return readKnowledgeContent(source);
-    const snapshot = await fetchWebsiteMarkdownSnapshot(source);
-    return { content: snapshot.content, preferredName: snapshot.preferredName };
-}
-async function writeMarkdownAsset(options) {
-    // Resolve write target via the v1 precedence chain (`--target` →
-    // `defaultWriteTarget` → working stash). Per spec §10 step 5, this is the
-    // single dispatch point — `core/write-source.ts` owns all kind-branching.
-    const cfg = loadConfig();
-    const { source, config } = resolveWriteTarget(cfg, options.target);
-    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
-    const normalizedName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
-    // Pre-flight: existence + force semantics. The helper itself overwrites
-    // unconditionally; the CLI surfaces a friendlier UsageError before any
-    // disk activity when --force is absent.
-    const assetPath = resolveAssetPathFromName(options.type, typeRoot, normalizedName);
-    if (!isWithin(assetPath, typeRoot)) {
-        throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
-    }
-    if (fs.existsSync(assetPath) && !options.force) {
-        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    // Delegate the actual write (and optional git commit/push) to the helper.
-    const result = await writeAssetToSource(source, config, { type: options.type, name: normalizedName }, options.content);
-    return {
-        ref: result.ref,
-        path: result.path,
-        stashDir: source.path,
-    };
-}
 const workflowStartCommand = defineCommand({
     meta: {
         name: "start",
-        description: "Start a new workflow run",
+        description: "Start a new workflow run in the current working scope",
     },
     args: {
         ref: { type: "positional", description: "Workflow ref (workflow:<name>)", required: true },
@@ -1148,22 +1451,25 @@ const workflowStartCommand = defineCommand({
 const workflowNextCommand = defineCommand({
     meta: {
         name: "next",
-        description: "Show the next actionable workflow step, auto-starting a run when passed a workflow ref",
+        description: "Show the next actionable workflow step in the current scope, auto-starting a run when passed a workflow ref",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+        "dry-run": { type: "boolean", description: "Not supported — rejected with an error", default: false },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (getHyphenatedBoolean(args, "dry-run")) {
+                throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
+            }
             const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
             // If the target looks like a UUID-style run id (no `:` and matches the
             // run-id shape), short-circuit with a structured WORKFLOW_NOT_FOUND
             // error before parseAssetRef gets to throw an unhelpful ref-parse error.
             if (looksLikeWorkflowRunId(args.target)) {
-                const { listWorkflowRuns: listRuns } = await import("./workflows/runs.js");
-                const { runs: existingRuns } = listRuns({});
-                if (!existingRuns.some((r) => r.id === args.target)) {
+                const { hasWorkflowRun } = await import("./workflows/runs.js");
+                if (!(await hasWorkflowRun(args.target))) {
                     throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
                 }
             }
@@ -1208,7 +1514,7 @@ const workflowCompleteCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = completeWorkflowStep({
+            const result = await completeWorkflowStep({
                 runId: args.runId,
                 stepId: args.step,
                 status: parseWorkflowStepState(args.state),
@@ -1222,13 +1528,13 @@ const workflowCompleteCommand = defineCommand({
 const workflowStatusCommand = defineCommand({
     meta: {
         name: "status",
-        description: "Show full workflow run state for review or resume",
+        description: "Show full workflow run state for review or resume; workflow refs resolve within the current scope",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
+        return runWithJsonErrors(async () => {
             const target = args.target;
             // Check if target looks like a workflow ref
             const parsed = (() => {
@@ -1241,18 +1547,18 @@ const workflowStatusCommand = defineCommand({
             })();
             if (parsed?.type === "workflow") {
                 const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-                const { runs } = listWorkflowRuns({ workflowRef: ref });
+                const { runs } = await listWorkflowRuns({ workflowRef: ref });
                 if (runs.length === 0) {
                     throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
                 }
                 const mostRecent = runs[0];
                 if (!mostRecent)
                     throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-                const result = getWorkflowStatus(mostRecent.id);
+                const result = await getWorkflowStatus(mostRecent.id);
                 output("workflow-status", result);
             }
             else {
-                const result = getWorkflowStatus(target);
+                const result = await getWorkflowStatus(target);
                 output("workflow-status", result);
             }
         });
@@ -1261,15 +1567,15 @@ const workflowStatusCommand = defineCommand({
 const workflowListCommand = defineCommand({
     meta: {
         name: "list",
-        description: "List workflow runs",
+        description: "List workflow runs in the current working scope",
     },
     args: {
         ref: { type: "string", description: "Filter to one workflow ref" },
         active: { type: "boolean", description: "Only show active runs", default: false },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
+        return runWithJsonErrors(async () => {
+            const result = await listWorkflowRuns({ workflowRef: args.ref, activeOnly: args.active });
             output("workflow-list", result);
         });
     },
@@ -1382,8 +1688,8 @@ const workflowResumeCommand = defineCommand({
         runId: { type: "positional", description: "Workflow run id", required: true },
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = resumeWorkflowRun(args.runId);
+        return runWithJsonErrors(async () => {
+            const result = await resumeWorkflowRun(args.runId);
             output("workflow-resume", result);
         });
     },
@@ -1405,10 +1711,10 @@ const workflowCommand = defineCommand({
         validate: workflowValidateCommand,
     },
     run({ args }) {
-        return runWithJsonErrors(() => {
+        return runWithJsonErrors(async () => {
             if (hasWorkflowSubcommand(args))
                 return;
-            output("workflow-list", listWorkflowRuns({ activeOnly: true }));
+            output("workflow-list", await listWorkflowRuns({ activeOnly: true }));
         });
     },
 });
@@ -1478,6 +1784,10 @@ const rememberCommand = defineCommand({
             type: "string",
             description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
         },
+        showSimilar: {
+            type: "boolean",
+            description: "Return top-3 similar existing memories in output (opt-in)",
+        },
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
@@ -1499,7 +1809,7 @@ const rememberCommand = defineCommand({
             if (typeof args.channel === "string" && args.channel.trim())
                 scopeFields.channel = args.channel.trim();
             const hasScope = Object.keys(scopeFields).length > 0;
-            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.enrich;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description;
             const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto;
             if (!hasStructuredArgs) {
                 const result = await writeMarkdownAsset({
@@ -1515,7 +1825,13 @@ const rememberCommand = defineCommand({
                     ref: result.ref,
                     metadata: { path: result.path, force: args.force === true },
                 });
-                output("remember", { ok: true, ...result });
+                if (args.showSimilar) {
+                    const similar = await fetchSimilarMemories(body.slice(0, 500), result.ref);
+                    output("remember", { ok: true, ...result, similar });
+                }
+                else {
+                    output("remember", { ok: true, ...result });
+                }
                 return;
             }
             // ── Accumulate metadata from all three modes ──────────────────────────
@@ -1604,53 +1920,31 @@ const rememberCommand = defineCommand({
                     ...(hasScope ? { scope: scopeFields } : {}),
                 },
             });
-            output("remember", { ok: true, ...result });
+            if (args.showSimilar) {
+                const similar = await fetchSimilarMemories((body ?? args.content ?? "").slice(0, 500), result.ref);
+                output("remember", { ok: true, ...result, similar });
+            }
+            else {
+                output("remember", { ok: true, ...result });
+            }
         });
     },
 });
-function resolveRememberContentArg(content) {
-    if (content === undefined)
-        return undefined;
-    const parsedFormat = parseFlagValue(process.argv, "--format");
-    if (parsedFormat !== undefined &&
-        content === parsedFormat &&
-        wasRememberFlagValueConsumedAsContent(content, parsedFormat, "--format")) {
-        return undefined;
-    }
-    const parsedDetail = parseFlagValue(process.argv, "--detail");
-    if (parsedDetail !== undefined &&
-        content === parsedDetail &&
-        wasRememberFlagValueConsumedAsContent(content, parsedDetail, "--detail")) {
-        return undefined;
+/**
+ * Best-effort top-3 similar memory search for `--show-similar`.
+ * Scoped to memory: type; excludes the just-written ref.
+ */
+async function fetchSimilarMemories(query, excludeRef) {
+    try {
+        const result = await akmSearch({ query, type: "memory", limit: 4 });
+        return (result.hits ?? [])
+            .filter((h) => "ref" in h && h.ref !== excludeRef)
+            .slice(0, 3)
+            .map((h) => ({ ref: h.ref, ...(h.name ? { title: h.name } : {}) }));
     }
-    return content;
-}
-function wasRememberFlagValueConsumedAsContent(content, flagValue, flagName) {
-    const argv = process.argv.slice(2);
-    const rememberIndex = argv.indexOf("remember");
-    const tokens = rememberIndex >= 0 ? argv.slice(rememberIndex + 1) : argv;
-    let flagIndex = -1;
-    let flagConsumesNextToken = false;
-    for (let i = 0; i < tokens.length; i += 1) {
-        const token = tokens[i];
-        if (token === flagName) {
-            flagIndex = i;
-            flagConsumesNextToken = true;
-            break;
-        }
-        if (token === `${flagName}=${flagValue}`) {
-            flagIndex = i;
-            break;
-        }
+    catch {
+        return [];
     }
-    if (flagIndex === -1)
-        return false;
-    if (tokens.slice(0, flagIndex).includes(content))
-        return false;
-    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? 2 : 1);
-    if (tokens.slice(firstTokenAfterFlag).includes(content))
-        return false;
-    return true;
 }
 const importKnowledgeCommand = defineCommand({
     meta: {
@@ -1740,10 +2034,11 @@ const helpCommand = defineCommand({
             },
             run({ args }) {
                 return runWithJsonErrors(() => {
-                    if (!args.version || !String(args.version).trim()) {
+                    const version = resolveHelpMigrateVersionArg(typeof args.version === "string" ? args.version : undefined);
+                    if (!version?.trim()) {
                         throw new UsageError("Usage: akm help migrate <version>.", "MISSING_REQUIRED_ARGUMENT", "Pass a version like `0.6.0`, `v0.6.0`, `0.6.0-rc1`, or `latest`.");
                     }
-                    process.stdout.write(renderMigrationHelp(args.version));
+                    process.stdout.write(renderMigrationHelp(version));
                 });
             },
         }),
@@ -1773,8 +2068,8 @@ const completionsCommand = defineCommand({
         const script = generateBashCompletions(main);
         if (args.install) {
             const dest = installBashCompletions(script);
-            console.error(`Completions installed to ${dest}`);
-            console.error(`Restart your shell or run:  source ${dest}`);
+            info(`Completions installed to ${dest}`);
+            info(`Restart your shell or run:  source ${dest}`);
         }
         else {
             process.stdout.write(script);
@@ -1841,21 +2136,43 @@ const disableCommand = defineCommand({
 });
 // ── vault ───────────────────────────────────────────────────────────────────
 //
-// `akm vault` manages secrets stored in `.env` files under the vaults/
-// asset directory. Values are NEVER written to stdout. `vault load` is
-// the only value-emitting path: it parses the vault with dotenv, writes
-// a safely-escaped shell script to a mode-0600 temp file, and emits only
-// `. <temp>; rm -f <temp>` on stdout for `eval`. The shell reads values
-// from the temp file — they never transit through akm's stdout.
+// `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}`);
+}
+function findVaultSource(origin) {
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    if (sources.length === 0) {
+        throw new UsageError("No stashes configured. Run `akm init` to create your working stash.");
+    }
+    if (!origin || origin === "local")
+        return sources[0];
+    const named = sources.find((source) => source.registryId === origin);
+    if (!named) {
+        throw new NotFoundError(`Source not found for origin: ${origin}`);
+    }
+    return named;
+}
+function makeVaultRef(name, source) {
+    return source?.registryId ? `${source.registryId}//vault:${name}` : `vault:${name}`;
+}
 function resolveVaultPath(ref) {
-    const stashDir = resolveStashDir({ readOnly: true });
-    const parsed = parseAssetRef(ref.includes(":") ? ref : `vault:${ref}`);
+    const parsed = parseVaultRef(ref);
     if (parsed.type !== "vault") {
         throw new UsageError(`Expected a vault ref (vault:<name>); got "${ref}".`);
     }
-    const typeRoot = path.join(stashDir, "vaults");
+    const source = findVaultSource(parsed.origin);
+    const typeRoot = path.join(source.path, "vaults");
     const absPath = resolveAssetPathFromName("vault", typeRoot, parsed.name);
-    return { name: parsed.name, absPath };
+    // Defense-in-depth: ensure the resolved path stays inside the vaults directory.
+    // validateName already rejects traversal patterns like "../../foo", but an
+    // absolute-path override or symlink-based attack could still escape without
+    // this second check.
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Vault name "${parsed.name}" escapes the vault directory.`);
+    }
+    return { name: parsed.name, absPath, source, parsedRef: parsed };
 }
 /**
  * Walk `vaults/` recursively and return one entry per `.env` file, using the
@@ -1864,97 +2181,65 @@ function resolveVaultPath(ref) {
  * `vault:team/prod`, `vaults/team/.env` → `vault:team/default`).
  */
 function listVaultsRecursive(listKeysFn) {
-    const stashDir = resolveStashDir({ readOnly: true });
-    const vaultsDir = path.join(stashDir, "vaults");
     const result = [];
-    if (!fs.existsSync(vaultsDir))
-        return result;
-    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 !== ".env" && !entry.name.endsWith(".env"))
-                continue;
-            const canonical = deriveCanonicalAssetName("vault", vaultsDir, full);
-            if (!canonical)
-                continue;
-            const { keys } = listKeysFn(full);
-            result.push({ ref: `vault:${canonical}`, path: full, keyCount: keys.length });
-        }
-    };
-    walk(vaultsDir);
+    for (const source of resolveSourceEntries(undefined, loadConfig())) {
+        const vaultsDir = path.join(source.path, "vaults");
+        if (!fs.existsSync(vaultsDir))
+            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 !== ".env" && !entry.name.endsWith(".env"))
+                    continue;
+                const canonical = deriveCanonicalAssetName("vault", vaultsDir, full);
+                if (!canonical)
+                    continue;
+                // Skip sensitive vaults: presence of a sibling .sensitive marker file suppresses listing.
+                const markerPath = full.replace(/\.env$/, ".sensitive");
+                if (fs.existsSync(markerPath))
+                    continue;
+                const { keys } = listKeysFn(full);
+                result.push({ ref: makeVaultRef(canonical, source), path: full, keys });
+            }
+        };
+        walk(vaultsDir);
+    }
     return result;
 }
-function wasRefMisparsedAsFlagValue(ref, flag, flagValue) {
-    const argv = process.argv.slice(2);
-    const vaultIndex = argv.indexOf("vault");
-    const listIndex = vaultIndex >= 0 ? argv.indexOf("list", vaultIndex + 1) : -1;
-    const tokens = listIndex >= 0 ? argv.slice(listIndex + 1) : argv;
-    let flagIndex = -1;
-    let flagConsumesNextToken = false;
-    for (let i = 0; i < tokens.length; i += 1) {
-        const token = tokens[i];
-        if (token === flag) {
-            flagIndex = i;
-            flagConsumesNextToken = true;
-            break;
-        }
-        if (token === `${flag}=${flagValue}`) {
-            flagIndex = i;
-            break;
-        }
+function splitVaultRunTarget(target) {
+    const full = resolveVaultPath(target);
+    if (fs.existsSync(full.absPath)) {
+        return { ref: makeVaultRef(full.name, full.source) };
     }
-    if (flagIndex === -1)
-        return false;
-    // If the same token appeared before the flag, the user explicitly passed it
-    // as the positional ref and it was not consumed by the output flag.
-    if (tokens.slice(0, flagIndex).includes(ref))
-        return false;
-    // Skip past either `--flag value` (2 tokens) or `--flag=value` (1 token)
-    // before checking whether the ref appears elsewhere as a real positional.
-    const TOKENS_AFTER_SPACE_FLAG = 2;
-    const TOKENS_AFTER_EQUALS_FLAG = 1;
-    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? TOKENS_AFTER_SPACE_FLAG : TOKENS_AFTER_EQUALS_FLAG);
-    if (tokens.slice(firstTokenAfterFlag).includes(ref))
-        return false;
-    return true;
-}
-function resolveVaultListRef(ref) {
-    if (ref === undefined)
-        return undefined;
-    const parsedFormat = parseFlagValue(process.argv, "--format");
-    if (parsedFormat !== undefined && ref === parsedFormat && wasRefMisparsedAsFlagValue(ref, "--format", parsedFormat)) {
-        return undefined;
+    const slashIndex = target.lastIndexOf("/");
+    if (slashIndex <= 0) {
+        throw new NotFoundError(`Vault not found: ${target.includes(":") ? target : `vault:${target}`}`);
     }
-    const parsedDetail = parseFlagValue(process.argv, "--detail");
-    if (parsedDetail !== undefined && ref === parsedDetail && wasRefMisparsedAsFlagValue(ref, "--detail", parsedDetail)) {
-        return undefined;
+    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>.");
     }
-    return ref;
+    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 vaults, or list keys (no values) inside one vault" },
-    args: {
-        ref: { type: "positional", description: "Optional vault ref (e.g. vault:prod or just prod)", required: false },
-    },
-    run({ args }) {
+    meta: { name: "list", description: "List all vaults across all stashes with their available key names (no values)" },
+    run() {
         return runWithJsonErrors(async () => {
-            const { listKeys, listEntries } = await import("./commands/vault.js");
-            const effectiveRef = resolveVaultListRef(args.ref);
-            if (effectiveRef) {
-                const { name, absPath } = resolveVaultPath(effectiveRef);
-                if (!fs.existsSync(absPath)) {
-                    throw new NotFoundError(`Vault not found: vault:${name}`);
-                }
-                const entries = listEntries(absPath);
-                output("vault-list", { ref: `vault:${name}`, path: absPath, entries });
-                return;
-            }
+            const { listKeys } = await import("./commands/vault.js");
             const vaults = listVaultsRecursive(listKeys);
             output("vault-list", { vaults });
         });
@@ -1964,48 +2249,69 @@ const vaultCreateCommand = defineCommand({
     meta: { name: "create", description: "Create an empty vault file (no-op if it already exists)" },
     args: {
         name: { type: "positional", description: "Vault name (e.g. prod) — file becomes <name>.env", required: true },
+        sensitive: {
+            type: "boolean",
+            description: "Exclude this vault from vault list output and the search index",
+            default: false,
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { createVault } = await import("./commands/vault.js");
-            const { name, absPath } = resolveVaultPath(args.name);
+            const { name, absPath, source } = resolveVaultPath(args.name);
             createVault(absPath);
-            output("vault-create", { ref: `vault:${name}`, path: absPath });
+            if (args.sensitive) {
+                const markerPath = absPath.replace(/\.env$/, ".sensitive");
+                if (!fs.existsSync(markerPath)) {
+                    fs.writeFileSync(markerPath, "", { mode: 0o600 });
+                }
+            }
+            output("vault-create", { ref: makeVaultRef(name, source) });
         });
     },
 });
 const vaultSetCommand = defineCommand({
     meta: {
         name: "set",
-        description: 'Set a key in a vault. Value is written to disk and never echoed back. Accepts KEY=VALUE combined form or separate KEY VALUE args. Optionally attach a comment with --comment "description".',
+        description: 'Set a key in a vault. Value is read from stdin by default (never via argv, avoiding /proc/cmdline exposure). Use --from-env <VAR> to read from an environment variable instead. Optionally attach a comment with --comment "description".',
     },
     args: {
         ref: { type: "positional", description: "Vault ref (e.g. vault:prod or just prod)", required: true },
-        key: { type: "positional", description: "Key name (e.g. DB_URL) or KEY=VALUE combined form", required: true },
-        value: {
-            type: "positional",
-            description: "Value to store (omit when using KEY=VALUE combined form)",
-            required: false,
-        },
+        key: { type: "positional", description: "Key name (e.g. DB_URL)", required: true },
         comment: { type: "string", description: "Optional comment written above the key line", required: false },
+        "from-env": {
+            type: "string",
+            description: "Read value from the named environment variable instead of stdin",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { setKey } = await import("./commands/vault.js");
-            const { name, absPath } = resolveVaultPath(args.ref);
-            let realKey;
+            const { name, absPath, source } = resolveVaultPath(args.ref);
+            const fromEnv = getHyphenatedArg(args, "from-env");
             let realValue;
-            if ((args.value === undefined || args.value === "") && args.key.includes("=")) {
-                const eqIdx = args.key.indexOf("=");
-                realKey = args.key.slice(0, eqIdx);
-                realValue = args.key.slice(eqIdx + 1);
+            if (fromEnv !== undefined) {
+                const envVal = process.env[fromEnv];
+                if (envVal === undefined) {
+                    throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
+                }
+                realValue = envVal;
             }
             else {
-                realKey = args.key;
-                realValue = args.value ?? "";
+                const MAX_VAULT_VALUE_BYTES = 1024 * 1024; // 1 MB
+                let totalBytes = 0;
+                const chunks = [];
+                for await (const chunk of Bun.stdin.stream()) {
+                    totalBytes += chunk.byteLength;
+                    if (totalBytes > MAX_VAULT_VALUE_BYTES) {
+                        throw new UsageError("Vault value exceeds 1 MB limit. Values must be provided via stdin.");
+                    }
+                    chunks.push(chunk);
+                }
+                realValue = Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
             }
-            setKey(absPath, realKey, realValue, args.comment);
-            output("vault-set", { ref: `vault:${name}`, key: realKey, path: absPath });
+            setKey(absPath, args.key, realValue, args.comment);
+            output("vault-set", { ref: makeVaultRef(name, source), key: args.key });
         });
     },
 });
@@ -2018,104 +2324,102 @@ const vaultUnsetCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { unsetKey } = await import("./commands/vault.js");
-            const { name, absPath } = resolveVaultPath(args.ref);
+            const { name, absPath, source } = resolveVaultPath(args.ref);
             if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: vault:${name}`);
+                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
             }
             const removed = unsetKey(absPath, args.key);
-            output("vault-unset", { ref: `vault:${name}`, key: args.key, removed, path: absPath });
+            output("vault-unset", { ref: makeVaultRef(name, source), key: args.key, removed });
         });
     },
 });
-const vaultLoadCommand = defineCommand({
+const vaultPathCommand = defineCommand({
     meta: {
-        name: "load",
-        description: 'Emit a shell snippet that loads vault values into the current shell. Use: eval "$(akm vault load vault:<name>)". Values are parsed by dotenv, written to a mode-0600 temp file with safe single-quote escaping, then sourced and removed. No values appear on akm\'s stdout, and no shell expansion happens on raw vault content.',
+        name: "path",
+        description: 'Print the absolute vault file path so you can load it directly, e.g. `source "$(akm vault path vault:prod)"`.',
     },
     args: {
         ref: { type: "positional", description: "Vault ref", required: true },
     },
-    async run({ args }) {
+    run({ args }) {
         return runWithJsonErrors(async () => {
-            // This command deliberately bypasses output()/JSON shaping. Its stdout
-            // is a shell snippet intended for `eval`, not structured output.
-            const { name, absPath } = resolveVaultPath(args.ref);
+            const { name, absPath, source } = resolveVaultPath(args.ref);
             if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: vault:${name}`);
-            }
-            const { buildShellExportScript } = await import("./commands/vault.js");
-            const crypto = await import("node:crypto");
-            const os = await import("node:os");
-            // Parse via dotenv (no expansion, no code execution) and build a
-            // script of literal `export KEY='value'` lines with `'\''` escaping.
-            // Sourcing this is safe even if the raw vault file contained shell
-            // metacharacters like $, backticks, or $(...).
-            const script = buildShellExportScript(absPath);
-            // Write to a mode-0600 temp file the shell can source.
-            //
-            // INTENTIONAL: this site uses `os.tmpdir()` (i.e. `/tmp` on Unix)
-            // rather than `${getCacheDir()}/vault/`. The temp file is written
-            // mode-0600, sourced by the parent shell via `eval`, and immediately
-            // `rm -f`'d on the same line of the emitted snippet. `/tmp` is the
-            // conventional location for short-lived shell-eval scratch files and
-            // benefits from tmp-cleanup-on-reboot semantics, which operators
-            // expect for ephemeral secret material. Moving to `~/.cache/akm/`
-            // would surprise those operators and also persist the file across
-            // reboots if the eval is interrupted before the inline `rm -f` runs.
-            // The bench/registry-build rationale (#276/#284) — orphan dirs
-            // accumulating under `/tmp` from long-running builds — does not
-            // apply here: the file is single-shot, a few hundred bytes, and
-            // removed by the same shell command that sources it.
-            // Regression test: tests/vault-load-error.test.ts verifies the
-            // emitted snippet contains both `. <path>` and `rm -f <path>`.
-            const tmpPath = path.join(os.tmpdir(), `akm-vault-${crypto.randomBytes(12).toString("hex")}.sh`);
-            fs.writeFileSync(tmpPath, script, { mode: 0o600, encoding: "utf8" });
-            try {
-                fs.chmodSync(tmpPath, 0o600);
+                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
             }
-            catch {
-                /* best-effort on platforms without chmod */
-            }
-            const quotedTmp = `'${tmpPath.replace(/'/g, "'\\''")}'`;
-            // Emit: source the temp file, then remove it — values reach bash only
-            // via the temp file (mode 0600), never via akm's stdout.
-            process.stdout.write(`. ${quotedTmp}; rm -f ${quotedTmp}\n`);
+            process.stdout.write(`${absPath}\n`);
         });
     },
 });
-const vaultShowCommand = defineCommand({
-    meta: { name: "show", description: "Show keys (no values) inside a vault — alias for `vault list <ref>`" },
+const vaultRunCommand = 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>`",
+    },
     args: {
-        ref: { type: "positional", description: "Vault ref (e.g. vault:prod or just prod)", required: true },
+        target: { type: "positional", description: "Vault ref or ref/key target", required: true },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            const { listEntries } = await import("./commands/vault.js");
-            const { name, absPath } = resolveVaultPath(args.ref);
+            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>");
+            }
+            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);
             if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Vault not found: vault:${name}`);
+                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
             }
-            const entries = listEntries(absPath);
-            output("vault-list", { ref: `vault:${name}`, path: absPath, entries });
+            const envValues = loadEnv(absPath);
+            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.
+            appendEvent({
+                eventType: "vault_access",
+                ref: makeVaultRef(name, source),
+                metadata: {
+                    keys: key ? [key] : Object.keys(envValues),
+                },
+            });
+            const result = spawnSync(command[0], command.slice(1), {
+                stdio: "inherit",
+                env: mergedEnv,
+            });
+            if (result.error)
+                throw result.error;
+            process.exit(result.status ?? 0);
         });
     },
 });
 const vaultCommand = defineCommand({
     meta: {
         name: "vault",
-        description: "Manage secret vaults (.env files). Lists keys + comments only — values never returned in structured output.",
+        description: "Manage secret vaults (.env files). Keys are visible, values stay on disk and never appear in structured output.",
     },
     subCommands: {
         list: vaultListCommand,
-        show: vaultShowCommand,
+        path: vaultPathCommand,
+        run: vaultRunCommand,
         create: vaultCreateCommand,
         set: vaultSetCommand,
         unset: vaultUnsetCommand,
-        load: vaultLoadCommand,
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (hasVaultSubcommand(args))
+            if (hasSubcommand(args, VAULT_SUBCOMMAND_SET))
                 return;
             // Default action: list all vaults
             const { listKeys } = await import("./commands/vault.js");
@@ -2279,12 +2583,39 @@ const wikiStashCommand = defineCommand({
         name: { type: "positional", description: "Wiki name", required: true },
         source: { type: "positional", description: "Source file path, URL, or '-' to read from stdin", required: true },
         as: { type: "string", description: "Preferred slug base (defaults to source filename or first-line slug)" },
+        target: {
+            type: "string",
+            description: "Name of a writable stash source to write into instead of the default stash. Must match a configured source name (run `akm list` to see sources).",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { stashRaw } = await import("./wiki/wiki.js");
-            const { content, preferredName } = await readKnowledgeInput(args.source);
-            const stashDir = resolveStashDir();
+            const { content, preferredName } = await (async () => {
+                if (!isHttpUrl(args.source))
+                    return readKnowledgeInput(args.source);
+                const { fetchWebsiteMarkdownSnapshot } = await import("./sources/website-ingest");
+                const snapshot = await fetchWebsiteMarkdownSnapshot(args.source);
+                return { content: snapshot.content, preferredName: args.as ?? snapshot.preferredName };
+            })();
+            let stashDir;
+            if (args.target) {
+                // Resolve the named source to its filesystem path.
+                const cfg = loadConfig();
+                const sources = resolveConfiguredSources(cfg);
+                const match = sources.find((s) => s.name === args.target);
+                if (!match) {
+                    throw new UsageError(`--target must reference a configured source name. No source named "${args.target}" found. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+                }
+                const spec = match.source;
+                if (spec.type !== "filesystem" && spec.type !== "local") {
+                    throw new ConfigError(`Source "${args.target}" is not a filesystem source and cannot be used as a wiki stash target.`, "INVALID_CONFIG_FILE", `Use a source with type "filesystem" or "local", or omit --target to use the default stash.`);
+                }
+                stashDir = spec.path;
+            }
+            else {
+                stashDir = resolveStashDir();
+            }
             const result = stashRaw({
                 stashDir,
                 wikiName: args.name,
@@ -2353,7 +2684,7 @@ const wikiCommand = defineCommand({
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
-            if (hasWikiSubcommand(args))
+            if (hasSubcommand(args, WIKI_SUBCOMMAND_SET))
                 return;
             // Default action: list wikis
             const { listWikis } = await import("./wiki/wiki.js");
@@ -2362,50 +2693,76 @@ const wikiCommand = defineCommand({
     },
 });
 // ── `akm events` ────────────────────────────────────────────────────────────
-// Append-only events stream surface (#204). `list` reads `events.jsonl`
-// with optional --since/--type/--ref filters; `tail` follows the file via
+// Append-only events stream surface (#204). `list` reads state.db events
+// with optional --since/--type/--ref filters; `tail` follows the table via
 // a polling loop and prints each event as a single JSONL line.
 const eventsListCommand = defineCommand({
-    meta: { name: "list", description: "List events from the append-only events.jsonl stream" },
+    meta: { name: "list", description: "List events from the append-only state.db events stream" },
     args: {
         since: {
             type: "string",
-            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-cursor (resume across processes)",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
         },
         type: { type: "string", description: "Filter by event type (add, remove, remember, feedback, ...)" },
         ref: { type: "string", description: "Filter by asset ref (type:name)" },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude events matching these tags (repeatable)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include events with ALL these tags (repeatable)",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            const result = akmEventsList({ since: args.since, type: args.type, ref: args.ref });
+            const excludeTags = parseAllFlagValues("--exclude-tags");
+            const includeTags = parseAllFlagValues("--include-tags");
+            const result = akmEventsList({
+                since: args.since,
+                type: args.type,
+                ref: args.ref,
+                ...(excludeTags.length > 0 ? { excludeTags } : {}),
+                ...(includeTags.length > 0 ? { includeTags } : {}),
+            });
             output("events-list", result);
         });
     },
 });
 const eventsTailCommand = defineCommand({
-    meta: { name: "tail", description: "Follow the append-only events.jsonl stream (polling)" },
+    meta: { name: "tail", description: "Follow the append-only state.db events stream (polling)" },
     args: {
         since: {
             type: "string",
-            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-cursor (resume across processes)",
+            description: "ISO timestamp / epoch ms, OR `@offset:<id>` for a durable row-id cursor (resume across processes)",
         },
         type: { type: "string", description: "Filter by event type" },
         ref: { type: "string", description: "Filter by asset ref (type:name)" },
         "interval-ms": { type: "string", description: "Polling interval in ms (default: 75)" },
         "max-duration-ms": { type: "string", description: "Stop after this many ms (default: never)" },
         "max-events": { type: "string", description: "Stop after observing this many events" },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude events matching these tags (repeatable)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include events with ALL these tags (repeatable)",
+        },
     },
     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
             // also rendered through the standard output() pipeline so JSON
             // consumers always get the canonical envelope.
             const stream = mode.format === "text" || mode.format === "jsonl";
+            const excludeTags = parseAllFlagValues("--exclude-tags");
+            const includeTags = parseAllFlagValues("--include-tags");
             const result = await akmEventsTail({
                 since: args.since,
                 type: args.type,
@@ -2413,6 +2770,8 @@ const eventsTailCommand = defineCommand({
                 intervalMs,
                 maxDurationMs,
                 maxEvents,
+                ...(excludeTags.length > 0 ? { excludeTags } : {}),
+                ...(includeTags.length > 0 ? { includeTags } : {}),
                 onEvent: stream
                     ? (event) => {
                         if (mode.format === "jsonl") {
@@ -2449,22 +2808,10 @@ const eventsTailCommand = defineCommand({
         });
     },
 });
-function parsePositiveInt(raw, flag) {
-    if (raw === undefined)
-        return undefined;
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return undefined;
-    const value = Number.parseInt(trimmed, 10);
-    if (Number.isNaN(value) || value <= 0) {
-        throw new UsageError(`Invalid ${flag} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
-    }
-    return value;
-}
 const eventsCommand = defineCommand({
     meta: {
         name: "events",
-        description: "Read or follow the append-only events.jsonl stream (mutations, feedback, indexing)",
+        description: "Read or follow the append-only state.db events stream (mutations, feedback, indexing)",
     },
     subCommands: {
         list: eventsListCommand,
@@ -2472,16 +2819,12 @@ const eventsCommand = defineCommand({
     },
 });
 // ── proposal substrate (#225) ────────────────────────────────────────────────
-const proposalListCommand = defineCommand({
-    meta: { name: "list", description: "List pending proposals (use --include-archive to see decided ones)" },
+const proposalsCommand = defineCommand({
+    meta: { name: "proposals", description: "List proposal queue entries" },
     args: {
         status: { type: "string", description: "Filter by status (pending|accepted|rejected)" },
         ref: { type: "string", description: "Filter by asset ref (type:name)" },
-        "include-archive": {
-            type: "boolean",
-            description: "Include accepted/rejected proposals from the archive",
-            default: false,
-        },
+        type: { type: "string", description: "Filter by asset type" },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
@@ -2489,28 +2832,20 @@ const proposalListCommand = defineCommand({
             const result = akmProposalList({
                 status,
                 ref: args.ref,
-                includeArchive: getHyphenatedBoolean(args, "include-archive"),
+                includeArchive: status === "accepted" || status === "rejected",
             });
             output("proposal-list", result);
         });
     },
 });
-const proposalShowCommand = defineCommand({
-    meta: { name: "show", description: "Show a proposal's metadata, payload, and validation report" },
-    args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
-    },
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            const result = akmProposalShow({ id: args.id });
-            output("proposal-show", result);
-        });
-    },
-});
-const proposalAcceptCommand = defineCommand({
-    meta: { name: "accept", description: "Validate and promote a proposal to a real asset" },
+const acceptCommand = defineCommand({
+    meta: { name: "accept", description: "Accept a proposal and promote it into the stash" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            required: true,
+        },
         target: { type: "string", description: "Override the write target by source name" },
     },
     async run({ args }) {
@@ -2520,23 +2855,34 @@ const proposalAcceptCommand = defineCommand({
         });
     },
 });
-const proposalRejectCommand = defineCommand({
-    meta: { name: "reject", description: "Archive a pending proposal with an optional reason" },
+const rejectCommand = defineCommand({
+    meta: { name: "reject", description: "Reject a proposal and record the reason" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
-        reason: { type: "string", description: "Reason for rejection (recorded in the archived proposal)" },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            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 = akmProposalReject({ id: args.id, reason: args.reason });
             output("proposal-reject", result);
         });
     },
 });
-const proposalDiffCommand = defineCommand({
-    meta: { name: "diff", description: "Show the diff between an existing asset and a pending proposal" },
+const diffCommand = defineCommand({
+    meta: { name: "diff", description: "Show the diff for a proposal (accepts full UUID, UUID prefix, or asset ref)" },
     args: {
-        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        id: {
+            type: "positional",
+            description: "Proposal id (uuid / prefix) or asset ref (e.g. skill:akm-dream)",
+            required: true,
+        },
         target: { type: "string", description: "Override the write target by source name" },
     },
     run({ args }) {
@@ -2546,76 +2892,7 @@ const proposalDiffCommand = defineCommand({
         });
     },
 });
-const proposalCommand = defineCommand({
-    meta: {
-        name: "proposal",
-        description: "Review and promote queued asset proposals (durable storage under .akm/proposals/)",
-    },
-    subCommands: {
-        list: proposalListCommand,
-        show: proposalShowCommand,
-        accept: proposalAcceptCommand,
-        reject: proposalRejectCommand,
-        diff: proposalDiffCommand,
-    },
-});
 // ── distill (#228) ──────────────────────────────────────────────────────────
-const distillCommand = defineCommand({
-    meta: {
-        name: "distill",
-        description: "Distil feedback for an asset into a queued lesson proposal (gated on llm.features.feedback_distillation)",
-    },
-    args: {
-        ref: { type: "positional", description: "Asset ref (type:name) to distil from", required: true },
-        "source-run": {
-            type: "string",
-            description: "Optional run id propagated onto the queued proposal for traceability",
-        },
-        "exclude-feedback-from": {
-            type: "string",
-            description: "Comma-separated asset refs whose feedback events MUST be filtered out before the LLM input is built. Falls back to AKM_DISTILL_EXCLUDE_FEEDBACK_FROM when omitted.",
-        },
-    },
-    async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const excludeFlag = getHyphenatedArg(args, "exclude-feedback-from");
-            const excludeEnv = process.env.AKM_DISTILL_EXCLUDE_FEEDBACK_FROM;
-            // CLI flag takes precedence over the env var when both are present.
-            const excludeRaw = excludeFlag ?? excludeEnv;
-            const excludeFeedbackFromRefs = parseExcludeFeedbackFromRefs(excludeRaw);
-            const result = await akmDistill({
-                ref: args.ref,
-                sourceRun: getHyphenatedArg(args, "source-run"),
-                ...(excludeFeedbackFromRefs.length > 0 ? { excludeFeedbackFromRefs } : {}),
-            });
-            output("distill", result);
-        });
-    },
-});
-/**
- * Parse a comma-separated list of asset refs (#267 — `--exclude-feedback-from`
- * and `AKM_DISTILL_EXCLUDE_FEEDBACK_FROM`). Each entry is validated against
- * the canonical `[origin//]type:name` grammar via `parseAssetRef`; an
- * invalid entry surfaces as a UsageError → exit 2.
- */
-function parseExcludeFeedbackFromRefs(raw) {
-    if (raw === undefined || raw.trim() === "")
-        return [];
-    const refs = raw
-        .split(",")
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0);
-    for (const ref of refs) {
-        try {
-            parseAssetRef(ref);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            throw new UsageError(`Invalid --exclude-feedback-from ref "${ref}": ${message}`, "INVALID_FLAG_VALUE", "Each ref must match `[origin//]type:name`, e.g. skill:deploy or team//memory:auth-tips.");
-        }
-    }
-    return refs;
-}
 function parseProposalStatus(raw) {
     if (raw === undefined)
         return undefined;
@@ -2626,39 +2903,232 @@ function parseProposalStatus(raw) {
         return trimmed;
     throw new UsageError(`Invalid --status value: "${raw}". Expected one of: pending, accepted, rejected.`, "INVALID_FLAG_VALUE");
 }
-// ── reflect / propose (agent proposal-producers, #226) ──────────────────────
-const reflectCommand = defineCommand({
+const agentCommand = defineCommand({
     meta: {
-        name: "reflect",
-        description: "Ask the configured agent CLI to review an asset (or recent feedback) and queue a revised proposal",
+        name: "agent",
+        description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a stash agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
     },
     args: {
-        ref: {
+        profile: {
             type: "positional",
-            description: "Asset ref (type:name) to reflect on. Optional — omit to reflect across recent feedback.",
+            description: "Agent profile / platform to use (opencode, claude, …)",
             required: false,
         },
-        task: { type: "string", description: "Optional task hint passed into the reflection prompt" },
-        profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
+        "agent-ref": {
+            type: "positional",
+            description: "Optional agent asset ref (e.g. agent:code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
+            required: false,
+        },
+        prompt: { type: "string", description: "Task prompt to pass to the agent" },
+        command: { type: "string", description: "Load prompt from a command: asset" },
+        workflow: { type: "string", description: "Load prompt from a workflow: asset" },
+        model: {
+            type: "string",
+            description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
+        },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
-            const result = await akmReflect({
-                ref: typeof args.ref === "string" && args.ref.trim() ? args.ref : undefined,
-                task: typeof args.task === "string" && args.task.trim() ? args.task : undefined,
-                profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
+            if (!args.profile) {
+                throw new UsageError("Usage: akm agent <profile> [<agent-ref>] [--prompt <text>] [--model <model>]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in config.agent.profiles.");
+            }
+            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);
+            // Resolve agent asset ref → extract system prompt, model, and tool policy.
+            const agentRef = getStringArg(args, "agent-ref");
+            let systemPrompt;
+            let assetModel;
+            let assetTools;
+            if (agentRef) {
+                const { akmShowUnified } = await import("./commands/show.js");
+                const asset = await akmShowUnified({ ref: agentRef, detail: "full" });
+                systemPrompt = typeof asset.content === "string" ? asset.content : undefined;
+                assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
+                assetTools = asset.toolPolicy;
+            }
+            // --model flag wins over the asset's modelHint.
+            const model = getStringArg(args, "model") ?? assetModel;
+            const promptText = getStringArg(args, "prompt");
+            const commandRef = getStringArg(args, "command");
+            const workflowRef = getStringArg(args, "workflow");
+            // Only build a dispatch request when there is something to dispatch — a
+            // prompt, an agent asset, or a model override. When none of these are
+            // present the agent is launched interactively (no injected prompt, no
+            // platform-specific flags beyond the profile's base args).
+            const hasDispatchContent = !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
+            const result = await akmAgentDispatch({
+                profileName: String(args.profile),
+                prompt: promptText,
+                commandRef,
+                workflowRef,
+                agentConfig,
+                llmConfig: config.llm,
+                ...(hasDispatchContent
+                    ? {
+                        dispatch: {
+                            prompt: promptText ?? "",
+                            systemPrompt,
+                            model,
+                            tools: assetTools,
+                        },
+                    }
+                    : {}),
                 ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
             });
-            output("reflect", result);
-            if (result.ok === false) {
+            output("agent-result", result);
+            if (!result.ok) {
                 process.exit(EXIT_GENERAL);
             }
         });
     },
 });
+const lintCommand = defineCommand({
+    meta: {
+        name: "lint",
+        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues.",
+    },
+    args: {
+        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        dir: { type: "string", description: "Override stash root directory (default: from config)" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = akmLint({
+                fix: args.fix ?? false,
+                dir: getStringArg(args, "dir"),
+            });
+            output("lint", result);
+            if (!result.ok)
+                process.exit(EXIT_GENERAL);
+        });
+    },
+});
+const improveCommand = defineCommand({
+    meta: {
+        name: "improve",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when 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 = getStringArg(args, "target");
+            const taskArg = getStringArg(args, "task");
+            const dryRun = getHyphenatedBoolean(args, "dry-run");
+            const autoAccept = autoAcceptRaw === "safe" ? "safe" : undefined;
+            const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const ignoreCooldown = getHyphenatedBoolean(args, "ignore-cooldown");
+            const reflectCooldownRaw = getHyphenatedArg(args, "reflect-cooldown-days");
+            const reflectCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(reflectCooldownRaw, "--reflect-cooldown-days");
+            const distillCooldownRaw = getHyphenatedArg(args, "distill-cooldown-days");
+            const distillCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(distillCooldownRaw, "--distill-cooldown-days");
+            const consolidateCooldownRaw = getHyphenatedArg(args, "consolidate-cooldown-days");
+            const consolidateCooldownDays = ignoreCooldown
+                ? 0
+                : parseNonNegativeIntFlag(consolidateCooldownRaw, "--consolidate-cooldown-days");
+            const consolidateRecoveryRaw = getHyphenatedArg(args, "consolidate-recovery");
+            const consolidateRecovery = consolidateRecoveryRaw === undefined
+                ? undefined
+                : consolidateRecoveryRaw.trim().toLowerCase();
+            if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
+                throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
+            }
+            const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
+            const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
+            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(improveLogFile);
+            let improveResult;
+            try {
+                improveResult = await akmImprove({
+                    scope: getStringArg(args, "scope"),
+                    task: taskArg,
+                    dryRun,
+                    target: targetArg,
+                    autoAccept,
+                    ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(reflectCooldownDays !== undefined ? { reflectCooldownDays } : {}),
+                    ...(distillCooldownDays !== undefined ? { distillCooldownDays } : {}),
+                    ...(consolidateCooldownDays !== undefined ? { consolidateCooldownDays } : {}),
+                    ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
+                    ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    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",
@@ -2671,6 +3141,7 @@ const proposeCommand = defineCommand({
         type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
         name: { type: "positional", description: "Asset name (slug or path under the type dir)", required: false },
         task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
         profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
     },
@@ -2679,17 +3150,22 @@ const proposeCommand = defineCommand({
             // citty silently shows help and exits 0 when required positionals are
             // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
             // structured JSON error reaches scripted callers.
-            if (!args.type || !args.name || !args.task) {
-                throw new UsageError("Usage: akm propose <type> <name> --task '<task>'.", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and a --task description, e.g. `akm propose skill deploy --task 'Deploy a service'`.");
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm propose <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
             }
-            const timeoutRaw = args["timeout-ms"];
-            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
+            }
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
             const result = await akmPropose({
                 type: String(args.type),
                 name: String(args.name),
-                task: String(args.task ?? ""),
-                profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
-                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+                task: taskText,
+                profile: getStringArg(args, "profile"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("propose", result);
             if (result.ok === false) {
@@ -2698,6 +3174,189 @@ const proposeCommand = defineCommand({
         });
     },
 });
+const TASKS_SUBCOMMAND_SET = new Set([
+    "add",
+    "list",
+    "show",
+    "remove",
+    "enable",
+    "disable",
+    "run",
+    "history",
+    "sync",
+    "doctor",
+]);
+const GRAPH_SUBCOMMAND_SET = new Set(["summary", "entities", "relations", "related", "export"]);
+const tasksAddCommand = defineCommand({
+    meta: { name: "add", description: "Register a new scheduled task and install it in the OS scheduler" },
+    args: {
+        id: { type: "positional", description: "Task id (used as filename and scheduler entry)", required: true },
+        schedule: { type: "string", description: 'Cron-style schedule, e.g. "0 9 * * *" or "@daily"', required: true },
+        workflow: { type: "string", description: "Workflow ref to invoke (e.g. workflow:my-flow)" },
+        prompt: {
+            type: "string",
+            description: "Prompt for the configured agent harness — inline text, an asset ref like agent:foo, or ./path.md",
+        },
+        profile: { type: "string", description: "Agent profile to use for prompt targets (default: config.agent.default)" },
+        params: { type: "string", description: "Workflow params as a JSON object" },
+        description: { type: "string", description: "Human-readable description" },
+        tags: { type: "string", description: "Comma-separated tags" },
+        disabled: { type: "boolean", description: "Register but leave disabled in the OS scheduler", default: false },
+        force: { type: "boolean", description: "Overwrite an existing task with the same id", default: false },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksAdd({
+                id: args.id,
+                schedule: args.schedule,
+                workflow: args.workflow,
+                prompt: args.prompt,
+                profile: args.profile,
+                params: args.params,
+                description: args.description,
+                tags: args.tags
+                    ? args.tags
+                        .split(/[\s,]+/)
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : undefined,
+                disabled: args.disabled === true,
+                force: args.force === true,
+            });
+            output("tasks-add", result);
+        });
+    },
+});
+const tasksListCommand = defineCommand({
+    meta: { name: "list", description: "List scheduled tasks in the stash" },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});
+const tasksShowCommand = defineCommand({
+    meta: { name: "show", description: "Show a parsed task definition" },
+    args: { id: { type: "positional", description: "Task id or task:<id>", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksShow(id);
+            output("tasks-show", result);
+        });
+    },
+});
+const tasksRemoveCommand = defineCommand({
+    meta: { name: "remove", description: "Delete a task file and uninstall it from the OS scheduler" },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksRemove(id);
+            output("tasks-remove", result);
+        });
+    },
+});
+function makeTasksToggleCommand(enabled) {
+    const verb = enabled ? "enable" : "disable";
+    const description = enabled
+        ? "Enable a previously-disabled task"
+        : "Disable a task in the OS scheduler without removing the file";
+    return defineCommand({
+        meta: { name: verb, description },
+        args: { id: { type: "positional", description: "Task id", required: true } },
+        async run({ args }) {
+            await runWithJsonErrors(async () => {
+                const { id } = parseTaskRef(args.id);
+                const result = await akmTasksSetEnabled(id, enabled);
+                output(`tasks-${verb}`, result);
+            });
+        },
+    });
+}
+const tasksEnableCommand = makeTasksToggleCommand(true);
+const tasksDisableCommand = makeTasksToggleCommand(false);
+const tasksRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Execute a task now (this is what cron / launchd / schtasks invoke at the scheduled time)",
+    },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const envelope = await akmTasksRun(id);
+            output("tasks-run", envelope);
+            if (envelope.exitCode !== 0)
+                process.exit(envelope.exitCode);
+        });
+    },
+});
+const tasksHistoryCommand = defineCommand({
+    meta: { name: "history", description: "Show recent task run history" },
+    args: {
+        id: { type: "string", description: "Filter to one task id" },
+        limit: { type: "string", description: "Maximum rows to return (default 50)" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const limit = parsePositiveIntFlag(args.limit ?? undefined);
+            const result = await akmTasksHistory({ id: args.id, limit });
+            output("tasks-history", result);
+        });
+    },
+});
+const tasksSyncCommand = defineCommand({
+    meta: {
+        name: "sync",
+        description: "Reconcile the on-disk task files with the OS scheduler",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksSync();
+            output("tasks-sync", result);
+        });
+    },
+});
+const tasksDoctorCommand = defineCommand({
+    meta: {
+        name: "doctor",
+        description: "Report the active scheduler backend, akm bin path, log dir, and supported schedule subset",
+    },
+    async run() {
+        await runWithJsonErrors(async () => {
+            const result = await akmTasksDoctor();
+            output("tasks-doctor", result);
+        });
+    },
+});
+const tasksCommand = defineCommand({
+    meta: {
+        name: "tasks",
+        description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
+    },
+    subCommands: {
+        add: tasksAddCommand,
+        list: tasksListCommand,
+        show: tasksShowCommand,
+        remove: tasksRemoveCommand,
+        enable: tasksEnableCommand,
+        disable: tasksDisableCommand,
+        run: tasksRunCommand,
+        history: tasksHistoryCommand,
+        sync: tasksSyncCommand,
+        doctor: tasksDoctorCommand,
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
+                return;
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -2718,7 +3377,9 @@ const main = defineCommand({
         setup: setupCommand,
         init: initCommand,
         index: indexCommand,
+        health: healthCommand,
         info: infoCommand,
+        graph: graphCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -2739,19 +3400,24 @@ const main = defineCommand({
         feedback: feedbackCommand,
         history: historyCommand,
         events: eventsCommand,
-        proposal: proposalCommand,
-        reflect: reflectCommand,
+        agent: agentCommand,
+        lint: lintCommand,
+        improve: improveCommand,
         propose: proposeCommand,
-        distill: distillCommand,
+        proposals: proposalsCommand,
+        accept: acceptCommand,
+        reject: rejectCommand,
+        diff: diffCommand,
         help: helpCommand,
         hints: hintsCommand,
         completions: completionsCommand,
         vault: vaultCommand,
         wiki: wikiCommand,
+        tasks: tasksCommand,
     },
 });
-const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
-const VAULT_SUBCOMMAND_SET = new Set(["list", "show", "create", "set", "unset", "load"]);
+const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "show", "get", "set", "unset"]);
+const VAULT_SUBCOMMAND_SET = new Set(["list", "path", "run", "create", "set", "unset"]);
 const WIKI_SUBCOMMAND_SET = new Set([
     "create",
     "register",
@@ -2764,7 +3430,6 @@ const WIKI_SUBCOMMAND_SET = new Set([
     "lint",
     "ingest",
 ]);
-const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
 // ── Exit codes ──────────────────────────────────────────────────────────────
 const EXIT_GENERAL = 1;
 const EXIT_USAGE = 2;
@@ -2778,17 +3443,11 @@ process.argv = normalizeShowArgv(process.argv);
 // invalid; surface it through the same JSON-error path the rest of the CLI uses
 // rather than letting the raw exception escape with a stack trace.
 try {
+    applyEarlyStderrFlags(process.argv);
     initOutputMode(process.argv, loadConfig().output ?? {});
 }
 catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const hint = extractHint(error);
-    const exitCode = classifyExitCode(error);
-    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-        ? error.code
-        : undefined;
-    console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
-    process.exit(exitCode);
+    emitJsonError(error);
 }
 runMain(main);
 function classifyExitCode(error) {
@@ -2800,33 +3459,6 @@ function classifyExitCode(error) {
         return EXIT_GENERAL;
     return EXIT_GENERAL;
 }
-async function runWithJsonErrors(fn) {
-    try {
-        // Apply --quiet flag early so warnings inside the command are suppressed
-        if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
-            setQuiet(true);
-        }
-        // Apply --verbose flag early so per-spec diagnostics (gated behind
-        // `isVerbose()` in src/core/warn.ts) are restored. The `AKM_VERBOSE`
-        // env var still wins regardless — see warn.ts for the precedence rule.
-        if (process.argv.includes("--verbose")) {
-            setVerbose(true);
-        }
-        await fn();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        const hint = extractHint(error);
-        const exitCode = classifyExitCode(error);
-        // Surface machine-readable error code from typed errors when present so
-        // scripts can branch on `.code` instead of message-string matching.
-        const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-            ? error.code
-            : undefined;
-        console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
-        process.exit(exitCode);
-    }
-}
 /**
  * Extract an actionable hint from an error instance. Hints live on the error
  * classes themselves (see src/errors.ts) — either supplied explicitly at the
@@ -2838,86 +3470,27 @@ function extractHint(error) {
     }
     return undefined;
 }
-function hasConfigSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && CONFIG_SUBCOMMAND_SET.has(command);
-}
-function hasVaultSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && VAULT_SUBCOMMAND_SET.has(command);
-}
-function hasWikiSubcommand(args) {
-    const command = Array.isArray(args._) ? args._[0] : undefined;
-    return typeof command === "string" && WIKI_SUBCOMMAND_SET.has(command);
-}
 /**
- * Normalize argv so positional view-mode arguments after the asset ref
- * are rewritten into internal flags that citty can parse.
- *
- * Converts:
- *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --akmView toc
- *   akm show knowledge:guide.md section Auth → akm show knowledge:guide.md --akmView section --akmHeading Auth
- *   akm show knowledge:guide.md lines 1 50   → akm show knowledge:guide.md --akmView lines --akmStart 1 --akmEnd 50
- *
- * Legacy `--view` is intentionally unsupported.
- * Returns a new array; the input is never modified.
+ * Serialize an error to the standard JSON envelope and exit.
+ * Used in both the startup try/catch and `runWithJsonErrors`.
  */
-function normalizeShowArgv(argv) {
-    // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
-    if (argv[2] !== "show")
-        return argv;
-    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
-        throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
-    }
-    // Separate global flags from positional/show-specific args
-    const prefix = argv.slice(0, 3); // [bun, script, show]
-    const rest = argv.slice(3);
-    const globalFlags = [];
-    const showArgs = [];
-    for (let i = 0; i < rest.length; i++) {
-        const arg = rest[i];
-        if (arg === "--quiet" || arg === "-q" || arg === "--for-agent" || arg === "--for-agent=true") {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg === "--format" || arg === "--detail") {
-            globalFlags.push(arg);
-            if (rest[i + 1] !== undefined) {
-                globalFlags.push(rest[i + 1]);
-                i++;
-            }
-            continue;
-        }
-        showArgs.push(arg);
-    }
-    // showArgs[0] = ref, showArgs[1] = potential view mode, showArgs[2..] = view params
-    const ref = showArgs[0];
-    const viewMode = showArgs[1];
-    if (!ref || !viewMode || !SHOW_VIEW_MODES.has(viewMode)) {
-        return argv;
-    }
-    const result = [...prefix, ref, "--akmView", viewMode];
-    if (viewMode === "section") {
-        // Next arg is the heading name; pass empty string when missing so the
-        // show handler can produce a clear "section not found" error.
-        const heading = showArgs[2] ?? "";
-        result.push("--akmHeading", heading);
+function emitJsonError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const hint = extractHint(error);
+    const exitCode = classifyExitCode(error);
+    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
+        ? error.code
+        : undefined;
+    console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
+    process.exit(exitCode);
+}
+async function runWithJsonErrors(fn) {
+    try {
+        await fn();
     }
-    else if (viewMode === "lines") {
-        // Next two args are start and end
-        const start = showArgs[2];
-        const end = showArgs[3];
-        if (start)
-            result.push("--akmStart", start);
-        if (end)
-            result.push("--akmEnd", end);
+    catch (error) {
+        emitJsonError(error);
     }
-    result.push(...globalFlags);
-    return result;
 }
 // ── Hints (embedded AGENTS.md) ──────────────────────────────────────────────
 function loadHints(detail = "normal") {