akm-cli 0.6.0 → 0.7.0-rc1

package/dist/{cli.js → src/cli.js}

@@ -5,13 +5,19 @@ import { defineCommand, runMain } from "citty";
 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 { akmHistory } from "./commands/history";
 import { assembleInfo } from "./commands/info";
 import { akmInit } from "./commands/init";
 import { akmListSources, akmRemove, akmUpdate } from "./commands/installed-stashes";
 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, parseSearchSource } from "./commands/search";
+import { akmSearch, parseScopeFilterFlags, parseSearchSource } from "./commands/search";
 import { checkForUpdate, performUpgrade } from "./commands/self-update";
 import { akmShowUnified } from "./commands/show";
 import { akmAdd } from "./commands/source-add";
@@ -22,8 +28,9 @@ import { deriveCanonicalAssetName, resolveAssetPathFromName } from "./core/asset
 import { isWithin, resolveStashDir, tryReadStdinText } from "./core/common";
 import { DEFAULT_CONFIG, getConfigPath, loadConfig, loadUserConfig, 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, warn } from "./core/warn";
+import { setQuiet, setVerbose, warn } from "./core/warn";
 import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
 import { closeDatabase, findEntryIdByRef, openDatabase } from "./indexer/db";
 import { akmIndex } from "./indexer/indexer";
@@ -32,7 +39,7 @@ import { insertUsageEvent } from "./indexer/usage-events";
 import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints";
 import { getHyphenatedArg, getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue, } from "./output/context";
 import { shapeForCommand } from "./output/shapes";
-import { formatPlain, outputJsonl } from "./output/text";
+import { formatEventLine, formatPlain, outputJsonl } from "./output/text";
 import { buildRegistryIndex, writeRegistryIndex } from "./registry/build-index";
 import { resolveSourcesForOrigin } from "./registry/origin-resolve";
 import { saveGitStash } from "./sources/providers/git";
