akm-cli 0.10.261012-beta → 0.10.261014-beta

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

@@ -1,13 +1,16 @@
 # 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
+0.10 is a clean-up and tuning release. It replaces the `engines` in your config
+with `connections` (the endpoints akm sends model requests to) and `harnesses`
+(the agent programs you already have), and runs OpenCode 2 inside akm. 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 build 0.10.261013 with the connections and harnesses rework
+(#1244). 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).
@@ -15,16 +18,17 @@ user-facing summary of the whole series is the
 ## What the upgrade preserves
 
 - config, `state.db`, `index.db`, task sources, frozen workflow plans and
-  scheduler rows that 0.9.15 or later wrote;
+  scheduler rows that 0.9.15 or later wrote; a config in the `engines` form
+  loads as `connections` and `harnesses` until you migrate it (see
+  [Connections, harnesses and OpenCode](#connections-harnesses-and-opencode));
 - 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.
+still in the old `stashDir` / `sources[]` / `installed[]` layout 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
@@ -45,10 +49,16 @@ akm workflow list --active
   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`
+  `script` target (both came from features 0.10 removed), or a command target
+  frozen before plan version 8 (it froze an engine), cannot be decoded in 0.10;
+  `akm workflow run` abandons it (status `failed`) and names `akm workflow run
+  <ref>` to start afresh. 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.
+  finish, or abandon them on purpose, before you upgrade. In 0.10
+  `akm workflow run <ref>` always starts a new run (`akm workflow run <run-id>`
+  continues one; `resume` only re-activates a blocked or failed one), runs are no longer scoped
+  to a directory, and 0.9.15 does not see runs 0.10 started on the same
+  `state.db`. `--new` and `--all-scopes` are accepted and do nothing.
 - **Quit OpenCode.** `akm upgrade` skips (reports `deferred`) a plugin update
   while an OpenCode process runs. See [Plugins](#plugins).
 
@@ -68,6 +78,11 @@ 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.
 
+`--engine NAME` is not in that list because it still runs, but search for it
+too (`grep -rn -- '--engine' <your script and task directories>`): after the
+migration it reaches only a connection or harness called `NAME`
+([step 5](#5-fix-what-the-migration-cannot)).
+
 ### 3. Upgrade the program
 
 ```sh
@@ -103,24 +118,57 @@ 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);
+- rewrites `config.json` under a backup in `<cache dir>/config-backups/`: the
+  `engines` / `defaults` form becomes `connections` / `harnesses`, the keys akm
+  no longer reads from config move to `credentials.json`, a leftover
+  `models.json` is folded in and moved, and every other retired or unknown key
+  is dropped (see [Connections, harnesses and
+  OpenCode](#connections-harnesses-and-opencode) and 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`;
+- rewrites the retired `engine:` key on commands, agents, workflows and task
+  sources to `connection:` or `harness:`, under one backup directory per run;
 - 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.
+Until you run it, a config in the `engines` form loads as `connections` and
+`harnesses` in memory, with one warning that names `akm migrate apply`, and any
+other retired key 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).
+- **`improve.strategy` (was `defaults.improveStrategy`) or `--strategy` names a
+  removed strategy.** The config still loads, but `akm improve` and `akm task
+  doctor` fail (exit 78, `UNKNOWN_IMPROVE_STRATEGY`) with an error that names
+  `default`. Change the name, or define a strategy of that name yourself (below).
+- **Notes from `akm migrate apply`.** Each names a setting it dropped, or a key
+  or an entry it could not move. A key it could not move stays on its connection
+  as `apiKey`, which akm warns about and never sends: put it in
+  `credentials.json` (`akm setup` does) or reference an environment variable
+  (`"apiKey": "$NAME"`). `AKM_ENGINE_<NAME>_API_KEY` and `AKM_LLM_API_KEY`
+  become an `apiKey` only when they were set in the environment you ran `apply`
+  in; if not, the connection has no key and a note names the variables. Set the
+  one you used and run `akm setup --api-key-env NAME`, or store the key with `akm
+  setup`.
+- **Scripts that pass `--engine` or `--require-engines`.** They keep running,
+  with one warning each. Change `--engine NAME` to `--connection <name>` or
+  `--harness <name>`: how an old engine name resolves, and when it stops, is
+  under [The `engines` form](../reference/configuration.md#the-engines-form).
+  `--require-engines` does nothing now, and a scheduled caller that relied on it
+  loses its guarantee: the run no longer checks, before any side effect, that
+  every enabled process has a usable target (a configured connection or harness
+  to run on, a harness program that exists, a connection that answers). `akm
+  improve` stops at planning (exit 78) only when no process has anywhere to
+  run; when some do and some do not, it runs the ones that do and lists the
+  rest in `skippedProcesses`. Use `akm health` for the check: `akm health &&
+  akm improve ...` stops before the run when it exits 4, and its
+  `connections-and-harnesses` check names each connection that does not answer,
+  each harness program that is not installed and a missing default. It looks at
+  the configuration and the endpoints, not at whether a completion works (only a
+  run shows that).
 - **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
@@ -219,8 +267,15 @@ carries the old built-in's settings. A reflect-only replacement for `quick`:
 
 **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.
+now `core/improve` (`akm improve`, 02:00), and `akm setup` preselects it. A
+scheduled command written for 0.9 keeps running: `--require-engines` is
+accepted and does nothing (the run stops at planning, exit 78, only when no
+process has a connection or harness to run on; the check it used to make, that
+every enabled process has a usable target, is gone, and `akm health` is the
+replacement), and `--engine NAME` on `agent`,
+`command run`, `task add`, `proposal new` and `proposal extract` keeps running
+([step 5](#5-fix-what-the-migration-cannot)). Each warns once, and neither is
+listed in `--help`.
 
 **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`
@@ -232,12 +287,19 @@ drops it. Paths are under `improve.strategies.<name>.processes.` unless noted.
 | `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. |
+| `execution.allowedTools` (top level) | Asset tool requests are gone (below), so there is nothing to cap. |
+
+**Asset `tools:`.** Agents, commands and tasks no longer restrict an agent's
+tools: an agent or command's `tools:` (or a Claude command's
+`allowed-tools:`) is not read, and a task's `tools:` is ignored with a warning.
+`akm show` no longer reports `toolPolicy`, a file is no longer recognized as an
+agent by a `tools:` key alone, and the `EXECUTION_NOT_AUTHORIZED` error is gone.
+To run an agent with restricted tools, define that agent in the harness itself
+(a Claude or OpenCode agent) and select it with the harness's `agent`.
 
 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.
+`installed`). It was only warned about in 0.9.15 and later; the error says to
+run `akm migrate apply` under akm 0.9.x.
 
 ### Workflows
 
@@ -283,6 +345,169 @@ stop.
   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).
 
+### Connections, harnesses and OpenCode
+
+`engines` become `connections` and `harnesses`, `akm setup` and `akm health`
+are rebuilt around them, and OpenCode 2 runs inside akm. Read this section even
+if you never wrote an engine: `akm migrate apply` rewrites your config and
+moves your keys.
+
+- **A connection** is an OpenAI-compatible endpoint (`endpoint`, `apiKey`,
+  `models`, `contextLength`, `timeoutMs`, `concurrency`; any other key, on the
+  connection or in a model entry, is a request field sent as written). **A
+  harness** is an agent program you already have (`platform`, `bin`, `args`,
+  `workspace`, `agent`, `timeoutMs`, `models`). There is no `defaults` block: the
+  entry named `default`, or the only entry, is the default connection or
+  harness, and anywhere one can be named and none is, the default is used. With
+  neither configured, model features and agent work are off and each command
+  that needs one points at `akm setup`; there is no fallback to an `opencode`
+  binary on `PATH`.
+- **Where a process runs** is set by `improve.connection` and `improve.harness`
+  (all of `akm improve`), `improve.processes.<process>`, `improve.qualityGate`
+  and `index`. A strategy says which processes run, never where.
+  `defaults.improveStrategy` is now `improve.strategy`.
+- **Aliases.** `fast`, `balanced` and `reasoning` are set on a connection's or
+  harness's `models`. `akm models` lists a connection's aliases, then the models
+  its endpoint lists, and `akm models set <alias> <model>` changes one.
+  `models.json` and the `akm models list` and `copy-defaults` commands are gone.
+- **Keys.** `apiKey` is a `$VAR` reference. Without one, the key is the entry
+  stored for the connection and its endpoint in `credentials.json`, next to
+  `config.json` (mode 0600); `akm setup` fills it from a masked prompt. A key is
+  read for the endpoint it was stored for and no other. A literal
+  `apiKey` in the file is warned about and never sent. `apiKeyFile`,
+  `${secrets/...}` and the implicit `AKM_ENGINE_<NAME>_API_KEY` and
+  `AKM_LLM_API_KEY` lookups are gone. Until `akm migrate apply` has filed it, a
+  key held in `apiKeyFile`, a literal or a `${secrets/...}` reference is not sent
+  (akm warns); `akm upgrade` runs `apply` for you.
+- **`akm setup`** takes one flag per question (`--endpoint`, `--api-key-env`,
+  `--name`, `--harness`, `--embedding`, `--embedding-endpoint`,
+  `--embedding-api-key-env`) and `--yes` for the detected default; `akm setup
+  --endpoint http://localhost:11434/v1 --yes` is the quick start. `--probe` and
+  `--config` are gone.
+- **`akm health` and `akm info`** print one table (the `connections-and-harnesses`
+  check, and `connectionsAndHarnesses` in `akm info`; a row for each
+  connection, each harness and each kind of work, with the connection or harness
+  and model it resolves to) in place of the engine checks. The checks
+  `default-engine`, `default-llm-engine`, `configured-engines`,
+  `active-improve-strategy`, `thinking-control` and `engine-last-used` are gone,
+  and an unreachable connection is a warning, not a failure.
+- **`--connection`, `--harness` and `--model`** replace `--engine` on `akm agent`,
+  `akm command run`, `akm proposal new`, `akm proposal extract` and `akm task
+  add`. A scheduled command that still passes `--engine NAME` or
+  `--require-engines` keeps running, with one warning each and neither listed in
+  `--help`; `--require-engines` does nothing (see above). `akm migrate
+  apply` renames the default engine `default` and moves an old `default` aside
+  to `legacy-default`; what `--engine` and `engine:` mean until it has rewritten
+  every key it can reach is under [The `engines`
+  form](../reference/configuration.md#the-engines-form). It cannot rewrite a
+  command line or script: change those to `--connection` or `--harness` yourself.
+- **`GET /api/config`** (the `akm ui` server) lists `connections` and `harnesses`
+  where it listed `engines`.
+
+**An old config still loads.** A `config.json` with `engines` and `defaults` is
+read as the new form in memory, with one warning that names `akm migrate
+apply`; the file is not rewritten until you run it. An ordinary `akm config
+set` edits the file as it is, and removing a value the old form supplies is
+refused until the file is migrated. A connection or harness whose own settings
+akm cannot use (no endpoint, an endpoint that is not a URL, a harness akm cannot
+run) is ignored with one warning naming it, and the rest of the file loads.
+
+**`akm migrate apply` converts the file.** Under a backup of `config.json` it
+writes `connections` and `harnesses`, renames the default LLM engine to
+`default` (references follow), moves what a strategy said about where a process
+runs to `improve.processes` and `improve.qualityGate`, and keeps a connection or
+harness the loader cannot use in the file, with a note on what to fix. It also:
+
+- moves every key akm no longer reads from config (an engine's `apiKeyFile`, a
+  literal or `${secrets/...}` `apiKey`, and the same on a connection,
+  `embedding` or `search.curateRerank`) into `credentials.json`, for the
+  connection (or the `embedding` or `curateRerank` service) and the endpoint the
+  block names, with one note per key and never its value. A key that cannot be
+  moved (its secret does not resolve, the block names no endpoint of its own, a
+  `connections` entry now gives it another endpoint than its engine wrote the key
+  for, or `credentials.json` already holds a different key or endpoint for that
+  slot) stays on the
+  connection as `apiKey`, with a note, until you move it. `AKM_ENGINE_<NAME>_API_KEY`
+  and `AKM_LLM_API_KEY`, when set in the environment you run `apply` in, become
+  `apiKey: "$VAR"` instead;
+- files a key in `credentials.json`'s older flat `{ "<name>": "<key>" }` form
+  under the endpoint your config gives that block, after copying the file to
+  `<cache dir>/config-backups/credentials.json.<timestamp>`. A block that already
+  has a stored key is not overwritten: the same key for the same endpoint drops
+  the older entry, and a different key or endpoint leaves both, with a note;
+- folds `models.json` into the `models` of the connections and harnesses it
+  names (a connection's own column first, then the `*` column and the flat
+  shorthand, then the engine's own model; a model the config already names
+  stands; the entries it cannot place are listed in the notes) and moves the
+  file to `<cache dir>/config-backups/`;
+- rewrites `engine:` on commands, agents, workflows and task sources to
+  `connection:` or `harness:` by what the name is now (a name that is neither is
+  written as `harness:`, with a note), under one backup directory per run. A
+  file you (or an editor or a bundle sync) changed after the plan was made is
+  left exactly as it now is, in no backup and no rewrite, and is reported as
+  skipped or still ready: running `akm migrate apply` again plans it afresh. An
+  asset that is a symbolic link is read but never rewritten: it is reported as
+  skipped, and its `engine:` key keeps its meaning until you change the file it
+  leads to.
+
+`akm migrate apply --dry-run` lists all of it first, and `akm upgrade` runs it
+for you.
+
+**Dropped, with a note.** `provider`, an `extraParams` key that shadows a
+first-class setting (the setting wins), `supportsJsonSchema` (akm retries
+without a schema when an endpoint rejects one), `workflow.judgeEngine`, a
+strategy's `engine`, `model`, `llm` and `timeoutMs`, an index pass's `engine`
+that names a harness (an index pass can only name a connection; with none named
+it runs where all model work does, on the default connection, else the default
+harness, restricted where the harness can be), `models.json`
+entries that name nothing configured, and an `opencode-sdk` engine's own model,
+timeout and workspace (akm's own runtime has no entry in config; the connection
+its `llmEngine` named becomes `default`). A workflow run frozen by an earlier
+release (plan version 7 or lower) whose plan holds a command target cannot be
+resumed: `akm workflow run` abandons it with a message naming `akm workflow run
+<ref>` to start afresh. Let such runs finish before you upgrade.
+
+**Harnesses run as thin shells.** akm writes only the arguments a program needs
+to run without a person, hands it the prompt, and takes its standard output as
+the reply, as written. It no longer asks a harness for JSON output or reads a
+result or a session id out of it. Claude Code and pi take the prompt on stdin.
+A harness's child gets your environment as it is, with akm's directories set
+over it ([The environment programs run
+in](#the-environment-programs-run-in)).
+`akm agent` with no `--prompt` starts the harness for a person.
+
+**OpenCode 1 is legacy, not deprecated for removal.** The `opencode` harness runs
+`opencode run` for both majors, with no change to the config. Where akm reads
+its version (`akm setup`, `akm upgrade`, and model work) and finds OpenCode 1, it
+warns once that OpenCode 2 is recommended; OpenCode 1 keeps working, its model
+work cannot be restricted, and no removal date is set.
+
+**Model work runs on any harness**, with its tools restricted where the harness
+can be (Claude Code, Codex, OpenCode 2) and unrestricted, with a notice, where it
+cannot ([How akm runs a
+harness](../reference/configuration.md#how-akm-runs-a-harness)). A config that
+names an `opencode` harness for model work loads.
+
+**akm's own runtime is a pinned OpenCode 2 binary that akm fetches and runs.**
+Agent work on a connection, with no harness configured, runs on it: no entry in
+config, no `opencode` of yours, driven by your connections only (no user or
+project OpenCode config loads, though it still loads `~/.agents` and OpenCode's
+system config, `/etc/opencode`; OpenCode's own free-model provider and model
+catalog fetch are off). The first run downloads the binary for your platform from
+the npm registry (about 114 MB, once, into `<akm cache dir>/opencode/<version>/`)
+and checks it against the registry's integrity hash; if akm cannot reach the
+registry for that step, enable the `opencode` harness with an installed OpenCode
+2 instead. On bare Alpine (musl) the binary needs `libstdc++` and `libgcc`, which
+the Alpine Node image already has. Its sessions are stored in
+`<akm data dir>/opencode-runtime/data/opencode/opencode.db`, with the rest of its
+files under `<akm data dir>/opencode-runtime/`. A run reports its token usage, and
+a persona goes in the prompt, not a system channel.
+
+**`platform: "opencode"` is your OpenCode**, whichever major is installed, run
+through its CLI (`opencode run`, the prompt on stdin). Your OpenCode owns its
+configuration, logins and sessions: akm reads, copies and embeds nothing of
+yours to run it, and its runs are in your OpenCode history, which improve reads.
+
 ## Behaviour changes you will notice
 
 ### `akm improve`
@@ -375,8 +600,8 @@ stop.
   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.
+  workflow and shell tasks already had. An explicit task `timeout:`, a connection's or
+  harness's `timeoutMs` 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.
@@ -384,13 +609,20 @@ stop.
 - **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.
+### The environment programs run in
+
+A harness (agent tasks and workflow agent steps included) and an `exec` unit's
+command now run with your environment as it is. In 0.9 each got an allowlist
+(`PATH`, `HOME`, locale and a few more, plus the provider keys a harness named,
+and an `exec` unit's `pass_env:` names); a variable outside it, a token in your
+shell included, did not reach the program. Now every variable does, and
+`pass_env:` still loads and selects nothing. What akm scrubs from an agent's reply
+is under [Architecture: Connections and
+Harnesses](../architecture/architecture.md#connections-and-harnesses); an `exec`
+command's output is not scrubbed of what it inherited. Where a program must not
+see a credential, scope the process that runs akm (a dedicated account, a clean
+environment). See [How akm runs a
+harness](../reference/configuration.md#how-akm-runs-a-harness).
 
 ## Plugins
 
@@ -419,19 +651,12 @@ run. For OpenCode 2, run `opencode plugin add akm-opencode-v2`.
   old build folders behind.) 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.
+- **Questions and permission requests.** Nobody can answer an akm run:
+  OpenCode's headless `run`, which akm's own runtime and the `opencode` harness
+  both use, cancels every question and rejects every permission request that
+  would ask, and the model carries on. akm changes no OpenCode permission
+  default. See
+  [Configuration](../reference/configuration.md#harnesses).
 - **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); the plugins require akm
@@ -445,7 +670,7 @@ run. For OpenCode 2, run `opencode plugin add akm-opencode-v2`.
   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
+  `opencode`, `claude` and `codex` CLI harnesses runs the harness in its own
   process group, and SIGTERM or SIGINT to akm now takes it down too.
 
 ## Version numbers
@@ -479,7 +704,7 @@ only.
 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 task doctor            # scheduler backend, akm path, connections and harnesses, 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
@@ -489,8 +714,16 @@ 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 health` check `connections-and-harnesses` lists a row for each connection and harness (its
+  key held and reachable, or its binary found) and for each kind of work with
+  the connection or harness and model it resolves to; `akm info` prints the same
+  rows without probing, and `akm models` shows each alias of the default
+  connection. A connection that is not reachable is a warning (exit 4), not a
+  failure.
+- `akm improve --dry-run` fails (exit 78, `UNKNOWN_IMPROVE_STRATEGY`) when the
+  configured strategy was removed.
+- `config.json` no longer has `engines` or `defaults`, `credentials.json` holds
+  any keys that were in it, and `models.json` is in `<cache dir>/config-backups/`.
 - `akm task doctor` reports `improveTriage` (enabled, mode) and
   `improveAutonomy` with the lanes the `experimental.improveAutonomy` gate holds
   off.
@@ -504,13 +737,20 @@ Things to look for:
 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`.
+`akm migrate apply` wrote under `<cache dir>/config-backups/`: 0.9 does not read
+`connections`, `harnesses` or `credentials.json`, so a migrated config leaves it
+with no engines (the backup holds your keys as they were, and `models.json` is
+in the same directory). The assets whose `engine:` key `apply` rewrote are in the
+backup directory the report names as `assetEngineKeys.backupPath`, under
+`<akm data dir>/backups/asset-engine-keys/`. Finish or abandon workflow runs
+started under 0.10 first; 0.9 refuses a plan a newer akm froze. 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).
+[the improvement loop](../architecture/improvement.md) and the
+[improve workflow reference](../architecture/internals/improve-workflow.md).

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -518,10 +518,10 @@ executor's replay-divergence error ("journaled with different inputs")
 instead of silently reusing a row bound to the now-stale value. Units
 without bindings are unaffected.
 
-See [`with:` on a task-composed step](../reference/workflow-schema.md#github-shaped-yaml-subset)
-for the full binding grammar, delivery surfaces (`AKM_TASK_INPUTS`, the
-`## Task inputs` prompt block), and `akm task explain` for inspecting what a
-task-composed step would actually receive.
+A workflow step that composes a task (`uses: tasks/<ref>`), with its `with:`
+bindings and the `AKM_TASK_INPUTS` and `## Task inputs` delivery surfaces, was
+removed in 0.10 (see [Workflows](v0.9-to-v0.10.md#workflows)). `akm task
+explain` remains: see [`akm task explain`](../reference/tasks.md#akm-task-explain).
 
 ## Child workflows
 
@@ -629,7 +629,8 @@ composing parent step's own output — see
 This is a Markdown-frontmatter-only key — a GitHub-shaped workflow's closed
 root key set (`name`, `on`, `jobs`) has no extension surface for it, the
 same reason it cannot declare `params:` either. See
-[Workflow Schema: Workflow outputs](../reference/workflow-schema.md#workflow-outputs).
+[Moving from akm 0.9 to 0.10: Workflows](v0.9-to-v0.10.md#workflows), which
+removed top-level `outputs:`.
 
 ## New commands
 

package/docs/posts/config-v2-lessons-16.md

@@ -176,7 +176,7 @@ akm config
 # Full config in the new shape
 ```
 
-The complete old-to-new key mapping is in [docs/migration/v0.7-to-v0.8.md](https://github.com/itlackey/akm/blob/main/docs/migration/v0.7-to-v0.8.md).
+The complete old-to-new key mapping is in [docs/migration/v0.7-to-v0.8.md](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md).
 
 ## What Adding a Field Looks Like Now
 

package/docs/posts/llm-mode-reflect-13.md

@@ -161,6 +161,6 @@ The next improve run after that shows reflect calls completing in the 6–10 sec
 
 ---
 
-LLM mode reflect is available in akm 0.8.0. The full configuration reference is in [configuration reference](../reference/configuration.md). The Config v2 key mapping is in the [v0.7 to v0.8 migration guide](../migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
+LLM mode reflect is available in akm 0.8.0. The full configuration reference is in [configuration reference](../reference/configuration.md). The Config v2 key mapping is in the [v0.7 to v0.8 migration guide](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
 
 For a broader view of the improve pipeline — all five phases, scheduling, and how reflect feeds the downstream consolidation and distill passes — see [The Improvement Loop: How akm Keeps Your Agent Sharp](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d). For debugging improve runs when something goes wrong (stale DB entries, hallucinated merge plans, pre-flight filters), see [Your Agent Has a Memory That Runs While You Sleep](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh).

package/docs/posts/release-0.6.0.md

@@ -18,7 +18,7 @@ date: '2026-05-05T02:19:46Z'
 
 akm 0.6.0 is out. This one is deliberately boring: a stabilization release that takes a clean break from pre-v1 terminology so the surface area we carry into v1 is honest. The domain model now has one noun for "a source of content" (stash) and one noun for "a service that helps discover them" (registry). The parallel vocabulary that accreted during earlier experiments — "kit", "source", hand-special-cased provider types — is gone. A handful of additive quality-of-life improvements ship alongside, but the headline story is fewer concepts, not more.
 
-If you are on 0.5.x, read [the v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) before upgrading. Most projects will work without edits thanks to automatic on-disk migrations; a small number of config fields and CLI flags need explicit updates.
+If you are on 0.5.x, read [the v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md) before upgrading. Most projects will work without edits thanks to automatic on-disk migrations; a small number of config fields and CLI flags need explicit updates.
 
 ## TL;DR
 
@@ -51,14 +51,14 @@ The registry wire format follows the same logic. Schema v3 drops `kits[]` and pa
 
 Each bullet below links to its section in the migration guide, which has the exact before/after code or config diff.
 
-- [`stash.lock` → `akm.lock`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#1-stashlock--akmlock) — auto-copied on first run.
-- [`installed[]` → `stashes[]` + `akm.lock`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#2-installed--stashes--akmlock) — config cleanup happens on next write.
-- [`stashDir` → `primary: true`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#3-stashdir--primary-true) — automatic.
-- [`disableGlobalStashes` → `stashInheritance`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#1-replace-disableglobalstashes) — **manual**, one-line config edit.
-- [`--for-agent` → `--detail=agent`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#2-replace---for-agent-with---detailagent) — old flag still works as a deprecated alias for one release cycle.
-- [`akm enable/disable context-hub` removed](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#3-replace-akm-enable-context-hub--akm-disable-context-hub) — add it as a regular git stash.
-- [Wire format `kits[]` → `stashes[]`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#wire-format-change-kits--stashes) — registry publishers must regenerate.
-- [Discovery keyword / topic `akm-kit` → `akm-stash`](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#publisher--kit-maker-changes) — publishers must re-tag.
+- [`stash.lock` → `akm.lock`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#1-stashlock--akmlock) — auto-copied on first run.
+- [`installed[]` → `stashes[]` + `akm.lock`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#2-installed--stashes--akmlock) — config cleanup happens on next write.
+- [`stashDir` → `primary: true`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#3-stashdir--primary-true) — automatic.
+- [`disableGlobalStashes` → `stashInheritance`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#1-replace-disableglobalstashes) — **manual**, one-line config edit.
+- [`--for-agent` → `--detail=agent`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#2-replace---for-agent-with---detailagent) — old flag still works as a deprecated alias for one release cycle.
+- [`akm enable/disable context-hub` removed](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#3-replace-akm-enable-context-hub--akm-disable-context-hub) — add it as a regular git stash.
+- [Wire format `kits[]` → `stashes[]`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#wire-format-change-kits--stashes) — registry publishers must regenerate.
+- [Discovery keyword / topic `akm-kit` → `akm-stash`](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#publisher--kit-maker-changes) — publishers must re-tag.
 
 If you consume only the public registry and do not maintain your own, the publisher changes do not apply to you.
 
@@ -96,7 +96,7 @@ akm upgrade
 
 Read:
 
-- [v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) — every breaking change with before/after code; publisher checklist if you maintain a registry or an npm/GitHub stash.
+- [v0.5 → v0.6 migration guide](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md) — every breaking change with before/after code; publisher checklist if you maintain a registry or an npm/GitHub stash.
 
 Verify:
 
@@ -106,7 +106,7 @@ akm config list                   # stashes[] populated, no installed[]
 akm list                          # your sources resolve cleanly  # doclint:ignore (historical — pre-0.9.0 command spelling)
 ```
 
-If something looks wrong after upgrade, the guide has a [troubleshooting section](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md#troubleshooting) covering the common pitfalls (stale context-hub entries, v2 registry URLs, empty `stashes[]` after a read-only upgrade path).
+If something looks wrong after upgrade, the guide has a [troubleshooting section](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.5-to-v0.6.md#troubleshooting) covering the common pitfalls (stale context-hub entries, v2 registry URLs, empty `stashes[]` after a read-only upgrade path).
 
 ## What's next
 

package/docs/posts/release-0.8.0.md

@@ -187,7 +187,7 @@ visible wins:
   asset that mentions a given entity, by confidence). `akm graph orphans`
   surfaces assets that produced zero entities — quality-triage candidates.
   See the 0.8.0 migration guide's
-  [graph extraction section](../migration/v0.7-to-v0.8.md#memory-inference-and-graph-extraction-moved-out-of-index).
+  [graph extraction section](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md#memory-inference-and-graph-extraction-moved-out-of-index).
 - **Better output.** `akm graph relations` and `akm graph entities` now show
   per-row confidence. Search hits annotate the graph-boost contribution in
   `whyMatched`. Related results end with a `Next: akm show '<ref>'` hint
@@ -202,7 +202,7 @@ the next `akm improve` cycle, which makes LLM calls. The first improve cycle
 after upgrade is slower than steady state, but the Phase 1 / Phase 2
 improvements above make it dramatically faster than equivalent re-extraction
 on 0.7.x. See the migration guide section
-[Graph extraction will re-run after upgrade](../migration/v0.7-to-v0.8.md#graph-extraction-will-re-run-after-upgrade).
+[Graph extraction will re-run after upgrade](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md#graph-extraction-will-re-run-after-upgrade).
 
 ## Config v2 and reflect LLM mode
 
@@ -269,7 +269,7 @@ akm config migrate  # doclint:ignore (historical — akm 0.8.0 release announcem
 ```
 
 Full reference: [configuration reference](../reference/configuration.md).
-Full key mapping: [v0.7 to v0.8 migration guide — Config 0.8.0 migration](../migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
+Full key mapping: [v0.7 to v0.8 migration guide — Config 0.8.0 migration](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
 
 ## Migration Guidance
 
@@ -327,6 +327,6 @@ akm task list              # shows your defined tasks — doclint:ignore (histor
 akm config get configVersion  # "0.8.0" after akm config migrate
 ```
 
-Full details in the [v0.7 to v0.8 migration guide](../migration/v0.7-to-v0.8.md) and the [configuration reference](../reference/configuration.md).
+Full details in the [v0.7 to v0.8 migration guide](https://github.com/itlackey/akm/blob/7a4f302febfc0fe8c0bf3028c6156e6edc5aae33/docs/migration/v0.7-to-v0.8.md) and the [configuration reference](../reference/configuration.md).
 
 Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).