akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/workflows/validator.js

@@ -1,12 +1,37 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
+ *
+ * The parser handles per-line shape checks; this module runs rules that need
+ * the whole document or the raw frontmatter at once: duplicate step IDs,
+ * step-id format, and the frontmatter key whitelist.
+ */
+import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);
     checkDuplicateStepIds(draft, errors);
+    checkResourceLimits(draft, errors);
+}
+function checkResourceLimits(draft, errors) {
+    if (draft.steps.length > WORKFLOW_MAX_STEPS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
+    }
+    if ((draft.parameters?.length ?? 0) > WORKFLOW_MAX_PARAMS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_PARAMS} parameters.` });
+    }
+    for (const step of draft.steps) {
+        if (utf8Bytes(step.instructions.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+            errors.push({
+                line: step.instructions.source.start,
+                message: `Step "${step.id}" instructions exceed the 256 KiB resource limit.`,
+            });
+        }
+    }
 }
 function checkFrontmatterKeys(data, fmEndLine, errors) {
     for (const key of Object.keys(data)) {
@@ -14,7 +39,7 @@ function checkFrontmatterKeys(data, fmEndLine, errors) {
             continue;
         errors.push({
             line: fmEndLine,
-            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, when_to_use.`,
+            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use.`,
         });
     }
 }

package/docs/data-and-telemetry.md

@@ -26,7 +26,7 @@ AKM writes to these locations on your machine. All paths follow [XDG Base Direct
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `config.json` | Your AKM configuration: LLM endpoints, stash paths, feature flags, profiles | **No** — deleting resets all settings |
+| `config.json` | Your AKM configuration: engines, strategies, stash paths, and feature settings | **No** — deleting resets all settings |
 
 Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
@@ -109,7 +109,7 @@ An append-only log of every mutating action you perform with AKM. Events are sto
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
 | `promoted` | `akm proposal accept <id>` | `ref` |
 | `rejected` | `akm proposal reject <id>` | `ref` |
-| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, profile |
+| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |
 | `reflect_completed` | Reflect phase produced a proposal | `ref` |
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm propose` | `ref` |
@@ -123,7 +123,8 @@ An append-only log of every mutating action you perform with AKM. Events are sto
 | `proposal_expired` | Proposal expired | `ref` |
 | `events_purged` | Old events deleted by maintenance | `purgedCount`, `retentionDays` |
 | `workflow_started` | `akm workflow start <ref>` | `ref`, `runId` |
-| `workflow_step_completed` | `akm workflow next` | `ref`, `runId`, `stepId` |
+| `workflow_step_completed` | `akm workflow next` (genuine `completed` transition only) | `ref`, `runId`, `stepId`, `status` |
+| `workflow_step_updated` | `akm workflow next` (non-`completed` transitions: `failed`/`skipped`/`blocked`) | `ref`, `runId`, `stepId`, `status` |
 | `workflow_finished` | `akm workflow complete` | `ref`, `runId` |
 | `schema_repair_invoked` | `akm lint --repair` triggered schema repair | `ref` |
 | `archive_cleanup` | Archive cleanup during consolidation | |

package/docs/migration/release-notes/0.6.0.md

@@ -90,7 +90,7 @@ vault | wiki | enable | disable | completions | upgrade | save | help |
 hints
 
 Full migration guides:
-- https://github.com/itlackey/akm/blob/main/docs/migration/v1.md (v1
+- https://github.com/itlackey/akm/blob/main/docs/archive/pre-1.0-migration.md (pre-1.0
   architecture refactor — read this first if you are coming from 0.5.x or
   an earlier 0.6 pre-release)
 - https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md

package/docs/migration/release-notes/0.7.0.md

@@ -13,7 +13,7 @@ grammar continue to match the v1 architecture spec
 pre-releases — the formal freeze itself happens at 1.0 GA.
 
 If you are coming from 0.6.x, the
-[v1 migration guide](../v1.md) covers the per-surface delta and is the
+[archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) covers the historical per-surface delta and is the
 canonical upgrade reference. This file is the executive summary of
 what's new in 0.7.0.
 
@@ -47,7 +47,8 @@ akm proposal reject <id> --reason "…"   # archive with reason
 Multiple proposals for the same `ref` coexist without filesystem
 collisions. Auto-accept is gated per-source via the source config
 (`autoAcceptProposals: true`); the default is off and requires a
-writable source. See v1 spec §11 and `docs/migration/v1.md`.
+writable source. See the archived pre-1.0 migration spec §11 at
+`docs/archive/pre-1.0-migration.md`.
 
 ### `akm reflect`, `akm propose`, `akm distill` — new CLI surfaces (#225, #226, #227)
 
