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

package/CHANGELOG.md

@@ -6,6 +6,124 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Removed
+
+- **The experimental `akm workflow brief` / `akm workflow report`
+  external-driver protocol is removed**, along with the
+  `experimental.workflowEngine` config key that gated it, its
+  `WORKFLOW_ENGINE_NOT_ENABLED` error code, and the `workflowEngine` block in
+  `akm task doctor`. `akm workflow run` is now the single execution surface.
+
+  The protocol let a calling agent session execute a run's units itself
+  instead of akm dispatching them. Its stated justification was harness
+  neutrality, which measurement did not support: native dispatch already
+  covers **ten** harnesses (opencode, claude, opencode-sdk, codex, copilot,
+  pi, gemini, aider, amazonq, openhands) in 2,214 LOC total, while the
+  protocol cost 2,690 LOC on its own — more than supporting every harness
+  natively — and an eleventh harness is ~220 lines, not a protocol. Removing
+  it also drops the second consumer of `workflow_run_units` and the
+  cross-surface parity obligation on `step-work.ts`, both of which
+  constrained every future engine change. The analysis is recorded in
+  `docs/architecture/specs/driver-protocol-keep-or-cut.md`.
+
+  Legacy configs setting `experimental.workflowEngine` remain valid — the
+  config schema is `.passthrough()`, so the key is accepted and ignored.
+
+### Added
+
+- **`akm workflow run` and prompt tasks fall back to `opencode-sdk` instead of
+  refusing when no engine is configured.** A clean install that never ran
+  `akm setup` — a bare container, a CI image, an agent-operated session — used
+  to fail closed with `INVALID_CONFIG_FILE` (exit 78). When the `opencode`
+  binary is on PATH, akm now synthesizes a **config-free** `opencode-sdk`
+  engine: it carries no model, endpoint, or credential, so provider, model,
+  and auth all resolve from opencode's own configuration and akm never mirrors
+  or validates it. With `opencode` absent the failure is unchanged, and its
+  remedy now names both routes. An operator-configured `opencode-sdk` engine
+  always wins over the synthesized one.
+
+  The requirement is the **binary**, not the npm package: `@opencode-ai/sdk`
+  is an HTTP client that declares no dependencies and whose own
+  `createOpencodeServer` spawns `opencode serve`, so a host with the package
+  and no binary has no server to reach. Install it with `npm i -g opencode-ai`
+  or opencode's own installer.
+
+  The fallback is **announced, never silent**: a workflow run surfaces it once
+  at run creation in the result's `warnings`, and a prompt task writes it to
+  the task run log. The frozen plan records the engine actually used, so a
+  resume never re-announces a decision it did not make.
+
+- **RSS, Bluesky, and X sources.** `akm bundle add` now recognizes three new
+  kinds of URL and snapshots them as knowledge assets instead of crawling
+  them as ordinary web pages:
+
+  ```sh
+  akm bundle add https://blog.example/feed          # RSS 2.0 / Atom / RDF
+  akm bundle add https://bsky.app/profile/<handle>  # public, no auth
+  akm bundle add https://x.com/<user>               # see token note below
+  ```
+
+  Any of these falling through — a `/feed` URL that actually serves HTML, an
+  unresolvable Bluesky handle — degrades to the normal website crawl rather
+  than failing the command.
+
+  X needs credentials: set `X_BEARER_TOKEN` for the X API v2, or
+  `X_RSS_TEMPLATE` to an RSS bridge URL containing `{username}`. To keep the
+  token out of your shell history, store it as an akm secret and inject it
+  per-invocation:
+
+  ```sh
+  akm secret set x-bearer-token
+  akm secret run secrets/x-bearer-token X_BEARER_TOKEN -- akm bundle add https://x.com/<user>
+  ```
+
+  With neither set, the X fetcher emits one warning and falls through.
+
+### Changed
+
+- **X source tokens now resolve from the secret store during bundle update.**
+  The `secrets/x-bearer-token` akm secret is honored on the provider
+  `sync()` / bundle-update path, not just when adding or importing a URL —
+  closing a gap where a refresh saw only the `X_BEARER_TOKEN` environment
+  variable. Implemented as a `SecretResolver` capability injected from above
+  the source-provider import cycle; internals are documented in
+  `docs/architecture/reviews/env-secret-access.md`.
+
+- **`website` crawls now have a hard time limit.** `crawlTimeoutMs` (default
+  600000 — 10 minutes) bounds the entire crawl, and unlike the previous
+  between-page check it aborts work already in flight: a `Retry-After` sleep
+  could previously park `akm bundle add` for as long as a rate-limiting server
+  asked, well past the advertised cap. Raise it for a large site, or set
+  `"crawlTimeoutMs": 0` to disable the cap. Relatedly, `fetchWithRetry` now
+  honors its caller's `AbortSignal` during retry backoff, so any operation that
+  passes a signal can actually interrupt a long wait.
+
+- **Website snapshots now extract the page's main content.** Conversion moved
+  from a hand-rolled regex converter to a DOM parse plus Turndown, scoped to
+  the page's content region (`<main>`, `<article>`, `[role=main]`, then common
+  content ids/classes, falling back to `<body>` minus nav/header/footer/aside).
+  Navigation, ads, and boilerplate no longer land in snapshots, and tables,
+  nested lists, and fenced code blocks with language hints now survive
+  conversion. **Existing website snapshots will change on their next refresh**
+  — expect them to get shorter and cleaner. Link discovery still scans the
+  whole page, so crawl coverage is unchanged.
+
+
+- **`website` sources now respect `robots.txt` by default.** Before crawling
+  an origin, akm fetches and parses that origin's `/robots.txt` and skips
+  paths disallowed for the `akm`/`akm-cli` product tokens (or `*`), honoring
+  `Crawl-delay` (clamped to 10s) between page fetches. This is a deliberate
+  behavior change: **existing website sources may return fewer pages, or
+  fail with an error if the start URL itself is disallowed, after
+  upgrading.** Re-running `akm bundle update` on a website source is what
+  surfaces it. Opt out with `"respectRobots": false` on the website
+  descriptor to restore the exact pre-upgrade behavior (no `/robots.txt`
+  request at all):
+
+  ```json
+  { "bundles": { "docs": { "website": { "url": "https://docs.example.com", "respectRobots": false } } } }
+  ```
+
 ## [0.9.0-rc.13] - 2026-07-31
 
 ### Security
