akm-cli 0.10.261012-beta → 0.10.261014-beta

package/README.md

@@ -40,6 +40,21 @@ prefers Bun for execution; old, unusable, or absent Bun installations fall
 back to Node.js. Node.js remains required for the npm package. The standalone
 binaries are runtime-free.
 
+Local semantic search runs its embedding model on ONNX Runtime
+(`onnxruntime-node`). A standalone binary carries the library for its platform
+and copies it once into akm's cache (18 to 34 MB); a `noexec` temp directory
+blocks a standalone binary's semantic search (keyword search still works), so
+set `TMPDIR` to a writable, executable one.
+Alpine/musl and Intel macOS have no native ONNX Runtime, so semantic search is
+unavailable there and keyword search works. See
+[Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/#standalone-binary-and-semantic-search).
+
+With a connection and no harness, agent work runs on akm's own runtime, a pinned
+OpenCode 2 binary. The first time it runs, akm downloads that binary from the npm
+registry (about 114 MB, once) into its cache; on Alpine/musl it needs `libstdc++`
+and `libgcc` (the Alpine Node image has them). See
+[Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/#akms-own-agent-runtime).
+
 ## Quick Start
 
 ```sh

package/SECURITY.md

@@ -43,8 +43,8 @@ bugs, but you should be aware of them:
 Workflow steps run in your shell with your PATH and your environment
 variables — including any secrets you have exported or loaded via
 `akm env run` / `akm secret run`. **Only add workflow sources you trust.** See
-[`docs/reference/workflows.md` — "Security: workflow sources are executed
-code"](docs/reference/workflows.md#security-workflow-sources-are-executed-code)
+[`docs/guides/run-workflows.md` — "Security: workflow sources are executed
+code"](docs/guides/run-workflows.md#security-workflow-sources-are-executed-code)
 for the full discussion.
 
 ### Scripts execute shell commands
@@ -75,8 +75,8 @@ The built-in YouTube snapshot fetcher (`src/sources/snapshot-fetchers/youtube.ts
 and `<stash>/secrets/`. They are protected against other local users by
 filesystem permissions but are not encrypted at rest. Do not commit these
 files to source control. Normal `akm env` and `akm secret` output never echoes
-values; materialize values only at the command boundary with `akm env run`,
-`akm secret run`, or `akm secret path`.
+values; materialize values only at the command boundary with `akm env run`
+or `akm secret run`.
 
 The knowledge graph extracted from your assets (entities/relations) lives
 only in `$DATA/index.db` and is surfaced as aggregate counts via `akm health`
@@ -87,12 +87,13 @@ graph content to an arbitrary path.
 
 `akm improve` (whose strategies run processes such as reflect, distill, and
 consolidate) and `akm proposal new` can send asset frontmatter and body to the
-named LLM engine selected by the command, strategy, or current defaults. LLM
-connections live under
-`engines.<name>` in `~/.config/akm/config.json`. If you configure a third-party
-LLM, your asset content goes to that third party. Use a local engine endpoint
-(for example, `http://localhost:11434/v1/chat/completions` via Ollama) for assets
-containing secrets or private notes.
+connection (or harness) selected by the command, strategy, or current defaults.
+Connections live under `connections.<name>` in `~/.config/akm/config.json`,
+with their keys in the environment or in `~/.config/akm/credentials.json`. If you
+configure a third-party LLM, your asset content goes to that third party, and a
+harness you enable (Claude Code, Codex, ...) sends it wherever it is configured
+to. Use a local endpoint (for example, `http://localhost:11434/v1` via Ollama)
+for assets containing secrets or private notes.
 
 ## Known non-issues
 

package/STABILITY.md

@@ -33,6 +33,29 @@ spelling is in the CHANGELOG entry and the CLI reference.
 | `akm config path --all` | `akm info` |
 | `--run` / `--since` on `akm improve` | `akm improve report --run` / `--since` |
 
+**Connections and harnesses (0.10, #1244).** `engines` and `defaults` are
+replaced by `connections` and `harnesses`. A config in the old form still loads
+(converted in memory, with a warning that names `akm migrate apply`), and `akm
+migrate apply` converts it.
+
+`--engine <name>` (on `agent`, `command run`, `task add`, `proposal new` and
+`proposal extract`) and `--require-engines` (on `improve`) are hidden from
+`--help` and still run, with one warning, through 0.10. `--require-engines`
+does nothing. Change a script to `--connection <name>` or `--harness <name>`,
+and `--model <alias|name>`; how an old engine name resolves is under
+[The `engines` form](docs/reference/configuration.md#the-engines-form).
+
+`AKM_ENGINE_<NAME>_API_KEY`, `AKM_LLM_API_KEY` and `AKM_EMBED_API_KEY` are no
+longer read implicitly: put `"apiKey": "$VAR"` on the connection, or the key in
+`credentials.json`.
+
+These are unknown flags or commands (exit 2) from 0.10, with no alias:
+
+| Gone | Use |
+| --- | --- |
+| `akm setup --config <json>` and `--probe` | `akm setup --endpoint <url> --yes` and the other answer flags; `--no-probe` for an offline run (probing is the default) |
+| `akm models list`, `akm models copy-defaults` | `akm models`, `akm models set <alias> <model>` |
+
 **Version numbers (0.10 onward, #1089).** A 0.10 release is numbered
 `0.10.YYMMNN`: `YY` the UTC year, `MM` the month (`01` to `12`) and `NN` the
 release within that month (`01` to `99`), each two digits. Every release takes
@@ -84,7 +107,7 @@ enumeration of the whole `proposal` noun group.
 
 | Command | Tier | Notes |
 | --- | --- | --- |
-| `akm setup` | Stable | |
+| `akm setup` | Stable | The answer flags (`--endpoint`, `--api-key-env`, `--name`, `--harness`, `--embedding`, ...) are new in 0.10; `--config` and `--probe` are gone (see the table above). |
 | `akm index` | Stable | |
 | `akm health` | Evolving | Exit codes are Evolving; report *content* and rendered `md`/`html` layout are Experimental — do not script against report layout. |
 | `akm metrics` | Experimental | New in 0.9.28. Report content, JSON shape and the `html` dashboard may change. |
@@ -100,9 +123,9 @@ enumeration of the whole `proposal` noun group.
 | `akm search` | Stable | |
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
-| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942), additive. |
+| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942); a deprecated no-op since 0.10 (#1239), accepted through 0.10. |
 | `akm workflow plan` | Experimental | New in 0.9.2; secret-free provenance output; envelope shape may change. |
-| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
+| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942); since 0.10 (#1239) `--all-scopes` is a deprecated no-op, accepted through 0.10, and the `scopeKey` field is removed from the list result. |
 | `akm workflow create` | Experimental | |
 | `akm workflow resume` | Experimental | |
 | `akm workflow abandon` | Experimental | |
@@ -126,7 +149,7 @@ enumeration of the whole `proposal` noun group.
 | `akm log` | Evolving | |
 | `akm agent` | Evolving | |
 | `akm command run` | Evolving | Runs stored command templates through the same agent dispatch as `akm agent`. |
-| `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
+| `akm models` | Evolving | The alias picks of a connection, then the models its endpoint lists, and `set` to change one. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
 | `akm improve report` | Evolving | Subcommand since 0.10 (was a magic `scope` value); owns `--run` and `--since`. |
@@ -314,7 +337,7 @@ CHANGELOG with a migration note.
   `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
   `inputs:`, optional `schedule:`) is the only accepted version — task v3 and
   task v2 sources are converted by `akm migrate apply`. Command tasks use
-  named engines and task history metadata is versioned. Schema additions in
+  a named connection or harness, and task history metadata is versioned. Schema additions in
   patch releases; removals only at minor. Bare `akm task` is a usage error
   naming the subcommands (`akm task doctor` reports scheduler diagnostics).
   `akm task explain <ref>` (new in 0.9.2) and `akm workflow plan <ref>` are
@@ -355,20 +378,17 @@ CHANGELOG with a migration note.
   `log.md` / `raw/` / `pages/` and its ingest flow); wiki pages are addressed
   as ordinary concepts inside their bundle. Adapter behavior and page
   conventions are still iterating.
-- **Agent dispatch** — `akm agent` and `akm command run`. Supported backends:
-  `claude`, `opencode-sdk` (the primary OpenCode interface), `codex`, and the
-  `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`, `amazonq`,
-  `openhands`. Every harness is Evolving: the harness implementation is being
-  reworked so harnesses are easy to add, remove and update (0.10). The set will
-  grow.
-  **Deprecated:** the `opencode` CLI dispatch path (an agent engine with
-  `platform: "opencode"`, which runs `opencode run` per call). It still works on
-  OpenCode 1 and 2 throughout 0.10; use an `opencode-sdk` engine instead, which
-  covers it, including a default agent (#1098). It may be removed in 0.11 or
-  later. The rest of the OpenCode integration (session-log import, config
-  import) is not deprecated.
-- **Model aliases** — `akm models list|copy-defaults` and the intent-alias
-  defaults they expose.
+- **Agent dispatch** — `akm agent` and `akm command run`. Supported
+  harnesses: `claude`, `codex`, `opencode` (through `opencode run`, for OpenCode 2
+  and for the legacy OpenCode 1, which keeps working with no removal date),
+  `copilot`, `pi`, `gemini`, `aider`, `amazonq` and `openhands`. Every harness is Evolving: a harness is a thin shell that turns a
+  request into a command, and the set is easy to add to, remove from and update.
+  The set will grow. A harness runs with your environment as it is
+  ([Configuration](docs/reference/configuration.md#how-akm-runs-a-harness)). With
+  no harness configured, agent work runs on akm's own runtime over a connection,
+  which is Evolving too.
+- **Model aliases** — `akm models` and `akm models set`, and the intent-alias
+  picks a connection holds.
 - **Proposal queue** — quality classifications (`accepted`, `pending`,
   `proposed`, `rejected`, `archived`) are stable; the JSON shape of a
   proposal record may add fields.
@@ -402,14 +422,13 @@ for scripted use.
   least settled part and are kept only in that simple form; `akm workflow list
   --children` goes with them.
 
-  Per-key status today, from the Outcome section of
-  `docs/plans/0.10-workflows.md`. It stands until the promote-or-remove
+  Per-key status today. It stands until the promote-or-remove
   decision in [#1096](https://github.com/itlackey/akm/issues/1096); every key
   is still Experimental until then.
 
   | Key | Status |
   | --- | --- |
-  | `params`, `steps`, `inputs`, `output` / `unit.output`, `defaults.engine`, `### gate` | Core: the feature set pinned by `core-feature-set.test.ts` |
+  | `params`, `steps`, `inputs`, `output` / `unit.output`, `defaults.connection` / `defaults.harness`, `### gate` | Core: the feature set pinned by `core-feature-set.test.ts` |
   | exec units (`unit.exec`), `budget`, `unit.retry`, `map`, `gate.max_loops` | Kept in the 0.10 trim |
   | child workflows (`unit.workflow`, `unit.with`) | Experimental: least settled |
 - **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
@@ -443,9 +462,9 @@ for scripted use.
   than `default` and `consolidate` and the proactive-maintenance lane. 0.10 measures each and keeps, folds or removes it
   (#1094). `quick`, `reflect-distill`, `thorough` and `catchup` were removed
   in 0.10 (#1130), as were `proactive-maintenance` and the high-salience lane (#1129); a user-defined strategy of the same name keeps working.
-- **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
-  engines, limits, gates, and the CLS knobs) and
-  the `index.*` per-pass config. The 0.9.x series is explicitly still settling
+- **Improve tuning config** — `improve.strategies.*.processes.*` (limits,
+  gates, and the CLS knobs), `improve.processes.*` and `improve.qualityGate`
+  (where each process runs) and the `index.*` per-pass config. The 0.9.x series is explicitly still settling
   the design of the improve processes, so **keys in these two families may be
   added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
   improve` *command* surface is Evolving (above); its tuning config is not.
@@ -487,15 +506,15 @@ the pair pass stages a retirement when its claim checks pass and there is no
 continuity risk. `triage` with `applyMode: "promote"` can accept that staged
 retirement unattended; an unstaged retirement stays pending. Both retirement
 checks receive complete note bodies with lexical attention hints, so the selected
-engine must accommodate them. The pair judge supplies distinct-claim lists; AKM
+model must accommodate them. The pair judge supplies distinct-claim lists; AKM
 derives duplicate/subsumed/overlap outcomes and retirement direction from those
 lists. Historical queued retirement labels remain readable. Before unattended drain after an upgrade, review pending/staged
 retirements produced by older builds from notes over 12,000 body characters:
 upgrading does not revalidate their evidence (#1195).
 
 Because the gate is applied before the LLM preflight, a review-first workspace
-also needs fewer engines configured: a strategy whose only model-backed process
-is a gated lane resolves without an engine at all.
+also needs fewer connections or harnesses configured: a strategy whose only
+model-backed process is a gated lane resolves without one at all.
 
 **Three direct writes are deliberately NOT gated**, because they are additive or
 already independently controlled:
@@ -539,8 +558,6 @@ on them.
 | Variable | Purpose |
 | --- | --- |
 | `AKM_BUNDLE_DIR`, `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` | Filesystem layout overrides |
-| `AKM_LLM_API_KEY`, `AKM_EMBED_API_KEY`, `AKM_ENGINE_<NAME>_API_KEY` | Credential provision for `$VAR` config references |
-| `AKM_LLM_ENDPOINT`, `AKM_LLM_BASE_URL` | Setup provider inference |
 | `AKM_VERBOSE`, `AKM_DEBUG` | Diagnostics |
 | `AKM_REGISTRY_URL` | akm registry mirror override |
 | `AKM_NPM_REGISTRY` | npm mirror override — redirects BOTH the trusted-tarball host allowlist and package metadata lookups (`npm view`-equivalent resolution) to the given registry base, replacing `registry.npmjs.org` wholesale rather than merging with it |
@@ -572,22 +589,6 @@ These changes are planned and will land in a known future release. They
 are not part of the current stability contract; you should plan migrations
 around them.
 
-**The 0.9.0 decision record is fully shipped.** The
-[decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md) settles a set of
-breaking changes; every one of them is now in the code, and each decision
-carries its own shipped status.
-
-Shipped from that record: **D1** (`#fragment` section selection),
-**D2** (the `akm show <ref> toc|section|lines|frontmatter|full` view grammar is
-gone — `#fragment` is the only section selector), **D4** (conceptId /
-`bundle//` prefix browse), **D5** (`akm bundle` removed), **D6** (open `type`
-set at runtime), **D7** (all six `--format` values everywhere), **D8** (the
-`experimental.improveAutonomy` gate), **D9** (`--auto-accept` removed, a hard error since 0.10),
-and partially **D10** (an `akm-migrate` binary now exists, though the code still
-lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
-0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
-Internal replacement for the one capability nothing else covered.
-
 - **0.10 — `config set`/`config unset` may drop the config dump** in favor of
   a compact `{ok, shape, key}` result; `akm config list` remains the full read.
 - **0.10 — migration extraction.** The migration machinery lives in its own
@@ -595,9 +596,6 @@ Internal replacement for the one capability nothing else covered.
   `akm` (no separate npm package). The task-source migrator (`task-to-v4.ts`,
   `task-source-v3-frozen.ts`) lives with it under `scripts/akm-migrate/migrate/`,
   out of `src/`.
-- **0.11 or later — the `opencode` CLI dispatch path may be removed.**
-  Deprecated in 0.10 (see Agent dispatch under Evolving); `opencode-sdk`
-  engines replace it.
 - **0.10 — `BundleAdapter.placeNew()` is removed.** Nothing called it; writes use AKM's fixed type→directory table.
   Writable bundles in a non-akm layout would need per-adapter placement back
   ([#1163](https://github.com/itlackey/akm/issues/1163)).
@@ -624,7 +622,5 @@ worth fixing.
   (independent of the feature-stability policy above).
 - [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the
   normative ref grammar.
-- [`docs/architecture/specs/0.9.0-decisions.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md)
-  — the decision record behind the 0.9.0 surface changes.
 - [`docs/reference/data-and-telemetry.md`](./docs/reference/data-and-telemetry.md) — what
   state akm reads and writes locally.

package/dist/assets/hints/cli-hints-full.md

@@ -68,7 +68,7 @@ akm show knowledge/my-doc                     # Show materialized local content
 | script | `run`, `setup`, `cwd` |
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description`, `parameters` |
-| agent | `prompt`, `description`, `modelHint`, `toolPolicy` |
+| agent | `prompt`, `description`, `modelHint` |
 | knowledge | `content` (whole document, or one section via `#fragment`) |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
@@ -92,7 +92,7 @@ akm import https://example.com/docs/auth       # Fetch one URL and import it as
 akm import ./doc.md --bundle my-other-bundle    # Route import to a named writable bundle source
 akm workflow create ship-release               # Create a workflow asset in the bundle
 akm lint --type workflows                      # Parse and compile every workflow source; list every error
-akm workflow run workflows/ship-release        # Start or resume and execute the workflow
+akm workflow run workflows/ship-release        # Start a new run and execute it
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
 akm feedback agents/reviewer --negative --reason "says to run jest; the suite runs on vitest" # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
 akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Apply an exact fix
@@ -150,8 +150,8 @@ the index (comments can contain commented-out credentials). akm does not edit
 entries — you edit the file with your own editor and akm loads it.
 
 ```sh
-akm env create prod                           # Create an empty env file
-akm env create prod --from-file ./.env        # Ingest an existing .env
+akm env create env/prod                           # Create an empty env file
+akm env create env/prod --from-file ./.env        # Ingest an existing .env
 akm env list                                  # List all env files across bundles with key names
 akm show env/prod                             # Inspect key names (never values or comments)
 akm env run env/prod -- ./deploy.sh           # Run a command with the whole .env injected (the safe path)
@@ -186,10 +186,10 @@ workflow. Direct run-id commands still target the exact run.
 akm workflow create ship-release --print     # Print a starter workflow template, without writing
 akm workflow create ship-release             # Scaffold a new workflow asset
 akm workflow run workflows/ship-release --version=1.2.3  # Start and execute with exact-name parameter flags
-akm workflow run <run-id> --max-retries 2 --timeout 10m  # Resume with invocation-wide controls
+akm workflow run <run-id> --max-retries 2 --timeout 10m  # Continue a run with invocation-wide controls
 akm workflow status <run-id>                 # Show the exact run by id
-akm workflow resume <run-id>                 # Resume a blocked or failed run
-akm workflow list                            # List workflow runs in the current scope
+akm workflow resume <run-id>                 # Re-activate a blocked or failed run, then `run <run-id>`
+akm workflow list                            # List workflow runs on this host
 ```
 
 ## Clone
@@ -282,7 +282,6 @@ akm bundle list --kind git                           # Filter by provider (files
 akm bundle remove <target>                           # Remove by id, ref, path, or name
 akm bundle update --all                              # Update all managed sources
 akm bundle update <target> --force                   # Force re-download
-akm bundle update <target> --allow-dangerous-env-keys # Approve reviewed dangerous env keys
 akm bundle update --all --skip-if-locked             # Scheduled refresh; exit 0 on DB contention
 ```
 
@@ -298,7 +297,6 @@ akm registry add <url> --name my-team         # Add with label
 akm registry add <url> --provider skills-sh   # Specify provider type
 akm registry remove <url-or-name>             # Remove a registry
 akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
-akm search "<query>" --from registry --assets # Include asset-level results
 ```
 
 ## Configuration
@@ -308,15 +306,18 @@ akm config list                               # Show current config
 akm config get <key>                          # Read a value
 akm config set <key> <value>                  # Set a value
 akm config unset <key>                        # Remove a key
+akm models                                    # Which model answers each alias, then what the endpoint lists
+akm models set <alias> <model>                # Change one (--connection <name> for another connection)
 ```
 
 ## Other Commands
 
 ```sh
 akm bundle create                                      # Initialize working bundle (scaffold only)
-akm setup                                     # Interactive wizard: bundle + LLM/embedding + agent + registry config
+akm setup                                     # Interactive wizard: agent programs, model connection, embeddings, bundle + registry config
 akm setup --dir ~/custom-bundle                # Run the wizard against a custom bundle path
 akm setup --yes                               # Non-interactive, accepts all defaults
+akm setup --endpoint <url> --yes              # Non-interactive, adds a model connection (an OpenAI-compatible endpoint)
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
 akm bundle list                                      # List all sources
@@ -334,8 +335,8 @@ akm completions --install                     # Install completions
 ```
 
 `akm bundle create` only scaffolds the bundle directory and registers it in config;
-`akm setup` additionally walks through embedding/LLM connections, agent
-profiles, sources, and registries. Use `setup` for first-time onboarding,
+`akm setup` additionally walks through agent programs, a model connection,
+embeddings, sources, and registries. Use `setup` for first-time onboarding,
 `bundle create` when you just need a bare bundle.
 
 ## Proposals & Improvement (0.8.0+)
@@ -379,7 +380,7 @@ akm search --type task                         # Enumerate task assets
 ```
 
 Task files use task source v4 (`version: 4`). There is no `akm:` options bag
-or `on:` block — every control (`schedule`, `timeout`, `engine`, `model`,
+or `on:` block — every control (`schedule`, `timeout`, `connection`, `harness`, `model`,
 `redact`, `maxSteps`, `maxRetries`, …) is a top-level key now. Typed
 `inputs:` declarations and a bounded `output:` schema work like a
 workflow's (`output:` replaces v3's `akm.outputSchema`). Task source never
@@ -387,23 +388,24 @@ controls activation: use `akm task enable` / `disable`, which update the
 host-local config allow-list and sync. To remove one, delete the YAML and run
 `akm task sync` — the scheduler entry is unbound. Top-level
 `timeout:` may be `null` (disable the invocation timer) or a duration/number
-overriding the selected engine invocation timeout. Preview old task-v2/v3
+overriding the selected connection's or harness's timeout. Preview old task-v2/v3
 conversion with `akm migrate apply --dry-run`.
 
 ## Agent Dispatch
 
 ```sh
-akm agent --prompt "summarize open proposals"   # Dispatch the configured agent CLI
-akm agent agents/architect --prompt "..."       # Embody a bundle agent asset (system prompt, model, tool policy)
+akm agent --prompt "summarize open proposals"   # Run an agent on your default harness (else akm's own runtime over your connection)
+akm agent agents/architect --prompt "..."       # Embody a bundle agent asset (system prompt, model)
 akm command run commands/release                # Canonical reusable-command dispatch
-akm agent --model sonnet --prompt "..."         # Model override (aliases or exact IDs)
+akm agent --model reasoning --prompt "..."      # Model override (alias fast|balanced|reasoning, or an exact name)
+akm agent --harness claude --prompt "..."       # Run on a named harness (or --connection <name>)
 ```
 
 ## Health, Info, and the Event Log
 
 ```sh
-akm info                                       # Capabilities, bundle dir, index stats, semantic-search status
-akm health                                     # Runtime diagnostics; exit 0 ok / 4 warn / 1 fail
+akm info                                       # Capabilities, bundle dir, index stats, semantic-search status, connections and harnesses
+akm health                                     # Runtime diagnostics, connections and harnesses; exit 0 ok / 4 warn / 1 fail
 akm health --report                            # Adds accept-rate metrics
 akm metrics                                    # Usage, feedback, utility, LLM tokens, tasks, workflows (last 30d, read-only)
 akm metrics --since 7d                         # Narrow the window

package/dist/assets/hints/cli-hints-short.md

@@ -15,9 +15,8 @@ For workflow tasks:
 2. `akm workflow run workflows/<name> --param_name=value` — execute every step and verification gate
 3. `akm workflow status <run-id> --units` — inspect a stopped or failed run
 
-Workflow runs are scoped to your current project/worktree/directory. Ref-based
-commands like `workflow run workflows/<name>`, `workflow status workflows/<name>`,
-and `workflow list` operate within the current scope only.
+A workflow ref (`workflows/<name>`) starts a new run; a run id drives that exact
+run. `workflow list` and `workflow status` see every run on this host.
 
 ## Quick Reference
 
@@ -29,7 +28,7 @@ akm search "memories/projectA/"               # List a subtree (conceptId prefix
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
 akm help <command>                            # Show a command's options and subcommands
-akm workflow run <ref>                        # Start or resume and execute a workflow
+akm workflow run <ref>                        # Start a new run and execute it
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
 akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)

package/dist/assets/opencode/akm-plugin.js

@@ -0,0 +1,177 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// The OpenCode 2 plugin of akm's own agent runtime. akm writes this file to the runtime's config directory and names
+// it in the inline config's `plugins` list (src/integrations/harnesses/opencode/runtime/). It runs inside OpenCode, so
+// it imports no package: only Node's own child_process, to call back into akm.
+//
+//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`. akm
+//     passes the argv that runs it in `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the
+//     runtime and the script for one run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on
+//     any platform. The run's environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as
+//     that run's.
+//   - The environment of the commands the agent runs: the variables akm set for the OpenCode process (its roots and
+//     its OpenCode settings) are put back to what akm runs in, or removed, so the agent's shell sees the environment a
+//     harness's child would.
+//   - The connection's request fields, laid over each model request in the endpoint's own field names, as the chat
+//     transport sends them. OpenCode sizes every request's output cap from the model's limit and sends it as
+//     `max_tokens` or `max_completion_tokens`; that is its own accounting, not a cap anyone asked for, so it is
+//     dropped, and the connection's fields carry a cap only when the connection writes one.
+
+import { execFile } from "node:child_process";
+
+const OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
+
+const TOOLS = [
+  {
+    name: "akm_curate",
+    command: "curate",
+    positional: "query",
+    description:
+      "Find the akm assets (skills, knowledge, memories, workflows) that best fit a task. Read one with akm_show before relying on it.",
+    input: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The task or question" },
+        type: { type: "string", description: "Optional asset type filter" },
+        limit: { type: "integer", minimum: 1 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "akm_search",
+    command: "search",
+    positional: "query",
+    description: "Search akm assets by name or keyword.",
+    input: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        type: { type: "string", description: "Optional asset type filter" },
+        limit: { type: "integer", minimum: 1 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "akm_show",
+    command: "show",
+    positional: "ref",
+    description: "Read one akm asset by its ref, as returned by akm_curate or akm_search.",
+    input: { type: "object", properties: { ref: { type: "string" } }, required: ["ref"] },
+  },
+];
+
+const text = (value) => (typeof value === "string" && value.trim() !== "" ? value.trim() : undefined);
+
+/** The arguments of one tool call for the akm CLI; throws when the required one is missing. */
+function cliArguments(tool, input) {
+  const value = text(input?.[tool.positional]);
+  if (!value) throw new Error(`"${tool.positional}" is required`);
+  const type = text(input?.type);
+  const limit = Number.isInteger(input?.limit) && input.limit > 0 ? String(input.limit) : undefined;
+  return [
+    tool.command,
+    value,
+    ...(type && tool.positional !== "ref" ? ["--type", type] : []),
+    ...(limit && tool.positional !== "ref" ? ["--limit", limit] : []),
+    "--detail",
+    "agent",
+    "--format",
+    "json",
+  ];
+}
+
+/** The argv in `AKM_OPENCODE_CLI`; throws unless it is a JSON array of strings with at least the executable. */
+function akmArgv() {
+  const raw = process.env.AKM_OPENCODE_CLI;
+  if (!raw) throw new Error("AKM_OPENCODE_CLI is not set");
+  const argv = JSON.parse(raw);
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string")) {
+    throw new Error("AKM_OPENCODE_CLI is not a JSON array of strings");
+  }
+  return argv;
+}
+
+function runAkm([executable, ...prefix], args) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      executable,
+      [...prefix, ...args],
+      { encoding: "utf8", maxBuffer: OUTPUT_LIMIT_BYTES, env: process.env },
+      (error, stdout, stderr) => {
+        if (error) reject(new Error((stderr || error.message).trim()));
+        else resolve(stdout);
+      },
+    );
+  });
+}
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** `over` laid over `base`; an object on both sides is merged one level deep, anything else of `over` wins. */
+function withFields(base, over) {
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    merged[key] = isObject(merged[key]) && isObject(value) ? { ...merged[key], ...value } : value;
+  }
+  return merged;
+}
+
+export default {
+  id: "akm",
+  setup: async (ctx) => {
+    await ctx.tool.transform((editor) => {
+      for (const tool of TOOLS) {
+        editor.add({
+          name: tool.name,
+          description: tool.description,
+          input: tool.input,
+          options: { codemode: false },
+          execute: async (input) => {
+            try {
+              const args = cliArguments(tool, input);
+              return { content: await runAkm(akmArgv(), args) };
+            } catch (error) {
+              return { content: `${tool.name} failed: ${error instanceof Error ? error.message : String(error)}` };
+            }
+          },
+        });
+      }
+    });
+
+    const shellEnv = ctx.options?.shellEnv;
+    if (isObject(shellEnv)) {
+      await ctx.shell.hook("create.before", async (event) => {
+        for (const [name, value] of Object.entries(shellEnv)) {
+          if (typeof value === "string") event.env[name] = value;
+          else delete event.env[name];
+        }
+      });
+    }
+
+    const fields = ctx.options?.requestFields;
+    await ctx.session.hook("http.request", async (event) => {
+      const request = event.request;
+      if (request.body === null) return;
+      let body;
+      try {
+        body = JSON.parse(await request.clone().text());
+      } catch {
+        return;
+      }
+      if (!isObject(body)) return;
+      const { max_tokens: _own, max_completion_tokens: _ownCompletion, ...kept } = body;
+      const headers = new Headers(request.headers);
+      headers.delete("content-length");
+      event.request = new Request(request.url, {
+        method: request.method,
+        headers,
+        body: JSON.stringify(isObject(fields) ? withFields(kept, fields) : kept),
+        signal: request.signal,
+      });
+    });
+  },
+};

package/dist/assets/stash-skeleton/README.md

@@ -13,7 +13,7 @@ consistency and reducing repeated context-setting.
 | `knowledge/` | Knowledge | Reference documents, guides, architecture notes |
 | `memories/` | Memories | Persistent facts and preferences learned over time |
 | `commands/` | Commands | Parameterised prompt templates for common workflows |
-| `agents/` | Agents | Agent definitions with system prompts and tool policies |
+| `agents/` | Agents | Agent definitions with system prompts |
 | `workflows/` | Workflows | Multi-step orchestration sequences |
 | `tasks/` | Tasks | Scheduled or on-demand automation tasks |
 | `lessons/` | Lessons | Durable lessons extracted from past sessions |

package/dist/assets/tasks/core/improve.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --require-engines
+run: akm improve
 description: Run improve pipeline nightly
 schedule: "0 2 * * *"

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --strategy consolidate --timeout-ms 3600000 --skip-if-locked --require-engines
+run: akm improve --strategy consolidate --timeout-ms 3600000 --skip-if-locked
 description: Consolidation-only pass (every 4h at :20)
 schedule: "20 */4 * * *"