akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/assets/wiki/ingest-workflow-template.md

@@ -6,20 +6,47 @@ Schema: {{SCHEMA_PATH}}
 Follow these steps. akm commands handle the invariants; use your native
 Read/Write/Edit tools for page edits.
 
+This workflow is for ingesting sources that are ALREADY present under
+`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
+empty and the caller explicitly asked for interactive ingest.
+
 1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
    kinds, contradiction policy, and any wiki-specific conventions. Do not
    skip this step even on familiar wikis — the schema may have changed.
 
-2. **File the source under `raw/`.**
+2. **Discover the pending raw queue.**
    ```sh
-   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   akm wiki lint {{WIKI_NAME}}
    ```
-   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
+   not yet cited by any authored page. Treat each `uncited-raw` finding as a
+   pending ingest item, and sort the queue **oldest raw file first** (by
+   filename/mtime). Processing oldest-first keeps backlog age bounded even
+   when the queue is larger than one run can finish. If there are no
+   `uncited-raw` findings, exit cleanly after a final `akm index` +
+   `akm wiki lint {{WIKI_NAME}}` verification.
+
+   Do not read or classify the whole backlog upfront. Work the queue as a
+   bounded loop, one raw file at a time: fully finish a raw (read → decide →
+   edit → log entry, steps 3-7 below) before looking at the next one. If you
+   run low on time partway through a large backlog, stop after finishing your
+   current raw — do not start a new one you can't complete. This is expected
+   and fine: whatever you already merged is committed to the pages and
+   `log.md`, so the next scheduled run picks up where you left off instead of
+   redoing this run's work.
+
+3. **For the current raw file, read the source and find related pages.**
+   Open the raw file directly from `{{WIKI_DIR}}/raw/`.
+
+   If the file does not read as text (binary content, garbled bytes, e.g. a
+   raw PDF byte-dump that was never text-extracted), do not attempt deep
+   forensic recovery (no web searches, no `strings`-style dumps). Append a
+   one-line `log.md` entry noting it as skipped/unprocessable with a short
+   reason, then move on to the next raw in the queue.
 
-3. **Find related existing pages.**
+   Otherwise, search for related pages:
    ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
    ```
    Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
    `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
@@ -39,8 +66,9 @@ Read/Write/Edit tools for page edits.
 6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
    page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
 
-7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
+7. **Append to `log.md`.** One entry per processed raw source (ingested or
+   skipped-as-unprocessable): date, raw slug, one-line summary, refs to
+   created/edited pages. Newest at the top.
 
 8. **Regenerate the index + verify.**
    ```sh
@@ -50,5 +78,5 @@ Read/Write/Edit tools for page edits.
    Resolve any lint findings before calling the ingest done.
 
 That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
+the invariants (raw immutability, ref validation, index regeneration,
+structural lint).

package/dist/cli/parse-args.js

@@ -8,7 +8,52 @@
  * main CLI file focused on command definitions and routing.
  */
 import { UsageError } from "../core/errors.js";