@@ -139,6 +257,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
+- **Workflow execution is consolidated on stable `akm workflow run`.** The
+  public `workflow start`, `next`, and `complete` commands are removed with
+  explicit `UNKNOWN_COMMAND` migration hints; `run <ref|run-id>` now owns
+  creation, active-run continuation, native dispatch, completion, and durable
+  replay. It is no longer gated by `experimental.workflowEngine`; only the
+  experimental `brief`/`report` external-driver protocol retains that opt-in.
+  Workflow parameters move from the opaque `--params '<json>'` bag to exact
+  declared flags (`--version 1.2.3`, repeated array flags, JSON object/array
+  values) coerced through the frozen parameter schemas. New invocation controls
+  add bounded failed-step retries (`--max-retries`) and a whole-run timeout
+  (`--timeout N|Nms|Ns|Nm`); failures, gate rejection, timeout, and signals now
+  produce non-zero process statuses while leaving interrupted work resumable.
+
+  Criteria-bearing gates now require `workflow.judgeEngine`, which may name a
+  configured LLM or agent engine and is frozen into the run. Verification is
+  fail-closed: a missing/failing verifier or malformed verdict rejects instead
+  of silently advancing. Scheduled workflow tasks now execute through the same
+  native orchestrator rather than stopping after run creation. Migration:
+  replace `workflow start/next/complete` loops with `workflow run`, replace
+  `--params` with exact declared flags, and configure `workflow.judgeEngine`
+  before running a workflow with a non-empty `### gate` rubric.
+
 - **The two workflow authoring formats — markdown documents and YAML
   orchestration programs — are unified into one format**, per
   `docs/architecture/specs/workflow-format-unification.md`. A workflow is
@@ -169,15 +309,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   bullet section — they live under a step's `### gate` sub-heading, the
   format's one reserved marker, as full prose a judge receives byte-exact.
   Frontmatter `gate:` now carries only optional `max_loops` configuration.
-  Omitted or empty rubric text skips validation; a non-empty rubric enables
-  fail-open validation, and unavailable or malformed judges are skipped.
+  Omitted or empty rubric text skips validation; a non-empty rubric requires
+  the frozen `workflow.judgeEngine`, and unavailable or malformed judges reject
+  the gate.
 
-  This is a **pre-1.0 change to an unshipped, opt-in feature** —
-  `experimental.workflowEngine` has never been enabled by default, and no
-  workflow asset has shipped outside the ten example workflows under
-  `scripts/akm-eval/example-stash/workflows/`, all rewritten to the
-  unified format in this change. There is nothing on disk to migrate and
-  no users to break.
+  This is a **pre-1.0 format change**. The ten example workflows under
+  `scripts/akm-eval/example-stash/workflows/` are rewritten to the unified
+  format in this change; existing user-authored workflow assets must be updated
+  manually before execution.
 
 - **akm is described as a knowledge toolkit, not a package manager** (R-048).
   The npm one-liner, the README lede, and the `concepts.md` opener all led with
