akm-cli 0.10.261012-beta → 0.10.261014-beta

package/docs/guides/improve-the-library.md

@@ -86,6 +86,11 @@ feedback signals and usage patterns, then generates proposals — it never
 writes directly to your bundle. By default, generated proposals always queue
 for review; the underlying autonomy gate and strategy configuration are
 covered in [Architecture: The Improvement Loop](../architecture/improvement.md).
+Its model calls run on your default connection, else your default harness
+(`--connection`, `--harness` and `--model` choose another for a run; see
+[Configuration](../reference/configuration.md#where-each-process-runs)). With
+neither, `akm improve` skips each process that needs a model, says so, and points
+at `akm setup`.
 
 ```sh
 akm improve                           # Full bundle pass
@@ -194,10 +199,11 @@ akm proposal accept abc12345           # write it to the bundle
 
 ## akm proposal new
 
-`akm proposal new` asks an engine to author a brand-new asset — useful
+`akm proposal new` asks an agent to author a brand-new asset — useful
 when you want to create something from scratch rather than improving an
-existing asset. Any engine kind works (an LLM engine, an agent CLI or
-`opencode-sdk`): the engine returns the asset as JSON, which akm validates.
+existing asset. It runs on your default harness, or on akm's own runtime over
+your connection when you have no harness (`--harness` and `--connection` choose
+another): the agent returns the asset as JSON, which akm validates.
 Output always goes to the proposal queue, never directly to the bundle.
 
 ```sh
@@ -240,7 +246,7 @@ autonomy gate that governs the few lanes that can act without one.
 ## See also
 
 - [Discover & Load](discover-and-load.md) — finding and loading assets
-- [Knowledge Management](knowledge-management.md) — capturing memories and docs
+- [Capture Knowledge](capture-knowledge.md) — capturing memories and docs
 - [Agent Integration](use-with-any-agent.md) — wiring feedback into agent workflows
 - [CLI Reference](../reference/cli.md) — full flag documentation for `feedback`, `log`, `improve`, `proposal`
 - [Architecture: The Improvement Loop](../architecture/improvement.md) — utility scoring, strategies, autonomy gates, auto-sync, and session extraction

package/docs/guides/recipes/headless-install.md

@@ -43,28 +43,23 @@ echo "akm setup complete"
 Node.js >= 22; a working Bun >= 1.0 is optional and preferred for execution
 after Node starts the package launcher.
 
-**Setup.** `akm setup --yes` accepts every default with no prompts. To
-pre-configure an LLM or agent engine at the same time instead of accepting
-defaults, pass `--config` with a JSON object, optionally followed by
-`--probe` to verify connectivity:
+**Setup.** `akm setup --yes` takes the detected default for every question:
+each agent program found on `PATH` is enabled and the first is the default. When
+akm can limit that program to reading and searching it takes akm's own model
+calls too; otherwise a local model server setup finds becomes the connection. To give akm an endpoint
+yourself, answer the question with a flag; the key is named by the environment variable that holds
+it and never appears on the command line:
 
 ```sh
-akm setup --config '{
-  "engines": {
-    "default": {
-      "kind": "llm",
-      "endpoint": "http://localhost:11434/v1/chat/completions",
-      "model": "llama3.2"
-    }
-  },
-  "defaults": { "llmEngine": "default" }
-}' --probe
+akm setup --yes --endpoint https://api.example.com/v1 --api-key-env EXAMPLE_API_KEY
 ```
 
-For the full set of accepted top-level `--config` keys and their meaning,
+`--no-probe` keeps the run offline (the endpoint's model list is not fetched), so a
+new connection has no model until `akm models set` names one.
+For the full set of flags, see `akm setup --help`; for the config they write,
 see [configuration.md](../../reference/configuration.md).
 
-**Semantic search.** Headless setups (`--yes` or `--config`, no wizard
+**Semantic search.** Headless setups (`--yes` or `--from`, no wizard
 prompts) defer the embedding-model download to the first `akm index` run,
 unlike the interactive wizard which downloads immediately during `akm
 setup`. Set the mode explicitly rather than relying on the implicit default:

package/docs/guides/run-workflows.md

@@ -12,15 +12,23 @@ see [Scheduling](scheduling.md).
 
 ## Start or continue a run
 
-`akm workflow run <run-id|workflows/ref>` starts or continues a persisted run
-and executes it until completion, failure, verification rejection,
-interruption, or an explicit invocation limit. Run state is scoped to the
-current project directory (nearest `.akm/config.json`, git root, bundle root,
-or current directory), so the same workflow can run independently in separate
-projects.
+`akm workflow run <workflows/ref>` always starts a new persisted run, and
+`akm workflow run <run-id>` continues that exact run. Either way it executes
+until completion, failure, verification rejection, interruption, or an
+explicit invocation limit. A run is identified by its run id and a workflow by
+its ref; the directory you run from never matters, so `akm workflow list` and
+`akm workflow status` show the same runs from anywhere.
+
+If other runs of the same ref are still active, a start says so in one
+warning that names their ids and the `akm workflow run <id>` /
+`akm workflow abandon <id>` commands. Starting is never refused.
+`akm workflow resume <id>` is only for a blocked or failed run: it re-activates
+the run so `akm workflow run <id>` can continue it.
+`--new` is a deprecated no-op (a ref always starts a new run), kept through
+0.10 so existing scripts keep working.
 
 Every new run/start compiles source IR v1 and freezes the durable plan v4
-family's current executable format (`irVersion: 5`) before publishing the run.
+family's current executable format (`irVersion: 8`) before publishing the run.
 A workflow ref is a Markdown `.md` source.
 
 ```sh
@@ -29,6 +37,9 @@ akm workflow run workflows/review --changed_files a.ts --changed_files b.ts
 akm workflow run <run-id> --max-retries 2 --timeout 10m
 ```
 
+Parameters are accepted on every ref start. They cannot be combined with a run
+id, which already has its parameters.
+
 Parameter flags must come after the target and exactly match declared
 `params` keys. Values are coerced through each parameter's JSON Schema:
 repeat an array flag, pass an object or whole array as JSON, and use a bare
@@ -58,7 +69,7 @@ and evidence — for a given run ID or workflow ref.
 ```sh
 akm workflow status <run-id>
 akm workflow status workflows/ship-release
-# When given a ref, resolves to the most-recently-updated run in the current scope
+# When given a ref, shows the most recently updated run of that ref
 ```
 
 Use this to inspect where a run is after a context window break, or to verify
@@ -151,12 +162,13 @@ A child run id always works directly, listed or not — `akm workflow status
 <childRunId>`, `resume`, `abandon`, and `run` all operate on it exactly like
 any other run.
 
-## List runs in scope
+## List runs
 
-`akm workflow list` shows workflow runs in the current scope.
+`akm workflow list` shows every workflow run on this host, most recently
+updated first. `--all-scopes` is a deprecated no-op, kept through 0.10.
 
 ```sh
-akm workflow list              # All runs in this scope (any status)
+akm workflow list              # All runs (any status)
 akm workflow list --active     # Only status=active (executable) runs
 akm workflow list --ref workflows/ship-release  # Runs for a specific workflow
 ```
@@ -190,7 +202,7 @@ completed are skipped, not re-run (see
 A resume consumes the frozen plan and journaled attempts; it does not re-read
 configuration or the index, and reads the authored workflow only to warn once
 when it changed since the run was frozen (the run continues on the frozen
-plan; `akm workflow run <ref> --new` picks up the edit). A stored plan this akm
+plan; `akm workflow run <ref>` starts a new run that picks up the edit). A stored plan this akm
 cannot decode is abandoned with a message naming how to start a new run.
 
 ## Abandon a run
@@ -225,11 +237,10 @@ Workflow steps that include shell commands run with **the full filesystem and
 network access of the user invoking `akm workflow run`** — same as if the user
 had typed those commands in their shell. There is no sandbox and no separation
 between trusted and untrusted workflows. An `exec` unit's *environment* is
-narrowed to an allowlist by default
-([Workflow Schema](../reference/workflow-schema.md#the-childs-environment-is-an-allowlist)),
-which bounds accidental exposure of unrelated credentials — but a command that
-runs at all can still read those credentials off disk, so it is a hygiene
-boundary, not a containment one. AKM
+yours
+([Workflow Schema](../reference/workflow-schema.md#the-childs-environment)):
+every variable of the process that ran `akm workflow run` reaches the command,
+credentials included. AKM
 directly orchestrates workflows as a defined execution surface — it does not
 blindly execute arbitrary indexed content — but that orchestration still runs
 the workflow's own declared shell commands with your full access once you
@@ -248,9 +259,7 @@ treat package dependencies**:
   workflow file first (`akm show workflows/<name>`) before running it.
 - **Audit before run** for any workflow that touches secrets, deploys to
   production, or writes outside the project tree. Read the `env:` bindings a
-  workflow declares, and read its `exec.pass_env` lines.
-  The durable v4 family (`irVersion: 5`) rejects `inherit_env`. Authors must
-  use exact named bindings and `pass_env` names.
+  workflow declares.
 - **Pin known-good versions** when adding workflow sources from a registry
   or git remote (`akm bundle add github:owner/repo#v1.2.3`), and update
   deliberately rather than via `akm bundle update --all`. A trusted workflow

package/docs/guides/scheduling.md

@@ -61,7 +61,7 @@ different checkout or package. Editing definitions and running ordinary `akm
 task sync` preserves that captured runtime.
 
 A scheduled fire re-reads the guarded current source and creates a fresh
-durable-v4-family freeze at executable `irVersion: 5`.
+durable-v4-family freeze at executable `irVersion: 8`.
 Scheduler sync/validation evidence is not an executable snapshot and is never reused as the later run plan.
 
 ## A scheduled `akm improve` covers one bundle
@@ -76,7 +76,7 @@ the command is `akm improve`'s own:
 
 ```sh
 akm task add improve-team --schedule "15 3 * * *" \
-  --command "akm improve --bundle team --require-engines"
+  --command "akm improve --bundle team"
 ```
 
 Leave `--skip-if-locked` off a once-a-night run: if a short-cadence improve task

package/docs/guides/use-with-any-agent.md

@@ -31,8 +31,8 @@ akm hints --detail brief >> AGENTS.md
 
 The output is stable across patch releases and designed for agents rather
 than humans: it describes the lookup workflow (`curate` → `show` →
-`feedback`) and explains how refs work. It prints a short guide by default;
-pass `--full` for the complete one.
+`feedback`) and explains how refs work. It prints the complete guide by default;
+`--detail brief` prints the short one.
 
 ## The retrieval loop: curate, show, feedback
 
@@ -80,9 +80,8 @@ recognized and indexed automatically once added as a source — see
 which formats are read-only versus writable in the current release.
 The native directory remains the source of truth: AKM translates recognized
 assets while reading the bundle and does not synchronize, copy, or write them
-back. The approved target execution rules for these translated agents and
-commands are documented in
-[Agent, Command, Engine, and Model Resolution](../architecture/specs/agent-command-engine-model-design.md).
+back. Execution of these translated agents and commands is described in
+[Architecture: Connections and Harnesses](../architecture/architecture.md#connections-and-harnesses).
 
 ## AKM complements, rather than replaces
 
@@ -98,15 +97,15 @@ than replacing either.
 
 - **Tab completion.** `akm completions --install` sets up shell completions
   for subcommands and flags. See [CLI Reference](../reference/cli.md#completions).
-- **Dispatching a bundle agent asset.** `akm agent agents/<name> --engine
-  <engine> --prompt "..."` runs a bundle `agents/<name>` persona and model
-  defaults through a named engine — including built-in model aliases like
-  `sonnet` and `opus` that resolve per platform. The current CLI rejects a
-  nonempty tool request at its separate authorization boundary; asset metadata
-  is never authorization by itself. See
-  [Configuration](../reference/configuration.md#engines) for the alias table
-  and [Architecture](../architecture/architecture.md) for how dispatch is
-  built into platform-specific CLI argv per backend.
+- **Dispatching a bundle agent asset.** `akm agent agents/<name> --harness
+  <harness> --prompt "..."` runs a bundle `agents/<name>` persona and model
+  default on a harness (or on akm's own runtime over a connection, with
+  `--connection <name>`), with the aliases `fast`, `balanced` and `reasoning`
+  resolved on whichever you select. See
+  [Configuration](../reference/configuration.md#aliases) for the aliases and
+  [Architecture](../architecture/architecture.md#connections-and-harnesses)
+  for how dispatch reaches each harness. The harness runs as you would run it by
+  hand ([how](../reference/configuration.md#how-akm-runs-a-harness)).
 - **Install refs vs. asset refs.** `npm:@scope/pkg` and `github:owner/repo`
   are install refs, accepted only by `akm bundle add`/`akm clone`, and are a
   different grammar from the `[bundle//]conceptId` refs `show`/`search` use.
@@ -156,18 +155,17 @@ config to follow prereleases. The exact rules are in the
 [`akm upgrade` reference](../reference/cli.md#harness-plugins). `akm health`
 warns when either plugin's bundled `akm-cli` differs from the running CLI.
 
-**Which OpenCode akm drives** is detected, not configured: an `opencode` or
-`opencode-sdk` agent engine runs the most recent OpenCode on `PATH` (or its own
-`bin`) and uses the adapters for the major that binary reports; OpenCode 1 logs a
-warning recommending OpenCode 2 (see
-[Configuration](../reference/configuration.md#engines)). It does not change
-which plugin you install, and the plugin choice does not change it.
+**Which OpenCode akm runs** does not depend on the plugin: the `opencode`
+harness runs your OpenCode through its CLI (OpenCode 1 and 2), and akm's own
+runtime fetches and runs its own pinned one (see
+[Configuration](../reference/configuration.md#without-a-harness)). Install the plugin for
+the OpenCode you use yourself.
 
 ## See also
 
-- [Configuration](../reference/configuration.md#engines) — named agent engines and model aliases
+- [Configuration](../reference/configuration.md#connections) — connections, harnesses and model aliases
 - [Discover and Load](discover-and-load.md) — the full curate → show retrieval path
-- [Knowledge Management](knowledge-management.md) — capturing agent-generated memories
+- [Capture Knowledge](capture-knowledge.md) — capturing agent-generated memories
 - [Improve the Library](improve-the-library.md) — feeding back usage signals
 - [CLI Reference](../reference/cli.md) — `completions`, `agent`, and `hints` command documentation
 - [Concepts](concepts.md) — refs, origins, and the asset type system

package/docs/integration/bundling-akm.md

@@ -29,12 +29,17 @@ akm migrate apply
 
 In order, every run applies (or, under `status`/`--dry-run`, plans):
 
-1. **config.json in its current shape** (`configFile`): retired and unknown
-   keys dropped, `configVersion` set. Config loading already does this in
-   memory; this persists it under a backup. A config older than 0.9.15 (the
-   legacy `stashDir`/`sources[]`/`installed` layout, an `extraParams` key
-   that shadows a first-class field) is not converted by 0.10: it blocks
-   with a message to run `akm migrate apply` under akm 0.9.x first.
+1. **config.json in its current shape** (`configFile`): unknown keys dropped,
+   `configVersion` set, and the `engines` / `defaults` form converted to
+   `connections` / `harnesses`. Config loading already does this in memory;
+   this persists it under a backup. The API keys a config still holds in any
+   form akm no longer reads move to `credentials.json` (`configFile.credentials`
+   lists the entry names, never a value), and a leftover `models.json` is folded
+   into the `models` of the connections and harnesses it names. A config older
+   than 0.9.15 (the legacy `stashDir`/`sources[]`/`installed` layout) is not
+   converted by 0.10: it blocks with a message to run `akm migrate apply` under
+   akm 0.9.x first. What each retired key becomes is the table in
+   [Configuration](../reference/configuration.md#the-engines-form).
 2. **Pending `state.db` migrations**, historical-destructive ones included
    (`stateMigrations`). This is the only path (besides `akm upgrade`, which
    calls the same code) that is allowed to apply a destructive migration to an
@@ -45,7 +50,11 @@ In order, every run applies (or, under `status`/`--dry-run`, plans):
    task source v4 (`taskFiles`) under one backup directory per run. A file
    the planner cannot convert unambiguously is reported `blocked` and left
    alone; the rest still convert.
-4. **Residue sweep**: superseded pre-0.9.0 `.akm` files in the stash and the
+4. **Asset `engine:` keys** (`assetEngineKeys`): the retired `engine:` key on
+   commands, agents, workflows and task sources rewritten to `connection:` or
+   `harness:` by what the name is now, under one backup directory per run. A
+   bundle akm may not change is skipped.
+5. **Residue sweep**: superseded pre-0.9.0 `.akm` files in the stash and the
    transaction-journal, maintenance-barrier, lock-mutex and version-stamp
    files older releases kept under `$DATA`/`$STATE`/`$CONFIG` (`deadResidue`).
 
@@ -67,6 +76,7 @@ same step names):
   "configFile": { "keys": [], "changed": false, "applied": false },
   "stateMigrations": { "pending": [] },
   "taskFiles": { "schemaVersion": 1, "changed": 0, "skipped": 0, "blocked": 0, "files": [] },
+  "assetEngineKeys": { "schemaVersion": 1, "changed": 0, "skipped": 0, "files": [] },
   "deadResidue": { "pending": [] }
 }
 ```
@@ -104,8 +114,7 @@ same step names):
   conflict; a real `apply` will clear them.
 - **`blocked`** — at least one item cannot be applied automatically (a
   genuine authoring problem, e.g. a task file the migrator can't rewrite
-  unambiguously, or a config `extraParams` value that conflicts with its
-  first-class field). `blockers` names each one. `apply` still applies
+  unambiguously, or a config that fails validation). `blockers` names each one. `apply` still applies
   everything it *can*, then reports `blocked` and exits non-zero.
 
 A pending `state.db` migration needs no human decision, so it is never
@@ -119,6 +128,7 @@ Key fields:
 | --- | --- |
 | `stateMigrations` | `{ pending: string[] }` under `status`/`--dry-run`; `{ applied: string[], safetyCopyPath?: string }` after a real `apply`. `safetyCopyPath` is present only when a historical-destructive migration ran — see below. |
 | `taskFiles` | `changed`/`skipped`/`blocked` counts and a `files[]` array with each file's `status` and `reason`. |
+| `assetEngineKeys` | `changed`/`skipped` counts and a `files[]` array with each rewritten file's `rewrites` (`at`, `from`, `to`). |
 | `backupPath` / `applied` | Present after a real apply that rewrote at least one task file: the run's backup directory and how many files it rewrote. |
 | `deadResidue` | `{ pending: [...] }` under a read-only run, `{ removed: [...] }` / `{ recovered: [...], quarantined: [...], deferred: [...] }` after apply. An untrusted journal (unreadable `journal.json`, or a fence violation) is quarantined to `$DATA/txn-quarantine`; a trusted, fenced journal whose `rollback`/`finalize` throws is deferred, left in place under `$DATA/txn/<rootNs>/`. Neither is thrown, and neither sets `status` to `blocked`. `staleTxns.pending` entries carry `wouldQuarantine: { reason }` when the journal's read-only fence check alone (not a `rollback`/`finalize` run) already shows it would be quarantined by a real apply. |
 

package/docs/maintainers/README.md

@@ -8,12 +8,8 @@ actually improve it, and the current state of the `curate` implementation.
   kind of contributor check (live source, built launcher, packed-package
   acceptance, global checkout install) and the verification commands to run
   before pushing.
-- [Release Checklist](release-checklist.md) — local release validation, exact
-  candidate-SHA semantic/Docker/native-scheduler gates, and the evidence links
-  required before publication.
+- [Release Checklist](release-checklist.md) — the branch model and the steps to
+  cut, release and install akm and its plugins.
 - [akm-eval](https://github.com/itlackey/akm-eval) — the evals and benchmarks
   that measure whether `akm improve` and retrieval changes are actually
   working. The old in-repo toolkit is retired: see [eval.md](eval.md).
-- [Curate Workmap](curate-workmap.md) — the current `akm curate` contract,
-  where its implementation diverges from intended behavior, and the
-  highest-value next fixes.

package/docs/maintainers/release-checklist.md

@@ -1,135 +1,82 @@
 # Release Checklist
 
-Use this checklist for every release candidate. Local release validation and
-scheduled CI are useful inputs, but neither substitutes for a successful gated
-run of the exact commit that will be published.
-
-## 1. Freeze the candidate
-
-1. Finish the version, changelog, migration-note, and release-PR changes. From
-   0.10 the version is a monthly release number, `0.10.YYMMNN` (see step 4):
-   `bun scripts/release-version.ts next` prints the next free one for this
-   month (UTC). Every release, whatever its stage, takes the next number.
-   Commit it in `package.json` and cut the CHANGELOG as
-   `## [0.10.YYMMNN] - YYYY-MM-DD`. A prerelease stage is not committed: it is
-   chosen when the Release workflow runs, and the release's CHANGELOG section
-   covers it.
-2. Record `git rev-parse HEAD`. This is the full 40-character release-candidate SHA.
-3. Run `bun run release:check` locally. If Docker is unavailable, run
-   `./tests/release-check.sh --skip-docker` and rely on the gated Docker job
-   below for the container matrix.
-
-Any commit added after this point creates a new candidate and invalidates the
-gated evidence collected for the previous SHA.
-
-## 2. Collect exact-SHA gated evidence
-
-GitHub only offers a scheduled or manually dispatched workflow after its file
-exists on the default branch. When validating the commit that first introduces
-or changes this workflow, create a unique lightweight candidate tag at the
-recorded SHA:
+`main` is the stable line (npm `latest`). The next version is developed on a
+release branch, `release/<version>` (npm `next`), which merges to `main` when
+it becomes stable. A fix for stable lands on `main` and is cherry-picked onto
+the release branch when that branch needs it.
+
+## 1. Cut the version
+
+On the branch you release from (`main` for stable, the release branch for
+next):
+
+1. Set the version: `npm pkg set version=<version>`. From 0.10,
+   `bun scripts/release-version.ts next` prints the next free one (see
+   [Versions](#versions)).
+2. Cut the changelog: add `## [<version>] - <YYYY-MM-DD>` (UTC date) directly
+   under `## [Unreleased]`, so the unreleased entries become this release's
+   section. CI fails the release commit when the newest section does not name
+   the `package.json` version (`tests/workflow-release.test.ts`).
+3. Add a migration note if the release needs one (see
+   [CONTRIBUTING](https://github.com/itlackey/akm/blob/main/.github/CONTRIBUTING.md#shipping-a-release--migration-notes)).
+4. Commit `release: <version>`, push it to the branch, and let CI run on it.
+
+## 2. Release akm
+
+```sh
+gh workflow run release.yml --ref <branch> -f version=<version> [-f stage=alpha|beta|rc]
+```
+
+The Release workflow, on the pushed commit:
+
+1. runs Gated CI: semantic search with real embeddings, the Docker install
+   matrix, and the native schedulers on Linux, macOS and Windows;
+2. requires CI to have passed on the same commit (it does not run lint, the
+   typecheck or the test suites again);
+3. runs `tests/release-check.sh --skip-docker`: the packaged artifact's bin
+   targets and migrator, package acceptance, and the upgrade rehearsal against
+   the packed tarball;
+4. builds the package and standalone binaries, publishes to npm (`latest` for
+   a stable version, `next` for a prerelease) and creates the GitHub release.
+
+If a job fails on a flake, rerun the failed jobs. If the fix needs a code
+change, commit it and release that commit. npm can take several minutes to show
+a new version: check `npm view akm-cli@<tag> version` before upgrading.
+
+## 3. Release the plugins
 
 ```sh
-candidate_sha="$(git rev-parse HEAD)"
-candidate_short_sha="$(git rev-parse --short=12 HEAD)"
-candidate_version="$(node -p 'require("./package.json").version')"
-candidate_tag="gated-ci/candidate-${candidate_version}-${candidate_short_sha}"
-git tag "$candidate_tag" "$candidate_sha"
-git push origin "refs/tags/$candidate_tag"
+gh workflow run release.yml --repo itlackey/akm-plugins --ref <plugins branch> -f akm_version=<published akm version>
 ```
 
-Verify that the tag target is the exact candidate commit recorded in step 1.
-The `gated-ci/candidate-*` trigger runs every gated suite from the workflow in
-that tagged commit. The resolver checks that the checkout equals the immutable
-event SHA, and the final evidence job records both that SHA and the tag ref.
-Never force-move or reuse a candidate tag; a changed commit needs a new tag and
-a new run.
-
-After **Gated CI** exists on the default branch, manual dispatch is an
-equivalent exact-SHA path. From the repository's Actions page, choose **Run
-workflow** and supply:
-
-- `candidate_sha`: the full 40-character SHA recorded above, never a branch or
-  tag name.
-
-Every suite runs; there is no suite selector.
-
-The manual request rejects abbreviated SHAs and checks out that immutable
-commit for every gate. Wait for all of these stable checks to succeed on either
-candidate path:
-
-- `Gated / Semantic Search`
-- `Gated / Docker Install`
-- `Gated / Native Scheduler / Linux`
-- `Gated / Native Scheduler / macOS`
-- `Gated / Native Scheduler / Windows`
-- `Gated / Release Candidate Evidence`
-
-The final evidence job records the requested and resolved SHA, the trigger ref,
-each suite's result, and a run link in the workflow summary. A weekly run is
-drift detection, not release evidence, because it may cover a different
-commit.
-
-Manual and tagged candidate runs are cache restore-only. Only a successful
-scheduled run of the workflow on the repository's default branch may save the
-HuggingFace model cache; its key identifies both the embedding model and the
-source/lock inputs. This prevents candidate-controlled workflow code from
-publishing cache entries while still avoiding repeated model downloads.
-
-Copy the successful run URL (for example,
-`https://github.com/itlackey/akm/actions/runs/<run-id>`) and the exact candidate
-SHA into both the release PR and its milestone/parent tracker. Do not publish
-from a candidate whose evidence link names a different SHA, whose final
-evidence job is skipped, or whose run was re-run after the candidate changed.
-
-## 3. Gated CI does not run on pull requests
-
-Gated CI runs on three triggers only: the weekly schedule, an exact-SHA
-`workflow_dispatch`, and a `gated-ci/candidate-*` tag. All three run every
-suite.
-
-There used to be a `Gated / Detect Changed Paths` job that also ran these on
-PRs, selecting suites by regex-matching the diff against path lists. It was
-deleted in 0.9.8: the patterns had gone stale — they still named test files a
-reorganisation had moved or deleted, so it was silently under-selecting suites
-and nobody noticed. A build-policing job that quietly stops policing is worse
-than no job, because its green status is read as coverage.
-
-Nothing about release evidence changes. Step 2 was always the requirement, and
-it never went through the PR path.
-
-The candidate-tag trigger is reserved for release evidence and workflow
-rollout: it always runs `all`, because a tag-push workflow is the path available
-before the workflow file reaches the default branch.
-
-## 4. Publish
-
-After the exact-SHA gated run and local release check are green, trigger the
-Release workflow with the version already committed in `package.json`. Keep the
-candidate SHA and Gated CI run URL in the release record so the published
-artifact's validation can be audited later.
+Plugins match akm's major.minor and keep their own patch numbers; each plugin
+release's notes name the akm version it requires. A plugin-only fix is released
+the same way, with the akm version already published. The Claude marketplace
+reads the plugins repository's `main`, so stable plugin releases come from
+`main`.
+
+## 4. Upgrade
+
+`akm upgrade` (stable) or `akm upgrade --next` (prerelease) updates akm and the
+installed plugins.
+
+## Gated CI on its own
+
+Gated CI also runs weekly on `main` to catch drift, and on demand from the
+Actions tab on any ref. Only the weekly run saves the Hugging Face model cache.
+
+## Versions
 
 0.10 and later use monthly release numbers, `0.10.YYMMNN`: `YY` the UTC year,
 `MM` the month and `NN` the release in that month (`01` to `99`), two digits
-each (see [`STABILITY.md`](../../STABILITY.md)). The first release of 2026-10 is
-`0.10.261001`. `bun scripts/release-version.ts next` takes `NN` as one above the
-highest release already on npm for this UTC month, with or without a stage
-(`npm view akm-cli versions`), so numbering follows what was published, not
-what was committed. The retired 8-digit daily builds (`0.10.26101001-alpha` to
-`0.10.26101202-alpha`) are not counted.
-
-The workflow has two inputs:
-
-- `version`: the version committed in `package.json`, as before. The workflow
-  rejects a malformed one (`scripts/release-version.ts`, tested in
-  `tests/release-version.test.ts`): two digits each for `YY`, `MM`, `NN`, a
-  month 01 to 12, `NN` 01 to 99; the old 8-digit daily form is rejected. For
-  0.9 and older it is the `X.Y.Z` as before.
-- `stage`: `none` publishes `<version>` to the npm `latest` tag and as a GitHub
-  release. `alpha`, `beta` or `rc` publishes `<version>-<stage>` to `next` as a
-  GitHub prerelease (no `.N`: every release has its own number). There is no
-  promoting one build through stages: the next release, at any stage, commits
-  the next number (`0.10.261001-alpha`, then `0.10.261002-beta`, then
-  `0.10.261003`).
-
-`bun scripts/release-version.ts validate <version>` checks a version by hand.
+each (see [`STABILITY.md`](../../STABILITY.md)). `bun scripts/release-version.ts
+next` takes `NN` as one above the highest release already on npm for this UTC
+month, with or without a stage, and `bun scripts/release-version.ts validate
+<version>` checks one by hand. The retired 8-digit daily builds
+(`0.10.26101001-alpha` to `0.10.26101202-alpha`) are not counted. 0.9 and older
+use `X.Y.Z`.
+
+The `stage` input is not committed: `none` (the default) publishes `<version>`
+to `latest`; `alpha`, `beta` or `rc` publishes `<version>-<stage>` to `next` as
+a GitHub prerelease. Every release, at any stage, takes the next number; a
+build is not promoted through stages.

package/docs/migration/README.md

@@ -2,14 +2,21 @@
 
 Upgrade guides and per-release migration notes.
 
+## Current
+
 - [v0.9 -> v0.10 migration guide](v0.9-to-v0.10.md) -- Upgrade order for a 0.9.15+ install, every removed CLI spelling, strategy, config key and workflow feature with its replacement, changed `akm improve` defaults, the OpenCode plugins, and `0.10.YYMMNN` version numbers
 - [v0.10.0 release note](release-notes/0.10.0.md) -- Summary of the 0.10 series: the 0.9.15 version floor, `--shape`/`--target`/`help agents` removals, `default` and `consolidate` as the only built-in strategies, OpenCode 2, feedback-scaled ranking, and what is gone
+- [Release notes index](release-notes/README.md) -- The short per-release notes `akm help migrate <version>` prints, with links to every bundled note
+
+## Historical
+
+Guides and notes for earlier releases. They describe the commands and formats of
+their own release, which the current CLI may no longer have, and are not checked
+against it.
+
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
 - [v0.9.17 release note](release-notes/0.9.17.md) -- Consolidate's retire proposals and index layout 26, replacing the LLM entity graph with declared links, and `akm improve` scoped to what retrieval actually returns
 - [v0.9.19 release note](release-notes/0.9.19.md) -- `akm improve` scoped to the bundle it writes to (scheduled runs need one `--bundle` run per other bundle), `akm proposal reopen` and the retire-proposal diff, and fewer repeat consolidate promotions
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
-- [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
-- [v0.5 -> v0.6 migration guide](v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
-- [Release notes index](release-notes/README.md) -- The short per-release notes `akm help migrate <version>` prints, with links to every bundled note