akm-cli 0.7.3 → 0.7.5

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/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";
@@ -34,6 +35,7 @@ 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 { ensureIndex } from "./indexer/ensure-index";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
 import { insertUsageEvent } from "./indexer/usage-events";
@@ -725,7 +727,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;
@@ -939,6 +941,30 @@ 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",
@@ -963,9 +989,13 @@ const feedbackCommand = defineCommand({
             default: false,
         },
         note: { type: "string", description: "Optional note to attach to the feedback" },
+        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 +1008,25 @@ 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 rawTags = parseAllFlagValues("--tag");
+            const validatedTags = validateFeedbackTags(rawTags);
+            const metadataObj = {
+                signal,
+                ...(args.note ? { note: args.note } : {}),
+                ...(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,7 +1038,7 @@ const feedbackCommand = defineCommand({
                     entry_ref: ref,
                     entry_id: entryId,
                     signal,
-                    metadata,
+                    metadata: metadataStr,
                 });
             }
             finally {
@@ -1004,9 +1047,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, note: args.note ?? null, tags: validatedTags });
         });
     },
 });
@@ -1132,7 +1175,7 @@ async function writeMarkdownAsset(options) {
 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,7 +1191,7 @@ 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 },
@@ -1161,9 +1204,8 @@ const workflowNextCommand = defineCommand({
             // 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 (!hasWorkflowRun(args.target)) {
                     throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
                 }
             }
@@ -1222,7 +1264,7 @@ 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 },
@@ -1261,7 +1303,7 @@ 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" },
@@ -1841,21 +1883,36 @@ 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 };
+    return { name: parsed.name, absPath, source, parsedRef: parsed };
 }
 /**
  * Walk `vaults/` recursively and return one entry per `.env` file, using the
@@ -1864,97 +1921,58 @@ 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;
+    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;
+                const { keys } = listKeysFn(full);
+                result.push({ ref: makeVaultRef(canonical, source), path: full, keys });
             }
-            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);
+        };
+        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;
+    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 });
         });
@@ -1968,9 +1986,9 @@ const vaultCreateCommand = defineCommand({
     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 });
+            output("vault-create", { ref: makeVaultRef(name, source), path: absPath });
         });
     },
 });
@@ -1992,7 +2010,7 @@ const vaultSetCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { setKey } = await import("./commands/vault.js");
-            const { name, absPath } = resolveVaultPath(args.ref);
+            const { name, absPath, source } = resolveVaultPath(args.ref);
             let realKey;
             let realValue;
             if ((args.value === undefined || args.value === "") && args.key.includes("=")) {
@@ -2005,7 +2023,7 @@ const vaultSetCommand = defineCommand({
                 realValue = args.value ?? "";
             }
             setKey(absPath, realKey, realValue, args.comment);
-            output("vault-set", { ref: `vault:${name}`, key: realKey, path: absPath });
+            output("vault-set", { ref: makeVaultRef(name, source), key: realKey, path: absPath });
         });
     },
 });
@@ -2018,100 +2036,89 @@ 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, path: absPath });
         });
     },
 });
-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);
-            }
-            catch {
-                /* best-effort on platforms without chmod */
+                throw new NotFoundError(`Vault not found: ${makeVaultRef(name, source)}`);
             }
-            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;
+                }
+            }
+            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 () => {
@@ -2374,10 +2381,26 @@ const eventsListCommand = defineCommand({
         },
         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);
         });
     },
@@ -2394,6 +2417,14 @@ const eventsTailCommand = defineCommand({
         "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 () => {
@@ -2406,6 +2437,8 @@ const eventsTailCommand = defineCommand({
             // 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 +2446,8 @@ const eventsTailCommand = defineCommand({
                 intervalMs,
                 maxDurationMs,
                 maxEvents,
+                ...(excludeTags.length > 0 ? { excludeTags } : {}),
+                ...(includeTags.length > 0 ? { includeTags } : {}),
                 onEvent: stream
                     ? (event) => {
                         if (mode.format === "jsonl") {
@@ -2575,6 +2610,14 @@ const distillCommand = defineCommand({
             type: "string",
             description: "Comma-separated asset refs whose feedback events MUST be filtered out before the LLM input is built. Falls back to AKM_DISTILL_EXCLUDE_FEEDBACK_FROM when omitted.",
         },
+        "exclude-tags": {
+            type: "string",
+            description: "Exclude feedback events matching these tags (repeatable, e.g. --exclude-tags slice:eval)",
+        },
+        "include-tags": {
+            type: "string",
+            description: "Only include feedback events with ALL these tags (repeatable)",
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -2583,10 +2626,38 @@ const distillCommand = defineCommand({
             // CLI flag takes precedence over the env var when both are present.
             const excludeRaw = excludeFlag ?? excludeEnv;
             const excludeFeedbackFromRefs = parseExcludeFeedbackFromRefs(excludeRaw);
+            const excludeTagsRaw = parseAllFlagValues("--exclude-tags");
+            const excludeTagsEnv = process.env.AKM_DISTILL_EXCLUDE_TAGS;
+            const excludeTags = [
+                ...new Set([
+                    ...excludeTagsRaw,
+                    ...(excludeTagsEnv
+                        ? excludeTagsEnv
+                            .split(",")
+                            .map((s) => s.trim())
+                            .filter(Boolean)
+                        : []),
+                ]),
+            ];
+            const includeTagsRaw = parseAllFlagValues("--include-tags");
+            const includeTagsEnv = process.env.AKM_DISTILL_INCLUDE_TAGS;
+            const includeTags = [
+                ...new Set([
+                    ...includeTagsRaw,
+                    ...(includeTagsEnv
+                        ? includeTagsEnv
+                            .split(",")
+                            .map((s) => s.trim())
+                            .filter(Boolean)
+                        : []),
+                ]),
+            ];
             const result = await akmDistill({
                 ref: args.ref,
                 sourceRun: getHyphenatedArg(args, "source-run"),
                 ...(excludeFeedbackFromRefs.length > 0 ? { excludeFeedbackFromRefs } : {}),
+                ...(excludeTags.length > 0 ? { excludeTags } : {}),
+                ...(includeTags.length > 0 ? { includeTags } : {}),
             });
             output("distill", result);
         });
@@ -2751,7 +2822,7 @@ const main = defineCommand({
     },
 });
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
-const VAULT_SUBCOMMAND_SET = new Set(["list", "show", "create", "set", "unset", "load"]);
+const VAULT_SUBCOMMAND_SET = new Set(["list", "path", "run", "create", "set", "unset"]);
 const WIKI_SUBCOMMAND_SET = new Set([
     "create",
     "register",

package/dist/commands/curate.js

@@ -135,6 +135,7 @@ async function enrichCuratedStashHit(query, hit) {
         ref: hit.ref,
         ...(description ? { description } : {}),
         ...(preview ? { preview } : {}),
+        ...(shown?.keys?.length ? { keys: shown.keys } : {}),
         ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
         ...(shown?.run ? { run: shown.run } : {}),
         followUp: `akm show ${hit.ref}`,