akm-cli 0.9.14 → 0.9.15-beta.1

package/docs/reference/configuration.md

@@ -3,7 +3,10 @@
 AKM reads one user configuration file: `$XDG_CONFIG_HOME/akm/config.json`
 (normally `~/.config/akm/config.json` on Linux and macOS, or
 `%APPDATA%\akm\config.json` on Windows). Set `AKM_CONFIG_DIR` to override the
-directory. Project `.akm/config.json` files are not merged.
+directory. Project `.akm/config.json` files are not merged. A config file may
+optionally extend one other config via `extends` (see "Sharing configuration
+across installs" below) — this is a single, explicit, user-opted-in key, not
+automatic project-config discovery.
 
 ## Version 0.9
 
@@ -89,14 +92,21 @@ LLM endpoints must be complete `http://` or `https://` chat-completions URLs
 ending in `/chat/completions`, without userinfo, query, or fragment. API keys
 are symbolic only: `$VAR` or `${VAR}`. AKM resolves them only at dispatch.
 
-An LLM engine may set `reasoningEffort` to a non-empty provider-supported
-value such as `"none"`, `"low"`, or `"high"`. AKM sends it as the top-level
-OpenAI-compatible `reasoning_effort` parameter alongside the existing
-`enableThinking` control, because providers do not all honor the same thinking
-switch. `reasoning_effort` is AKM-owned and cannot be set through
-`extraParams`. If a response reports reasoning tokens despite
-`enableThinking: false`, AKM emits a runtime warning so an ineffective provider
-control is visible.
+An LLM engine may set `enableThinking: false` to turn thinking off and
+`reasoningEffort` to a value such as `"none"`, `"low"`, or `"high"`. AKM sends
+**both** wire forms — `chat_template_kwargs.enable_thinking` and top-level
+`enable_thinking` — whenever `enableThinking` resolves, from engine config
+or a calling process (improve's `consolidate`/`reflect` and the distill
+quality gate always request `enableThinking: false` for a machine-readable
+payload); `reasoningEffort` is always sent as top-level `reasoning_effort`
+when set. Backend support: llama.cpp direct honors both forms
+(`reasoning_effort` from build ≥ b10644); vLLM honors
+`chat_template_kwargs`; Bifrost drops `chat_template_kwargs` and passes
+`reasoning_effort` through, so also set `reasoningEffort: "none"` behind it; a
+strict hosted API may 400 on unrecognized keys. Both fields are AKM-owned, not
+settable via `extraParams`. A response with reasoning tokens despite
+`enableThinking: false` triggers a runtime warning and the `akm health`
+`thinking-control` advisory.
 
 An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`.
 Only `platform: "opencode-sdk"` may set `llmEngine`; it names
@@ -147,19 +157,54 @@ the same version-1 schema as the installed file:
 ```
 
 Each engine mapping is either a non-empty exact model string or a structured
-profile with the documented fields `model` and `inference`. A user profile may
-omit `model` when the installed layer already supplies it, as the partial
-Claude override above does. After overlay, every alias/engine entry must have a
-usable model. Unknown profile fields are rejected; JSON-safe fields inside
-`inference` are preserved for engine adapters to lower optimistically.
+profile with the documented fields `model`, `inference`, and `engine`. A user
+profile may omit `model` when the installed layer already supplies it, as the
+partial Claude override above does. After overlay, every alias/engine entry
+must have a usable model. Unknown profile fields are rejected; JSON-safe
+fields inside `inference` are preserved for engine adapters to lower
+optimistically.
+
+A profile's `engine` field (0.9.15, #946) borrows a column's `model` (and, for
+an `llm`-kind engine, its inference defaults) from a configured
+`engines.<name>` connection instead of hand-typing a literal model a second
+time:
+
+```json
+{
+  "version": 1,
+  "aliases": {
+    "fast": {
+      "opencode": { "engine": "local-fast" }
+    }
+  }
+}
+```
+
+With `engines.local-fast` configured (agent-kind or llm-kind), this column
+resolves to that engine's own `model` string. `model` and `engine` are
+mutually exclusive on the same profile — `engine` is an indirection for the
+model value, never an engine-selection override; which engine `akm agent`
+dispatches to is still decided entirely by `--engine`/`defaults.engine` (see
+[Engine selection](#engines)). The referenced engine's `model` must itself be
+literal, not another alias, and akm copies it verbatim: it does not translate
+between an engine's connection and an agent platform's own provider registry,
+so the value must already be meaningful for the column's platform (e.g. a
+`kind: "agent", platform: "opencode"` engine's `model` should already be a
+string opencode itself understands, such as `krang/qwen3.5-9b`). Run
+`akm models list` to see, for every alias/column, the resolved model and
+whether it came from the installed defaults, the user overlay, and a literal
+value or an `engine` reference.
 
 The user file overlays the installed file by alias, engine, and nested object
 field. Objects merge recursively. Arrays, scalars, and explicit `null` replace
-the lower value; omitted fields preserve it. Alias and engine keys are
-case-normalized, and case-colliding definitions are rejected. Unknown model
-inputs still pass through byte-for-byte as exact identifiers. Once a name is a
-known merged alias, selecting an engine with no mapping is an actionable
-configuration error rather than silently sending the alias as a model ID.
+the lower value; omitted fields preserve it. A layer setting a literal `model`
+clears any `engine` inherited from a farther layer, and vice versa — the
+nearer layer's choice of literal-vs-engine always wins outright rather than
+merging. Alias and engine keys are case-normalized, and case-colliding
+definitions are rejected. Unknown model inputs still pass through
+byte-for-byte as exact identifiers. Once a name is a known merged alias,
+selecting an engine with no mapping is an actionable configuration error
+rather than silently sending the alias as a model ID.
 
 The common execution cascade reads these files for current direct command and
 non-interactive agent calls, task source v4 runs, and improve/proposal/index
@@ -354,6 +399,19 @@ reference, same rules as engine `apiKey`), `dimension`, `localModel`,
 `maxTokens`, `batchSize`, `chunkSize`, `contextLength`, and
 `ollamaOptions.num_ctx`.
 
+`akm index` keeps a small, fixed number of `/v1/embeddings` requests in
+flight at once (a remote endpoint only; the local transformer path is
+unaffected): `1` for a loopback endpoint (`localhost`, `127.0.0.0/8`, etc. —
+a local model server serves one inference at a time, and parallel requests
+thrash it) and `2` for a remote one. This width is not configurable. The
+actual throughput knob is request SIZE, not request count: `embedding.batchSize`
+(a document-count cap, default 100) together with `embedding.maxTokens` /
+`embedding.contextLength` (an estimated token budget per request, default
+8000) control how many documents land in one request — a batch of 16-32
+documents takes about the same wall time as a single one against a healthy
+endpoint, so growing the batch is where most of the win is, not adding more
+concurrent requests.
+
 ## Search tuning
 
 `search` tunes ranking, not behavior an ordinary user needs to touch:
@@ -484,6 +542,94 @@ Arrays replace, `null` is only valid for nullable fields, and `config unset` is
 the only deletion operation. `configVersion` cannot be set or unset with the
 generic walker.
 
+`config get <key> --show-source` wraps the (redacted) value as
+`{ value, source }`, where `source` is `"local"` when the local file's own
+JSON sets the key, `"extends:<ref>"` for the nearest `extends` chain member
+that sets it, or `"default"` when neither does. It is opt-in — plain
+`config get` keeps its Stable, script-safe bare-value shape.
+
+### Sharing configuration across installs
+
+Five hosts running the same fleet often carry an identical `engines` map and
+`improve.strategies` block, differing only in credential delivery (`apiKey`
+vs `apiKeyFile`), bundle paths, and cron offsets. Hand-syncing that block
+across hosts drifts silently. `extends` fixes this: put the shared block in
+one file, and have each host's local config extend it.
+
+```jsonc
+// bundles/fleet/config/shared.json — versioned with the bundle, shared by every host
+{
+  "configVersion": "0.9.0",
+  "engines": {
+    "fast": { "kind": "llm", "endpoint": "https://api.example.test/v1/chat/completions", "model": "qwen3" }
+  },
+  "improve": { "strategies": { "nightly": { "engine": "fast" } } }
+}
+```
+
+```jsonc
+// ~/.config/akm/config.json — this host's local file, under 20 lines
+{
+  "configVersion": "0.9.0",
+  "extends": "fleet//config/shared.json",
+  "bundles": {
+    "fleet": { "git": "https://github.com/example/fleet-bundle.git" },
+    "stash": { "path": "~/akm-stash", "writable": true }
+  },
+  "defaultBundle": "stash",
+  "engines": { "fast": { "apiKeyFile": "/run/secrets/fast-api-key" } }
+}
+```
+
+`extends` accepts either form:
+
+- A filesystem path — relative paths resolve against the directory of the
+  config file that declares them; a leading `~` expands.
+- A `bundle//<path>` ref — a plain file path *relative to that bundle's
+  content root* (e.g. `config/shared.json`), resolved through the bundle's
+  configured `path`, not the search index — so it never needs `akm index` to
+  have run. This is not an asset ref: the path after `//` needs no asset type
+  (`scripts/`, `knowledge/`, …) and the shared file is never indexed; it can
+  live anywhere under the bundle. An empty, absolute, or content-root-escaping
+  path is rejected. Only a filesystem bundle (`bundles.<id>.path`) can host an
+  `extends` source; sync a `git`/`website` bundle with `akm bundle
+  add`/`akm sync` first so the file is materialized locally, then point
+  `extends` at it.
+
+There is no `extends: <url>` form: config load is synchronous and runs on
+every invocation, and akm deliberately does not fetch network resources at
+load time (the same reason `registries` is never fetched until a
+registry-touching command runs). A URL-backed shared config should be synced
+as a `git`/`website` bundle and referenced as `extends: bundle//<path>`
+once materialized, reusing the sync machinery akm already has instead of a
+second one inside config load.
+
+The base config runs through the exact same load pipeline as the local
+file — its own version shim, its own legacy-shape shim — so it can carry an
+older `configVersion` independently, and it may itself set `extends`
+(chained). Cycle detection (`ConfigError`, "extends cycle detected") stops A
+extends B extends A instead of recursing forever. Merge order is
+`DEFAULT_CONFIG` (outermost) → the resolved `extends` chain → the local
+file's own keys (local always wins) — the same `deepMergeConfig` "override
+wins" semantics `config set` already uses. A referenced file/bundle that does
+not already exist locally is a load-time `ConfigError` naming the ref — akm
+never fetches or syncs one on your behalf.
+
+`akm config diff <path|bundle//path>` compares this host's EFFECTIVE
+config (its own `extends` already applied) against another config file or
+bundle-relative file (loaded through the same loader, so ITS `extends` is
+honoured too), printing sorted `{ path, local, other }` rows for every leaf
+that differs. Both sides are redacted the same way `config get`/`list` are
+before comparison, so a differing secret never round-trips into the diff
+output. Cross-host comparison (`ssh host2 akm config diff ...` in a loop) is
+left to the operator; akm has no concept of a networked fleet to compare
+against directly.
+
+```sh
+akm config diff ~/other-host/config.json
+akm config diff fleet//config/shared.json
+```
+
 ## Environment
 
 | Variable | Purpose |
@@ -513,6 +659,21 @@ not itself a secret. Setting both `apiKey` and `apiKeyFile` on the same
 engine is rejected. A missing, unreadable, or empty file fails the call
 closed, naming the engine and path but never the file's content.
 
+`engines.<name>.apiKey` also accepts `secret://<name>`, a reference into
+AKM's own secret store (`akm secret set <name> --from-file <file>`), for a
+launch context where the credential's environment variable is deliberately
+not sourced into the process — a scheduled task's crontab preamble, or a
+container entrypoint that keeps the user's env out on purpose — and a
+file-backed credential is not an option. Like `apiKeyFile`, only the
+reference is kept in `config.json`; the store lookup happens at dispatch
+time, and an unresolved reference fails the call closed, naming the
+reference but never the value. `akm improve`, workflow LLM steps, and `akm
+health`'s engine probes all resolve `secret://` the same way direct LLM and
+embedding calls have since 0.9.13 (#917); resolution order for a single
+`apiKey` field is: an env reference (`$VAR`/`${VAR}`) first, then
+`apiKeyFile`, then `secret://<name>` — though in practice a config sets only
+one of the three per engine.
+
 Use `AKM_SQLITE_JOURNAL_MODE=DELETE` or `TRUNCATE` when WAL is unavailable,
 such as on some NFS/SMB mounts. With the default `WAL` setting, AKM detects a
 network filesystem for the data directory and falls back to `DELETE`.

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

@@ -230,6 +230,14 @@ the set of types the code actually emits at HEAD (verified against every
 | `llm_usage_summary` | The owning LLM telemetry sink's terminal-record count marker | `expectedTerminalRecords` |
 | `health_probe` | `akm health`'s state.db round-trip write/read probe. **Not durably retained**: the row is inserted then deleted within the same connection once the round trip is confirmed, so the net effect on the `events` table is always zero rows | n/a (ephemeral) |
 
+`llm_usage` rows also carry `process`/`engine`/`stage` (each optional; a call
+made outside any attributed scope carries none of them). `akm improve`
+(#944) aggregates a run's own `llm_usage` events into a process x engine x
+model cross-tab — `summarizeLlmUsageCrossTab` in `src/commands/health/llm-usage.ts`
+— persisted on the run result as `usageReport.byProcessEngineModel` and
+queryable per-run or aggregated with `akm improve report`; see
+`docs/reference/cli.md`'s `#### improve report` section.
+
 ### 2. Usage Events Table
 
 `usage_events` is the local analytical record behind utility ranking,

package/docs/reference/tasks.md

@@ -121,6 +121,20 @@ key in task source v4: `agent`, `engine`, `model`, `inference`, `tools`,
 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:
+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.
+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
+`task-fail-rate` row](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/health-advisories.md)
+for how `akm health` surfaces a timeout-dominant failure pattern.
+
 ## Scheduling
 
 Scheduling is **optional**. Omit `schedule:` entirely for a manual-only
@@ -381,7 +395,8 @@ for full before/after examples and recovery guidance.
 
 ## Operations
 
-- `akm search --type task` and `akm show tasks/<id>` inspect task assets.
+- `akm search --type task` (or its alias `akm task list`) and
+  `akm show tasks/<id>` inspect task assets.
 - `akm task explain <ref>` prints a task's declared inputs, resolved target,
   effective execution settings, and schedule bindings without running
   anything — see [`akm task explain`](#akm-task-explain) above.

package/docs/reference/workflow-schema.md

@@ -1352,7 +1352,11 @@ optional user `models.json` files:
 
 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. See the [Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md#choosing-engines-and-models)
+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.
 
 ## See also

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.14",
+  "version": "0.9.15-beta.1",
   "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": [

package/schemas/akm-config.json

@@ -9,6 +9,10 @@
       "type": "string",
       "const": "0.9.0"
     },
+    "extends": {
+      "type": "string",
+      "minLength": 1
+    },
     "engines": {
       "type": "object",
       "additionalProperties": {
@@ -1696,6 +1700,10 @@
           "type": "string",
           "const": "0.9.0"
         },
+        "extends": {
+          "type": "string",
+          "minLength": 1
+        },
         "engines": {
           "type": "object",
           "additionalProperties": {