akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/cli.js

@@ -2,28 +2,26 @@
 // 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/.
-// Runtime guard: akm-cli 0.9 runs on Bun (primary) and Node.js >= 20 (#465,
-// #560). The runtime boundary (src/runtime.ts, src/storage/database.ts) makes
-// the Node path additive. Under Node the CLI must be launched via the
+// Runtime guard: the akm-cli npm package bootstraps with Node.js >= 22
+// (#465, #560), then its launcher prefers a working Bun >= 1.0 when available.
+// The runtime boundary (src/runtime.ts, src/storage/database.ts) supports both.
+// Under Node the CLI must be launched via the
 // `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.12: `@clack/core` (prompts) imports
+// the supported entry. The hard floor is Node 22 (Node 20 support dropped 2026-07; `@clack/core` 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 = 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)));
+        const [major = 0] = (process.versions.node ?? "0").split(".").map((part) => Number.parseInt(part, 10) || 0);
+        const nodeOk = major >= 22;
         if (!nodeOk) {
-            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.12.\n" +
+            console.error("\n  ERROR: the akm-cli npm package requires Node.js >= 22.\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.12 or newer (https://nodejs.org)\n" +
-                "    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
+                "  Bun >= 1.0 is optional for execution; it does not replace the Node.js bootstrap.\n" +
+                "  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\n" +
+                "    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
             process.exit(1);
         }
     }
@@ -44,7 +42,7 @@ process.on("unhandledRejection", (reason) => {
     }, null, 2));
     if (process.env.AKM_DEBUG === "1" && err.stack)
         console.error(err.stack);
