akm-cli 0.9.1 → 0.9.2-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,98 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.2-alpha.2] - 2026-08-25
+
+- TODO
+
+## [0.9.2-alpha.1] - 2026-08-24
+
+### Breaking changes & migration
+
+- **Node.js 22 is no longer supported by the npm package.** `akm-cli` now
+  requires Node.js >= 24 to bootstrap its command. A working Bun >= 1.0 remains
+  optional and preferred for execution after that bootstrap; the standalone
+  binary remains runtime-free. Upgrade Node before installing or running the
+  npm package.
+- The `inherit_env` option is a breaking removal: new durable-v4 workflow starts reject it.
+  Replace ambient whole-process inheritance with exact named environment bindings and
+  `exec.pass_env` names. Pre-v4 stored workflow plans are not executable in
+  0.9.2; start a new run from current source.
+- `improve.strategies.*.processes.triage.judgment` now accepts `true`/`false`
+  and honors `enabled` on object values; existing `{}` and configured objects
+  remain enabled. Unknown object keys are now rejected instead of ignored, so
+  correct typos such as `egnine`, `judgement`, or other unrecognized fields
+  before upgrading. Use `judgment: false` to disable the tier explicitly.
+
+### Added
+
+- **WP0 — characterization and release contracts:** pinned direct-agent,
+  command, task, workflow-freeze, model-alias, and harness-lowering behavior;
+  added cross-entry-point equivalence fixtures and immutable release-surface
+  gates.
+- **WP1 — shared execution contracts:** introduced adapter-rendered source
+  identity and one resolved-request representation carrying final content,
+  engine/model/inference selection, authorization, runtime settings, source
+  hashes, and structured lowering notices.
+- **WP2 — layered model maps:** ship a versioned installed `models.json`, merge
+  an optional user overlay from the config directory, expand known aliases by
+  engine, pass unknown identifiers through exactly, and provide guarded model
+  map initialization.
+- **WP3 — common cascade and authorization:** resolve far-to-near defaults once,
+  preserve explicit false/zero/empty values, authorize selected tools before
+  dispatch, and expose stable field-level provenance without resolved values.
+- **WP4 — portable command execution:** added canonical
+  `akm command run <ref>`, implemented one-pass `$ARGUMENTS` substitution, and
+  reject unsupported native template constructs before dispatch. Stored
+  commands have one execution surface; `akm agent --command` is not retained.
+- **WP6 — task v3:** added the strict shipped task schema, command/workflow/script
+  targets, closed shell and working-directory rules, portable schedules, and a
+  fail-closed task-v2 migrator with no-write preview, per-file status, backups,
+  validation, and blocked argv-array handling.
+- **WP7 — peer workflow sources and durable v4:** compile Markdown and the
+  approved GitHub-shaped `.yml` subset through source IR v1; new runs atomically
+  persist immutable v4 targets, guarded source reads, symbolic environments,
+  and durable dispatch attempts. Pre-v4 stored plans are rejected rather than
+  maintaining a second runtime.
+- **WP8 — release diagnostics:** added zero-write, secret-safe command dry-run
+  output, stderr-only verbose provenance, offline `selected-model-aliases` and
+  `configured-engines` health advisories, self-contained migration guidance,
+  and npm tar/install/link release gates.
+
+### Changed
+
+- **WP5 — engine lowering convergence:** direct command/agent execution,
+  improve/proposal dispatch, tasks, and workflows now share the resolved-request
+  boundary and implementation-derived lowerers. Exact model and inference
+  settings reach registered harnesses; unsupported fields produce safe notices,
+  while provider capability rejection remains a runtime result.
+- Scheduled workflow fires re-read the current peer source and create a fresh
+  durable-v4 freeze. Resume remains journaled replay, and crash recovery uses
+  at-least-once attempt semantics with stable reclaim identities.
+- Task scheduler synchronization is transactional across supported adapters and
+  preserves exact ownership, rollback evidence, enabled state, parameters,
+  timeouts, redaction metadata, and resolver overrides.
+
+### Fixed
+
+- Ordinary managed database opens no longer silently apply released migration
+  `018-drop-dead-lane-schema`, which drops retired tables and a column. Every
+  state migration now has an explicit safety classification; migration 002's
+  row-preserving table rebuild remains automatic, while migration 018 requires
+  a successful `akm upgrade` and a verified sibling SQLite snapshot created
+  immediately before its immutable SQL runs. The ledger recheck, WAL-inclusive
+  snapshot, and 018 transaction now share one writer-exclusion window; fresh
+  files and randomized backup paths are atomically reserved and inode-verified.
+  Pre-existing unversioned files—including an absent or empty migration
+  ledger—are rejected without writes by ordinary opens and snapshotted before
+  migration 001 by explicit upgrade. That snapshot, ledger initialization, and
+  migrations 001–002 share one writer-exclusion transaction, preventing an old
+  schema writer from landing data between the snapshot and the 002 rebuild.
+  Migration locks now reject phantom `BEGIN IMMEDIATE` results before running
+  SQL and fail clearly if the transaction disappears after a body. Snapshot
+  source and target handles are inode-bound, and failed reserved paths are
+  retained rather than removed by raced cleanup.
+
 ## [0.9.1] - 2026-08-18
 
 ### Fixed
