akm-cli 0.7.5 → 0.8.0-rc.11

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

@@ -0,0 +1,1307 @@
+# Migrating from akm 0.7.x to 0.8.0
+
+0.8.0 is a storage reorganization release. The pre-0.8 self-improvement flow
+based on `reflect` / `distill` has been consolidated into the `improve` +
+`proposals` flow (`improve`, `propose`, `proposals`, `accept`, `reject`).
+This guide focuses on what changed in storage/runtime state and which legacy
+write paths were removed.
+
+Most users need to do exactly one thing: run the migration script. The guide
+below explains what the script does and what you need to verify afterward.
+
+## Table of contents
+
+- [Installing 0.8.0](#installing-080)
+- [What changed in 0.8.0](#what-changed-in-080)
+- [Behavior change: `--auto-accept` is now OFF by default](#behavior-change---auto-accept-is-now-off-by-default)
+- [Running the migration script](#running-the-migration-script)
+- [New XDG directory layout](#new-xdg-directory-layout)
+- [Event log: events.jsonl → state.db](#event-log-eventsjsonl--statedb)
+- [Registry index cache: files → index.db](#registry-index-cache-files--indexdb)
+- [Task history: JSONL files → state.db](#task-history-jsonl-files--statedb)
+- [Task definition files: .md+frontmatter → .yml](#task-definition-files-mdfrontmatter--yml)
+- [akm.lock moved to \$DATA](#akmlock-moved-to-data)
+- [Graph extraction will re-run after upgrade](#graph-extraction-will-re-run-after-upgrade)
+- [Removed fallbacks and aliases](#removed-fallbacks-and-aliases)
+- [`akm enable context-hub` / `akm disable context-hub` removed](#akm-enable-context-hub--akm-disable-context-hub-removed)
+- [`akm improve` no longer accepts `--format`](#akm-improve-no-longer-accepts---format)
+- [`akm index --enrich` / `--re-enrich` removed](#akm-index---enrich----re-enrich-removed)
+- [Memory inference and graph extraction moved out of `index`](#memory-inference-and-graph-extraction-moved-out-of-index)
+- [`akm wiki ingest` now dispatches an agent](#akm-wiki-ingest-now-dispatches-an-agent)
+- [`config.agent.processes["task"]` and `improve.schedule` removed](#configagentprocessestask-and-improveschedule-removed)
+- [Bootstrap-from-file: `akm setup --from <file>`](#bootstrap-from-file-akm-setup---from-file)
+- [Manual actions required](#manual-actions-required)
+- [Verifying the upgrade](#verifying-the-upgrade)
+- [Troubleshooting](#troubleshooting)
+- [Rolling back](#rolling-back)
+- [Config v2 migration (reflect multi-mode)](#config-v2-migration-reflect-multi-mode)
+
+## Installing 0.8.0
+
+Pick whichever method you used for 0.7.x:
+
+```sh
+# npm
+npm install -g akm-cli@0.8.0
+
+# bun
+bun install -g akm-cli@0.8.0
+
+# From source (contributors)
+git fetch origin && git checkout v0.8.0 && bun install
+```
+
+**Do not run any akm commands yet.** Run the migration script first (see
+below). The 0.8.0 binary reads from the new locations; data that has not been
+migrated will appear missing.
+
+## What changed in 0.8.0
+
+0.8.0 reorganizes on-disk storage around four XDG-compliant directories and
+replaces two remaining JSONL write paths with SQLite tables:
+
+| Area | 0.7.x | 0.8.0 |
+| --- | --- | --- |
+| Durable databases | `$CONFIG` | `$DATA` (`~/.local/share/akm`) |
+| `akm.lock` location | `$CONFIG/akm.lock` | `$DATA/akm.lock` |
+| Event log | `$CACHE/events.jsonl` | `events` table in `$DATA/state.db` |
+| Registry index cache | `$CACHE/registry-index/<slug>.json` | `registry_index_cache` table in `$DATA/index.db` |
+| Task run history | `$STATE/tasks/history/<id>.jsonl` | `task_history` table in `$DATA/state.db` |
+| Task definition files | `<stash>/tasks/<id>.md` (Markdown + YAML frontmatter) | `<stash>/tasks/<id>.yml` (pure YAML) |
+| `--target` flag | inconsistent across commands | uniform on `remember`, `import`, `wiki stash` |
+| JSONL fallbacks | present for backward compat | removed; `state.db` only |
+
+No asset files under `$STASH/` are touched. Your memories, skills, lessons,
+workflows, and other content are unaffected.
+
+## Behavior change: `--auto-accept` is now OFF by default
+
+> **Action required if you relied on the 0.8.0-RC auto-accept default.**
+
+The `--auto-accept` flag on `akm improve` has been redefined as a confidence
+threshold. Earlier 0.8.0 RCs shipped this flag **on by default at threshold
+90**, which surprised operators who expected Phase B operations to require
+confirmation. The 0.8.0 release flips that default: **auto-accept is OFF
+unless you explicitly pass a threshold value**.
+
+If you were already on 0.7.x and never touched the flag, this is a no-op for
+you — both 0.7.x and 0.8.0 default to interactive review. The only audience
+that must update scripts is users who were tracking a 0.8.0 RC where the
+default was ON.
+
+### New semantics
+
+| Form | Effect |
+| --- | --- |
+| (flag absent) | Auto-accept **OFF** (default) |
+| `--auto-accept` (bare) | Auto-accept **OFF** (treated as flag absent) |
+| `--auto-accept=<N>` | Auto-accept ON at integer threshold `N` (0-100) |
+| `--auto-accept=safe` | Permanent alias for `--auto-accept=90` |
+| `--auto-accept=false` | Auto-accept OFF (explicit form, matches the default) |
+| any other value | Error |
+
+### What you need to do
+
+- **To get the legacy "always auto-accept" behavior**, pass
+  `--auto-accept=safe` (or `--auto-accept=90`) explicitly to `akm improve`
+  and to any scheduled task YAML, agent prompt, or CI invocation that
+  expects un-prompted Phase B operations.
+- The literal string `safe` is a permanent alias for `90` and is **not**
+  deprecated.
+- **Confidence scoring is not yet implemented.** Proposals do not currently
+  carry per-item confidence scores, so any non-`undefined` value of
+  `--auto-accept` behaves identically to the legacy `safe` mode (whole-batch
+  auto-accept). Once confidence scores ship, the threshold will gate
+  individual proposals.
+
+```sh
+# 0.8.0 default (interactive review of proposals):
+akm improve
+
+# Opt in to legacy whole-batch auto-accept:
+akm improve --auto-accept=safe        # or --auto-accept=90
+
+# Opt in to a stricter threshold (no-op until confidence scoring lands):
+akm improve --auto-accept=95
+
+# Explicit OFF (matches the default; useful for self-documenting scripts):
+akm improve --auto-accept=false
+```
+
+Review any scheduled `akm improve` tasks, agent prompts, or CI invocations
+that were authored against a 0.8.0 RC with the previous default and update
+them before upgrading.
+
+## Running the migration script
+
+The migration script is the canonical upgrade path. It is idempotent — safe to
+run more than once.
+
+The `akm-migrate-storage` binary ships alongside `akm` in the global install
+(both npm and prebuilt-binary distributions). Developers working from a
+source clone can run `bun scripts/migrate-storage.ts` instead — both invoke
+identical code.
+
+**Step 1 — preview:**
+
+```sh
+akm-migrate-storage --dry-run
+```
+
+The dry run prints every file move and database import it would perform without
+touching disk. Review the output. If any paths look unexpected, check your
+`AKM_CONFIG_DIR`, `AKM_CACHE_DIR`, `AKM_DATA_DIR`, and `AKM_STATE_DIR`
+environment variables (see [New XDG directory layout](#new-xdg-directory-layout)).
+
+**Step 2 — apply:**
+
+```sh
+akm-migrate-storage --yes
+```
+
+The script performs these steps in order:
+
+1. Creates `$DATA` and `$STATE` directories if they do not exist.
+2. Moves `$CONFIG/index.db` → `$DATA/index.db`.
+3. Moves `$CONFIG/workflow.db` → `$DATA/workflow.db`.
+4. Creates `$DATA/state.db` with the initial schema.
+5. Copies `$CONFIG/akm.lock` → `$DATA/akm.lock` (leaves the original in place
+   until you confirm everything works).
+6. Imports `$CACHE/events.jsonl` into the `events` table in `state.db`.
+   Duplicate rows (same `ts` + `eventType` + `ref`) are skipped.
+7. Imports per-task JSONL files from `$STATE/tasks/history/` (or
+   `$CACHE/tasks/history/` for older installations) into the `task_history`
+   table in `state.db`.
+8. Prints a summary of rows imported and files moved.
+
+After step 2 completes successfully you can delete the legacy files:
+
+```sh
+# Optional cleanup — only after confirming akm works
+rm -f ~/.config/akm/index.db ~/.config/akm/workflow.db
+rm -f ~/.cache/akm/events.jsonl
+rm -rf ~/.cache/akm/registry-index/
+```
+
+The old `$CONFIG/akm.lock` can be left in place; 0.8.0 reads only from
+`$DATA/akm.lock` and ignores the old location.
+
+## New XDG directory layout
+
+akm 0.8.0 uses four XDG base directories:
+
+| Variable | Default (Linux/macOS) | Default (Windows) | Override env var |
+| --- | --- | --- | --- |
+| `$CONFIG` | `~/.config/akm` | `%APPDATA%\akm` | `AKM_CONFIG_DIR` |
+| `$CACHE` | `~/.cache/akm` | `%LOCALAPPDATA%\akm` | `AKM_CACHE_DIR` |
+| `$DATA` | `~/.local/share/akm` | `%LOCALAPPDATA%\akm\data` | `AKM_DATA_DIR` |
+| `$STATE` | `~/.local/state/akm` | `%LOCALAPPDATA%\akm\state` | `AKM_STATE_DIR` |
+| `$STASH` | `~/akm` | `%USERPROFILE%\Documents\akm` | `AKM_STASH_DIR` |
+
+**What lives where after migration:**
+
+| Path | Contents |
+| --- | --- |
+| `$CONFIG/config.json` | User configuration (unchanged location) |
+| `$DATA/index.db` | Main search index, embeddings, registry cache |
+| `$DATA/workflow.db` | Workflow run state |
+| `$DATA/state.db` | Events, proposals, task history |
+| `$DATA/akm.lock` | Installed stash lockfile |
+| `$DATA/config-backups/` | Pre-save config snapshots |
+| `$CACHE/` | Regenerable data: registry downloads, binary cache |
+| `$STATE/tasks/logs/` | Per-run stdout/stderr logs (unchanged) |
+
+If you set `AKM_CONFIG_DIR` or `AKM_DATA_DIR` in CI or agent environments,
+update those environment variables to reflect the new split. The
+`AKM_CONFIG_DIR`-as-data-directory fallback (which previously caused data
+files to land in `$CONFIG` if `AKM_DATA_DIR` was unset) is removed in 0.8.0.
+
+## Event log: events.jsonl → state.db
+
+The file `$CACHE/events.jsonl` (one JSON object per line) is replaced by the
+`events` table in `$DATA/state.db`.
+
+**What this means for you:**
+
+- The migration script imports all existing JSONL events into `state.db`. After
+  a successful import, the JSONL file can be deleted.
+- Any tooling that read `events.jsonl` directly must be updated. Use
+  `akm events` to inspect the event stream from the CLI, or query `state.db`
+  directly with any SQLite client.
+- **Cursor reset**: The old cursor was a byte offset into the JSONL file. The
+  new cursor is the integer `id` (autoincrement rowid) in the `events` table.
+  If you have scripts that persist a byte-offset cursor to resume event
+  polling, reset the cursor to `0` after migration. The new `readEvents()`
+  API accepts `sinceOffset` as a row `id`.
+
+The event schema is unchanged on the wire — the same `eventType`, `ts`, `ref`,
+and `metadata` fields are present. New event types added in 0.8.0:
+
+| Event type | Emitted by | Purpose |
+| --- | --- | --- |
+| `select` | `akm show` (after search within 60s) | MemRL selection signal |
+| `improve_skipped` | `akm improve` (cooldown guards) | Observability for skip distribution |
+| `promoted` / `rejected` | `akm accept` / `akm reject` | Proposal lifecycle decisions |
+
+The `search` event now carries `mode: "semantic" | "keyword"` in its
+`metadata` field.
+
+## Registry index cache: files → index.db
+
+Per-registry JSON files at `$CACHE/registry-index/<slug>.json` are replaced
+by the `registry_index_cache` table in `$DATA/index.db`.
+
+**No manual action is required.** The cache is regenerable data: akm fetches
+and stores a fresh copy the next time it queries each registry. The migration
+script does not import the old JSON files — they are simply superseded.
+
+After confirming akm works normally, you can delete the directory:
+
+```sh
+rm -rf ~/.cache/akm/registry-index/
+```
+
+## Task history: JSONL files → state.db
+
+Per-task JSONL execution logs at `$STATE/tasks/history/<task-id>.jsonl`
+(or `$CACHE/tasks/history/` for older installations) are replaced by the
+`task_history` table in `$DATA/state.db`.
+
+The migration script imports all discovered JSONL history files into
+`task_history`. Existing entries are not overwritten.
+
+After confirming task history is visible via `akm tasks history`, you can
+delete the old files:
+
+```sh
+rm -rf ~/.local/state/akm/tasks/history/
+# or, for older installations:
+rm -rf ~/.cache/akm/tasks/history/
+```
+
+Note: per-run stdout/stderr log files at `$CACHE/tasks/logs/<task-id>/` are
+**not** moved. They remain under `$CACHE` and are unaffected by this migration.
+
+## Task definition files: .md+frontmatter → .yml
+
+In 0.7.x and earlier, scheduled task definitions lived at
+`<stash>/tasks/<id>.md` — a Markdown file where the schedule, target, and
+options were specified as YAML frontmatter and, for inline prompts, the
+Markdown body served as the prompt text:
+
+```markdown
+---
+schedule: "0 9 * * 1-5"
+workflow: workflow:daily-backup
+params:
+  region: us-east-1
+enabled: true
+---
+```
+
+For inline prompts the old format used `prompt: inline` as a sentinel and the
+Markdown body held the text:
+
+```markdown
+---
+schedule: "@daily"
+prompt: inline
+profile: opencode
+enabled: true
+---
+
+Do the thing.
+And the other thing.
+```
+
+In 0.8.0 task definitions are **pure YAML files** at `<stash>/tasks/<id>.yml`.
+The frontmatter wrapper and the Markdown body are gone. Inline prompts are
+written as a YAML block scalar:
+
+```yaml
+# <stash>/tasks/daily-backup.yml
+schedule: "0 9 * * 1-5"
+workflow: workflow:daily-backup
+params:
+  region: us-east-1
+enabled: true
+```
+
+```yaml
+# <stash>/tasks/morning-prompt.yml
+schedule: "@daily"
+prompt: |
+  Do the thing.
+  And the other thing.
+profile: opencode
+enabled: true
+```
+
+The 0.8.0 release also adds optional display fields that were not present in
+the old format:
+
+```yaml
+schedule: "@weekly"
+command: akm improve --auto-accept=90 --limit 25
+enabled: true
+name: Weekly improve cycle
+description: Runs the improve pipeline against the full stash.
+when_to_use: Run manually or let the scheduler trigger it every Monday.
+tags: [scheduled, improve]
+```
+
+### What 0.8.0 does and does not do with old .md files
+
+- `akm tasks list` — enumerates only `.yml` files. Old `.md` files are
+  **silently invisible**; they will not appear in the list or be registered
+  with the OS scheduler.
+- `akm tasks show <id>` / `akm tasks run <id>` — if you pass an id that
+  includes the `.md` suffix (e.g. `akm tasks show daily-backup.md`), the
+  suffix is stripped before the lookup, so the command resolves to
+  `<stash>/tasks/daily-backup.yml`. If no `.yml` file exists the command
+  returns a "task not found" error, not a parse error.
+- `akm tasks add` — always writes a new `.yml` file. It will not overwrite or
+  convert an existing `.md` file.
+
+There is no automatic migration of task definition files. Each `.md` file must
+be converted manually (see below).
+
+### Step-by-step migration
+
+**Step 1 — list your existing task files:**
+
+```sh
+ls ~/akm/tasks/*.md 2>/dev/null
+# or, if AKM_STASH_DIR is set:
+ls "$AKM_STASH_DIR/tasks"/*.md 2>/dev/null
+```
+
+**Step 2 — for each task, create the equivalent `.yml` file.**
+
+Extract the frontmatter keys from the old `.md` file and write them as a
+top-level YAML document. If the old file used `prompt: inline`, replace it
+with `prompt: |` followed by the indented body text.
+
+Old file `~/akm/tasks/weekly-review.md`:
+
+```markdown
+---
+schedule: "0 8 * * 1"
+prompt: inline
+profile: opencode
+enabled: true
+---
+
+Review the week's completed tasks and summarize action items.
+```
+
+New file `~/akm/tasks/weekly-review.yml`:
+
+```yaml
+schedule: "0 8 * * 1"
+prompt: |
+  Review the week's completed tasks and summarize action items.
+profile: opencode
+enabled: true
+```
+
+If the old file used `prompt: <asset-ref>` or `prompt: ./path/to/file.md`,
+carry the value through unchanged:
+
+```yaml
+schedule: "0 8 * * 1"
+prompt: agent:weekly-review-agent
+enabled: true
+```
+
+**Step 3 — validate the new file:**
+
+```sh
+akm tasks show weekly-review
+```
+
+This command parses and prints the task. Any YAML errors or missing required
+fields are reported here before the task is registered with the scheduler.
+
+**Step 4 — register with the OS scheduler:**
+
+```sh
+akm tasks sync
+```
+
+`akm tasks sync` scans all `.yml` files, installs tasks that are not yet
+registered, and removes scheduler entries whose backing `.yml` file no longer
+exists. Run this once after converting all tasks.
+
+**Step 5 — remove the old `.md` files:**
+
+Once `akm tasks list` shows all your tasks correctly and `akm tasks sync`
+reports them as installed, delete the old Markdown files:
+
+```sh
+rm ~/akm/tasks/*.md
+```
+
+### Verifying task migration
+
+```sh
+# All tasks appear with expected schedules
+akm tasks list
+
+# Each task resolves without errors
+akm tasks show <id>
+
+# Scheduler entries are in sync
+akm tasks sync
+```
+
+If a task that was registered on 0.7.x is now missing from the scheduler,
+the most likely cause is that its `.md` file has not been converted yet.
+Convert the file, run `akm tasks sync`, and confirm with `akm tasks list`.
+
+## akm.lock moved to $DATA
+
+`akm.lock` (the installed stash lockfile) moves from `$CONFIG/akm.lock` to
+`$DATA/akm.lock`.
+
+The migration script copies the file to its new location. The original at
+`$CONFIG/akm.lock` is left in place and can be deleted once you confirm `akm
+list` shows your stashes correctly.
+
+0.8.0 reads **only** from `$DATA/akm.lock`. The old location is silently
+ignored.
+
+## Graph extraction will re-run after upgrade
+
+0.8.0 includes a graph schema redesign and ships `DB_VERSION = 17` (the
+v0.7.x line shipped at version 10; intermediate bumps land in this release).
+On first launch after upgrade, akm detects the version mismatch and rebuilds
+the affected `index.db` tables in place. A warning is logged during the
+upgrade so this is visible in `akm` output.
+
+**What rebuilds automatically (free, fast):**
+
+- `entries`, `embeddings`, FTS, and the `entries_vec` table all regenerate from
+  disk via `akm index`. On most stashes this completes in a few seconds.
+
+**What requires LLM calls (the only user-visible cost):**
+
+- The graph tables (`graph_files`, `graph_file_entities`, `graph_file_relations`,
+  `graph_meta`) are dropped during the upgrade and repopulated by graph
+  extraction on the next `akm improve` cycle. Graph extraction makes LLM calls
+  to identify entities and relations in each asset, so the first improve cycle
+  after upgrade will be slower than steady state.
+
+**Recommendation:**
+
+```sh
+# Run after the storage migration to repopulate graph data.
+akm improve
+```
+
+Subsequent improve cycles return to their normal cadence; only the first run
+pays the full re-extraction cost.
+
+**Why this is faster than it would have been on 0.7.x:**
+
+- Graph extraction now uses an incremental `candidatePaths` filter so it only
+  visits assets that have actually changed, dramatically reducing repeat work
+  on a cold cache.
+- `graphExtractionBatchSize` defaults to 4 (was 1), auto-tuned against
+  `llm.contextLength`, so each LLM round-trip processes more assets.
+- `replaceStoredGraph` is now incremental — unchanged entries skip, changed
+  entries swap their child rows in place, and removed entries cascade out.
+- `listRelatedPathsForFile` is now a scoped SQL self-join instead of a full
+  in-memory scan, cutting cold-call latency from tens of milliseconds to
+  single-digit milliseconds.
+
+No manual SQL or repair commands are required — the DB_VERSION bump (10 → 17)
+and the DROP+rebuild path handle everything. If you query the graph tables directly
+from external tooling, note that `graph_files` is now keyed on
+`entry_id INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE` and the
+child tables (`graph_file_entities`, `graph_file_relations`) are re-keyed on
+`entry_id` rather than `(stash_root, file_path)`. `body_hash` is now `NOT NULL`.
+New columns: `extraction_run_id` (on `graph_files` and `graph_meta`) and
+`extractor_id` (on `graph_meta`).
+
+## Removed fallbacks and aliases
+
+The following backward-compatibility shims that shipped in 0.7.x are removed
+in 0.8.0. Update scripts, agent prompts, and config before upgrading.
+
+### JSONL write fallbacks
+
+`akm remember`, `akm import`, and `akm wiki stash` no longer fall back to
+JSONL-based event writing. All writes go through `state.db`. If you were
+relying on the JSONL file for event streaming, switch to `akm events` or
+`akm events --tail`.
+
+### Deprecated `filePath` alias
+
+The `filePath` field on task history entries (deprecated in 0.7.x in favour of
+`log`) is removed. Tools that read task history records must use the `log`
+field.
+
+### `--target` flag standardisation
+
+The write-target flag is now uniformly `--target <stash-name>` on `akm
+remember`, `akm import`, and `akm wiki stash`. Previous inconsistent flag
+names are removed with no compatibility aliases.
+
+```sh
+# Before (0.7.x inconsistent forms — removed in 0.8.0)
+akm remember "note" --stash team-stash
+akm wiki stash my-wiki ./page.md --source team-stash
+
+# After (0.8.0)
+akm remember "note" --target team-stash
+akm import ./page.md --target team-stash
+akm wiki stash my-wiki ./page.md --target team-stash
+```
+
+### Config-dir fallback removed
+
+In 0.7.x and earlier, setting `AKM_CONFIG_DIR` without setting `AKM_DATA_DIR`
+would cause data files (`index.db`, `workflow.db`) to land in `$CONFIG`. This
+fallback is removed. Set `AKM_DATA_DIR` explicitly if you override paths.
+
+## `akm enable context-hub` / `akm disable context-hub` removed
+
+`context-hub` is no longer a recognised target for `akm enable` / `akm
+disable` in 0.8.0. The toggle was originally retired in 0.6.0 (context-hub
+became a regular git stash); 0.8.0 tightens the parser so invoking either
+form now errors with a usage message:
+
+```
+Unsupported target "context-hub". Supported targets: skills.sh
+```
+
+The only valid targets for `akm enable` / `akm disable` in 0.8.0 are
+`skills.sh` (and its provider-id alias `skills-sh`). Every other component
+that used to be toggled — context-hub, builtin stash sources, registry
+defaults — is configured via the regular config file or `akm registry`
+commands rather than via `enable` / `disable`.
+
+### What to do
+
+If you still have automation or muscle-memory invocations of `akm enable
+context-hub`:
+
+1. **Remove the toggle calls.** They never re-enable a "context-hub
+   provider" — that provider type was deleted in 0.6.0.
+2. **Add context-hub as a regular git stash** if you want its content in
+   your stash list. This is the same shape used by any other git source:
+
+   ```sh
+   akm add github:andrewyng/context-hub --name context-hub
+   ```
+
+3. **Verify with `akm list`.** The output should show `context-hub` as a
+   git-type stash, not as a special component.
+
+If you only ever ran `akm disable context-hub` to suppress a phantom
+provider entry, no replacement action is needed — there is nothing to
+disable in 0.8.0.
+
+### Before / after
+
+```sh
+# Before (0.7.x and earlier — silently no-op after 0.6.0)
+akm enable context-hub
+akm disable context-hub
+
+# After (0.8.0 — explicit error; replace with regular stash management)
+akm add github:andrewyng/context-hub --name context-hub
+akm remove context-hub          # if you previously disabled it
+```
+
+## `akm improve` no longer accepts `--format`
+
+In 0.7.x `akm improve --format json` printed a JSON envelope to stdout. In
+0.8.0 the flag is rejected with `INVALID_FLAG_VALUE` to remove the implicit
+"stdout swallow" failure mode that masked errors when the improve pipeline
+emitted progress lines.
+
+### New behaviour
+
+| Form | Effect in 0.8.0 |
+| --- | --- |
+| `akm improve` (no `--format`) | Human-readable output to stderr; full JSON result written to `.akm/runs/<run-id>/improve-result.json` |
+| `akm improve --format json` | **Error** — `INVALID_FLAG_VALUE: --format is no longer supported on akm improve` |
+| `akm improve --json-to-stdout` | Same as 0.7.x `--format json` — JSON envelope on stdout for capture by pipelines |
+
+The on-disk JSON file at `.akm/runs/<run-id>/improve-result.json` is always
+written regardless of stdout mode, so post-hoc inspection of an `akm
+improve` run no longer depends on having captured stdout at the time.
+
+### What to do
+
+If you have CI jobs, agent prompts, or shell scripts that pipe `akm
+improve --format json` into `jq` or another consumer:
+
+1. **Replace `--format json` with `--json-to-stdout`.** The envelope shape is
+   unchanged — only the flag name moved.
+2. **Or read the run artifact.** If your pipeline can tolerate reading from
+   disk after the fact, drop the stdout capture entirely and read
+   `.akm/runs/<run-id>/improve-result.json` instead. The run id is printed
+   to stderr at the start of the run.
+
+### Before / after
+
+```sh
+# Before (0.7.x)
+akm improve --format json | jq '.proposals[] | select(.confidence > 80)'
+
+# After (0.8.0)
+akm improve --json-to-stdout | jq '.proposals[] | select(.confidence > 80)'
+
+# After (0.8.0 — disk-based, no stdout capture required)
+akm improve
+jq '.proposals[] | select(.confidence > 80)' \
+  "$(ls -1t .akm/runs/*/improve-result.json | head -n1)"
+```
+
+If you see this error after upgrading:
+
+```
+INVALID_FLAG_VALUE: --format is no longer supported on akm improve.
+```
+
+it is always a script-side fix — add `--json-to-stdout` (or switch to the
+file-based path) and re-run.
+
+## `akm index --enrich` / `--re-enrich` removed
+
+The `--enrich` and `--re-enrich` flags on `akm index` are gone. In 0.7.x they
+forced a slow LLM-enrichment pass alongside the regular index rebuild; in
+0.8.0 the responsibilities are split:
+
+- Plain `akm index` continues to own **fast metadata enhancement** when LLM
+  metadata enrichment is enabled (controlled by `index.metadataEnhance` in
+  the unified config tree).
+- Slow LLM maintenance work — memory inference, graph extraction, lesson
+  distillation, consolidation — runs from `akm improve`, not from `akm index`.
+
+If you have cron jobs or scripts that call `akm index --enrich` (or
+`--re-enrich`) on a schedule:
+
+```sh
+# Before (0.7.x)
+akm index --enrich
+
+# After (0.8.0)
+akm improve         # slow LLM maintenance work
+akm index           # fast metadata enrichment is already included
+```
+
+Pure index rebuilds without any LLM work continue to call `akm index` with no
+flag changes required.
+
+## Memory inference and graph extraction moved out of `index`
+
+Closely related to the `--enrich` removal above: the LLM-driven memory
+inference and graph-extraction passes that previously ran from `akm index
+--enrich` now run exclusively from the `akm improve` maintenance phase, after
+consolidation and (when relevant) the post-consolidation reindex.
+
+If any automation relied on `akm index` to refresh derived memories or graph
+data, switch it to call `akm improve` on the desired cadence. The improve
+pipeline reindexes when memory inference writes new derived memories and
+refreshes graph extraction against the post-improve corpus state, so a single
+`akm improve` run settles both surfaces.
+
+```sh
+# Before (0.7.x)
+akm index --enrich              # also refreshed memories + graph
+
+# After (0.8.0)
+akm improve                     # refreshes memories + graph as part of maintenance
+```
+
+Read-only callers (`akm graph entities`, `akm graph relations`, etc.) are
+unaffected — they continue to query whichever graph data is already in
+`index.db`.
+
+## `akm wiki ingest` now dispatches an agent
+
+`akm wiki ingest <name>` no longer prints the ingest workflow to stdout for a
+human to copy/paste or pipe elsewhere. It now resolves an agent profile (from
+`--profile` or `config.defaults.agent`) and **dispatches that agent directly
+with the workflow as its prompt**. The agent does the work end-to-end.
+
+**Behavior changes:**
+
+- The `--execute` flag is removed. Dispatch is the only mode.
+- Without an accessible agent profile, the command fails with a clear error
+  pointing at `profiles.agent`.
+- Output is the agent's run envelope, not the workflow text.
+
+**New flags:**
+
+| Flag | Description |
+| --- | --- |
+| `--profile <name>` | Override the agent profile resolved from `config.defaults.agent` |
+| `--model <model>` | Override the agent's model alias or platform ID |
+| `--timeout-ms <ms>` | Override the agent CLI timeout in milliseconds |
+
+**Migration:**
+
+Scripts that piped the previous print-only output into another tool will
+break. If you still need the raw workflow text (e.g. for an external
+orchestrator), capture it from the wiki source files directly rather than
+from `akm wiki ingest`.
+
+```sh
+# Before (0.7.x — print-only or --execute)
+akm wiki ingest my-wiki > workflow.md
+akm wiki ingest my-wiki --execute
+
+# After (0.8.0 — agent dispatch is the only mode)
+akm wiki ingest my-wiki                          # uses defaults.agent
+akm wiki ingest my-wiki --profile opencode-cli   # explicit profile
+akm wiki ingest my-wiki --model opus --timeout-ms 600000
+```
+
+## `config.agent.processes["task"]` and `improve.schedule` removed
+
+Two keys are dropped during config auto-migration and not transformed to a
+new location:
+
+- **`config.agent.processes["task"]`** — task dispatch parameters now live in
+  the task's own stash YAML file. Each task declares its `mode` and `profile`
+  (and optional `timeoutMs`) directly. This removes the global "all tasks use
+  this dispatch config" coupling that the legacy key encoded.
+
+- **`config.improve.schedule` / `improve.schedule`** — global improve
+  scheduling is no longer a config key. Scheduling is owned by stash task
+  YAMLs that wrap `akm improve` calls (via the `command:` task target).
+
+**Migration:**
+
+If your 0.7.x config had `config.agent.processes.task`, rewrite each task
+file to set `mode` / `profile` / `timeoutMs` at the top level:
+
+```yaml
+# <stash>/tasks/nightly-improve.yml
+schedule: "@daily"
+command: akm improve --auto-accept=90 --limit 50
+profile: opencode-cli   # was config.agent.processes.task.profile
+timeoutMs: 7200000      # was config.agent.processes.task.timeoutMs
+enabled: true
+```
+
+If your 0.7.x config had `improve.schedule`, create an equivalent task file:
+
+```yaml
+# <stash>/tasks/improve-cycle.yml
+schedule: "0 3 * * *"   # the cron you used to put in improve.schedule
+command: akm improve
+enabled: true
+```
+
+Run `akm tasks sync` after creating or editing task files so the OS scheduler
+picks them up. Auto-migration strips the old keys from `config.json`; the
+backup it writes before doing so retains the original schedule string if you
+need to recover it.
+
+## Bootstrap-from-file: `akm setup --from <file>`
+
+0.8.0 adds an `--from <file>` flag to `akm setup` that bootstraps the config
+from a JSON or YAML file on disk. This is the recommended way to:
+
+- Move an existing config to a new machine without typing the same answers
+  into the interactive wizard.
+- Recover from a clobbered `~/.config/akm/config.json` using the timestamped
+  snapshots that akm writes to `~/.cache/akm/config-backups/` before every
+  destructive save.
+- Replay a known-good config in CI without piping a large JSON literal on
+  the command line.
+
+The flag accepts both JSON and YAML — detection is by file extension
+(`.yml` / `.yaml` → YAML; anything else, including `.json`, parses as JSON).
+A leading `~` in the path is expanded against `$HOME`, and relative paths
+resolve against the current directory.
+
+### Recovering a clobbered config
+
+If the post-incident audit
+(`docs/technical/incidents/2026-05-23-setup-clobbers-user-config.md`) ever
+fires for you and you lose your `~/.config/akm/config.json`, restore from
+the most recent backup:
+
+```sh
+# 1. Locate the backup written immediately before the destructive save.
+ls -1t ~/.cache/akm/config-backups/ | head
+
+# 2. Replay it through setup. The wizard will skip prompts for keys
+#    present in the backup and only prompt (or accept defaults) for
+#    anything missing.
+akm setup --from ~/.cache/akm/config-backups/config-2026-05-22T18-44-31.json
+```
+
+### Bootstrapping from a YAML profile
+
+YAML is easier to hand-edit and version-control than JSON. The flag accepts
+the same top-level keys as `--config <json>` — `stashDir`, `llm`,
+`embedding`, `agent`, `semanticSearchMode`, `output`, `profiles`,
+`defaults`:
+
+```yaml
+# ~/akm-bootstrap.yml
+stashDir: /home/dev/akm
+llm:
+  endpoint: http://localhost:11434/v1
+  model: gpt-oss-20b
+semanticSearchMode: off
+```
+
+```sh
+akm setup --from ~/akm-bootstrap.yml
+```
+
+### Validation
+
+The CLI rejects with a friendly error when:
+
+- The file does not exist: `ConfigError(INVALID_CONFIG_FILE): Config file not
+  found: <path>`.
+- The file cannot be parsed: `ConfigError(INVALID_CONFIG_FILE): Failed to
+  parse JSON|YAML config file <path>: <parser error>`.
+- The top-level payload is not an object (e.g. a JSON array or string).
+- Both `--from <file>` and `--config <json>` are passed: `UsageError`.
+
+Partial files are allowed — the wizard simply prompts (or in `--yes` mode,
+accepts defaults) for any required keys that the file omitted.
+
+## Manual actions required
+
+Most users need only run the migration script. The following are exceptions:
+
+### 1. Update event stream consumers
+
+If any script, cron job, or agent prompt reads `$CACHE/events.jsonl` directly,
+update it to use `akm events [--tail]` or query `state.db` directly:
+
+```sh
+# Before
+tail -f ~/.cache/akm/events.jsonl | jq .
+
+# After
+akm events --tail
+# or for scripted consumption with cursor:
+akm events --since-offset <last-row-id> --format json
+```
+
+### 2. Reset byte-offset event cursors
+
+If you maintain a persistent cursor (file, env var, database) that stores a
+byte offset into `events.jsonl` for incremental polling, reset it to `0` after
+migration. The new cursor is a row `id` integer, not a byte offset.
+
+### 3. Update environment variable splits in CI
+
+If your CI sets `AKM_CONFIG_DIR` and relies on data files landing there:
+
+```sh
+# Before (implicit; worked because of config-dir fallback)
+export AKM_CONFIG_DIR=/ci/akm-config
+
+# After (explicit split required)
+export AKM_CONFIG_DIR=/ci/akm-config
+export AKM_DATA_DIR=/ci/akm-data
+```
+
+### 4. Update write-target flags in scripts
+
+See [Removed fallbacks and aliases](#removed-fallbacks-and-aliases) above.
+Replace any `--stash <name>` on `remember` / `import` / `wiki stash` with
+`--target <name>`.
+
+### 5. Convert task definition files from .md to .yml
+
+If you have existing task files at `<stash>/tasks/*.md`, they will not appear
+in `akm tasks list` or be run by the scheduler. Convert each one to a `.yml`
+file as described in [Task definition files: .md+frontmatter → .yml](#task-definition-files-mdfrontmatter--yml),
+then run `akm tasks sync` to register them with the OS scheduler.
+
+### 6. Run `akm improve` once to repopulate graph data
+
+The DB_VERSION bump from 10 to 17 drops and rebuilds the graph tables. The
+non-graph tables regenerate automatically the first time akm opens `index.db`,
+but graph extraction needs LLM calls and only runs from `akm improve`. See
+[Graph extraction will re-run after upgrade](#graph-extraction-will-re-run-after-upgrade).
+
+## Verifying the upgrade
+
+After running the migration script, run:
+
+```sh
+akm info
+```
+
+Look for:
+- `version` reports `0.8.0` or higher.
+- No `WARNING: legacy events.jsonl found` message.
+
+Then run the post-upgrade checklist:
+
+```sh
+akm info --format text                          # 1. version 0.8.x
+akm config list --format json | head -40        # 2. stashes[] populated
+akm list                                        # 3. your sources resolve
+akm events --limit 5 --format json              # 4. event log readable from state.db
+akm workflow list --format json | head -20      # 5. active workflow runs intact
+akm search "<a query you know works>"           # 6. indexed content still matches
+```
+
+If step 4 returns zero events after a known-active installation, the migration
+script may not have imported the JSONL file. Re-run:
+
+```sh
+akm-migrate-storage --yes
+```
+
+The import step is idempotent: each `(event_type, ts, ref, metadata_json)`
+tuple is pre-checked against the `events` table and skipped if already
+present. Re-running will only insert rows that are missing — it will not
+double-import the rows already in `state.db`.
+
+## Troubleshooting
+
+**`akm search` returns no results after upgrading.**
+The search index (`index.db`) may not have been found at its new location. Run
+`akm info` and check the `dataDir` field. If it points to `$CONFIG` instead of
+`$DATA`, `AKM_DATA_DIR` may be unset but `AKM_CONFIG_DIR` was previously
+relied upon as a fallback. Set `AKM_DATA_DIR` explicitly, re-run the migration
+script, or move `index.db` manually.
+
+**`akm events` shows 0 results but I had thousands.**
+The migration script imports events in append order. If the JSONL file was
+corrupted or truncated, some rows may have been skipped. Run:
+
+```sh
+akm-migrate-storage --dry-run
+```
+
+and look for import warnings. You can also inspect `state.db` directly:
+
+```sh
+sqlite3 ~/.local/share/akm/state.db 'SELECT COUNT(*) FROM events;'
+```
+
+**`akm list` shows empty stashes.**
+Check that `$DATA/akm.lock` exists. If only `$CONFIG/akm.lock` exists, the
+migration script may not have run. Run:
+
+```sh
+akm-migrate-storage --yes
+```
+
+**Tasks show no history.**
+`akm tasks history <id>` reads from the `task_history` table in `state.db`.
+Run the migration script to import existing JSONL files. If you see records
+from the migration but are missing recent ones, confirm your akm binary is
+0.8.0 (`akm info | grep version`).
+
+**`akm tasks list` shows fewer tasks than expected (or none).**
+Task definitions are now read exclusively from `.yml` files. Any `.md` task
+files from 0.7.x are silently skipped. Run:
+
+```sh
+ls "$AKM_STASH_DIR/tasks"/*.md 2>/dev/null
+```
+
+If `.md` files exist, convert them to `.yml` as described in the
+[task migration section](#task-definition-files-mdfrontmatter--yml) and
+re-run `akm tasks sync`.
+
+**`akm tasks show` says "task not found" for a task that used to exist.**
+The task's `.md` file has not been converted to `.yml` yet. The lookup
+resolves to `<id>.yml` regardless of whether you pass `.md` or no suffix in
+the command. Convert the file and run `akm tasks sync`.
+
+**`--stash` flag not recognized on `remember`.**
+The `--stash` flag was removed in 0.8.0. Use `--target` instead:
+
+```sh
+akm remember "note" --target team-stash
+```
+
+## Rolling back
+
+If you need to roll back to 0.7.x:
+
+1. The migration script copies (not moves) `akm.lock` and imports (not
+   removes) JSONL events. Your original files are intact.
+2. Events written to `state.db` by 0.8.0 will not be visible to 0.7.x. If you
+   wrote new events on 0.8.0 and need them in 0.7.x, export them:
+
+   ```sh
+   sqlite3 ~/.local/share/akm/state.db \
+     "SELECT json_object('schemaVersion', schema_version, 'ts', ts, 'eventType', event_type, 'ref', ref, 'metadata', json(metadata)) FROM events ORDER BY id;" \
+     >> ~/.cache/akm/events.jsonl
+   ```
+
+3. Reinstall 0.7.x:
+
+   ```sh
+   npm install -g akm-cli@0.7
+   # or
+   bun install -g akm-cli@0.7
+   ```
+
+Asset files under `$STASH/` are unchanged — stash content is fully
+forward/backward compatible across 0.7.x and 0.8.x.
+
+If you find a regression in 0.8.0, file an issue at
+<https://github.com/itlackey/akm/issues> with the output of `akm info` and a
+redacted copy of your `config.json`.
+
+---
+
+## Config 0.8.0 migration (unified profiles)
+
+0.8.0 ships a new config shape (`configVersion: "0.8.0"`) that **removes** the
+legacy `llm`, `agent`, and `features` top-level blocks and reorganizes LLM and
+agent configuration into a unified `profiles` + `defaults` tree alongside
+first-class `index.*` and `search.*` feature sections.
+
+### What changed
+
+- **`profiles.llm.<name>`** — each named LLM endpoint declared once (endpoint,
+  model, apiKey, temperature, supportsJsonSchema).
+- **`profiles.agent.<name>`** — each named agent runtime, with a required
+  `platform: "opencode" | "claude" | "opencode-sdk"` field.
+- **`profiles.improve.<name>`** — named improve-pipeline profiles. Each lists
+  per-process bindings under `processes.{reflect,distill,consolidate,memoryInference,graphExtraction,feedbackDistillation,validation}`.
+- **`defaults.llm` / `defaults.agent` / `defaults.improve`** — fallback profile names.
+- **`index.metadataEnhance` / `index.stalenessDetection`** — first-class
+  feature sections replacing the legacy `features.index.*` entries.
+- **`search.curateRerank`** — first-class feature section replacing the legacy
+  `features.search.curate_rerank` entry.
+
+### Keys removed (not migrated)
+
+The following keys are **dropped** during migration — they are not transformed
+to a new location:
+
+- `sdkMode: true` on agent profiles (replaced by `platform: "opencode-sdk"`)
+- `config.agent.processes["task"]` (tasks now declare `mode` + `profile` in
+  their own YAML)
+- `config.improve.schedule` / `improve.schedule` (scheduling lives in stash
+  task YAMLs)
+
+### Old key → new location mapping
+
+| Old key | New location |
+| --- | --- |
+| `config.llm` (endpoint/model/apiKey/temperature) | `profiles.llm.default` + `defaults.llm = "default"` |
+| `config.llm.judgeModel` | preserved on the migrated `profiles.llm.default` entry |
+| `config.agent.profiles.<n>` | `profiles.agent.<n>` |
+| `config.agent.default` | `defaults.agent` |
+| `config.agent.processes.<name>` | `profiles.improve.default.processes.<name>` (`mode: "agent"` + `profile: <agent profile name>`) |
+| `config.improve.reflectCooldownByType` | `profiles.improve.default.processes.reflect.cooldownByType` |
+| `config.improve.limit` | `profiles.improve.default.limit` |
+| `config.llm.features.memory_inference` | `profiles.improve.default.processes.memoryInference.enabled` |
+| `config.llm.features.graph_extraction` | `profiles.improve.default.processes.graphExtraction.enabled` |
+| `config.llm.features.metadata_enhance` | `index.metadataEnhance.enabled` |
+| `config.llm.features.memory_consolidation` | `profiles.improve.default.processes.consolidate.enabled` |
+| `config.llm.features.feedback_distillation` | `profiles.improve.default.processes.feedbackDistillation.enabled` |
+| `config.llm.features.curate_rerank` | `search.curateRerank.enabled` |
+| `config.llm.features.lesson_quality_gate` | `profiles.improve.default.processes.distill.qualityGate.enabled` |
+| `config.llm.features.proposal_quality_gate` | `profiles.improve.default.processes.reflect.qualityGate.enabled` |
+| `config.llm.features.memory_contradiction_detection` | `profiles.improve.default.processes.consolidate.contradictionDetection.enabled` |
+| `config.features.improve.*` | identical migration to the matching `profiles.improve.default.processes.*` entry |
+| `config.features.index.staleness_detection.options.thresholdDays` | `index.stalenessDetection.thresholdDays` |
+
+### Auto-migration at first run
+
+When akm loads a config that does not have `configVersion: "0.8.0"` (or that
+contains old keys), it:
+
+1. Prints a one-time notice describing the migration.
+2. Writes a timestamped backup to `$DATA/config-backups/` before touching the
+   file.
+3. Rewrites the config file in place with the v2 shape.
+4. Sets `configVersion: "0.8.0"` so subsequent launches skip migration.
+
+If you run multiple config layers (user + project), each layer is visited and
+rewritten independently. Read-only layers print the migrated content for manual
+apply instead of writing.
+
+**Suppress auto-migration:**
+
+```sh
+export AKM_NO_AUTO_MIGRATE=1
+```
+
+Useful on read-only CI mounts. With this flag set, akm still loads and uses
+the v1 config for the current run, but does not rewrite the file.
+
+**Auto-migration banner:** Starting in 0.8.0, when akm auto-migrates your
+config it prints a loud banner to **both stderr and stdout** so you can see
+it regardless of which stream your shell or pipeline captures. The banner
+includes the resolved config file path, the backup directory path, the
+opt-out instruction, and the preview command:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  akm: auto-migrated config → 0.8.0 format
+  file:   /home/user/.config/akm/config.json
+  backup: /home/user/.cache/akm/config-backups/config-<timestamp>.json
+  to opt out of future auto-migration: AKM_NO_AUTO_MIGRATE=1
+  to preview a dry-run diff:            akm config migrate --dry-run --print-diff
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Manual migration
+
+To preview the migration without writing (shows what would change):
+
+```sh
+akm config migrate --dry-run
+```
+
+To preview with a full unified diff of old vs new config:
+
+```sh
+akm config migrate --dry-run --print-diff
+```
+
+To apply:
+
+```sh
+akm config migrate
+```
+
+To apply and see a unified diff of what changed:
+
+```sh
+akm config migrate --print-diff
+```
+
+`akm config migrate` acquires a file lock (`<config-dir>/.akm/migrate.lock`)
+before writing, so concurrent akm commands launched while a migrate is in
+flight block cleanly rather than racing. Pass `--no-wait` to fail immediately
+instead of blocking.
+
+**CI/CD note:** On read-only mounts (e.g. ephemeral containers), set
+`AKM_NO_AUTO_MIGRATE=1` and run `akm config migrate` explicitly during the
+deploy pipeline — before any command that reads config — so the config file is
+rewritten once at deploy time and the container never tries to write at runtime.
+
+### Verifying the config migration
+
+```sh
+# Confirm configVersion is present
+akm config get configVersion
+
+# Confirm profiles resolved
+akm config get profiles.llm
+
+# Confirm profile tree populated
+akm config get profiles.improve.default
+
+# Smoke test: confirm improve resolves cleanly without invoking the runner
+akm improve --dry-run
+```
+
+## Config layer rewrite (late-0.8.x)
+
+Late in the 0.8.x cycle the config layer was rewritten end-to-end around a
+single Zod schema in `src/core/config-schema.ts`. The on-disk shape is
+unchanged — `~/.config/akm/config.json` from before the rewrite still loads.
+But several behaviors that used to be silent are now loud, and a handful of
+configurations that used to silently misbehave are now rejected.
+
+### Behavior changes you should know about
+
+1. **`akm config set llm.apiKey` and friends now throw.** Persisting API keys
+   in the config file leaked them through backups and version control. The new
+   behavior is to throw `UsageError` pointing at the environment variable
+   instead:
+
+   - `llm.apiKey` → `AKM_LLM_API_KEY`
+   - `embedding.apiKey` → `AKM_EMBED_API_KEY`
+   - `profiles.llm.<name>.apiKey` → `AKM_PROFILE_<NAME>_API_KEY` (with `-`
+     normalized to `_` and uppercased)
+
+   If you had `apiKey` in your config before, it was silently stripped on the
+   first save; that behavior is unchanged for already-loaded configs. The
+   throw only fires on new `akm config set` invocations.
+
+2. **Malformed config JSON now throws.** Before the rewrite, if your
+   `config.json` had a syntax error, AKM silently fell back to `DEFAULT_CONFIG`
+   and your settings appeared to vanish. Now you get a clear
+   `ConfigError("Failed to parse config JSON")` with the underlying JSON parse
+   error. Fix the syntax error and AKM resumes normal operation. The
+   file-not-existing case is still the legitimate cold-start path.
+
+3. **Project-level `.akm/config.json` files are deprecated.** AKM still merges
+   them into the loaded config in 0.8.x (giving you one release of grace), but
+   you'll see a one-time warning on first discovery:
+
+   ```text
+   [akm] DEPRECATED: project-level config file found at <path>.
+   Project-level config files will be ignored in 0.9.0+.
+   Move your settings to ~/.config/akm/config.json.
+   ```
+
+   If you relied on this, plan to migrate your project-level settings to the
+   user config before 0.9.0 ships.
+
+4. **Every schema-leaf key is now reachable via `akm config set`.** Previously
+   the CLI maintained a hand-listed whitelist of settable keys, and several
+   common ones (`defaults.agent`, `search.minScore`, `improve.eventRetentionDays`,
+   `embedding.provider`, `llm.temperature`, `profiles.llm.<name>.*`,
+   `profiles.agent.<name>.*`, `improve.utilityDecay.halfLifeDays`,
+   `feedback.requireReason`, `index.metadataEnhance.enabled`, etc.) were
+   missing. The schema is now the source of truth — if it's in the schema,
+   you can set it. If you have a script that worked around this by editing
+   `config.json` directly, you can now use `akm config set` instead.
+
+5. **Unknown keys in nested objects are now rejected.** Before, an unknown
+   key inside `registries[]`, `sources[]`, or `profiles.llm.*` was silently
+   accepted. The schema now uses `.strict()` on those objects — unknown keys
+   throw with a path-pointing error (e.g. `registries.0.somethingTypo:
+   Unrecognized key(s)`). Fix the typo or remove the key.
+
+6. **Config backups are bounded to 5.** Each `akm config set` keeps a
+   timestamped backup of the previous config under `~/.cache/akm/config-backups/`.
+   Before the rewrite this was unbounded and could accumulate thousands of
+   entries; now it's pruned to the 5 most recent on each save.
+   `config.latest.json` is preserved separately and continues to hold the
+   most recent pre-write copy.
+
+7. **`akm config validate` and `akm config migrate` are real subcommands.**
+   Before, both lived in the codebase but weren't wired into the CLI surface
+   — error messages that referenced them were misleading. Now:
+
+   ```sh
+   akm config validate         # check the on-disk file against the schema
+   akm config migrate           # migrate legacy shape to 0.8.0 in place
+   akm config migrate --dry-run # preview the migration without writing
+   ```
+
+8. **`defaultWriteTarget` validation tightened.** It must name a configured
+   source in `sources[]`. With no sources configured, save-time validation now
+   errors rather than silently accepting an unresolvable name.
+
+### Manual migration
+
+If you have a custom config beyond the documented surface — especially
+project-level `.akm/config.json` files, env-var literals stored in non-`apiKey`
+fields, or manually-edited unknown fields — read this section carefully.
+
+- **Project-level configs (deprecated):** move every setting that lives in a
+  `.akm/config.json` somewhere under your project tree into your
+  `~/.config/akm/config.json`. After 0.9.0 the project-level discovery will
+  be removed entirely.
+- **Unknown fields you added by hand:** the strict-mode parser will now reject
+  them. Either move them to a documented key, or accept that they were never
+  doing anything anyway.
+- **`apiKey` in your config file:** export the appropriate env var instead and
+  remove the field from the JSON. AKM reads the env var on every connection.
+- **CI scripts that captured `akm config set llm.apiKey`:** swap for
+  `export AKM_LLM_API_KEY=...` before the `akm` command.
+