akm-cli 0.9.31 → 0.10.261002-beta

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

@@ -0,0 +1,507 @@
+# Moving from akm 0.9 to 0.10
+
+0.10 is a clean-up and tuning release. It adds no `state.db` migration and
+does not change the `index.db` layout (still 26). It does remove CLI
+spellings, built-in improve strategies and a few workflow features, it changes
+what a nightly `akm improve` does on its own, and it changes how releases are
+numbered. This guide lists what to do, in order, and every change that can
+break a script, a task or a config.
+
+Checked against the `release/0.10.0` branch at build 0.10.26101202. The
+user-facing summary of the whole series is the
+[0.10.0 release note](release-notes/0.10.0.md); the per-build detail is in the
+[CHANGELOG](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).
+
+## What the upgrade preserves
+
+- config, `state.db`, `index.db`, task sources, frozen workflow plans and
+  scheduler rows that 0.9.15 or later wrote;
+- every authored asset in your bundles;
+- the `akm upgrade` and `akm migrate` commands, with the same behaviour.
+
+## What it does not cover
+
+0.10 reads what 0.9.15 and later wrote and converts nothing older. A config
+still in the old `stashDir` / `sources[]` / `installed[]` layout, or one with an
+`engines.<name>.extraParams` key that shadows a first-class engine field,
+fails to load with one message that names `akm migrate apply` under akm 0.9.x.
+An install older than 0.9.15 must go through 0.9.x first (step 1).
+
+## Upgrade procedure
+
+### 1. Check your starting point
+
+```sh
+akm --version
+akm migrate status
+akm workflow list --active
+```
+
+- **Older than 0.9.15?** Install 0.9.31 first (`npm install -g akm-cli@0.9.31`,
+  or the same with Bun or pnpm, or the standalone binary from the `v0.9.31`
+  GitHub release), run `akm migrate apply` under it, then continue. Once 0.10
+  is the `latest` release, a plain `akm upgrade` would skip that step.
+- **0.9.15 or later?** `akm migrate status` should end with `status: "current"`.
+  If it does not, run `akm migrate apply` now, under 0.9.x, and read what it
+  changed.
+- **Workflow runs in flight.** A stored run whose plan has a `route` step or a
+  `script` target (both came from features 0.10 removed) cannot be decoded in
+  0.10; `akm workflow run` abandons it. A run whose plan has `unit.isolation`
+  still decodes and runs in the engine's working directory. Let active runs
+  finish, or abandon them on purpose, before you upgrade.
+- **Quit OpenCode.** `akm upgrade` skips (reports `deferred`) a plugin update
+  while an OpenCode process runs. See [Plugins](#plugins).
+
+### 2. Find the callers that need a change
+
+The spellings in the [CLI](#cli-spellings-that-are-gone) and
+[improve](#improve-strategies-tasks-and-config-keys) tables are unknown flags
+or commands in 0.10 (exit 2, `UNKNOWN_FLAG` / `UNKNOWN_COMMAND`), with no alias
+and no hint that points to the new spelling. Search your scripts, hooks,
+agent instructions, scheduled tasks and crontab for them before you upgrade:
+
+```sh
+grep -rnE -- '--shape|--target|help agents|task (list|validate)|config path --all|--reset|improve .*(--plan|--auto-accept|--run|--since)|--strategy +(quick|reflect-distill|thorough|catchup|proactive-maintenance)' <your script and task directories>
+crontab -l | grep akm
+```
+
+`--target` is still valid on `env run`, `bundle remove`, `bundle update` and
+`registry remove` (it names the thing to act on there). Read each hit.
+
+### 3. Upgrade the program
+
+```sh
+akm upgrade --check
+akm upgrade
+akm --version
+```
+
+`akm upgrade` installs the newer release, then runs `akm-migrate apply` (the
+migrator that shipped with the new install), then updates the harness plugins.
+It exits 1 when the migration is blocked.
+
+- **Release channels.** 0.10 releases are `0.10.YYMMNN`. Prereleases
+  (`-alpha`, `-beta`, `-rc`) publish to the npm `next` tag and stable builds to
+  `latest`; `akm upgrade --next` follows `next`. See
+  [Version numbers](#version-numbers).
+- **OpenCode plugin installed?** `akm upgrade` holds the CLI to the `akm-cli`
+  version the plugin pins (see [Plugins](#plugins)). If the CLI stays on
+  0.9.x and the output says it was held back, the plugin on that channel has
+  not published a 0.10 build yet.
+- You can install a specific version directly with npm, Bun or pnpm
+  (`akm-cli@<version>`), or replace the standalone binary after checking its
+  published checksum.
+
+### 4. Apply the config migration
+
+```sh
+akm migrate status
+akm migrate apply --dry-run
+akm migrate apply
+```
+
+`akm upgrade` already ran `apply`; run `status` to confirm. What `apply` does
+in 0.10:
+
+- rewrites `config.json` through the normal load path, under a backup in
+  `<cache dir>/config-backups/`, and drops every retired or unknown key (the
+  [removed keys](#improve-strategies-tasks-and-config-keys) below);
+- applies pending `state.db` migrations. 0.10 adds none, so on a 0.9.31 install
+  this step has nothing to do;
+- rewrites task files still at version 2 or 3 as task source v4 and reports
+  any it cannot convert as `blocked`;
+- removes superseded residue files.
+
+Until you run it, a retired key in `config.json` is harmless: the config loads,
+names the key once, and ignores it.
+
+### 5. Fix what the migration cannot
+
+- **`defaults.improveStrategy` or `--strategy` names a removed strategy.** The
+  config still loads, but `akm improve` fails (exit 78) with an error that names
+  `default`. `akm health` reports it as the warning `active-improve-strategy`.
+  Change the name, or define a strategy of that name yourself (below).
+- **Scheduled tasks that call a removed strategy, flag or command.** Edit the
+  task source, then run `akm task sync`. Tasks copied from the shipped
+  templates `akm-improve-nightly`, `akm-improve-frequent` and
+  `akm-improve-catchup` keep their `--strategy`; change it to `default` or
+  `consolidate`.
+- **A consolidate task copied from the shipped template** runs with the old
+  2-hour budget. The shipped `akm-improve-consolidate` task now passes
+  `--timeout-ms 3600000` so its 00:20 run ends before a 02:00 nightly; add the
+  flag to your copy if you run both.
+- **Workflows.** Rewrite any `.yml` workflow as Markdown and remove the
+  [removed workflow features](#workflows).
+- **Pasted agent guides.** If you pasted `akm help agents` output into an
+  `AGENTS.md` or a system prompt, regenerate it with
+  `akm hints --detail brief` (or `akm hints` for the complete guide). The old
+  text uses `--shape`.
+
+### 6. Update the plugins and other callers
+
+See [Plugins](#plugins). Do this in the same sitting: a 0.9 plugin passes
+`--shape agent`, which 0.10 rejects, and a 0.10 plugin passes `--detail agent`,
+which 0.9 rejects.
+
+### 7. Verify
+
+See [Verify the upgrade](#verify-the-upgrade).
+
+## Breaking changes
+
+### CLI spellings that are gone
+
+Each is an unknown flag or command (exit 2) from 0.10.
+
+| Gone | Use |
+| --- | --- |
+| `akm help agents` | `akm hints` (complete guide); `akm hints --detail brief` for the short one |
+| `--shape agent` (any command) | `--detail agent` |
+| `--shape summary` (only `akm show` used it) | `--detail brief` |
+| `--detail` values | now `brief`, `normal`, `full`, `agent`; `agent` trims `search`, `curate` and `show`, other commands ignore it |
+| `--target` on `import`, `env create`, `env remove`, `secret set`, `proposal accept`, `proposal diff`, `proposal revert` | `--bundle` |
+| `akm task validate <path>` | `akm lint --type tasks` (also runs the two gates `akm task sync` runs; point `--dir` at a bundle root, not a file) |
+| `akm task list` | `akm search --type task` |
+| `akm config path --all` | `akm info` (reports the bundle, config, data, cache and state directories) |
+| `akm improve --plan` | `akm improve --dry-run` |
+| `akm improve --auto-accept` | `akm improve && akm proposal drain --promote --yes`, or a `triage` block with `applyMode: "promote"` |
+| `akm improve --run`, `akm improve --since` | `akm improve report --run` / `--since` |
+| `akm workflow create --reset` | `--force` (alone: replace with a fresh template; with `--from <file>`: replace from the file) |
+
+Also gone, with no replacement needed:
+
+- every hint that told you the new spelling of a retired 0.9.0 command or
+  flag. A retired command is now a plain `UNKNOWN_COMMAND` (with a "did you
+  mean" only when the name is close) and a retired flag a plain `UNKNOWN_FLAG`;
+- the error codes `INVALID_SHAPE_VALUE`; `INVALID_DETAIL_VALUE` now lists
+  `agent`;
+- `task run` and `task explain` no longer reserve the input name `target`.
+
+`akm improve report` and `akm improve judge` are now real subcommands. Both
+spellings you used before still work; `--run` and `--since` belong to `report`
+alone, and `--strategy` is also `judge`'s own flag. `akm improve [scope]` is
+unchanged. `akm improve canary` is now an asset-type scope that matches nothing.
+
+### Improve strategies, tasks and config keys
+
+**Built-in strategies.** Only `default` and `consolidate` are built in.
+
+| Removed | Why / what to do |
+| --- | --- |
+| `quick` | Measured at 0.75 to 0.76 of items solved against `default`'s 0.89 to 0.92. For a reflect-only run, define your own (below). |
+| `reflect-distill` | Same measurement (0.77 to 0.78). Use `default`. |
+| `thorough` | Added only a judged triage drain, which harmed items. Use `default`. |
+| `catchup` | Identical to `consolidate` on the pool. Use `consolidate`. |
+| `proactive-maintenance` | The lane now lives in `default`. |
+
+A `improve.strategies.<name>` block with one of these names stays valid as an
+ordinary user-defined strategy, but it now inherits `default` and no longer
+carries the old built-in's settings. A reflect-only replacement for `quick`:
+
+```json
+{
+  "improve": {
+    "strategies": {
+      "reflect-only": {
+        "processes": {
+          "distill": { "enabled": false },
+          "consolidate": { "enabled": false },
+          "memoryInference": { "enabled": false },
+          "triage": { "enabled": false },
+          "validation": { "enabled": false },
+          "proactiveMaintenance": { "enabled": false }
+        }
+      }
+    }
+  }
+}
+```
+
+**Shipped task templates.** `akm-improve-nightly`, `akm-improve-frequent` and
+`akm-improve-catchup` are gone. The nightly template for a server install is
+now `core/improve` (`akm improve --require-engines`, 02:00), and `akm setup`
+preselects it.
+
+**Config keys.** These are removed. A config that still sets one loads (the key
+is named once by the unknown-key warning and ignored), and `akm migrate apply`
+drops it. Paths are under `improve.strategies.<name>.processes.` unless noted.
+
+| Removed key | Note |
+| --- | --- |
+| `consolidate.antiCollapse`, `consolidate.p90ChunkSecondsDefault`, `consolidate.minPoolSize`, `distill.fidelityCheck`, `reflect.lowValueFilter`, `improve.salience.outcomeWeightEnabled` | Measured no effect. The `pool_below_min_size` skip reason goes with `minPoolSize`. |
+| `improve.salience.salienceThreshold` | The high-salience lane it tuned is gone. |
+| `distill.limit`, `memoryInference.cls`, `proactiveMaintenance.limit`, `triage.policy` | Nothing read them. `distill.cls` and the `limit` of `reflect` and `consolidate` are read and stay. |
+| `defaults.llm`, `defaults.agent`, `defaults.improve`, `feedbackDistillation`, `index.<pass>.{endpoint,provider,apiKey,baseUrl,temperature,maxTokens,capabilities}`, `index.stalenessDetection` | 0.9 rejected these with a bespoke error. They now load like any unknown key. |
+
+Config that is newly refused: a retired source key (`stashDir`, `sources`,
+`installed`) and an `engines.<name>.extraParams` key that shadows a first-class
+field (`temperature`, `maxTokens`, `enableThinking`, `reasoningEffort`). Both
+were only warned about in 0.9.15 and later; the error says to run
+`akm migrate apply` under akm 0.9.x.
+
+### Workflows
+
+Workflows are Experimental through 0.10. Removed:
+
+- **The GitHub-shaped YAML workflow format.** A `.yml` under `workflows/` is
+  skipped at index time with the message "must use .md". Rewrite it as
+  Markdown. This takes with it workflow-step `uses: tasks/<ref>`,
+  `uses: scripts/<ref>` and `uses: commands/<ref>`, YAML `on.schedule`
+  triggers, and the `script` frozen target. A task that runs a workflow
+  (`uses: workflows/<ref>`, or a `run:` that calls `akm workflow run`) is a
+  task feature and is unchanged.
+- **Top-level `outputs:`** (a lint error). A completed child workflow returns
+  the output of its last step; a parent reads `steps.<composing-step>.output`.
+- **`route` steps** (a lint error). Branch with an `exec` or agent step that
+  reads its inputs.
+- **`unit.isolation: worktree`** (a lint error).
+
+Child workflows stay, in a simpler form: a Markdown step declares
+`unit: { workflow: workflows/<name>, with: { <param>: <literal or { from: <reference> }> } }`.
+See [Workflow schema](../reference/workflow-schema.md#child-workflows).
+
+One change in the other direction: a param's `default:` is now applied. A run
+starts with each declared default for the params it was not given, where it
+used to leave them absent. Workflows that restated their defaults in prose can
+stop.
+
+### Internal surfaces and packaging
+
+- **`BundleAdapter.placeNew()`** is removed, with its nine implementations. It
+  was never called; every write already used the fixed type-to-directory table.
+  There is no behaviour change. A writable bundle in a non-akm layout would need
+  per-adapter placement back ([#1163](https://github.com/itlackey/akm/issues/1163)).
+- **`package.json` has an `exports` map**: `akm-cli/api`, `akm-cli/package.json`
+  and `akm-cli/dist/*`. `akm-cli/api` exports `curate` for in-process recall by
+  the plugins (see [Programmatic API](../reference/api.md)). Any other deep
+  import path no longer resolves.
+- **The task-source migrator moved** to `scripts/akm-migrate/migrate/` out of
+  `src/`. `akm migrate apply` and `akm-migrate apply` behave as before for data
+  0.9.15 and later wrote.
+- **Dropped runtime shims.** The `{kind, ref, sourceId}` write-back of
+  `scheduler.enabled` is gone: 0.10 writes plain refs and still reads the
+  object form. The `targetVocab` marker on `task_history` rows is no longer
+  written, and the `"mcp"` package keyword is gone (akm has no MCP code).
+
+## Behaviour changes you will notice
+
+### `akm improve`
+
+- **A nightly `akm improve` now drains the proposal queue.** The `default`
+  strategy runs triage in `promote` mode with judgment off, up to 200 accepts
+  a run (it was off before). It accepts proposals a quality judge already
+  stamped as passing, when their content has not changed since, and retirements
+  the consolidate pair pass staged with no continuity risk. It never accepts a
+  proposal from the proactive lane (reason `proactive-needs-review`), an
+  uncertain verdict, or a distill lesson. The judgment tier is off in every
+  built-in strategy and, if you turn it on, accepts only consolidate
+  promotions. To keep the old behaviour of leaving every proposal for you, set
+  this in config:
+
+  ```json
+  { "improve": { "strategies": { "default": { "processes": { "triage": { "enabled": false } } } } } }
+  ```
+
+  Every accept is an ordinary accept: a git-backed bundle gets the usual commit,
+  and `akm proposal revert` undoes it. A standalone `akm proposal drain` now
+  resolves to promote mode on a stock install, asks for confirmation, and needs
+  `--yes` when there is no terminal.
+- **The proactive-maintenance lane is on in `default`.** It plans up to 15
+  assets a run that have no fresh feedback and were not reflected or distilled
+  in the last 30 days. Its proposals wait for you. `--require-feedback-signal`
+  turns it off for one run; `processes.proactiveMaintenance.enabled: false`
+  turns it off in a strategy.
+- **Sync before the run.** On a git-backed bundle, a live run does what
+  `akm sync` does right after it takes its lock and before it plans: commit
+  pending edits in the managed paths, fetch, fast-forward or merge, push. A
+  conflict or a failed fetch warns and the run continues on local state. The
+  result carries `preRunSync`. `--no-sync` skips both the pre-run and the
+  end-of-run sync, and `--no-push` skips the push.
+- **Uncertain reflect verdicts go to a person.** A reflect revision the judge
+  does not pass but scores 3.5 or more becomes a pending proposal
+  (`judge-uncertain`, shown as `gate=deferred:judge-uncertain`) with no 14-day
+  lock on the asset. A lower score is refused as before. A distill lesson or
+  promotion whose judge is missing is queued for review, not locked out for 30
+  days.
+- **The retrieval regression gate is gone.** After the judge passed a revision,
+  reflect used to grade old and new text against the asset's retrieval queries
+  and refuse the revision if the grade fell. It refused 12 to 17 percent of
+  revisions the judge had passed. A judge-passed revision is now minted as a
+  proposal with no further check. The gate had no config key.
+- **`captureMode: hot` memories are consolidated like any other.** The pair pass
+  may retire one and the promote pass may promote and archive one.
+- **Distill can extend a lesson.** When a memory repeats an existing lesson, a
+  proposal on the lesson's own ref adds the new lines (reason `distill-update`).
+  It is left for a person.
+- **Retirements expire.** A retire proposal now expires by age like any other
+  (`archiveRetentionDays`, default 90) instead of never; `akm proposal reopen`
+  brings one back. One whose file or successor has changed is rejected once as
+  `stale-target`.
+- **Per-run log files are purged.** `$CACHE/logs/improve/` and
+  `$CACHE/logs/index/` files now follow `improve.eventRetentionDays` (default 90;
+  0 disables).
+- **`akm improve <scope>` warns** on stderr when the scope matches no asset,
+  naming the likely intended type. Exit code and plan are unchanged.
+- **A run killed by its budget watchdog** now leaves an `improve_runs` row
+  (`budget_exhausted`) and commits what it wrote, without pushing.
+
+### Feedback
+
+- **Manual fixes apply at once.** `akm feedback --negative ... --replace/--with/--source`,
+  `--superseded-by` and `--outdated` used to queue a `feedback` proposal for
+  `akm proposal accept`. They now file it and accept it in the same command
+  (gate decision `manual-fix`, no judge). If the accept refuses, the proposal is
+  rejected, the file is untouched and the command fails. Drop any follow-up
+  `akm proposal accept` from your scripts; use `akm proposal revert` to undo.
+- **Feedback changes search and curate ranking.** Each hit's score is
+  multiplied by `1 + 0.03 x (ln(1 + positives) - ln(1 + negatives))`, counting
+  your own feedback events for the asset (not improve, task or audit feedback).
+  The effect is small: about +2 percent, +3, +5 and +9 for 1, 2, 5 and 20
+  positives. It reorders close matches and does not override relevance, and it
+  takes effect without a reindex. `rankingUpdate.applied` in the `akm feedback`
+  output is now `true` exactly when the event counts toward ranking.
+- **Utility has one formula.** `akm feedback` and `akm index` now compute the
+  utility score the same way, so the stored value no longer depends on which ran
+  last. Improve and `akm metrics` read it; search does not.
+
+### Other commands
+
+- **`akm sync` fetches first.** On a writable bundle with a remote it fetches,
+  fast-forwards or merges what another host pushed, then pushes. A merge that
+  conflicts is aborted, your commit stays, the push is skipped and `reason`
+  names the files. Before this it failed with exit 70 once another host had
+  pushed.
+- **`akm search` no longer warns "no embedding provider is configured"** on a
+  default install. It warns only for a remote `embedding.endpoint` with no
+  `embedding.model`.
+- **Command tasks (`uses: commands/...`) get the 6-hour unattended timeout** that
+  workflow and shell tasks already had. An explicit task `timeout:`, an engine
+  timeout or `timeout: null` still wins.
+- **Memory inference** writes to the default bundle (it used the first bundle in
+  the list), and no longer reverts an edit made to the parent memory while the
+  model ran.
+- **The session summary prompt** fences the transcript as untrusted.
+- **A transient reflect failure** (transport error, timeout, crash) no longer
+  uses up the feedback that planned it; the ref is retried next run.
+
+## Deprecated in 0.10
+
+- **The `opencode` CLI dispatch path.** An agent engine with
+  `platform: "opencode"` runs `opencode run` for each call. It still works on
+  OpenCode 1 and 2 throughout 0.10, but it is deprecated and may be removed in
+  0.11 or later. Switch such engines to `opencode-sdk`, which covers the same
+  work, including a default agent for the engine.
+
+## Plugins
+
+| OpenCode | Package | Config key | Cache folder |
+| --- | --- | --- | --- |
+| 1 | `akm-opencode` | `"plugin"` | `~/.cache/opencode/packages/akm-opencode@<tag>/` |
+| 2 | `akm-opencode-v2` (new) | `"plugins"` | `~/.cache/opencode/npm/akm-opencode-v2@<tag>/<build>/` |
+
+(`$XDG_CACHE_HOME` moves both.) Install only the package for the OpenCode you
+run. For OpenCode 2, run `opencode plugin add akm-opencode-v2`.
+
+- **Each plugin pins one exact `akm-cli`.** It runs that CLI in-process, so
+  `akm upgrade` never moves the CLI past the pin, and with both plugins present
+  it holds the CLI to the older pin. It never moves the CLI backwards. If it
+  cannot read the pin it leaves the CLI alone and exits 1. `akm health` warns
+  when a plugin's bundled `akm-cli` differs from the running CLI.
+- **OpenCode caches the plugin spec it resolved, and never re-checks it.** A new
+  plugin build is not picked up until its cache folder is cleared. `akm upgrade`
+  does this for `@latest` (and `@next` with `--next`) when no OpenCode process
+  is running: it moves the folder to the trash, then re-fetches (`opencode debug
+  config` for OpenCode 1, `opencode plugin add akm-opencode-v2` for OpenCode 2).
+  If your config pins another spec, such as `akm-opencode@0.9.30`, `akm upgrade`
+  leaves it alone: change the spec, quit OpenCode, move that cache folder aside
+  and start OpenCode again.
+- **OpenCode 2 permission defaults.** akm rejects every OpenCode permission
+  request in a dispatch and changes no OpenCode default. OpenCode 1 asks before
+  reading or writing outside the project directory, so akm rejects it and the
+  model carries on. OpenCode 2 does not ask, so a read or write outside the
+  project just runs. To get the rejection on OpenCode 2, add a rule to the
+  global `opencode.json`, for example
+  `"permissions": [{"action": "external_directory", "resource": "*", "effect": "ask"}]`.
+  When akm rejects a request on OpenCode 2 the turn ends with `ok: false` and
+  `reason: "aborted"`. See [Configuration](../reference/configuration.md#engines).
+- **Which OpenCode akm drives is detected**, from the engine's `bin` (or
+  `opencode2`, else `opencode`, on `PATH`). There is no setting. OpenCode 1
+  logs one warning recommending OpenCode 2; a binary of an unknown major is
+  driven as OpenCode 2 with a warning.
+- **Claude Code and Codex plugins** come from the `akm-plugins` marketplace and
+  are updated by `akm upgrade`. Use the 0.10 plugin set with 0.10 (it passes
+  `--detail agent`; see itlackey/akm-plugins#133).
+- **Other callers.** Anything of yours that passes `--shape agent` (benchmark
+  runners, hooks) needs `--detail agent` and akm 0.10 together. akm-eval's
+  retrieval, skillret and longmemeval benchmarks are the known ones
+  (itlackey/akm-eval#33).
+- **A signal to `akm agent` now ends the harness.** `akm agent` on the
+  `opencode`, `claude` and `codex` CLI engines runs the harness in its own
+  process group, and SIGTERM or SIGINT to akm now takes it down too.
+
+## Version numbers
+
+From 0.10 a release is numbered `0.10.YYMMNN`: the UTC year and month, then the
+release within that month (`01` to `99`), two digits each. The first release of
+2026-10 is `0.10.261001`. Every release takes the next number, whatever its
+stage. A prerelease carries its stage only (`0.10.261001-alpha`, `-beta`,
+`-rc`), and a build is not promoted through stages under one number. Prereleases
+go to the npm `next` tag and stable releases to `latest`. Versions sort by
+month and then number, so `akm upgrade` and semver ranges order them correctly.
+The patch number no longer says how big a change is: read the CHANGELOG, which
+still marks breaking changes. The 0.9 line keeps `0.9.N`, and 0.11 restarts on
+the same scheme.
+
+**If you installed a 0.10 daily alpha** (`0.10.26101001-alpha` through
+`0.10.26101202-alpha`, an 8-digit patch), `akm upgrade` will not offer the
+monthly numbering: semver compares the patch numerically, so `0.10.261001` is
+below every daily alpha. Install the first monthly release explicitly once, for
+example `npm install -g akm-cli@0.10.261001-beta`; `akm upgrade` works normally
+from there.
+
+`akm help migrate 0.10.0` prints the [0.10.0 release note](release-notes/0.10.0.md).
+The loader looks a note up by its exact file name, so `akm help migrate latest`
+and a release number such as `0.10.261001` print the CHANGELOG section
+only.
+
+## Verify the upgrade
+
+```sh
+akm --version              # the 0.10.YYMMNN you meant to install
+akm migrate status         # status "current", ok true
+akm health                 # exit 0 ok; 4 means a warning, read the check names
+akm task doctor            # scheduler backend, akm path, engines, improve triage and autonomy
+akm upgrade --check        # per-plugin outcomes: current, pending, deferred, failed
+akm improve --dry-run      # the strategy resolves, plan.triage shows the drain
+akm lint --type tasks      # task files parse and pass the gates task sync runs
+akm lint --type workflows  # workflows parse; no .yml, route, outputs or isolation
+akm search --type task     # your tasks are indexed
+```
+
+Things to look for:
+
+- `akm health` check `active-improve-strategy` warns when the configured
+  strategy was removed.
+- `akm task doctor` reports `improveTriage` (enabled, mode) and
+  `improveAutonomy` with the lanes the `experimental.improveAutonomy` gate holds
+  off.
+- `akm health` check `state-db-migrations` passes with nothing applied.
+- After one scheduled `akm improve`, `akm log` shows `stash_synced` events with
+  `phase: "pre-run"` on a git-backed bundle, and `akm proposal list` shows what
+  the drain left for you.
+
+## Recovery
+
+0.10 changes neither database schema, so a downgrade needs no data change. To
+go back, stop AKM and any OpenCode process, install the earlier version
+(`akm-cli@0.9.31`), and restore `config.json` from the backup that
+`akm migrate apply` wrote under `<cache dir>/config-backups/` if you want the
+dropped keys back. Downgrade the plugins with the CLI: a 0.9 CLI rejects
+`--detail agent` and a 0.10 CLI rejects `--shape agent`.
+
+For the CHANGELOG entries behind each item, see the
+[CHANGELOG](https://github.com/itlackey/akm/blob/main/CHANGELOG.md) sections
+`0.10.26101001` to `0.10.26101202` (the daily alphas) and the monthly releases after them. For the stability tier of each command, see
+[STABILITY.md](https://github.com/itlackey/akm/blob/main/STABILITY.md). The
+rules each improve process follows in 0.10 are in
+[the 0.10 process rules](../architecture/0.10-process-rules.md).

package/docs/posts/akm-command-tour.md

@@ -99,7 +99,7 @@ Use this to inspect or change settings.
 ```sh
 akm config get output.format
 akm config set output.detail full
-akm config path --all
+akm info
 ```
 
 Real-world use: your agent prefers text output in one repo and JSON in another, or you want to set a default write target for memories and imports.
@@ -404,12 +404,12 @@ akm help migrate latest
 
 Real-world use: you upgraded `akm` and want the release-specific migration notes without leaving the terminal.
 
-### `akm help agents`
+### `akm hints`
 
 Print instructions you can drop into `AGENTS.md` or `CLAUDE.md`.
 
 ```sh
-akm help agents
+akm hints
 ```
 
 Real-world use: you want every project to tell its coding agent how to use the local `akm` installation.

package/docs/product-surface.md

@@ -28,7 +28,7 @@ Every akm feature, with its status. Status meanings are in
 - [`akm improve` and proposals](guides/improve-the-library.md): reviewable changes from feedback and usage. *Evolving*
 - Improve settings and strategies other than `default` and `consolidate`. *Experimental*
 - Automatic acceptance (opt-in). *Experimental*
-- Session extraction. *Experimental*
+- Session extraction. *Evolving*
 
 ## Monitor
 

package/docs/reference/README.md

@@ -2,6 +2,7 @@
 
 Authoritative reference documentation for the akm CLI and its data.
 
+- [Programmatic API](api.md) -- `akm-cli/api`: in-process `curate()` for the akm plugins
 - [Bundle Types](bundle-types.md) -- Supported bundle formats and compatibility
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Configuration](configuration.md) -- Engines, strategies, bundles, and settings

package/docs/reference/api.md

@@ -0,0 +1,65 @@
+# Programmatic API (`akm-cli/api`)
+
+`akm-cli` is a CLI package. The one supported programmatic entry point is
+`akm-cli/api`, which exists so the akm plugins (OpenCode, Claude Code, ...) can
+do their automatic recall in-process instead of starting an `akm` process per
+prompt. Everything else in the package stays CLI-only: deep imports of
+`akm-cli/dist/*` are not an API, and the CLI is still the way to run every
+other command.
+
+```ts
+import { curate } from "akm-cli/api";
+
+const text = await curate("deploy to prod", { limit: 4, type: "skill", format: "text" });
+```
+
+## `curate(query, options?)`
+
+```ts
+function curate(
+  query: string,
+  options?: { limit?: number; type?: string; format?: "text" | "json" },
+): Promise<string>;
+```
+
+- **Result.** Exactly the stdout of
+  `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`,
+  including the trailing newline, computed in-process. `format` defaults to
+  `"json"`, as the CLI does. It runs the same code as the command (argument
+  validation, search, ranking, shaping and rendering are shared, not copied), so
+  the two cannot drift.
+- **Failure.** It rejects with an `Error` whose `message` is the CLI's error
+  text and whose `code` is the CLI's error code (`MISSING_REQUIRED_ARGUMENT`,
+  `INVALID_FLAG_VALUE`, `INVALID_CONFIG_FILE`, ...) wherever the CLI would have
+  failed. An unexpected internal failure rejects with a plain `Error` without a
+  `code`.
+- **No side effects on the host.** No child process; nothing is written to
+  stdout or stderr; `process.chdir` is never called; `process.env` and
+  `process.argv` are not modified; the host's quiet and verbose state is
+  unchanged afterwards. As with `akm curate`, the call records its usage
+  event in `state.db`.
+- **Repeated calls.** Config is re-validated against `config.json` on every
+  call (its path, size and modification time), so an edit on disk is seen by
+  the next call exactly as a separate CLI run would see it. Database handles are
+  opened and closed within each call. The local embedding model and the embedding
+  cache are kept for the life of the process, which is what makes a warm call
+  cheaper than a CLI run. Overlapping calls are safe. Under Bun the SQLite file
+  descriptors of a finished call are released when the garbage collector
+  finalizes its statements, so they can briefly outlive the call.
+
+## Loading it
+
+`package.json` `exports` maps `akm-cli/api` to `dist/api.js` under Bun and to
+`dist/api-node.mjs` under Node (which registers the loader hook for the
+package's embedded `.md`/`.xml` assets before loading `dist/api.js`), with
+`dist/api.d.ts` for types. `akm-cli/package.json` and `akm-cli/dist/*` are also
+exported, so a plugin can locate the `akm` bin with
+`require.resolve("akm-cli/package.json")` and published plugin versions that
+deep-import `akm-cli/dist/commands/read/*.js` keep working.
+
+## Stability
+
+Evolving (see [STABILITY.md](../../STABILITY.md)): the export list only grows,
+and `curate()`'s parameters and result keep the contract above; the text it
+returns is the CLI's agent-shaped output and changes whenever that does.
+`tests/contracts/api-surface.test.ts` pins the export list.

package/docs/reference/asset-types.md

@@ -40,7 +40,7 @@ my-bundle/
   instructions/   # Project guidance (.md)
   env/            # Environment files (.env) — groups of related config, loaded whole
   secrets/        # Secrets — one sensitive value per file (auth tokens, keys, certs)
-  workflows/      # Peer workflow sources (.md and .yml)
+  workflows/      # Workflow sources (.md)
   lessons/        # Distilled lessons (.md, see akm improve / proposals)
   memories/       # Recalled context fragments (.md, see Memory reference)
   facts/          # Durable bundle-level facts (.md)
@@ -60,10 +60,8 @@ Scripts and knowledge are classified by **what they are**: a `.sh` file is a
 script; a plain `.md` file is knowledge. Commands and agents are classified
 by **how an LLM should use them**: a `.md` file with `$ARGUMENTS`
 placeholders is a command template; one with `tools` in its frontmatter is an
-agent definition. Workflow assets may be `.md` or `.yml`: Markdown is
-classified by `type: workflow` or placement, while the GitHub-shaped YAML
-adapter validates the closed workflow subset. These are peer workflow sources,
-not an md-only surface. Skills are a
+agent definition. Workflow assets are `.md`, classified by `type: workflow`
+or placement. Skills are a
 **packaging convention**: a directory containing a `SKILL.md` file.
 
 See [Classification](../architecture/internals/classification.md) for the

package/docs/reference/bundle-types.md

@@ -3,8 +3,7 @@
 This page has moved. AKM's bundle-format documentation is now split in two:
 the public compatibility table lives at
 [Supported Formats](supported-formats.md), and the adapter internals — probe
-order, the `BundleAdapter` interface, `placeNew()` wiring status, and the
-write allowlists — live at
+order, the `BundleAdapter` interface, and the write allowlists — live at
 [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md).
 
 - [Supported Formats](supported-formats.md) — the format-by-format table:
@@ -13,7 +12,6 @@ write allowlists — live at
   `llm-wiki`, `claude`, `opencode`, `agent-skills`, `dotenv`,
   `akm-workflow`, `akm-task`, `website-snapshot`, `generic-files`).
 - [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks an
-  adapter for a bundle, the `BundleAdapter` interface contract, the current
-  `placeNew()` wiring status, the write allowlists that actually gate
+  adapter for a bundle, the `BundleAdapter` interface contract, the write allowlists that actually gate
   `akm remember`/`import`/`proposal accept`/etc., and per-adapter
   implementation caveats.