akm-cli 0.9.25-alpha.1 → 0.9.25-alpha.3

package/dist/workflows/exec/unit-dispatch.js

@@ -5,8 +5,7 @@ import { ConfigError } from "../../core/errors.js";
 import { assertFrozenDirectoryContained } from "../../execution/directory-identity.js";
 import { canonicalResolvedExecutionRequest } from "../../execution/resolved-request.js";
 import { buildExecutionFromWire } from "../../integrations/agent/execution.js";
-import { runExecution } from "../../integrations/agent/runner-dispatch.js";
-import { getHarness } from "../../integrations/harnesses/index.js";
+import { runExecution, unwrapHarnessReply } from "../../integrations/agent/runner-dispatch.js";
 /** Lower a frozen common request through its frozen runner only. */
 export function prepareWorkflowExecution(request, prompt = request.prompt) {
     const target = request.frozenTarget;
@@ -107,17 +106,9 @@ export async function dispatchWorkflowExecution(request, feedback) {
             ...(notices ? { notices } : {}),
         };
     }
-    let text = result.stdout;
-    let sessionId = result.sessionId;
-    if (lowered.runner.kind === "agent" && result.ok) {
-        const harness = getHarness(lowered.runner.profile.platform ?? lowered.runner.profile.name);
-        if (harness?.resultExtractor) {
-            const extraction = harness.resultExtractor(result);
-            text = extraction.text;
-            if (extraction.sessionId !== undefined)
-                sessionId = extraction.sessionId;
-        }
-    }
+    const extraction = result.ok ? unwrapHarnessReply(lowered.runner, result) : undefined;
+    const text = extraction?.text ?? result.stdout;
+    const sessionId = extraction?.sessionId ?? result.sessionId;
     return {
         ok: result.ok,
         text,

package/docs/reference/cli.md

@@ -517,7 +517,6 @@ kept.
 | `--filter` | `<key>=<value>` | _(none)_ | Scope filter — repeatable. Valid keys: `user`, `agent`, `run`, `channel`. Example: `--filter user=alice --filter channel=ops`. Narrows the result set; ranking is unchanged. |
 | `--include-proposed` | flag | `false` | Include entries with `quality: "proposed"` in the result set. Default search excludes them; `generated` and `curated` quality entries are always included. Unknown quality values warn once and remain searchable. |
 | `--belief` | `all`, `current`, `historical` | `all` | Memory belief filter. `current` keeps active memory beliefs; `historical` keeps contradicted/superseded/archived ones. |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 | `--include-sessions` | flag | `false` | Include session assets, which are excluded from default results via `config.search.defaultExcludeTypes` |
 | `--format` | `json`, `jsonl`, `yaml`, `text`, `md`, `html` | `json` | Output format |
 | `--detail` | `brief`, `normal`, `full` | `brief` | Output verbosity level |
@@ -593,7 +592,6 @@ akm curate "learn the release workflow" --from all --format text
 | `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter curated results by asset type |
 | `--limit` | number | `4` | Maximum curated results |
 | `--from` | `local`, `registry`, `all` | `local` | Where to search before curating |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 
 `akm curate` takes the top `--limit` hits of one search, in search order, and
 enriches each with a preview, run details and up to two support refs: the
@@ -623,7 +621,6 @@ curated like any other.
 every prompt: it only ever reads the index as it currently stands (the same
 non-blocking `ensureIndex()` path `search` uses) and never waits on or
 contends with a full `akm index` rebuild in progress.
-Use `--no-track-usage` when this inspection must not record usage events.
 
 ### show
 
@@ -631,9 +628,6 @@ Display an asset by ref. On a markdown document `#fragment` selects one
 section by heading slug (falling back to case-insensitive heading text); an
 unmatched fragment lists the available slugs.
 
-Successful reads record local usage events by default; pass
-`--no-track-usage` to suppress them.
-
 ```sh
 akm show scripts/deploy.sh
 akm show skills/code-review
@@ -662,7 +656,6 @@ akm show memories/retro --filter user=alice --filter agent=claude
 | `--max-chars` | positive integer | `3200` for `lead` | Hard contextual content budget in characters; requires `--context lead` and is mutually exclusive with `--max-tokens`. |
 | `--max-tokens` | positive integer | _(none)_ | Approximate contextual budget using four characters per token; requires `--context lead` and is mutually exclusive with `--max-chars`. |
 | `--filter` | `<key>=<value>` | _(none)_ | Repeatable scope filter (`user`, `agent`, `run`, `channel`). |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read. |
 
 `meta` is not an asset type — `[<origin>//]meta[:<name>]` direct-reads a
 human-authored orientation doc from a bundle's optional `.meta/` directory
@@ -2431,6 +2424,7 @@ akm improve lessons/my-lesson --show-prompt --format text # print the composed r
 akm improve report                     # LLM usage/routing report for the most recent real run
 akm improve report --run <id>          # ...for one specific improve_runs id
 akm improve report --since 7d          # ...aggregated over every real run started in the last 7 days
+akm improve judge < revision.json      # reflect's quality judge on one revision; writes nothing
 ```
 
 | Flag | Description |
@@ -2606,16 +2600,16 @@ default probe-on behavior) to check whether a named engine actually answers.
 
 `--show-prompt` (#952) is the cheapest way to exercise reflect alone: it
 builds the exact prompt reflect would send for one asset — the same source
-resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
-proposal gathering `akm improve`'s live reflect step uses — and prints it
+resolution, runner selection, feedback/schema-hint/rejected-proposal
+gathering `akm improve`'s live reflect step uses — and prints it
 without reading a credential, so it never calls an engine. An LLM engine
 receives the reply's JSON Schema as `response_format`, and an agent engine as
 an instruction that dispatch appends to this prompt. Add
 `--format text` (the default JSON/yaml envelope escapes the prompt into one
 line, which defeats a by-eye read) to confirm by eye that recent feedback is
-framed as an unverified report to investigate (never a fact to insert
-verbatim) and that the response contract tells the model never to emit the
-truncation marker or any content from outside the shown asset.
+framed as a signal (never a fact to insert) and that the response contract asks
+only for `confidence` and a `frontmatterPatch` of `description`,
+`when_to_use` and `title`: akm keeps the body.
 
 When reinforced facts need promotion, `knowledge` is the higher-authority
 destination than `memory`.
@@ -2660,6 +2654,17 @@ that run's own `llm_usage` events instead of erroring, sets `noCalls` to `[]`
 `notes` entry saying so rather than fabricating precision the old row can't
 support.
 
+#### improve judge
+
+`akm improve judge` runs reflect's quality judge on one revision and prints its
+verdict, for testing a judge engine on revisions whose right answer you know. It
+reads `{"source": "...", "candidate": "...", "feedback": "...", "ref": "..."}` JSON
+from stdin (`feedback` and `ref` are optional; `ref` names the revised asset,
+which a judge on an agent engine may read), judges with the engine the strategy's
+`processes.reflect.qualityGate.engine` names (`--strategy` picks the strategy),
+and prints `{ engine, pass, score, reason, criteria }` with the gate's prompt and
+pass rule. A `score` of `-1` means the judge gave no verdict. It writes nothing.
+
 ### proposal
 
 Manage the proposal queue. The canonical grammar is `akm proposal <verb>`:
@@ -2687,21 +2692,23 @@ authenticates its root; it never falls back to an ambient write target.
 #### proposal extract
 
 Extract durable insights from native coding-agent session files (claude-code,
-opencode) and queue them as proposals. This is the standalone entrypoint for
-session extraction — it replaces the legacy session-checkpoint hook and runs
-independently of the improve-stage extract toggle (see `improve` above).
+codex, opencode) and queue them as proposals. This is the standalone
+entrypoint for session extraction — it replaces the legacy session-checkpoint
+hook and runs independently of the improve-stage extract toggle (see `improve`
+above).
 
 ```sh
 akm proposal extract --type claude --session-id <id>
 akm proposal extract --type claude --since 24h
 akm proposal extract --type opencode --since 7d --dry-run
+akm proposal extract --type codex --since 24h
 akm proposal extract --auto                 # iterate every available harness
 akm proposal extract --type claude --location /custom/path --session-id <id>
 ```
 
 | Flag | Description |
 | --- | --- |
-| `--type <harness>` | Harness name (`claude`, `opencode`). Required unless `--auto`. |
+| `--type <harness>` | Harness name (`claude`, `codex`, `opencode`). Required unless `--auto`. |
 | `--session-id <id>` | Process only this session ID. When absent, discover sessions via `--since`. |
 | `--location <path>` | Override the harness's default session-discovery location. |
 | `--since <cutoff>` | Discovery cutoff. ISO timestamp or duration (`24h`, `7d`, `30m`). Default `24h`. |
@@ -2719,6 +2726,12 @@ session-log location on the current machine — and returns an aggregated
 per-harness `results`); the run exits non-zero only when every harness
 failed.
 
+The `codex` harness reads Codex's rollout files under `$CODEX_HOME/sessions`
+(`~/.codex/sessions` by default; `--location` points at another rollout
+directory). It lists a person's sessions, `codex exec` runs included, and
+leaves out the rollouts Codex writes for subagents and its other internal agents:
+those are not sessions of their own.
+
 There is no `akm proposal extract --watch`/`--debounce-ms` either (0.9.0:
 dropped — a foreground polling daemon in a one-shot CLI); the shipped
 `core/extract.yml` cron template (`akm proposal extract --auto` on a

package/docs/reference/configuration.md

@@ -126,10 +126,9 @@ value matching this JSON Schema (no prose, no code fences):` followed by the
 schema), plus the harness's own schema channel where it has one (codex
 `--output-schema`).
 
