akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/sources/stash-cli.js

@@ -5,39 +5,39 @@
  * Stash-lifecycle command cluster — the create/index/ingest/inspect verbs for
  * the working stash and its index database: `akm init` (create the stash +
  * persist stashDir), `akm index` (build/refresh the search index), `akm import`
- * (ingest a knowledge doc/URL), `akm db` (+ nested `backups` — inspect the
- * SQLite data dir), and `akm info` (system capabilities + index stats).
+ * (ingest a knowledge doc/URL), and `akm info` (system capabilities + index
+ * stats).
  * Extracted verbatim from src/cli.ts (WS6) so the God Module shrinks; the
- * `main.subCommands.{init,index,import,db,info}` keys and every subcommand's
+ * `main.subCommands.{init,index,import,info}` keys and every subcommand's
  * args/output shape stay byte-identical.
  *
  * These share no private helper with any command still inline in cli.ts — every
  * dependency is already exported from a shared module (core/paths, core/warn,
  * core/errors, core/events, output/context, cli/shared, cli/parse-args, plus the
- * per-command implementations in ./init, ./indexer, ./info, ./db-cli, ./knowledge,
+ * per-command implementations in ./init, ./indexer, ./info, ./knowledge,
  * ./core/asset-create, ./core/common), so the cluster moves with zero hoisting.
  *
  * The leaf handlers whose body is a plain `runWithJsonErrors(...) + output(...)`
