akm-cli 0.9.0-rc.8 → 0.9.0

package/docs/migration/v0.8-to-v0.9.md

@@ -1,10 +1,14 @@
 # Migrating from akm 0.8.x to 0.9.0
 
 0.9.0 is the format-neutral **bundle / adapter** refactor. It replaces the flat
-asset-type registry with per-format adapters, adopts one canonical ref grammar,
-consolidates the durable databases and config, and completes several 0.8-era
-deprecations (the CLI aliases and the `vault` asset type). This guide is
-ordered the way you'll need it:
+asset-type registry with per-format adapters for *recognition, indexing,
+presentation, and validation* — placement alone still routes through AKM's
+native type→directory table; wiring it through the adapter interface is
+deferred to 0.10 (see [Removed surfaces](#3-removed-surfaces) and the 0.9.0
+release notes for the exact boundary) — adopts one canonical ref grammar,
+consolidates the durable databases and config, and completes several
+0.8-era deprecations (the CLI aliases and the `vault` asset type). This
+guide is ordered the way you'll need it:
 
 > **Heads-up on the 0.9.x series:** 0.9.x is a refactoring and clean-up
 > series — patch releases may include further breaking changes (each with a
@@ -20,11 +24,14 @@ ordered the way you'll need it:
 5. [Troubleshooting](#5-troubleshooting)
 
 The durable-state re-key, database merge, and config migration are handled by
-the journaled, crash-resumable `akm migrate apply` coordinator. It also rewrites
+the crash-resumable `akm migrate apply` coordinator. It also rewrites
 legacy `workflow:` target refs in valid 0.8 task files after resolving them
 against their containing/configured bundle while preserving each YAML file's
 permission mode; it does not translate profile-based configuration or workflow
-definitions automatically. Create the recovery backup
+definitions automatically — a 0.8 workflow document keeps its 0.8 structure
+verbatim and needs a manual rewrite (see
+[0.8 workflow assets after migration](#08-workflow-assets-after-migration) for
+the concrete symptom and the fix). Create the recovery backup
 before changing a live installation, then migrate other affected assets deliberately.
 
 ## 1. Cross the boundary: `akm migrate status` / `akm migrate apply`
@@ -45,15 +52,22 @@ It:
 - Folds the former `workflow.db` into `state.db`, taking the database count
   from four to three: `state.db` (durable workspace state), `index.db` (the
   fully regenerable search cache), and a separate `logs.db`.
-- Folds `.stash.json` sidecars into the new layout and applies the D-R6
-  reserved-filename renames (`index.md` / `log.md` at any bundle depth are now
-  reserved structural files — see [§2](#2-ref-grammar-typename--bundleconceptid)).
+- Folds `.stash.json` sidecars into the new layout and applies the AKM adapter's
+  D-R6 reserved-filename renames (`index.md` / `log.md` at any AKM stash depth
+  are now reserved structural files — see
+  [§2](#2-ref-grammar-typename--bundleconceptid)).
 - Imports any pre-0.9 filesystem proposals into `state.db` as part of the same
   apply — this is no longer a separate step.
 - Re-keys every durable ref (usage/feedback events, proposal targets,
   workflow/task targets, salience) to the new `[bundle//]conceptId` spelling.
   Refs embedded in your own asset bodies are rewritten by the content
-  migration; unresolvable refs are quarantined, not dropped.
+  migration; unresolvable refs are quarantined, not dropped: the audit summary
+  lands in `legacy_state` (surface, ref, row count) and the complete original
+  rows are preserved as JSON in `legacy_state_rows` in the migrated
+  `state.db`, so nothing the migration cannot re-key is destroyed.
+- Generates the target config for you when no `--config` is given and none
+  exists yet, instead of requiring one hand-authored from a blank page — see
+  [Auto-generating the 0.9 config](#auto-generating-the-09-config).
 
 ### The 0.8 binary cannot do this
 
@@ -63,8 +77,18 @@ The 0.8 binary does not contain `akm migrate` or the `upgrade
 package-manager/manual boundary procedure instead:
 
 1. Stop AKM writers, schedulers, and workflow drivers.
-2. Prepare the complete 0.9 config in a separate file. Do not replace the live
-   0.8 config; AKM cannot infer names when old LLM and agent profiles collide.
+2. Decide how the 0.9 target config gets prepared. You usually don't need to
+   hand-write one: `akm migrate apply` (step 5) generates the mechanical part
+   — `bundles`/`defaultBundle` — from your existing `stashDir`/`sources[]`/
+   `installed[]` automatically when no `--config` is given and no target
+   config exists yet (see
+   [Auto-generating the 0.9 config](#auto-generating-the-09-config) below).
+   Write one by hand instead (see
+   [Preparing the 0.9 config](#preparing-the-09-config)) only if you want full
+   control, or already know your 0.8 config configured LLM/agent profiles —
+   AKM never guesses those. Either way, never replace the live 0.8 config
+   directly; a generated or hand-written target config always lives in a
+   separate file.
 3. Take an independent filesystem backup of the live 0.8 `config.json`,
    `state.db`, and `workflow.db` (including any SQLite `-wal`/`-shm` files).
    Store it outside AKM's data directory and verify it before continuing.
@@ -74,10 +98,188 @@ package-manager/manual boundary procedure instead:
    independent data backup in either case.
 5. Invoke the newly installed or staged 0.9 binary, whose migration startup
    bypass can read the old installation without loading its config normally.
-6. After apply succeeds, run `akm tasks sync` with that same 0.9 binary and
-   inspect `skipped` before restarting schedulers. Sync registers the migrated
-   task view and quarantines the obsolete published backup task described in
-   [§4](#4-behavioral-notes).
+6. After apply succeeds, run `akm task sync --rebind` with that same 0.9 binary
+   before restarting schedulers. The explicit rebind replaces 0.8 native
+   scheduler definitions with current context-bound invocations.
+
+### Auto-generating the 0.9 config
+
+Run `akm migrate status` (or `akm migrate apply`) with **no** `--config`. If
+the active 0.8 config still carries `stashDir`/`sources[]`/`installed[]` and no
+target config exists yet, the plan's `generatedConfig` field previews what a
+`migrate apply` will write: `path` (a predictable location next to the
+migration's recovery backups — never the live `config.json`) and
+`droppedKeys` — any `profiles.llm.<name>`/`profiles.agent.<name>`/
+`profiles.improve.<name>`/`defaults.llm`/`defaults.agent`/`defaults.improve`
+keys it will leave out, named exactly rather than guessed at (see
+[Engine And Task Assets](#engine-and-task-assets) for why).
+
+A `migrate apply` with no `--config` and no target config yet WRITES that
+file and stops — it deliberately does not proceed to back up or mutate
+anything on that run, so you get a real chance to review the generated
+config (and hand-add `engines`/`defaults` for anything `droppedKeys` named)
+before a second, explicit `akm migrate apply` — still no `--config` — picks
+the file up and completes the cutover:
+
+```sh
+akm migrate status   # previews: generatedConfig.status "pending", droppedKeys []
+akm migrate apply    # writes the starter config, stops (status "ready")
+# review/edit the file named in the JSON result's generatedConfig.path if
+# droppedKeys named anything you need engines for, then:
+akm migrate apply    # picks up the generated file, applies it (status "current")
+```
+
+The generated file's `bundles`/`defaultBundle` come from the exact same
+transform (`migrateConfigSourcesToBundles`) [the key-mapping table
+below](#08-key--09-key) describes for a hand-written target — generation just
+runs it for you. When your 0.8 config had no `profiles`/`defaults.llm`/
+`defaults.agent`/`defaults.improve` to translate, `droppedKeys` comes back
+empty and the generated config is complete on its own: the second `apply` is
+a plain confirming re-run, no editing required.
+
+An explicit `--config` always wins over this and is never second-guessed — if
+you pass one, generation never runs, exactly as if this section did not
+exist. Use it for full control, or when you already know your 0.8 config
+configured LLM/agent profiles and would rather write `engines`/`defaults`
+yourself up front instead of re-running `apply` a second time.
+
+### Preparing the 0.9 config
+
+A 0.9 config is a plain JSON file; nothing stops you from writing one
+yourself instead of letting `migrate apply` generate it (see above) — you
+still point `--config` at it exactly as before. This is the minimum that is
+sufficient to drive a successful `akm migrate apply`: one writable bundle and
+a `defaultBundle` naming it.
+
+```json
+{
+  "configVersion": "0.9.0",
+  "bundles": {
+    "primary": { "path": "/abs/path/to/your/stash", "writable": true }
+  },
+  "defaultBundle": "primary"
+}
+```
+
+Point `path` at the same directory your 0.8 `stashDir` used — that is what
+turns your existing assets into the migrated installation's working bundle. If
+your 0.8 config also had `sources[]` or `installed[]` entries, add one
+`bundles` entry per source (see the mapping table below); each one becomes
+searchable the same way it was in 0.8.
+
+If your 0.8 config configured LLM or agent profiles, add `engines` and
+`defaults` too:
+
+```jsonc
+{
+  "configVersion": "0.9.0",
+  "bundles": {
+    "primary": { "path": "/abs/path/to/your/stash", "writable": true }
+  },
+  "defaultBundle": "primary",
+  "engines": {
+    "fast": {
+      "kind": "llm",
+      "endpoint": "http://localhost:11434/v1/chat/completions",
+      "model": "qwen3"
+    },
+    "reviewer": { "kind": "agent", "platform": "opencode" }
+  },
+  "defaults": {
+    "engine": "reviewer",
+    "llmEngine": "fast"
+  }
+}
+```
+
+This is a minimal illustration, not the full schema — see
+[Configuration](../reference/configuration.md) for every `engines`/`defaults`/
+`improve.strategies` field, and point your editor's JSON schema support at
+`$schema: "https://itlackey.github.io/akm/schemas/akm-config.json"` (or the
+local `schemas/akm-config.json` in a source checkout) for autocomplete and
+inline validation while you write it.
+
+#### 0.8 key → 0.9 key
+
+Verified against `scripts/akm-migrate/migrate/legacy/config-source-migration.ts`
+(the transform `akm migrate apply` runs on your behalf once you give it a
+target config that already speaks the 0.9 shape) and
+`src/core/config/config-walker.ts`'s retired-key hints:
+
+| 0.8 key | 0.9 key | Notes |
+| --- | --- | --- |
+| `stashDir` | `bundles.<id>.path` + `defaultBundle` | The `primary: true` source (or the top-level `stashDir` if none was marked primary) becomes the bundle named by `defaultBundle` |
+| `sources[]` | `bundles` | One `bundles.<id>` entry per source; `id` is derived from the source's `name`/`registryId` or a slug of its path |
+| `installed[]` | `bundles` + lockfile | The config entry keeps only the desired locator (`git`/`npm` + `registryId`); the materialized cache path and revision move to the lockfile, not the config |
+| `wikiName` | (gone — no replacement) | The wiki subsystem was removed in 0.9; a Karpathy-style wiki is recognized automatically as an `llm-wiki` bundle, and ordinary content goes through `akm import` |
+| `profiles.llm.<name>` / `defaults.llm` | `engines.<name>` (`kind: "llm"`) / `defaults.llmEngine` | Not migrated automatically — you choose the new engine names |
+| `profiles.agent.<name>` / `defaults.agent` | `engines.<name>` (`kind: "agent"`) / `defaults.engine` | Not migrated automatically — see the name-collision note below |
+| `profiles.improve.<name>` / `defaults.improve` | `improve.strategies.<name>` / `defaults.improveStrategy` | Not migrated automatically |
+
+The engine/task-asset keys are **not** translated to `engines`/`defaults` by
+`migrate apply` — see [Engine And Task Assets](#engine-and-task-assets) below
+for why AKM cannot safely auto-generate `engines` names when a 0.8 LLM
+profile and agent profile shared one. In a hand-written target config passed
+via `--config`, leaving these keys in is a hard schema-validation error (same
+as before 0.9.0's config generation existed) — [Preparing the 0.9
+config](#preparing-the-09-config) above never touches them for you. The
+auto-generation path ([above](#auto-generating-the-09-config)) instead
+actively STRIPS them and reports exactly what it stripped via
+`generatedConfig.droppedKeys`, so the config it writes is valid on its own;
+either way, you still add `engines`/`defaults` by hand afterward if you want
+LLM/agent execution to keep working. Everything else in the table above
+(bundles, defaultBundle, `wikiName` removal) *is* handled — by `migrate apply`
+once you hand it a target config, or by the generator on your behalf —
+`migrate apply` moves the durable state and databases, not the config keys
+themselves.
+
+#### End-to-end happy path
+
+The complete sequence, in the order you actually hit it, assuming a single
+0.8 `stashDir` and no LLM/agent profiles to carry over — letting `migrate
+apply` generate the target config instead of hand-writing one:
+
+```sh
+# 1. Stop schedulers and any running akm process first (see step 1 above).
+
+# 2. Back up the live 0.8 data directory independently (outside AKM's own dirs).
+cp -a ~/.local/share/akm ~/akm-0.8-backup-"$(date +%Y%m%d)"
+
+# 3. Install 0.9.
+npm install -g akm-cli@0.9.0
+
+# 4. Check eligibility (previews the config apply would generate), then apply
+#    TWICE: the first apply only writes the generated config and stops; the
+#    second, unchanged, invocation picks it up and performs the cutover.
+akm migrate status
+akm migrate apply --dry-run
+akm migrate apply
+akm migrate apply
+
+# 5. Rebind the scheduler to the new binary and rebuild the index.
+akm task sync --rebind
+akm index
+akm migrate status   # now reports current with no --config needed
+```
+
+If your 0.8 config configured LLM/agent profiles, or you'd simply rather
+write the target config yourself, replace step 4 with the hand-authored
+`--config` form instead:
+
+```sh
+# 4'. Write the target config (see the minimal example above), then check
+#     eligibility, dry-run, and apply against it explicitly.
+cat > ./prepared-0.9.json << 'EOF'
+{
+  "configVersion": "0.9.0",
+  "bundles": { "primary": { "path": "/home/you/akm", "writable": true } },
+  "defaultBundle": "primary"
+}
+EOF
+akm migrate status --config ./prepared-0.9.json
+akm migrate apply --config ./prepared-0.9.json --dry-run
+akm migrate apply --config ./prepared-0.9.json
+```
 
 Package-manager installation examples for step 4:
 
@@ -96,51 +298,30 @@ Commands for steps 5 and 6:
 akm migrate status --config ./prepared-0.9.json
 akm migrate apply --config ./prepared-0.9.json --dry-run
 akm migrate apply --config ./prepared-0.9.json
-akm tasks sync
+akm task sync --rebind
 
 # Or invoke a checksummed staged standalone binary explicitly.
 ./akm-0.9 migrate status --config ./prepared-0.9.json
 ./akm-0.9 migrate apply --config ./prepared-0.9.json
-./akm-0.9 tasks sync
+./akm-0.9 task sync --rebind
 ```
 
 Status and dry-run perform the same read-only eligibility checks and report the
 source config plus target config explicitly. Apply validates the target in
-memory, creates a verified recovery run, applies pending `state.db` and
-`workflow.db` migrations one transaction at a time, and atomically installs the
-prepared config last. If any later artifact fails, apply restores config and
-both databases from the verified run before returning. Each artifact is
-classified independently, so a current config with pre-cutover databases can be
-recovered safely.
-
-Apply records durable `prepared`, `state-converting`, `state-collapsing`,
-`state-applied`, `workflow-applied`, `cutover-applied`, `config-applied`, `tasks-prepared`, `tasks-applied`,
-`pilot-prepared`, `pilot-applied`, `rollback-prepared`, and `committed` phases. Every phase stores
-streaming size/SHA fingerprints for config, both databases, and SQLite sidecars;
-a pre-cutover resume or rollback first requires the exact live generation.
-State schema migration and the `state-converting` marker commit together; the
-marker binds a canonical logical digest before the journal records the exact
-physical `state-collapsing` generation. A marker-write crash is recoverable only
-when that digest still matches. Once the journal is bound, any later WAL frame
-fails closed; a nonexact generation is accepted only after the raw database
-header proves the WAL-to-DELETE collapse completed and the logical digest still
-matches. After a process
-crash, ordinary config and canonical database access fail closed; `akm migrate
-status` reports the pending phase and `akm migrate apply` resumes idempotently
-from the retained target and verified backup. Apply also refuses before backup
-while managed database handles, maintenance activities, AKM mutation locks, or
-workflow claims are live.
-
-Format-v2 journals written by an earlier 0.9 RC at `state-applied` or
-`workflow-applied` are authenticated by raw artifact fingerprints before AKM
-opens live SQLite files. An exact journal is durably rewound through
-`state-converting`; a nonexact journal fails closed without probing WAL state.
-Earlier format-v2 journals at `cutover-applied` or any later forward-only phase
-are instead authenticated by the same operation's committed cutover ledger row.
-They continue from their recorded phase without requiring the newer
-`state-converting` marker; physical WAL differences are retained rather than
-rolled back. A post-cutover journal without that operation-bound marker fails
-closed.
+memory and creates a verified recovery run. Before the first mutation it writes
+one phase-free incomplete sentinel containing the retained target, path base,
+and original backup identity. It then applies schema changes by ordered
+migration ID, runs the data and asset transforms idempotently, and atomically
+installs the prepared config last.
+
+If a transform fails, apply does not guess at rollback and does not replace the
+original backup. It leaves the incomplete sentinel in place, ordinary config
+and canonical database access fail closed, and the next `akm migrate apply`
+replays the same transforms to convergence. The transaction-local cutover
+ledger prevents duplicate workflow or usage-event imports. The sentinel is
+removed only after final config, schema, task, proposal-ref, and cutover outcome
+checks pass. Apply also refuses before backup while managed database handles,
+maintenance activities, AKM mutation locks, or workflow claims are live.
 
 Once already running a contract-capable 0.9 release, future self-upgrades may
 pass a prepared target through the coordinated upgrade path:
@@ -159,12 +340,61 @@ no migration-config flag is needed.
 
 Recovery runs are stored under
 `$DATA/backups/migrations/<installation-id>/<run-id>/`. They record present and
-absent `config.json`, `state.db`, and `workflow.db` artifacts, ordered migration
-ledgers, sizes, and streaming SHA-256 hashes. SQLite snapshots must also pass
+absent `config.json`, `state.db`, `workflow.db`, and `index.db` artifacts,
+ordered migration ledgers, and semantic state. SQLite snapshots must pass
 `PRAGMA quick_check` and ledger-prefix validation before the manifest is
-published. `akm backup create --for 0.9.0` creates an additional unique run when
-an operator wants a manual snapshot. Routine config writes, telemetry, and
-already-current database opens do not depend on any historical run.
+published. `akm-migrate backup
+--for 0.9.0` creates an additional unique run when an operator wants a manual
+snapshot. Routine config writes, telemetry, and already-current database opens
+do not depend on any historical run.
+
+### What migration control does not cover
+
+Migration control tracks exactly four artifacts — `config.json`, `state.db`,
+`workflow.db`, `index.db` — because that is the literal list the backup/restore
+manifest enumerates. Two boundaries follow from that list that are worth
+stating plainly rather than discovering by accident:
+
+- **`logs.db` is entirely outside the migration system.** It is never backed
+  up, never restored, and never version-checked; `src/core/logs-db.ts`
+  bootstraps its own schema the first time it is opened, independent of the
+  migration coordinator. This is fine in practice — task and index logs are
+  purgeable operational data, not state you need a rollback path for — but it
+  means an `akm-migrate restore` rolls back `config.json`, `state.db`,
+  `workflow.db`, and `index.db` to a prior run while `logs.db` is left exactly
+  as the newer binary wrote it. Do not expect `logs.db` to move with a
+  restore.
+- **`index.db` is only checked with `PRAGMA quick_check`**, never inspected
+  for a schema/migration version the way `state.db` and `workflow.db` are. A
+  `index.db` written by a release newer than the one currently running cannot
+  be detected as "newer" — the runtime instead quarantines and rebuilds it
+  from scratch on the next `akm index`. This is safe because the index is a
+  fully regenerable search cache; it is called out here only so "migration
+  status: current" is not read as "index.db is exactly what this binary
+  expects."
+
+### Two different `migrate` surfaces
+
+`akm migrate` — the subcommand on the everyday `akm` binary — exposes only
+`status` and `apply`: the two commands you need to cross the boundary and to
+check or apply any future in-place migration. It does **not** expose `backup`,
+`restore`, or `storage`.
+
+The standalone `akm-migrate` program (`scripts/akm-migrate.ts` in a source
+checkout; shipped as its own `dist/akm-migrate` release artifact — see the
+`bin` entry in `package.json`) is a separate binary with a larger surface:
+`status`, `apply`, `backup`, `restore`, and `storage`. `backup` and `restore`
+exist **only** here — there is no `akm migrate restore`. If your install does
+not ship `akm-migrate` (some minimal or hand-rolled installs omit it), you have
+no restore path from that install; every `akm-migrate restore ...` /
+`akm-migrate backup ...` command in this guide and in
+[the troubleshooting guide](v0.9.0-troubleshooting.md) refers to that separate
+binary, not the `akm migrate` subcommand.
+
+There is also no `plan` subcommand on either surface. What some other tools
+call "planning" is `akm migrate status` (read-only eligibility check) or
+`akm migrate apply --dry-run` (the same transforms, run without writing) — do
+not look for a separate plan step.
 
 ## 2. Ref grammar: `type:name` → `[bundle//]conceptId`
 
@@ -187,18 +417,19 @@ Before / after:
 
 **There is no compatibility parser.** The pre-0.9.0 `[origin//]type:name`
 grammar is removed from every normal code path; it survives only inside the
-migrator (`src/migrate/legacy-ref-grammar.ts`) for reading pre-cutover data.
+migrator (`scripts/akm-migrate/migrate/legacy-ref-grammar.ts`) for reading
+pre-cutover data.
 `akm migrate apply` re-keys every durable ref to the new spelling, and refs
 embedded in your own asset bodies are rewritten by the content migration — but
 any prompt, `AGENTS.md`, or doc that still spells refs in the old `type:name`
 form must be updated by hand. A code-review skill is now `skills/code-review`.
 See `STABILITY.md` for the full contract.
 
-`index.md` and `log.md` are also now reserved. Per the Open Knowledge Format,
-these are directory/structure files at every bundle depth — never indexed as
-concepts and never valid write / `akm mv` targets. Existing stash files with
-those names are excluded from the index (and renamed by the content migration
-if they hold a real concept).
+`index.md` and `log.md` are also now reserved by the AKM adapter at every stash
+depth — never indexed as items and never valid item-write targets. This matches
+OKF's structural names but is an AKM format rule, not an assertion that the
+stash is an OKF bundle. Existing stash files with those names are excluded from
+the index and renamed by the content migration if they hold a real item.
 
 ## 3. Removed surfaces
 
@@ -206,17 +437,32 @@ if they hold a real concept).
 
 0.9.0 removes the entire `akm wiki` verb family (`create`, `register`, `list`,
 `show`, `remove`, `pages`, `search`, `stash`, `lint`, `ingest`) and the `wiki`
-asset type. The Karpathy-style LLM wiki structure stays first-class, but as a
-**bundle format** owned by the `llm-wiki` adapter instead of a bespoke command
-surface: `schema.md` (the per-wiki rulebook) + `pages/` (agent-authored pages)
-at a bundle's root is enough for the indexer to recognize and lint it like any
-other bundle. `raw/`, `index.md`, and `log.md` stay reserved infrastructure.
+asset type. The Karpathy-style LLM wiki structure stays first-class for
+*reading*, now as a **bundle format** recognized by the `llm-wiki` adapter
+instead of a bespoke command surface: `schema.md` (the per-wiki rulebook) +
+`pages/` (agent-authored pages) at a bundle's root is enough for the indexer
+to recognize it, index its pages, and present them through `akm show`.
+`raw/`, `index.md`, and `log.md` stay reserved infrastructure.
+
+**llm-wiki is consumer/read-only for writes in 0.9.0, the same as OKF.** The
+adapter defines its own `validate` and `placeNew` logic. Validation is
+adapter-driven in 0.9.0: `akm lint` runs the `llm-wiki` adapter's own
+wiki-shaped checks through `validate()` rather than falling back to the
+generic AKM subdirectory scan. Placement is not — nothing in the write path
+calls `placeNew()` yet for any adapter, llm-wiki included; that wiring is
+deferred to 0.10 (see
+[D12 in the 0.9.0 decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)).
+Separately, `akm remember`/`akm import`/proposal-accept into an llm-wiki
+bundle are rejected before they reach the adapter at all — the same
+`assertAkmAssetWrite` allowlist that rejects OKF targets, unrelated to the
+`placeNew` deferral. Author llm-wiki content through your agent writing
+directly into `pages/` (as the Karpathy pattern always intended), not
+through akm's native write commands.
 
 There is no `akm wiki ...` compatibility shim — an installed non-akm wiki
 directory reclassifies under the `llm-wiki` adapter on your next `akm index`
 (see [adapter dispatch reclassification](#4-behavioral-notes)); wiki pages are
-found through `akm search`/`akm show` like any other asset, and lint runs
-through `akm lint`.
+found through `akm search`/`akm show` like any other asset.
 
 ### `akm vault` → `env` / `secret`
 
@@ -225,10 +471,10 @@ asset type, shipped in 0.8.0 alongside a deprecation shim and an automatic
 `vaults/` → `env/` migration. This section explains what changed, how to
 migrate, and what 0.9.0 removes.
 
-> **TL;DR:** In 0.8.0, run the migration (`akm-migrate-storage --yes`) to copy
+> **TL;DR:** In 0.8.0, run the migration (`akm-migrate storage --yes`) to copy
 > `vaults/` → `env/`, then switch your scripts from `akm vault …` to
 > `akm env …` and from `source "$(akm vault path …)"` to
-> `akm env run env:<name> -- <command>` (or `-- $SHELL` for an interactive
+> `akm env run <name> -- <command>` (or `-- $SHELL` for an interactive
 > session). Everything keeps working through 0.8.x; the `vault` verb and
 > `vault:` refs are removed in 0.9.0.
 
@@ -284,13 +530,13 @@ move**: the legacy `vaults/` tree is left intact as a frozen copy and a
 
 ```sh
 # Preview (no changes written)
-akm-migrate-storage --dry-run
+akm-migrate storage --dry-run
 
 # Apply
-akm-migrate-storage --yes
+akm-migrate storage --yes
 
 # From a source clone:
-bun scripts/migrate-storage.ts --yes
+bun scripts/akm-migrate.ts storage --yes
 ```
 
 What the `vaults/ → env/` step does:
@@ -316,7 +562,7 @@ After migrating, run `akm index` to refresh search so entries surface under
 
 ```sh
 # List
-akm vault list                          →  akm env list
+akm vault list                          →  akm env list  # doclint:ignore (left side is the removed 0.8.x `vault` verb — this is the "Before" of the mapping)
 
 # Inspect keys (values never shown)
 akm show vault:prod                     →  akm show env/prod
@@ -325,14 +571,14 @@ akm show vault:prod                     →  akm show env/prod
 source "$(akm vault path vault:prod)"   →  akm env run prod -- $SHELL
 
 # Run a command with the env injected
-akm vault run vault:prod -- ./deploy.sh →  akm env run prod -- ./deploy.sh
+akm vault run vault:prod -- ./deploy.sh →  akm env run prod -- ./deploy.sh  # doclint:ignore (left side is the removed 0.8.x `vault` verb — this is the "Before" of the mapping)
 
 # Create / ingest an existing .env
-akm vault create prod                   →  akm env create prod
+akm vault create prod                   →  akm env create prod  # doclint:ignore (left side is the removed 0.8.x `vault` verb — this is the "Before" of the mapping)
                                             # or: akm env create prod --from-file ./.env
 
 # Edit (akm no longer manages entries)
-akm vault set vault:prod DB_URL         →  $EDITOR "$(akm env path prod --quiet)"
+akm vault set vault:prod DB_URL         →  $EDITOR "$(akm env path prod --quiet)"  # doclint:ignore (left side is the removed 0.8.x `vault` verb — this is the "Before" of the mapping)
                                             # or: akm secret set db-url
 ```
 
@@ -376,8 +622,8 @@ is a security-relevant behaviour change.
 
 - The entire `akm vault` verb and its subcommands.
 - The `vault:` ref alias. Parsing a `vault:` ref now fails immediately with:
-  `The \`vault\` asset type was removed in 0.9.0 — use \`env:\` (whole .env
-  config) or \`secret:\` (a single value).`
+  `The \`vault\` asset type was removed in 0.9.0 — use \`env/\` (whole .env
+  config) or \`secrets/\` (a single value).`
 - The `vault` asset-spec entry, renderer (`vault-env`), and the `vault_access`
   audit-event alias.
 - The frozen `vaults/` directory is deleted **only** after explicit per-path
@@ -390,25 +636,21 @@ idiom before upgrading to 0.9.0.
 
 Because 0.9.0 removed the `vault` asset type, the indexer **no longer scans
 `vaults/` at all**. If you jumped from 0.7/0.8 to 0.9.0 and never ran
-`akm-migrate-storage`, the `.env` data still sitting in `vaults/` was never
+`akm-migrate storage`, the `.env` data still sitting in `vaults/` was never
 copied to `env/` and will **not** appear under `env/…` — it is silently
 un-indexed (the files themselves are untouched on disk).
 
-To make this non-silent, 0.9.0 adds a **one-time, read-only guard**: whenever
-`akm index` (or any auto-index path) runs against a stash whose `vaults/`
-directory holds `.env` files but has no `vaults/.migrated` marker, akm prints a
-single warning pointing here and at `akm-migrate-storage`. The guard never
-reads secret contents, and never writes, moves, or deletes anything — it only
-detects the un-migrated state. The fix is the same idempotent, non-destructive
-command as on 0.8:
+The 0.9 runtime does not inspect the retired `vaults/` tree. Use the standalone
+migration tool to detect and copy any remaining files; it owns the
+`vaults/.migrated` marker and remains idempotent and non-destructive:
 
 ```sh
-akm-migrate-storage --yes   # copies vaults/ -> env/, leaving vaults/ intact
-akm index                   # refresh search so entries surface under env:
+akm-migrate storage --yes   # copies vaults/ -> env/, leaving vaults/ intact
+akm index                   # refresh search so entries surface under env/
 ```
 
 The `vaults/ → env/` migration step still ships in 0.9.0's
-`akm-migrate-storage` (it is part of the `0.8 → 0.9` migration) precisely so a
+`akm-migrate storage` (it is part of the `0.8 → 0.9` migration) precisely so a
 late migration on a 0.9.0 install still works.
 
 #### Verifying the migration
@@ -418,7 +660,7 @@ late migration on a 0.9.0 install still works.
 akm env list
 
 # The frozen copy + marker are present
-ls -la "$(akm info --format=json | jq -r .stashDir)/vaults/.migrated"
+ls -la "$(akm info --format=json | jq -r .bundleDir)/vaults/.migrated"
 
 # Values still never leak
 akm show env/prod          # key names only
@@ -431,17 +673,15 @@ The migration is non-destructive — `vaults/` is untouched. To roll back, delet
 the generated `env/` directory and remove the `vaults/.migrated` marker, then
 downgrade akm. Because `env/` is a copy, no data is lost either way.
 
-### `--auto-accept` on `akm improve` — deprecated and ignored
+### Removed `--auto-accept` on `akm improve`
 
 The 0.9.0 confidence gate `--auto-accept` used to configure was deleted:
 proposals now queue for review (`akm proposal` / the drain engine) instead of
-being auto-promoted by threshold. The flag is accepted but ignored for one
-minor release — installed crontabs embed the old command line, and a hard
-parse error would make scheduled background runs fail invisibly after upgrade.
-Any present value (bare flag, `safe`, `false`, a number, garbage) prints one
-deprecation warning on stderr and never throws. It will be a hard error in
-0.10. Drop `--auto-accept` from your task definitions and scripts now; see
-[proposal triage](#4-behavioral-notes) for its replacement.
+being auto-promoted by threshold. Through 0.9.x, `--auto-accept` is accepted
+only as a compatibility flag: akm warns that it is removed and ignored, and
+discards a space-separated value. Remove it from task definitions and scripts;
+it becomes a hard error in 0.10. See [proposal triage](#4-behavioral-notes) for
+the explicit replacement.
 
 ### Retired `--wiki` flag
 
@@ -460,6 +700,44 @@ budget). There is no replacement flag — retrieval-count signal still feeds
 ranking, just not through a dedicated eligibility fallback. Drop the flag from
 any scripted `akm improve` invocations.
 
+### `akm mv` → move the file, then `akm index`
+
+0.9.0 removes `akm mv` outright — no alias, no stub; `akm mv …` fails with the
+standard unknown-command error. A rename **is** delete plus create in akm's
+identity model (see [`STABILITY.md`](../../STABILITY.md) § Renames), and the
+command's inbound-ref rewrite matched bare conceptIds rather than anchored
+`bundle//conceptId` refs, so it could edit ordinary prose while leaving real
+refs dangling. The supported procedure is three steps you can see the results
+of:
+
+```sh
+mv ~/akm/memories/projectA/old-note.md ~/akm/memories/projectA/new-note.md
+akm index   # the new path is indexed; the old entry drops out
+akm lint    # reports every inbound ref the rename left dangling
+```
+
+Fix the refs `akm lint` reports (its `missing-ref` check covers body prose and
+the frontmatter xref channels) and re-run `akm lint` until it is clean.
+Cross-bundle movement is copy/import plus delete — never identity-preserving.
+
+**Optional: carry the ranking signal over.** The destination gets a fresh
+identity, so its accumulated signal — feedback, usage events, salience and
+outcome history — stays keyed to the old ref and is eventually collected as
+orphan rows. If the asset has earned history worth keeping, run the re-key
+script from a source clone **before** `akm index`:
+
+```sh
+mv ~/akm/memories/projectA/old-note.md ~/akm/memories/projectA/new-note.md
+bun scripts/rekey-asset-ref.ts memories/projectA/old-note memories/projectA/new-note
+akm index && akm lint
+```
+
+Add `--dry-run` to see the row counts it would move. It refuses if both files
+exist (that is a copy, not a rename), and it is idempotent — a second run
+reports zero changed rows. See
+[the 0.9.0 troubleshooting guide](v0.9.0-troubleshooting.md) for the symptom
+this fixes after the fact.
+
 ## 4. Behavioral notes
 
 ### Adapter dispatch reclassification (installed non-akm bundles)
@@ -473,18 +751,63 @@ regenerable cache and rebuilds itself — but searches or saved refs into those
 bundles may resolve to the new spellings afterwards. Reindex with `akm index`
 right after the cutover so this settles before you rely on saved refs.
 
+### 0.8 workflow assets after migration
+
+A workflow document created by 0.8's own `akm workflow create` used
+heading-based steps (`## Step name` sections). 0.9.0 requires the step graph
+in frontmatter (`steps:`) instead — see
+[Ref grammar](#2-ref-grammar-typename--bundleconceptid) for the related
+`index.md`/`log.md` reservation, and the workflow authoring reference for the
+current shape. `migrate apply` does not rewrite workflow *definitions* (only
+`workflow:` target refs inside task files), so a 0.8-authored workflow
+document keeps its 0.8 heading structure verbatim after migration.
+
+The concrete end state, if you leave such a document unconverted:
+
+- `akm lint` reports structural validation errors against it (missing
+  frontmatter `steps:`, plus one error per heading that no longer matches a
+  declared step id).
+- It is **not indexed** as a workflow: `akm search --type workflow` and
+  `akm show <ref>` will not find it.
+- Any run already started against it before the upgrade is unaffected by the
+  document rewrite and **stays `active`** — 0.9 does not silently fail or
+  auto-close it — and pollutes unrelated `akm show` output for other assets
+  with a `WORKFLOW ACTIVE` banner (workflow status is looked up by target,
+  not by whether the definition still validates).
+
+Fix either by rewriting the asset with a frontmatter `steps:` list (see the
+workflow reference for the schema, or run `akm workflow create --print` for a
+fresh template to copy the shape from), or, if the run is no longer wanted, by
+retiring it explicitly:
+
+```sh
+akm workflow list --active     # find the stale run-id
+akm workflow abandon <run-id>  # marks it failed; resume can still reopen it
+```
+
+`akm workflow abandon` only changes the run's status — it does not touch the
+workflow document. Rewrite the document separately if you want the asset
+itself to lint clean and be searchable again.
+
 ### `env`/`secret` writes now honor `--target` / `defaultWriteTarget`
 
 Previously, `env create`/`set`/`unset`/`remove` and `secret set`/`remove`
 selected a write destination independently of `--target` and
 `defaultWriteTarget`, ignoring writability and git commit boundaries. 0.9.0
-routes these mutations through the same `resolveWriteTarget` selection every
-other write command uses: explicit `--target` wins, else `defaultWriteTarget`,
-else the working stash — and a non-writable target is refused. A git-backed
-writable target now lands the change in the same batch-at-boundary commit as
-any other write (see [below](#single-batch-at-boundary-git-commit)). Reads
-(`env run`/`show`/`list`/`path`/`export`, `secret run`/`path`/`list`) are
-unaffected — they still search every configured source.
+routes the surviving mutating subcommands (`env create`/`remove`, `secret
+set`) through the same `resolveWriteTarget` selection every other write
+command uses: explicit `--target` wins, else `defaultWriteTarget`, else the
+working stash — and a non-writable target is refused. A git-backed writable
+target now lands the change in the same batch-at-boundary commit as any other
+write (see [below](#single-batch-at-boundary-git-commit)). Reads (`env
+run`/`list`/`path`/`export`, `secret run`/`list`) are unaffected — they still
+search every configured source.
+
+`env set`/`env unset` and `secret path`/`secret remove` are not merely
+unaffected — they no longer exist in 0.9.0 (see the
+[CLI rename table](#cli-surface-overhaul-rename-table-090-hard-break) and
+[`akm secret`'s removal note](../reference/cli.md#secret) for why `secret
+path`/`secret remove` specifically were dropped rather than fixed).
 
 ### LLM enrichment concurrency defaults
 
@@ -493,8 +816,9 @@ configured LLM endpoint instead of always assuming a remote API: a **local**
 endpoint (`localhost`/`127.0.0.1`/`::1`/`*.localhost`) defaults to
 **concurrency 1** (a single loaded model; parallel requests trigger reload
 thrash), and a **remote** endpoint defaults to **concurrency 2** (enough to
-overlap request latency without hammering rate-limited APIs). Set
-`llm.concurrency` in `config.json` to override either default explicitly.
+overlap request latency without hammering rate-limited APIs).
+`engines.<name>.concurrency` does not currently affect indexing enrichment;
+it does cap frozen workflow fan-out.
 
 ### CLI rename table (old → new, removed 0.9.0)
 
@@ -504,7 +828,7 @@ spellings entirely — there is no delegation, and using one is a usage error.
 
 | Old spelling (0.8, deprecated) | Canonical (use this) | Notes |
 | --- | --- | --- |
-| `akm proposals` | `akm proposal list` | bare `akm proposal` also lists |
+| `akm proposals` | `akm proposal list` | bare `akm proposal` is now a usage error (exit 2) |
 | `akm show proposal <id>` | `akm proposal show <id>` | |
 | `akm diff <id>` | `akm proposal diff <id>` | |
 | `akm accept <id>` | `akm proposal accept <id>` | |
@@ -513,17 +837,72 @@ spellings entirely — there is no delegation, and using one is a usage error.
 | `--detail summary` | `--shape summary` | `--detail` is now verbosity only (`brief\|normal\|full`) |
 | `--detail agent` | `--shape agent` | |
 | `--for-agent` | `--shape agent` | |
-| `--source` (on `accept`/`reject`/`history`) | `--generator` | unchanged on `search`/`curate`/`graph`/`remember` |
+| `--source` (on `accept`/`reject`/`history`) | `--generator` | `search`/`curate`'s `--source` was separately replaced by `--from` in the 0.9.0 surface overhaul (see below); `remember`'s `--source` is a distinct memory-tagging field, not renamed; `graph` was removed in 0.9.0 |
 | `akm save` | `akm sync` | `sync` = commit + optional push; adds `--no-push` |
-| `akm enable <component>` | `akm config enable <component>` | |
-| `akm disable <component>` | `akm config disable <component>` | |
+| `akm enable <component>` | `akm registry add <url> --name <component>` | `akm config enable/disable` was also removed in 0.9.0 (it only ever toggled the skills.sh registry); use `akm registry add\|remove`, the general mechanism |
+| `akm disable <component>` | `akm registry remove <component>` | |
 | `akm events` | `akm log` | `log` is primary in 0.9.0; `history` is a different (asset-scoped) surface |
 | `akm wiki remove --force` | (removed — see [§3](#3-removed-surfaces)) | the whole `akm wiki` family is gone in 0.9.0 |
 | `akm feedback --note <text>` | `akm feedback --reason <text>` | |
 | `akm workflow next --dry-run` | (removed) | the flag is gone; `next` never supported a dry run |
 
-Additive (non-breaking) singular aliases also shipped in 0.8 and remain:
-`akm task` (= `akm tasks`) and `akm lesson` (= `akm lessons`).
+0.9.0 retires the plural `akm tasks` spelling entirely (no alias): `akm task`
+is the sole scheduling group. Its remaining subcommands are `add`, `run`,
+`sync`, `doctor`, and `history`; `list`, `remove`, `init`, `enable`, and
+`disable` are removed. `akm lessons` was removed outright (see
+[§3](#3-removed-surfaces)).
+
+### CLI surface overhaul rename table (0.9.0, hard break)
+
+A second, larger rename pass landed within 0.9.0 itself: a full CLI-surface
+overhaul with no deprecation window and no aliases. Every old spelling below
+fails immediately with the standard unknown-command/unknown-flag error —
+there was no 0.8.x warn-and-delegate period for these.
+
+| Old spelling | New spelling / replacement | Notes |
+| --- | --- | --- |
+| `akm init` | `akm bundle create` | |
+| `akm add` | `akm bundle add` | |
+| `akm list` | `akm bundle list` | |
+| `akm remove` | `akm bundle remove` | |
+| `akm update` | `akm bundle update` | |
+| `akm extract` | `akm proposal extract` | |
+| `akm propose` | `akm proposal new` | |
+| `akm registry search` | `akm search --from registry` | `--assets` folds in too |
+| `akm tasks ...` | `akm task add\|run\|sync\|doctor\|history` | singular group; no plural alias; `list`, `remove`, `init`, `enable`, and `disable` are removed |
+| `akm lessons` / `akm lesson` (command group) | (removed) | the `lesson` asset **type** is unaffected — read/write it via `akm search`/`akm show`/the proposal queue |
+| `akm history` | (removed) | `--accept-rate-by-source` folded into `akm health --report` |
+| `akm log tail` | `akm log --since '@offset:<id>'` | poll from a cooperating process; no daemon |
+| `akm graph ...` (command group) | (removed) | summary counts (entities/relations/extraction coverage) folded into `akm health`; the extraction engine and `akm show`'s related-paths are unaffected |
+| `akm mv` | (removed — see [§3](#akm-mv--move-the-file-then-akm-index)) | plain filesystem move → `akm index` → `akm lint`; optionally `bun scripts/rekey-asset-ref.ts <old> <new>` first to carry feedback/usage signal across the rename |
+| `akm workflow template` | `akm workflow create --print` | prints the template without writing |
+| `akm workflow validate` | `akm lint --type workflows --fail-on-flagged` | plain `lint` exits 0 regardless of findings — keep `--fail-on-flagged` in CI gates to preserve the old non-zero-on-invalid semantics |
+| `akm workflow watch <run-id>` | `akm log --run <run-id> --since '@offset:<id>'` | |
+| `akm workflow start <ref> --params '<json>'` | `akm workflow run <ref> --<param> <value> ...` | `run` is the canonical start/resume/execute command; parameter flags must exactly match declared names, and `--force` parallel starts are removed |
+| `akm workflow next <target>` | `akm workflow run <target>` or `akm workflow status <target>` | use `run` to execute and `status` to inspect; there is no step-at-a-time native lifecycle |
+| `akm workflow complete ...` | `akm workflow run ...` | native orchestration completes steps itself |
+| `akm workflow brief` / `akm workflow report` | `akm workflow run <target>` | the experimental external-driver protocol was removed; `run` dispatches and records units itself |
+| `akm workflow run <ref> --params '<json>'` | `akm workflow run <ref> --<param> <value> ...` | the JSON parameter bag is removed; repeat array flags or pass object/whole-array values as JSON |
+| `akm extract --watch` / `--debounce-ms` | (removed) | use the shipped `core/extract.yml` cron template instead of a foreground daemon |
+| `akm improve canary` / `--refresh` | `bun scripts/refresh-canary-set.ts [--refresh]` | maintainer tooling, run from a source checkout — helper scripts are not shipped in the npm package or binaries |
+| `akm config show` | `akm config list` | `show` was a self-declared alias |
+| `akm config validate` | (removed) | load-time schema checks already reject an invalid config |
+| `akm index --background` | (removed) | the flag never actually backgrounded the process |
+| `akm setup --detect-only` / `--reset-recommended` | (removed) | environment detection runs inside `akm setup`; `akm info` reports the *configured* capabilities, not a detection scan |
+| `akm env set` / `akm env unset` | (removed) | edit the `.env` file directly, or ingest one with `env create --from-file` |
+| `--source` on `search` / `curate` | `--from` | value rename too: `stash` → `local`, `both` → `all` |
+| `--target` on `remember` / `clone` / `improve` / `task add`/`run`/`sync`/`history` | `--bundle` | `import`, `proposal accept`/`diff`/`revert`, `env create`/`remove`, and `secret set` **keep** `--target` |
+| `AKM_STASH_DIR` | `AKM_BUNDLE_DIR` | no fallback to the old name |
+| JSON field `stashDir` | `bundleDir` | in command results (`akm info`, `akm bundle create`, `akm config path --all`'s `stash` key → `bundle`); internal DB columns and type names are unaffected |
+| "stash" wording in help text, hints, and docs | "bundle" | user-visible surface only — internal identifiers, DB schema, and historical CHANGELOG/release-notes text are unaffected |
+
+**Scheduler ABI respelling.** Installed cron/launchd/schtasks entries invoke
+`akm task run <id> ... --scheduled` (previously a `tasks` spelling on some
+installs). `akm task sync` detects an entry whose argv no longer parses under
+the current spelling — treating it as an orphan of its marker id — and
+reinstalls it from the current file state. Run `akm task sync --rebind` once
+after upgrading to 0.9.0 to explicitly capture the current binary/invocation
+in every installed scheduler entry; see [§1](#1-cross-the-boundary-akm-migrate-status--akm-migrate-apply).
 
 ### Safety guards added in 0.8 (behavior change for non-interactive callers)
 
@@ -574,7 +953,7 @@ ref scalars; it does not convert an arbitrary prompt task into this command. The
 deterministic `akm proposal drain` verb, or the folded strategy pre-pass, is the
 supported 0.9 path.
 
-### Single batch-at-boundary git commit (`options.pushOnCommit` deprecated)
+### Single batch-at-boundary git commit
 
 0.9.0 unifies the two commit models for git-backed sources onto a single
 **batch-at-boundary** model (issue #507). Previously, writing an asset to a
@@ -584,17 +963,14 @@ on `options.pushOnCommit`. That staged only the single asset file (leaving
 
 Now every write/delete to a source is a plain filesystem operation with **no**
 per-asset commit. Git-backed targets are committed **once** at the end of the
-operation (e.g. `akm remember --target <git-source>`, proposal accept/revert,
+operation (e.g. `akm remember --bundle <git-source>`, proposal accept/revert,
 consolidate) as a single complete commit (`git add -A` staging `.akm/` + assets
 together), pushed under the same `writable + remote` gate as `akm save`/`akm sync`.
 
-**Migration:** `options.pushOnCommit` is **deprecated**. Existing configs still
-parse — its push intent is honored via the batch push gate, and akm prints a
-one-time deprecation warning when it encounters the option. Remove
-`pushOnCommit` from your source config and rely on `writable: true` (plus a
-configured remote) to push. No behavior is lost: a writable git target with a
-remote is still pushed; a target without a remote (or with push disabled)
-commits only.
+**Migration:** `options.pushOnCommit` is rejected at config load. Remove it
+from your source config and rely on `writable: true` (plus a configured remote)
+to push. A writable git target with a remote is still pushed; a target without
+a remote (or with push disabled) commits only.
 
 ## Engine And Task Assets
 
@@ -608,12 +984,11 @@ Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
 Do not reuse a colliding LLM and agent profile name without deciding which new
 engine names make the distinction clear. AKM cannot safely infer that choice.
 
-New task files use strict YAML v2. During `migrate apply`, valid 0.8 task files
-with legacy workflow-target refs are surgically rewritten to canonical refs;
-other fields and current refs remain byte-identical. The 0.9 reader continues to
-normalize their missing/`1` version, prompt `profile:` field, permissive scalar
-forms, and `akm improve --profile` commands in memory. Update user-authored files
-to `version: 2` when editing them:
+Task files use strict YAML v2. During `migrate apply`, valid 0.8 task files are
+rewritten on disk to v2. The standalone migrator canonicalizes workflow refs,
+moves prompt `profile:` to `engine:`, normalizes permissive scalar forms, maps
+bare-current-AKM `improve --profile` to `--strategy`, and removes the retired
+`--auto-accept` argument. The 0.9 runtime does not read v1 task files:
 
 ```yaml
 version: 2
@@ -627,9 +1002,14 @@ enabled: true
 
 Prompt tasks may use `engine`, `model`, `timeoutMs`, and `llm`; command tasks
 may use `timeoutMs`; workflow tasks may use `params`. Unknown and wrong-target
-keys are errors in v2. Unsupported future versions are reported by `akm tasks
-list`, `sync`, and `doctor`. Reader normalization changes only the removed AKM
-spellings; arbitrary shell commands are never rewritten.
+keys are errors in v2. Unsupported versions are reported by current task
+commands. Migration changes only removed AKM spellings; arbitrary shell
+commands are never rewritten.
+
+A workflow task now invokes the same native orchestration as `akm workflow
+run`: it executes to completion, failure, or verification rejection rather
+than merely creating a run row. Review scheduled workflow tasks for the
+resulting execution and cost impact before re-enabling the scheduler.
 
 For 0.8 command tasks, syntax migration and self-invocation routing are separate.
 `--profile` is lowered only for a PATH-selected bare `akm`/`akm.exe`, including
@@ -641,20 +1021,17 @@ is operator-owned: it keeps selecting that exact binary and its command argv is
 retained exactly. In particular, AKM does not change syntax sent to a retained
 0.8 binary. Version-2 commands receive no compatibility rewriting.
 
-The published 0.8 core `backup.yml` is a special unsafe legacy definition. It
-was enabled and ran `akm db backups`, but that command only listed snapshots; it
-did not create a recurring backup. In 0.9, `tasks add` refuses the enabled exact
-bare-self command before changing its source file or scheduler. `tasks sync`
-reports it in `skipped`, does not install a missing entry, and disables an
-existing scheduler entry while preserving the task file byte-for-byte. `tasks
-enable` also refuses to re-enable it. This quarantine applies only when bare
-`akm`/`akm.exe` is followed by exactly `db backups`; an explicit executable path
-is operator-owned and is not quarantined. Use `akm backup create --for 0.9.0`
-for an explicit migration recovery snapshot. Existing 0.8 data-directory backup
-folders are left untouched by migration.
+The published 0.8 core `backup.yml` is a special unsafe definition. It was
+enabled and ran `akm db backups`, but that command only listed snapshots; it did
+not create a recurring backup. The standalone migrator disables the exact bare
+`akm db backups` task while preserving its command for operator review. An
+explicit executable path is operator-owned and is not changed. Replace or remove
+the disabled task; use `akm-migrate backup --for 0.9.0` for an explicit migration
+recovery snapshot. Existing 0.8 data-directory backup folders are left
+untouched.
 
 Task `enabled` state controls scheduler-originated execution, not explicit
-operator invocation. `akm tasks run <id>` intentionally runs a disabled task so
+operator invocation. `akm task run <id>` intentionally runs a disabled task so
 manual catch-up definitions remain useful. Backend-generated invocations carry
 the internal `--scheduled` marker and record a `disabled` result without running
 the target. Do not use the manual command as a scheduler replacement.
@@ -678,88 +1055,67 @@ than inventing a command classification. New runs use the correct target kind.
 
 ## 5. Troubleshooting
 
-### "Cannot convert state.db out of WAL mode for migration"
+### Database is busy
 
-`akm migrate apply` fails with:
-
-> Cannot convert state.db out of WAL mode for migration — another akm process
-> is holding it open. Close other akm processes and re-run `akm migrate apply`.
-
-This means a live `akm` process (or a zombie connection from a prior crashed
-one) still has `state.db` open in WAL mode, which blocks the checkpoint apply
-needs to fold `workflow.db` in. Close every other `akm` process (schedulers,
-`akm workflow run`, background `improve` runs) and re-run `akm migrate apply`
-— it resumes from the last completed phase rather than starting over.
+Close every other `akm` process, including schedulers, workflow runs, and
+background improve jobs, then re-run `akm migrate apply`. Apply holds the
+maintenance barrier and refuses to begin while known database handles, process
+locks, or workflow claims are active.
 
 ### Resuming after a crash
 
 If `akm migrate apply` is interrupted (killed, host crash, power loss), do not
 manually edit or delete anything under `$DATA`. Run `akm migrate status` to
-read the pending phase, then re-run `akm migrate apply` with the same
-`--config` (or none, if the active config is already the target) — it
-authenticates the retained target and verified backup by fingerprint and
-resumes idempotently from the last durable phase (`prepared`, `state-converting`, `state-collapsing`, `state-applied`,
-`workflow-applied`, `cutover-applied`, `config-applied`, `tasks-prepared`,
-`tasks-applied`, `pilot-prepared`, `pilot-applied`, `rollback-prepared`, or `committed`). A
-malformed or fingerprint-mismatched journal fails closed for operator
-diagnosis instead of guessing.
+confirm that an incomplete apply is present, then re-run `akm migrate apply`.
+The sentinel already contains the original target and path base, so `--config`
+is not needed on a retry. Apply reuses the same verified backup and operation ID,
+reruns every idempotent transform, verifies final outcomes, and removes the
+sentinel. A malformed sentinel fails closed for operator diagnosis.
 
-### Restoring or downgrading the cutover
+### Restoring migration control state
 
 Stop scheduled AKM jobs and all running `akm improve`, `akm extract`, and
 workflow engine processes first. Restore refuses while a live process lock or
 workflow lease exists. Then, while still running the 0.9 binary, restore the
-complete pre-cutover snapshot:
+pre-cutover config and database snapshot:
 
 ```sh
-akm backup restore --for 0.9.0 --run <run-id> --confirm
+akm-migrate restore --for 0.9.0 --run <run-id> --confirm
 ```
 
 Restore verifies the selected run before changing live files and then creates a
-second verified rescue run of the current installation. It stages every
-replacement beside its destination, writes a durable restore journal,
-quarantines each database together with its WAL/SHM sidecars, and only then
-publishes clean staged files. The journal records a durable committed phase
-before cleanup: an earlier interruption rolls back, while an interruption after
-commit finishes cleanup without mixing generations. While either recovery phase
-is pending, ordinary config and canonical database access fail closed before
-accepting writes or recreating absent files. The selected and rescue runs remain
-under `$DATA`; if verification reports corruption, preserve them and recover
-from an independent backup.
-
-Recovery validates the complete restore journal before removing or renaming any
-path: journal format and migration version, phase, exact artifact and SQLite
-sidecar set, operation-bound stage/quarantine names, path uniqueness, source
-backup, and the expected prepared/committed filesystem state. A malformed or
-stale journal remains in place and recovery fails closed for operator diagnosis.
-Committed recovery additionally authenticates each published artifact against
-the selected backup's byte size and streaming SHA-256, then reruns config-state
-validation or SQLite `quick_check` and ledger validation before deleting any
-quarantine or journal.
-
-Prepared rollback is itself crash-idempotent. The journal fingerprints the
-original config/database/sidecar generation before quarantine. If recovery dies
-after restoring a quarantine or deleting a stage but before journal deletion,
-the next recovery authenticates the already-restored destination and continues
-cleanup. A same-ledger but byte-different substitution fails closed.
-
-Migration config files, manifests, and apply/restore journals are read through
+second verified rescue run of the current installation. It writes one
+phase-free restore sentinel, stages each selected artifact beside its
+destination, removes stale SQLite sidecars, and publishes the config last. If
+interrupted, ordinary config and canonical database access remain blocked and
+the next recovery repeats the same replacements from the selected backup until
+semantic verification passes. The selected and rescue runs remain under
+`$DATA`; if verification reports corruption, preserve them and recover from an
+independent backup.
+
+Recovery runs do not copy writable bundle content. Reserved-file rename and ref
+plans are retained; sidecar/frontmatter rewrites are inherently idempotent, and
+task rewrites are re-planned on each apply. Restore replaces config and databases
+only. Already-migrated content stays in its forward-compatible form so a later
+0.9 apply can converge without undoing filesystem changes.
+
+Migration config files, manifests, and apply/restore sentinels are read through
 bounded readers (1 MiB each). Oversized local control files fail closed rather
-than being loaded wholesale. Apply also measures the complete serialized journal
+than being loaded wholesale. Apply also measures the complete serialized sentinel
 before its first write; a near-limit config whose expanded target would exceed
-the same cap is rejected before any apply journal or artifact mutation.
+the same cap is rejected before any apply sentinel or artifact mutation.
 
-Only after restore succeeds should you install the older AKM binary. A 0.8
-binary must not run against a 0.9 config or against `state.db` migration 017 /
-`workflow.db` migration 010. If no valid pre-cutover bundle exists, do not
-downgrade in place: preserve the current config and databases, create a separate
-0.8 data/config root, and manually reconstruct the profile-based configuration.
+Do not install a 0.8 binary into this restored installation: writable content may
+already use 0.9 task and ref formats. Restore is a control-state recovery step for
+a later 0.9 apply, not an in-place downgrade. To run 0.8 again, recover config,
+databases, and writable content from an independent pre-cutover backup, or create
+a separate 0.8 data/config/content root and reconstruct it manually.
 
 ### Where backups live
 
 Recovery runs are stored under
 `$DATA/backups/migrations/<installation-id>/<run-id>/`. They record present and
-absent `config.json`, `state.db`, and `workflow.db` artifacts, ordered
-migration ledgers, sizes, and streaming SHA-256 hashes. `akm backup create
---for 0.9.0` creates an additional unique run when an operator wants a manual
-snapshot outside of `apply`'s automatic one.
+absent `config.json`, `state.db`, `workflow.db`, and `index.db` artifacts,
+ordered migration ledgers, and semantic state. `akm-migrate backup --for 0.9.0`
+creates an additional unique run when an operator wants a manual snapshot
+outside of `apply`'s automatic one.