@@ -141,7 +142,7 @@ The bench technical reference lives in
 - Earlier 0.7.x pre-release work (#220–#223) finalised the registry
   curation surface removal, classification pipeline rewrites, and
   error envelope shape that 0.7.0 ships. Operators upgrading from a
-  0.6.x baseline should read [`docs/migration/v1.md`](../v1.md) for
+  0.6.x baseline should read the [archived pre-1.0 plan](../../archive/pre-1.0-migration.md) for
   the per-surface migration recipe.
 
 ### CLI surface as of 0.7.0
@@ -257,7 +258,7 @@ akm proposal accept <id>
 
 ## Full migration guides
 
-- [v1 migration guide](../v1.md) — per-surface delta from any 0.6.x
+- [Archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) — per-surface delta from any 0.6.x
   baseline. The canonical reference for upgrading.
 - [v0.5 → v0.6](../v0.5-to-v0.6.md) — the older terminology cut and
   registry schema v3.

package/docs/migration/release-notes/0.9.0-beta.60.md

@@ -0,0 +1,19 @@
+Migration notes for akm v0.9.0-beta.60
+
+This beta brings command-surface alignment updates. The functional storage and API shape remain stable for existing 0.9.0-compatible stashes, but old command naming and docs references are now considered deprecated in this cycle.
+
+Key operator-facing changes:
+
+- `akm vault` is replaced by `akm env`/`akm secret` as the preferred secure runtime surface.
+- `akm save` is replaced by `akm sync` for writable-stash persistence and pushes.
+- `akm events` is replaced by `akm log`.
+- Proposal workflow is consolidated on `akm improve`, `akm propose`, and `akm proposal ...`.
+- Legacy migration notes references (`reflect`, `distill`, flat `proposals/accept/reject` aliases) are deferred to final 0.9 cleanup.
+
+Recommended checks:
+
+- Run `akm help migrate 0.9.0-beta.60` on each machine after upgrade.
+- Run `akm-migrate-storage --yes` if older stashes still use `vaults/` only.
+- Rebuild search with `akm index` after any migration step.
+
+No additional storage migration is required for existing 0.9.0 betas that already use `env/`.

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

@@ -0,0 +1,401 @@
+# Migrating from akm 0.8.x to 0.9.0
+
+0.9.0 is a strict engine and strategy cutover. It removes the CLI deprecation
+aliases introduced during the 0.8 stabilization window and the deprecated
+`vault` asset type. It does not translate profile-based configuration, workflow,
+or task files automatically. Create the recovery backup before changing a live
+installation, then migrate the affected assets deliberately.
+
+## Engine And Task Assets
+
+Before editing a 0.8 configuration, create a recovery bundle:
+
+```sh
+akm backup create --for 0.9.0
+```
+
+The immutable bundle is stored under `$CACHE/migration-backups/0.9.0`
+(`$XDG_CACHE_HOME/akm` by default on Linux). It records both present and absent files for
+`config.json`, `state.db`, and `workflow.db`, verifies every captured file by
+SHA-256, and is created automatically before AKM first opens either canonical
+durable database for the 0.9 engine migrations. Do not move individual files
+into or out of the bundle; verification fails closed on any mismatch.
+
+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 are strict YAML v2. Add `version: 2`, replace prompt `profile:` with
+`engine:`, and retain only fields valid for the target:
+
+```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. `akm tasks list`, `sync`, and `doctor` report stale v1 files;
+`show`, `run`, `enable`, and `disable` reject them without mutation. Regenerate
+the known default improve tasks or replace `akm improve --profile <name>` with
+`akm improve --strategy <name>` yourself. AKM never rewrites arbitrary shell
+commands.
+
+## CLI rename table (old → new, removed 0.9.0)
+
+Every old spelling prints a stderr deprecation warning in 0.8.x (suppressed
+under `--quiet`) and delegates to the canonical form. JSON stdout is unaffected.
+
+| Old spelling (0.8, deprecated) | Canonical (use this) | Notes |
+| --- | --- | --- |
+| `akm proposals` | `akm proposal list` | bare `akm proposal` also lists |
+| `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` | unchanged on `search`/`curate`/`graph`/`remember` |
+| `akm save` | `akm sync` | `sync` = commit + optional push; adds `--no-push` |
+| `akm enable <component>` | `akm config enable <component>` | |
+| `akm disable <component>` | `akm config disable <component>` | |
+| `akm events` | `akm log` | `log` is primary in 0.9.0; `history` is a different (asset-scoped) surface |
+| `akm wiki remove --force` | `akm wiki remove -y` | `--force` skips the new confirmation prompt; use `-y`/`--yes` |
+| `akm feedback --note <text>` | `akm feedback --reason <text>` | |
+| `akm workflow next --dry-run` | (removed) | the flag is gone; `next` never supported a dry run |
+
+Additive (non-breaking) singular aliases also shipped in 0.8: `akm task`
+(= `akm tasks`) and `akm lesson` (= `akm lessons`).
+
+## Safety guards added in 0.8 (behavior change for non-interactive callers)
+
+Two previously-unguarded destructive paths now confirm before acting. **Scripts
+that invoked 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 and AKM does not rewrite them. The deterministic
+`akm proposal drain` verb, or the folded strategy pre-pass, is the supported
+0.9 path.
+
+## Single batch-at-boundary git commit (`options.pushOnCommit` deprecated)
+
+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 --target <git-source>`, proposal accept/revert,
+consolidate) as a single complete commit (`git add -A` staging `.akm/` + assets
+together), pushed under the same `writable + remote` gate as `akm save`/`akm sync`.
+
+**Migration:** `options.pushOnCommit` is **deprecated**. Existing configs still
+parse — its push intent is honored via the batch push gate, and akm prints a
+one-time deprecation warning when it encounters the option. Remove
+`pushOnCommit` from your source config and rely on `writable: true` (plus a
+configured remote) to push. No behavior is lost: a writable git target with a
+remote is still pushed; a target without a remote (or with push disabled)
+commits only.
+
+## `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 guide 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 env:<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.
+
+## Table of contents
+
+- [Why `vault` → `env`](#why-vault--env)
+- [What changed in 0.8.0](#what-changed-in-080)
+- [Running the migration](#running-the-migration)
+- [Command mapping](#command-mapping)
+- [The safe shell-load path](#the-safe-shell-load-path)
+- [Single values are now secrets](#single-values-are-now-secrets)
+- [What 0.9.0 removes](#what-090-removes)
+- [Verifying the migration](#verifying-the-migration)
+- [Rolling back](#rolling-back)
+
+## 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 changed in 0.8.0
+
+| Area | 0.7.x / early 0.8 | 0.8.0+ |
+| --- | --- | --- |
+| Asset type | `vault` | `env` (`vault` is a deprecated alias) |
+| Directory | `vaults/` | `env/` (`vaults/` frozen after migration) |
+| Ref prefix | `vault:prod` | `env:prod` (also accepts `environment:`; `vault:` still resolves) |
+| Shell load | `source "$(akm vault path …)"` | `akm env run env:prod -- $SHELL` (or `export --out <file>` then source) |
+| Run | `akm vault run vault:prod[/KEY] -- …` | `akm env run env:prod [--only K] -- …` |
+| Set one value | `akm vault set vault:prod KEY` | `akm secret set secret:key` (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 env:prod` |
+| Renderer | `vault-env` | `env-file` |
+| Audit event | `vault_access` | `env_access` (`metadata.deprecatedAlias` when reached via the `vault` shim) |
+
+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/migrate-storage.ts --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
+
+# 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 env:prod -- $SHELL
+
+# Run a command with the env injected
+akm vault run vault:prod -- ./deploy.sh →  akm env run env:prod -- ./deploy.sh
+
+# Create / ingest an existing .env
+akm vault create prod                   →  akm env create prod
+                                            # 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 env:prod --quiet)"
+                                            # or: akm secret set secret: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 env: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
+  env: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 env: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](../cli.md#secret) instead:
+
+```sh
+printf '%s' "$TOKEN" | akm secret set secret:deploy-token
+akm secret run secret: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 becomes an unknown-type error
+  pointing at `env:`).
+- 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 env:<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).
+
+To make this non-silent, 0.9.0 adds a **one-time, read-only guard**: whenever
+`akm index` (or any auto-index path) runs against a stash whose `vaults/`
+directory holds `.env` files but has no `vaults/.migrated` marker, akm prints a
+single warning pointing here and at `akm-migrate-storage`. The guard never
+reads secret contents, and never writes, moves, or deletes anything — it only
+detects the un-migrated state. The fix is the same idempotent, non-destructive
+command as on 0.8:
+
+```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 config get stashDir)/vaults/.migrated"
+
+# Values still never leak
+akm show env:prod          # key names only
+akm search <a-secret-value> # no hits
+```
+
+## Restoring or downgrading the engine 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 backup restore --for 0.9.0 --confirm
+```
+
+Restore verifies the manifest, permissions, sizes, and checksums before
+replacing anything. It restores each original file and removes a canonical DB
+that the manifest recorded as originally absent, including its WAL/SHM
+sidecars. Restore also holds the global maintenance barrier from its last
+lock/lease check through replacement, so a new index writer, improve/extract
+lock, lockfile writer, or workflow engine lease cannot start in that window.
+The recovery bundle itself remains in `$CACHE` for repeatable recovery. If
+verification reports corruption, preserve the bundle and recover
+from an independent backup; do not delete the manifest or regenerate it from a
+post-cutover config.
+
+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.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.0",
+  "version": "0.9.0-rc.2",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
@@ -43,7 +43,9 @@
     "LICENSE",
     "docs/migration/release-notes",
     "docs/migration/v0.7-to-v0.8.md",
-    "docs/data-and-telemetry.md"
+    "docs/migration/v0.8-to-v0.9.md",
+    "docs/data-and-telemetry.md",
+    "schemas"
   ],
   "bin": {
     "akm": "dist/akm",