-    process.exit(1);
+    process.exit(EXIT_CODES.INTERNAL);
 });
 process.on("uncaughtException", (err) => {
     console.error(JSON.stringify({
@@ -55,92 +53,61 @@ process.on("uncaughtException", (err) => {
     }, null, 2));
     if (process.env.AKM_DEBUG === "1" && err.stack)
         console.error(err.stack);
-    process.exit(1);
+    process.exit(EXIT_CODES.INTERNAL);
 });
 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 { defineCommand, parseArgs, renderUsage, runCommand, showUsage } from "citty";
+import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
+import { retiredCommandHint } from "./cli/retired-commands.js";
+import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "./cli/shared.js";
+import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
 import { configCommand } from "./commands/config-cli.js";
 import { envCommand } from "./commands/env/env-cli.js";
 import { secretCommand } from "./commands/env/secret-cli.js";
 import { feedbackCommand } from "./commands/feedback-cli.js";
-import { graphCommand } from "./commands/graph/graph-cli.js";
 import { akmHealth } from "./commands/health.js";
-import { renderRunsDetailMd, renderWindowCompareMd } from "./commands/health/md-report.js";
+import "./commands/health/renderers.js";
 import { parseWindowSpec } from "./commands/health/windows.js";
-import { extractCommand } from "./commands/improve/extract-cli.js";
 import { improveCommand } from "./commands/improve/improve-cli.js";
-import { hintsCommand, lessonsCommand, logCommand } from "./commands/observability-cli.js";
+import { migrateCommand } from "./commands/migrate-cli.js";
+import { logCommand } from "./commands/observability-cli.js";
 import { proposalCommand } from "./commands/proposal/proposal-cli.js";
 import { rememberCommand } from "./commands/read/remember-cli.js";
 import { curateCommand, searchCommand, showCommand } from "./commands/read/search-cli.js";
-import { normalizeShowArgv } from "./commands/read/show.js";
 import { registryCommand } from "./commands/registry-cli.js";
-import { addCommand } from "./commands/sources/add-cli.js";
+import { bundleCommand } from "./commands/sources/bundle-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 { 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 { cloneCommand, syncCommand, upgradeCommand } from "./commands/sources/sources-cli.js";
+import { importKnowledgeCommand, indexCommand, infoCommand } from "./commands/sources/stash-cli.js";
+import { taskCommand } from "./commands/tasks/tasks-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
-import { bestEffort } from "./core/best-effort.js";
-import { loadConfig } from "./core/config/config.js";
+import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
 import { UsageError } from "./core/errors.js";
-import { getCacheDir, getConfigPath, getDbPath } from "./core/paths.js";
+import { assertNoPendingMigrationOperation } from "./core/migration-operation.js";
+import { getConfigPath } from "./core/paths.js";
+import { DURATION_UNITS, parseDuration } from "./core/time.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
-import { getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue } from "./output/context.js";
-import { deliverRendered, renderHtml, resolveTemplatePath } from "./output/html-render.js";
+import { disposeDispatchResources } from "./integrations/agent/runner-dispatch.js";
+import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints.js";
+import { getOutputMode, initOutputMode, parseDetailLevel } from "./output/context.js";
+import { isFormatExemptCommand } from "./output/format-exempt.js";
+import { consumeSchedulerContextArg } from "./tasks/scheduler-invocation.js";
 import { pkgVersion } from "./version.js";
 function applyEarlyStderrFlags(argv) {
-    if (argv.includes("--quiet") || argv.includes("-q")) {
+    const separator = argv.indexOf("--");
+    const ownArgv = separator === -1 ? argv : argv.slice(0, separator);
+    if (ownArgv.includes("--quiet") || ownArgv.includes("-q")) {
         setQuiet(true);
     }
-    if (argv.includes("--verbose")) {
+    if (ownArgv.includes("--verbose")) {
         setVerbose(true);
     }
 }
-function resolveHelpMigrateVersionArg(version) {
-    if (version === undefined)
-        return undefined;
-    const parsedFormat = parseFlagValue(process.argv, "--format");
-    if (parsedFormat !== undefined &&
-        version === parsedFormat &&
-        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedFormat, "--format")) {
-        return undefined;
-    }
-    const parsedDetail = parseFlagValue(process.argv, "--detail");
-    if (parsedDetail !== undefined &&
-        version === parsedDetail &&
-        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedDetail, "--detail")) {
-        return undefined;
-    }
-    return version;
-}
-function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName) {
-    const argv = process.argv.slice(2);
-    const helpIndex = argv.indexOf("help");
-    const tokens = helpIndex >= 0 ? argv.slice(helpIndex + 1) : argv;
-    const migrateIndex = tokens.indexOf("migrate");
-    const relevant = migrateIndex >= 0 ? tokens.slice(migrateIndex + 1) : tokens;
-    let flagIndex = -1;
-    for (let i = 0; i < relevant.length; i += 1) {
-        const token = relevant[i];
-        if (token === flagName || token === `${flagName}=${flagValue}`) {
-            flagIndex = i;
-            break;
-        }
-    }
-    if (flagIndex === -1)
-        return false;
-    if (relevant.slice(0, flagIndex).includes(version))
-        return false;
-    return relevant[flagIndex] === flagName ? relevant[flagIndex + 1] === version : true;
-}
+// resolveHelpMigrateVersionArg moved to ./cli/invocation (chunk-9 WI-9.9
+// argv-normalization fold — it re-scanned process.argv, same as
+// findCittyTopLevelCommand and parseAllFlagValues below).
 /**
  * Stderr-only human-friendly hint after a non-interactive `setup` invocation.
  * Default --format is `json`, so a CI or piped consumer sees only the JSON on
@@ -160,10 +127,10 @@ function printSetupTtyHint(result) {
         return;
     if (isQuiet())
         return;
-    if (!result?.stashDir)
+    if (!result?.bundleDir)
         return;
-    console.error(plainize(`\n✓ Stash created at ${result.stashDir}\n` +
-        `  Next: \`akm add github:itlackey/akm-stash\` then \`akm index\` to populate the stash.`));
+    console.error(plainize(`\n✓ Bundle created at ${result.bundleDir}\n` +
+        '  Next: `akm bundle add <source>`, `akm index`, `akm search "<query>"`, `akm help agents`'));
 }
 /**
  * Module Naming:
@@ -178,9 +145,14 @@ const setupCommand = defineCommand({
         description: "Interactive configuration wizard. Configures embeddings/LLM connections (for indexing/enrichment), agent profiles (CLI agent, embedded SDK, or none), sources, and registries. Shows which features are enabled at the end. Use --config <json> or --yes for non-interactive/scripting mode.",
     },
     args: {
+        // R-051/S11: `setup` is a raw `defineCommand` (not `defineJsonCommand`),
+        // so it does not get `GLOBAL_OUTPUT_ARGS` for free — same gap `health`
+        // already had. Three of its four run branches call `output()`; spreading
+        // this in is a `--help` visibility fix, not a behavior change.
+        ...GLOBAL_OUTPUT_ARGS,
         config: {
             type: "string",
-            description: 'Config JSON to apply non-interactively, e.g. \'{"llm":{"endpoint":"...","model":"..."}}\'',
+            description: 'Config JSON to apply non-interactively, e.g. \'{"engines":{"local":{"kind":"llm","endpoint":"...","model":"..."}},"defaults":{"llmEngine":"local"}}\'',
         },
         from: {
             type: "string",
@@ -193,43 +165,29 @@ const setupCommand = defineCommand({
         },
         dir: {
             type: "string",
-            description: "Stash directory path (overrides stashDir in config or --config JSON)",
+            description: "Bundle directory path (overrides defaultBundle in config or --config JSON)",
         },
-        probe: {
+        // Declared as the POSITIVE name with `default: true` so citty's native
+        // `--no-<name>` negation (it strips a leading `--no-` from ANY token and
+        // negates the remainder BEFORE consulting the declared-args table) does
+        // the work, matching the `sync --push/--no-push` pattern. A flag
+        // DECLARED as `no-init` can never be negated: `--no-init` parses as
+        // "negate `init`", a name nothing declared, leaving the real key at its
+        // default forever — see `search --no-project-context`'s identical fix.
+        init: {
             type: "boolean",
-            default: false,
-            description: "Probe LLM/embedding endpoints after writing config to verify connectivity",
+            default: true,
+            description: "Scaffold the bundle directory. Use --no-init to write configuration without scaffolding it.",
         },
-        "detect-only": {
-            type: "boolean",
-            default: false,
-            description: "Run environment detection only and print the result (no prompts, no writes). Pair with --format json.",
-        },
-        "reset-recommended": {
+        probe: {
             type: "boolean",
             default: false,
-            description: "Merge opinionated, detection-derived defaults into the existing config without removing custom keys.",
+            description: "Probe LLM/embedding endpoints before writing config to verify connectivity",
         },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const noInit = getHyphenatedBoolean(args, "no-init");
-            const detectOnly = args["detect-only"];
-            const resetRecommended = args["reset-recommended"];
-            if (detectOnly) {
-                // Detection only: no prompts, no writes.
-                const { runDetectOnly } = await import("./setup/setup.js");
-                const detection = await runDetectOnly();
-                output("setup", detection);
-                return;
-            }
-            if (resetRecommended) {
-                const { runResetRecommended } = await import("./setup/setup.js");
-                const result = await runResetRecommended({ dir: args.dir, noInit, probe: args.probe });
-                output("setup", result);
-                printSetupTtyHint(result);
-                return;
-            }
+            const noInit = !args.init;
             if (args.from && args.config) {
                 throw new UsageError("Pass either --from <file> or --config <json>, not both.", "INVALID_FLAG_VALUE");
             }
@@ -286,8 +244,17 @@ const setupCommand = defineCommand({
     },
 });
 const healthCommand = defineCommand({
-    meta: { name: "health", description: "Check akm runtime health, artifacts, and improve metrics" },
+    meta: {
+        name: "health",
+        description: "Check akm runtime health, artifacts, and improve metrics",
+    },
     args: {
+        // R-051: `health` is a raw `defineCommand` (not `defineJsonCommand`), so
+        // it does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
+        // `--shape`/`--output` already parsed correctly here (this command has
+        // no positional for a stray value to fall into), so this is purely a
+        // `--help` visibility / consistency fix, not a behavior change.
+        ...GLOBAL_OUTPUT_ARGS,
         since: {
             type: "string",
             description: "Rolling window start (ISO timestamp, date, epoch ms, or shorthand like 24h / 7d)",
@@ -304,95 +271,228 @@ const healthCommand = defineCommand({
             type: "string",
             description: "Explicit comparison window 'name=...,since=ISO,until=ISO' (repeatable, up to 4; mutually exclusive with --window-compare)",
         },
-        compare: {
-            type: "string",
-            description: "Comparison window for the --format html report's trend deltas (default: 24h)",
+        report: {
+            type: "boolean",
+            description: "Fetch the full report dataset: per-run rows, trend deltas vs the prior window, and the pending proposal queue. Renders as the rich report under --format md/html and as complete data under any other format.",
+            default: false,
         },
     },
     async run({ args }) {
         let resultStatus;
+        const exitCodeBeforeRun = process.exitCode;
         await runWithJsonErrors(async () => {
             // citty only surfaces the last value of a repeated flag, so read --windows
             // directly from argv to support multi-window comparison.
             const rawWindows = parseAllFlagValues("--windows");
             const windows = rawWindows.length > 0 ? rawWindows.map((raw) => parseWindowSpec(raw)) : undefined;
             const groupBy = args["group-by"];
-            const windowCompareRaw = args["window-compare"];
-            const mode = getOutputMode();
-            // `--format html` is health-specific: render the full HTML health
-            // report (charts, KPI cards, advisories) from the bespoke template.
-            // Mirrors the `md` intercept below. Two reads, exactly like the
-            // retired akm-health-report skill: the canonical per-run window plus a
-            // window-compare read for the trend deltas (defaults to 24h,
-            // overridable via --compare).
-            if (mode.format === "html") {
-                // 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 = result.deltas;
-                const { buildHealthHtmlReplacements } = await import("./commands/health/html-report.js");
-                const { listPendingProposals } = await import("./commands/proposal/proposal.js");
-                const replacements = buildHealthHtmlReplacements(result, {
-                    window: args.since ?? "24h",
-                    compare,
-                    proposals: listPendingProposals(),
-                    deltas,
-                });
-                deliverRendered(renderHtml(resolveTemplatePath("health"), replacements), mode.outputPath);
-                return;
-            }
-            const result = akmHealth({
+            const report = args.report === true;
+            // `--report` is a DATA flag: it selects the richer read (per-run rows +
+            // window-compare deltas + the proposal queue) and nothing about the read
+            // depends on --format. The registered md/html renderers are pure
+            // functions of the result — a report-shaped result renders as the rich
+            // report, any other shape falls through to the generic rendering.
+            //
+            // The compare window defaults to the report's own `--since` window so the
+            // 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.
+            // Comparison-window precedence. An explicit `--window-compare` always
+            // wins. Otherwise `--report` seeds a like-for-like comparison from
+            // `--since`, but only when `--since` is a DURATION: `resolveWindowCompare`
+            // parses durations only, so feeding it an absolute date, ISO timestamp, or
+            // epoch value throws. And explicit `--windows` gets no implicit value at
+            // all — the two are mutually exclusive, so synthesizing one turned a valid
+            // invocation into a usage error.
+            const explicitWindows = windows !== undefined && windows.length > 0;
+            const sinceIsDuration = args.since !== undefined && parseDuration(args.since, DURATION_UNITS) !== null;
+            const implicitCompare = explicitWindows ? undefined : ((sinceIsDuration ? args.since : undefined) ?? "24h");
+            const windowCompare = report ? (args["window-compare"] ?? implicitCompare) : args["window-compare"];
+            const base = akmHealth({
                 since: args.since,
-                groupBy: groupBy,
-                windowCompare: windowCompareRaw,
+                groupBy: report ? "run" : groupBy,
+                windowCompare,
                 windows,
             });
-            resultStatus = result.status;
-            // `--format md` is health-specific: render a TSV-shaped per-run or
-            // window-compare table to stdout instead of going through the JSON
-            // envelope. Other modes fall through to the standard output() path.
-            if (mode.format === "md") {
-                if (result.windows && result.windows.length > 0) {
-                    deliverRendered(renderWindowCompareMd(result.windows, result.deltas), mode.outputPath);
-                }
-                else if (result.runs) {
-                    deliverRendered(renderRunsDetailMd(result.runs), mode.outputPath);
-                }
-                else {
-                    output("health", result);
-                }
-            }
-            else {
-                output("health", result);
+            const reportCompare = windowCompare ??
+                (explicitWindows
+                    ? [...(base.windows ?? [])]
+                        .sort((a, b) => new Date(a.since).getTime() - new Date(b.since).getTime())
+                        .map((window) => window.name)
+                        .join(" → ")
+                    : undefined) ??
+                "24h";
+            resultStatus = base.status;
+            if (report) {
+                const { listPendingProposals } = await import("./commands/proposal/proposal.js");
+                const { computeAcceptRateBySource } = await import("./commands/health/accept-rate.js");
+                output("health", {
+                    ...base,
+                    report: {
+                        window: args.since ?? "24h",
+                        compare: reportCompare,
+                        comparisonMode: explicitWindows ? "custom" : "duration",
+                        pendingProposals: listPendingProposals().map(({ ref, source, createdAt }) => ({ ref, source, createdAt })),
+                        acceptRateBySource: computeAcceptRateBySource(),
+                    },
+                });
+                return;
             }
+            output("health", base);
         });
+        // R-067: `emitJsonError` (src/cli/shared.ts) no longer force-exits on the
+        // error path — it sets `process.exitCode` and returns, so a `--report`
+        // failure thrown AFTER `resultStatus` was already assigned (e.g. the
+        // proposal-queue read above) would otherwise leave `resultStatus`
+        // populated here too. Skip the status-derived exit entirely once
+        // `runWithJsonErrors` has already recorded a classified failure, so it is
+        // never clobbered by a mismatched health status.
+        if (process.exitCode !== exitCodeBeforeRun)
+            return;
         if (resultStatus === "fail") {
-            process.exit(EXIT_GENERAL);
+            process.exitCode = EXIT_GENERAL;
         }
         if (resultStatus === "warn") {
-            process.exit(EXIT_HEALTH_WARN);
+            process.exitCode = EXIT_HEALTH_WARN;
         }
     },
 });
-const helpCommand = defineCommand({
+function loadAgentHints(full) {
+    return full ? EMBEDDED_HINTS_FULL : EMBEDDED_HINTS;
+}
+const hintsCommand = defineCommand({
+    meta: {
+        name: "hints",
+        description: "Print agent instructions on how to use akm — the complete guide by default; pass --detail brief for the short one",
+    },
+    args: {
+        detail: {
+            type: "string",
+            description: "Hints detail level (brief|normal|full). `brief` prints the short guide; `normal`/`full` print the complete guide.",
+            default: "normal",
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(() => {
+            const detail = parseDetailLevel(args.detail) ?? "normal";
+            process.stdout.write(loadAgentHints(detail !== "brief"));
+        });
+    },
+});
+const completionsCommand = defineCommand({
+    meta: {
+        name: "completions",
+        description: "Generate or install shell completion script",
+    },
+    args: {
+        install: {
+            type: "boolean",
+            description: "Install completions to the appropriate directory",
+            default: false,
+        },
+        shell: {
+            type: "string",
+            description: "Shell type (bash)",
+            default: "bash",
+        },
+    },
+    run({ args }) {
+        // R-052(b): this was a bare `run()` throwing directly, so an unsupported
+        // `--shell` value escaped straight to citty's top-level error handling
+        // instead of the standard JSON envelope — exit 1 with a raw stack trace
+        // instead of the classified exit-2 usage error every other command
+        // produces (`completions` is format-exempt, so it stays a raw
+        // `defineCommand` rather than `defineJsonCommand`, but still needs the
+        // same error-classification wrapper other bare `defineCommand`s in this
+        // file use, e.g. `help migrate` below).
+        return runWithJsonErrors(() => {
+            if (args.shell !== "bash") {
+                throw new UsageError(`Unsupported shell: ${args.shell}. Only bash is supported.`);
+            }
+            const script = generateBashCompletions(main);
+            if (args.install) {
+                const dest = installBashCompletions(script);
+                info(`Completions installed to ${dest}`);
+                info(`Restart your shell or run:  source ${dest}`);
+            }
+            else {
+                process.stdout.write(script);
+            }
+        });
+    },
+});
+const commands = {
+    setup: setupCommand,
+    index: indexCommand,
+    health: healthCommand,
+    info: infoCommand,
+    bundle: bundleCommand,
+    upgrade: upgradeCommand,
+    search: searchCommand,
+    curate: curateCommand,
+    show: showCommand,
+    workflow: workflowCommand,
+    remember: rememberCommand,
+    import: importKnowledgeCommand,
+    sync: syncCommand,
+    clone: cloneCommand,
+    registry: registryCommand,
+    migrate: migrateCommand,
+    config: configCommand,
+    feedback: feedbackCommand,
+    log: logCommand,
+    agent: agentCommand,
+    lint: lintCommand,
+    improve: improveCommand,
+    proposal: proposalCommand,
+    completions: completionsCommand,
+    env: envCommand,
+    secret: secretCommand,
+    task: taskCommand,
+    hints: hintsCommand,
+};
+function commandHelpTopic(name, command) {
+    return defineCommand({
+        meta: { name, description: `Print help for akm ${name}` },
+        async run() {
+            await showUsage(command, buildUsageParentForPath([name]));
+        },
+    });
+}
+const commandHelpTopics = Object.fromEntries(Object.entries(commands)
+    .filter(([name]) => name !== "migrate")
+    .map(([name, command]) => [name, commandHelpTopic(name, command)]));
+const helpCommand = defineGroupCommand({
     meta: {
         name: "help",
-        description: "Print focused help topics such as migration guidance for a release",
+        description: "Print the command overview, detailed help for a command, agent instructions, or a release's migration guidance",
     },
     subCommands: {
+        ...commandHelpTopics,
+        agents: defineCommand({
+            meta: {
+                name: "agents",
+                description: "Print agent instructions on how to use akm — the short guide by default; pass --full for the complete guide",
+            },
+            args: {
+                full: {
+                    type: "boolean",
+                    default: false,
+                    description: "Print the complete guide instead of the short one.",
+                },
+            },
+            run({ args }) {
+                return runWithJsonErrors(() => {
+                    process.stdout.write(loadAgentHints(args.full === true));
+                });
+            },
+        }),
         migrate: defineCommand({
             meta: {
                 name: "migrate",
                 description: "Print release notes and migration guidance for a version. Bundled notes live in docs/migration/release-notes/<version>.md; an unknown version lists what's available.",
             },
             args: {
-                // Optional in citty so run() is invoked even when omitted; we
-                // re-validate below to surface a structured UsageError (exit 2)
-                // instead of citty's default help-banner exit-0.
                 version: {
                     type: "positional",
                     description: "Version to review (for example 0.6.0, v0.6.0, 0.6.0-rc1, or latest)",
@@ -410,123 +510,76 @@ const helpCommand = defineCommand({
             },
         }),
     },
-});
-const completionsCommand = defineCommand({
-    meta: {
-        name: "completions",
-        description: "Generate or install shell completion script",
-    },
-    args: {
-        install: {
-            type: "boolean",
-            description: "Install completions to the appropriate directory",
-            default: false,
-        },
-        shell: {
-            type: "string",
-            description: "Shell type (bash)",
-            default: "bash",
-        },
-    },
-    run({ args }) {
-        if (args.shell !== "bash") {
-            throw new UsageError(`Unsupported shell: ${args.shell}. Only bash is supported.`);
-        }
-        const script = generateBashCompletions(main);
-        if (args.install) {
-            const dest = installBashCompletions(script);
-            info(`Completions installed to ${dest}`);
-            info(`Restart your shell or run:  source ${dest}`);
-        }
-        else {
-            process.stdout.write(script);
-        }
+    async defaultRun() {
+        process.stdout.write(`${await renderSectionedRootHelp()}\n`);
     },
 });
 export const main = defineCommand({
     meta: {
         name: "akm",
         version: pkgVersion,
-        description: "Agent Knowledge Management — search, show, and manage assets from your stash.\n\n" +
+        description: "Agent Knowledge Manager — search, show, and manage assets from your bundle.\n\n" +
             "Exit codes:\n" +
             "  0   success\n" +
-            "  1   general error / not found\n" +
+            "  1   not found / command-reported failure\n" +
             "  2   usage error\n" +
             "  4   health warn (akm health only)\n" +
+            "  70  internal / unclassified error\n" +
             "  78  config error",
     },
     args: {
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml|md|html)", default: "json" },
-        output: {
-            type: "string",
-            description: "Write rendered output to a file instead of stdout (all formats except jsonl)",
-        },
-        detail: {
-            type: "string",
-            description: "Detail level (verbosity): brief|normal|full. Default: brief.",
-            default: "brief",
-        },
-        shape: {
-            type: "string",
-            description: "Output projection: human|agent|summary. 'agent' trims to agent-essential fields; " +
-                "'summary' is only valid on 'akm show'. Default: human.",
-        },
-        quiet: {
-            type: "boolean",
-            alias: "q",
-            description: "Suppress non-essential stderr output (banners, spinners, progress info). " +
-                "Safety-critical output is never suppressed: errors, destructive-action confirmation prompts, " +
-                "and auto-migration banners always appear regardless of --quiet.",
-            default: false,
-        },
-        verbose: {
-            type: "boolean",
-            description: "Print per-spec diagnostics to stderr (also honours AKM_VERBOSE env var)",
-            default: false,
-        },
+        // Single-sourced from GLOBAL_OUTPUT_ARGS (src/cli/shared.ts) so root help
+        // and leaf help state identical text. format/detail get their `default`
+        // added here only — the description text itself is never redeclared.
+        ...GLOBAL_OUTPUT_ARGS,
+        format: { ...GLOBAL_OUTPUT_ARGS.format, default: "json" },
+        detail: { ...GLOBAL_OUTPUT_ARGS.detail, default: "brief" },
     },
     subCommands: {
-        setup: setupCommand,
-        init: initCommand,
-        index: indexCommand,
-        health: healthCommand,
-        info: infoCommand,
-        graph: graphCommand,
-        add: addCommand,
-        list: listCommand,
-        remove: removeCommand,
-        update: updateCommand,
-        upgrade: upgradeCommand,
-        search: searchCommand,
-        curate: curateCommand,
-        show: showCommand,
-        workflow: workflowCommand,
-        remember: rememberCommand,
-        import: importKnowledgeCommand,
-        sync: syncCommand,
-        clone: cloneCommand,
-        registry: registryCommand,
-        config: configCommand,
-        feedback: feedbackCommand,
-        history: historyCommand,
-        log: logCommand,
-        lessons: lessonsCommand,
-        agent: agentCommand,
-        lint: lintCommand,
-        improve: improveCommand,
-        extract: extractCommand,
-        propose: proposeCommand,
-        proposal: proposalCommand,
+        ...commands,
         help: helpCommand,
-        hints: hintsCommand,
-        completions: completionsCommand,
-        env: envCommand,
-        secret: secretCommand,
-        wiki: wikiCommand,
-        tasks: tasksCommand,
     },
 });
 const MAIN_TOP_LEVEL_ARGS = main.args;
+function isTaskRunWithId(argv) {
+    const args = argv.slice(2);
+    const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
+    const command = commandIndex >= 0 ? args[commandIndex] : undefined;
+    if (command !== "task")
+        return false;
+    const taskArgs = args.slice(commandIndex + 1);
+    if (taskArgs[0] !== "run")
+        return false;
+    const runCommand = taskCommand.subCommands?.run;
+    if (!runCommand?.args)
+        return false;
+    try {
+        const parsed = parseArgs(taskArgs.slice(1), runCommand.args);
+        return typeof parsed.id === "string" && parsed.id.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Recovery/setup surfaces must remain reachable when config.json is invalid. */
+export function shouldBypassConfigStartup(argv) {
+    const userArgs = argv.slice(2);
+    const separator = userArgs.indexOf("--");
+    const args = separator === -1 ? userArgs : userArgs.slice(0, separator);
+    if (args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v"))
+        return true;
+    const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
+    const command = commandIndex >= 0 ? args[commandIndex] : undefined;
+    if (command === "setup" || command === "migrate")
+        return true;
+    if (isTaskRunWithId(argv))
+        return true;
+    if (command !== "config")
+        return false;
+    const configIndex = args.indexOf("config");
+    const subcommand = args.slice(configIndex + 1).find((arg) => !arg.startsWith("-"));
+    return subcommand === "path";
+}
 // ── 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"
@@ -534,21 +587,339 @@ const MAIN_TOP_LEVEL_ARGS = main.args;
 // GENERAL (1) and USAGE (2). CI monitors can map: 0=pass, 4=warn, 1=fail.
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
 const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
-// Only run the CLI when this module is the direct entry point. When it is
-// imported (e.g. by the in-process test harness in tests/_helpers/cli.ts),
-// `import.meta.main` is false and we skip all startup side effects (argv
-// mutation, output-mode init, index cleanup, banner, runMain) so importers
-// can drive the `main` command themselves without the process exiting.
+// ── Top-level driver (replaces citty's `runMain`) ───────────────────────────
 //
-// Node path: this module carries a `#!/usr/bin/env bun` shebang and is launched
-// under Node via the `dist/cli-node.mjs` wrapper, which `import()`s this file
-// (so `import.meta.main` is false here even though the CLI is the real entry).
-// 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") {
-    // 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);
+// R-032: citty's own `runMain` catches EVERY error escaping `runCommand` —
+// including its unexported `CLIError`, thrown for "Unknown command …", "No
+// command specified.", "Missing required argument/positional …", and invalid
+// enum values — and unconditionally calls `process.exit(1)`, regardless of
+// error kind (node_modules/citty/dist/index.mjs). That collapsed usage
+// mistakes (`akm totally-bogus`, `akm wiki list`, bare `akm log`) onto exit
+// code 1 instead of the documented usage-error code 2 (STABILITY.md's
+// exit-code table), and there is no way to override it from outside
+// `runMain`'s own call frame: once it calls `process.exit`, nothing run
+// afterward — including a `finally` further up the stack — gets a chance to
+// execute. So the CLI drives citty's exported `runCommand` directly instead
+// of `runMain`, replicating `runMain`'s `--help` / `--version`
+// short-circuits and its CLIError → usage-banner rendering, but classifying
+// a CLIError as USAGE (2) instead of GENERAL (1). Every other error escaping
+// this boundary keeps the previous GENERAL (1) mapping — this only
+// reclassifies the one error family citty itself throws before any of our
+// own command bodies (and their `runWithJsonErrors` / `emitJsonError`
+// classification) ever run.
+const HELP_FLAGS = ["--help", "-h"];
+const VERSION_FLAGS = ["--version", "-v"];
+/**
+ * Duck-types citty's internal, unexported `CLIError`
+ * (node_modules/citty/dist/index.mjs) — the class `runCommand` throws for
+ * "Unknown command …", "No command specified.", "Missing required
+ * argument/positional …", and invalid enum values. citty does not export
+ * this class, so `instanceof` isn't available; `name` is set in its
+ * constructor (`this.name = "CLIError"`) and is stable across the pinned
+ * `citty@^0.2.2` dependency.
+ */
+function isCittyCliError(error) {
+    return error instanceof Error && error.name === "CLIError";
+}
+function findCittySubCommandByName(subCommands, name) {
+    if (name in subCommands)
+        return subCommands[name];
+    for (const sub of Object.values(subCommands)) {
+        const alias = sub.meta?.alias;
+        const aliases = Array.isArray(alias) ? alias : alias ? [alias] : [];
+        if (aliases.includes(name))
+            return sub;
+    }
+    return undefined;
+}
+/**
+ * Re-implementation of citty's own (unexported) `resolveSubCommand`: walks
+ * `rawArgs` down the subcommand tree the same way its private
+ * `findSubCommandIndex` / `_findSubCommand` do, so an explicit `--help`
+ * renders the deepest command the user was actually invoking, matching what
+ * citty's own `runMain` would have shown.
+ */
+function resolveDeepestCittyCommand(cmd, rawArgs) {
+    const subCommands = cmd.subCommands;
+    if (subCommands && Object.keys(subCommands).length > 0) {
+        const idx = findCittyTopLevelCommandIndex(rawArgs, (cmd.args ?? {}));
+        const name = idx >= 0 ? rawArgs[idx] : undefined;
+        if (name !== undefined) {
+            const sub = findCittySubCommandByName(subCommands, name);
+            if (sub)
+                return resolveDeepestCittyCommand(sub, rawArgs.slice(idx + 1));
+        }
+    }
+    return cmd;
+}
+function resolveCittyCommandPath(cmd, rawArgs, path = []) {
+    const subCommands = cmd.subCommands;
+    if (!subCommands || Object.keys(subCommands).length === 0)
+        return [...path];
+    const index = findCittyTopLevelCommandIndex(rawArgs, (cmd.args ?? {}));
+    const token = index >= 0 ? rawArgs[index] : undefined;
+    if (token === undefined)
+        return [...path];
+    const sub = findCittySubCommandByName(subCommands, token);
+    if (!sub)
+        return [...path];
+    const name = Object.entries(subCommands).find(([, candidate]) => candidate === sub)?.[0] ?? token;
+    return resolveCittyCommandPath(sub, rawArgs.slice(index + 1), [...path, name]);
+}
+/**
+ * `showUsage`/`renderUsage` (citty) render a subcommand's own USAGE line as
+ * `${parentMeta.name} ${cmdMeta.name}` using only the DIRECT parent — for a
+ * two-deep command (`akm task run`) that renders `task run`, silently
+ * dropping the `akm ` root prefix every top-level command's `--help` already
+ * shows. Building a synthetic parent whose `meta.name` is the full prefix
+ * (`akm task`) fixes it for any depth without patching the vendored
+ * dependency (S11 item 4).
+ */
+function buildUsageParentForPath(path) {
+    // `version` carries through too — citty's renderUsage falls back to
+    // `parentMeta.version` when the resolved command itself declares none
+    // (true of every subcommand here), and the real parent it substitutes for
+    // always resolves to `main`, which does declare one.
+    return {
+        meta: {
+            name: ["akm", ...path.slice(0, -1)].join(" "),
+            version: pkgVersion,
+        },
+    };
+}
+// ── Sectioned root help (S11) ────────────────────────────────────────────────
+//
+// citty's own generated COMMANDS list is a flat, unordered dump of every
+// top-level command — fine for a handful of commands, not for the ~28 this
+// CLI has grown to. Groups them instead under fixed sections mirroring
+// how they're actually used, reusing citty's own `renderUsage` for the
+// banner/USAGE/OPTIONS portion (so it stays byte-identical to every
+// subcommand's own `--help`) and replacing only the COMMANDS section.
+const HELP_SECTIONS = [
+    {
+        title: "AGENT LOOP",
+        commands: ["curate", "search", "show", "feedback", "remember"],
+    },
+    {
+        title: "ASSETS",
+        commands: ["import", "clone", "bundle", "env", "secret", "sync", "proposal"],
+    },
+    { title: "AUTOMATION", commands: ["improve", "agent", "workflow", "task"] },
+    {
+        title: "SYSTEM",
+        commands: [
+            "setup",
+            "index",
+            "lint",
+            "health",
+            "config",
+            "registry",
+            "info",
+            "log",
+            "help",
+            "hints",
+            "upgrade",
+            "completions",
+        ],
+    },
+];
+/** Abbreviations whose trailing period does not end a sentence. */
+const NON_TERMINAL_ABBREVIATIONS = ["e.g.", "i.e.", "etc.", "vs."];
+/**
+ * First sentence of a description, for the root command list.
+ *
+ * Several commands carry multi-paragraph descriptions that are correct on
+ * `akm <cmd> --help` but turn the root listing back into the undifferentiated
+ * wall this section replaced (a single command's description ran past 1k
+ * characters on one row).
+ */
+function firstSentence(text) {
+    const line = text.split("\n", 1)[0]?.trim() ?? "";
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] !== "." && line[i] !== "!" && line[i] !== "?")
+            continue;
+        const candidate = line.slice(0, i + 1);
+        const next = line[i + 1];
+        if (next !== undefined && next !== " ")
+            continue;
+        if (NON_TERMINAL_ABBREVIATIONS.some((abbr) => candidate.toLowerCase().endsWith(abbr)))
+            continue;
+        return candidate;
+    }
+    return line;
+}
+function topLevelCommandDescription(name) {
+    const sub = main.subCommands?.[name];
+    return firstSentence(sub?.meta?.description ?? "");
+}
+function formatCommandRows(names) {
+    const width = Math.max(...names.map((name) => name.length));
+    return names.map((name) => `  ${name.padEnd(width)}  ${topLevelCommandDescription(name)}`).join("\n");
+}
+function renderCommandSections() {
+    return HELP_SECTIONS.map(({ title, commands }) => `${title}\n${formatCommandRows(commands)}`).join("\n\n");
+}
+/**
+ * Sectioned replacement for citty's root COMMANDS list (S11 item 1). Reuses
+ * `renderUsage(main)` for the banner + exit-code table (kept verbatim) +
+ * USAGE line + global OPTIONS, then cuts the string before citty's own
+ * "COMMANDS" heading (present because `main` has `subCommands`) and appends
+ * the grouped sections plus a one-line bundle/ref-grammar tagline and the
+ * `akm help agents` pointer.
+ */
+async function renderSectionedRootHelp() {
+    const base = await renderUsage(main, undefined);
+    const commandsHeadingIndex = base.indexOf("COMMANDS");
+    // Cut at the START of the heading's own line, not the word itself — the
+    // word is preceded by citty's own ANSI bold/underline escape codes, and
+    // slicing mid-line would leave a dangling open escape sequence.
+    const cutIndex = commandsHeadingIndex === -1 ? -1 : base.lastIndexOf("\n", commandsHeadingIndex);
+    const head = (cutIndex === -1 ? base : base.slice(0, cutIndex)).replace(/\n+$/, "");
+    const epilogue = [
+        'A "bundle" is your managed directory of assets (skills, agents, memories, workflows, ...). Refs use the ' +
+            "grammar [bundle//]conceptId[#fragment], where the concept id is the bundle's own path for the asset — " +
+            "e.g. `akm show skills/deploy`, or `akm show work//skills/deploy` for a named bundle. Copy ids from " +
+            "`akm search` output rather than synthesizing them.",
+        "",
+        "Run `akm help <command>` or `akm <command> --help` for details on any command.",
+        "Agents: run `akm hints` for the complete guide or `akm help agents` for the short guide.",
+    ].join("\n");
+    return [head, "", renderCommandSections(), "", epilogue].join("\n");
+}
+/**
+ * Walk down the subcommand tree the same way {@link resolveDeepestCittyCommand}
+ * does, but stop and report the first token that fails to resolve instead of
+ * silently giving up — the attempted spelling plus its sibling candidate set,
+ * for the did-you-mean suggestion below. Returns undefined when every token
+ * resolved (e.g. "no command specified", or a missing positional/flag on an
+ * otherwise-valid command) — there is no unknown NAME to suggest a fix for.
+ */
+function findUnknownCommandAttempt(rawArgs) {
+    let cmd = main;
+    let args = rawArgs;
+    const parentPath = [];
+    for (;;) {
+        const subCommands = cmd.subCommands;
+        if (!subCommands || Object.keys(subCommands).length === 0)
+            return undefined;
+        const idx = findCittyTopLevelCommandIndex(args, (cmd.args ?? {}));
+        const token = idx >= 0 ? args[idx] : undefined;
+        if (token === undefined)
+            return undefined;
+        const sub = findCittySubCommandByName(subCommands, token);
+        if (!sub)
+            return {
+                attempted: token,
+                candidates: Object.keys(subCommands),
+                parentPath,
+            };
+        parentPath.push(token);
+        cmd = sub;
+        args = args.slice(idx + 1);
+    }
+}
+/**
+ * Standard edit-distance DP, single-row-at-a-time (sizes here are always
+ * short command-name strings). Builds each row left-to-right, appending as
+ * it goes, so every index read below is already-populated — the `?? 0`
+ * fallbacks only satisfy `noUncheckedIndexedAccess`, they never fire.
+ */
+function levenshteinDistance(a, b) {
+    let previousRow = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const currentRow = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitutionCost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const deletion = (previousRow[j] ?? 0) + 1;
+            const insertion = (currentRow[j - 1] ?? 0) + 1;
+            const substitution = (previousRow[j - 1] ?? 0) + substitutionCost;
+            currentRow.push(Math.min(deletion, insertion, substitution));
+        }
+        previousRow = currentRow;
+    }
+    return previousRow[b.length] ?? 0;
+}
+/** Closest candidate within a length-scaled distance threshold, or undefined when nothing is close enough to be worth suggesting. */
+function closestCommandMatch(attempted, candidates) {
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = levenshteinDistance(attempted, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    const threshold = Math.max(2, Math.ceil(attempted.length / 2));
+    return best !== undefined && bestDistance <= threshold ? best : undefined;
+}
+const CLI_HELP_POINTER = "Run `akm --help` for usage.";
+/**
+ * citty's `CLIError` carries its own stable `.code` (not exported in its
+ * types, but present on every instance — see {@link isCittyCliError}'s doc
+ * comment): `E_UNKNOWN_COMMAND` for an unrecognized command/subcommand name,
+ * `EARG`/`E_NO_COMMAND` for a missing required argument/positional or a bare
+ * group with no `run`. Maps that to one of this CLI's own stable
+ * `UsageErrorCode`s so the reclassified error (below) carries a real code
+ * instead of the generic fallback.
+ */
+function cittyCliErrorUsageCode(error) {
+    switch (error.code) {
+        case "E_UNKNOWN_COMMAND":
+            return "UNKNOWN_COMMAND";
+        case "EARG":
+        case "E_NO_COMMAND":
+            return "MISSING_REQUIRED_ARGUMENT";
+        default:
+            return "INVALID_FLAG_VALUE";
+    }
+}
+/**
+ * Route a citty `CLIError` through the standard JSON envelope instead of
+ * citty's own usage-banner + raw `console.error(message)` (S11 item 3): the
+ * one-line diagnosis is the error's own message (e.g. "Unknown command
+ * foo"), and the hint is a short pointer — with a did-you-mean suggestion
+ * prepended when the unresolved token is close to a real sibling command —
+ * rather than the full ~46KB usage dump citty would otherwise print.
+ */
+function toUsageErrorFromCliError(error, rawArgs) {
+    const code = cittyCliErrorUsageCode(error);
+    const attempt = code === "UNKNOWN_COMMAND" ? findUnknownCommandAttempt(rawArgs) : undefined;
+    // Retired spellings from the 0.9 hard break get their replacement, not a
+    // did-you-mean: edit distance suggests the WRONG command for most of them
+    // (`init`→`info`, `update`→`upgrade`), and agents follow suggestions.
+    const retired = attempt ? retiredCommandHint(attempt.parentPath, attempt.attempted) : undefined;
+    const suggestion = retired === undefined && attempt ? closestCommandMatch(attempt.attempted, attempt.candidates) : undefined;
+    const hint = retired ?? (suggestion ? `Did you mean \`${suggestion}\`? ${CLI_HELP_POINTER}` : CLI_HELP_POINTER);
+    // citty colorizes error.message with ANSI escapes even when stdout/stderr
+    // is not a TTY. Strip them so the JSON envelope's `error` field is plain
+    // text instead of embedding raw escape sequences.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip ANSI escape codes
+    const message = error.message.replace(/\x1b\[[0-9;]*m/g, "");
+    return new UsageError(message, code, hint);
+}
+/**
+ * The CLI's real startup sequence, extracted into a function so error paths
+ * can `return` early — top-level `return` is a syntax error in an ES module,
+ * and this used to rely on `emitJsonError`'s `never` return type (a
+ * synchronous `process.exit`) to stop execution instead. Now that
+ * `emitJsonError` (src/cli/shared.ts, R-067) only records `process.exitCode`
+ * and returns, every direct call site here needs its own explicit `return;`
+ * to stop the rest of startup from running after a fatal early error.
+ */
+async function runCli() {
+    try {
+        process.argv = consumeSchedulerContextArg(process.argv);
+    }
+    catch (error) {
+        emitJsonError(error);
+        return;
+    }
+    // Mint the ParsedInvocation singleton from the (normalized) argv — the ONE
+    // place argv is parsed for the whole process (plan §10.7 / chunk-9 WI-9.9).
+    // Every out-of-cli.ts command module reads argv state through
+    // `getParsedInvocation()` from here on instead of re-scanning process.argv.
+    setParsedInvocation(process.argv);
     // Resolve output mode once at startup from the (normalized) argv and persisted
     // config. All subsequent output() calls read from this in-memory singleton.
     // `initOutputMode` can throw a UsageError when --format/--detail values are
@@ -556,10 +927,14 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // rather than letting the raw exception escape with a stack trace.
     try {
         applyEarlyStderrFlags(process.argv);
-        initOutputMode(process.argv, loadConfig().output ?? {});
+        if (isTaskRunWithId(process.argv))
+            assertNoPendingMigrationOperation();
+        const bypassConfig = shouldBypassConfigStartup(process.argv);
+        initOutputMode(process.argv, bypassConfig ? (DEFAULT_CONFIG.output ?? {}) : (loadConfig().output ?? {}));
     }
     catch (error) {
         emitJsonError(error);
+        return;
     }
     // `--shape summary` is only meaningful on `akm show`. Reject it up front for
     // every other command so a write command (e.g. `akm proposal accept …`)
@@ -567,23 +942,23 @@ 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).
-    const topLevelCommand = findCittyTopLevelCommand(process.argv.slice(2), MAIN_TOP_LEVEL_ARGS);
+    const commandPath = resolveCittyCommandPath(main, process.argv.slice(2));
+    const topLevelCommand = commandPath[0] ?? 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"));
+        return;
+    }
+    // D7 — every command that renders through output() honours all six --format
+    // values. The declared exempt set (src/output/format-exempt.ts) does not
+    // render an envelope at all, so warn rather than pretend: silently ignoring
+    // the flag is what made the old md/html behaviour so hard to discover. A
+    // warning, not an error, because the flag is harmless here and scripts that
+    // pass --format globally to a mixed batch of commands should still work.
+    const invocation = getParsedInvocation();
+    if ((invocation.hasFlag("--format") || invocation.getFlagValue("--format") !== undefined) &&
+        isFormatExemptCommand(commandPath)) {
+        warn(`[output] '--format' has no effect on 'akm ${commandPath.join(" ")}' — its output is not a result envelope.`);
     }
-    // One-time cleanup of stale 0.7.x index file at the old cache location.
-    // 0.8.0 moved the index to $XDG_DATA_HOME/akm/index.db (getDataDir()).
-    // If the old file exists at $XDG_CACHE_HOME/akm/index.db, remove it so the
-    // user isn't confused by a phantom DB. Best-effort; never fatal.
-    bestEffort(() => {
-        const oldIndexPath = path.join(getCacheDir(), "index.db");
-        if (fs.existsSync(oldIndexPath)) {
-            fs.rmSync(oldIndexPath, { force: true });
-            fs.rmSync(`${oldIndexPath}-shm`, { force: true });
-            fs.rmSync(`${oldIndexPath}-wal`, { force: true });
-            warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
-        }
-    }, "stale 0.7.x index cleanup is non-fatal");
     // First-time-user breadcrumb: when run with no subcommand AND no config
     // exists yet AND stderr is a TTY, print a friendly pointer to `akm setup`
     // above citty's auto-generated usage block. Triggers only when stdin/stderr
@@ -608,5 +983,84 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
         }
         console.error(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
     })();