- * (`init`, `import`, `info`, `db`, `db backups`) are migrated onto
+ * (`init`, `import`, `info`) are migrated onto
  * `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
  * exit-code) as the inline form. `index` keeps a plain `defineCommand` wrapping
  * `runWithJsonErrors` because its body owns a spinner, an AbortController, and
  * SIGINT/SIGTERM handlers in a try/finally — left byte-for-byte untouched.
  */
 import path from "node:path";
-import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
-import { hasSubcommand } from "../../cli/parse-args.js";
+import * as p from "../../cli/clack.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { isHttpUrl } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { getCacheDir } from "../../core/paths.js";
 import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
-import { akmDbBackups } from "../db-cli.js";
 import { readKnowledgeInput, writeMarkdownAsset } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
 import { akmInit } from "./init.js";
@@ -48,12 +48,20 @@ export const initCommand = defineJsonCommand({
     },
     args: {
         dir: { type: "string", description: "Custom stash directory path (default: ~/akm)" },
+        "set-default": {
+            type: "boolean",
+            description: "Make --dir the default stash (write stashDir to config.json). Without this, `akm init --dir X` scaffolds X but leaves your existing default stash unchanged.",
+            default: false,
+        },
     },
     async run({ args }) {
         // Accept both historical spellings for backwards compatibility with
         // older docs/scripts that used `--stashDir`.
         const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
-        const result = await akmInit({ dir: args.dir ?? legacyDir });
+        const result = await akmInit({
+            dir: args.dir ?? legacyDir,
+            setDefault: args["set-default"],
+        });
         output("init", result);
     },
 });
@@ -145,35 +153,6 @@ export const infoCommand = defineJsonCommand({
         output("info", result);
     },
 });
-// MVP DB administration. Currently only `akm db backups`; restore is manual —
-// stop akm and run `scripts/migrations/restore-data-dir.sh <backup>`.
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const dbSubCommands = {
-    backups: defineJsonCommand({
-        meta: {
-            name: "backups",
-            description: "List pre-upgrade snapshots of the data directory (newest first). Backups are created automatically before destructive DB version upgrades unless AKM_DB_BACKUP=0.",
-        },
-        run() {
-            output("db-backups", akmDbBackups());
-        },
-    }),
-};
-const DB_SUBCOMMAND_SET = new Set(Object.keys(dbSubCommands));
-export const dbCommand = defineJsonCommand({
-    meta: {
-        name: "db",
-        description: "Inspect the AKM SQLite data directory. Currently exposes `backups`; to restore from a snapshot, stop akm and run scripts/migrations/restore-data-dir.sh against the chosen backup.",
-    },
-    subCommands: dbSubCommands,
-    run({ args }) {
-        if (hasSubcommand(args, DB_SUBCOMMAND_SET))
-            return;
-        // Default action: list backups.
-        output("db-backups", akmDbBackups());
-    },
-});
 export const importKnowledgeCommand = defineJsonCommand({
     meta: {
         name: "import",
@@ -206,7 +185,8 @@ export const importKnowledgeCommand = defineJsonCommand({
     async run({ args }) {
         // `--name` is a flat name; subdirectory placement is `--path`'s job.
         assertFlatAssetName(args.name);
-        const { content, preferredName } = await readKnowledgeInput(args.source);
+        const stashDir = resolveWriteTarget(loadConfig(), args.target).source.path;
+        const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
         const result = await writeMarkdownAsset({
             type: "knowledge",
             content,

package/dist/commands/sources/stash-skeleton.js

@@ -6,27 +6,42 @@ import path from "node:path";
 import { getDirname } from "../../runtime.js";
 const SKELETON_DIR = path.join(getDirname(import.meta.url), "../../assets/stash-skeleton");
 /**
- * Copy the default stash skeleton into a newly created stash directory.
+ * Copy the default stash skeleton into a stash directory.
  *
- * Each file in src/assets/stash-skeleton/ is written to the stash root only
- * if the destination does not already exist — existing files are never
- * overwritten. Non-fatal: if the skeleton directory is missing or a copy
- * fails the caller continues normally.
+ * The skeleton tree under src/assets/stash-skeleton/ is mirrored **recursively**
+ * into the stash root, preserving relative subpaths (e.g.
+ * `facts/conventions/assets/skill.md` lands at the matching stash subpath).
+ * Each file is written only if the destination does not already exist — existing
+ * (possibly user-edited) files are never overwritten. Intermediate directories
+ * are created as needed.
+ *
+ * Idempotent and absent-only: running it again on an existing stash backfills
+ * any skeleton files that are missing without clobbering present ones. Non-fatal:
+ * if the skeleton directory is missing or a copy fails the caller continues.
  */
 export function copyStashSkeleton(stashDir) {
+    copySkeletonDir(SKELETON_DIR, stashDir);
+}
+/** Recursively mirror `srcDir` into `destDir`, writing files only when absent. */
+function copySkeletonDir(srcDir, destDir) {
     let entries;
     try {
-        entries = fs.readdirSync(SKELETON_DIR);
+        entries = fs.readdirSync(srcDir, { withFileTypes: true });
     }
     catch {
         return;
     }
     for (const entry of entries) {
-        const src = path.join(SKELETON_DIR, entry);
-        const dest = path.join(stashDir, entry);
+        const src = path.join(srcDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copySkeletonDir(src, dest);
+            continue;
+        }
         if (fs.existsSync(dest))
             continue;
         try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(src, dest);
         }
         catch {
@@ -56,6 +71,40 @@ export function scaffoldStashMeta(stashDir) {
         // Non-fatal — stash is usable without the .meta orientation doc
     }
 }
+/** Marks the akm-authored block in a stash `.gitignore` (idempotency anchor). */
+const STASH_GITIGNORE_MARKER = "# akm: keep secret material out of git by default";
+const STASH_GITIGNORE_BLOCK = [
+    STASH_GITIGNORE_MARKER,
+    "# env/ and secrets/ assets hold tokens and keys. They are ignored by default",
+    "# so `git push` can never leak them. To version a specific one (e.g. for a",
+    "# private-remote backup), un-ignore its path below once you accept the risk.",
+    "env/",
+    "secrets/",
+    "",
+].join("\n");
+/**
+ * Ensure the stash `.gitignore` keeps `env/` and `secrets/` out of git by
+ * default (08-F1: the v0.8.0 `vaults/` → `env/`+`secrets/` migration never
+ * carried the ignore rules forward, and init scaffolded none).
+ *
+ * Idempotent + non-clobbering: creates the file when absent, appends the akm
+ * block when the file exists but lacks it (preserving the user's own rules),
+ * and no-ops once the marker is present. The user opts INTO versioning by
+ * un-ignoring a path.
+ */
+export function ensureStashGitignore(stashDir) {
+    try {
+        const gitignorePath = path.join(stashDir, ".gitignore");
+        const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
+        if (existing.includes(STASH_GITIGNORE_MARKER))
+            return;
+        const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        fs.writeFileSync(gitignorePath, `${existing}${gap}${STASH_GITIGNORE_BLOCK}`);
+    }
+    catch {
+        // Non-fatal — the stash is usable without the ignore scaffold.
+    }
+}
 const STASH_META_INDEX_TEMPLATE = `---
 # Optional, human-authored orientation for this stash. Not indexed; surfaced
 # on demand via \`akm show meta\` (this file) or \`akm show <stash>//meta\`.