-// ── Subcommand detection ─────────────────────────────────────────────────────
+function cittyComparableName(name) {
+    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
+}
+function toAliasArray(alias) {
+    if (Array.isArray(alias))
+        return alias;
+    return typeof alias === "string" ? [alias] : [];
+}
+function isCittyValueFlag(flag, argsDef) {
+    const name = flag.replace(/^-{1,2}/, "");
+    const normalized = cittyComparableName(name);
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== "string" && def.type !== "enum")
+            continue;
+        if (normalized === cittyComparableName(key))
+            return true;
+        if (toAliasArray(def.alias).includes(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Match citty's top-level subcommand scan (`findSubCommandIndex`).
+ *
+ * Citty does not assume `rawArgs[0]` is the command: global string flags may
+ * appear first and consume the following token. The CLI startup guard uses this
+ * to classify the requested command before any command handler can run.
+ */
+export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
+    for (let i = 0; i < rawArgs.length; i += 1) {
+        const arg = rawArgs[i];
+        if (arg === "--")
+            return -1;
+        if (arg.startsWith("-")) {
+            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
+                i += 1;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+export function findCittyTopLevelCommand(rawArgs, argsDef) {
+    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
+    return index >= 0 ? rawArgs[index] : undefined;
+}
 /**
  * Return true when `args._[0]` is a member of `validSet`.
  *

package/dist/cli/shared.js

@@ -15,6 +15,7 @@ import { getOutputMode } from "../output/context.js";
 import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { hasSubcommand } from "./parse-args.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -111,6 +112,33 @@ export function defineJsonCommand(def) {
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
+ * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * DERIVED from that map's keys (so the set can never silently desync from the
+ * registered subcommands), and a default body that fires ONLY for the bare
+ * group invocation — citty still runs the group body after dispatching a
+ * subcommand, so the shared guard short-circuits when `args._[0]` names a
+ * registered subcommand.
+ *
+ * The `defaultRun` body is wrapped in `runWithJsonErrors`, so it emits a
+ * byte-identical JSON error envelope on throw — exactly the per-site
+ * `run() { return runWithJsonErrors(() => { if (hasSubcommand(...)) return; … }); }`
+ * boilerplate this replaces.
+ */
+export function defineGroupCommand(def) {
+    const subcommandSet = new Set(Object.keys(def.subCommands));
+    return defineCommand({
+        meta: def.meta,
+        ...(def.args ? { args: def.args } : {}),
+        subCommands: def.subCommands,
+        run: (context) => runWithJsonErrors(() => {
+            if (hasSubcommand(context.args, subcommandSet))
+                return;
+            return def.defaultRun(context);
+        }),
+    });
+}
 /**
  * Render a command result according to the active output mode
  * (json/jsonl/yaml/text/md/html). When `--output <path>` is set, the rendered

package/dist/cli.js

@@ -8,18 +8,21 @@
 // `dist/cli-node.mjs` wrapper, which registers the text-import loader hook
 // before this module graph loads; running `node dist/cli.js` directly still
 // works for code paths that touch no embedded text asset, but the wrapper is
-// the supported entry. The hard floor is Node 20: `@clack/core` (prompts) imports
+// the supported entry. The hard floor is Node 20.12: `@clack/core` (prompts) imports
 // `node:util`'s `styleText` (added in Node 20.12) — Node 18 (EOL) throws at import.
 {
     const isBun = typeof globalThis.Bun !== "undefined";
     if (!isBun) {
-        const major = Number.parseInt((process.versions.node ?? "0").split(".")[0], 10);
-        if (Number.isNaN(major) || major < 20) {
-            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.\n" +
+        const [major = 0, minor = 0, patch = 0] = (process.versions.node ?? "0")
+            .split(".")
+            .map((part) => Number.parseInt(part, 10) || 0);
+        const nodeOk = major > 20 || (major === 20 && (minor > 12 || (minor === 12 && patch >= 0)));
+        if (!nodeOk) {
+            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.12.\n" +
                 `  Detected Node.js ${process.versions.node ?? "unknown"}.\n` +
                 "  Install options:\n" +
                 "    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\n" +
-                "    2. Node:   upgrade to Node.js 20 or newer (https://nodejs.org)\n" +
+                "    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\n" +
                 "    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
             process.exit(1);
         }
@@ -57,6 +60,7 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
+import { findCittyTopLevelCommand } from "./cli/parse-args.js";
 import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared.js";
 import { agentCommand, lintCommand, proposeCommand } from "./commands/agent/contribute-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
@@ -77,7 +81,7 @@ import { registryCommand } from "./commands/registry-cli.js";
 import { addCommand } from "./commands/sources/add-cli.js";
 import { renderMigrationHelp } from "./commands/sources/migration-help.js";
 import { cloneCommand, historyCommand, listCommand, removeCommand, syncCommand, updateCommand, upgradeCommand, } from "./commands/sources/sources-cli.js";
-import { dbCommand, importKnowledgeCommand, indexCommand, infoCommand, initCommand, } from "./commands/sources/stash-cli.js";
+import { importKnowledgeCommand, indexCommand, infoCommand, initCommand } from "./commands/sources/stash-cli.js";
 import { tasksCommand } from "./commands/tasks/tasks-cli.js";
 import { wikiCommand } from "./commands/wiki-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
@@ -320,10 +324,14 @@ const healthCommand = defineCommand({
             // window-compare read for the trend deltas (defaults to 24h,
             // overridable via --compare).
             if (mode.format === "html") {
-                const compare = args.compare ?? windowCompareRaw ?? "24h";
-                const result = akmHealth({ since: args.since, groupBy: "run" });
+                // Default the compare window to the report's own `--since` window so the
+                // trend deltas are like-for-like (e.g. last 7d vs the prior 7d). A fixed
+                // 24h default made a `--since 7d` report compare its 7-day totals against
+                // a 24-hour prior window, producing meaningless deltas.
+                const compare = args.compare ?? windowCompareRaw ?? args.since ?? "24h";
+                const result = akmHealth({ since: args.since, groupBy: "run", windowCompare: compare });
                 resultStatus = result.status;
-                const deltas = akmHealth({ since: args.since, windowCompare: compare }).deltas;
+                const deltas = result.deltas;
                 const { buildHealthHtmlReplacements } = await import("./commands/health/html-report.js");
                 const { listPendingProposals } = await import("./commands/proposal/proposal.js");
                 const replacements = buildHealthHtmlReplacements(result, {
@@ -482,7 +490,6 @@ export const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
-        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -517,6 +524,7 @@ export const main = defineCommand({
         tasks: tasksCommand,
     },
 });
+const MAIN_TOP_LEVEL_ARGS = main.args;
 // ── Exit codes ──────────────────────────────────────────────────────────────
 // Canonical table lives in `src/cli/shared.ts` (EXIT_CODES). These aliases keep
 // the local call sites terse. EXIT_HEALTH_WARN (4) is the `akm health` "warn"
@@ -536,6 +544,13 @@ const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // The wrapper sets `AKM_NODE_ENTRY=1` to opt into the startup block. The test
 // harness never sets it, so importing cli.ts under Bun stays inert as before.
 if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
+    // Mark that this process is the real akm CLI: its `process.argv[1]` is the
+    // akm entrypoint, so the background auto-reindex may safely re-invoke it as a
+    // detached child. Hosts that merely import this module (the in-process test
+    // harness, library embeddings) never reach this block, so they fall back to
+    // an inline reindex instead of spawning the wrong program. See
+    // `ensureIndex` in src/indexer/ensure-index.ts.
+    process.env.AKM_CLI_ENTRY = "1";
     // citty reads process.argv directly and does not accept a custom argv array,
     // so we must replace process.argv with the normalized version before runMain.
     process.argv = normalizeShowArgv(process.argv);
@@ -557,7 +572,8 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // output-shaping time after the side effect has already happened. The
     // shape-registry gate in shapeForCommand() remains as defense-in-depth (and
     // covers the in-process test harness, which skips this startup block).
-    if (getOutputMode().shape === "summary" && process.argv[2] !== "show") {
+    const topLevelCommand = findCittyTopLevelCommand(process.argv.slice(2), MAIN_TOP_LEVEL_ARGS);
+    if (getOutputMode().shape === "summary" && topLevelCommand !== "show") {
         emitJsonError(new UsageError("'--shape summary' is only valid on 'akm show'.", "INVALID_SHAPE_VALUE"));
     }
     // One-time cleanup of stale 0.7.x index file at the old cache location.

package/dist/commands/agent/agent-dispatch.js

@@ -18,7 +18,7 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { requireAgentProfile } from "../../integrations/agent/config.js";
 import { runAgent } from "../../integrations/agent/spawn.js";
-import { runAgentSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 /**
  * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
  * corresponding entries in `args`. Any placeholder index that exceeds the
@@ -93,7 +93,7 @@ export async function akmAgentDispatch(options) {
         ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
     };
     const result = profile.sdkMode
-        ? await runAgentSdk(profile, prompt ?? "", runOptions, options.llmConfig)
+        ? await runOpencodeSdk(profile, prompt ?? "", runOptions, options.llmConfig)
         : await runAgent(profile, prompt, runOptions);
     return {
         schemaVersion: 1,

package/dist/commands/agent/agent-support.js

@@ -1,13 +1,6 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Shared helpers for agent-based commands (reflect, propose, etc.).
- *
- * Consolidates utility functions that were duplicated byte-for-byte across
- * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
- * profile can import from here rather than copy-pasting.
- */
 import { loadConfig } from "../../core/config/config.js";
 import { requireAgentProfile, } from "../../integrations/agent/index.js";
 // ── Config helpers ───────────────────────────────────────────────────────────

package/dist/commands/agent/contribute-cli.js

@@ -29,7 +29,7 @@ import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getHyphenatedArg } from "../../output/context.js";
-import { akmLint } from "../lint.js";
+import { akmLint } from "../lint/index.js";
 import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
@@ -122,23 +122,36 @@ export const lintCommand = defineCommand({
         description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
-        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        fix: {
+            type: "boolean",
+            alias: "auto-fix",
+            description: "Apply auto-fixes in place (alias: --auto-fix)",
+            default: false,
+        },
         dir: { type: "string", description: "Override stash root directory (default: from config)" },
         "fail-on-flagged": {
             type: "boolean",
             description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
             default: false,
         },
+        type: {
+            type: "string",
+            description: "Only lint assets of this type (e.g. workflows, tasks, memories)",
+            default: undefined,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = akmLint({
                 fix: args.fix ?? false,
                 dir: getStringArg(args, "dir"),
+                typeFilter: getStringArg(args, "type"),
             });
             output("lint", result);
-            if (args["fail-on-flagged"] && result.summary.flagged > 0)
-                process.exit(EXIT_GENERAL);
+            if (args["fail-on-flagged"] && result.summary.flagged > 0) {
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
         });
     },
 });

package/dist/commands/config-cli.js

@@ -64,7 +64,10 @@ function rewriteKey(config, key) {
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
     const k = rewriteKey(config, key);
-    return configGet(config, k);
+    const value = configGet(config, k);
+    if (k.split(".").at(-1) === "apiKey")
+        return null;
+    return omitApiKeysForOutput(value);
 }
 export function setConfigValue(config, key, rawValue) {
     // #454: reject the legacy aliases up front so the error message names the
@@ -154,7 +157,20 @@ export function listConfig(config) {
         result.archiveRetentionDays = config.archiveRetentionDays;
     if (config.configVersion !== undefined)
         result.configVersion = config.configVersion;
-    return result;
+    return omitApiKeysForOutput(result);
+}
+function omitApiKeysForOutput(value) {
+    if (Array.isArray(value))
+        return value.map(omitApiKeysForOutput);
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "apiKey")
+            continue;
+        out[key] = omitApiKeysForOutput(child);
+    }
+    return out;
 }
 export { unknownKeyHint };
 // ── `akm config` command surface ────────────────────────────────────────────

package/dist/commands/env/child-env.js

@@ -0,0 +1,47 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+const CLEAN_ENV_ALLOWLIST = [
+    "HOME",
+    "PATH",
+    "PWD",
+    "SHELL",
+    "TERM",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LANGUAGE",
+    "LC_ALL",
+    "LC_CTYPE",
+    "LC_COLLATE",
+    "LC_MESSAGES",
+    "LC_MONETARY",
+    "LC_NUMERIC",
+    "LC_TIME",
+    "LC_PAPER",
+    "LC_NAME",
+    "LC_ADDRESS",
+    "LC_TELEPHONE",
+    "LC_MEASUREMENT",
+    "LC_IDENTIFICATION",
+    "TZ",
+    "NO_COLOR",
+    "COLORTERM",
+];
+export function buildChildEnv(parentEnv, options) {
+    const base = options.clean ? {} : { ...parentEnv };
+    if (options.clean) {
+        for (const key of CLEAN_ENV_ALLOWLIST) {
+            if (parentEnv[key] !== undefined)
+                base[key] = parentEnv[key];
+        }
+    }
+    for (const key of options.inherit) {
+        if (parentEnv[key] !== undefined)
+            base[key] = parentEnv[key];
+    }
+    return base;
+}

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

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
 import { isWithin, writeFileAtomic } from "../../core/common.js";
@@ -32,6 +32,7 @@ import { isQuiet } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { getHyphenatedArg, parseFlagValue } from "../../output/context.js";
 import { readStdin } from "../../runtime.js";
+import { buildChildEnv } from "./child-env.js";
 /**
  * Walk each stash's env files and return one entry per `.env` file, using the
  * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
@@ -297,7 +298,10 @@ async function runEnvInjected(target, opts) {
         }
         process.stderr.write(`warning: ${detail} Injecting anyway (first-party stash).\n`);
     }
-    const mergedEnv = { ...process.env };
+    const mergedEnv = buildChildEnv(process.env, {
+        clean: opts.clean === true,
+        inherit: opts.inherit ?? [],
+    });
     for (const [envKey, envValue] of Object.entries(envValues)) {
         mergedEnv[envKey] = envValue;
     }
@@ -341,7 +345,7 @@ const envRunCommand = defineCommand({
         name: "run",
         description: 
         // biome-ignore lint/suspicious/noTemplateCurlyInString: literal `${secret:NAME}` token syntax documented for users, not interpolation
-        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `secret:NAME` value from the same stash.",
+        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `secret:NAME` value from the same stash. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
     },
     args: {
         target: { type: "positional", description: "Env ref", required: true },
@@ -350,11 +354,22 @@ const envRunCommand = defineCommand({
             description: "Inject ONLY these keys (comma-separated). Mutually exclusive with --except.",
         },
         except: { type: "string", description: "Inject all keys EXCEPT these (comma-separated)." },
+        clean: {
+            type: "boolean",
+            description: "Start the child with a minimal inherited environment (PATH/HOME/locale/terminal basics) instead of the full parent environment.",
+            default: false,
+        },
+        inherit: {
+            type: "string",
+            description: "When used with --clean, also inherit these parent env vars (comma-separated). Ignored without --clean.",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(() => runEnvInjected(args.target, {
             only: parseKeyListFlag(getHyphenatedArg(args, "only")),
             except: parseKeyListFlag(getHyphenatedArg(args, "except")),
+            clean: getHyphenatedArg(args, "clean") === true,
+            inherit: parseKeyListFlag(getHyphenatedArg(args, "inherit")) ?? [],
         }));
     },
 });
@@ -499,31 +514,23 @@ const envUnsetCommand = defineCommand({
         });
     },
 });
-// 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 envSubCommands = {
-    list: envListCommand,
-    path: envPathCommand,
-    export: envExportCommand,
-    run: envRunCommand,
-    create: envCreateCommand,
-    set: envSetCommand,
-    unset: envUnsetCommand,
-    remove: envRemoveCommand,
-};
-const ENV_SUBCOMMAND_SET = new Set(Object.keys(envSubCommands));
-export const envCommand = defineCommand({
+export const envCommand = defineGroupCommand({
     meta: {
         name: "env",
         description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
-    subCommands: envSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, ENV_SUBCOMMAND_SET))
-                return;
-            const { listKeys } = await import("./env.js");
-            output("env-list", { envs: listEnvsRecursive(listKeys) });
-        });
+    subCommands: {
+        list: envListCommand,
+        path: envPathCommand,
+        export: envExportCommand,
+        run: envRunCommand,
+        create: envCreateCommand,
+        set: envSetCommand,
+        unset: envUnsetCommand,
+        remove: envRemoveCommand,
+    },
+    async defaultRun() {
+        const { listKeys } = await import("./env.js");
+        output("env-list", { envs: listEnvsRecursive(listKeys) });
     },
 });

package/dist/commands/env/secret-cli.js

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
 import { loadConfig } from "../../core/config/config.js";
 import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
@@ -29,6 +29,16 @@ import { appendEvent } from "../../core/events.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { getHyphenatedArg } from "../../output/context.js";
 import { readStdin } from "../../runtime.js";
+import { buildChildEnv } from "./child-env.js";
+function parseKeyListFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const keys = raw
+        .split(/[,\s]+/)
+        .map((k) => k.trim())
+        .filter(Boolean);
+    return keys.length > 0 ? keys : undefined;
+}
 /** Walk `secrets/` across all stashes, returning one entry per secret file. */
 function listSecretsRecursive() {
     const result = [];
@@ -152,11 +162,20 @@ const secretPathCommand = defineCommand({
 const secretRunCommand = defineCommand({
     meta: {
         name: "run",
-        description: "Run a command with a secret's value injected into an env var: `akm secret run <ref> <VAR> -- <command>`. The value is set as $VAR in the child process only.",
+        description: "Run a command with a secret's value injected into an env var: `akm secret run <ref> <VAR> -- <command>`. The value is set as $VAR in the child process only. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
     },
     args: {
         ref: { type: "positional", description: "Secret ref", required: true },
         var: { type: "positional", description: "Environment variable name to inject the value into", required: true },
+        clean: {
+            type: "boolean",
+            description: "Start the child with a minimal inherited environment (PATH/HOME/locale/terminal basics) instead of the full parent environment.",
+            default: false,
+        },
+        inherit: {
+            type: "string",
+            description: "When used with --clean, also inherit these parent env vars (comma-separated). Ignored without --clean.",
+        },
     },
     run({ args }) {
         return runWithJsonErrors(async () => {
@@ -181,7 +200,10 @@ const secretRunCommand = defineCommand({
                 throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
             }
             const { readValue } = await import("./secret.js");
-            const mergedEnv = { ...process.env };
+            const mergedEnv = buildChildEnv(process.env, {
+                clean: getHyphenatedArg(args, "clean") === true,
+                inherit: parseKeyListFlag(getHyphenatedArg(args, "inherit")) ?? [],
+            });
             mergedEnv[varName] = readValue(absPath).toString("utf8");
             // Audit trail: record access by ref + var name only — never the value.
             appendEvent({
@@ -233,27 +255,19 @@ const secretRemoveCommand = defineCommand({
         });
     },
 });
-// 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 secretSubCommands = {
-    list: secretListCommand,
-    path: secretPathCommand,
-    run: secretRunCommand,
-    set: secretSetCommand,
-    remove: secretRemoveCommand,
-};
-const SECRET_SUBCOMMAND_SET = new Set(Object.keys(secretSubCommands));
-export const secretCommand = defineCommand({
+export const secretCommand = defineGroupCommand({
     meta: {
         name: "secret",
         description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
     },
-    subCommands: secretSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
-                return;
-            output("secret-list", { secrets: listSecretsRecursive() });
-        });
+    subCommands: {
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
+    },
+    defaultRun() {
+        output("secret-list", { secrets: listSecretsRecursive() });
     },
 });