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

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

@@ -0,0 +1,844 @@
+# 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:
+
+> **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.
+
+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)
+
+The durable-state re-key, database merge, and config migration are handled by
+the journaled, 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
+before changing a live installation, then migrate other affected assets deliberately.
+
+## 1. Cross the boundary: `akm migrate status` / `akm migrate apply`
+
+`akm migrate apply` is the one command that performs the 0.8 → 0.9 cutover.
+It:
+
+- 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.
+
+### The 0.8 binary cannot do this
+
+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:
+
+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.
+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.
+
+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, 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.
+
+A journal at `state-applied` or `workflow-applied` is 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. A journal at `cutover-applied` or any later
+forward-only phase is instead authenticated by the same operation's committed
+cutover ledger row, continuing from its recorded phase without requiring the
+`state-converting` marker; physical WAL differences are retained rather than
+rolled back. A post-cutover journal without that operation-bound marker fails
+closed.
+
+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`, and `workflow.db` artifacts, ordered migration
+ledgers, sizes, and streaming SHA-256 hashes. SQLite snapshots must also 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.
+
+## 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, 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.
+
+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`.
+
+### `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.
+
+#### Verifying the migration
+
+```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.
+
+### `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.
+
+### 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 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` and `proposal accept`/`diff`/`revert` **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
+```
+
+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.
+
+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.
+
+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
+
+### "Cannot convert state.db out of WAL mode for migration"
+
+`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.
+
+### 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.
+
+### Restoring or downgrading the cutover
+
+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:
+
+```sh
+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
+bounded readers (1 MiB each). Oversized local control files fail closed rather
+than being loaded wholesale. Apply also measures the complete serialized journal
+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.
+
+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.
+
+### 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-migrate backup
+--for 0.9.0` creates an additional unique run when an operator wants a manual
+snapshot outside of `apply`'s automatic one.