akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/cli/parse-args.js

@@ -8,7 +8,6 @@
  * main CLI file focused on command definitions and routing.
  */
 import { UsageError } from "../core/errors.js";
-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
@@ -73,27 +72,6 @@ export function parseNonNegativeIntFlag(raw, flagName) {
     }
     return parseInt(trimmed, 10);
 }
-// ── Auto-accept flag parsing (deprecated) ───────────────────────────────────
-/**
- * DEPRECATED (0.9.0): `akm improve --auto-accept` is accepted but ignored.
- *
- * 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.
- *
- * - `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;
-    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 ──────────────────────────────────────────────────────
 /**
  * Extract a string value from a parsed citty argument object by key.

package/dist/cli/retired-commands.js

@@ -0,0 +1,121 @@
+// 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/.
+/**
+ * Replacement hints for command spellings retired by the 0.9 CLI overhaul
+ * (hard break — no aliases). Consulted by the unknown-command error path
+ * BEFORE the edit-distance did-you-mean: distance-based suggestions are
+ * actively misleading for retired spellings (`init` → "did you mean
+ * `info`?", `update` → "did you mean `upgrade`?" — the latter replaces the
+ * BINARY, not the sources), and an agent following them gets steered into
+ * the wrong command instead of the renamed one.
+ *
+ * Keys are either a bare retired top-level token (`"init"`) or a
+ * group-scoped `"<group> <sub>"` pair (`"env set"`). Keep entries one
+ * sentence; the migration pointer is appended by the caller.
+ */
+const RETIRED_COMMAND_HINTS = {
+    // Top-level verbs absorbed by the `bundle` group.
+    init: "`akm init` moved in 0.9 — use `akm bundle create`.",
+    add: "`akm add` moved in 0.9 — use `akm bundle add <source>`.",
+    list: "`akm list` moved in 0.9 — use `akm bundle list`.",
+    remove: "`akm remove` moved in 0.9 — use `akm bundle remove <source>`.",
+    update: "`akm update` moved in 0.9 — use `akm bundle update` (to update akm itself, use `akm upgrade`).",
+    // Group renamed to the singular.
+    tasks: "the `tasks` group was renamed in 0.9 — use `akm task <subcommand>`.",
+    // Verbs absorbed by the `proposal` group.
+    extract: "`akm extract` moved in 0.9 — use `akm proposal extract`.",
+    propose: "`akm propose` moved in 0.9 — use `akm proposal new`.",
+    proposals: "`akm proposals` moved in 0.9 — use `akm proposal list`.",
+    accept: "`akm accept` moved in 0.9 — use `akm proposal accept <id>`.",
+    reject: '`akm reject` moved in 0.9 — use `akm proposal reject <id> --reason "..."`.',
+    diff: "`akm diff` moved in 0.9 — use `akm proposal diff <id>`.",
+    revert: "`akm revert` moved in 0.9 — use `akm proposal revert <id>`.",
+    reflect: "`akm reflect` was folded into 0.9 — use `akm improve <ref>`.",
+    distill: "`akm distill` was folded into 0.9 — use `akm improve <ref>`.",
+    // Renamed persistence and observability verbs.
+    save: "`akm save` moved in 0.9 — use `akm sync`.",
+    events: "`akm events` moved in 0.9 — use `akm log`.",
+    // Removed observability surfaces.
+    history: "`akm history` was removed in 0.9 — use `akm log --ref <ref>` for an asset's event trail.",
+    graph: "`akm graph` was removed in 0.9 — graph counts appear in `akm health`; refresh extraction with `akm improve --strategy graph-refresh`.",
+    lessons: "`akm lessons` was removed in 0.9 — lesson strength is indexed; use `akm search --type lesson`.",
+    lesson: "`akm lesson` was removed in 0.9 — lesson strength is indexed; use `akm search --type lesson`.",
+    // Relocated guidance / removed asset verbs.
+    mv: "`akm mv` was removed in 0.9 — move the file, then run `akm index` and `akm lint` (to carry ranking signal: `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>`).",
+    // Pre-0.9 removals agents still trip over.
+    wiki: "the `akm wiki` family was removed in 0.9 — wikis are ordinary knowledge assets; ingest with `akm import <url> --path <subdir>`.",
+    backup: "`akm backup` was removed in 0.9 — backups belong to the standalone `akm-migrate backup` tool.",
+    vault: "the `akm vault ...` family was removed in 0.9 — use `akm env list`/`akm env create` for a whole `.env` group, or `akm secret set <name>` for a single sensitive value.",
+    // Group-scoped retirements.
+    "env set": "`akm env set` was removed in 0.9 — edit the `.env` file directly; akm loads it as-is.",
+    "env unset": "`akm env unset` was removed in 0.9 — edit the `.env` file directly; akm loads it as-is.",
+    "registry search": "`akm registry search` was folded into `akm search --from registry` in 0.9.",
+    "registry build-index": "`akm registry build-index` moved in 0.9 — maintainers run `bun scripts/build-registry-index.ts`.",
+    "workflow template": "`akm workflow template` was folded into `akm workflow create --print` in 0.9.",
+    "workflow validate": "`akm workflow validate` was folded into `akm lint --type workflows` in 0.9 (add `--fail-on-flagged` for CI gates).",
+    "workflow watch": "`akm workflow watch` was removed in 0.9 — use `akm log --run <run-id>`.",
+    "workflow start": "`akm workflow start` was removed in 0.9 — use `akm workflow run <ref>`.",
+    "workflow next": "`akm workflow next` was removed in 0.9 — use `akm workflow status <target>` to inspect or `akm workflow run <target>` to execute.",
+    "workflow complete": "`akm workflow complete` was removed in 0.9 — `akm workflow run <target>` completes steps automatically; use `akm workflow status <target>` to inspect.",
+    "workflow brief": "`akm workflow brief` was removed — the external-driver protocol is gone; `akm workflow run <target>` executes the run and `akm workflow status <target>` inspects it.",
+    "workflow report": "`akm workflow report` was removed — the external-driver protocol is gone; `akm workflow run <target>` dispatches and records units itself.",
+    "config show": "`akm config show` was removed in 0.9 — use `akm config list`.",
+    "config validate": "`akm config validate` was removed in 0.9 — the config file is validated on every load.",
+    "task enable": "`akm task enable` was removed in 0.9 — set `enabled: true` in the task YAML, then `akm task sync`.",
+    "task disable": "`akm task disable` was removed in 0.9 — set `enabled: false` in the task YAML, then `akm task sync`.",
+    "task init": "`akm task init` was removed in 0.9 — `akm setup` seeds the default schedules.",
+    "task list": "there is no `task list` — task files are indexed assets; use `akm search --type task`.",
+    "task show": "there is no `task show` — task files are indexed assets; use `akm show <ref>`.",
+    "task remove": "there is no `task remove` — delete the task YAML, then run `akm task sync` to unbind it.",
+    // `improve canary` is NOT here: `akm improve` is a leaf command (a
+    // positional `ref`, not a subcommand group), so "canary" never reaches the
+    // unknown-command path this table serves — `improve-cli.ts` already
+    // self-diagnoses it with a more specific, correct message before this
+    // table would ever be consulted.
+    "log tail": "`akm log tail` was removed in 0.9 — poll `akm log --since @offset:<id>` (the durable cursor).",
+    "log list": "`akm log list` was flattened in 0.9 — bare `akm log` is the same surface.",
+};
+const MIGRATION_POINTER = "Full rename table: `akm help migrate 0.9.0`.";
+/**
+ * Replacement hint for a retired spelling, or undefined when the attempted
+ * token isn't a known retirement. `parentPath` is the group path already
+ * resolved before the unknown token (empty at root), so `env set` and a
+ * hypothetical top-level `set` can't collide.
+ */
+export function retiredCommandHint(parentPath, attempted) {
+    const key = parentPath.length === 0 ? attempted : `${parentPath[parentPath.length - 1]} ${attempted}`;
+    const entry = RETIRED_COMMAND_HINTS[key];
+    return entry === undefined ? undefined : `${entry} ${MIGRATION_POINTER}`;
+}
+/**
+ * Same idea as {@link RETIRED_COMMAND_HINTS}, but for FLAGS the 0.9 overhaul
+ * removed outright rather than commands. Consulted by
+ * `src/cli/unknown-flags.ts` BEFORE its own edit-distance did-you-mean, for
+ * the same reason: a distance-based suggestion on a retired flag can point at
+ * an unrelated survivor rather than the real replacement procedure.
+ *
+ * Keys are the FULL resolved command path joined with spaces, plus the flag
+ * exactly as the unknown-flag scanner reports it (leading dashes, long form
+ * only — `--background`, not `-b`): `"<cmd> [sub...] --flag"`. The command
+ * path is whatever `unknown-flags.ts`'s `KnownArgs.path` resolved (e.g.
+ * `["proposal", "extract"]` for the flag's CURRENT location, not any retired
+ * top-level spelling — that command-level retirement is already handled by
+ * {@link retiredCommandHint} before flag scanning ever runs).
+ */
+const RETIRED_FLAG_HINTS = {
+    "index --background": "`--background` was removed in 0.9 — the flag never actually backgrounded; use `--quiet`.",
+    "setup --detect-only": "`--detect-only` was removed in 0.9 — environment detection runs inside `akm setup`; `akm info` reports the configured capabilities.",
+    "setup --reset-recommended": "`--reset-recommended` was removed in 0.9 — `akm setup` now offers to apply recommended defaults interactively.",
+    "proposal extract --watch": "`--watch` was removed in 0.9 — schedule `akm proposal extract --auto` as a task instead.",
+    "proposal extract --debounce-ms": "`--debounce-ms` was removed in 0.9 — schedule `akm proposal extract --auto` as a task instead.",
+};
+/**
+ * Replacement hint for a retired flag on its current command path, or
+ * undefined when the attempted spelling isn't a known retirement.
+ */
+export function retiredFlagHint(path, attempted) {
+    const key = `${path.join(" ")} ${attempted}`;
+    const entry = RETIRED_FLAG_HINTS[key];
+    return entry === undefined ? undefined : `${entry} ${MIGRATION_POINTER}`;
+}