-    runMain(main);
+    const rawArgs = process.argv.slice(2);
+    try {
+        if (rawArgs.length === 0) {
+            process.stdout.write(`${await renderSectionedRootHelp()}\n`);
+            return;
+        }
+        // Mirrors citty's own builtin-flag short-circuit in `runMain` (main's own
+        // args never declare `help`/`h`/`version`/`v`, so both stay the fixed
+        // defaults citty would have computed too).
+        //
+        // Scan only akm's OWN arguments: everything after a literal `--` belongs to
+        // the child process (`akm env run <ref> -- tool --help`, `akm secret run
+        // <ref> -- tool -h`). Scanning the tail printed akm's usage and returned
+        // without ever launching the requested command.
+        const passthroughAt = rawArgs.indexOf("--");
+        const ownArgs = passthroughAt === -1 ? rawArgs : rawArgs.slice(0, passthroughAt);
+        if (HELP_FLAGS.some((flag) => ownArgs.includes(flag))) {
+            const resolved = resolveDeepestCittyCommand(main, rawArgs);
+            if (resolved === main) {
+                // Root `--help` (S11 item 1): the sectioned overview, not citty's
+                // flat COMMANDS dump.
+                process.stdout.write(`${await renderSectionedRootHelp()}\n`);
+            }
+            else {
+                const path = resolveCittyCommandPath(main, rawArgs);
+                await showUsage(resolved, buildUsageParentForPath(path));
+            }
+            return;
+        }
+        if (rawArgs.length === 1 && VERSION_FLAGS.includes(rawArgs[0])) {
+            console.log(pkgVersion);
+            return;
+        }
+        await runCommand(main, { rawArgs });
+    }
+    catch (error) {
+        if (isCittyCliError(error)) {
+            // R-032/S11: reclassify citty's own "unknown command" / "no command
+            // specified" / "missing required argument" family as USAGE (2) and
+            // route it through the SAME JSON envelope every other command's
+            // failure uses (`emitJsonError`), rather than citty's own usage-banner
+            // + raw `console.error(message)` — a one-line diagnosis plus a short
+            // hint (with a did-you-mean suggestion when applicable), not a ~46KB
+            // usage dump.
+            emitJsonError(toUsageErrorFromCliError(error, rawArgs));
+            return;
+        }
+        // Anything else escaping here is a genuinely unexpected failure outside
+        // any command's own error handling — every command wraps its body in
+        // `runWithJsonErrors`, `defineJsonCommand`, or `defineGroupCommand`, all
+        // three of which route thrown errors through `emitJsonError` before they
+        // could ever reach this boundary. Route it the same way rather than
+        // hard-coding GENERAL(1): the CLI contract reserves 1 for general/not-found
+        // and requires a non-`AkmError` throw to render the JSON failure envelope
+        // with INTERNAL(70) (AGENTS.md "CLI Contract"), which is what lets
+        // automation tell an internal defect apart from an ordinary failure.
+        // `emitJsonError` classifies and sets `process.exitCode` itself.
+        emitJsonError(error);
+    }
+    finally {
+        await disposeDispatchResources();
+    }
+}
+// Only run the CLI when this module is the direct entry point. When it is
+// imported (e.g. by the in-process test harness in tests/_helpers/cli.ts),
+// `import.meta.main` is false and we skip all startup side effects (argv
+// mutation, output-mode init, index cleanup, banner, command dispatch) so
+// importers can drive the `main` command themselves without the process
+// exiting.
+//
+// Node path: this module carries a `#!/usr/bin/env bun` shebang and is launched
+// under Node via the `dist/cli-node.mjs` wrapper, which `import()`s this file
+// (so `import.meta.main` is false here even though the CLI is the real entry).
+// The wrapper sets `AKM_NODE_ENTRY=1` to opt into the startup block. Compiled
+// standalone binaries are the same shape: their entry is
+// `scripts/akm-standalone.ts` (which also embeds the akm-migrate tool), and it
+// sets `AKM_STANDALONE_ENTRY=1` before importing this file. The test harness
+// sets neither, so importing cli.ts under Bun stays inert as before.
+if (import.meta.main || process.env.AKM_NODE_ENTRY === "1" || process.env.AKM_STANDALONE_ENTRY === "1") {
+    await runCli();
 }