akm-cli 0.10.261012-beta → 0.10.261014-beta

package/docs/reference/data-and-telemetry.md

@@ -1,6 +1,6 @@
 # AKM Data & Telemetry
 
-AKM stores your data locally on your machine and has **no telemetry**: it does not send usage data, analytics, or crash reports to Anthropic or to the AKM project, and it has no servers of its own that receive your data. It does, however, make network requests to the endpoints **you** configure — your LLM/embedding provider, the registries and source hosts you install from, and GitHub for upgrades — and those endpoints necessarily receive whatever those requests contain. This document describes exactly what AKM reads, writes, and sends.
+AKM stores your data locally on your machine and has **no telemetry**: it does not send usage data, analytics, or crash reports to Anthropic or to the AKM project, and it has no servers of its own that receive your data. It does, however, make network requests to the endpoints **you** configure — your model connections and embedding provider, the harness programs you enable, the registries and source hosts you install from, and GitHub for upgrades — and those endpoints necessarily receive whatever those requests contain. This document describes exactly what AKM reads, writes, and sends.
 
 ## No Telemetry
 
@@ -12,10 +12,11 @@ AKM does not:
 
 AKM adds no network destinations of its own. The requests it *does* make all go to endpoints you chose or invoked, and those third parties receive whatever the request contains:
 