-An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`,
-and the inference fields its platform translates (see
-[Inference on an agent engine](#inference-on-an-agent-engine)).
-Only `platform: "opencode-sdk"` may set `llmEngine`; it names
+An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`;
+it takes no inference of its own (see
+[Inference on an agent engine](#inference-on-an-agent-engine)). Only `platform: "opencode-sdk"` may set `llmEngine`; it names
 the LLM engine used as that SDK engine's fallback connection. With no
 `llmEngine`, an SDK engine has no fallback connection and opencode resolves
 provider, model and auth from its own configuration. `defaults.llmEngine` is
@@ -138,10 +137,10 @@ not a substitute.
 On an engine without `timeoutMs`, model work (an improve process, a quality or
 triage judge, or an index pass) stops after 600 seconds, whatever the engine's
 kind; other work on an agent engine runs until it finishes. An improve stage's
-reply that does not match the stage's JSON Schema gets one corrective retry
-before the stage reads it. Reflect holds its reply to its own contract the same
-way on every engine kind: a reply that is not the JSON object of reflect's
-schema gets one repair turn, and one still invalid fails with `parse_error`.
+reply that the stage cannot read gets one corrective retry. Reflect holds its
+reply to its own contract the same way on every engine kind: a reply that is not
+the JSON object of reflect's schema gets one repair turn, and one still invalid
+fails with `parse_error`.
 
 Executable assets may request tools, but the request is not authority. Configure
 the host-local `execution.allowedTools` list to define the ceiling; `"*"` is an
@@ -157,74 +156,28 @@ with `npm i -g opencode-ai` or opencode's own installer.
 
 ### Inference on an agent engine
 
-A request's inference (`temperature`, `maxTokens`, `contextLength`,
-`enableThinking`, `reasoningEffort`) reaches an agent engine's harness from
-every place it can come from: the engine's own settings, an improve process's
-`llm` overlay, a task, command or agent asset's `inference`, a workflow's
-`llm:`, and a `models.json` alias. The nearest layer wins, field by field, as
-for an LLM engine. With no setting anywhere akm sends nothing of its own, so
-the model's own default applies: a `reasoningEffort: "none"` that your opencode
-config sets on a model stays in force until a layer overrides it.
+An agent engine sets no inference of its own. For `opencode`, set it on the
+model in your own opencode config, which akm leaves as it is. akm carries
+inference (`temperature`, `reasoningEffort`, `enableThinking`, `maxTokens`,
+`contextLength`) into opencode only where it writes opencode's config itself:
 
-Each platform translates what it can carry:
+- **Model work on `opencode` and `opencode-sdk`:** an improve process's `llm`
+  overlay becomes the options of the `akm-model-work` agent that runs the
+  dispatch, so opencode's own title call on the same model keeps its defaults.
+- **An `opencode-sdk` engine's `llmEngine` fallback:** the model akm declares for
+  it under `akm-custom` carries the fallback's inference and the request's.
+  `maxTokens` and `contextLength` become `limit.output` and `limit.context`, and
+  only together: opencode refuses half a `limit`.
 
-| Platform | Translates | How |
-|---|---|---|
-| `claude` | `reasoningEffort` | `--effort <level>`, in the harness's own levels (`low`, `medium`, `high`, `xhigh`, `max` in Claude Code 2.1.283). The value is passed as given, so one Claude Code rejects fails the dispatch. |
-| `opencode`, `opencode-sdk` | `temperature`, `reasoningEffort`, `enableThinking`, and `maxTokens` with `contextLength` | Injected opencode config, below. |
-| every other platform | nothing | |
-
-An agent engine that sets a field its platform does not translate fails to
-load, with an error that names the platform and the fields it does translate.
-Inference that reaches the engine from an asset or a caller, and that the
-platform does not translate, is reported as an `untranslated-field` notice and
-dispatch continues, because the same asset may run on any engine.
-
-On `opencode` and `opencode-sdk`, inference goes into opencode's config for the
-model the dispatch names: the request's model, or the `--model` an `opencode`
-engine's `args` name. That must be a `provider/model`, except for an
-`opencode-sdk` engine with an `llmEngine` fallback, which routes the
-fallback's model through its own provider. Without a model to attach to the
-fields are reported as untranslated, except that model work's agent (below)
-carries its options whichever model opencode picks, so an `opencode-sdk` engine
-with no `model` and no `llmEngine` still gets them. The injected entry merges
-over your own opencode config for the same provider and model, so what the
-request does not set stays as you wrote it. A dispatch with no inference injects
-nothing. akm
-checked these shapes against opencode 1.18.25 and an OpenAI-compatible provider
-(`@ai-sdk/openai-compatible`); another provider package is given the same
-options and may ignore one.
-
-- `temperature` becomes `options.temperature`, and `reasoningEffort` becomes
-  `options.reasoningEffort`. opencode reads the camelCase name: its
-  `reasoning_effort` spelling is dropped, so a model option written that way in
-  `opencode.jsonc` does nothing.
-- `enableThinking` becomes `options.chat_template_kwargs.enable_thinking` and
-  `options.enable_thinking`, the two forms an LLM engine sends.
-- `maxTokens` becomes `limit.output` and `contextLength` becomes
-  `limit.context`. Set them together. Without `limit.output` opencode asks for
-  `max_tokens: 32000`, which a small-context server rejects, and a wrong
-  `limit.context` lets opencode build requests longer than the server's window.
-  opencode refuses a `limit` with only one of them, and a half would overwrite
-  the other half of a limit you declared for the model, so akm declares `limit`
-  only when it has both and reports a lone `maxTokens` or `contextLength` as
-  untranslated.
-- For model work (below) the options go on the `akm-model-work` agent that runs
-  the dispatch, so opencode's own call on the same model, a title for the
-  session, keeps the model's defaults. Any other dispatch runs your own agent,
-  whose name akm cannot rely on, so the options go on the model and the title
-  call sees them too. `opencode-sdk` names its session, so it makes no title
-  call.
-- `opencode-sdk` declares the model of its `llmEngine` fallback with the
-  fallback's own inference, under the request's, field by field. Each distinct
-  set of inference starts its own `opencode serve`, as a different model does.
+Inference from an asset, a workflow's `llm:` or a `models.json` alias reaches an
+LLM engine. On an agent engine it is reported as an `untranslated-field`
+notice and dispatch continues; model work's agent carries `temperature`,
+`reasoningEffort` and `enableThinking` without one.
 
 Reasoning effort has one word in a request, `reasoningEffort`. `effort`, as a
-`models.json` alias or an asset's `effort:` frontmatter spells it, is the same
-setting and is read as `reasoningEffort` wherever layers are merged, so the
-nearest layer wins whichever word it used. On an LLM engine an alias's or
-asset's `effort` is therefore sent as `reasoning_effort`; before, it was
-reported as untranslated.
+`models.json` alias or an asset's `effort:` frontmatter spells it, is read as
+`reasoningEffort` wherever layers are merged, so an LLM engine sends it as
+`reasoning_effort`.
 
 ### Engines for unattended model work
 
@@ -248,7 +201,7 @@ cannot enforce:
 |---|---|
 | LLM | No tools. |
 | `claude` | Read and Edit inside the working directory, and Bash for `akm search` and `akm show` only. akm runs it with `--restricted`, so your user, project and local settings cannot widen that. |
-| `opencode`, `opencode-sdk` | Read and edit inside the working directory, through an injected `akm-model-work` agent. No bash, so no `akm search` or `akm show`, because opencode cannot stop a redirect such as `akm show x > file` from writing elsewhere. |
+| `opencode`, `opencode-sdk` | Read, grep and glob in the working directory and the stash, edit in the working directory only, and `akm_search` and `akm_show`, through an injected `akm-model-work` agent. No bash, because opencode cannot stop a redirect such as `akm show x > file` from writing elsewhere. |
 | `codex`, `copilot`, `pi`, `gemini`, `aider`, `amazonq`, `openhands` | Cannot run model work: akm refuses the request before it starts. |
 
 **The one rule.** Every key model work reads its engine from must name an
@@ -268,12 +221,17 @@ key, the engine and its platform. Other engine keys, `defaults.engine` and
 **Further details:**
 - A model-work dispatch builds its own command, so the engine's `args` do not
   apply to it, except a `--model` they name, and neither does its `workspace`.
-- The temporary directory must not be inside a git repository, because
-  opencode would treat the whole repository as its working directory. Point
-  `TMPDIR` elsewhere if it is.
-- `llm` overrides that reach an agent engine are translated when its platform
-  translates them (see [Inference on an agent engine](#inference-on-an-agent-engine))
-  and reported as `untranslated-field` notices, not errors, when it does not.
+- An improve process's `llm` overlay reaches the `akm-model-work` agent on
+  `opencode` and `opencode-sdk` (see
+  [Inference on an agent engine](#inference-on-an-agent-engine)); on any other
+  agent engine it is reported as `untranslated-field` notices, not errors.
+- opencode model work may read the stash and write only its working directory.
+  `akm_search` and `akm_show` come from the akm-opencode plugin (0.9.21 or
+  later), which akm does not load: put it in your opencode config
+  (`"plugin": ["akm-opencode"]`). akm turns off the plugin's curation, learning
+  and write gate for these dispatches and keeps its state in akm's state
+  directory. The stash is protected from edits only while the temporary
+  directory is outside a git repository.
 
 ### Model-map files
 
@@ -320,9 +278,7 @@ 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. An `inference.effort` is read as `reasoningEffort`
-(see [Inference on an agent engine](#inference-on-an-agent-engine)), so the
-starter's `reasoning` alias sets `--effort high` on `claude` and
-`options.reasoningEffort: "high"` on `opencode` and `opencode-sdk`.
+(see [Inference on an agent engine](#inference-on-an-agent-engine)).
 
 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
@@ -511,9 +467,7 @@ guidance. When enabled, engine selection is judgment → triage → strategy →
 
 `processes.reflect.qualityGate` and `processes.distill.qualityGate` control
 each process's LLM-as-judge quality gate. Each is on unless it sets
-`enabled: false`, and each follows only its own switch. A reflect revision
-that changes the body is never auto-accepted; when the judge passes it, it
-waits for review. With the gate off, it waits for review too. The judge is the
+`enabled: false`, and each follows only its own switch. The judge is the
 process's own engine when that is an LLM engine, or the `defaults.llmEngine`
 engine when an agent generates. `engine`, `model`, `timeoutMs` and `llm` give the gate a judge of its own,
 resolved over the process's settings the way `triage.judgment` resolves over
@@ -549,6 +503,46 @@ judge's engine at the server directly.
 }
 ```
 
+`processes.reflect.defectFilter` sets the wording of the checks reflect runs
+before the judge. With the quality gate on or off, reflect refuses a revision
+that adds placeholder text, talks about its own edit, or copies frontmatter into
+its body: no proposal, and no judge call. Each rule counts only what the
+revision adds to its source, so wording the asset already had and kept is not
+held against it. Each of the three lists is optional. A list you set replaces
+that rule's default list, and `[]` turns the rule off.
+
+| List | Rule | Default |
+|---|---|---|
+| `placeholders` | `placeholder_added` | `please confirm`, `please verify`, `to be confirmed`, `to be determined`, `to be verified` |
+| `metaCommentary` | `meta_commentary_added` | `feedback signal`, `feedback signals`, `feedback indicate`, `feedback indicates`, `feedback suggest`, `feedback suggests`, `feedback ask`, `feedback asks`, `feedback says`, `feedback report`, `feedback reports`, `feedback request`, `feedback requests`, `this revision`, `the source asset`, `the source note`, `the source memory`, `the original asset`, `the original note`, `the original memory`, `the original version of this`, `quality gate rejected`, `proposal rejected` |
+| `frontmatterKeys` | `frontmatter_copied_into_body` | `sources`, `updated`, `inferenceProcessed`, `captureMode`, `beliefState`, `xrefs`, `contradictedBy`, `outcomeData`, `orderedActions`, `generated`, `verified`, `description`, `when_to_use`, `tags`, `searchHints`, `quality`, `salience`, `salienceInputs`, `lint_skip`, `type` |
+
+`placeholders` and `metaCommentary` entries are plain phrases, not patterns:
+whole words, in any case, with any run of whitespace between words.
+`frontmatterKeys` entries are exact key names: a line outside a code fence that
+starts with `key:` counts. The rule also refuses a `sources`, `xrefs` or
+`contradictedBy` value copied into the body; `frontmatterKeys: []` turns that
+off too. Every entry must be a non-empty string, or the config does not load.
+
+```jsonc
+{
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "processes": {
+          "reflect": {
+            "defectFilter": {
+              "placeholders": ["please confirm", "to be confirmed", "[draft]"],
+              "frontmatterKeys": []
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 No shipped strategy turns improve-stage session extraction on.
 `proactiveMaintenance` is on only in the `proactive-maintenance` preset; run
 `akm improve --strategy proactive-maintenance` to use that opt-in preset.

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

@@ -245,9 +245,8 @@ engagement, feedback signals, stable refs, and timestamps. It never leaves the
 machine unless you explicitly copy the database or send derived content to a
 configured endpoint.
 
-Successful `search`, `curate`, and `show` commands record usage by default.
-Pass `--no-track-usage` to any of those commands to leave local usage events
-unchanged.
+Successful `search`, `curate`, and `show` commands always record usage. Machine
+reads are stamped by source (below), so they never skew ranking or eval.
 
 Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
 `unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,

package/docs/reference/workflow-schema.md

@@ -299,15 +299,12 @@ families) plus the orchestration keys:
 - `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 translates what its platform can carry
-  (`temperature`, `reasoning_effort`, `enable_thinking`, and `max_tokens` with
-  `context_length` on `opencode` and `opencode-sdk`; `reasoning_effort` on
-  `claude`; see
-  [Inference on an agent engine](configuration.md#inference-on-an-agent-engine))
-  and reports the rest as an `untranslated-field` notice on that step. 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:`.
+  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)).
+  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:`.
 - `outputs` — name → `{ from, schema? }`, a run-level export projected from
   a step's own artifact (Markdown-only; see [Workflow
   outputs](#workflow-outputs) below).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.25-alpha.1",
+  "version": "0.9.25-alpha.3",
   "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

@@ -146,24 +146,6 @@
                 "type": "string",
                 "maxLength": 63,
                 "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
-              },
-              "temperature": {
-                "type": "number"
-              },
-              "maxTokens": {
-                "type": "integer",
-                "exclusiveMinimum": 0
-              },
-              "contextLength": {
-                "type": "integer",
-                "exclusiveMinimum": 0
-              },
-              "enableThinking": {
-                "type": "boolean"
-              },
-              "reasoningEffort": {
-                "type": "string",
-                "minLength": 1
               }
             },
             "required": [
@@ -837,6 +819,33 @@
                           }
                         },
                         "additionalProperties": true
+                      },
+                      "defectFilter": {
+                        "type": "object",
+                        "properties": {
+                          "placeholders": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
+                          "metaCommentary": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
+                          "frontmatterKeys": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        },
+                        "additionalProperties": true
                       }
                     },
                     "additionalProperties": true
@@ -1816,24 +1825,6 @@
                     "type": "string",
                     "maxLength": 63,
                     "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
-                  },
-                  "temperature": {
-                    "type": "number"
-                  },
-                  "maxTokens": {
-                    "type": "integer",
-                    "exclusiveMinimum": 0
-                  },
-                  "contextLength": {
-                    "type": "integer",
-                    "exclusiveMinimum": 0
-                  },
-                  "enableThinking": {
-                    "type": "boolean"
-                  },
-                  "reasoningEffort": {
-                    "type": "string",
-                    "minLength": 1
                   }
                 },
                 "required": [
@@ -2507,6 +2498,33 @@
                               }
                             },
                             "additionalProperties": true
+                          },
+                          "defectFilter": {
+                            "type": "object",
+                            "properties": {
+                              "placeholders": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "metaCommentary": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "frontmatterKeys": {
+                                "type": "array",
+                                "items": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              }
+                            },
+                            "additionalProperties": true
                           }
                         },
                         "additionalProperties": true
@@ -3620,6 +3638,33 @@
           },
           "additionalProperties": true
         },
+        "defectFilter": {
+          "type": "object",
+          "properties": {
+            "placeholders": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "metaCommentary": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "frontmatterKeys": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": true
+        },
         "requirePlannedRefs": {
           "type": "boolean"
         },
@@ -4009,6 +4054,33 @@
                     }
                   },
                   "additionalProperties": true
+                },
+                "defectFilter": {
+                  "type": "object",
+                  "properties": {
+                    "placeholders": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "metaCommentary": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "frontmatterKeys": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "additionalProperties": true
                 }
               },
               "additionalProperties": true