akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/config-cli.js

@@ -11,14 +11,11 @@
  * `configVersion` is controlled by the config lifecycle. All execution
  * settings use their canonical engine/strategy paths; retired aliases are not
  * rewritten at this boundary.
- *   - `parseConfigValue` returns a Partial<AkmConfig> so it can be merged with
- *     the runtime config object via `mergeConfigValue`.
  */
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { resolveStashDir } from "../core/common.js";
 import { DEFAULT_CONFIG, loadConfig, mutateConfig } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
-import { UsageError } from "../core/errors.js";
 import { getCacheDir, getConfigPath, getDbPath, getDefaultStashDir } from "../core/paths.js";
 // ── Public API ──────────────────────────────────────────────────────────────
 export function getConfigValue(config, key) {
@@ -30,25 +27,6 @@ export function setConfigValue(config, key, rawValue) {
 export function unsetConfigValue(config, key) {
     return configUnset(config, key);
 }
-/**
- * Compatibility shim: returns a `Partial<AkmConfig>` containing just the
- * change. Older code merged this onto the live config — new code should call
- * `setConfigValue` directly (which returns the full merged config).
- */
-export function parseConfigValue(key, value) {
-    // Use a "marker" base so we can detect which top-level fields actually got
-    // touched by the set call. Anything still equal to the marker is untouched.
-    const SENTINEL = Symbol("untouched");
-    const base = { semanticSearchMode: SENTINEL };
-    const next = setConfigValue(base, key, value);
-    const patch = {};
-    for (const k of Object.keys(next)) {
-        if (next[k] !== SENTINEL) {
-            patch[k] = next[k];
-        }
-    }
-    return patch;
-}
 export function listConfig(config) {
     // 0.9.0 (spec §10.1): sources live in `bundles` (spread from config); the
     // retired top-level `sources[]` array is no longer surfaced.
@@ -71,63 +49,28 @@ function redactConfigValue(value) {
 export { unknownKeyHint };
 // ── `akm config` command surface ────────────────────────────────────────────
 // Extracted verbatim from src/cli.ts (WS6). The `main.subCommands.config` key
-// and every config subcommand's args/output shape are byte-identical. The
-// `skills.sh` toggle helpers and the `CONFIG_SUBCOMMAND_SET` routing constant
-// are used ONLY by this command, so they move with the cluster. Leaf handlers
-// whose body is a plain `runWithJsonErrors(() => { … })` are migrated to
-// `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
-// exit-code) as the inline form.
-const SKILLS_SH_NAME = "skills.sh";
-const SKILLS_SH_URL = "https://skills.sh";
-const SKILLS_SH_PROVIDER = "skills-sh";
-function normalizeToggleTarget(target) {
-    const normalized = target.trim().toLowerCase();
-    if (normalized === "skills.sh" || normalized === "skills-sh")
-        return "skills.sh";
-    throw new UsageError(`Unsupported target "${target}". Supported targets: skills.sh`);
-}
-function toggleSkillsShRegistry(enabled) {
-    let changed = false;
-    mutateConfig((config) => {
-        const registries = (config.registries ?? DEFAULT_CONFIG.registries ?? []).map((registry) => ({ ...registry }));
-        const idx = registries.findIndex((registry) => registry.provider === SKILLS_SH_PROVIDER || registry.name === SKILLS_SH_NAME || registry.url === SKILLS_SH_URL);
-        if (idx >= 0) {
-            const target = registries[idx];
-            const wasEnabled = target.enabled !== false;
-            target.enabled = enabled;
-            changed = wasEnabled !== enabled;
-            return { ...config, registries };
-        }
-        registries.push({ url: SKILLS_SH_URL, name: SKILLS_SH_NAME, provider: SKILLS_SH_PROVIDER, enabled });
-        changed = true;
-        return { ...config, registries };
-    });
-    return { changed, component: SKILLS_SH_NAME, enabled };
-}
-function toggleComponent(targetRaw, enabled) {
-    const target = normalizeToggleTarget(targetRaw);
-    if (target === "skills.sh")
-        return toggleSkillsShRegistry(enabled);
-    // normalizeToggleTarget throws for any unsupported target; this is unreachable.
-    throw new UsageError(`Unsupported target "${targetRaw}". Supported targets: skills.sh`);
-}
+// and every config subcommand's args/output shape are byte-identical. Leaf
+// handlers whose body is a plain `runWithJsonErrors(() => { … })` are
+// migrated to `defineJsonCommand`, which emits the same JSON envelope
+// (stdout/stderr/exit-code) as the inline form.
+//
+// `akm config enable|disable` (a hardcoded alias for toggling the skills.sh
+// registry) was removed in 0.9.0 (C4). Use `akm registry add|remove`, the
+// general mechanism, instead.
 export const configCommand = defineGroupCommand({
     meta: { name: "config", description: "Show and manage configuration" },
-    args: {
-        list: { type: "boolean", description: "List current configuration", default: false },
-    },
     subCommands: {
         path: defineJsonCommand({
-            meta: { name: "path", description: "Show paths to config, stash, cache, and index" },
+            meta: { name: "path", description: "Show paths to config, bundle, cache, and index" },
             args: {
-                all: { type: "boolean", description: "Show all paths (config, stash, cache, index)", default: false },
+                all: { type: "boolean", description: "Show all paths (config, bundle, cache, index)", default: false },
             },
             run({ args }) {
                 const configPath = getConfigPath();
                 if (args.all) {
                     let stashDir;
                     try {
-                        stashDir = resolveStashDir({ readOnly: true });
+                        stashDir = resolveStashDir();
                     }
                     catch {
                         stashDir = `${getDefaultStashDir()} (not initialized)`;
@@ -135,7 +78,7 @@ export const configCommand = defineGroupCommand({
                     const cacheDir = getCacheDir();
                     const result = {
                         config: configPath,
-                        stash: stashDir,
+                        bundle: stashDir,
                         cache: cacheDir,
                         index: getDbPath(),
                     };
@@ -152,16 +95,10 @@ export const configCommand = defineGroupCommand({
                 output("config", listConfig(loadConfig()));
             },
         }),
-        show: defineJsonCommand({
-            meta: { name: "show", description: "Alias for `akm config list` — list current configuration" },
-            run() {
-                output("config", listConfig(loadConfig()));
-            },
-        }),
         get: defineJsonCommand({
             meta: { name: "get", description: "Get a configuration value by key" },
             args: {
-                key: { type: "positional", required: true, description: "Config key (for example: embedding, stashDir)" },
+                key: { type: "positional", required: true, description: "Config key (for example: embedding, defaultBundle)" },
             },
             run({ args }) {
                 output("config", getConfigValue(loadConfig(), args.key));
@@ -184,22 +121,8 @@ export const configCommand = defineGroupCommand({
                     description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
                     default: false,
                 },
-                // #463: explicit layer flag for forward-compat. User layer is the only
-                // settable layer today; the flag exists so plugin authors can encode
-                // intent and the surface stays stable if project-layer writes return.
-                layer: {
-                    type: "string",
-                    description: "Config layer to write to. Currently only `user` is supported.",
-                    default: "user",
-                },
             },
             run({ args }) {
-                if (args.layer && args.layer !== "user") {
-                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.9.0.`, "INVALID_FLAG_VALUE");
-                }
-                // Use loadConfig (not loadUserConfig) so the project-config
-                // deprecation warning fires consistently with `akm config get`
-                // (#457). Effective merged shape is identical post-0.8.0.
                 const updated = mutateConfig((current) => setConfigValue(current, args.key, args.value)).config;
                 if (!args.silent) {
                     output("config", listConfig(updated));
@@ -215,16 +138,8 @@ export const configCommand = defineGroupCommand({
                     description: "Suppress the post-write config dump on stdout.",
                     default: false,
                 },
-                layer: {
-                    type: "string",
-                    description: "Config layer to write to. Currently only `user` is supported.",
-                    default: "user",
-                },
             },
             run({ args }) {
-                if (args.layer && args.layer !== "user") {
-                    throw new UsageError(`Unsupported --layer "${args.layer}". Only "user" is settable in 0.9.0.`, "INVALID_FLAG_VALUE");
-                }
                 const result = mutateConfig((current) => unsetConfigValue(current, args.key), { absentNoop: true });
                 const updated = result.config;
                 if (!args.silent) {
@@ -232,60 +147,12 @@ export const configCommand = defineGroupCommand({
                 }
             },
         }),
-        validate: defineJsonCommand({
-            meta: {
-                name: "validate",
-                description: "Validate the on-disk config file against the schema. Exits non-zero on errors.",
-            },
-            async run() {
-                const { runConfigValidate } = await import("../cli/config-validate.js");
-                await runConfigValidate();
-            },
-        }),
-        migrate: defineJsonCommand({
-            meta: {
-                name: "migrate",
-                description: "Compatibility alias for the canonical top-level migrate status/apply coordinator.",
-            },
-            args: {
-                config: {
-                    type: "string",
-                    description: "Path to an operator-prepared current-version config to validate and install",
-                },
-                dryRun: { type: "boolean", default: false, description: "Validate and report without changing files" },
-            },
-            async run({ args }) {
-                const { runConfigMigrate } = await import("../cli/config-migrate.js");
-                await runConfigMigrate({ preparedConfigPath: args.config, dryRun: args.dryRun });
-            },
-        }),
-        enable: defineJsonCommand({
-            meta: { name: "enable", description: "Enable an optional component (skills.sh)" },
-            args: {
-                target: { type: "positional", description: "Component to enable (skills.sh)", required: true },
-            },
-            run({ args }) {
-                const result = toggleComponent(args.target, true);
-                output("enable", result);
-            },
-        }),
-        disable: defineJsonCommand({
-            meta: { name: "disable", description: "Disable an optional component (skills.sh)" },
-            args: {
-                target: { type: "positional", description: "Component to disable (skills.sh)", required: true },
-            },
-            run({ args }) {
-                const result = toggleComponent(args.target, false);
-                output("disable", result);
-            },
-        }),
     },
     // The bare `akm config` invocation (and `akm config --list`) dumps the
     // current config. defineGroupCommand short-circuits this body when a
     // registered subcommand ran, so the routing set stays derived from the
-    // subCommands map and can never desync (previously validate/migrate were
-    // missing from a hand-maintained set, causing a spurious second dump).
-    defaultRun() {
-        output("config", listConfig(loadConfig()));
-    },
+    // subCommands map and can never desync.
+    // No `defaultRun`: bare `akm config` is a usage error (exit 2), the canonical
+    // bare-group behavior — owner ruling 12. Run `akm config list` for what the
+    // bare form used to print.
 });

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

@@ -25,16 +25,16 @@ import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.
 import { deriveCanonicalAssetName } from "../../core/asset/asset-placement.js";
 import { writeFileAtomic } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
-import { commitEnvSecretWrite, makeEnvRef, resolveEnvPath, resolveEnvWriteTarget, writeTargetDisplaySource, } from "../../core/env-secret-ref.js";
+import { makeEnvRef, resolveEnvPath, resolveEnvWriteTarget, withEnvSecretWrite } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
-import { isQuiet } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { readStdin } from "../../runtime.js";
 import { buildChildEnv } from "./child-env.js";
+import { sensitiveMarkerPath } from "./marker-path.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` →
- * `env:team/prod`, `env/team/.env` → `env:team/default`).
+ * `env/team/prod`, `env/team/.env` → `env/team/default`).
  */
 function listEnvsRecursive(listKeysFn) {
     const result = [];
@@ -57,7 +57,7 @@ function listEnvsRecursive(listKeysFn) {
                 if (!canonical)
                     continue;
                 // Skip sensitive envs: a sibling .sensitive marker file suppresses listing.
-                const markerPath = full.replace(/\.env$/, ".sensitive");
+                const markerPath = sensitiveMarkerPath(full, "env");
                 if (fs.existsSync(markerPath))
                     continue;
                 const { keys } = listKeysFn(full);
@@ -69,7 +69,7 @@ function listEnvsRecursive(listKeysFn) {
     return result;
 }
 const envListCommand = defineJsonCommand({
-    meta: { name: "list", description: "List all env files across all stashes with their key names (no values)" },
+    meta: { name: "list", description: "List all env files across all bundles with their key names (no values)" },
     async run() {
         const { listKeys } = await import("./env.js");
         output("env-list", { envs: listEnvsRecursive(listKeys) });
@@ -99,28 +99,27 @@ const envCreateCommand = defineJsonCommand({
         },
         target: {
             type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
     },
     async run({ args }) {
         const { createEnv, writeEnv } = await import("./env.js");
         // `create` always targets env/, never the frozen vaults/ copy. `--path` is
         // the subdirectory; `--target` selects the writable destination source.
-        const { name, absPath, target } = resolveEnvWriteTarget(args.name, args.target, {
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.name, args.target, {
             subPath: getStringArg(args, "path"),
         });
-        const displaySource = writeTargetDisplaySource(target);
         const fromFile = args["from-file"];
         const fromStdin = args["from-stdin"] === true;
         if (fromFile !== undefined && fromStdin) {
             throw new UsageError("Pass only one of --from-file or --from-stdin.", "INVALID_FLAG_VALUE");
         }
+        let content;
         if (fromFile !== undefined || fromStdin) {
             // Ingest path: never silently clobber an existing env file.
             if (fs.existsSync(absPath)) {
-                throw new UsageError(`Env "${makeEnvRef(name, displaySource)}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
+                throw new UsageError(`Env "${ref}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
             }
-            let content;
             if (fromFile !== undefined) {
                 if (!fs.existsSync(fromFile)) {
                     throw new NotFoundError(`Source file not found: ${fromFile}`, "FILE_NOT_FOUND");
@@ -132,21 +131,24 @@ const envCreateCommand = defineJsonCommand({
                 const buf = await readStdin(MAX_ENV_BYTES, () => new UsageError("Env file exceeds 1 MB limit.", "INVALID_FLAG_VALUE"));
                 content = buf.toString("utf8");
             }
-            writeEnv(absPath, content);
-        }
-        else {
-            createEnv(absPath);
         }
         const written = [absPath];
+        const markerPath = sensitiveMarkerPath(absPath, "env");
         if (args.sensitive) {
-            const markerPath = absPath.replace(/\.env$/, ".sensitive");
-            if (!fs.existsSync(markerPath)) {
-                fs.writeFileSync(markerPath, "", { mode: 0o600 });
-            }
             written.push(markerPath);
         }
-        commitEnvSecretWrite(target, { type: "env", name }, "Update", written);
-        output("env-create", { ref: makeEnvRef(name, displaySource) });
+        withEnvSecretWrite(target, { type: "env", name }, "Update", written, () => {
+            if (content !== undefined)
+                writeEnv(absPath, content);
+            else
+                createEnv(absPath);
+            if (args.sensitive) {
+                if (!fs.existsSync(markerPath)) {
+                    writeFileAtomic(markerPath, "", 0o600);
+                }
+            }
+        });
+        output("env-create", { ref });
     },
 });
 const envPathCommand = defineJsonCommand({
@@ -170,6 +172,22 @@ const envPathCommand = defineJsonCommand({
             process.stderr.write(`warning: this is the raw file path. Do NOT \`source\` it (shell substitutions in the file would execute).\n` +
                 `         To inject values run: akm env run ${args.ref} -- <command>\n`);
         }
+        // F3/B3: this stdout write IS the payload — a bare absolute path for
+        // shell substitution (`$(akm env path <ref>)`, Docker `_FILE` /
+        // `--env-file`) — not a field inside a result envelope. `env path` is
+        // now declared format-exempt (src/output/format-exempt.ts, same
+        // classification as `env run`/`secret run`/`help`), so `--format`
+        // WARNS rather than doing anything to this write (src/cli.ts's startup
+        // `isFormatExemptCommand` check). An earlier version of this fix routed
+        // this through `output()` with a `{ path }` envelope so `--format`
+        // "worked" — but the CLI's process-wide default format is `json`, so a
+        // bare `akm env path <ref>` (exactly how `$(akm env path foo)` is
+        // written, with no explicit `--format`) started emitting
+        // `{"path":"..."}` instead of the raw path, breaking every existing
+        // shell substitution silently. Declaring the exemption is the correct
+        // fix: it keeps this byte-identical to history and makes the
+        // already-broken combination (`--format` + this command) loud instead
+        // of silent, per STABILITY.md's promise for exempt commands.
         process.stdout.write(`${absPath}\n`);
     },
 });
@@ -225,7 +243,7 @@ async function runEnvInjected(target, opts) {
                 }
                 if (baseExists) {
                     throw new UsageError(`'akm env run' injects the whole file; the single-key '<ref>/${maybeKey}' form was removed.\n` +
-                        `       For one value use a secret: \`akm secret run secret:${maybeKey} ${maybeKey} -- <command>\`.`, "INVALID_FLAG_VALUE");
+                        `       For one value use a secret: \`akm secret run secrets/${maybeKey} ${maybeKey} -- <command>\`.`, "INVALID_FLAG_VALUE");
                 }
             }
         }
@@ -263,7 +281,15 @@ async function runEnvInjected(target, opts) {
         }
         throw err;
     }
-    process.exit(result.status ?? 0);
+    // R-067: was `process.exit(result.status ?? 0)`, which terminates the
+    // process synchronously and skips the `finally { await
+    // disposeDispatchResources(); }` block in src/cli.ts's `runCommand` — even
+    // on the success path, since this call was unconditional. Setting
+    // `process.exitCode` and returning lets cleanup run while still exiting
+    // with the child's exact status once the event loop drains, matching the
+    // pattern `emitJsonError` (src/cli/shared.ts) already established.
+    process.exitCode = result.status ?? 0;
+    return;
 }
 /** Parse a comma/space-separated key list flag into a trimmed, non-empty array. */
 function parseKeyListFlag(raw) {
@@ -280,7 +306,7 @@ const envRunCommand = defineJsonCommand({
         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. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
+        "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 bundle. 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 },
@@ -315,12 +341,11 @@ const envRemoveCommand = defineJsonCommand({
         yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
         target: {
             type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
     },
     async run({ args }) {
-        const { name, absPath, target } = resolveEnvWriteTarget(args.ref, args.target);
-        const displaySource = writeTargetDisplaySource(target);
+        const { name, absPath, target, ref } = resolveEnvWriteTarget(args.ref, args.target);
         const { confirmDestructive } = await import("../../cli/confirm.js");
         const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
             yes: args.yes === true,
@@ -330,124 +355,18 @@ const envRemoveCommand = defineJsonCommand({
             return;
         }
         if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Env not found: ${makeEnvRef(name, displaySource)}`);
+            throw new NotFoundError(`Env not found: ${ref}`);
         }
         const { removeEnv } = await import("./env.js");
-        const removed = removeEnv(absPath);
-        commitEnvSecretWrite(target, { type: "env", name }, "Remove", [absPath, `${absPath}.sensitive`]);
-        output("env-remove", { ref: makeEnvRef(name, displaySource), removed });
-    },
-});
-const envSetCommand = defineJsonCommand({
-    meta: {
-        name: "set",
-        description: "Set (create or update) a single KEY in an env file: `akm env set <ref> <KEY>`. The value is read from stdin by default (never via argv); use --from-env <VAR> or --from-file <path>. Preserves existing comments and key order; the value is never printed. Creates the env file if it does not exist.",
-    },
-    args: {
-        ref: { type: "positional", description: "Env ref (e.g. env:prod or just prod)", required: true },
-        key: { type: "positional", description: "Key name to set (e.g. API_URL)", required: true },
-        "from-env": { type: "string", description: "Read the value from the named environment variable" },
-        "from-file": { type: "string", description: "Read the value from this file" },
-        target: {
-            type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
-        },
-    },
-    async run({ args }) {
-        const { name, absPath, target } = resolveEnvWriteTarget(args.ref, args.target);
-        const displaySource = writeTargetDisplaySource(target);
-        const key = String(args.key);
-        const { ENV_KEY_RE, setEnvKey } = await import("./env.js");
-        if (!ENV_KEY_RE.test(key)) {
-            throw new UsageError(`Invalid env key "${key}". Keys match [A-Za-z_][A-Za-z0-9_]*.`, "INVALID_FLAG_VALUE");
-        }
-        const fromEnv = args["from-env"];
-        const fromFile = args["from-file"];
-        if (fromEnv !== undefined && fromFile !== undefined) {
-            throw new UsageError("Pass only one of --from-file or --from-env (or use stdin).", "INVALID_FLAG_VALUE");
-        }
-        const MAX_ENV_VALUE_BYTES = 1024 * 1024; // 1 MB
-        let value;
-        if (fromFile !== undefined) {
-            if (!fs.existsSync(fromFile)) {
-                throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
-            }
-            const buf = fs.readFileSync(fromFile);
-            if (buf.byteLength > MAX_ENV_VALUE_BYTES)
-                throw new UsageError("Value exceeds the 1 MB limit.");
-            value = buf.toString("utf8");
-        }
-        else if (fromEnv !== undefined) {
-            const v = process.env[fromEnv];
-            if (v === undefined) {
-                throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
-            }
-            value = v;
-        }
-        else {
-            const buf = await readStdin(MAX_ENV_VALUE_BYTES, () => new UsageError("Value exceeds the 1 MB limit."));
-            // Strip a single trailing newline so `echo "$VAL" | akm env set` is exact.
-            value = buf.toString("utf8").replace(/\n$/, "");
-        }
-        setEnvKey(absPath, key, value);
-        commitEnvSecretWrite(target, { type: "env", name }, "Update", [absPath]);
-        // Warn (never block) on process-hijacking key names, matching the env-run audit.
-        const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-        if (isDangerousEnvKey(key) && !isQuiet()) {
-            process.stderr.write(`warning: "${key}" can influence process execution when this env is loaded via 'akm env run'.\n`);
-        }
-        output("env-set", { ref: makeEnvRef(name, displaySource), key });
-    },
-});
-const envUnsetCommand = defineJsonCommand({
-    meta: {
-        name: "unset",
-        description: "Remove one or more KEYs from an env file: `akm env unset <ref> <KEY...>`. Preserves other keys and comments. To remove the whole file, use `akm env remove`.",
-    },
-    args: {
-        ref: { type: "positional", description: "Env ref (e.g. env:prod or just prod)", required: true },
-        // `key` is read from the raw positionals (one or more) in run(); declared
-        // non-required so citty doesn't block before we emit a structured error.
-        key: { type: "positional", description: "Key name(s) to remove (one or more)", required: false },
-        target: {
-            type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
-        },
-    },
-    async run({ args }) {
-        const { name, absPath, target } = resolveEnvWriteTarget(args.ref, args.target);
-        const displaySource = writeTargetDisplaySource(target);
-        if (!fs.existsSync(absPath)) {
-            throw new NotFoundError(`Env not found: ${makeEnvRef(name, displaySource)}`);
-        }
-        // citty puts every positional in `args._` (incl. the ref at [0]); the keys
-        // are the remaining positionals. citty also mis-captures the space-separated
-        // value of a global flag (`--format json`) as a positional, so drop any
-        // token that is actually a global flag's value (cli.ts:1335 documents this).
-        const invocation = getParsedInvocation();
-        const globalFlagValues = new Set(["--format", "--shape", "--detail", "--scope", "--filter", "--target"]
-            .map((flag) => invocation.getFlagValue(flag))
-            .filter((v) => typeof v === "string"));
-        const keys = (Array.isArray(args._) ? args._.map(String) : [])
-            .slice(1)
-            .filter((k) => !globalFlagValues.has(k));
-        if (keys.length === 0) {
-            throw new UsageError("Usage: akm env unset <ref> <KEY...> (one or more keys).", "MISSING_REQUIRED_ARGUMENT");
-        }
-        const { ENV_KEY_RE, unsetEnvKeys } = await import("./env.js");
-        const invalid = keys.filter((k) => !ENV_KEY_RE.test(k));
-        if (invalid.length > 0) {
-            throw new UsageError(`Invalid env key(s): ${invalid.join(", ")}.`, "INVALID_FLAG_VALUE");
-        }
-        const { removed, missing } = unsetEnvKeys(absPath, keys);
-        commitEnvSecretWrite(target, { type: "env", name }, "Update", [absPath]);
-        output("env-unset", { ref: makeEnvRef(name, displaySource), removed, missing });
+        const removed = withEnvSecretWrite(target, { type: "env", name }, "Remove", [absPath, sensitiveMarkerPath(absPath, "env")], () => removeEnv(absPath));
+        output("env-remove", { ref, removed });
     },
 });
 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`.",
+        description: "Manage `.env` files — configuration values an app loads together (URLs, flags, and any credentials it needs).\n\n" +
+            "Values may or may not be sensitive; akm protects them all the same way — key names are visible, values never appear in structured output. For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
     subCommands: {
         list: envListCommand,
@@ -455,12 +374,9 @@ export const envCommand = defineGroupCommand({
         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) });
-    },
+    // No `defaultRun`: bare `akm env` is a usage error (exit 2), the canonical
+    // bare-group behavior — owner ruling 12. Run `akm env list` for what the
+    // bare form used to print.
 });