@@ -1125,34 +1217,17 @@ See `docs/migration/v0.8-to-v0.9.md` and
   and a real domain asset always outranks the facts. That invariant is pinned
   by `tests/search-convention-fact-demotion.test.ts`, which becomes the
   regression guard if a demotion contributor is ever revisited.
-- **Config-gated indexing of the self-situating body opening —
-  `index.indexBodyOpening` (default `false`).** Body prose is not indexed
-  (the FTS `content` column carries only TOC headings and parameters), which
-  is why the stash conventions route orientation into
-  `description:`/`when_to_use:`. With the new flag enabled, the metadata pass
-  captures the first prose paragraph of each markdown asset body — skipping
-  headings (ATX and setext), fenced code blocks, thematic breaks, and a
-  leading nested frontmatter block (only when its content is actually
-  frontmatter-shaped: prose wrapped in decorative `---` lines is captured,
-  not discarded); capped at 280 chars with word-boundary truncation and a
-  trailing ellipsis — into `entry.bodyOpening`, which folds into the
-  lowest-weight `content` FTS column (bm25 weight 1.0, so a name match always
-  outranks a body-opening-only match) and into the search/embedding text.
-  Secret and env files are never read for it, and session-kind memories
-  (`akm_memory_kind` in outer or nested inner frontmatter) are excluded —
-  their bodies are raw transcripts. Both indexing walks and write-path
-  indexing honor the flag (the metadata pass reads the user config directly).
-  With the flag absent or `false`, entries and search fields stay
-  byte-identical to before. **Costs of toggling (either direction):** indexed
-  text changes, so collapse-detector canary recall baselines shift — re-mint
-  via `akm improve canary --refresh` — and embeddings are NOT regenerated for
-  entries that already have one, while incremental runs re-extract only
-  changed files. Run `akm index --full` after toggling: it re-extracts every
-  entry and wipes embeddings so they rebuild from the new text; until then
-  `akm index` warns that the flag differs from the state the index was built
-  with. The conventions' `description:`/`when_to_use:` orientation routing
-  remains primary — this flag makes body openings additionally pay retrieval
-  rent, it does not replace structured metadata. See `docs/configuration.md`.
+- **One progressive lexical retrieval path and searchable Markdown prose.**
+  FTS now tokenizes Unicode letters/numbers, deduplicates and caps the query,
+  then runs strict AND, prefix-AND, and a single OR/prefix-OR recovery only
+  after both conjunctive forms miss. Every stage keeps the existing BM25 field
+  weights and downstream ranker; callers do not maintain stopword lists or
+  parallel result collections. AKM-native Markdown contributes a normalized,
+  16,384-character body projection through the existing lowest-weight
+  `content` field. Frontmatter, comments, fenced code, and link destinations
+  are removed; secret/env values and raw session/checkpoint bodies never enter
+  the projection. Structured fields remain first in the bounded embedding
+  input, so exact names and metadata continue to dominate body-only matches.
 - **`akm mv <ref> <new-name>` — rename with inbound-xref rewrite and
   utility-history preservation (Experimental).** The stash conventions'
   forced-rename procedure ("grep and fix inbound xrefs in the same pass") was

