akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -1,1123 +1,122 @@
-# Migrating from akm 0.8.x to 0.9.0
+# Moving from akm 0.8 to the current 0.9 line
 
-0.9.0 is the format-neutral **bundle / adapter** refactor. It replaces the flat
-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:
+The current 0.9 runtime does not contain a second 0.8 config/storage/runtime
+architecture. Upgrading the package is supported; loading an old installation
+in place is not.
 
-> **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
-> CHANGELOG migration note) until the remaining technical debt is paid off.
-> The 0.10.x series returns to bug fixes and tuning with the normal
-> breaking-changes-only-in-major/minor discipline. See STABILITY.md.
+## What the upgrade preserves
 
-1. [Cross the boundary: `akm migrate status` / `akm migrate apply`](#1-cross-the-boundary-akm-migrate-status--akm-migrate-apply)
-2. [Ref grammar: `type:name` → `[bundle//]conceptId`](#2-ref-grammar-typename--bundleconceptid)
-3. [Removed surfaces](#3-removed-surfaces)
-4. [Behavioral notes](#4-behavioral-notes), including
-   [Engine And Task Assets](#engine-and-task-assets) config migration
-5. [Troubleshooting](#5-troubleshooting)
+- authored assets that you copy into a current bundle;
+- task-v2 source files that the explicit task migrator can translate without
+  guessing;
+- package-manager or standalone-binary updates through `akm upgrade`.
 
-The durable-state re-key, database merge, and config migration are handled by
-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 — 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.
+## What it does not preserve
 
-## 1. Cross the boundary: `akm migrate status` / `akm migrate apply`
+- 0.8 config shapes;
+- old `index.db`, `workflow.db`, task-history JSONL, or legacy lock/cache
+  layouts;
+- old ref grammar or old workflow/task execution paths;
+- in-flight pre-v4 workflow plans.
 
-`akm migrate apply` is the one command that performs the 0.8 → 0.9 cutover.
-It:
+Those formats are not compatibility inputs to the current runtime. Keep an
+archive if you need historical inspection; do not place it in the live 0.9
+config/data directories.
 
-- Converts config from the flat `stashDir` / `sources` / `installed` /
-  `wikiName` keys to a `bundles` map keyed by each source's stable id, plus
-  `defaultBundle` naming the primary writable bundle. Bundle ids are derived
-  from the existing `registryId` / path slug, so no second identity migration
-  happens. After the cutover, the retired keys are **hard-rejected** by the
-  0.9.0 config schema whenever present — a config still carrying them fails to
-  load with an error naming `akm migrate apply`
-  (`src/core/config/config-schema.ts`). Registry-installed bundles keep only
-  their desired locator (`git`/`npm` + `registryId`) in config; resolved cache
-  paths and revisions live exclusively in the lockfile.
-- 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 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: 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).
+## Upgrade procedure
 
-### The 0.8 binary cannot do this
+### 1. Archive the old installation
 
-The 0.8 binary does not contain `akm migrate` or the `upgrade
---migration-config` contract. Do not attempt to invoke either command with
-0.8, and do not use 0.8 self-update to cross this boundary. Use this
-package-manager/manual boundary procedure instead:
+Stop scheduled tasks and running AKM processes. Copy the old config, data,
+state, cache, and authored bundle directories to an archive outside the live
+AKM paths. Verify the copy before continuing.
 
-1. Stop AKM writers, schedulers, and workflow drivers.
-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.
-4. Install 0.9 with the package manager, or download, checksum, and stage the
-   0.9 standalone binary. A package-manager install replaces the managed 0.8
-   package; a standalone operator should retain the old executable. Keep the
-   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 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.
+Do not delete the authored bundle: it is the input you will selectively bring
+forward.
 
-### Auto-generating the 0.9 config
+### 2. Update the package or binary
 
-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:
+Use the installation method that owns AKM:
 
 ```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")
+akm upgrade --check
+akm upgrade
+akm --version
 ```
 
-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
+Alternatively install `akm-cli@0.9.2` directly with npm, Bun, or pnpm, or
+replace the standalone binary after verifying its published checksum.
 
-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.
+`akm upgrade` updates executable code. It does not rewrite old config or
+storage.
 
-```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.
+### 3. Start from current config and state
 
-If your 0.8 config configured LLM or agent profiles, add `engines` and
-`defaults` too:
+Move the archived 0.8 config/data/state/cache paths out of the live locations,
+then run current setup:
 
-```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"
-  }
-}
+```sh
+akm setup
+akm health
 ```
 
-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.
+Configure current `bundles`, `defaultBundle`, engines, and credentials. Copy
+only authored assets you intend to retain into a current bundle. Regenerable
+indexes and caches should be rebuilt, not imported.
 
-#### 0.8 key → 0.9 key
+Current additive `state.db` schema changes run automatically when the managed
+database opens. That mechanism upgrades current ledgers; it is not an importer
+for 0.8 databases.
 
-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:
+### 4. Convert task-v2 sources explicitly
 
-| 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:
+Normal task execution accepts task v3 only. Preview every translation:
 
 ```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:
-
-Package-manager installs require Node.js >= 22. If Bun >= 1.0 is also on
-`PATH`, the installed launcher prefers Bun after Node.js bootstraps it.
-
-```sh
-npm install -g akm-cli@0.9.0
-# or: pnpm add -g akm-cli@0.9.0
-```
-
-Commands for steps 5 and 6:
-
-```sh
-# Package-manager install: this `akm` is now the 0.9 binary.
-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 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 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 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:
-
-```sh
-akm upgrade --migration-config ./prepared-0.9.json
-```
-
-This command is not the 0.8-to-0.9 procedure. The already-installed 0.8 binary
-cannot contain or enforce safeguards added in 0.9, so operators must follow the
-manual boundary above rather than relying on 0.8 self-update. For 0.9+ upgrades,
-the current binary preflights only its current artifact state; it does not parse
-a prepared config for the future release. After installation, only the new
-binary receives `--config` during apply. If the active config is already current,
-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`, `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-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`
-
-Refs are now subdir-qualified concept ids inside their bundle —
-`skills/code-review`, `memories/vpn-note`, `knowledge/api-guide`, `env/prod`,
-`secrets/deploy-token` — with an optional `bundle//` installation prefix and an
-optional `#fragment`. Durable state stores the fully-qualified
-`bundle//conceptId`; the short bundle-omitted form is accepted input only (CLI,
-API, and inside bundle content), resolved against `defaultBundle` and then
-installation-priority order.
-
-Before / after:
-
-| 0.8.x | 0.9.0 |
-| --- | --- |
-| `skill:code-review` | `skills/code-review` |
-| `memory:vpn-note` | `memories/vpn-note` |
-| `origin//knowledge:api-guide` | `origin//knowledge/api-guide` |
-| `vault:prod` | `env/prod` (see [§3](#3-removed-surfaces)) |
-
-**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 (`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 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
-
-### `akm wiki` → a bundle format, not a command family
-
-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 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.
-
-### `akm vault` → `env` / `secret`
-
-0.9.0 also removes the deprecated `vault` asset type. Its replacement, the `env`
-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
-> `vaults/` → `env/`, then switch your scripts from `akm vault …` to
-> `akm env …` and from `source "$(akm vault path …)"` to
-> `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.
-
-#### Why `vault` → `env`
-
-The old `vault` type managed individual `KEY=value` entries: `vault set`,
-`vault unset`, comment management, and bespoke value quoting. That hand-rolled
-write surface was the riskiest part of the feature. 0.8.0 simplifies the model
-and splits it by **purpose**:
-
-- **`env`** — a group of related **configuration** for an app/service (URLs,
-  flags, and any credentials it needs) in one `.env` file, sourced or injected
-  **wholesale**. Values may or may not be sensitive — all are protected. akm no
-  longer edits entries; you edit the file with your own editor and akm loads it.
-- **`secret`** — a single **sensitive value** used on its own for authentication
-  (one file = one value: a token, key, or cert), for the cases where
-  `vault set <ref> <KEY>` was used to store one credential.
-
-Both protect values identically (never written to stdout, the index, or any
-structured output); env additionally surfaces key names for discoverability
-(comment text is never surfaced — comments can contain commented-out
-credentials). Pick `env` for configuration, `secret` for a standalone
-authentication credential.
-
-#### What the `vault` split became
-
-The mapping (right column is the current 0.9.0 world):
-
-| Area | old `vault` world | now (0.9.0) |
-| --- | --- | --- |
-| Asset type | `vault` | `env` (whole group) / `secret` (single value) |
-| Directory | `vaults/` | `env/` and `secrets/` (`vaults/` frozen after migration) |
-| Ref | `vault:prod` | `env/prod` / `secrets/<name>` (the `vault:` prefix is removed) |
-| Shell load | `source "$(akm vault path …)"` | `akm env run prod -- $SHELL` (or `export --out <file>` then source) |
-| Run | `akm vault run vault:prod[/KEY] -- …` | `akm env run prod [--only K] -- …` |
-| Set one value | `akm vault set vault:prod KEY` | `akm secret set <name>` (or edit the `.env`) |
-| Ingest a `.env` | (hand-copy into `vaults/`) | `akm env create prod --from-file ./.env` |
-| Delete | (hand-delete the file) | `akm env remove prod` |
-| Renderer | `vault-env` | `env-file` |
-| Audit event | `vault_access` | `env_access` |
-
-The `akm vault` verb still works in 0.8.x: it prints a stderr deprecation
-warning and delegates `list` / `path` / `export` / `run` / `create` to the
-`env` handlers. `vault set` / `vault unset` and the single-key
-`vault run <ref>/KEY` form are **hard-errors** with a signpost — silent changes
-to secret-handling behaviour are unacceptable.
-
-#### Running the migration
-
-The migration copies `<stash>/vaults/` → `<stash>/env/`. It is **copy, never
-move**: the legacy `vaults/` tree is left intact as a frozen copy and a
-`vaults/.migrated` marker is written so re-runs are no-ops.
-
-```sh
-# Preview (no changes written)
-akm-migrate storage --dry-run
-
-# Apply
-akm-migrate storage --yes
-
-# From a source clone:
-bun scripts/akm-migrate.ts storage --yes
-```
-
-What the `vaults/ → env/` step does:
-
-1. Skips entirely if there is no `vaults/` directory, if the `.migrated` marker
-   already exists, or if `vaults/` contains no `.env` files (e.g. a fresh
-   install).
-2. Copies every file under `vaults/` into `env/` as **opaque bytes** (`.env`,
-   `.sensitive`, and `.lock` sidecars alike) — contents are never read or
-   re-serialised.
-3. **Never overwrites** an `env/` file you already authored (those are skipped
-   and preserved).
-4. Tightens permissions on the copied tree: `0600` files, `0700` directories,
-   then verifies the mode. (The generic copy helper checks size only, so this
-   pass guarantees migrated secret material does not land at the umask default.)
-5. Verifies the post-copy `.env` count is at least the source count, then writes
-   the `vaults/.migrated` marker.
-
-After migrating, run `akm index` to refresh search so entries surface under
-`env/…` rather than `vault:`.
-
-#### Command mapping
-
-```sh
-# 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
-
-# Load values into a shell (use a subshell — safe, nothing on disk)
-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  # 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  # 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)"  # 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
-```
-
-Existing `vault:` refs embedded in your own assets are **not** rewritten (akm
-never mutates your content). They keep resolving through 0.8.x: the resolver
-prefers `env/` and falls back to the frozen `vaults/` copy.
-
-#### The safe load paths
-
-`env path` prints the **raw** file path. Do **not** `source` it: a hand-edited
-or migrated `.env` containing `X=$(rm -rf ~)` would execute on `source`.
-
-- **Processes / agents / interactive** — `akm env run prod -- <cmd>` (or
-  `-- $SHELL`). Values go straight into the child process, never through a shell
-  and never onto stdout. **This is the only path safe for AI agents** —
-  `env export`/`env path` put value-bearing data where a captured context would
-  ingest it.
-- **A sourceable file** (a tool that must `source` a script) — `akm env export
-  prod --out <file>` writes single-quote-escaped `export KEY='value'` lines
-  to a file (mode 0600); the values are re-serialised so sourcing it can never
-  execute a substitution. `export` never prints values to stdout, so it requires
-  `--out`.
-- **Docker `_FILE` / `--env-file`** — `akm env path prod --quiet` prints the
-  raw file path for tools that read it themselves.
-
-#### Single values are now secrets
-
-If you used `vault set <ref> <KEY>` to store a single credential, store it as a
-[secret](../reference/cli.md#secret) instead:
-
-```sh
-printf '%s' "$TOKEN" | akm secret set deploy-token
-akm secret run deploy-token GITHUB_TOKEN -- gh release create v1.0.0
-```
-
-`akm env run` injects the **whole** file; the single-key `vault run <ref>/KEY`
-form was removed because silently changing which variables a child process sees
-is a security-relevant behaviour change.
-
-#### What 0.9.0 removes
-
-- 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 \`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
-  confirmation — the migration never auto-removes it.
-
-Switch to `akm env` / `akm secret` and the `akm env run <name> -- <cmd>`
-idiom before upgrading to 0.9.0.
-
-##### If you upgraded straight to 0.9.0 without migrating
-
-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
-copied to `env/` and will **not** appear under `env/…` — it is silently
-un-indexed (the files themselves are untouched on disk).
-
-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/
 ```
 
-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
-late migration on a 0.9.0 install still works.
+Review each `changed`, `skipped`, and `blocked` entry. The migrator blocks
+ambiguous argv arrays or any conversion whose execution meaning is not
+provable. Rewrite blocked files manually as task v3.
 
-#### Verifying the migration
+Apply only after the preview is correct:
 
 ```sh
-# env/ now contains your former vault files
-akm env list
-
-# The frozen copy + marker are present
-ls -la "$(akm info --format=json | jq -r .bundleDir)/vaults/.migrated"
-
-# Values still never leak
-akm show env/prod          # key names only
-akm search <a-secret-value> # no hits
-```
-
-#### Rolling back the vault copy
-
-The migration is non-destructive — `vaults/` is untouched. To roll back, delete
-the generated `env/` directory and remove the `vaults/.migrated` marker, then
-downgrade akm. Because `env/` is a copy, no data is lost either way.
-
-### 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. 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
-
-`akm import`'s 0.8.x `--wiki <name>` flag (route content into
-`wikis/<name>/raw/` instead of `knowledge/`) is removed along with the rest of
-the `akm wiki` surface. `akm import` always writes into `knowledge/` (use
-`--path` for a subdirectory); use the `llm-wiki` bundle format directly
-(`pages/`, `raw/`) if you still want wiki-shaped content.
-
-### Removed `--min-retrieval-count`
-
-`akm improve`'s `--min-retrieval-count` flag and the `minRetrievalCount` option
-configured the P0-A high-retrieval fallback lane, which was deleted along with
-several other improve-loop lanes (self-consistency, multi-cycle, exploration
-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)
-
-The indexer now dispatches each installed bundle's *detected* adapter (Claude
-tool dirs, LLM wikis, website snapshots, agent-skills packs, …) instead of
-recognizing everything with the akm-stash adapter. Entries in such bundles
-change type and ref spelling to the owning adapter's own scheme the first time
-you reindex after upgrading. **No action needed** — the index is a
-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. See
-[Bundle Types](../reference/bundle-types.md) for the full 11-adapter list,
-detection rules, and what each one reads/writes.
-
-### 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 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
-
-Indexing's LLM enrichment pool now defaults its concurrency from the
-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).
-`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)
-
-Every old spelling printed a stderr deprecation warning in 0.8.x (suppressed
-under `--quiet`) and delegated to the canonical form. 0.9.0 removes the old
-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` 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>` | |
-| `akm reject <id>` | `akm proposal reject <id>` | |
-| `akm revert <id>` | `akm proposal revert <id>` | |
-| `--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` | `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 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 |
-
-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)
-
-Two previously-unguarded destructive paths confirm before acting. **Scripts
-that invoke these non-interactively must add `-y` / `--yes`:**
-
-- `akm registry remove <name>` — prompts before removing the registry; pass `-y`
-  to skip. Non-interactive use without `-y` aborts.
-- `akm proposal accept --generator <g>` (the **bulk** form) — prompts before
-  promoting every matching proposal. Single-id accept is unchanged (revertable).
-
-### Proposal triage replaces the `process-proposals` prompt task
-
-Move a 0.8 triage process into the selected 0.9 improve strategy. The folded
-pre-pass remains the recommended shape:
-
-```jsonc
-{
-  "improve": {
-    "strategies": {
-      "default": {
-        "processes": {
-          "triage": {
-            "enabled": true,
-            "applyMode": "queue",
-            "policy": "personal-stash"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-If a separate schedule is required, replace the old agent prompt task with a
-strict task YAML v2 command:
-
-```yaml
-version: 2
-schedule: "20 * * * *"
-command: akm proposal drain --policy personal-stash --yes
-enabled: true
-name: Drain AKM proposal queue
-```
-
-Task files live in your stash. Migration rewrites only legacy workflow-target
-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
-
-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
-writable git `--target` committed (and optionally pushed) **per asset**, gated
-on `options.pushOnCommit`. That staged only the single asset file (leaving
-`.akm/` state dirty) and produced one noisy commit per asset.
-
-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 --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 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
-
-Replace `profiles.llm.<name>` and `profiles.agent.<name>` with one
-`engines.<name>` map. Replace `defaults.llm`, `defaults.agent`, and
-`defaults.improve` with `defaults.llmEngine`, `defaults.engine`, and
-`defaults.improveStrategy`. Replace `profiles.improve.<name>` with
-`improve.strategies.<name>`, process `mode`/`profile` with `engine`, and CLI
-`--profile` with `--strategy` for improve or `--engine` for execution.
-
-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.
-
-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
-schedule: "@daily"
-prompt: Review the previous day's changes.
-engine: reviewer
-model: claude-sonnet-4-6
-timeoutMs: 600000
-enabled: true
+akm migrate apply
 ```
 
-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 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
-when it follows supported `env` options and assignments. The scanner recognizes
-citty-valid global forms before `improve`, including `--no-quiet`,
-`--no-verbose`, `--quiet=false`, `--verbose=false`, and value options such as
-`--format json`. An explicit `./akm`, `/opt/vendor/akm`, or other executable path
-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.
+Each changed file is validated, backed up immediately before replacement, and
+atomically replaced. `akm migrate` does not alter config or databases.
 
-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 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.
-
-Canonical task IDs contain only letters, digits, dots, underscores, and dashes,
-start with a letter or digit, are at most 228 characters, omit `.yml`/`.yaml`,
-and cannot use Windows device aliases such as `CON`, `NUL`, `COM1`, or `LPT1`
-(including aliases followed by a dot). The 228-character limit is the final
-portable bound after scheduler and filename overhead. These portability checks
-apply on every platform. For command-line compatibility only, a trailing
-lowercase `.yml` or legacy `.md` is stripped from an ID; a filename discovered
-under `tasks/` must already be canonical and is never renamed. Sync skips a
-non-portable file and disables any matching installed entry rather than guessing
-a replacement ID.
-
-Canonical migration preserves 0.8 `state.db` task-history rows and their log
-paths. One historical detail cannot be recovered: published 0.8.14 stored
-command-task history with `target_kind=prompt`. Because the durable row contains
-no command marker, 0.9 preserves and exposes it as legacy prompt history rather
-than inventing a command classification. New runs use the correct target kind.
-
-## 5. Troubleshooting
-
-### Database is busy
-
-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
-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 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
-pre-cutover config and database snapshot:
+### 5. Rebuild and reactivate
 
 ```sh
-akm-migrate restore --for 0.9.0 --run <run-id> --confirm
+akm index
+akm task doctor
+akm task sync
+akm health
 ```
 
-Restore verifies the selected run before changing live files and then creates a
-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.
+Review the scheduler plan before activation. Use `task sync --rebind` only when
+you intentionally want the current installation to take ownership of an
+existing scheduler entry.
 
-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.
+## Workflow boundary
 
-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 sentinel
-before its first write; a near-limit config whose expanded target would exceed
-the same cap is rejected before any apply sentinel or artifact mutation.
+Current Markdown and GitHub-shaped YAML workflows compile to the same source
+IR and freeze durable plan IR v4. Durable v4 is the only executable stored
+plan. Do not copy an old workflow database expecting old runs to resume; start
+new runs from current authored sources.
 
-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.
+## Recovery
 
-### Where backups live
+If the new setup is wrong, stop AKM, move the new current directories aside,
+and restore the archived 0.8 installation with its matching 0.8 executable.
+Do not mix old executable code with current state or current executable code
+with old state.
 
-Recovery runs are stored under
-`$DATA/backups/migrations/<installation-id>/<run-id>/`. They record present and
-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.
+For the task-v3 format and the narrower 0.9.1-to-0.9.2 transition, see
+[Tasks](../reference/tasks.md) and
+[Migrating from 0.9.1 to 0.9.2](v0.9.1-to-v0.9.2.md).