-1. **Your configured LLM/embedding provider** (e.g. Anthropic, OpenAI, a local Ollama, or any OpenAI-compatible endpoint) receives the prompts and asset content sent for reflect/propose/distill/embedding when you enable those features. If you point AKM at Anthropic, Anthropic receives those requests.
+1. **Your configured connections and embedding provider** (e.g. Anthropic, OpenAI, a local Ollama, or any OpenAI-compatible endpoint) receive the prompts and asset content sent for reflect/propose/distill/embedding when you enable those features, and `akm setup`, `akm models` and `akm health` ask each endpoint which models it serves. If you point AKM at Anthropic, Anthropic receives those requests. Your API key is sent only to the endpoint of the connection it belongs to.
+   **A harness you enable** (Claude Code, Codex, OpenCode, ...) is a program akm runs on your machine, and what akm hands it reaches whatever that harness is configured for: its own provider, its own tools, its own MCP servers. It runs with your environment as it is ([How akm runs a harness](configuration.md#how-akm-runs-a-harness)). akm's own agent runtime (used when no harness is enabled) sends to your connection only.
 2. **Registry metadata and bundle packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
 3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
-4. **`akm setup`** — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
+4. **`akm setup`** — looks for an OpenAI-compatible server on `localhost` (ports 11434, 1234 and 8080) with one `GET /v1/models` each, and asks the endpoint you give it (and the embedding endpoint, if you pick another) for its model list. `--no-probe` contacts none of them.
 5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short per-request timeout, checked at a bounded concurrency rather than all at once) to every URL found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
 
 In every case the receiving endpoint is one you configured or invoked; the data leaving your machine is the data you directed AKM to send there.
@@ -48,7 +49,8 @@ AKM writes to these locations on your machine. All paths follow [XDG Base Direct
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `config.json` | Your AKM configuration: engines, improve strategies, bundles (bundle sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
+| `config.json` | Your AKM configuration: connections, harnesses, improve strategies, bundles (bundle sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
+| `credentials.json` | The API keys akm holds for your connections and for the `embedding` and `search.curateRerank` services, each with the endpoint it was stored for, written with mode 0600 (see [Credentials](configuration.md#credentials)) | **No** — deleting it removes those keys; akm sends requests without them |
 
 Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
@@ -62,6 +64,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
 | `backups/tasks/` | Copies of task files taken by `akm migrate apply` before it rewrites them, one timestamped directory per run that rewrote a file | Yes — once the migrated tasks are verified |
 | `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
+| `opencode-runtime/` | Everything akm's own agent runtime keeps: OpenCode's `config/` (with akm's plugin), `data/` (logs, repositories, shell output, and `data/opencode/opencode.db`, the runtime's sessions, which `akm proposal extract --type opencode` reads back, read-only), `cache/`, `state/` and `tmp/` (the binary's own native pieces) | Yes — recreated on next use; deleting it loses the runtime's session history |
 
 Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
 
@@ -101,10 +104,10 @@ Everything in the cache is regenerable. It is safe to delete the entire cache di
 | `config-backups/config.latest.json` | Latest backup alias (owner-only `0600`) | Yes |
 | `registry/` | Downloaded registry tarballs (bundle packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm bundle add` or `akm bundle update` |
 | `registry-index/` | Legacy per-URL JSON cache (v0.7 artifact) | Yes — fully replaced by `index.db` in 0.8.0 |
-| `semantic-status.json` | Semantic index build status marker | Yes |
 | `bin/` | Downloaded AKM binary cache (used by `akm upgrade`) | Yes |
 | `tasks/logs/` | Scheduled task log files. Written at your umask; they hold captured command/agent output, so tighten the directory yourself if the machine is shared | Yes — ephemeral logs |
 | `tasks/history/` | Legacy task history JSONL (v0.7 migration artifact) | Yes |
+| `opencode/<version>/` | The OpenCode binary akm's own agent runtime runs (about 240 MB), fetched from the npm registry on the runtime's first use | Yes — fetched again on next use |
 
 Override: set `AKM_CACHE_DIR` or `XDG_CACHE_HOME`.
 
@@ -170,7 +173,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `index_completed` | `akm index`, once when a run finishes | `mode`, `totalMs`, `walkMs`, `llmMs`, `embedMs`, `ftsMs`, `finalizeMs` (phase timings in milliseconds) |
 | `stash_synced` | `akm improve`'s internal sync passes (the `sync.push` feature), before the run and at its end, **distinct from** the `akm sync` command above | `phase` (`pre-run` or `end-of-run`), `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
-| `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
+| `env_access` | `akm env run <ref> -- <command>`, and a workflow unit's `env:` binding at each dispatch (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
 | `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
 
 *Proposals*

package/docs/reference/env-and-secrets.md

@@ -19,6 +19,16 @@ command; use `env` or `secret`.
 | Discoverable | key *names* (not values) | name only (the whole file is the value) |
 | Injects | many vars at once (`env run`) | one var (`secret run <ref> <VAR>`) |
 
+## Addressing: the akm ref
+
+`env` and `secret` assets are addressed like every other asset, by their akm
+ref `[bundle//]conceptId`: `env/prod`, `secrets/gitea_token`,
+`team//secrets/discord_bot_token`. There is no bare-name form. `akm secret
+run gitea_token ...` and `akm env run prod -- ...` are usage errors that name
+the full ref (`secrets/<name>`, `env/<name>`). An unqualified ref resolves the
+way every unqualified ref does: the default bundle first, then installation
+priority.
+
 ## Core security guarantee
 
 Values never appear in akm's structured output. `env list` and `akm show
@@ -31,8 +41,8 @@ the child process — never through akm's own stdout, the index, or `akm
 show`.
 
 ```sh
-akm env create prod                       # create an empty .env group
-akm env create prod --from-file ./.env    # or ingest an existing .env
+akm env create env/prod                   # create an empty .env group
+akm env create env/prod --from-file ./.env  # or ingest an existing .env
 
 # akm does not manage individual keys — edit the whole file with your own editor:
 $EDITOR "$(akm env path env/prod --quiet)"
@@ -58,17 +68,57 @@ script (re-serialised single-quoted, so shell substitutions in the source
 `.env` become literal strings) — it requires `--out` and never prints values
 to stdout.
 
-An env value can be a `${secret:<name>}` token, such as
-`DISCORD_BOT_TOKEN=${secret:discord_bot_token}`. `akm env run` and a workflow
-unit's `env:` binding both replace it with the secret at `secrets/<name>` in
-the env asset's own bundle; `env export` writes the token verbatim. `<name>` is
-a path under that `secrets/` directory, so `bundle//name` inside the token is
-not a bundle qualifier. A missing secret is an error and nothing is injected.
-In a workflow, every value of a bound env asset is redacted from the run's
-output and each read records an `env_access` event, so keep non-secret ids out
-of env assets used there. See
+## The `${ref}` token
+
+Wherever akm substitutes a reference into a string it hands to a process or a
+provider, the token is `${[bundle//]conceptId}`:
+
+- an env value: `DISCORD_BOT_TOKEN=${team//secrets/discord_bot_token}`;
+- a git bundle's config `credential`: `"${secrets/gitea_token}"`.
+
+Where the token may appear decides what it may name:
+
+- **In an env value**, any asset ref substitutes. A `secrets/...` ref stands for
+  the secret's value; any other asset ref (for example
+  `${scripts/lab/fetch.sh}`) stands for the asset's absolute path.
+- **In a git bundle's `credential`**, only a `secrets/...` ref is accepted. A `${...}`
+  naming any other kind of asset is rejected when the config loads.
+
+The ref is resolved with the one ref walk, so it may name any bundle and any
+asset its owner holds. A `${...}` body is a ref when it leads with a native type
+directory, qualified or not (`${secrets/x}`, `${scripts/run.sh}`,
+`${team//secrets/x}`), or when it is bundle-qualified and that bundle is
+installed (`${docs//tables/customers}`, whatever adapter owns it). `akm env
+run` and a workflow unit's `env:` binding replace the tokens in an env file's
+values; `env export` writes them verbatim. A `${...}` body that is not an akm
+ref (`${HOME}`, `${PATH//:/ }`, and shell substitution such as `${v//-/_}`
+unless a bundle named `v` is installed) is plain text: it is left untouched in an env
+value, and in a git bundle's `credential` a `${NAME}` that is a valid variable name is
+expanded from the process environment. A ref no bundle owns is an error and
+nothing is injected. Each read records an `env_access` event. See
 [Workflow Schema: Binding a secret to a unit](workflow-schema.md#binding-a-secret-to-a-unit).
 
+The API keys of model connections, `embedding` and `search.curateRerank` are
+not secrets-store references: they are a `$VAR` environment reference or an
+entry of `credentials.json` stored for the endpoint, and a `${secrets/...}` in an `apiKey` is ignored
+with a warning (see [Configuration: Credentials](configuration.md#credentials)).
+The `secrets/` store is for the secrets your own agents, tasks and bundle
+sources need.
+
+A secret's value is its file content with surrounding whitespace trimmed. That
+one read is used by `akm secret run`, env tokens, bundle credentials and the
+website fetchers, so a hand-written file's trailing newline never lands in an
+HTTP header.
+
+`${secret:NAME}` was the old env-value spelling, meaning the secret `NAME` in the
+env file's own bundle. akm still reads it that way, as `${<bundle>//secrets/NAME}`
+with the bundle that owns the env file, and warns once naming the env ref. The
+env file is bundle content and is not rewritten; write the full ref.
+
+`secret://name` was the config spelling of the same thing. It is retired:
+config still reads it as `${secrets/name}` and names the key once, and `akm
+migrate apply` rewrites the file.
+
 ## File modes and storage
 
 `.env` files are stored at mode 0600 under `env/` in the target bundle;
@@ -80,6 +130,12 @@ secret can carry a sibling `.sensitive` marker that excludes it from `list`
 output and from the search index entirely; the value remains usable via
 `run`.
 
+An env file or secret may be a symlink to a file anywhere else, such as a
+container's `/run/secrets/<name>`: `akm env`, `akm secret`, `${secrets/name}`
+substitution and a workflow `env:` binding follow it. A name still cannot climb
+out of `env/` or `secrets/` with `..` or an absolute path. Writes never follow
+a symlink out of the bundle.
+
 ## Write-target resolution
 
 Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
@@ -108,10 +164,11 @@ subprocess the child spawns.
 - Avoid running commands that print the environment (`env`, `printenv`,
   shell tracing, verbose diagnostics) in agent contexts unless you
   explicitly intend to expose the child environment.
-- Before spawning, injected key names are scanned for known
-  process-hijacking variables (`LD_PRELOAD`, `PATH`, `GIT_CONFIG_*`, ...): a
-  first-party bundle warns and proceeds, a third-party-sourced bundle is
-  refused.
+- Installing a bundle is the trust decision: `env run`, `secret run` and
+  workflow `env:` bindings inject what the bundle's files define, including
+  keys such as `PATH` or `LD_PRELOAD`, from any bundle, with no warning, block
+  or flag. `akm lint` still reports such keys (`dangerous-env-key`,
+  non-blocking) so an author can review their own files.
 
 ## Stability
 

package/docs/reference/refs.md

@@ -87,20 +87,6 @@ for retrieval — ship as the `facts/conventions/organization`,
 facts in the bundle skeleton, and are surfaced to agents automatically at
 authoring time.
 
-### Planned
-
-Not part of the current stability contract; see
-[ROADMAP.md](../../ROADMAP.md) for what's committed:
-
-- A `--namespace <ns>` flag to provide a thin name-prefix normalizer on
-  `search`, `remember`, `improve`, and `feedback` so the same prefix doesn't
-  have to be typed every time.
-- A `::` delimiter (for example `projectA::memories/auth-tip`) to provide
-  strict isolation so refs from different namespaces never collide in
-  ranking or recall.
-
-Until those land, physical subdirectories remain the recommended pattern.
-
 ## Renames and moves
 
 **Treat a ref as permanent.** A rename is **delete plus create**: the new
@@ -125,8 +111,7 @@ real refs dangling. The procedure above is the only supported path today.
 To carry an asset's earned signal (feedback, usage, salience/outcome
 history) across a rename, the maintainer script `scripts/rekey-asset-ref.ts`
 re-keys those rows onto the new ref before `akm index` runs; it is Internal
-tooling, not a supported command surface. See
-[the decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d3--renames-are-delete--create-akm-mv-ships-experimental).
+tooling, not a supported command surface.
 
 ## Refs in prose
 
@@ -143,9 +128,8 @@ fully-qualified `bundle//conceptId`; the short form is accepted input only),
 conceptId-prefix enumeration, and the rename-is-delete-plus-create procedure
 are all named explicitly in the Stable tier, and the ref grammar is called
 out as frozen at 1.0 alongside the supported source model, search behavior,
-and write-target rules. The `--namespace` flag and `::` delimiter above are
-On the horizon, not yet part of the contract. See `STABILITY.md` for the
-full command- and surface-level tier index.
+and write-target rules. See `STABILITY.md` for the full command- and
+surface-level tier index.
 
 ## See also
 
@@ -153,4 +137,3 @@ full command- and surface-level tier index.
 - [Asset Types](asset-types.md) — how a conceptId's subdirectory maps to an asset type
 - [Memory](memory.md) — parent/derived-memory provenance backrefs
 - [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the normative ref grammar spec
-- [ROADMAP.md](../../ROADMAP.md) — planned ref-syntax additions

package/docs/reference/registry.md

@@ -95,8 +95,6 @@ is no longer reachable in 0.9.2; publish it at a publicly routable HTTPS
 endpoint. The only private-network compatibility exception is an npm mirror
 explicitly selected with `AKM_NPM_REGISTRY`; metadata and tarball requests may
 reach that configured mirror, but not link-local or cloud-metadata addresses.
-See [Registry network boundary](../architecture/internals/registry-network-boundary.md)
-for the complete policy and DNS guarantee.
 
 ## Searching Registries
 
@@ -108,9 +106,6 @@ akm search "deploy" --from registry
 
 # Search both the local bundle library and registries
 akm search "deploy" --from all
-
-# Include asset-level results from v3 indexes
-akm search "deploy" --from registry --assets
 ```
 
 ### Search Results
@@ -124,24 +119,11 @@ Each registry hit includes:
 | `id` | Unique identifier (e.g. `npm:@scope/bundle`) |
 | `description` | Summary from the registry |
 | `action` | Ready-to-run next step such as `akm bundle add ... -> then search again` |
+| `installRef` | The ref to pass to `akm bundle add` to install the bundle. Present at every `--detail` level |
 | `quality` | Optional provenance marker — `"generated"`, `"curated"`, or `"proposed"`. Replaces the legacy `curated` boolean removed in 0.7.0 |
 
 Use `--detail full` to include ranking metadata like `score`.
 
-### The `--assets` Flag
-
-When a registry publishes a v3 index (see below), `akm search --from
-registry` can return individual asset-level hits in addition to bundle-level
-hits. Pass `--assets` to enable this:
-
-```bash
-akm search "code review" --from registry --assets
-```
-
-Asset hits include `assetType`, `assetName`, `description`, and the parent
-`stash` information, so you can install the right bundle and immediately know
-which asset to use.
-
 ## Discovery Filtering
 
 Not every npm package or GitHub repo is an akm bundle. To keep results
@@ -153,9 +135,7 @@ relevant, the registry enforces tag-based filtering:
 > **0.6.0 breaking change:** `akm-cli >= 0.6.0` indexes only the
 > `akm-stash` keyword / topic. The pre-0.6.0 `akm-kit` and `agentikit`
 > keywords/topics are **not** honored as fallbacks. Publishers migrating
-> from 0.5.x must add the new tag — see the
-> [migration guide](../migration/v0.5-to-v0.6.md) for the step-by-step
-> publisher checklist.
+> from 0.5.x must add the new tag.
 
 If you are publishing a bundle, add these tags so it can be discovered:
 
@@ -215,17 +195,12 @@ akm bundle add file:///absolute/path/to/bundle
 3. **Download and extract** -- The tarball is downloaded (or repo cloned) to a
    cache directory under `~/.cache/akm/registry/` and extracted securely
    (path traversal is rejected).
-4. **Security audit** -- Before install completes, the extracted bundle's
-   `env`/`secret` asset **key names** are checked against a denylist of
-   process-execution-hijacking variables -- dynamic-linker hooks
-   (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, ...), `PATH`, shell/runtime startup
-   hooks (`BASH_ENV`, `PROMPT_COMMAND`, `NODE_OPTIONS`, `PYTHONSTARTUP`, ...),
-   and interactive-tool overrides (`EDITOR`, `PAGER`, `GIT_SSH_COMMAND`, ...).
-   `akm bundle add` **blocks the install** when a dangerous key is present unless
-   `--allow-dangerous-env-keys` is set (or you confirm at an interactive prompt).
-   This is a **key-name audit only** (plus the path-traversal rejection in step
-   3) -- akm does **not** scan source files, prompts, metadata, or install
-   scripts for prompt-injection phrases, shell pipes, or lifecycle hooks.
+4. **No content audit** -- Installing a bundle is the trust decision. akm does
+   **not** scan the extracted bundle's source files, prompts, metadata, env
+   files or install scripts (beyond the path-traversal rejection in step 3), and
+   `akm bundle add` never blocks or prompts over the keys an env file sets.
+   `akm lint` reports env keys that can hijack a process (`dangerous-env-key`)
+   for authors who want to review their own bundle.
 5. **Bundle root detection** -- The extracted contents are scanned for asset
    type directories (`scripts/`, `skills/`, etc.) or a `.stash/` marker. If the
    bundle nests its bundle under an `opencode/` subdirectory, that is detected
@@ -428,9 +403,9 @@ official registry.
 ## Registry Index v3
 
 Version 3 of the registry index schema is the only format `akm-cli >=
-0.6.0` parses. It carries an `assets` array on each bundle entry so
-clients can perform asset-level search without installing the bundle
-first.
+0.6.0` parses. It carries an `assets` array on each bundle entry that
+describes the assets the bundle contains. `akm search --from registry` matches
+bundles; it does not return asset-level hits.
 
 ```json
 {
@@ -466,8 +441,7 @@ Each asset entry supports:
 The 0.6.0 release dropped support for the legacy v1 / v2 indexes;
 publishers must regenerate `index.json` with the
 `scripts/build-registry-index.ts` maintainer script
-or the [akm-registry](https://github.com/itlackey/akm-registry) tooling
-(see the [v0.5 → v0.6 migration guide](../migration/v0.5-to-v0.6.md)). akm
+or the [akm-registry](https://github.com/itlackey/akm-registry) tooling. akm
 treats unknown fields inside a v3 entry as forward-compatible.
 
 ## Cache Layout

package/docs/reference/supported-formats.md

@@ -68,6 +68,6 @@ formats are writable today and why.
 
 - [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) — the 14 native asset types AKM's own format recognizes
 - [Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks a format, the write-path internals, and current caveats
-- [Agent, Command, Engine, and Model Resolution](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/agent-command-engine-model-design.md) — approved runtime semantics for translated native agents and commands
+- [Architecture: Connections and Harnesses](https://github.com/itlackey/akm/blob/main/docs/architecture/architecture.md#connections-and-harnesses) — how translated native agents and commands are executed
 - [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) — the retrieval loop these formats feed
 - [Wikis](https://github.com/itlackey/akm/blob/main/docs/guides/wikis.md) — the `llm-wiki` authoring workflow

package/docs/reference/tasks.md

@@ -116,25 +116,36 @@ Script refs use this closed table; any other extension fails before dispatch:
 `run` is one non-empty shell string. It may specify `shell` from the closed host
 shell table `bash`, `sh`, `zsh`, `pwsh`, `powershell`, or `cmd`. Shell expansion
 is runtime behavior for an explicitly authored task `run`; AKM does not infer a
-shell from `uses`. `working-directory` must be a relative, contained path under
-the task's workspace root. Absolute paths, traversal, dangling links, and
-symlink escapes fail before execution.
+shell from `uses`. `working-directory` is a non-empty string, relative to the
+task's bundle root or absolute, like a workflow's `exec.cwd`. akm does not
+keep it inside the bundle or check it when the task source is parsed, so a
+symlink that resolves outside the bundle works. The task runs in
+`<bundle root>/<working-directory>` (or the absolute path as written): akm does
+not capture the directory's identity or re-check it when the task runs. A
+`uses: scripts/<file>` target may itself be a symlink to a file outside the
+bundle; the task freezes that file's bytes, not its location. The interpreter
+comes from the name the script has in the bundle, not from the file the link
+points to, so `scripts/deploy.sh` linked to `real-script.txt` runs under the
+shell.
 
 Every field that used to live under v3's `akm:` options bag is a top-level
-key in task source v4: `agent`, `engine`, `model`, `inference`, `tools`,
-`timeout`, `redact`, `maxSteps`, and `maxRetries`, plus `description`,
-`when_to_use`, and `tags`. Environment entries (`env`) are literal string,
+key in task source v4: `agent`, `connection`, `harness`, `model`, `inference`, `timeout`,
+`redact`, `maxSteps`, and `maxRetries`, plus `description`, `when_to_use`, and
+`tags`. A v3 `akm.tools` is dropped by the migration, and a v4 `tools` is
+ignored with a warning. Environment entries (`env`) are literal string,
 number, or boolean values. Keep credentials out of task source; `redact`
 contains environment variable names, never secret values.
 
 `timeout:` (milliseconds) means a different mechanism depending on the
 target. For `run:` (native shell/script) and `workflows/<name>` targets it is
-an outer supervisory deadline: the runner kills the child process, or aborts
-the workflow run at its next step boundary, when it fires. For `uses:
+an outer supervisory deadline: the runner stops the child process (SIGINT, then
+SIGTERM, then SIGKILL; see [How akm runs a
+harness](configuration.md#how-akm-runs-a-harness)), or aborts the workflow run at
+its next step boundary, when it fires. For `uses:
 akm/command`, `commands/<name>`, and any other agent/LLM dispatch target
 there is no outer process kill — `timeout:` instead resolves through the
 execution cascade (config/persona/command/task layers) into the dispatch's
-own deadline, and the SDK/CLI runner races each phase against it internally.
+own deadline, and the runner (a harness's process, or akm's own runtime) enforces it.
 Either way, a dispatch that times out is recorded as `status: failed` with
 `detail.reason: "timeout"` in `task_history` — not a silent `completed` — and
 `akm task run` exits non-zero for it; see [health-advisories.md's
@@ -211,7 +222,7 @@ schedule:
   - cron: "0 8 * * 1"
     inputs: { scope: all, ticket: OPS-1234 }
 timeout: 45000
-engine: reviewer
+harness: reviewer
 redact: [TOKEN]
 ```
 
@@ -408,7 +419,7 @@ for full before/after examples and recovery guidance.
   a `version: 4` file still carrying a retired `schedule[].enabled` (the finding
   names `akm migrate apply`, which converts them), a cron the local scheduler
   backend cannot parse, and a schedule entry whose `inputs` leave a required
-  input unsatisfied. It is read-only and needs no configured engine.
+  input unsatisfied. It is read-only and needs no configured connection or harness.
 - `akm task add` validates a task source v4 document, writes it, adds its ref
   to local scheduler activation, and syncs its bundle. `--params` renders
   typed `inputs:` declarations instead of a `with:` bag; `--schedule` is

package/docs/reference/ui-api.md

@@ -32,7 +32,7 @@ release, and nothing outside the page should script against them. Use the CLI's
   `ORIGIN_NOT_ALLOWED`, `METHOD_NOT_ALLOWED`, `UNSUPPORTED_MEDIA_TYPE`, `BODY_TOO_LARGE`, `INVALID_JSON_ARGUMENT`,
   `NOT_FOUND`, `INTERNAL_ERROR`.
 - **Redaction.** Config values under secret-like keys (`apiKey`, `token`, `password`, `secret`, `credential`,
-  `authorization`, anything under `env` or `secrets`) are `"[redacted]"`; symbolic references (`$VAR`, `secret://name`)
+  `authorization`, anything under `env` or `secrets`) are `"[redacted]"`; symbolic references (`$VAR`, `${secrets/name}`)
   are kept. Credentials inside any URL in any response (userinfo, `token=`, `api_key=`, `sig=`, ...) are masked. Env and
   secret assets are never read; see `/api/asset`.
 - **Timestamps** are ISO 8601 UTC unless noted. Counts that cannot be computed are `null`, never `NaN`.
@@ -75,7 +75,7 @@ Everything on the overview page in one call. Query parameters:
 | --- | --- | --- |
 | `since` | `24h` | Health window start (ISO, date, epoch ms, or `24h` / `7d`). A duration also turns on the prior-window comparison, as `akm health --report --since` does. |
 | `metricsSince` | `30d` | Metrics window start, as `akm metrics --since`. |
-| `probe` | off | `1` probes engine reachability and checks for a newer akm release (network). Off by default so loading the page makes no outbound calls. |
+| `probe` | off | `1` probes whether each connection's endpoint answers and what each harness's `--version` prints, and checks for a newer akm release (network). Off by default so loading the page makes no outbound calls. |
 
 ```json
 {
@@ -210,14 +210,16 @@ The effective configuration, as `akm config list` shows it, with where each valu
     "exists": true,
     "config": {
       "semanticSearchMode": "off",
-      "engines": { "default": { "kind": "llm", "endpoint": "https://llm.example.test/v1/chat/completions?token=%5Bredacted%5D", "model": "chat-model" } },
+      "connections": { "default": { "endpoint": "https://llm.example.test/v1?token=%5Bredacted%5D", "models": { "fast": "chat-model" } } },
+      "harnesses": { "claude": {} },
       "defaultBundle": "stash"
     },
     "entries": [
       { "path": "semanticSearchMode", "value": "off", "source": "file" },
       { "path": "output.format", "value": "json", "source": "default" }
     ],
-    "engines": [{ "name": "default", "kind": "llm", "endpoint": "https://llm.example.test/v1/chat/completions?token=%5Bredacted%5D", "model": "chat-model" }],
+    "connections": [{ "name": "default", "endpoint": "https://llm.example.test/v1?token=%5Bredacted%5D", "models": { "fast": "chat-model" } }],
+    "harnesses": [{ "name": "claude" }],
     "env": [{ "name": "AKM_BUNDLE_DIR", "value": "/home/me/akm" }]
   }
 }
@@ -226,8 +228,11 @@ The effective configuration, as `akm config list` shows it, with where each valu
 - `config` is the redacted effective config tree. `entries` is the same data flattened to one row per leaf (arrays are
   leaves) with `source`: `default` (no config file sets it), `file` (this install's `config.json`),
   `extends:<ref>` (a config it extends), or `null` when the key cannot be traced (a key containing a `.`).
-- `engines` is `config.engines` as a list. Reachability is a health probe, not config: use `/api/overview?probe=1`.
-- `env` lists the `AKM_*` environment variables set for the server, which override paths and credentials. A
+- `connections` and `harnesses` are `config.connections` and `config.harnesses` as lists, each entry with its `name`
+  and the entry's own keys (a connection's `endpoint` and `models`, a harness's `platform`, ...); keys are never
+  included (`apiKey` shows as `[redacted]` or its `$VAR` reference). Reachability is a health probe, not config: use
+  `/api/overview?probe=1`.
+- `env` lists the `AKM_*` environment variables set for the server, which override paths and other settings. A
   secret-like name (`...KEY`, `...TOKEN`, ...) has `value: "[redacted]"`.
 
 ## `GET /api/proposals`
@@ -570,7 +575,7 @@ Recent commits of the write-target stash (`defaultWriteTarget`, else the default
 }
 ```
 
-- `asset` is the show response in full (frontmatter fields such as `description`, `tags`, `toolPolicy`, the
+- `asset` is the show response in full (frontmatter fields such as `description`, `tags`, `modelHint`, the
   `content`, workflow `steps`, and so on depending on the type), and `links` groups declared links by kind
   (`outgoing`, `incoming`, `unresolved`). A missing ref is a `404` `ASSET_NOT_FOUND`.
 - `feedback.counts` are all-time totals by signal across every source; `history` is the latest 50 events, newest
@@ -616,7 +621,7 @@ general config editor or command-execution endpoint.
 | `POST` route | Body and existing operation |
 | --- | --- |
 | `/api/feedback` | `{ref, signal: "positive"\|"negative", reason?, tags?: string[]}` → `akm feedback`. The ref is passed to `akm feedback` as given, which resolves it as the CLI does; tags follow existing `key:value` validation. Negative feedback requires a reason when `feedback.requireReason` is enabled. Submissions are recorded with source `user` unless the server runs with an `AKM_EVENT_SOURCE` already set (for example under an improve or task run), which wins as it does for every akm child; they retain existing ranking/utility/event effects. Feedback does not save config, so it works under a config that still holds a literal API key. No fix, supersession or model flags are exposed. |
-| `/api/bundles/add` | `{source, name?, writable?}` → `akm bundle add`, including source validation and installation audit. Existing provider restrictions apply; no dangerous-key or insecure-transport bypass is exposed. |
+| `/api/bundles/add` | `{source, name?, writable?}` → `akm bundle add`, including source validation. Existing provider restrictions apply; no insecure-transport bypass is exposed. |
 | `/api/bundles/update` | `{bundle}` → `akm bundle update -- <bundle>`. Fetches/reindexes only on explicit submission. A rare update requiring destructive confirmation remains refused; the UI does not silently pass `--yes`. |
 | `/api/bundles/remove` | `{bundle, confirm: true}` → `akm bundle remove --yes -- <bundle>`. The UI requires an inline confirmation before this call. Managed installs may be deleted; local filesystem source files remain on disk. |
 | `/api/bundles/settings` | `{bundle?, enabled?, writable?, componentWritability?: {existingComponent: boolean}, defaultBundle?, defaultWriteTarget?}` → existing schema-walking config setters inside `mutateConfig`. Only changed controls are submitted. Defaults take existing names or `""` to unset a local value; inherited values cannot be unset locally. Existing validation rejects invalid defaults, disabled targets and writable npm/website sources. |
@@ -624,7 +629,7 @@ general config editor or command-execution endpoint.
 | `/api/asset/save` | `{ref, revision, content}` → the existing shared Markdown writer with `force` and the expected raw-content hash. Only indexed writable AKM knowledge/memory documents accepted by `/api/asset/source` can be edited. The writer takes the asset-mutation lease and compares the live source with `revision` inside it, immediately before writing. While another writer holds the lease the save fails fast with `409 ASSET_MUTATION_LEASE_HELD` instead of waiting. A stale revision returns `409 ASSET_CONTENT_CHANGED` without writing; a source deleted after it was loaded is refused (`404 ASSET_NOT_FOUND`) rather than recreated. The browser keeps the draft after a rejected save. An identical save returns `unchanged: true` without rewriting, reindexing or recording an event. Changed saves retain normal writer validation, indexing and Git effects. |
 
 Configuration-affecting actions do not round-trip the redacted API configuration. Existing mutation helpers retain
-unknown/unrelated fields, local overrides and supported `$VAR`/`secret://` credential references. If the existing
+unknown/unrelated fields, local overrides and supported `$VAR`/`${ref}` credential references. If the existing
 config sanitizer would remove unrelated legacy literal credentials, a bundle add or remove, or a settings change that
 would write config, is refused with `400 INVALID_FLAG_VALUE` and the user is asked to correct those settings through
 the CLI first. A settings request that changes nothing writes nothing and is not refused. It never writes