package/README.md

@@ -16,7 +16,7 @@ assistant, including [Claude Code](https://claude.ai/code),
 
 ## Install
 
-**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 22):**
+**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 24):**
 
 ```sh
 npm install -g akm-cli
@@ -85,6 +85,8 @@ Full docs, CLI reference, and guides are available on [GitHub](https://github.co
 - [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md)
 - [Supported Formats](https://github.com/itlackey/akm/blob/main/docs/reference/supported-formats.md)
 - [CLI Reference](https://github.com/itlackey/akm/blob/main/docs/reference/cli.md)
+- [Task v3 Reference](https://github.com/itlackey/akm/blob/main/docs/reference/tasks.md)
+- [0.9.2 Migration Guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.9.1-to-v0.9.2.md)
 - [Configuration](https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md)
 - [Bundle Authoring Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md)
 - [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md)

package/SECURITY.md

@@ -96,7 +96,7 @@ containing secrets or private notes.
 
 ## Known non-issues
 
-- **The `akm-cli` npm package requires Node.js >= 22 as its bootstrap.** A
+- **The `akm-cli` npm package requires Node.js >= 24 as its bootstrap.** A
   working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old,
   unusable, or absent Bun installations fall back to Node.js. Bun does not
   remove the package's Node.js requirement. Standalone binaries are

package/STABILITY.md

@@ -218,7 +218,7 @@ enumeration of the whole `proposal` noun group.
   | `78` | Configuration error |
 - **Install scripts** — `install.sh` and `install.ps1` URLs; the `--prefix`
   / `AKM_INSTALL_DIR` environment override.
-- **Runtime** — the npm package requires Node.js >= 22 as its bootstrap and
+- **Runtime** — the npm package requires Node.js >= 24 as its bootstrap and
   prefers a working Bun >= 1.0 for execution when both are available; old,
   unusable, or absent Bun installations fall back to Node.js. Standalone
   binaries are runtime-free.

package/dist/akm

@@ -120,8 +120,8 @@ if (contextValid) {
 
   if (!process.versions.bun) {
     const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-    if (major < 22) {
-      console.error("The akm-cli npm package requires Node.js >= 22 to bootstrap.");
+    if (major < 24) {
+      console.error("The akm-cli npm package requires Node.js >= 24 to bootstrap.");
       process.exit(1);
     }
   }

package/dist/akm-migrate

@@ -8,8 +8,8 @@ import { fileURLToPath } from "node:url";
 
 if (!process.versions.bun) {
   const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
-  if (major < 22) {
-    console.error("The akm-cli npm package requires Node.js >= 22 to bootstrap.");
+  if (major < 24) {
+    console.error("The akm-cli npm package requires Node.js >= 24 to bootstrap.");
     process.exit(1);
   }
 }

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

@@ -92,7 +92,7 @@ akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
 akm import https://example.com/docs/auth       # Fetch one URL and import it as knowledge
 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 lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
 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
@@ -160,7 +160,9 @@ akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0  #
 
 ## Workflows
 
-Workflows live under `<bundle>/workflows/` as unified markdown assets.
+Workflows live under `<bundle>/workflows/` as peer `.md` and `.yml` sources.
+Both compile to the same source IR; see `docs/reference/workflow-schema.md` for
+the bounded GitHub-shaped YAML subset.
 
 Ref-based workflow commands are scoped to the current project/worktree/directory,
 so one active run does not block unrelated directories from starting the same
@@ -269,6 +271,7 @@ akm bundle list --kind git                           # Filter by provider (files
 akm bundle remove <target>                           # Remove by id, ref, path, or name
 akm bundle update --all                              # Update all managed sources
 akm bundle update <target> --force                   # Force re-download
+akm bundle update <target> --allow-insecure          # Approve reviewed dangerous env keys
 ```
 
 ## Registries
@@ -336,7 +339,7 @@ akm proposal reject <id> --reason "..."                 # Archive with a reason
 akm proposal revert <id>                                # Restore the pre-promotion content
 akm proposal new <type> <name> --task "..."             # Agent-author a NEW asset as a proposal
 akm proposal extract --auto                             # Mine native session files into proposals