@@ -58,6 +65,10 @@ function parseAllFlagValues(flag) {
         const arg = process.argv[i];
         if (arg === flag && i + 1 < process.argv.length) {
             values.push(process.argv[i + 1]);
+            // BUG-M4: skip the value index so `--tag --tag` (literal `--tag`
+            // value) does not double-count the second `--tag` as a separate
+            // flag occurrence.
+            i++;
         }
         else if (arg.startsWith(`${flag}=`)) {
             values.push(arg.slice(flag.length + 1));
@@ -96,7 +107,7 @@ function output(command, result) {
 const setupCommand = defineCommand({
     meta: {
         name: "setup",
-        description: "Interactive configuration wizard for embeddings, LLM, registries, and stash sources",
+        description: "Interactive configuration wizard: detects services and walks you through embeddings, LLM, registries, sources, and agent profiles. Writes config once at the end.",
     },
     async run() {
         await runWithJsonErrors(async () => {
@@ -154,10 +165,19 @@ const searchCommand = defineCommand({
         query: { type: "positional", description: "Search query (omit to list all assets)", required: false, default: "" },
         type: {
             type: "string",
-            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, or any). Use workflow to find step-by-step task assets.",
+            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, lesson, or any). Use workflow to find step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of results" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
+        filter: {
+            type: "string",
+            description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows results without changing ranking.",
+        },
+        "include-proposed": {
+            type: "boolean",
+            description: 'Include entries with quality:"proposed" in the result set. Excluded by default (v1 spec §4.2).',
+            default: false,
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
         detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
     },
@@ -165,7 +185,7 @@ const searchCommand = defineCommand({
         await runWithJsonErrors(async () => {
             const query = (args.query ?? "").trim();
             if (!query) {
-                throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT");
+                throw new UsageError('A search query is required. Usage: akm search "<query>" [--type <type>] [--limit <n>]', "MISSING_REQUIRED_ARGUMENT", "Provide a query string. Filter by type with --type skill|command|...; limit results with --limit N.");
             }
             const type = args.type;
             const limitRaw = args.limit ? parseInt(args.limit, 10) : undefined;
@@ -174,7 +194,12 @@ const searchCommand = defineCommand({
             }
             const limit = limitRaw;
             const source = parseSearchSource(args.source);
-            const result = await akmSearch({ query, type, limit, 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 });
             output("search", result);
         });
     },
@@ -182,16 +207,22 @@ const searchCommand = defineCommand({
 const curateCommand = defineCommand({
     meta: { name: "curate", description: "Curate the best matching assets for a task or prompt" },
     args: {
-        query: { type: "positional", description: "Task or prompt to curate assets for", required: true },
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        query: { type: "positional", description: "Task or prompt to curate assets for", required: false },
         type: {
             type: "string",
-            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, or any). Use workflow to curate step-by-step task assets.",
+            description: "Asset type filter (skill, command, agent, knowledge, workflow, script, memory, vault, wiki, lesson, or any). Use workflow to curate step-by-step task assets.",
         },
         limit: { type: "string", description: "Maximum number of curated results", default: "4" },
         source: { type: "string", description: "Search source (stash|registry|both)", default: "stash" },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (!args.query || !String(args.query).trim()) {
+                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)) {
@@ -234,14 +265,24 @@ const addCommand = defineCommand({
         },
         "max-pages": { type: "string", description: "Maximum pages to crawl for website sources (default: 50)" },
         "max-depth": { type: "string", description: "Maximum crawl depth for website sources (default: 3)" },
+        "allow-insecure": {
+            type: "boolean",
+            description: "Allow a plain HTTP source URL (otherwise rejected for non-localhost hosts)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const ref = args.ref.trim();
+            const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
             // URL with --provider → stash source (remote or git provider)
             if (args.provider) {
                 if (shouldWarnOnPlainHttp(ref)) {
-                    warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                    if (!allowInsecure) {
+                        throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+                    }
+                    warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
                 }
                 let parsedOptions;
                 if (args.options) {
@@ -265,11 +306,19 @@ const addCommand = defineCommand({
                     options: parsedOptions,
                     writable: args.writable,
                 });
+                appendEvent({
+                    eventType: "add",
+                    metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
+                });
                 output("add", result);
                 return;
             }
             if (shouldWarnOnPlainHttp(ref)) {
-                warn("Warning: source URL uses plain HTTP (not HTTPS). For security, prefer https:// to protect against eavesdropping and tampering.");
+                if (!allowInsecure) {
+                    throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                        "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+                }
+                warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
             }
             const websiteOptions = buildWebsiteOptions(args);
             if (args.type === "wiki") {
@@ -281,6 +330,10 @@ const addCommand = defineCommand({
                     trustThisInstall: args.trust,
                     writable: args.writable,
                 });
+                appendEvent({
+                    eventType: "add",
+                    metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
+                });
                 output("add", result);
                 return;
             }
@@ -292,6 +345,15 @@ const addCommand = defineCommand({
                 trustThisInstall: args.trust,
                 writable: args.writable,
             });
+            appendEvent({
+                eventType: "add",
+                metadata: {
+                    target: ref,
+                    name: args.name ?? null,
+                    overrideType: args.type ?? null,
+                    writable: args.writable === true,
+                },
+            });
             output("add", result);
         });
     },
@@ -353,6 +415,14 @@ const removeCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = await akmRemove({ target: args.target });
+            appendEvent({
+                eventType: "remove",
+                metadata: {
+                    target: args.target,
+                    ref: typeof result.removed?.ref === "string" ? result.removed.ref : null,
+                    id: typeof result.removed?.id === "string" ? result.removed.id : null,
+                },
+            });
             output("remove", result);
         });
     },
@@ -367,6 +437,17 @@ const updateCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = await akmUpdate({ target: args.target, all: args.all, force: args.force });
+            appendEvent({
+                eventType: "update",
+                metadata: {
+                    target: args.target ?? null,
+                    all: args.all === true,
+                    force: args.force === true,
+                    processed: Array.isArray(result.processed)
+                        ? result.processed.length
+                        : 0,
+                },
+            });
             output("update", result);
         });
     },
@@ -407,9 +488,17 @@ const showCommand = defineCommand({
         description: "Show a stash asset by ref (e.g. akm show knowledge:guide.md toc, akm show knowledge:guide.md section 'Auth')",
     },
     args: {
-        ref: { type: "positional", description: "Asset ref (type:name)", required: true },
+        ref: {
+            type: "positional",
+            description: 'Asset ref ([origin//]type:name) optionally followed by a view mode. View modes: `toc` (table of contents), `section "Heading"` (extract one section), `lines <start> <end>` (line range), `frontmatter` (YAML metadata only), `full` (raw file). Example: `akm show knowledge:guide.md section "Auth"`.',
+            required: true,
+        },
         format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
         detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
+        scope: {
+            type: "string",
+            description: "Scope filter (repeatable): --scope user=<id> --scope agent=<id> --scope run=<id> --scope channel=<name>. Narrows resolution to assets whose frontmatter scope matches.",
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -445,8 +534,13 @@ const showCommand = defineCommand({
                 }
             }
             const cliDetail = getOutputMode().detail;
-            const showDetail = cliDetail === "summary" ? "summary" : undefined;
-            const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail });
+            const explicitDetail = parseFlagValue(process.argv, "--detail");
+            const showDetail = explicitDetail === "brief" ? "brief" : cliDetail === "summary" ? "summary" : undefined;
+            // `--scope` is repeatable — citty only exposes the last value, so read
+            // every occurrence directly from argv (same pattern as `--filter`).
+            const scopeTokens = parseAllFlagValues("--scope");
+            const scope = parseScopeFilterFlags(scopeTokens, "--scope");
+            const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail, scope });
             output("show", result);
         });
     },
@@ -587,6 +681,14 @@ const saveCommand = defineCommand({
                 writable = cfg.writable === true ? true : undefined;
             }
             const result = saveGitStash(effectiveName, args.message, writable);
+            appendEvent({
+                eventType: "save",
+                metadata: {
+                    name: effectiveName ?? null,
+                    message: args.message ?? null,
+                    ok: result.ok !== false,
+                },
+            });
             output("save", result);
         });
     },
@@ -793,16 +895,19 @@ const feedbackCommand = defineCommand({
         description: "Record positive or negative feedback for any indexed stash asset",
     },
     args: {
-        ref: { type: "positional", description: "Asset ref (type:name)", required: true },
+        // Optional in citty so run() is invoked even when omitted; we re-validate
+        // and throw a structured UsageError below so exit code is 2 (USAGE) rather
+        // than citty's default 0 (help banner).
+        ref: { type: "positional", description: "Asset ref (type:name)", required: false },
         positive: { type: "boolean", description: "Record positive feedback", default: false },
         negative: { type: "boolean", description: "Record negative feedback", default: false },
         note: { type: "string", description: "Optional note to attach to the feedback" },
     },
     run({ args }) {
         return runWithJsonErrors(() => {
-            const ref = args.ref.trim();
+            const ref = (args.ref ?? "").trim();
             if (!ref) {
-                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative");
+                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
             }
             parseAssetRef(ref);
             if (args.positive && args.negative) {
@@ -830,10 +935,35 @@ const feedbackCommand = defineCommand({
             finally {
                 closeDatabase(db);
             }
+            appendEvent({
+                eventType: "feedback",
+                ref,
+                metadata: { signal, ...(args.note ? { note: args.note } : {}) },
+            });
             output("feedback", { ok: true, ref, signal, note: args.note ?? null });
         });
     },
 });
+const historyCommand = defineCommand({
+    meta: {
+        name: "history",
+        description: "Show mutation/usage history for a single asset (--ref) or stash-wide. Backed by the internal usage_events log.",
+    },
+    args: {
+        ref: { type: "string", description: "Asset ref (type:name). Omit for stash-wide history." },
+        since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const result = await akmHistory({
+                ref: args.ref,
+                since: args.since,
+            });
+            output("history", result);
+        });
+    },
+});
 function normalizeMarkdownAssetName(name, fallback) {
     const trimmed = (name ?? fallback)
         .trim()
@@ -943,11 +1073,40 @@ const workflowNextCommand = defineCommand({
     async run({ args }) {
         await runWithJsonErrors(async () => {
             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)) {
+                    throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
+                }
+            }
             const result = await getNextWorkflowStep(args.target, parsedParams);
             output("workflow-next", result);
         });
     },
 });
+/**
+ * Heuristic: a workflow run id is a UUID-shaped or hex-id-shaped string with
+ * no `:` separator (refs always contain a colon: `workflow:<name>` or
+ * `<origin>//workflow:<name>`). When this matches we can give a much better
+ * error than parseAssetRef's "Invalid asset type" failure.
+ */
+function looksLikeWorkflowRunId(target) {
+    if (target.includes(":"))
+        return false;
+    if (target.includes("/"))
+        return false;
+    // UUID v4-ish: 8-4-4-4-12 hex digits separated by dashes.
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target))
+        return true;
+    // Bare hex/alphanumeric run ids of >=8 chars (covers shortened ids).
+    if (/^[0-9a-z][0-9a-z_-]{7,}$/i.test(target) && /[0-9]/.test(target))
+        return true;
+    return false;
+}
 const workflowCompleteCommand = defineCommand({
     meta: {
         name: "complete",
@@ -1219,6 +1378,22 @@ const rememberCommand = defineCommand({
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
         },
+        user: {
+            type: "string",
+            description: "Scope this memory to a user id (persisted as `scope_user` frontmatter)",
+        },
+        agent: {
+            type: "string",
+            description: "Scope this memory to an agent id (persisted as `scope_agent` frontmatter)",
+        },
+        run: {
+            type: "string",
+            description: "Scope this memory to a run id (persisted as `scope_run` frontmatter)",
+        },
+        channel: {
+            type: "string",
+            description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
+        },
     },
     async run({ args }) {
         return runWithJsonErrors(async () => {
@@ -1227,7 +1402,21 @@ const rememberCommand = defineCommand({
             // Collect all --tag occurrences directly from process.argv because citty
             // only exposes the last value for repeated string flags.
             const rawTags = parseAllFlagValues("--tag");
-            const hasStructuredArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.auto || args.enrich;
+            // Collect scope flags. Scope alone counts as structured metadata so we
+            // emit frontmatter, but it does NOT trigger the "tags required" check —
+            // memory + scope (no tags) is a valid combination for multi-tenant use.
+            const scopeFields = {};
+            if (typeof args.user === "string" && args.user.trim())
+                scopeFields.user = args.user.trim();
+            if (typeof args.agent === "string" && args.agent.trim())
+                scopeFields.agent = args.agent.trim();
+            if (typeof args.run === "string" && args.run.trim())
+                scopeFields.run = args.run.trim();
+            if (typeof args.channel === "string" && args.channel.trim())
+                scopeFields.channel = args.channel.trim();
+            const hasScope = Object.keys(scopeFields).length > 0;
+            const hasTagRequiringArgs = rawTags.length > 0 || !!args.expires || !!args.source || !!args.description || args.auto || args.enrich;
+            const hasStructuredArgs = hasTagRequiringArgs || hasScope;
             if (!hasStructuredArgs) {
                 const result = await writeMarkdownAsset({
                     type: "memory",
@@ -1237,6 +1426,11 @@ const rememberCommand = defineCommand({
                     force: args.force,
                     target: args.target,
                 });
+                appendEvent({
+                    eventType: "remember",
+                    ref: result.ref,
+                    metadata: { path: result.path, force: args.force === true },
+                });
                 output("remember", { ok: true, ...result });
                 return;
             }
@@ -1282,8 +1476,12 @@ const rememberCommand = defineCommand({
                     observed_at = enriched.observed_at;
             }
             // ── Required-field check (before any write) ───────────────────────────
+            // Tags remain required when the user opted into a tag-producing mode
+            // (--tag / --auto / --enrich / --description / --source / --expires).
+            // Scope-only writes (`akm remember "..." --user u1`) skip this check —
+            // scope is independent metadata and a memory with only scope is valid.
             const missing = [];
-            if (tags.length === 0)
+            if (hasTagRequiringArgs && tags.length === 0)
                 missing.push("tags");
             if (missing.length > 0) {
                 throw new UsageError(`Memory is missing required frontmatter field(s): ${missing.join(", ")}. ` +
@@ -1297,6 +1495,7 @@ const rememberCommand = defineCommand({
                 observed_at,
                 expires,
                 subjective,
+                ...(hasScope ? { scope: scopeFields } : {}),
             });
             const contentWithFrontmatter = `${frontmatterBlock}\n${body}`;
             const result = await writeMarkdownAsset({
@@ -1307,6 +1506,18 @@ const rememberCommand = defineCommand({
                 force: args.force,
                 target: args.target,
             });
+            appendEvent({
+                eventType: "remember",
+                ref: result.ref,
+                metadata: {
+                    path: result.path,
+                    force: args.force === true,
+                    tagCount: tags.length,
+                    enriched: args.enrich === true,
+                    auto: args.auto === true,
+                    ...(hasScope ? { scope: scopeFields } : {}),
+                },
+            });
             output("remember", { ok: true, ...result });
         });
     },
@@ -1348,6 +1559,11 @@ const importKnowledgeCommand = defineCommand({
                 force: args.force,
                 target: args.target,
             });
+            appendEvent({
+                eventType: "import",
+                ref: result.ref,
+                metadata: { source: args.source, path: result.path, force: args.force === true },
+            });
             output("import", { ok: true, source: args.source, ...result });
         });
     },
@@ -1358,7 +1574,11 @@ const hintsCommand = defineCommand({
         description: "Print agent instructions on how to use akm, use --detail full for a complete guide",
     },
     args: {
-        detail: { type: "string", description: "Detail level (normal|full)", default: "normal" },
+        detail: {
+            type: "string",
+            description: "Hints detail level — accepts only `normal` or `full`. Differs from the global --detail flag (brief|normal|full|summary|agent); other values are rejected with INVALID_DETAIL_VALUE.",
+            default: "normal",
+        },
     },
     run({ args }) {
         if (args.detail !== "normal" && args.detail !== "full") {
@@ -1379,14 +1599,22 @@ const helpCommand = defineCommand({
                 description: "Print release notes and migration guidance for a version. Bundled notes live in docs/migration/release-notes/<version>.md; an unknown version lists what's available.",
             },
             args: {
+                // Optional in citty so run() is invoked even when omitted; we
+                // re-validate below to surface a structured UsageError (exit 2)
+                // instead of citty's default help-banner exit-0.
                 version: {
                     type: "positional",
                     description: "Version to review (for example 0.6.0, v0.6.0, 0.6.0-rc1, or latest)",
-                    required: true,
+                    required: false,
                 },
             },
             run({ args }) {
-                process.stdout.write(renderMigrationHelp(args.version));
+                return runWithJsonErrors(() => {
+                    if (!args.version || !String(args.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));
+                });
             },
         }),
     },
@@ -1427,9 +1655,6 @@ function normalizeToggleTarget(target) {
     const normalized = target.trim().toLowerCase();
     if (normalized === "skills.sh" || normalized === "skills-sh")
         return "skills.sh";
-    if (normalized === "context-hub") {
-        throw new UsageError('The "context-hub" component is no longer toggleable. Run `akm add github:andrewyng/context-hub --name context-hub` to add it as a git stash.');
-    }
     throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh`);
 }
 function toggleSkillsShRegistry(enabled) {
@@ -1535,6 +1760,53 @@ function listVaultsRecursive(listKeysFn) {
     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;
+        }
+    }
+    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 parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined && ref === parsedDetail && wasRefMisparsedAsFlagValue(ref, "--detail", parsedDetail)) {
+        return undefined;
+    }
+    return ref;
+}
 const vaultListCommand = defineCommand({
     meta: { name: "list", description: "List vaults, or list keys (no values) inside one vault" },
     args: {
@@ -1543,8 +1815,9 @@ const vaultListCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { listKeys, listEntries } = await import("./commands/vault.js");
-            if (args.ref) {
-                const { name, absPath } = resolveVaultPath(args.ref);
+            const effectiveRef = resolveVaultListRef(args.ref);
+            if (effectiveRef) {
+                const { name, absPath } = resolveVaultPath(effectiveRef);
                 if (!fs.existsSync(absPath)) {
                     throw new NotFoundError(`Vault not found: vault:${name}`);
                 }
@@ -1649,6 +1922,22 @@ const vaultLoadCommand = defineCommand({
             // 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 {
@@ -1942,6 +2231,343 @@ 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
+// 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" },
+    args: {
+        since: {
+            type: "string",
+            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-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)" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = akmEventsList({ since: args.since, type: args.type, ref: args.ref });
+            output("events-list", result);
+        });
+    },
+});
+const eventsTailCommand = defineCommand({
+    meta: { name: "tail", description: "Follow the append-only events.jsonl stream (polling)" },
+    args: {
+        since: {
+            type: "string",
+            description: "ISO timestamp / epoch ms, OR `@offset:<bytes>` for a durable byte-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" },
+    },
+    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 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 result = await akmEventsTail({
+                since: args.since,
+                type: args.type,
+                ref: args.ref,
+                intervalMs,
+                maxDurationMs,
+                maxEvents,
+                onEvent: stream
+                    ? (event) => {
+                        if (mode.format === "jsonl") {
+                            console.log(JSON.stringify(event));
+                        }
+                        else {
+                            console.log(formatEventLine(event));
+                        }
+                    }
+                    : undefined,
+            });
+            // Emit the canonical envelope last (JSON/YAML modes rely on this;
+            // streaming modes already printed each event but we still emit a
+            // trailer so callers can persist the resumable cursor).
+            if (!stream) {
+                output("events-tail", result);
+            }
+            else if (mode.format === "jsonl") {
+                // Final discriminated trailer row so jsonl consumers can resume.
+                const trailer = {
+                    _kind: "trailer",
+                    schemaVersion: 1,
+                    nextOffset: result.nextOffset,
+                    totalCount: result.totalCount,
+                    reason: result.reason,
+                };
+                console.log(JSON.stringify(trailer));
+            }
+            else {
+                // text mode: keep stdout pristine for line-oriented parsers and
+                // emit the trailer on stderr.
+                process.stderr.write(`[events-tail] reason=${result.reason} nextOffset=${result.nextOffset} total=${result.totalCount}\n`);
+            }
+        });
+    },
+});
+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)",
+    },
+    subCommands: {
+        list: eventsListCommand,
+        tail: eventsTailCommand,
+    },
+});
+// ── proposal substrate (#225) ────────────────────────────────────────────────
+const proposalListCommand = defineCommand({
+    meta: { name: "list", description: "List pending proposals (use --include-archive to see decided ones)" },
+    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,
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const status = parseProposalStatus(args.status);
+            const result = akmProposalList({
+                status,
+                ref: args.ref,
+                includeArchive: getHyphenatedBoolean(args, "include-archive"),
+            });
+            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" },
+    args: {
+        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        target: { type: "string", description: "Override the write target by source name" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const result = await akmProposalAccept({ id: args.id, target: args.target });
+            output("proposal-accept", result);
+        });
+    },
+});
+const proposalRejectCommand = defineCommand({
+    meta: { name: "reject", description: "Archive a pending proposal with an optional reason" },
+    args: {
+        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        reason: { type: "string", description: "Reason for rejection (recorded in the archived proposal)" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            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" },
+    args: {
+        id: { type: "positional", description: "Proposal id (uuid)", required: true },
+        target: { type: "string", description: "Override the write target by source name" },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const result = akmProposalDiff({ id: args.id, target: args.target });
+            output("proposal-diff", result);
+        });
+    },
+});
+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;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed === "pending" || trimmed === "accepted" || trimmed === "rejected")
+        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({
+    meta: {
+        name: "reflect",
+        description: "Ask the configured agent CLI to review an asset (or recent feedback) and queue a revised proposal",
+    },
+    args: {
+        ref: {
+            type: "positional",
+            description: "Asset ref (type:name) to reflect on. Optional — omit to reflect across recent feedback.",
+            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)" },
+        "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,
+                ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+            });
+            output("reflect", result);
+            if (result.ok === false) {
+                process.exit(EXIT_GENERAL);
+            }
+        });
+    },
+});
+const proposeCommand = defineCommand({
+    meta: {
+        name: "propose",
+        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
+    },
+    args: {
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        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?)" },
+        profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // 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 timeoutRaw = args["timeout-ms"];
+            const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+            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 } : {}),
+            });
+            output("propose", result);
+            if (result.ok === false) {
+                process.exit(EXIT_GENERAL);
+            }
+        });
+    },
+});
 const main = defineCommand({
     meta: {
         name: "akm",
@@ -1949,9 +2575,14 @@ const main = defineCommand({
         description: "Agent Kit Manager — search, show, and manage assets from your stash.",
     },
     args: {
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-        detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)" },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)", default: "json" },
+        detail: { type: "string", description: "Detail level (brief|normal|full|summary|agent)", default: "brief" },
         quiet: { type: "boolean", alias: "q", description: "Suppress stderr warnings", default: false },
+        verbose: {
+            type: "boolean",
+            description: "Print per-spec diagnostics to stderr (also honours AKM_VERBOSE env var)",
+            default: false,
+        },
     },
     subCommands: {
         setup: setupCommand,
@@ -1976,6 +2607,12 @@ const main = defineCommand({
         enable: enableCommand,
         disable: disableCommand,
         feedback: feedbackCommand,
+        history: historyCommand,
+        events: eventsCommand,
+        proposal: proposalCommand,
+        reflect: reflectCommand,
+        propose: proposeCommand,
+        distill: distillCommand,
         help: helpCommand,
         hints: hintsCommand,
         completions: completionsCommand,
@@ -2039,6 +2676,12 @@ async function runWithJsonErrors(fn) {
         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) {