akm-cli 0.9.8 → 0.9.9-beta.1

package/dist/tasks/backends/cron.js

@@ -21,7 +21,11 @@
 //     `LOGNAME`/`USER` only). The cron line uses an absolute akm path
 //     resolved at install time so it doesn't rely on the inherited PATH.
 //   • BSD `crontab -l` returns exit 1 with "no crontab for <user>" on a
-//     fresh user; we treat that as an empty crontab rather than an error.
+//     fresh user; a supercronic-managed PATH shim (#910, e.g. OpenPalm's
+//     `/tmp/openpalm-bin/crontab` before any spool exists) does the same
+//     with empty stdout instead. Both mean "empty crontab", not "broken
+//     install" — only a genuinely missing binary (ENOENT from the spawn
+//     itself) gets the "install crontab" remedy.
 //
 // Tests inject a fake exec so unit tests don't touch the real crontab.
 import { spawnSync } from "node:child_process";
@@ -480,12 +484,21 @@ function readCrontab(exec) {
     const result = exec.read();
     if (result.status === 0)
         return result.stdout ?? "";
-    // BSD crontab returns 1 with "no crontab for <user>" on stderr — treat as empty.
-    if (/no crontab for/i.test(result.stderr ?? ""))
-        return "";
-    if (/no crontab/i.test(result.stdout ?? ""))
+    // The spawn itself failed to find the binary (ENOENT) — this is the only
+    // case where "install/PATH the crontab binary" is the correct remedy.
+    if (result.enoent) {
+        throw new ConfigError("crontab -l failed: the `crontab` binary was not found on PATH.", "INVALID_CONFIG_FILE", "Install the `crontab` binary (e.g. cron/cronie/vixie-cron) or add one to PATH.");
+    }
+    // #910: a nonzero exit that says nothing at all, or whose stderr says
+    // "no crontab" (BSD's "no crontab for <user>"; a supercronic-managed PATH
+    // shim like OpenPalm's before any spool exists), is cron's own contract
+    // for "empty crontab" — not evidence the binary is missing or broken. A
+    // nonzero exit that DID say something else (a permission refusal) is
+    // reported as what it said, below.
+    const stderr = (result.stderr ?? "").trim();
+    if (((result.stdout ?? "").trim() === "" && stderr === "") || /no crontab/i.test(stderr))
         return "";
-    throw new ConfigError(`crontab -l failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "Ensure the `crontab` binary is on PATH and your shell can read the user crontab.");
+    throw new ConfigError(`crontab -l failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "The `crontab` binary ran but did not report success; check its output above.");
 }
 function writeCrontab(exec, content) {
     const normalised = content.endsWith("\n") || content.length === 0 ? content : `${content}\n`;
@@ -517,6 +530,7 @@ function defaultCronExec() {
                 status: r.status ?? 1,
                 stdout: r.stdout ?? "",
                 stderr: r.stderr ?? "",
+                enoent: r.error?.code === "ENOENT",
             };
         },
         write(content) {
@@ -525,6 +539,7 @@ function defaultCronExec() {
                 status: r.status ?? 1,
                 stdout: r.stdout ?? "",
                 stderr: r.stderr ?? "",
+                enoent: r.error?.code === "ENOENT",
             };
         },
     };

package/dist/tasks/resolve-akm-bin.js