-akm proposal extract --type claude-code                 # Restrict extraction to one harness
+akm proposal extract --type claude                 # Restrict extraction to one harness
 ```
 
 The flat verbs `akm proposals` / `akm show proposal` / `akm accept` /
@@ -353,7 +356,7 @@ file plus one `sync` is a complete workflow.
 
 ```sh
 akm task add nightly-improve --schedule "@daily" --command "akm improve --strategy frequent"
-akm task add briefing --schedule "0 9 * * *" --prompt agents/briefer  # Agent-target task
+akm task add briefing --schedule "0 9 * * *" --prompt "Draft the morning briefing"  # Inline command task
 akm task sync                                  # Reconcile task files with the OS scheduler
 akm task sync --rebind                         # Also re-pin the scheduler's akm binary/spelling
 akm task doctor                                # Scheduler binding + runtime eligibility diagnosis
@@ -362,18 +365,20 @@ akm task run <id>                              # Run one task immediately (works
 akm search --type task                         # Enumerate task assets (there is no `task list`)
 ```
 
-To disable a task, set `enabled: false` in its YAML and run `akm task sync`
+Task files use strict task v3 (`version: 3`). To disable one, set
+`akm.enabled: false` and run `akm task sync`
 (the cron line stays, commented). To remove one, delete the YAML and run
-`akm task sync` — the scheduler entry is unbound. Per-task `timeoutMs` in
-the YAML may be `null` (disable the agent kill timer for long local-model
-runs) or a number of milliseconds overriding the selected engine invocation timeout.
+`akm task sync` — the scheduler entry is unbound. Per-task `akm.timeout` may
+be `null` (disable the invocation timer) or a duration/number overriding the
+selected engine invocation timeout. Preview old task-v2 conversion with
+`akm migrate apply --dry-run`.
 
 ## Agent Dispatch
 
 ```sh
 akm agent --prompt "summarize open proposals"   # Dispatch the configured agent CLI
 akm agent agents/architect --prompt "..."       # Embody a bundle agent asset (system prompt, model, tool policy)