package/dist/commands/tasks/default-tasks.js

@@ -20,8 +20,9 @@ import fs from "node:fs";
 import os from "node:os";
 import { akmTasksAdd, akmTasksList } from "./tasks.js";
 /**
- * The canonical default improve task set. `update-stashes` is deliberately NOT
- * listed here — it ships as an embedded core template and is left unchanged.
+ * The canonical default improve task set. The `update-stashes` embedded core
+ * template (nightly `akm update --all`) was retired in meta-review 06-M2:
+ * third-party stash pulls are on-demand only now, not a scheduled cron.
  */
 export const DEFAULT_IMPROVE_TASKS = [
     {
@@ -76,12 +77,19 @@ const DEFAULT_DEPS = {
     list: akmTasksList,
     add: akmTasksAdd,
 };
+let defaultTasksOverrides;
+/** TEST-ONLY. Swap the CI/server/register functions; pass undefined to restore. */
+export function _setDefaultTasksForTests(fakes) {
+    defaultTasksOverrides = fakes;
+}
 /**
  * Decide whether `akm setup` is running in a CI environment, where it must
  * register NO scheduled tasks. Mirrors the common `CI=true` convention used by
  * GitHub Actions, GitLab CI, CircleCI, etc.
  */
 export function isCiEnvironment(env = process.env) {
+    if (defaultTasksOverrides?.isCiEnvironment)
+        return defaultTasksOverrides.isCiEnvironment(env);
     const ci = env.CI;
     if (ci === undefined || ci === null)
         return false;
@@ -95,6 +103,8 @@ export function isCiEnvironment(env = process.env) {
  * Used as the default when setup is non-interactive (no TTY / --yes / CI).
  */
 export function detectServerDefault() {
+    if (defaultTasksOverrides?.detectServerDefault)
+        return defaultTasksOverrides.detectServerDefault();
     if (os.platform() !== "linux")
         return false;
     // A laptop exposes a battery under /sys/class/power_supply/BAT*. Absence of
@@ -121,6 +131,9 @@ export function detectServerDefault() {
  *   never re-disable a user-enabled task).
  */
 export async function registerDefaultTasks(options = {}) {
+    if (defaultTasksOverrides?.registerDefaultTasks) {
+        return defaultTasksOverrides.registerDefaultTasks(options);
+    }
     if (isCiEnvironment()) {
         return { skipped: true, reason: "ci", created: [], existing: [], toggled: [] };
     }

package/dist/commands/tasks/tasks-cli.js

@@ -13,9 +13,8 @@
  * with the family.
  */
 import { defineCommand } from "citty";
-import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
-import { getHyphenatedArg } from "../../output/context.js";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { detectServerDefault, registerDefaultTasks } from "./default-tasks.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./tasks.js";
 const tasksAddCommand = defineJsonCommand({
@@ -51,7 +50,7 @@ const tasksAddCommand = defineJsonCommand({
             profile: args.profile,
             params: args.params,
             name: args.name,
-            when_to_use: getHyphenatedArg(args, "when-to-use"),
+            when_to_use: args["when-to-use"],
             description: args.description,
             tags: args.tags
                 ? args.tags
@@ -176,35 +175,27 @@ const tasksDoctorCommand = defineJsonCommand({
         output("tasks-doctor", result);
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const tasksSubCommands = {
-    add: tasksAddCommand,
-    init: tasksInitCommand,
-    list: tasksListCommand,
-    show: tasksShowCommand,
-    remove: tasksRemoveCommand,
-    enable: tasksEnableCommand,
-    disable: tasksDisableCommand,
-    run: tasksRunCommand,
-    history: tasksHistoryCommand,
-    sync: tasksSyncCommand,
-    doctor: tasksDoctorCommand,
-};
-const TASKS_SUBCOMMAND_SET = new Set(Object.keys(tasksSubCommands));
-export const tasksCommand = defineCommand({
+export const tasksCommand = defineGroupCommand({
     meta: {
         name: "tasks",
         alias: "task",
         description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
     },
-    subCommands: tasksSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
-                return;
-            const result = await akmTasksList();
-            output("tasks-list", result);
-        });
+    subCommands: {
+        add: tasksAddCommand,
+        init: tasksInitCommand,
+        list: tasksListCommand,
+        show: tasksShowCommand,
+        remove: tasksRemoveCommand,
+        enable: tasksEnableCommand,
+        disable: tasksDisableCommand,
+        run: tasksRunCommand,
+        history: tasksHistoryCommand,
+        sync: tasksSyncCommand,
+        doctor: tasksDoctorCommand,
+    },
+    async defaultRun() {
+        const result = await akmTasksList();
+        output("tasks-list", result);
     },
 });

package/dist/commands/tasks/tasks.js

@@ -16,11 +16,12 @@ import { isWithin, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { listAgentProfileNames } from "../../integrations/agent/index.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
-import { resolveAkmInvocation } from "../../tasks/resolveAkmBin.js";
+import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
@@ -38,7 +39,8 @@ export async function akmTasksAdd(input) {
     // Validate the schedule for the active backend before writing anything.
     const backend = backendNameForPlatform();
     parseSchedule(input.schedule, backend);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     fs.mkdirSync(typeRoot, { recursive: true });
     const assetPath = resolveAssetPathFromName("task", typeRoot, id);
@@ -64,7 +66,8 @@ export async function akmTasksAdd(input) {
     });
     const task = parseTaskDocument({ yaml, filePath: assetPath, id });
     await validateTaskDocument(task, { backend, stashDir });
-    fs.writeFileSync(assetPath, yaml.endsWith("\n") ? yaml : `${yaml}\n`, "utf8");
+    const ref = taskAssetRef(id);
+    await writeAssetToSource(target.source, target.config, ref, yaml);
     // Install in the OS scheduler. If install fails after the file was written,
     // delete the file so the on-disk state never claims a task is registered
     // when it isn't.
@@ -74,13 +77,14 @@ export async function akmTasksAdd(input) {
     }
     catch (err) {
         try {
-            fs.rmSync(assetPath, { force: true });
+            await deleteAssetFromSource(target.source, target.config, ref);
         }
         catch {
             /* ignore */
         }
         throw err;
     }
+    commitWriteTargetBoundary(target, `Update task:${id}`);
     return {
         id,
         ref: `task:${id}`,
@@ -192,30 +196,47 @@ export async function akmTasksShow(id) {
 }
 export async function akmTasksRemove(id) {
     const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
         warnLegacyMdTaskFiles(typeRoot);
-    const filePath = await resolveAssetPath(stashDir, "task", normalised);
+    await resolveAssetPath(stashDir, "task", normalised);
+    const ref = taskAssetRef(normalised);
     const sched = selectBackend();
+    let uninstallError;
+    let deleteError;
     try {
         await sched.uninstall(normalised);
     }
-    finally {
-        fs.rmSync(filePath, { force: true });
+    catch (err) {
+        uninstallError = err;
+    }
+    try {
+        await deleteAssetFromSource(target.source, target.config, ref);
     }
+    catch (err) {
+        deleteError = err;
+    }
+    if (uninstallError !== undefined)
+        throw uninstallError;
+    if (deleteError !== undefined)
+        throw deleteError;
+    commitWriteTargetBoundary(target, `Remove task:${normalised}`);
     return { id: normalised, removed: true, backend: sched.name };
 }
 export async function akmTasksSetEnabled(id, enabled) {
     const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
         warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const yaml = fs.readFileSync(filePath, "utf8");
     const updated = setEnabledInYaml(yaml, enabled);
-    fs.writeFileSync(filePath, updated, "utf8");
+    const ref = taskAssetRef(normalised);
+    await writeAssetToSource(target.source, target.config, ref, updated);
     const sched = selectBackend();
     try {
         // Reinstall from the (just-updated) definition rather than only toggling
@@ -229,9 +250,10 @@ export async function akmTasksSetEnabled(id, enabled) {
     catch (err) {
         // Roll the file back so the YAML source-of-truth and the OS
         // scheduler don't diverge silently when the backend call fails.
-        fs.writeFileSync(filePath, yaml, "utf8");
+        await writeAssetToSource(target.source, target.config, ref, yaml);
         throw err;
     }
+    commitWriteTargetBoundary(target, `Update task:${normalised}`);
     return { id: normalised, enabled, backend: sched.name };
 }
 export async function akmTasksRun(id) {
@@ -392,6 +414,12 @@ function normaliseTaskId(raw) {
     }
     return id;
 }
+function taskAssetRef(id) {
+    return { type: "task", name: id };
+}
+function resolveTaskWriteTarget() {
+    return resolveWriteTarget(loadConfig());
+}
 function renderTaskYaml(input) {
     const obj = { schedule: input.schedule };
     if (input.workflow) {

package/dist/commands/wiki-cli.js

@@ -11,12 +11,11 @@
  * `process.exit(1)` after the wrapper when findings exist.
  */
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand, parsePositiveIntFlag } from "../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
-import { isHttpUrl, resolveStashDir } from "../core/common.js";
+import { getStringArg, parsePositiveIntFlag } from "../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
+import { resolveStashDir } from "../core/common.js";
 import { loadConfig, resolveConfiguredSources } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
-import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context.js";
 import { akmAgentDispatch } from "./agent/agent-dispatch.js";
 import { readKnowledgeInput } from "./read/knowledge.js";
 import { buildWebsiteOptions } from "./sources/add-cli.js";
@@ -108,7 +107,7 @@ const wikiRemoveCommand = defineJsonCommand({
             process.stderr.write("Aborted.\n");
             return;
         }
-        const withSources = getHyphenatedBoolean(args, "with-sources");
+        const withSources = args["with-sources"];
         const { removeWiki } = await import("../wiki/wiki.js");
         const { akmIndex } = await import("../indexer/indexer.js");
         const stashDir = resolveStashDir();
@@ -168,13 +167,6 @@ const wikiStashCommand = defineJsonCommand({
     },
     async run({ args }) {
         const { stashRaw } = await import("../wiki/wiki.js");
-        const { content, preferredName } = await (async () => {
-            if (!isHttpUrl(args.source))
-                return readKnowledgeInput(args.source);
-            const { fetchWebsiteMarkdownSnapshot } = await import("../sources/website-ingest.js");
-            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.
@@ -193,6 +185,7 @@ const wikiStashCommand = defineJsonCommand({
         else {
             stashDir = resolveStashDir();
         }
+        const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
         const result = stashRaw({
             stashDir,
             wikiName: args.name,
@@ -250,7 +243,7 @@ const wikiIngestCommand = defineJsonCommand({
         if (!profileName) {
             throw new UsageError("akm wiki ingest requires an agent profile. Pass --profile <name> or set defaults.agent in config.", "MISSING_REQUIRED_ARGUMENT", "Available profiles are listed under profiles.agent in your config. Run `akm config get profiles.agent` to inspect.");
         }
-        const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+        const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
         const model = getStringArg(args, "model");
         const { getDefaultLlmConfig } = await import("../core/config/config.js");
         const dispatchResult = await akmAgentDispatch({
@@ -274,34 +267,26 @@ const wikiIngestCommand = defineJsonCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const wikiSubCommands = {
-    create: wikiCreateCommand,
-    register: wikiRegisterCommand,
-    list: wikiListCommand,
-    show: wikiShowCommand,
-    remove: wikiRemoveCommand,
-    pages: wikiPagesCommand,
-    search: wikiSearchCommand,
-    stash: wikiStashCommand,
-    lint: wikiLintCommand,
-    ingest: wikiIngestCommand,
-};
-const WIKI_SUBCOMMAND_SET = new Set(Object.keys(wikiSubCommands));
-export const wikiCommand = defineCommand({
+export const wikiCommand = defineGroupCommand({
     meta: {
         name: "wiki",
         description: "Manage multiple markdown wikis (Karpathy-style). akm surfaces (lifecycle, raw/, lint, index); the agent writes pages.",
     },
-    subCommands: wikiSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, WIKI_SUBCOMMAND_SET))
-                return;
-            // Default action: list wikis
-            const { listWikis } = await import("../wiki/wiki.js");
-            output("wiki-list", { wikis: listWikis(resolveStashDir()) });
-        });
+    subCommands: {
+        create: wikiCreateCommand,
+        register: wikiRegisterCommand,
+        list: wikiListCommand,
+        show: wikiShowCommand,
+        remove: wikiRemoveCommand,
+        pages: wikiPagesCommand,
+        search: wikiSearchCommand,
+        stash: wikiStashCommand,
+        lint: wikiLintCommand,
+        ingest: wikiIngestCommand,
+    },
+    async defaultRun() {
+        // Default action: list wikis
+        const { listWikis } = await import("../wiki/wiki.js");
+        output("wiki-list", { wikis: listWikis(resolveStashDir()) });
     },
 });

package/dist/commands/workflow-cli.js

@@ -24,7 +24,7 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { resolveAssetPath } from "../sources/resolve.js";
 import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
 import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
-import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
+import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStartCommand = defineJsonCommand({
     meta: {
         name: "start",
@@ -290,6 +290,19 @@ async function resolveWorkflowFilePath(target) {
     }
     throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
 }
+const workflowAbandonCommand = defineJsonCommand({
+    meta: {
+        name: "abandon",
+        description: "Give up on a workflow run: mark it failed so it stops counting as active (resume can reopen it)",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+    },
+    async run({ args }) {
+        const result = await abandonWorkflowRun(args.runId);
+        output("workflow-abandon", result);
+    },
+});
 const workflowResumeCommand = defineJsonCommand({
     meta: {
         name: "resume",
@@ -317,6 +330,7 @@ export const workflowCommand = defineCommand({
         create: workflowCreateCommand,
         template: workflowTemplateCommand,
         resume: workflowResumeCommand,
+        abandon: workflowAbandonCommand,
         validate: workflowValidateCommand,
     },
     run({ args }) {

package/dist/core/asset/asset-registry.js

@@ -29,6 +29,7 @@ export const TYPE_TO_RENDERER = {
     wiki: "wiki-md",
     task: "task-yaml",
     session: "session-md",
+    fact: "fact-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -40,11 +41,12 @@ export const ACTION_BUILDERS = {
     lesson: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
-    env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (the agent-safe path — values never reach stdout). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
+    env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (prefer --clean to minimize inherited parent env; child stdout is not redacted). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
     secret: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
     task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
     session: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
+    fact: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
 };
 /**
  * Register a type-to-renderer mapping.