@@ -766,9 +905,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **The CHURN alert class is removed from the collapse detector.** Its input was
   a hard-coded `0` from the 0.9.0 confidence-gate deletion onward, so the alert
   could never fire. The other three alert classes are unaffected. The
-  `improve_cycle_metrics.accepted_actions` column stays and is written as `0`:
-  it lives in a released migration body, and 0.8 ships `state.db`, so a deployed
-  ledger can already have sealed that body's checksum.
+  `improve_cycle_metrics.accepted_actions` column stays and is written as `0`
+  because deployed 0.8 `state.db` files already contain it.
 
 - **`IndexResponse.graphQuality` is removed** from the `akm index` envelope — it
   was declared but never assigned in any code path, so it was always absent.
@@ -839,15 +977,16 @@ earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
   order). The pre-0.9.0 `[origin//]type:name` grammar is removed — there is no
   compatibility parser; the frozen migrator in `scripts/akm-migrate/migrate/`
   is the only place it survives.
-- **Explicit, journaled, crash-resumable cutover (`akm migrate apply`).** The
+- **Explicit, crash-resumable cutover (`akm migrate apply`).** The
   migrator re-keys all durable state to the new spelling, folds the former
   `workflow.db` into `state.db` (four databases down to three: `state.db` /
   `index.db` / a separate `logs.db`), and migrates config from the flat
   `stashDir` / `sources` / `installed` / `wikiName` keys to `bundles` /
-  `defaultBundle`. A verified, installation-scoped **backup manifest v3**
-  (covering the pre-rescue `index.db`) is taken before any ledger is sealed;
-  expected orphans are quarantined, integrity failures fail closed, and the
-  whole cutover resumes idempotently after a crash. Normal commands refuse an
+  `defaultBundle`. A semantically verified, installation-scoped **backup manifest v4**
+  (covering the pre-rescue `index.db`) is taken before mutation. One phase-free
+  incomplete sentinel retains that backup and target; expected orphans are
+  quarantined, integrity failures fail closed, and the whole cutover reruns
+  idempotently after a crash. Normal commands refuse an
   un-migrated or divergent durable schema rather than migrating as a side effect.
   The retired `stashDir` / `sources` / `installed` keys are **hard-rejected** by
   the 0.9.0 config schema whenever present (the error names `akm migrate apply`);
@@ -888,13 +1027,13 @@ See `docs/migration/v0.8-to-v0.9.md` and
   migration, dashboard, or health schema was added.
 - **Explicit, crash-resumable 0.9 migration coordination.** `akm migrate
   status` classifies config, `state.db`, and `workflow.db` independently;
-  `akm migrate apply [--config <prepared>]` creates a verified,
-  installation-scoped backup before sealing ledgers or applying pending
-  migrations. Apply and restore use authenticated phase journals, exact
-  artifact fingerprints, bounded streaming I/O, SQLite integrity checks,
-  active-writer barriers, WAL/SHM-safe publication, and idempotent recovery.
-  Routine reads and current database opens no longer depend on a historical
-  cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
+  `akm migrate apply [--config <prepared>]` creates a semantically verified,
+  installation-scoped config/database backup before applying pending migrations.
+  Apply and restore use one phase-free incomplete sentinel, bounded control-file
+  reads, SQLite integrity and ordered-ledger checks, active-writer barriers,
+  WAL/SHM-safe publication, and idempotent replay. Legacy checksum columns are
+  inert. Routine reads and current database opens no longer depend on a
+  historical cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
 - **Workflow orchestration engine (experimental).** akm can now execute
   multi-step workflows through a native engine or any agent session. Workflow
   assets use the unified markdown format described above; the stable manual

package/dist/akm-migrate

@@ -24,11 +24,13 @@ const bunProbe = process.versions.bun
 const [bunMajor = 0] = (bunProbe.status === 0 ? bunProbe.stdout.trim() : "").split(".").map(Number);
 const useBun = bunMajor >= 1;
 const bunEntry = fileURLToPath(new URL("./scripts/akm-migrate.js", import.meta.url));