package/dist/cli/shared.js

@@ -12,7 +12,9 @@ import { stringify as yamlStringify } from "yaml";
 import { assertNever } from "../core/assert.js";
 import { AkmError, UsageError } from "../core/errors.js";
 import { getOutputMode } from "../output/context.js";
+import { renderGenericHtml, renderGenericMarkdown, renderGenericText } from "../output/generic-render.js";
 import { deliverRendered } from "../output/html-render.js";
+import { getHtmlRendererHandler, getMdRendererHandler } from "../output/render-registry.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
 import { parseAllFlagValues } from "./invocation.js";
@@ -73,8 +75,26 @@ function extractHint(error) {
     return undefined;
 }
 /**
- * Serialize an error to the standard JSON envelope and exit.
- * Used in both the startup try/catch and `runWithJsonErrors`.
+ * Serialize an error to the standard JSON envelope and record the mapped
+ * exit code. Used in both the startup try/catch and `runWithJsonErrors`.
+ *
+ * R-067: this used to call `process.exit(exitCode)` directly, which
+ * terminates the process synchronously and skips every pending `finally`
+ * block up the call stack — including `src/cli.ts`'s own
+ * `disposeDispatchResources()` cleanup and citty's per-command `cleanup`
+ * hooks. `process.exitCode = exitCode; return;` is equivalent for every
+ * caller here: Node/Bun exits with that code once the event loop drains
+ * naturally, but cleanup on the way there still runs.
+ * `src/commands/improve/extract-cli.ts` already uses this exact pattern for
+ * its own non-throw failure signal.
+ *
+ * Because this no longer throws or exits, it no longer terminates control
+ * flow on its own — every call site MUST treat it like a normal return and
+ * stop doing further work itself (an explicit `return;` right after the
+ * call, same as any other caller of a fallible function). `runWithJsonErrors`
+ * below satisfies this for free (this call is its catch block's last
+ * statement); `src/cli.ts`'s three direct call sites add the `return;`
+ * explicitly.
  */
 export function emitJsonError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -84,7 +104,7 @@ export function emitJsonError(error) {
     // internal errors have none.
     const code = error instanceof AkmError ? error.code : undefined;
     console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
-    process.exit(exitCode);
+    process.exitCode = exitCode;
 }
 /**
  * Run an async function and route any thrown error through the standard JSON
@@ -98,25 +118,126 @@ export async function runWithJsonErrors(fn) {
         emitJsonError(error);
     }
 }
+/**
+ * The global output flags, redeclared on every leaf command.
+ *
+ * citty parses each command level against only that command's own args, so a
+ * flag declared on the root command is UNKNOWN at the leaf — and an unknown
+ * flag does not consume its space-separated value, which then falls through as
+ * a positional. `akm sync --format json` once synced a bundle named "json",
+ * and `akm env unset env:x KEY --format json` once tried to unset a key named
+ * "json"; both grew bespoke argv-inspection workarounds. Declaring the flags
+ * at the leaf lets the parser consume the value, which is the root-cause fix.
+ *
+ * These declarations exist for PARSING only. The output mode is still read
+ * exactly once, from the invocation singleton at startup — no command body may
+ * read these args (that is the same one-parse rule `cli/invocation.ts`
+ * documents).
+ *
+ * These are also the canonical descriptions for the root command's own args
+ * (`main.args` in src/cli.ts) — the root spreads this same object rather than
+ * redeclaring the text, so root help and leaf help can never drift apart.
+ * `format`/`detail` need per-site `default` overrides (root has one, leaves
+ * don't — see the one-parse rule above), so those two keys get shallow
+ * overrides at the root; the description text itself is never duplicated.
+ */
+export const GLOBAL_OUTPUT_ARGS = {
+    format: { type: "string", description: "Output format: json|jsonl|yaml|text|md|html (global flag)" },
+    detail: {
+        type: "string",
+        description: "Detail level (verbosity): brief|normal|full (global flag).",
+    },
+    // R-050(c): single-sourced with the root command's own `--shape` help
+    // (`main.args.shape` in src/cli.ts, which spreads this object) so the
+    // caveat is visible from every leaf's own `--help`, not only the top-level
+    // one. `summary` outside `show` is a hard usage error (exit 2,
+    // INVALID_SHAPE_VALUE), enforced at startup in src/cli.ts before any
+    // command body runs.
+    shape: {
+        type: "string",
+        description: "Output projection: human|agent|summary (global flag). 'agent' trims to agent-essential fields; " +
+            "'summary' is only valid on 'akm show' (a usage error, exit 2, everywhere else). Default: human.",
+    },
+    output: {
+        type: "string",
+        description: "Write rendered output to a file instead of stdout (all formats except jsonl) (global flag)",
+    },
+    // S11: surfaced at every leaf (not just the root) so `akm <command> --help`
+    // documents them too — they already apply globally, parsed from raw argv
+    // by `applyEarlyStderrFlags` in src/cli.ts before citty ever sees them, so
+    // declaring them here is documentation, not new parsing behavior. A
+    // command with its own same-named arg (e.g. `env path --quiet`) wins the
+    // merge in `defineJsonCommand` as usual.
+    quiet: {
+        type: "boolean",
+        alias: "q",
+        description: "Suppress non-essential stderr output (banners, spinners, progress info) (global flag). " +
+            "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 (global flag; also honours AKM_VERBOSE env var).",
+        default: false,
+    },
+};
 /**
  * Define a citty command whose `run` body is automatically wrapped in
  * `runWithJsonErrors`, so the handler emits a byte-identical JSON error
  * envelope (stdout/stderr/exit-code) on throw without the boilerplate. A
  * command without a `run` (a pure subcommand group) is passed through
  * unchanged.
+ *
+ * Every command defined here also accepts the {@link GLOBAL_OUTPUT_ARGS} so
+ * their values are parsed rather than mis-captured as positionals; a command
+ * declaring its own arg of the same name wins (e.g. `env path` has its own
+ * `quiet`).
  */
 export function defineJsonCommand(def) {
     const { run, ...rest } = def;
+    const withGlobals = { ...rest, args: { ...GLOBAL_OUTPUT_ARGS, ...rest.args } };
     if (!run)
-        return defineCommand({ ...rest });
+        return defineCommand(withGlobals);
     return defineCommand({
-        ...rest,
+        ...withGlobals,
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Canonical bare-group behavior (0.9.0 breaking change, owner ruling 12).
+ *
+ * Before 0.9.0 the twelve `akm <group>` command groups did three different
+ * things when invoked with no subcommand: some printed help and exited 1,
+ * some ran an implicit default action and exited 0 (e.g. bare `akm graph`
+ * silently rendering `graph summary`), and one already raised a structured
+ * usage error and exited 2. None of that is discoverable from the exit code
+ * alone, and a script that greps stdout for a specific default action broke
+ * silently the moment someone reordered subcommands.
+ *
+ * The canonical choice, applied uniformly: a bare group invocation is a
+ * USAGE ERROR — exit 2, the same structured JSON envelope every other usage
+ * mistake in this CLI produces (not citty's raw help banner, and not a
+ * silent default action). This matches STABILITY.md's documented exit-code
+ * table (2 = usage) and the exit code the CLI already used for "unknown
+ * command" / "missing required argument" as of the companion 0.9.0 fix.
+ *
+ * `defaultRun` is now OPTIONAL for exactly this reason: omitting it opts a
+ * group into the shared, canonical error below. Passing an explicit
+ * `defaultRun` is a deliberate opt-out and should not be added to new groups
+ * without a documented reason — see CHANGELOG for the migration note.
+ */
+function bareGroupUsageError(meta, subcommandSet) {
+    const name = typeof meta === "object" && meta !== null && "name" in meta && typeof meta.name === "string"
+        ? meta.name
+        : undefined;
+    const usage = name ? `\`akm ${name}\`` : "This command";
+    const subcommands = [...subcommandSet].sort().join(", ");
+    throw new UsageError(`${usage} requires a subcommand. Available: ${subcommands}.`, "MISSING_REQUIRED_ARGUMENT", `Run \`akm ${name ?? "<command>"} --help\` to see usage for each subcommand.`);
+}
 /**
  * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
- * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * …) that shares one wiring shape: a `subCommands` map, a routing set
  * DERIVED from that map's keys (so the set can never silently desync from the
  * registered subcommands), and a default body that fires ONLY for the bare
  * group invocation — citty still runs the group body after dispatching a
@@ -130,6 +251,7 @@ export function defineJsonCommand(def) {
  */
 export function defineGroupCommand(def) {
     const subcommandSet = new Set(Object.keys(def.subCommands));
+    const defaultRun = def.defaultRun ?? (() => bareGroupUsageError(def.meta, subcommandSet));
     return defineCommand({
         meta: def.meta,
         ...(def.args ? { args: def.args } : {}),
@@ -137,7 +259,7 @@ export function defineGroupCommand(def) {
         run: (context) => runWithJsonErrors(() => {
             if (hasSubcommand(context.args, subcommandSet))
                 return;
-            return def.defaultRun(context);
+            return defaultRun(context);
         }),
     });
 }
@@ -162,25 +284,35 @@ export function output(command, result) {
             deliverRendered(yamlStringify(shaped), mode.outputPath);
             return;
         case "text": {
+            // D7 — registry first, generic rendering of the shaped envelope second.
+            // Mirrors the md/html fallback immediately below: a command with no
+            // registered text formatter used to fall through to
+            // `JSON.stringify(shaped, null, 2)`, i.e. silently hand back JSON while
+            // claiming `--format text` — the same "wrong format wearing the right
+            // flag" bug D7 already closed for md/html. `renderGenericText` (a
+            // DISTINCT function from `renderGenericMarkdown` — see its doc comment
+            // in src/output/generic-render.ts for why reusing the md renderer here
+            // was itself a version of the same bug) renders flat `key=value` text
+            // matching the house style already established by registered text
+            // formatters like `config list`.
             const plain = formatPlain(command, shaped, mode.detail);
-            deliverRendered(plain ?? JSON.stringify(shaped, null, 2), mode.outputPath);
+            deliverRendered(plain ?? renderGenericText(command, shaped), mode.outputPath);
             return;
         }
-        case "md":
-            // `--format md` is currently only consumed by `akm health` for the
-            // per-run / window-compare table renderings. Commands that don't
-            // implement an md renderer fall back to the JSON envelope so
-            // pipelines never get an empty stdout.
-            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
+        case "md": {
+            // D7 — registry first, generic rendering of the shaped envelope second.
+            // No command emits JSON under `--format md` any more: silently handing
+            // back the wrong format was the worst of the three behaviours this
+            // replaced.
+            const rendered = getMdRendererHandler(command)?.(shaped, mode.detail);
+            deliverRendered(rendered ?? renderGenericMarkdown(command, shaped), mode.outputPath);
+            return;
+        }
+        case "html": {
+            const rendered = getHtmlRendererHandler(command)?.(shaped, mode.detail);
+            deliverRendered(rendered ?? renderGenericHtml(command, shaped), mode.outputPath);
             return;
-        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");
+        }
     }
 }
 // parseAllFlagValues moved to ./invocation (chunk-9 WI-9.9 argv-normalization

package/dist/cli/unknown-flags.js

@@ -0,0 +1,236 @@
+// 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/.
+/**
+ * Reject flags the resolved command does not declare.
+ *
+ * citty (0.2.x) parses argv with `node:util`'s parseArgs in non-strict mode
+ * (`strict: false`), so an undeclared flag is collected into the parsed object
+ * and silently ignored by the handler. Nothing
+ * downstream noticed, so `akm lint --fail-on-flaged` (one transposed letter in
+ * the flag STABILITY.md documents as a CI contract) parsed fine, exited 0, and
+ * the gate it was meant to enforce never fired. Same for `--limt 3`, `--jsn`,
+ * and every other typo — the command ran with the default instead, and the user
+ * had no signal.
+ *
+ * This walks the same subcommand path citty resolves (via the shared scan
+ * helpers in `./invocation`), unions the arg definitions declared along it,
+ * and fails a flag that matches nothing. The union (rather than the leaf's
+ * args alone) is deliberate: parent-level flags may legally appear before the
+ * subcommand token, and a false positive here would reject a VALID invocation
+ * — much worse than the silence it replaces. In the same spirit, everything
+ * after a literal `--` is passthrough, a declared value flag's value is never
+ * scanned as a flag, `--no-<name>` resolves against `<name>`, and a bare `-`
+ * (stdin convention) and negative numbers are left alone. A subcommand invoked
+ * by a `meta.name` alias rather than its key takes the stand-down path (no
+ * validation) — conservative by design.
+ */
+import { UsageError } from "../core/errors.js";
+import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray, } from "./invocation.js";
+import { retiredFlagHint } from "./retired-commands.js";
+/** Flags citty implements itself, which no command declares. */
+const IMPLICIT_FLAGS = ["help", "h", "version", "v"];
+/**
+ * Retired flags whose commands still diagnose them THEMSELVES, with a message
+ * that names the replacement ("`--scope` was removed, use `--filter`",
+ * "`--source` was renamed to `--generator`"). A generic "unknown flag" would
+ * preempt the better diagnosis, so these are passed through — but ONLY on the
+ * command path that owns the diagnostic, keyed by the resolved path. On every
+ * other command the same spelling is a genuine typo and still fails fast
+ * A retired flag is rejected everywhere else, where silently dropping it could
+ * run a real mutation.
+ *
+ * Shrink-only: when a command drops its bespoke diagnostic, drop the entry and
+ * the generic error takes over.
+ */
+const SELF_DIAGNOSED_FLAGS = new Map(Object.entries({
+    show: ["akmView", "scope"], // removed view grammar; --scope points at --filter
+    index: ["enrich", "re-enrich"], // removed index-time enrichment flags
+    "proposal accept": ["source"], // renamed to --generator
+    "proposal reject": ["source"], // renamed to --generator
+    "proposal drain": ["profile"], // retired, points at --strategy
+    search: ["source"], // renamed to --from
+    curate: ["source"], // renamed to --from
+    remember: ["target"], // renamed to --bundle
+    clone: ["target"], // renamed to --bundle
+    improve: ["auto-accept", "target"], // retired in 0.9.0 / renamed to --bundle
+    "task add": ["target"], // renamed to --bundle
+    "task run": ["target"], // renamed to --bundle
+    "task history": ["target"], // renamed to --bundle
+    "task sync": ["target"], // renamed to --bundle
+}).map(([path, flags]) => [path, new Set(flags.map(cittyComparableName))]));
+/**
+ * Union the arg definitions declared along the resolved command path. The
+ * subcommand walk delegates to {@link findCittyTopLevelCommandIndex} — the
+ * same scan `src/cli.ts` resolves commands with — so both agree on which
+ * token is the subcommand name.
+ */
+function collectKnownArgs(root, rawArgs) {
+    const names = new Set(IMPLICIT_FLAGS.map(cittyComparableName));
+    const valueFlags = new Set();
+    const booleanFlags = new Set();
+    const displayNames = [];
+    const path = [];
+    let cmd = root;
+    let args = rawArgs;
+    for (;;) {
+        for (const [key, def] of Object.entries(cmd.args ?? {})) {
+            // Positionals are not flags; including them would accept `--<positional>`.
+            if (def.type === "positional")
+                continue;
+            const comparable = cittyComparableName(key);
+            // Shared args (GLOBAL_OUTPUT_ARGS) recur at every level; suggest each once.
+            if (!names.has(comparable)) {
+                names.add(comparable);
+                displayNames.push(`--${key}`);
+            }
+            if (def.type === "string" || def.type === "enum")
+                valueFlags.add(comparable);
+            if (def.type === "boolean")
+                booleanFlags.add(comparable);
+            for (const alias of toAliasArray(def.alias)) {
+                names.add(cittyComparableName(alias));
+                if (def.type === "string" || def.type === "enum")
+                    valueFlags.add(cittyComparableName(alias));
+                if (def.type === "boolean")
+                    booleanFlags.add(cittyComparableName(alias));
+            }
+        }
+        const subCommands = cmd.subCommands;
+        if (!subCommands || Object.keys(subCommands).length === 0)
+            break;
+        const idx = findCittyTopLevelCommandIndex(args, (cmd.args ?? {}));
+        const token = idx >= 0 ? args[idx] : undefined;
+        // A group with no subcommand token: citty reports "no command specified".
+        if (token === undefined)
+            return { names, valueFlags, booleanFlags, displayNames, path, resolved: false };
+        const sub = subCommands[token];
+        // An unrecognized token: citty reports the unknown command, which is the
+        // real problem — its flags are beside the point.
+        if (!sub)
+            return { names, valueFlags, booleanFlags, displayNames, path, resolved: false };
+        path.push(token);
+        cmd = sub;
+        args = args.slice(idx + 1);
+    }
+    return { names, valueFlags, booleanFlags, displayNames, path, resolved: true };
+}
+/** Single-row-at-a-time edit-distance DP (inputs are short flag/command names). */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + cost));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+/**
+ * Closest candidate within `threshold` edit distance, or undefined when
+ * nothing is close enough to be worth suggesting. Shared by the unknown-flag
+ * and unknown-command (src/cli.ts) did-you-mean paths, which pick different
+ * thresholds.
+ */
+export function closestMatch(attempted, candidates, threshold) {
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = editDistance(attempted, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return best !== undefined && bestDistance <= threshold ? best : undefined;
+}
+/**
+ * The one unknown-flag rejection, shared by the short- and long-flag scans so
+ * the user-facing error contract cannot drift between them. No explicit hint
+ * when there is no suggestion — UNKNOWN_FLAG's canned hint (core/errors.ts)
+ * already says to run the command with --help.
+ *
+ * @param shown      The flag as the user typed it (dashes, no `=value`).
+ * @param attempted  The spelling to edit-distance against `--long` candidates.
+ */
+function throwUnknownFlag(shown, attempted, known) {
+    // Flags the 0.9 overhaul removed outright get their retirement note, not a
+    // did-you-mean — same reasoning as `retiredCommandHint` in src/cli.ts:
+    // edit distance can point at an unrelated survivor rather than the real
+    // replacement procedure (e.g. `index --background` is closer to no other
+    // `index` flag than it is to any useful suggestion).
+    const retired = retiredFlagHint(known.path, attempted);
+    if (retired) {
+        throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", retired);
+    }
+    const threshold = Math.max(2, Math.ceil(attempted.length / 3));
+    const suggestion = closestMatch(attempted, known.displayNames, threshold);
+    throw new UsageError(`Unknown flag "${shown}".`, "UNKNOWN_FLAG", suggestion
+        ? `Did you mean \`${suggestion}\`? Run the command with \`--help\` to see its accepted flags.`
+        : undefined);
+}
+/**
+ * Throw a {@link UsageError} naming the first flag the resolved command does
+ * not declare. Returns silently when every flag is known.
+ */
+export function assertKnownFlags(root, rawArgs) {
+    const passthroughAt = rawArgs.indexOf("--");
+    const ownArgs = passthroughAt === -1 ? rawArgs : rawArgs.slice(0, passthroughAt);
+    const known = collectKnownArgs(root, rawArgs);
+    if (!known.resolved)
+        return;
+    const dynamicWorkflowParams = known.path.join(" ") === "workflow run";
+    const selfDiagnosed = SELF_DIAGNOSED_FLAGS.get(known.path.join(" "));
+    for (let i = 0; i < ownArgs.length; i += 1) {
+        const token = ownArgs[i];
+        // Not a flag: positional, a bare `-` (stdin), or a negative number.
+        if (!token.startsWith("-") || token === "-" || /^-\d/.test(token))
+            continue;
+        // Node's util.parseArgs, which citty delegates to, treats one-dash tokens
+        // as bundled short flags. Boolean aliases may be combined (`-qy`), while a
+        // string alias consumes the remainder (`-mhello`) or the following token.
+        // It never treats `-auto-fix` as the long `auto-fix` option.
+        if (!token.startsWith("--")) {
+            const shortFlags = token.slice(1);
+            for (let offset = 0; offset < shortFlags.length; offset += 1) {
+                const rawName = shortFlags[offset];
+                const candidate = cittyComparableName(rawName);
+                if (!known.names.has(candidate))
+                    throwUnknownFlag(token, `-${rawName}`, known);
+                if (known.valueFlags.has(candidate)) {
+                    if (offset === shortFlags.length - 1)
+                        i += 1;
+                    break;
+                }
+            }
+            continue;
+        }
+        const withoutDashes = token.replace(/^-{1,2}/, "");
+        const [rawName = ""] = withoutDashes.split("=", 1);
+        const hasInlineValue = withoutDashes.includes("=");
+        // `--no-foo` is citty's negation of the BOOLEAN `--foo`. Resolving it
+        // against a value flag would accept `--no-limit`, which citty's own `--no-`
+        // preprocessing force-sets to `limit: false` (no type check, before
+        // parseArgs runs) — a boolean reaching a string parser, i.e. an internal
+        // error (exit 70) instead of the usage error (exit 2) this is here to give.
+        const negated = rawName.startsWith("no-") && known.booleanFlags.has(cittyComparableName(rawName.slice(3)))
+            ? rawName.slice(3)
+            : undefined;
+        const candidates = [cittyComparableName(rawName), ...(negated ? [cittyComparableName(negated)] : [])];
+        if (selfDiagnosed !== undefined && candidates.some((name) => selfDiagnosed.has(name)))
+            continue;
+        if (!candidates.some((name) => known.names.has(name))) {
+            // `workflow run` owns one deliberately dynamic namespace: long options
+            // become exact-name workflow parameters and are checked against the
+            // frozen plan before a run is inserted. Short flags remain strict.
+            if (dynamicWorkflowParams)
+                continue;
+            throwUnknownFlag(token.split("=")[0], `--${rawName}`, known);
+        }
+        // Skip a declared value flag's value so `--reason "--x"` is not scanned.
+        if (!hasInlineValue && candidates.some((name) => known.valueFlags.has(name)))
+            i += 1;
+    }
+}

package/dist/cli-node.mjs

@@ -20,7 +20,8 @@ import { register } from "node:module";
 register("./text-import-hook.mjs", import.meta.url);
 
 // cli.js gates its startup block on `import.meta.main`, which is false when we
-// `import()` it here. Opt in explicitly so the CLI actually runs `runMain`.
+// `import()` it here. Opt in explicitly so the CLI actually runs its startup
+// block (dispatch, `runCli`).
 process.env.AKM_NODE_ENTRY = "1";
 
 await import("./cli.js");