akm-cli 0.10.261013-beta → 0.10.261014-beta

package/docs/reference/workflow-schema.md

@@ -51,9 +51,9 @@ steps:
 The step needs a `## investigate` body section like any other step (it is
 documentation for a human; the child's own steps carry the instructions).
 
-- `workflow` names the child. A workflow unit reaches no engine and the child
-  carries its own environment, so `exec`, `engine`, `model`, `llm` and `env`
-  beside `workflow` are lint errors. `workflow` is not allowed inside
+- `workflow` names the child. A workflow unit runs no model of its own and the
+  child carries its own environment, so `exec`, `connection`, `harness`, `model`,
+  `llm` and `env` beside `workflow` are lint errors. `workflow` is not allowed inside
   `map.unit`.
 - `with:` binds the child's declared `params:` (a workflow has no `inputs:`).
   Each value is a literal (validated against the param's declared type at
@@ -159,12 +159,14 @@ families) plus the orchestration keys:
 - `params` — name → `{ type, description, default }` (JSON-Schema-typed, unlike a bare
   description string). A param the run does not supply takes its `default:`; an explicit
   value wins. Params are never required.
-- `defaults` — run-level dispatch defaults (`engine`, `model`, `llm`,
-  `timeout`, `on_error`), overridable per unit. `llm:` tuning reaches an engine
-  of any kind, and a document-level `llm:` reaches EVERY step. An LLM engine
-  sends it; an agent engine reports it as an `untranslated-field` notice on that
-  step (see
-  [Inference on an agent engine](configuration.md#inference-on-an-agent-engine)).
+- `defaults` — run-level dispatch defaults (`connection`, `harness`, `model`,
+  `llm`, `timeout`, `on_error`), overridable per unit. A step with neither runs
+  on the default harness, else akm's own runtime over the default connection.
+  `llm:` tuning (`temperature`, `max_tokens`, `enable_thinking`,
+  `reasoning_effort`) reaches every step, and a document-level `llm:` reaches
+  EVERY step. A connection and akm's own runtime send it; a harness reports it as
+  an `untranslated-field` notice on that step (see
+  [Settings a call asks for](configuration.md#settings-a-call-asks-for)).
   There is no per-step opt-out (`llm: {}` is a no-op and `llm: null` is a parse
   error), so in a mixed document put `llm:` on the `unit:` of each step it is
   meant for instead of in `defaults:`.
@@ -174,8 +176,8 @@ families) plus the orchestration keys:
   (`[A-Za-z_][A-Za-z0-9_-]*` — no dots) and **at most one** of `unit` or `map`.
   A step with neither is **still a unit step** — bare
   `- id: validate` is the complete minimal declaration. `unit:` is the
-  optional dispatch-override bag (`exec`, `engine`, `model`, `llm`, `timeout`,
-  `retry`, `on_error`, `output`, `env`; see
+  optional dispatch-override bag (`exec`, `connection`, `harness`, `model`,
+  `llm`, `timeout`, `retry`, `on_error`, `output`, `env`; see
   [Exec (shell) units](#exec-shell-units) and
   [Failure policy](#failure-policy)). Dispatch settings live under `unit:`
   (`map.unit:` on a map step), not on the step itself; `unit.output` types
@@ -267,7 +269,7 @@ type: workflow
 description: Review changed files and give an overall verdict
 params:
   changed_files: { type: array, description: Files to review }
-defaults: { engine: reviewer, model: balanced, timeout: 10m, on_error: fail }
+defaults: { harness: claude, model: balanced, timeout: 10m, on_error: fail }
 budget: { max_units: 40, max_tokens: 200000 }
 steps:
   - id: discover
@@ -278,8 +280,8 @@ steps:
       over: steps.discover.output.files
       concurrency: 8
       unit:
-        engine: reviewer
-        model: deep
+        harness: claude
+        model: reasoning
         timeout: 5m
         retry: { max: 1, on: [timeout, llm_rate_limit] }
         on_error: continue
@@ -491,20 +493,20 @@ fail later at `akm workflow run`:
 | `map.concurrency` | 1 – 64 |
 | `retry.max` | 0 – 100 |
 | `timeout` | ≤ 2147483647 ms (~24.8 days), or `none` |
-| `engine` names | `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, ≤ 63 chars |
+| `connection` and `harness` names | `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, ≤ 63 chars |
 
 `timeout` is resolved **once, at freeze time**, and the frozen value is what
-dispatch applies — there is no separate engine-side ceiling on top of it. The
+dispatch applies — there is no separate ceiling on top of it. The
 first of these that is set wins: the unit's `timeout`, then the document's
-`defaults.timeout`, then `engines.<name>.timeoutMs`, then the engine-kind
-default — **10m for `kind: llm` engines, and none for agent engines**, which
-manage their own process lifetime. Writing `timeout: none` is an explicit opt
+`defaults.timeout`, then the selected connection's or harness's `timeoutMs`,
+then the default — **none for agent work, whether it runs on a harness or on
+akm's runtime over a connection, and 10m for model work**. Writing `timeout: none` is an explicit opt
 out and leaves the unit genuinely unbounded; nothing later re-imposes a cap.
 
 ## Exec (shell) units
 
 A step whose `unit:` block declares `exec:` runs a **shell command** instead of
-dispatching to an engine. Deterministic work — running the test suite, building,
+dispatching a model. Deterministic work — running the test suite, building,
 linting, copying a file, invoking a script — is a command, not a prompt, and
 paying for an LLM or agent dispatch to get it done buys nondeterminism, latency,
 and tokens in exchange for nothing.
@@ -520,10 +522,10 @@ steps:
       retry: { max: 1, on: [timeout] }
 ```
 
-An exec unit names **no engine**. It carries no `engine`, `model`, or `llm` (the
-parser rejects those alongside `exec:`), it consumes no tokens, and a workflow
-made only of exec steps freezes and runs on an install with no engine configured
-at all. Everything else about a unit still applies unchanged: `timeout`, `retry`,
+An exec unit names **no connection or harness**. It carries no `connection`,
+`harness`, `model`, or `llm` (the parser rejects those alongside `exec:`), it
+consumes no tokens, and a workflow made only of exec steps freezes and runs on an
+install with no connection or harness configured at all. Everything else about a unit still applies unchanged: `timeout`, `retry`,
 `on_error`, `output`, `env`, `map` fan-out and its concurrency, the
 unit journal, budget accounting, and replay/reuse.
 
@@ -579,9 +581,9 @@ full.
 | --- | --- |
 | **Working directory** | The owner root of the run's workflow, found at each step's dispatch. `cwd` joins it once and may be absolute. |
 | **Argv** | Spawned directly, never shell-interpreted. A `${ref}` token in an entry is replaced at dispatch. |
-| **Environment** | Starts empty: the [default allowlist](#the-childs-environment-is-an-allowlist) plus `pass_env`, then the unit's `env:` bindings, then the engine's `AKM_*` [context](#context-reaching-the-command). |
+| **Environment** | [akm's own](#the-childs-environment), with the directories this akm resolved set over it, then the unit's `env:` bindings, then the engine's `AKM_*` [context](#context-reaching-the-command). |
 | **`${ref}` tokens** | In argv, `cwd` and env-asset values. `${secrets/name}` becomes the secret's value, any other asset ref the asset's absolute path. A ref no bundle owns fails the unit before it spawns. Prompts are not substituted. |
-| **Redaction** | Only values substituted from `secrets/` refs, engine credentials and unsafe passthrough values are scrubbed from stdout, stderr, diagnostics and the journal. Configuration, such as a URL bound through an env asset, is not. |
+| **Redaction** | Only values akm knows are secret are scrubbed from stdout, stderr, diagnostics and the journal: values substituted from `secrets/` refs, secret-shaped run params, connection keys, and the values of credential-named variables the command inherited from akm's environment (names such as `*_API_KEY`, `*_TOKEN`, `*_SECRET` and `*_PASSWORD`, eight characters or more). Configuration, such as a URL bound through an env asset or an ordinary inherited variable, is not. |
 
 #### What is frozen, and what is found at dispatch
 
@@ -696,8 +698,10 @@ is exactly what makes a `test` step a **gate**. With `on_error: continue` the
 failure is recorded in the step's evidence and the completion gate decides.
 
 On timeout or cancellation the child's whole **process group** gets a
-SIGTERM→SIGKILL ladder, so a command that spawned its own children does not
-leave them orphaned.
+SIGINT→SIGTERM→SIGKILL ladder (each signal after a grace period of 5 seconds, for
+a command still running), so a command that spawned its own children does not
+leave them orphaned. Windows has no process group; there the first signal ends
+the command itself.
 
 ### Output limits
 
@@ -779,7 +783,7 @@ Where those numbers come from:
 - **macOS** has no per-string cap; its binding constraint is `ARG_MAX`
   (262 144 bytes) over `argv` + `environ` *combined*. The 128 KiB total keeps
   akm's own contribution to half of that, leaving the rest for the argv, the
-  environment allowlist and your `env:` bindings.
+  rest of the environment and your `env:` bindings.
 - **Windows** caps a single user-defined environment variable at 32 767
   characters (`SetEnvironmentVariable`), and the environment block has limits of
   the same order.
@@ -823,50 +827,32 @@ command would have to handle both shapes, and the spill file would have to be
 placed and cleaned up. A stable contract plus
 an explicit error is the smaller, more predictable surface.
 
-### The child's environment is an allowlist
+### The child's environment
 
-An exec unit's command does **not** inherit akm's environment. The child starts
-from an **empty** environment and is built in three layers, in this order:
+An exec unit's command inherits the environment akm runs in, as a command typed in
+your shell would, and nothing is filtered out of it: `PATH`, `HOME`, locale and
+toolchain variables, and any credential or proxy setting of the process that ran
+`akm workflow run` reach the command. It is built in three layers, in this order:
 
-1. akm's own directories and the **default allowlist** below, copied through
-   from akm's own environment (plus any names the unit adds with `pass_env:`);
+1. akm's own environment, with the directories this akm resolved set over it;
 2. the unit's resolved **`env:` bindings**;
 3. the engine-authored **`AKM_*` context** — last, so a binding can never
    shadow it.
 
-The default allowlist is exactly these names (a name absent from akm's own
-environment is simply absent from the child):
-
-| Group | Names | Why |
-| --- | --- | --- |
-| Command resolution | `PATH` | without it only an absolute `command[0]` can be spawned |
-| Home | `HOME` | the config/cache root git, npm, bun, cargo and ssh all read |
-| Identity | `USER`, `LOGNAME`, `SHELL` | read by git/ssh and by tools that re-exec a login shell |
-| Locale | `LANG`, `LC_ALL`, `LC_CTYPE` | without a locale, non-ASCII stdout — *which is this unit's artifact* — gets mangled |
-| Terminal / clock | `TERM`, `TZ` | some CLIs abort with no `TERM`; `TZ` keeps printed timestamps stable |
-| Scratch space | `TMPDIR`, `TEMP`, `TMP` | POSIX and Windows temp roots |
-| Windows essentials | `SystemRoot`, `SystemDrive`, `WINDIR`, `COMSPEC`, `PATHEXT` | Windows **process creation itself** fails with an empty environment; `PATHEXT` is what makes `bun.exe`/`bun.cmd` resolvable at all |
-| Windows home/config | `USERPROFILE`, `HOMEDRIVE`, `HOMEPATH`, `APPDATA`, `LOCALAPPDATA`, `ProgramData`, `ProgramFiles` | the Windows analogues of `HOME` and the machine-wide install roots toolchain shims resolve against |
-| akm provenance | `AKM_EVENT_SOURCE` | a command that calls `akm` records machine traffic, not user demand |
-
-`PATH` is additionally supplemented with well-known user binary directories
-when akm is running in a scheduler context (cron/launchd/Task Scheduler) that
-stripped it — the same treatment an agent-harness child gets.
-
-The child also gets akm's own directories, whatever the parent found them
-through: `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` and `AKM_STATE_DIR` are
-set to the directories the akm that started it resolved (from `AKM_*_DIR`,
-`XDG_*_HOME` or the platform default), and `AKM_BUNDLE_DIR` is passed when that
+The directories are `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` and
+`AKM_STATE_DIR`, set to the ones the akm that started the command resolved (from
+`AKM_*_DIR`, `XDG_*_HOME` or the platform default), and `AKM_BUNDLE_DIR` when that
 akm had one. A step that runs `akm` therefore uses the same bundle, config, data,
-cache and state, with no `pass_env:`. Naming one of these in `pass_env:` or
-binding it in `env:` overrides it.
+cache and state. Binding one of them in `env:` overrides it. When a scheduled
+task runs the workflow, `AKM_EVENT_SOURCE` is set (when the environment has
+none), so a command that calls `akm` records machine traffic, not user demand; a
+direct `akm workflow run` leaves it as it found it.
 
-Deliberately **not** on the list: credentials of any kind, cloud/CI variables,
-and the proxy family (`HTTP_PROXY` and friends — proxy URLs routinely embed
-credentials). Reach a required value with an exact named `env:` binding, or
-name a non-secret per-machine variable with `pass_env:`.
+Reach a fixed value or a secret with an exact named `env:` binding; what is
+redacted from what the command prints is in the Redaction row of [the exec
+contract](#the-exec-contract).
 
-#### `pass_env:` — widen the allowlist by name
+#### `pass_env:` — frozen, and it selects nothing
 
 ```yaml
     unit:
@@ -875,13 +861,11 @@ name a non-secret per-machine variable with `pass_env:`.
         pass_env: [CARGO_HOME, SCCACHE_DIR]
 ```
 
-Names only, 1–32 of them, matching `^[A-Za-z_][A-Za-z0-9_]*$`. Use it for a
-**per-machine** variable an `env:` binding cannot express — an env asset stores
-a committed *value*, so it cannot carry "whatever this build agent's
-`CARGO_HOME` happens to be".
-
-Values passed through this way are **not** redacted from the command's output
-the way a secret bound through `env:` is, so never list a credential here.
+`pass_env:` was the list of variable names an earlier release copied into a child
+that started empty. A workflow that has it keeps loading, and the names are kept
+in the frozen plan and in the unit's input hash, but they select nothing now: the
+command already has the environment. Names only, matching
+`^[A-Za-z_][A-Za-z0-9_]*$`.
 
 #### Binding a secret to a unit
 
@@ -930,18 +914,18 @@ env asset:
   or a channel id, reaches the journal and the next step unredacted. A
   credential typed straight into an env file is not redacted, so keep
   credentials in `secrets/` and bind them with a `${secrets/name}` token.
-- `env:` needs a child process: it works on exec units and on agent and SDK
-  engines. A unit on an `llm` engine that declares `env:` fails
-  `env_unsupported`.
+- `env:` needs a child process: it works on exec units and on every unit that
+  runs an agent, whether on a harness or on akm's own runtime. A model call that
+  runs no agent cannot take a per-unit environment and fails `env_unsupported`.
 
-#### Durable v4 (`irVersion: 7`) forbids `inherit_env`
+#### Durable v4 (`irVersion: 8`) forbids `inherit_env`
 
 Every new workflow start freezes the durable plan v4 family's current
-executable format (`irVersion: 7`; 5 and 6 still decode). It rejects
-`inherit_env: true` and any other request for whole-process inheritance; use
-exact named environment bindings and `pass_env:` instead. Both mechanisms are
-dispatch-significant, keep the visible environment surface bounded, and form
-part of the unit's input hash.
+executable format (`irVersion: 8`; a plan frozen earlier decodes when it holds no
+model step). It rejects
+`inherit_env: true`, which is not needed: the command inherits akm's
+environment. Exact named `env:` bindings are dispatch-significant and form part
+of the unit's input hash.
 
 The historical `inherit_env` spelling is unsupported.
 
@@ -949,8 +933,8 @@ The historical `inherit_env` spelling is unsupported.
 
 `akm show <workflow> --format json` summarizes each step under
 `steps[].orchestration`. For an exec step that summary carries an `exec` object
-and **no `engine`/`model`** — an exec unit names no engine, so reporting the
-workflow's `defaults.engine` there would describe a dispatch that never
+and **no `engine`/`model`** — an exec unit runs on no connection or harness, so
+reporting the workflow's `defaults` there would describe a dispatch that never
 happens. Field presence is the discriminator, the same way `fanOut` marks a
 `map` step:
 
@@ -978,8 +962,8 @@ happens. Field presence is the discriminator, the same way `fanOut` marks a
   step's output. Every byte is already visible in the workflow file (and stored
   verbatim in `plan_json`) — which is also why you never inline a secret there.
 - `cwd` and `passEnv` appear only when the unit declares them. `passEnv` is a
-  list of variable **names**; no value is ever projected. New v4 plans never
-  carry `inheritEnv`.
+  list of variable **names** that select nothing; no value is ever projected. New
+  v4 plans never carry `inheritEnv`.
 - `timeoutMs` is still reported, because an exec unit really does inherit
   `defaults.timeout` — that number is true for it.
 
@@ -992,21 +976,12 @@ Exec units sit inside the existing workflow trust model — see
 [Security: workflow sources are executed code](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md#security-workflow-sources-are-executed-code).
 They do not widen it, and they do not narrow it:
 
-- **The child's environment is an allowlist, not an inheritance.** Be clear
-  about what that does and does not buy. It does *not* stop a determined
-  attacker: a command that runs at all can read the same credentials off disk
-  that the environment would have handed it, and a workflow source is executed
-  code either way. What it does buy is real but narrower — it bounds
-  **accidental** exposure (the shell or CI job that invoked `akm` routinely
-  exports tokens for unrelated services, and a third-party step that merely
-  prints its environment, or a tool that ships one in a crash report, should
-  not get them for free), it makes the environment surface **explicit and
-  reviewable** (this list plus lines in the frontmatter diff, rather than
-  "whatever the invoking shell happened to export"), and it **matches the
-  convention akm already applies to spawned children** — agent-harness children
-  have always been built from `envPassthrough` this way, and exec units now use
-  the same mechanism rather than a second one. Operators who need a harder
-  boundary still scope the *akm process* (dedicated account, ephemeral working
+- **The child inherits akm's environment.** The command runs with your
+  environment, as if you had typed it in your shell, so a credential the shell or
+  CI job exported reaches it, and a value it inherited is not redacted from what
+  it prints. That is the same trust a workflow source already has: a command that
+  runs at all can read the same credentials off disk. Operators who need a
+  boundary scope the *akm process* (dedicated account, ephemeral working
   directory, external network/filesystem policy); that is the boundary that
   actually holds.
 - **Secrets come from `env:` bindings by name.** The frozen plan carries only
@@ -1062,18 +1037,16 @@ Raising one never raises the others:
 | --- | --- | --- |
 | `map.concurrency` | the step | `workflow.defaultMapConcurrency`, else **4** |
 | `execution.maxConcurrency` | `workflow.maxConcurrency` config | CPU-derived `min(16, max(1, cores − 2))` |
-| the selected LLM engine's concurrency | `engines.<name>.concurrency` | **1** for a loopback endpoint, **4** for a remote one |
+| the selected connection's concurrency | `connections.<name>.concurrency` | **1** for a loopback endpoint, **4** for a remote one |
 | the host CPU safety cap | nothing — reapplied at dispatch | `min(16, max(1, cores − 2))` |
 
-The engine limit is per **endpoint kind** on purpose. A local model server (LM
+The connection limit is per **endpoint kind** on purpose. A local model server (LM
 Studio, Ollama) has one loaded model, and concurrent inference makes it reload
 and return HTTP 500 — a hard failure, so loopback endpoints stay at 1 and a
 `map` against a local model is still effectively serial unless you raise
-`engines.<name>.concurrency` yourself. Remote providers fail softly (a
+`connections.<name>.concurrency` yourself. Remote providers fail softly (a
 retryable 429), and four concurrent completions is well inside any hosted
-provider's entry tier. Agent engines carry no concurrency limit of their own —
-except an `opencode-sdk` engine that sets `llmEngine`, which inherits that
-fallback engine's limit.
+provider's entry tier. A harness carries no concurrency limit of its own.
 
 #### What counts as a loopback endpoint
 
@@ -1095,15 +1068,15 @@ exactly as single-model as one on `127.0.0.1`.
 re-serializes the dotted form to the hex one before the check ever sees it. A
 mapped public address such as `[::ffff:8.8.8.8]` still reads as remote. The
 deprecated IPv4-compatible form `[::127.0.0.1]` is not recognized; if you use
-it, set `engines.<name>.concurrency: 1`.
+it, set `connections.<name>.concurrency: 1`.
 
 The check is **purely syntactic — it never resolves a name.** A frozen plan has
 to come out the same on your laptop, on CI, and on a machine with no network at
 all, and a DNS lookup would make the frozen width depend on what a resolver
 happened to answer. So a *name* that resolves to loopback (a hosts-file alias,
 `host.docker.internal`, an internal DNS record) is treated as **remote**; point
-the engine at the address itself, or set `engines.<name>.concurrency: 1`
-explicitly. In the other direction the classification is deliberately
+the connection's endpoint at the address itself, or set
+`connections.<name>.concurrency: 1` explicitly. In the other direction the classification is deliberately
 conservative: an endpoint akm cannot parse at all is treated as loopback, since
 freezing 4 for a config it does not understand is the failure worth avoiding.
 
@@ -1177,17 +1150,17 @@ verdict that cannot change. So a step whose unit is `exec:` still has its
 artifact judged and can still be failed by the verdict; a rejection simply lands
 on the first evaluation, carrying the same missing criteria and feedback the
 one-shot case does. `gate.max_loops` on such a step is capped at 1 rather than
-rejected, and an engine step's declared `max_loops` is untouched. This is the
+rejected, and a model step's declared `max_loops` is untouched. This is the
 same reasoning that makes an exec unit's `output:` schema miss fail without a
 corrective re-dispatch.
 
 **Fail-closed verification.** With no non-empty `### gate` rubric, no
-verification runs. When a rubric is present, the workflow requires
-`workflow.judgeEngine` to name a configured LLM or agent engine before the
-plan can be frozen — see
+verification runs. When a rubric is present, the workflow requires a
+connection or a harness to judge it before the plan can be frozen: the judge
+runs where model work runs (the default connection, else the default harness; see
+[Where each process runs](configuration.md#where-each-process-runs)) — see
 [Author's Guide: Troubleshooting](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#troubleshooting)
-if that engine isn't configured yet. That verifier invocation is frozen into
-the run.
+if neither is configured yet. That verifier invocation is frozen into the run.
 
 Only a well-formed `complete: true` verdict advances a criteria-bearing step.
 A missing verifier, dispatch failure, or malformed result rejects the gate
@@ -1204,33 +1177,32 @@ across resumes**, not just the current invocation. Hitting a ceiling aborts
 the step's still-pending dispatches and fails the step with a
 `budget exceeded (<which> ceiling)` summary — budget exhaustion is a hard
 stop that ignores `on_error: continue`. Because the plan is frozen, raising a
-budget means starting a new run.
+budget means starting a new run. Only units that run on akm's own runtime
+report token usage; a unit on a harness or a direct model call reports none
+and adds nothing to `max_tokens`.
 
 ## Model references
 
 Reference semantic aliases in `model:` fields instead of exact model ids so a
-workflow stays harness-agnostic. Aliases are defined only in the installed and
-optional user `models.json` files:
+workflow stays portable across machines. The standard aliases are `fast`,
+`balanced` and `reasoning`; each connection and harness says which of its models
+answers them (`connections.<name>.models`, `harnesses.<name>.models`; Claude Code
+ships a map of its own):
 
-```jsonc
-{
-  "version": 1,
-  "aliases": {
-    "fast": { "claude": "claude-haiku-4-5", "opencode": "opencode/claude-haiku-4-5" },
-    "balanced": { "claude": "claude-sonnet-4-6", "opencode": "opencode/claude-sonnet-4-6" },
-    "reasoning": { "claude": "claude-opus-4-7", "opencode": "opencode/claude-opus-4-7" }
-  }
-}
+```yaml
+defaults: { model: balanced }
+steps:
+  - id: review
+    unit:
+      model: reasoning
 ```
 
-Resolution checks the selected engine name or canonical harness column. A
-known alias without that column fails rather than guessing a provider model;
-an unknown string is treated as an exact model selector. A column may itself
-be an `engine`-backed indirection (0.9.15) rather than a literal model string
-— see [Model-map files](configuration.md#model-map-files) — so a step naming
-`model: fast` also benefits from whatever engine-backed mapping the operator
-configured for the selected engine, with no workflow-authored change. See the [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-engines-and-models)
-for guidance on which tier to pick per step.
+Resolution looks the alias up on the connection or harness the step runs on. A
+string that is not an alias is an exact model name and is used as written. An
+alias the connection does not map answers with that connection's first model; a
+harness with no model for it passes none and uses its own default. See
+[Aliases](configuration.md#aliases) for the full rules and the author's guide
+for [which tier to pick per step](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-where-a-step-runs-and-which-model).
 
 ## See also
 

package/docs/reference/workflows.md

@@ -11,9 +11,7 @@ interruption without replaying completed units.
 
 Workflows are one of the execution surfaces AKM directly orchestrates: AKM
 retrieves every supported capability type, but a workflow's declared steps —
-not arbitrary indexed content — are what actually gets dispatched. See
-[Architecture: Core Principles](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-core-principles.md) for
-that boundary.
+not arbitrary indexed content — are what actually gets dispatched.
 
 This page is a short map. The full contract now lives across four pages,
 split by what you're doing:
@@ -24,8 +22,8 @@ split by what you're doing:
   someone else's bundle.
 - **[Author's Guide: Writing Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md)** —
   writing and testing a workflow definition: choosing a source format, the Markdown structure, a
-  minimal complete example, common authoring mistakes, choosing engines and
-  models, and engine-selection troubleshooting.
+  minimal complete example, common authoring mistakes, choosing where a step
+  runs and which model, and troubleshooting a missing harness or connection.
 - **[Workflow Schema](../reference/workflow-schema.md)** — the exhaustive,
   authoritative reference: every frontmatter key, the bare-reference grammar,
   failure policy, gates, and budget ceilings, with exact syntax.
@@ -41,7 +39,7 @@ For task- or schedule-driven workflow runs — an `akm task` bound to
 
 Markdown `.md` is the one workflow source format; it preserves AKM's full prose,
 gates, maps, typed artifacts, and exec vocabulary. New starts resolve source
-owners and executable targets, then freeze durable plan `irVersion` 5. A
+owners and executable targets, then freeze durable plan `irVersion` 8. A
 stored plan is read back as it is: one frozen at another `irVersion` that
 still decodes runs, and one this akm cannot decode is abandoned by
 `akm workflow run` with a message naming how to start a new run. See

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261013-beta",
+  "version": "0.10.261014-beta",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -34,10 +34,11 @@
   },
   "license": "MPL-2.0",
   "pinNotes": {
-    "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for.",
-    "@opencode/client@2.0.26": "Exact pin. The OpenCode 2 wire client (OpenCode.make + session.create/prompt/wait/interrupt, event.subscribe, permission.reply) used by src/integrations/harnesses/opencode-sdk/v2-adapter.ts, the default adapter. It is an HTTP client for a private `opencode serve` child akm spawns; it does not install the opencode binary and must never pull in `opencode-ai` or `@opencode/cli`. Re-run the gated real-binary test (AKM_OPENCODE_V2_BIN) before bumping.",
     "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
-    "@huggingface/transformers@4.2.0": "Exact semantic-search dependency pin. Re-run the real-model semantic gate before changing it."
+    "@huggingface/tokenizers@0.1.3": "Exact pin: the tokenizer of the local embedding model (src/llm/embedders/local.ts). Pure JS with no dependencies. A different release can change the token ids and with them every stored vector, so re-run the real-model semantic gate (tests/integration/semantic-search-e2e.test.ts, which compares the vectors with tests/fixtures/embedder-reference-vectors.json) before changing it.",
+    "onnxruntime-node@1.24.3": "Exact pin: the local embedding runtime. The standalone binary embeds this version's native library from node_modules/onnxruntime-node/bin/napi-v6/ (src/standalone/native/) and its addon is bound to exactly that library, so a bump moves this pin, the library file names in src/standalone/native/ (the macOS one carries the version), the list of platforms it ships a library for in src/llm/embedders/local.ts and the real-model semantic gate together.",
+    "ajv@8.20.0": "Exact pin (devDependency, used only by tests: tests/tasks-schema.test.ts validates task sources against schemas/akm-task.json, tests/contracts/config-schema-drift.test.ts checks schemas/akm-config.json). Pinned in 4d7d77992 without a recorded reason; keep exact until the pin is next reviewed.",
+    "cmd-shim@9.0.2": "Exact pin (devDependency), from cd5a3be12 \"pin cmd-shim for launcher tests\": tests/integration/install/package-launcher.test.ts writes the Windows shims npm would write with this package, where it used to load the copy inside the installed npm's own node_modules. That commit records no reason for an exact version over a range; keep exact until the pin is next reviewed."
   },
   "files": [
     "dist",
@@ -46,7 +47,6 @@
     "SECURITY.md",
     "STABILITY.md",
     "LICENSE",
-    "ROADMAP.md",
     "docs/agents",
     "docs/architecture",
     "docs/guides",
@@ -56,7 +56,6 @@
     "docs/posts",
     "docs/reference",
     "docs/product-surface.md",
-    "docs/plans/0.9.2-agent-command-workflow-plan.md",
     "schemas"
   ],
   "exports": {
@@ -77,7 +76,7 @@
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
-    "check:changed": "bun run lint && bunx tsc --noEmit && bun test tests/integration/output-baseline.test.ts tests/integration/registry-search.test.ts tests/integration/show-argv-entrypoint.test.ts tests/output-shapes-unit.test.ts",
+    "check:changed": "bun run lint && bunx tsc --noEmit && bun test tests/integration/output-baseline.test.ts tests/integration/registry/registry-search.test.ts tests/integration/show-argv-entrypoint.test.ts tests/output-shapes-unit.test.ts",
     "sweep:tmp": "bun scripts/sweep-test-tmp.ts",
     "test": "bash scripts/test-unit.sh",
     "test:unit": "bash scripts/test-unit.sh",
@@ -87,7 +86,7 @@
     "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/lint-lockfile.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",
     "format": "bunx biome format --write src/ tests/ scripts/",
     "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",
@@ -118,14 +117,13 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
-    "@huggingface/transformers": "4.2.0",
-    "@opencode-ai/sdk": "1.2.20",
-    "@opencode/client": "2.0.26",
+    "@huggingface/tokenizers": "0.1.3",
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",
     "fast-xml-parser": "^5.10.1",
     "marked": "^18.1.1",
     "node-html-parser": "^9.0.1",
+    "onnxruntime-node": "1.24.3",
     "semver": "^7.6.0",
     "turndown": "^7.2.4",
     "yaml": "^2.8.4",