-akm agent --workflow workflows/ship-release     # Load the task from a workflow asset
+akm command run commands/release                # Canonical reusable-command dispatch
 akm agent --model sonnet --prompt "..."         # Model override (aliases or exact IDs)
 ```
 

package/dist/assets/improve-strategies/proactive-maintenance.json

@@ -17,7 +17,7 @@
       "policy": "personal-stash",
       "maxAcceptsPerRun": 100,
       "maxDiffLines": 200,
-      "judgment": {}
+      "judgment": true
     },
     "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 100 }
   },

package/dist/assets/improve-strategies/reflect-distill.json

@@ -22,7 +22,7 @@
       "policy": "personal-stash",
       "maxAcceptsPerRun": 15,
       "maxDiffLines": 200,
-      "judgment": {}
+      "judgment": true
     },
     "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 }
   },

package/dist/assets/models.json

@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "aliases": {
+    "fast": {
+      "claude": "claude-haiku-4-5-20251001",
+      "opencode": "opencode/claude-haiku-4-5",
+      "opencode-sdk": "anthropic/claude-haiku-4-5"
+    },
+    "balanced": {
+      "claude": "claude-sonnet-4-6",
+      "opencode": "opencode/claude-sonnet-4-6",
+      "opencode-sdk": "anthropic/claude-sonnet-4-6"
+    },
+    "reasoning": {
+      "claude": {
+        "model": "claude-opus-4-7",
+        "inference": {
+          "effort": "high"
+        }
+      },
+      "opencode": {
+        "model": "opencode/claude-opus-4-7",
+        "inference": {
+          "effort": "high"
+        }
+      },
+      "opencode-sdk": {
+        "model": "anthropic/claude-opus-4-7",
+        "inference": {
+          "effort": "high"
+        }
+      }
+    }
+  }
+}

package/dist/assets/stash-skeleton/facts/conventions/backlinks.md

@@ -73,10 +73,9 @@ xrefs:
 ## Self-situating headers and canonical naming
 
 Put the one-line orientation in `description:` and the trigger conditions in
-`when_to_use:` — those are indexed fields; body prose is not indexed by
-default (only headings reach the index; the opt-in `index.indexBodyOpening`
-flag adds just the first body paragraph, at the lowest weight —
-`description:`/`when_to_use:` remain the primary orientation channel). Then
+`when_to_use:` — those remain the higher-weight indexed fields. Bounded body
+prose is indexed in the lowest-weight `content` field, so
+`description:`/`when_to_use:` remain the primary orientation channel. Then
 open the body with a plain title plus a one-line
 orientation naming what it is, its scope/domain, and its key entities in
 canonical spelling (`Postgres`, `OAuth`, `TLS`, `Acme`) — the entity/relation

package/dist/assets/stash-skeleton/facts/conventions/organization.md

@@ -86,9 +86,7 @@ cross-project reuse.
   (`acme` vs `acme-corp`) so the prefix does not fragment. Keep the domain
   vocabulary in `facts/conventions/domains`.
 - **Off-axis facets go in `tags:`, not a bare field.** The indexed FTS fields are
-  name, description, tags, hints, and content (headings only — body prose is
-  not indexed by default; the opt-in `index.indexBodyOpening` flag adds just
-  the first body paragraph, at the lowest weight) — there is **no `project`
+  name, description, tags, hints, and bounded low-weight body content — there is **no `project`
   field**, so `project: projectA` in
   frontmatter is invisible to search. Put the off-axis facet in `tags` instead
   (a project-scoped memory adds `tags: [auth]`; a domain-scoped asset genuinely

package/dist/assets/tasks/core/extract.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "*/30 * * * *"
-command: akm proposal extract --auto
-enabled: true
-description: Opt-in all-harness session extraction every 30 min
+version: 3
+run: akm proposal extract --auto
+akm:
+  schedule: "*/30 * * * *"
+  enabled: true
+  description: Opt-in all-harness session extraction every 30 min

package/dist/assets/tasks/core/improve.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "0 2 * * *"
-command: akm improve
-enabled: true
-description: Run improve pipeline nightly
+version: 3
+run: akm improve
+akm:
+  schedule: "0 2 * * *"
+  enabled: true
+  description: Run improve pipeline nightly

package/dist/assets/tasks/core/index-refresh.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "0 4 * * *"
-command: akm index
-enabled: true
-description: Nightly incremental index refresh
+version: 3
+run: akm index
+akm:
+  schedule: "0 4 * * *"
+  enabled: true
+  description: Nightly incremental index refresh

package/dist/assets/tasks/core/sync.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "*/15 * * * *"
-command: akm sync
-enabled: true
-description: Sync stash changes to git remote every 15 min
+version: 3
+run: akm sync
+akm:
+  schedule: "*/15 * * * *"
+  enabled: true
+  description: Sync stash changes to git remote every 15 min

package/dist/assets/tasks/core/version-check.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "0 9 * * 1"
-command: akm upgrade --check
-enabled: true
-description: Weekly check for new akm releases
+version: 3
+run: akm upgrade --check
+akm:
+  schedule: "0 9 * * 1"
+  enabled: true
+  description: Weekly check for new akm releases

package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "10 3 * * 0"
-command: akm improve --strategy graph-refresh --skip-if-locked
-enabled: true
-description: Full-corpus graph rebuild (weekly Sunday 3:10am)
+version: 3
+run: akm improve --strategy graph-refresh --skip-if-locked
+akm:
+  schedule: "10 3 * * 0"
+  enabled: true
+  description: Full-corpus graph rebuild (weekly Sunday 3:10am)

package/dist/assets/tasks/improve/akm-improve-catchup.yml

@@ -1,8 +1,9 @@
-version: 2
-schedule: "0 4 * * *"
-command: akm improve --strategy catchup --skip-if-locked
+version: 3
+run: akm improve --strategy catchup --skip-if-locked
+akm:
+  schedule: "0 4 * * *"
 # Manual-recovery task: ships disabled (the retired registerDefaultTasks
 # marked it enableMode: "manual"). `akm task run` works while disabled;
 # opting into the schedule is `enabled: true` + `akm task sync`.
-enabled: false
-description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)
+  enabled: false
+  description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "20 */4 * * *"
-command: akm improve --strategy consolidate --skip-if-locked
-enabled: true
-description: Consolidation-only pass (every 4h at :20)
+version: 3
+run: akm improve --strategy consolidate --skip-if-locked
+akm:
+  schedule: "20 */4 * * *"
+  enabled: true
+  description: Consolidation-only pass (every 4h at :20)

package/dist/assets/tasks/improve/akm-improve-frequent.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "40 * * * *"
-command: akm improve --strategy frequent --skip-if-locked
-enabled: true
-description: Frequent inference pass (hourly at :40; improve-stage extract off)
+version: 3
+run: akm improve --strategy frequent --skip-if-locked
+akm:
+  schedule: "40 * * * *"
+  enabled: true
+  description: Frequent inference pass (hourly at :40; improve-stage extract off)

package/dist/assets/tasks/improve/akm-improve-nightly.yml

@@ -1,5 +1,6 @@
-version: 2
-schedule: "15 2 * * *"
-command: akm improve --strategy thorough --skip-if-locked
-enabled: true
-description: Full nightly quality sweep (daily 2:15am; suggested for server installs)
+version: 3
+run: akm improve --strategy thorough --skip-if-locked
+akm:
+  schedule: "15 2 * * *"
+  enabled: true
+  description: Full nightly quality sweep (daily 2:15am; suggested for server installs)

package/dist/cli/confirm.js

@@ -32,8 +32,8 @@
  *
  * ## Safety exemptions
  *
- * `--quiet` NEVER suppresses the confirmation prompt — it is safety-critical
- * output. The auto-migration banner is similarly exempt from `--quiet`.
+ * `--quiet` NEVER suppresses the confirmation prompt because it is
+ * safety-critical output.
  */
 import { UsageError } from "../core/errors.js";
 import * as p from "./clack.js";

package/dist/cli/parse-args.js

@@ -45,9 +45,9 @@ export function parsePositiveIntFlag(raw, flagName = "--limit") {
     const trimmed = raw.trim();
     if (!trimmed)
         return undefined;
-    // Strict digits, matching parseNonNegativeIntFlag below. parseInt stops at the
-    // first non-digit, so "10x" silently became 10, "3.5" became 3, and
-    // "5 apples" became 5 — accepted rather than rejected as invalid.
+    // Strict digits: parseInt stops at the first non-digit, so "10x" silently
+    // became 10, "3.5" became 3, and "5 apples" became 5 — accepted rather than
+    // rejected as invalid.
     if (!/^\d+$/.test(trimmed)) {
         throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
     }
@@ -57,27 +57,6 @@ export function parsePositiveIntFlag(raw, flagName = "--limit") {
     }
     return parsed;
 }
-/**
- * Parse a non-negative integer flag value (0 is allowed, unlike `parsePositiveIntFlag`).
- *
- * Returns `undefined` when `raw` is `undefined` or empty (flag not supplied).
- * Throws `UsageError` when the raw value is present but not a valid non-negative
- * integer (e.g. contains decimals, letters, or is negative).
- *
- * @param raw       The raw string value (may be undefined).
- * @param flagName  The flag name to include in the error message.
- */
-export function parseNonNegativeIntFlag(raw, flagName) {
-    if (raw === undefined)
-        return undefined;
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return undefined;
-    if (!/^\d+$/.test(trimmed)) {
-        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a non-negative integer.`, "INVALID_FLAG_VALUE");
-    }
-    return parseInt(trimmed, 10);
-}
 // ── String flag parsing ──────────────────────────────────────────────────────
 /**
  * Extract a string value from a parsed citty argument object by key.

package/dist/cli/retired-commands.js

@@ -45,7 +45,7 @@ const RETIRED_COMMAND_HINTS = {
     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.",
+    backup: "`akm backup` was removed in 0.9 — stop writers and archive current config, data, state, and writable bundles with your normal backup tooling.",
     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.",

package/dist/cli/shared.js

@@ -172,8 +172,8 @@ export const GLOBAL_OUTPUT_ARGS = {
         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.",
+            "Safety-critical output is never suppressed: errors and destructive-action confirmation prompts " +
+            "always appear regardless of --quiet.",
         default: false,
     },
     verbose: {