akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/cli/invocation.js

@@ -0,0 +1,255 @@
+// 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/.
+/**
+ * Single-parse argv normalization (plan §10.7, chunk-9 WI-9.9).
+ *
+ * Before this module, ~46 `process.argv` read sites were scattered across
+ * `src/**` (32 outside `src/cli.ts`), each re-scanning the raw argv array for
+ * repeated flags (`parseAllFlagValues`), `--`-passthrough tails (`env run`,
+ * `secret run`), or first-occurrence flag values (`parseFlagValue`) — plus a
+ * startup MUTATION of the global `process.argv` at `cli.ts:644`. This module
+ * normalizes argv into one typed {@link ParsedInvocation} object, minted ONCE
+ * by `src/cli.ts` right after its `normalizeShowArgv` rewrite, so every
+ * downstream reader shares one parse instead of re-scanning the raw array.
+ *
+ * Deliberately import-free: this module must never join an import cycle
+ * (cycle ratchet, plan §10.7 / chunk-9 D.3), so it depends on nothing but
+ * global `process` — no `output/context`, no `core/errors`. The flag-parsing
+ * primitives below are intentionally small, self-contained re-implementations
+ * of the same algorithms `output/context.ts`'s `parseFlagValue`/
+ * `hasBooleanFlag` and (the now-retired) `cli/shared.ts` `parseAllFlagValues`
+ * used, kept byte-identical so every converted call site is behavior-
+ * preserving.
+ *
+ * Singleton + fallback semantics (the design decision this module encodes):
+ *  - `setParsedInvocation(argv)` is called exactly once, by `src/cli.ts`,
+ *    immediately after `process.argv = normalizeShowArgv(process.argv)`. It
+ *    snapshots that argv into an immutable {@link ParsedInvocation} that
+ *    every subsequent `getParsedInvocation()` call returns unchanged for the
+ *    rest of the process lifetime — "normalize argv exactly once at entry".
+ *  - `getParsedInvocation()` is the ONLY way leaf command modules read
+ *    invocation state. When the singleton was never set — the common case
+ *    for unit tests that call command logic directly, and for
+ *    `tests/_helpers/cli.ts`'s in-process CLI harness, which drives citty's
+ *    `runCommand` WITHOUT running `src/cli.ts`'s `import.meta.main` startup
+ *    block (see that file's docstring) — it falls back to parsing the
+ *    CURRENT `process.argv` fresh, on every call, uncached. That harness
+ *    mutates `process.argv` itself per invocation and restores it in
+ *    `finally`, and many suites issue several back-to-back in-process runs
+ *    per test; caching the fallback parse would leak one run's flags into
+ *    the next. So "lazily parses process.argv once" means "once PER CALL",
+ *    not "once for the life of the process" — the fallback is intentionally
+ *    request-scoped, mirroring how every pre-WI-9.9 leaf site read
+ *    `process.argv` fresh at call time. Production code never touches the
+ *    fallback path: the real entry point sets the singleton before any
+ *    command handler can run.
+ *  - `_resetParsedInvocationForTests()` clears an explicitly-set singleton
+ *    (symmetry with `resetOutputMode`/`resetConfigCache` in
+ *    `tests/_helpers/cli.ts`); no suite currently needs it because the
+ *    startup block that calls `setParsedInvocation` never runs under
+ *    `bun test`, but it exists so a test that DOES call
+ *    `setParsedInvocation` directly can clean up after itself.
+ *
+ * Also folds three argv re-scanners that pre-dated this module (plan §10.7):
+ *  - `parseAllFlagValues` (moved from `cli/shared.ts`) — repeated-flag
+ *    collection (`--tag foo --tag bar`), re-exported from `cli/shared.ts` so
+ *    every existing importer (feedback-cli, observability-cli, remember-cli,
+ *    search-cli, stash-cli, cli.ts) is unaffected.
+ *  - `findCittyTopLevelCommand`/`findCittyTopLevelCommandIndex` (moved from
+ *    `cli/parse-args.ts`, which had zero internal imports for this cluster) —
+ *    re-exported from `cli/parse-args.ts` for `tests/tasks-embedded.test.ts`
+ *    and `commands/read/show.ts`.
+ *  - `resolveHelpMigrateVersionArg` (moved from `cli.ts`, where it was
+ *    private) — the `akm help migrate <version>` positional/flag
+ *    disambiguation guard.
+ */
+// ── Repeated-flag / `--`-passthrough primitives (byte-identical to the
+// pre-WI-9.9 per-site implementations they replace) ─────────────────────────
+function getFlagValueFrom(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag)
+            return argv[i + 1];
+        if (arg.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return undefined;
+}
+function hasFlagIn(argv, flag) {
+    return argv.some((arg) => arg === flag || arg === `${flag}=true`);
+}
+function getAllFlagValuesFrom(argv, flag) {
+    const values = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === flag && i + 1 < argv.length) {
+            values.push(argv[i + 1]);
+            // BUG-M4: skip the value index so `--tag --tag` (literal `--tag` value)
+            // does not double-count the second `--tag` as a separate flag occurrence.
+            i++;
+        }
+        else if (arg.startsWith(`${flag}=`)) {
+            values.push(arg.slice(flag.length + 1));
+        }
+    }
+    return values;
+}
+/**
+ * Tokens after a literal `--` marker in argv, or `[]` when there is no `--`
+ * OR nothing follows it. Callers that previously threw a "Missing command"
+ * UsageError on `dashIndex < 0 || dashIndex === argv.length - 1` now check
+ * `passthroughArgs().length === 0` — the two conditions are equivalent.
+ */
+function passthroughArgsFrom(argv) {
+    const dashIndex = argv.indexOf("--");
+    if (dashIndex < 0 || dashIndex === argv.length - 1)
+        return [];
+    return argv.slice(dashIndex + 1);
+}
+function createParsedInvocation(argv) {
+    const snapshot = Object.freeze([...argv]);
+    const userArgs = Object.freeze(snapshot.slice(2));
+    return {
+        argv: snapshot,
+        userArgs,
+        getFlagValue: (flag) => getFlagValueFrom(snapshot, flag),
+        hasFlag: (flag) => hasFlagIn(snapshot, flag),
+        getAllFlagValues: (flag) => getAllFlagValuesFrom(snapshot, flag),
+        passthroughArgs: () => passthroughArgsFrom(snapshot),
+    };
+}
+let _invocation;
+/**
+ * Mint the process-wide {@link ParsedInvocation} singleton. Called exactly
+ * once, by `src/cli.ts`, right after `normalizeShowArgv` — "normalize argv
+ * exactly once at entry" (plan §10.7).
+ */
+export function setParsedInvocation(argv) {
+    _invocation = createParsedInvocation(argv);
+    return _invocation;
+}
+/**
+ * Read the process-wide {@link ParsedInvocation}. Returns the singleton set
+ * by `setParsedInvocation` when one exists; otherwise falls back to parsing
+ * the CURRENT `process.argv` fresh (uncached — see the module docstring for
+ * why caching the fallback would be wrong). The fallback is what every
+ * leaf-command unit test and `tests/_helpers/cli.ts`'s in-process harness
+ * exercise; production CLI runs always hit the singleton.
+ */
+export function getParsedInvocation() {
+    if (_invocation)
+        return _invocation;
+    return createParsedInvocation(process.argv);
+}
+/** Test-only: clear an explicitly-set singleton. Symmetry with resetOutputMode/resetConfigCache. */
+export function _resetParsedInvocationForTests() {
+    _invocation = undefined;
+}
+// ── Folded re-scanner #1: parseAllFlagValues (moved from cli/shared.ts) ─────
+/**
+ * Collect all occurrences of a repeatable flag from the current invocation's
+ * argv. Citty's StringArgDef only exposes the last value when a flag is
+ * repeated, so for repeatable CLI args (like `--tag foo --tag bar`) callers
+ * read argv directly via this helper. Supports both `--flag value` and
+ * `--flag=value` forms.
+ */
+export function parseAllFlagValues(flag) {
+    return getParsedInvocation().getAllFlagValues(flag);
+}
+function cittyComparableName(name) {
+    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
+}
+function toAliasArray(alias) {
+    if (Array.isArray(alias))
+        return alias;
+    return typeof alias === "string" ? [alias] : [];
+}
+function isCittyValueFlag(flag, argsDef) {
+    const name = flag.replace(/^-{1,2}/, "");
+    const normalized = cittyComparableName(name);
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== "string" && def.type !== "enum")
+            continue;
+        if (normalized === cittyComparableName(key))
+            return true;
+        if (toAliasArray(def.alias).includes(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Match citty's top-level subcommand scan (`findSubCommandIndex`).
+ *
+ * Citty does not assume `rawArgs[0]` is the command: global string flags may
+ * appear first and consume the following token. The CLI startup guard uses this
+ * to classify the requested command before any command handler can run.
+ */
+export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
+    for (let i = 0; i < rawArgs.length; i += 1) {
+        const arg = rawArgs[i];
+        if (arg === "--")
+            return -1;
+        if (arg.startsWith("-")) {
+            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
+                i += 1;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+export function findCittyTopLevelCommand(rawArgs, argsDef) {
+    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
+    return index >= 0 ? rawArgs[index] : undefined;
+}
+// ── Folded re-scanner #3: resolveHelpMigrateVersionArg (moved from cli.ts,
+// where it was a private, unexported function) ──────────────────────────────
+/**
+ * Guard against citty consuming a global flag value as the `help migrate`
+ * version positional (mirrors `resolveRememberContentArg` /
+ * `wasFormatValueConsumedAsName` in the read/sources leaf modules).
+ *
+ * When the user runs `akm help migrate --format json` without a version
+ * argument, citty may assign `"json"` to the `version` positional. This
+ * detects that case and returns `undefined` so the caller surfaces the
+ * "missing version" UsageError instead of treating a flag value as a version.
+ */
+export function resolveHelpMigrateVersionArg(version) {
+    if (version === undefined)
+        return undefined;
+    const invocation = getParsedInvocation();
+    const parsedFormat = invocation.getFlagValue("--format");
+    if (parsedFormat !== undefined &&
+        version === parsedFormat &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = invocation.getFlagValue("--detail");
+    if (parsedDetail !== undefined &&
+        version === parsedDetail &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return version;
+}
+function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName) {
+    const argv = getParsedInvocation().userArgs;
+    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;
+}

package/dist/cli/parse-args.js

@@ -8,52 +8,12 @@
  * main CLI file focused on command definitions and routing.
  */
 import { UsageError } from "../core/errors.js";
-function cittyComparableName(name) {
-    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
-}
-function toAliasArray(alias) {
-    if (Array.isArray(alias))
-        return alias;
-    return typeof alias === "string" ? [alias] : [];
-}
-function isCittyValueFlag(flag, argsDef) {
-    const name = flag.replace(/^-{1,2}/, "");
-    const normalized = cittyComparableName(name);
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (def.type !== "string" && def.type !== "enum")
-            continue;
-        if (normalized === cittyComparableName(key))
-            return true;
-        if (toAliasArray(def.alias).includes(name))
-            return true;
-    }
-    return false;
-}
-/**
- * Match citty's top-level subcommand scan (`findSubCommandIndex`).
- *
- * Citty does not assume `rawArgs[0]` is the command: global string flags may
- * appear first and consume the following token. The CLI startup guard uses this
- * to classify the requested command before any command handler can run.
- */
-export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
-    for (let i = 0; i < rawArgs.length; i += 1) {
-        const arg = rawArgs[i];
-        if (arg === "--")
-            return -1;
-        if (arg.startsWith("-")) {
-            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
-                i += 1;
-            continue;
-        }
-        return i;
-    }
-    return -1;
-}
-export function findCittyTopLevelCommand(rawArgs, argsDef) {
-    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
-    return index >= 0 ? rawArgs[index] : undefined;
-}
+import { warn } from "../core/warn.js";
+// findCittyTopLevelCommand(Index) + CittyArg(s)DefinitionForScan moved to
+// ./invocation (chunk-9 WI-9.9 argv-normalization fold — that cluster had no
+// internal imports, so it relocated cleanly); re-exported here so existing
+// importers (tests/tasks-embedded.test.ts, commands/read/show.ts) are unaffected.
+export { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, } from "./invocation.js";
 /**
  * Return true when `args._[0]` is a member of `validSet`.
  *
@@ -113,49 +73,26 @@ export function parseNonNegativeIntFlag(raw, flagName) {
     }
     return parseInt(trimmed, 10);
 }
-// ── Auto-accept flag parsing ─────────────────────────────────────────────────
+// ── Auto-accept flag parsing (deprecated) ───────────────────────────────────
 /**
- * Parse the value of `akm improve --auto-accept` into a confidence threshold.
+ * DEPRECATED (0.9.0): `akm improve --auto-accept` is accepted but ignored.
  *
- * Semantics (see docs/migration/v0.7-to-v0.8.md):
- * - `undefined` (flag absent) → `undefined` (default-OFF; pre-prod flip)
- * - `""` (bare `--auto-accept`, no value) → `undefined` (treated as flag absent)
- * - `"false"` (case-insensitive) → `undefined` (explicit disable)
- * - `"safe"` (case-insensitive) → `90` (permanent back-compat alias)
- * - integer string `"0".."100"` → that integer
- * - anything else → throws `UsageError("INVALID_FLAG_VALUE")`
+ * The confidence gate the flag configured was deleted in 0.9.0 — proposals
+ * now queue for review (`akm proposal` / the drain engine) instead of being
+ * auto-promoted by threshold. The flag warns-and-ignores for one minor
+ * because installed crontabs embed the old command line; a hard parse error
+ * would make scheduled background runs fail invisibly after upgrade. Hard
+ * removal in 0.10.
  *
- * Citty's `type: "string"` resolves bare flags to `""` and an absent flag to
- * `undefined`. Both forms now disable auto-accept; users must pass an explicit
- * threshold (`--auto-accept=N` or `--auto-accept=safe`) to opt in. This is a
- * deliberate flip from the earlier 0.8.0-RC behaviour, which defaulted to ON
- * at threshold 90 and surprised users who didn't expect Phase B operations to
- * apply without confirmation.
- *
- * Until proposals expose per-operation confidence scores, any non-`undefined`
- * threshold causes the consolidate path to auto-accept the whole batch
- * (legacy "safe" behaviour). The threshold value is preserved for the eventual
- * per-operation comparison; see the TODO in `consolidate.ts`.
+ * - `undefined` (flag absent) → silent no-op.
+ * - Any present value (bare flag, `safe`, `false`, a number, garbage) →
+ *   one deprecation warning on stderr; never throws.
  */
 export function parseAutoAcceptFlag(raw) {
     if (raw === undefined)
-        return undefined;
-    const trimmed = raw.trim();
-    if (trimmed === "")
-        return undefined;
-    const lower = trimmed.toLowerCase();
-    if (lower === "false")
-        return undefined;
-    if (lower === "safe")
-        return 90;
-    if (!/^\d+$/.test(trimmed)) {
-        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
-    }
-    const parsed = parseInt(trimmed, 10);
-    if (parsed < 0 || parsed > 100) {
-        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
-    }
-    return parsed;
+        return;
+    warn("[improve] --auto-accept is deprecated and ignored (the 0.9.0 confidence gate was removed; " +
+        "proposals queue for review via `akm proposal` or the drain engine). The flag will be removed in 0.10.");
 }
 // ── String flag parsing ──────────────────────────────────────────────────────
 /**

package/dist/cli/shared.js

@@ -10,12 +10,14 @@
 import { defineCommand } from "citty";
 import { stringify as yamlStringify } from "yaml";
 import { assertNever } from "../core/assert.js";
-import { AkmError } from "../core/errors.js";
+import { AkmError, UsageError } from "../core/errors.js";
 import { getOutputMode } from "../output/context.js";
-import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
+import { deliverRendered } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { parseAllFlagValues } from "./invocation.js";
 import { hasSubcommand } from "./parse-args.js";
+export { parseAllFlagValues };
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -171,40 +173,16 @@ export function output(command, result) {
             // pipelines never get an empty stdout.
             deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
             return;
-        case "html": {
-            // Generic fallback: render the JSON envelope inside the dark-mode
-            // default template. Commands with a bespoke HTML template (`akm health`)
-            // intercept before reaching output(), same as the `md` intercept.
-            const html = renderHtml(resolveTemplatePath(DEFAULT_TEMPLATE), {
-                "%%COMMAND%%": escapeHtml(command),
-                "%%CONTENT_JSON%%": escapeHtml(JSON.stringify(shaped, null, 2)),
-                "%%GENERATED_AT%%": new Date().toISOString(),
-            });
-            deliverRendered(html, mode.outputPath);
-            return;
-        }
-    }
-}
-/**
- * Collect all occurrences of a repeatable flag from process.argv.
- * Citty's StringArgDef only exposes the last value when a flag is repeated,
- * so for repeatable CLI args (like `--tag foo --tag bar`) we read argv directly.
- * Supports both `--flag value` and `--flag=value` forms.
- */
-export function parseAllFlagValues(flag) {
-    const values = [];
-    for (let i = 0; i < process.argv.length; i++) {
-        const arg = process.argv[i];
-        if (arg === flag && i + 1 < process.argv.length) {
-            values.push(process.argv[i + 1]);
-            // BUG-M4: skip the value index so `--tag --tag` (literal `--tag`
-            // value) does not double-count the second `--tag` as a separate
-            // flag occurrence.
-            i++;
-        }
-        else if (arg.startsWith(`${flag}=`)) {
-            values.push(arg.slice(flag.length + 1));
-        }
+        case "html":
+            // `akm health` intercepts `mode.format === "html"` before reaching
+            // output() (cli.ts, same as the `md` intercept) and renders its own
+            // bespoke template. Every other command has no HTML surface — the
+            // generic JSON-in-<pre> fallback template was removed (chunk-9 WI-9.4c
+            // / Decision 4); `html` stays a valid --format value (OUTPUT_FORMATS),
+            // it just only resolves for health.
+            throw new UsageError("html output is only available for `akm health`", "INVALID_FLAG_VALUE");
     }
-    return values;
 }
+// parseAllFlagValues moved to ./invocation (chunk-9 WI-9.9 argv-normalization
+// fold); re-exported above so every existing importer of this module is
+// unaffected.

package/dist/cli.js

@@ -2,24 +2,22 @@
 // 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: the akm-cli npm package bootstraps with Node.js >= 20.12
+// 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: the akm-cli npm package requires 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` +
                 "  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" +
@@ -60,10 +58,11 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex } from "./cli/parse-args.js";
-import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared.js";
+import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
+import { EXIT_CODES, emitJsonError, output, runWithJsonErrors } from "./cli/shared.js";
 import { agentCommand, lintCommand, proposeCommand } from "./commands/agent/contribute-cli.js";
 import { backupCommand } from "./commands/backup-cli.js";
+import { bundleCommand } from "./commands/bundle/bundle-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
 import { configCommand } from "./commands/config-cli.js";
 import { envCommand } from "./commands/env/env-cli.js";
@@ -88,7 +87,6 @@ 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 { workflowCommand } from "./commands/workflow-cli.js";
 import { bestEffort } from "./core/best-effort.js";
 import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
@@ -98,7 +96,7 @@ import { getCacheDir, getConfigPath, getDbPath } from "./core/paths.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
 import { disposeDispatchResources } from "./integrations/agent/runner-dispatch.js";
-import { getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue } from "./output/context.js";
+import { getHyphenatedBoolean, getOutputMode, initOutputMode } from "./output/context.js";
 import { deliverRendered, renderHtml, resolveTemplatePath } from "./output/html-render.js";
 import { pkgVersion } from "./version.js";
 function applyEarlyStderrFlags(argv) {
@@ -109,43 +107,9 @@ function applyEarlyStderrFlags(argv) {
         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
@@ -504,6 +468,7 @@ export const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
+        bundle: bundleCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -537,7 +502,6 @@ export const main = defineCommand({
         completions: completionsCommand,
         env: envCommand,
         secret: secretCommand,
-        wiki: wikiCommand,
         tasks: tasksCommand,
     },
 });
@@ -590,6 +554,11 @@ 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);
+    // 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

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

@@ -14,7 +14,7 @@
  * filled from the extra positional args in order.
  */
 import fs from "node:fs";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
@@ -39,7 +39,7 @@ function fillPlaceholders(template, args) {
 async function resolveAssetBody(ref) {
     let parsed;
     try {
-        parsed = parseAssetRef(ref);
+        parsed = parseRefInput(ref);
     }
     catch (err) {
         throw new UsageError(`Invalid asset ref "${ref}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_FLAG_VALUE");

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

@@ -28,6 +28,7 @@ import { EXIT_CODES, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
 import { akmLint } from "../lint/index.js";
 import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
@@ -40,13 +41,13 @@ export const agentCommand = defineCommand({
     args: {
         "agent-ref": {
             type: "positional",
-            description: "Optional agent asset ref (e.g. agent:code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
+            description: "Optional agent asset ref (e.g. agents/code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
             required: false,
         },
         prompt: { type: "string", description: "Task prompt to pass to the agent" },
         engine: { type: "string", description: "Agent engine to use (default: defaults.engine)" },
-        command: { type: "string", description: "Load prompt from a command: asset" },
-        workflow: { type: "string", description: "Load prompt from a workflow: asset" },
+        command: { type: "string", description: "Load prompt from a command asset" },
+        workflow: { type: "string", description: "Load prompt from a workflow asset" },
         model: {
             type: "string",
             description: "Model override — accepts aliases (opus, sonnet, haiku) or exact platform model IDs. Overrides the model specified in the agent asset.",
@@ -69,7 +70,7 @@ export const agentCommand = defineCommand({
             let assetTools;
             if (agentRef) {
                 const { akmShowUnified } = await import("../read/show.js");
-                const asset = await akmShowUnified({ ref: agentRef, detail: "full" });
+                const asset = await akmShowUnified({ ref: agentRef, detail: "full", eventSource: resolveUsageEventSource() });
                 systemPrompt = typeof asset.content === "string" ? asset.content : undefined;
                 assetModel = typeof asset.modelHint === "string" ? asset.modelHint : undefined;
                 assetTools = asset.toolPolicy;