@@ -159,7 +159,7 @@ function samePath(left, right) {
 // once-only flag) so a differently-invoked probe later in the same process
 // still gets its own answer instead of a stale one.
 let cachedNpmGlobalRoot;
-function resolveNpmGlobalRoot(nodePath, env) {
+export function resolveNpmGlobalRoot(nodePath, env) {
     if (cachedNpmGlobalRoot && cachedNpmGlobalRoot.nodePath === nodePath) {
         return cachedNpmGlobalRoot.value;
     }

package/docs/README.md

@@ -41,6 +41,7 @@ Package complete capabilities and turn knowledge into repeatable work.
 - [Bundle Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it so others can install it with `akm bundle add`
 - [Author's Guide: Writing Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md) -- Write and test a workflow definition, from a minimal example to gates and outputs
 - [Claude Code workflows vs. akm workflows](https://github.com/itlackey/akm/blob/main/docs/guides/claude-code-vs-akm-workflows.md) -- Short decision guide for choosing between a session-native workflow and an akm workflow ([full technical comparison](https://github.com/itlackey/akm/blob/main/docs/architecture/comparisons/claude-code-vs-akm-workflows-full.md))
+- [Bundling akm](integration/bundling-akm.md) -- Ship akm inside your own product: the pin/migrate/health boot contract, plan JSON shapes, and exit codes for bundlers
 
 ### Maintainers
 

package/docs/integration/bundling-akm.md

@@ -0,0 +1,276 @@
+# Bundling akm
+
+This is for anyone shipping `akm` inside their own product: a Docker image, a
+plugin whose `node_modules` carries its own akm, or any other install a human
+never runs `akm setup` inside. It says exactly what to call at boot and what
+each call's JSON means — nothing about akm's internals you don't need.
+
+## The contract
+
+Three lines cover it:
+
+1. **Pin** an exact `akm-cli` version and install it however you install
+   things (npm, the standalone binary, a `node_modules` dependency).
+2. **At boot, run `akm migrate apply`** (or `akm upgrade`, which runs it).
+   It is offline, idempotent, needs no root, takes its own safety copies,
+   prints one JSON plan, and exits `0` unless a file is genuinely blocked.
+3. **Read `akm health --format json`.** Never grep error text — akm's
+   wording is not a stable interface; the JSON fields are.
+
+Everything below is detail in service of those three lines.
+
+## `akm migrate apply`
+
+```sh
+akm migrate status        # read-only: what would change
+akm migrate apply --dry-run
+akm migrate apply
+```
+
+In order, every run applies (or, under `status`/`--dry-run`, plans):
+
+1. **Legacy config lift** — `extraParams` keys on an engine config moved onto
+   first-class fields.
+2. **Pending `state.db` migrations**, historical-destructive ones included.
+   This is the only path (besides `akm upgrade`, which calls the same code)
+   that is allowed to apply a destructive migration to an existing,
+   unversioned or behind-generation `state.db` — see
+   [One-way state.db](#one-way-note-statedb-migrations-are-one-way) below.
+3. **Task sources**: task-v2 files to task v3, then task-v3 files to task
+   source v4. Each generation keeps its own lock and backup, so a file
+   blocked in one generation does not stop the other from converting files
+   that are already current.
+4. **Stash residue sweeps**: superseded pre-0.9.0 `.akm` files and stale
+   filesystem transactions, scoped to the configured bundle (skipped
+   entirely when no bundle is configured yet).
+
+### The plan JSON
+
+One JSON object on stdout, always. A current install, nothing to do:
+
+```json
+{
+  "schemaVersion": 1,
+  "status": "current",
+  "blockers": [],
+  "configExtraParams": { "applied": false, "lifted": [], "conflicts": [] },
+  "stateMigrations": { "pending": [] },
+  "taskV3Migration": { "schemaVersion": 1, "generation": "task-v2-to-v3", "changed": 0, "skipped": 4, "blocked": 0, "files": [] },
+  "taskV4Migration": { "schemaVersion": 1, "generation": "task-v3-to-v4", "changed": 0, "skipped": 4, "blocked": 0, "files": [] }
+}
+```
+
+`akm migrate status` against a tree with one blocked task file (`taskV3Migration`
+omitted below for brevity — its shape is identical):
+
+```json
+{
+  "schemaVersion": 1,
+  "status": "blocked",
+  "blockers": ["with-on-non-command-target"],
+  "stateMigrations": { "pending": [] },
+  "taskV4Migration": {
+    "schemaVersion": 1,
+    "generation": "task-v3-to-v4",
+    "changed": 3,
+    "skipped": 1,
+    "blocked": 1,
+    "files": [
+      {
+        "filePath": "tasks/nightly.yml",
+        "status": "blocked",
+        "reason": "with-on-non-command-target",
+        "beforeHash": "…"
+      }
+    ]
+  }
+}
+```
+
+`status` is one of:
+
+- **`current`** — no task-source file needs converting, and no config
+  extraParams lift is pending. A no-op boot.
+- **`ready`** — task sources have eligible changes and no config-lift
+  conflict; a real `apply` will clear them.
+- **`blocked`** — at least one item cannot be applied automatically (a
+  genuine authoring problem, e.g. a task file the migrator can't rewrite
+  unambiguously, or a config `extraParams` value that conflicts with its
+  first-class field). `blockers` names each one. `apply` still applies
+  everything it *can*, then reports `blocked` and exits non-zero.
+
+A pending `state.db` migration needs no human decision, so it is never
+`blocked`: under `akm migrate status` or `apply --dry-run` it reads as
+`ready` (the run would change `state.db`) and is listed in
+`stateMigrations.pending`; a real `apply` always applies it.
+
+Key fields:
+
+| Field | Meaning |
+| --- | --- |
+| `stateMigrations` | `{ pending: string[] }` under `status`/`--dry-run`; `{ applied: string[], safetyCopyPath?: string }` after a real `apply`. `safetyCopyPath` is present only when a historical-destructive migration ran — see below. |
+| `taskV3Migration` / `taskV4Migration` | Per-generation summary: `changed`/`skipped`/`blocked` counts and a `files[]` array with each file's `status` and `reason`. |
+| `backupPath` / `taskV4BackupPath` | Present after a real apply that changed at least one file in that generation — a timestamped snapshot directory. |
+| `deadResidue` / `staleTxns` | Present only when a bundle is configured. `{ pending: [...] }` under a read-only run, `{ removed: [...] }` / `{ recovered: [...] }` after apply. |
+
+**Backups and their retention:**
+
+- Task-source backups (task-v2→v3 and v3→v4) go to
+  `<dataDir>/backups/task-v3/<timestamp>-<uuid>/` and
+  `<dataDir>/backups/task-v4/<timestamp>-<uuid>/` respectively — one
+  directory per apply run, pruned to the **5 most recent** automatically.
+- Config backups go to `<cacheDir>/config-backups/config-<ISO-ts>.json`,
+  also capped at **5**.
+- A `state.db` historical-destructive migration writes a verified sibling
+  snapshot next to `state.db` itself:
+  `state.db.pre-<migrationId>.<UTC-digits>.<UUID>.bak`. This one is **never
+  auto-pruned** — it is a one-time, rare event (a single destructive ledger
+  boundary), so clean it up yourself once you've confirmed the upgrade, if
+  disk space matters to your image.
+
+**Exit codes:**
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | `current` or `ready`-and-applied — nothing left to do. |
+| `1` | `blocked` — at least one item needs a human. |
+| anything else | A crash, not a migration outcome: `{"ok":false,"error":"...","code"?:"...","hint"?:"..."}` on stderr, with the exit code from akm's normal error-classification table (`2` usage, `70` internal, `78` config). |
+
+**Idempotency:** re-running `apply` against a `current` database/tree is a
+no-op — safe to put in every boot, every time, on every replica.
+
+**Offline, no root:** every step reads and writes files/SQLite it already
+owns under your configured `$DATA`/`$CACHE`/bundle directories. Nothing here
+touches the network or needs elevated privileges.
+
+## `akm upgrade` in a bundled install
+
+```sh
+akm upgrade              # install a newer release if there is one, then migrate
+akm upgrade --check      # check for updates only — no install, no migration step
+```
+
+`akm upgrade` always runs the migration step after its install step — on
+install success, on install failure, and when there was nothing to install.
+Its result carries the same plan under `migration`:
+
+```json
+{
+  "currentVersion": "0.9.8",
+  "newVersion": "0.9.9",
+  "upgraded": false,
+  "installMethod": "package-local",
+  "message": "akm runs as a dependency of the package at /opt/myapp; upgrade that package to move akm.",
+  "migration": { "schemaVersion": 1, "status": "current", "blockers": [], "stateMigrations": { "pending": [] } }
+}
+```
+
+**`installMethod: "package-local"`** is the detection that matters for a
+bundler: an `akm` living inside *another* package's `node_modules` (your
+image's `tools/` dependency, a plugin's own `node_modules/akm-cli`) is never
+`npm install -g`'d over — that would silently diverge from the copy the
+parent package actually executes. akm reports `upgraded: false` and names the
+parent package to upgrade instead; **its migrations still run**, exactly as
+in every other install method. `installMethod` is one of `"binary"`,
+`"bun"`, `"npm"`, `"pnpm"`, `"package-local"`, or `"unknown"`.
+
+**Exit code:** `akm upgrade` exits `1` when `migration.status` is `"blocked"`
+or `"failed"`, even if the install itself succeeded — an upgrade whose
+migration didn't finish is not done. This makes plain `akm upgrade` (no
+flags) a safe, idempotent container entrypoint step on every boot: on an
+already-current install with nothing pending it is a fast no-op that exits 0.
+
+**`--check`** skips the migration step entirely — it only compares versions
+and reports `updateAvailable`. Use it for a version-drift alert, not as your
+boot check.
+
+## `akm health`
+
+```sh
+akm health --format json
+```
+
+Read the JSON. Never parse the human-readable text or grep for a phrase —
+that wording is not a stable interface.
+
+**Exit codes:** `0` (`status: "pass"`), `4` (`status: "warn"`), `1`
+(`status: "fail"`).
+
+The check that replaces grepping akm's refusal text is a **hard check**
+named `state-db-migrations`:
+
+```json
+{
+  "name": "state-db-migrations",
+  "status": "fail",
+  "message": "1 pending state.db migration(s) (018-drop-dead-lane-schema); run `akm migrate apply`.",
+  "evidence": { "path": "/data/akm/state.db", "pending": ["018-drop-dead-lane-schema"] }
+}
+```
+
+It reads `evidence.pending` — a read-only preflight, never the managed open
+— so `akm health` can report this state even though **an ordinary command
+that opens `state.db` refuses to touch a pending historical-destructive
+migration by design**, naming `akm upgrade` and `akm migrate apply` as the
+only two commands allowed to apply one. Before this check existed, that
+refusal surfaced as a crash (config-error exit) instead of a normal `fail`
+row — this is what a bundler should now watch for `state-db-migrations` to
+report, instead of grepping error text for a fixed remedy string.
+
+## The `akm-migrate` executable
+
+`akm-migrate` is the second `bin` entry the `akm-cli` npm package installs
+(`akm` and `akm-migrate` side by side), and it is also embedded directly in
+the compiled standalone binary — a release binary re-execs itself internally
+to reach it, so it needs no separate download. Same surface either way:
+
+```sh
+akm-migrate status
+akm-migrate apply --dry-run
+akm-migrate apply
+```
+
+`akm migrate status`/`apply` (under the `akm` CLI) are a thin wrapper over
+this same executable — same plan, same exit codes. Reach for `akm-migrate`
+directly when you don't want `akm`'s `--format`/`--shape`/`--detail` output
+handling in the way, e.g. a shell script that just wants the raw JSON line
+on stdout and a plain exit code.
+
+## Container entrypoint sketch
+
+```sh
+#!/bin/sh
+set -e
+akm --version                 # optional: confirm the pinned version actually landed
+akm migrate apply             # offline, idempotent — exits 1 only if genuinely blocked
+akm task sync --rebind        # only if you schedule akm tasks inside this image
+akm health --format json      # read this JSON; act on ok/status, never on message text
+```
+
+### Environment variables
+
+A bundler that controls the filesystem layout should set these explicitly
+rather than rely on `$HOME`-derived defaults (names verified against
+`src/core/paths.ts` and `src/tasks/scheduler-invocation.ts`):
+
+| Variable | What it points at |
+| --- | --- |
+| `AKM_BUNDLE_DIR` | The content bundle (`$STASH`) — assets akm indexes and serves. |
+| `AKM_CONFIG_DIR` | `config.json`'s directory. |
+| `AKM_DATA_DIR` | Durable, non-regenerable data: **`index.db` and `state.db` live here.** This is the directory a migration snapshot's safety copy sits beside. |
+| `AKM_CACHE_DIR` | Regenerable cache: registry downloads, config backups, task logs. Safe to discard between image builds (not between boots of the same running install). |
+| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory used for scheduled-task invocation context and companion-plugin hook state (Claude Code / OpenCode hook logs). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
+
+Set all five to paths that persist across container restarts (a mounted
+volume), or `akm migrate apply` will see an empty `state.db` on every boot
+and never actually converge.
+
+## One-way note: `state.db` migrations are one-way
+
+Once a migration has run against `state.db`, an **older** akm binary that
+later opens the same file refuses it outright — the migration ledger moved
+forward, and there is no downgrade path. If you need the ability to roll
+back a bundled akm version, take your own backup of the whole data directory
+(`$AKM_DATA_DIR`) before running `akm upgrade`/`akm migrate apply` — the
+per-migration safety copy described above exists to protect that one
+destructive step, not as a general rollback mechanism for your deployment.

package/docs/migration/v0.9.0-troubleshooting.md

@@ -18,23 +18,19 @@ Managed current databases apply exact-prefix additive schema migrations
 automatically. Released migration 002's `task_history` table rebuild is also
 automatic and preserves every existing row. Released migration 018 is the
 exception: it removes retired dead-lane state, so an ordinary command stops
-before that migration and tells you to run:
+before that migration and tells you to run either of:
 
 ```sh
-akm upgrade --force
+akm upgrade        # applies pending state migrations first, then installs if a release is newer
+akm migrate apply  # applies them alongside the task-source and config migrations
 ```
 
-Where akm cannot reinstall itself — a container that ships the CLI globally,
-an unprivileged runtime user — that command fails at its install step
-(`EACCES` on the global module directory) before it ever reaches the
-migration. Use the install-free route instead:
-
-```sh
-akm upgrade --state-only
-```
-
-Both admit migration 018 and both take the same verified safety copy described
-below; `--state-only` simply skips the executable replacement. Immediately before
+Both run on an already-current install and never need an install to reach
+the migration, so either is safe as a container entrypoint: on a current
+database the step is a no-op. `akm upgrade` installs a newer release first
+when there is one, then runs `akm-migrate apply` — the migrator that shipped
+with whatever is now installed; `akm migrate apply` is that step without the
+release check. Immediately before
 the migration, AKM takes a SQLite writer-exclusion lock, rechecks the exact
 ledger, and writes a consistent SQLite snapshot beside the database as
 `state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak`. The randomized
@@ -51,7 +47,7 @@ general storage migrator.
 
 An existing database with no applied migration IDs is never treated as a fresh
 install, whether its `schema_migrations` table is absent or empty. Ordinary
-commands reject it without writing. The explicit `akm upgrade --force` (or `--state-only`) path
+commands reject it without writing. The explicit `akm upgrade` / `akm migrate apply` path
 takes and verifies a descriptor-bound snapshot named
 `state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak` before it creates the
 ledger or applies any migration from 001 through 022. A truly new database is

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -13,12 +13,14 @@ steps; no run data is lost.
 The released 0.9.1 state ledger already includes historical migration 018, so
 the normal 0.9.1→0.9.2 database step is additive and automatic. If a pre-release
 database has an exact prefix before 018, ordinary commands stop before its
-destructive dead-lane cleanup. Run `akm upgrade --force`; after successful
-executable replacement AKM creates and verifies a sibling pre-018 SQLite safety
-copy before applying that immutable released migration. Its locked ledger
-recheck, snapshot, and migration share one writer-exclusion window, so another
-WAL writer cannot commit between the copy and 018. Unknown or divergent ledgers
-remain unsupported.
+destructive dead-lane cleanup. Run `akm migrate apply` (or `akm upgrade`, which
+runs it after its install step regardless of whether an install happened): AKM
+creates and verifies a sibling pre-018 SQLite safety copy before applying that
+immutable released migration. Its locked ledger recheck, snapshot, and
+migration share one writer-exclusion window, so another WAL writer cannot
+commit between the copy and 018. Unknown or divergent ledgers remain
+unsupported. See [Bundling akm](../integration/bundling-akm.md) for the full
+migration contract.
 
 ## Before you upgrade
 
@@ -250,16 +252,10 @@ Common blocked reasons and what to do about each:
 | `read-only-source` | The owning source or file is not writable. | Move or re-source the file somewhere writable, or edit it by hand. |
 | `invalid-v3-task` | The v3 document itself is structurally invalid (unknown fields, missing selector, malformed trigger, etc). | Fix the underlying v3 document first — the migrator translates structure, it does not repair it. |
 
-If you only want to run this generation in isolation (for example, your
-tree is already all `version: 3` and you want to preview just this step),
-the frozen migrator's standalone entry points remain available as a
-separate executable, installed alongside `akm`:
-
-```sh
-akm-migrate task-v4-status
-akm-migrate task-v4-apply --dry-run
-akm-migrate task-v4-apply
-```
+The migrator is also installed as its own executable, `akm-migrate`, with the
+same `status` / `apply [--dry-run]` surface as `akm migrate`. A tree that is
+already all `version: 3` simply reports the first generation as current and
+runs this one.
 
 ## Task history result vocabulary (`target.kind`)
 

package/docs/reference/cli.md

@@ -282,7 +282,7 @@ Primary result fields:
 | Field | Description |
 | --- | --- |
 | `status` | Overall health verdict: `pass`, `warn`, or `fail` |
-| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `task-log-backing`, `active-runs`, `default-engine`, and `model-map-files` |
+| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, and `model-map-files` |
 | `advisories` | Non-fatal warnings including `semantic-search-runtime` and `session-extraction` (akmExtract pipeline health) |
 | `metrics` | Aggregate task/runtime metrics: `taskFailRate`, `agentFailureRate`, `stuckActiveRuns`, `logBackingRate`, `probeRoundTripMs` |
 | `improve` | Recent improve-loop counts derived from `improve_invoked`, `improve_skipped`, and `improve_completed` events |
@@ -292,6 +292,14 @@ memory-prune actions, memory-inference writes, graph-extraction refreshes,
 session-extraction outcomes (`sessionsScanned`, `sessionsExtracted`, `proposalsCreated`),
 dead-URL detections, and skip reasons observed in the selected time window.
 
+`state-db-migrations` reports whether `state.db`'s migration ledger has any
+pending entries (checked read-only, without applying anything). It `fail`s
+when migrations are pending — naming them and pointing at `akm migrate apply`
+— rather than the command crashing, which is what happens when `state.db`
+holds a pending historical-destructive migration and something other than
+`akm upgrade` / `akm migrate apply` opens it directly. Read this check's
+`status` instead of grepping akm's error text for that case.
+
 The `session-extraction` advisory reflects the health of the `akmExtract` pipeline
 (Phase 0.4 of `akm improve`). It warns on harness errors or when no proposals are
 generated across five or more scanned sessions.
@@ -1010,33 +1018,45 @@ Upgrade `akm` itself to the latest release. Standalone binaries are downloaded,
 checksummed, and staged before replacement; npm, Bun, and pnpm global installs
 use their package manager.
 
-Upgrade replaces the installed program and then rebuilds the derived index.
-It does not run legacy config, database, or workflow migration paths. Standalone
-downloads use a temporary rollback copy only during atomic executable replacement.
+Upgrade replaces the installed program when a newer release exists, then runs
+`akm-migrate apply` — the migrator that shipped with whatever is now installed
+— and rebuilds the derived index. The migration step runs on every
+`akm upgrade`, install or no install, and its plan is reported under
+`migration`; an upgrade whose migration is blocked or could not run exits 1.
+That makes `akm upgrade` safe as a container entrypoint: on a current
+installation it is a no-op. An akm installed as a dependency of another
+package (`installMethod: "package-local"`) is never reinstalled — the parent
+package owns that copy — but its migrations still run. Standalone downloads
+use a temporary rollback copy only during atomic executable replacement.
 
 Standalone downloads are streamed directly to the staged file while SHA-256 is
 computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 1 MiB; an oversized response is cancelled and the staged file is removed.
 
 ```sh
-akm upgrade              # Download and replace the running binary
-akm upgrade --check      # Check for updates without installing
-akm upgrade --force      # Force upgrade even if already on latest
-akm upgrade --state-only # Apply pending state.db migrations; install nothing
+akm upgrade              # Install a newer release if there is one, then run every pending migration
+akm upgrade --check      # Check for updates without installing (no migration step)
+akm upgrade --force      # Force the install even if already on latest
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--check` | Check for updates without installing |
 | `--force` | Force upgrade even if on latest version |
-| `--state-only` | Apply pending `state.db` migrations without installing a new akm. For installs that cannot rewrite their own binary — a container shipping akm globally, an unprivileged runtime user — where the install step would fail `EACCES` before the migration could run. Takes the same verified safety copy as `--force`; it changes who may request the migration, not what it does. |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
 
+Offline, or to migrate without a release check, run `akm migrate apply`
+directly: it is the same step.
+
 Checksum verification is not optional and has no flag. If a release's
 `checksums.txt` is genuinely unreachable, the recovery hatch is the
 `AKM_UPGRADE_SKIP_CHECKSUM=1` environment variable (Internal — deliberately
 not a discoverable, tab-completable flag). See STABILITY.md.
 
+Shipping akm inside your own product (a Docker image, a plugin's own
+`node_modules`)? See [Bundling akm](../integration/bundling-akm.md) for the
+full boot contract, JSON shapes, and exit codes.
+
 ### clone
 
 Copy an asset from any source into a managed writable bundle or an unmanaged
@@ -1440,33 +1460,41 @@ akm registry remove my-team --yes    # Skip the confirmation prompt
 
 ### migrate
 
-Inspect or apply the explicit, one-way conversion of on-disk task sources to
-task source v4, the only grammar normal task execution accepts. `akm migrate`
-runs **both** migration generations in one pass — task-v2 to task-v3, then
-task-v3 to task source v4 against the resulting files — each keeping its own
-lock, backup, prevalidation, and rollback, so a file blocked in the first
-generation does not stop the second generation from converting files that are
-already `version: 3`. Database schema upgrades are additive and run
-automatically when `state.db` opens; config and workflow formats have no
-runtime compatibility migrator.
+Inspect or apply every pending migration in one plan. `akm migrate` is a thin
+wrapper over the standalone `akm-migrate` executable (installed alongside
+`akm`, and embedded in the release binary), which owns every historical shape
+akm has ever written so the CLI proper reads only current schemas. The steps,
+in order:
+
+1. legacy config `extraParams` keys lifted onto first-class engine fields
+   (`configExtraParams`);
+2. pending `state.db` migrations, historical-destructive ones included, with
+   a verified sibling safety copy (`stateMigrations`) — the only path besides
+   `akm upgrade` that admits released migration 018, which an ordinary
+   command refuses;
+3. task-v2 files to task v3, then task-v3 files to task source v4
+   (`taskV3Migration`, `taskV4Migration`), each keeping its own lock, backup,
+   prevalidation, and rollback, so a file blocked in the first generation does
+   not stop the second from converting files already at `version: 3`;
+4. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
+   (`deadResidue`, `staleTxns`).
 
 ```sh
 akm migrate status
 akm migrate apply --dry-run
 akm migrate apply
-```
-
-`status` and `apply --dry-run` are read-only. Apply refuses blocked task
-sources, backs up each changed file immediately before replacement, and
-atomically publishes strict task source v4 YAML; it is idempotent per
-generation, skipping a file already at that generation's target version
-(`already-v3`, `already-v4`). To run only the second generation in isolation
-(for example, previewing just the v3-to-v4 step against a tree that is
-already all `version: 3`), the frozen migrator's standalone entry points
-remain available as a separate executable: `akm-migrate task-v4-status` /
-`akm-migrate task-v4-apply [--dry-run]`. See [Tasks: Migrating to task
-source v4](tasks.md#migrating-to-task-source-v4) for the full blocked-reason
-table and worked examples.
+akm-migrate apply          # the same, without the akm wrapper
+```
+
+`status` and `apply --dry-run` are read-only. Apply skips blocked task
+sources rather than failing (and exits 1 while any remain), backs up each
+changed file immediately before replacement, and atomically publishes strict
+task source v4 YAML; it is idempotent, so a current installation is a no-op.
+`akm upgrade` runs `apply` after its install step. See [Tasks: Migrating to
+task source v4](tasks.md#migrating-to-task-source-v4) for the full
+blocked-reason table and worked examples, and
+[Bundling akm](../integration/bundling-akm.md) for the plan JSON shape and
+how to drive this from a container/image boot step.
 
 ### config
 

package/docs/reference/tasks.md

@@ -371,16 +371,10 @@ Two cases produce one today:
   v4 task is runnable manually with `akm task run` whether or not it has a
   `schedule:`. The migrated document simply has no `schedule:` key.
 
-If you only want to run one generation in isolation (for example, your
-tree is already all `version: 3` and you want to preview just the v4 step),
-the frozen migrator's standalone, single-generation entry points remain
-available as a separate executable:
-
-```sh
-akm-migrate task-v4-status
-akm-migrate task-v4-apply --dry-run
-akm-migrate task-v4-apply
-```
+The migrator is also installed as its own executable, `akm-migrate`, with the
+same `status` / `apply [--dry-run]` surface; `akm migrate` wraps it, and
+`akm upgrade` runs `apply` after installing a release. A tree that is already
+all `version: 3` simply reports the first generation as current.
 
 See the [0.9.1 to 0.9.2 migration guide](../migration/v0.9.1-to-v0.9.2.md#migrating-task-v3-to-task-source-v4)
 for full before/after examples and recovery guidance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.8",
+  "version": "0.9.9-beta.1",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -51,6 +51,7 @@
     "docs/migration/v0.8-to-v0.9.md",
     "docs/migration/v0.9.0-troubleshooting.md",
     "docs/migration/v0.9.1-to-v0.9.2.md",
+    "docs/integration/bundling-akm.md",
     "docs/reference/bundle-types.md",
     "docs/reference/cli.md",
     "docs/reference/configuration.md",