+const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.meta.url));
 
 {
   const command = process.versions.bun ? process.execPath : useBun ? "bun" : process.execPath;
+  const entry = process.versions.bun || useBun ? bunEntry : nodeEntry;
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [bunEntry, ...process.argv.slice(2)], { stdio: "inherit" });
+    const child = spawn(command, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/assets/hints/cli-hints-full.md

@@ -93,7 +93,7 @@ akm import https://example.com/docs/auth       # Fetch one URL and import it as
 akm import ./doc.md --target my-other-bundle    # Route import to a named writable bundle source
 akm workflow create ship-release               # Create a workflow asset in the bundle
 akm lint --type workflows                      # Parse and compile every unified markdown workflow; list every error
-akm workflow next workflows/ship-release       # Start or resume the next workflow step
+akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped
 akm feedback agents/reviewer --negative --reason "wrong framework" # Record why an asset missed the mark
 akm feedback memories/deployment-notes --positive # Works for memories too
@@ -169,9 +169,8 @@ workflow. Direct run-id commands still target the exact run.
 ```sh
 akm workflow create ship-release --print     # Print a starter workflow template, without writing
 akm workflow create ship-release             # Scaffold a new workflow asset
-akm workflow start workflows/ship-release    # Start a new run in the current scope
-akm workflow next workflows/ship-release     # Advance to the next step (or auto-start) in the current scope
-akm workflow complete <run-id> --step <id> --summary "..."  # Mark a step complete and advance
+akm workflow run workflows/ship-release --version=1.2.3  # Start and execute with exact-name parameter flags
+akm workflow run <run-id> --max-retries 2 --timeout 10m  # Resume with invocation-wide controls
 akm workflow status <run-id>                 # Show the exact run by id
 akm workflow resume <run-id>                 # Resume a blocked or failed run
 akm workflow list                            # List workflow runs in the current scope

package/dist/assets/hints/cli-hints-short.md

@@ -11,12 +11,12 @@ For any task, follow this loop:
 4. `akm feedback <ref> --positive` — record success; use `--negative --reason "..."` when it fails
 
 For workflow tasks:
-1. `akm workflow next workflows/<name>` — get current step instructions
-2. Do the step work in your workspace
-3. `akm workflow complete <run-id> --step <step-id> --summary "what was done"` — mark done, get next step
+1. `akm show workflows/<name>` — inspect the procedure before executing it
+2. `akm workflow run workflows/<name> --param_name=value` — execute every step and verification gate
+3. `akm workflow status <run-id> --units` — inspect a stopped or failed run
 
 Workflow runs are scoped to your current project/worktree/directory. Ref-based
-commands like `workflow next workflows/<name>`, `workflow status workflows/<name>`,
+commands like `workflow run workflows/<name>`, `workflow status workflows/<name>`,
 and `workflow list` operate within the current scope only.
 
 ## Quick Reference
@@ -29,7 +29,7 @@ akm search "memories/projectA/"               # List a subtree (conceptId prefix
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
 akm help <command>                            # Show a command's options and subcommands
-akm workflow next <ref>                       # Start or resume a workflow
+akm workflow run <ref>                        # Start or resume and execute a workflow
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
 akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)

package/dist/assets/workflows/workflow-template.md

@@ -32,9 +32,10 @@ first step's attached artifact."
 ### gate
 
 A `### gate` sub-heading is the step's completion rubric: the judge
-receives this whole section byte-exact when validation is available. Omit
-the heading or leave its text empty to skip validation. An unavailable or
-malformed judge also skips validation.
+receives this whole section byte-exact. Omit the heading or leave its text
+empty to skip validation. A non-empty rubric requires
+`workflow.judgeEngine`; verifier failures and malformed verdicts reject the
+gate rather than silently skipping it.
 
 - Confirm the step accomplished what it set out to do.
 - Confirm nothing required was silently skipped.

package/dist/cli/invocation.js

@@ -181,10 +181,11 @@ export function _resetParsedInvocationForTests() {
 export function parseAllFlagValues(flag) {
     return getParsedInvocation().getAllFlagValues(flag);
 }
-function cittyComparableName(name) {
+/** citty compares `foo-bar` and `fooBar` as the same arg name. */
+export function cittyComparableName(name) {
     return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
 }
-function toAliasArray(alias) {
+export function toAliasArray(alias) {
     if (Array.isArray(alias))
         return alias;
     return typeof alias === "string" ? [alias] : [];

package/dist/cli/retired-commands.js

@@ -54,6 +54,11 @@ const RETIRED_COMMAND_HINTS = {
     "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`.",

package/dist/cli/unknown-flags.js

@@ -0,0 +1,226 @@
+// 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";
+/** 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) {
+    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;
+    }
+}