akm-cli 0.10.261018-beta → 0.10.261020-beta

package/dist/indexer/passes/metadata.js

@@ -875,9 +875,9 @@ function isMarkdownFenceClosing(line, fence) {
  * Version of what {@link projectMarkdownContent} indexes. It is part of every
  * directory's index fingerprint, so bumping it makes the next `akm index`
  * re-project every directory once instead of keeping the old text for
- * unchanged files. 2: identifiers from fenced code (akm#1260).
+ * unchanged files. 3: count each fenced identifier once per document (akm#1284).
  */
-export const CONTENT_PROJECTION_VERSION = 2;
+export const CONTENT_PROJECTION_VERSION = 3;
 /** At or above this length a token with a digit reads as a key or hash, not a name. */
 const TOKEN_LIKE_MIN_LENGTH = 20;
 /**
@@ -1114,7 +1114,7 @@ export function projectMarkdownContent(body, truncationInfo) {
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
     const projected = [];
-    const fenced = [];
+    const fenced = new Map();
     forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
         let trimmed = visible.trim();
         if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
@@ -1135,11 +1135,13 @@ export function projectMarkdownContent(body, truncationInfo) {
             projected.push(trimmed);
     }, (_index, fencedLine) => {
         const identifiers = fencedCodeIdentifiers(fencedLine);
-        if (identifiers)
-            fenced.push(identifiers);
+        for (const identifier of identifiers.split(/\s+/)) {
+            if (identifier)
+                fenced.set(identifier.toLowerCase(), identifier);
+        }
     });
     // Fenced identifiers follow the prose, so a head-truncated embedding input keeps the prose first.
-    const text = [...projected, ...fenced].join(" ").replace(/\s+/g, " ").trim();
+    const text = [...projected, ...fenced.values()].join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
     if (truncationInfo)

package/dist/output/text/command-format.js

@@ -680,11 +680,15 @@ function formatUpgradePluginLines(r) {
     }
     const plugins = Array.isArray(r.plugins) ? r.plugins : [];
     for (const p of plugins) {
-        if (p.outcome === "current" || p.outcome === "skipped")
+        if ((p.outcome === "current" || p.outcome === "skipped") &&
+            (r.updateAvailable === undefined || !p.channel) &&
+            !p.channelMismatch &&
+            !p.targetChannel)
             continue;
         const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
+        const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
         const note = p.message ? ` (${p.message})` : "";
-        lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+        lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
     }
     return lines;
 }
@@ -698,8 +702,11 @@ function formatUpgradeHead(r) {
     if (r.upgraded === true) {
         return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
     }
+    if (r.targetChannel && r.latestVersion && r.latestVersion !== r.currentVersion && r.updateAvailable === false) {
+        return `akm v${r.currentVersion} → v${r.latestVersion} requires --allow-downgrade (run 'akm upgrade --channel ${r.targetChannel} --allow-downgrade' to install)`;
+    }
     if (r.updateAvailable === true) {
-        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
+        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.targetChannel ? ` --channel ${r.targetChannel}` : r.channel === "next" ? " --next" : ""}' to install)`;
     }
     if (r.updateAvailable === false && r.latestVersion) {
         return `akm v${r.currentVersion} is already the latest version`;

package/dist/scripts/akm-migrate-node.js

@@ -34812,7 +34812,7 @@ function projectMarkdownContent(body, truncationInfo) {
   const innerBlock = findInnerFrontmatterBlock(lines);
   const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
   const projected = [];
-  const fenced = [];
+  const fenced = new Map;
   forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
     let trimmed = visible.trim();
     if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
@@ -34832,10 +34832,12 @@ function projectMarkdownContent(body, truncationInfo) {
       projected.push(trimmed);
   }, (_index, fencedLine) => {
     const identifiers = fencedCodeIdentifiers(fencedLine);
-    if (identifiers)
-      fenced.push(identifiers);
+    for (const identifier of identifiers.split(/\s+/)) {
+      if (identifier)
+        fenced.set(identifier.toLowerCase(), identifier);
+    }
   });
-  const text2 = [...projected, ...fenced].join(" ").replace(/\s+/g, " ").trim();
+  const text2 = [...projected, ...fenced.values()].join(" ").replace(/\s+/g, " ").trim();
   if (!text2)
     return;
   if (truncationInfo)
@@ -70528,11 +70530,12 @@ function formatUpgradePluginLines(r) {
   }
   const plugins = Array.isArray(r.plugins) ? r.plugins : [];
   for (const p of plugins) {
-    if (p.outcome === "current" || p.outcome === "skipped")
+    if ((p.outcome === "current" || p.outcome === "skipped") && (r.updateAvailable === undefined || !p.channel) && !p.channelMismatch && !p.targetChannel)
       continue;
     const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} → v${p.to}` : "";
+    const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
     const note = p.message ? ` (${p.message})` : "";
-    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
   }
   return lines;
 }
@@ -70547,8 +70550,11 @@ function formatUpgradeHead(r) {
   if (r.upgraded === true) {
     return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
   }
+  if (r.targetChannel && r.latestVersion && r.latestVersion !== r.currentVersion && r.updateAvailable === false) {
+    return `akm v${r.currentVersion} → v${r.latestVersion} requires --allow-downgrade (run 'akm upgrade --channel ${r.targetChannel} --allow-downgrade' to install)`;
+  }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
+    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.targetChannel ? ` --channel ${r.targetChannel}` : r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;

package/dist/scripts/akm-migrate.js

@@ -34811,7 +34811,7 @@ function projectMarkdownContent(body, truncationInfo) {
   const innerBlock = findInnerFrontmatterBlock(lines);
   const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
   const projected = [];
-  const fenced = [];
+  const fenced = new Map;
   forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
     let trimmed = visible.trim();
     if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
@@ -34831,10 +34831,12 @@ function projectMarkdownContent(body, truncationInfo) {
       projected.push(trimmed);
   }, (_index, fencedLine) => {
     const identifiers = fencedCodeIdentifiers(fencedLine);
-    if (identifiers)
-      fenced.push(identifiers);
+    for (const identifier of identifiers.split(/\s+/)) {
+      if (identifier)
+        fenced.set(identifier.toLowerCase(), identifier);
+    }
   });
-  const text2 = [...projected, ...fenced].join(" ").replace(/\s+/g, " ").trim();
+  const text2 = [...projected, ...fenced.values()].join(" ").replace(/\s+/g, " ").trim();
   if (!text2)
     return;
   if (truncationInfo)
@@ -70526,11 +70528,12 @@ function formatUpgradePluginLines(r) {
   }
   const plugins = Array.isArray(r.plugins) ? r.plugins : [];
   for (const p of plugins) {
-    if (p.outcome === "current" || p.outcome === "skipped")
+    if ((p.outcome === "current" || p.outcome === "skipped") && (r.updateAvailable === undefined || !p.channel) && !p.channelMismatch && !p.targetChannel)
       continue;
     const versions = p.from && p.to && p.from !== p.to ? ` v${p.from} \u2192 v${p.to}` : "";
+    const channel = p.channel ? ` [channel ${p.channel}${p.channelMismatch ? "; differs from CLI" : ""}]` : "";
     const note = p.message ? ` (${p.message})` : "";
-    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${note}`);
+    lines.push(`${HARNESS_LABELS[String(p.harness)] ?? p.harness} plugin ${p.outcome}${versions}${channel}${note}`);
   }
   return lines;
 }
@@ -70545,8 +70548,11 @@ function formatUpgradeHead(r) {
   if (r.upgraded === true) {
     return `akm upgraded: v${r.currentVersion} \u2192 v${r.newVersion}`;
   }
+  if (r.targetChannel && r.latestVersion && r.latestVersion !== r.currentVersion && r.updateAvailable === false) {
+    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} requires --allow-downgrade (run 'akm upgrade --channel ${r.targetChannel} --allow-downgrade' to install)`;
+  }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
+    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade${r.targetChannel ? ` --channel ${r.targetChannel}` : r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;

package/docs/architecture/internals/health-advisories.md

@@ -34,7 +34,7 @@ harness's `--version`, looks up the latest akm release on GitHub for `cli-versio
 Claude plugin is installed. With
 `--no-probe` none of these runs: the connection rows carry no `reachable` field and the
 message says reachability was not probed, and `plugin-version` reports `unknown` (its
-`AKM_VERSION_RANGE` check is local and still runs). The `plugin-version` and `cli-version`
+`AKM_MIN_VERSION` (or legacy `AKM_VERSION_RANGE`) check is local and still runs). The `plugin-version` and `cli-version`
 lookups are best-effort and silent on failure; see `src/commands/health/plugin-staleness.ts`
 and `src/commands/health/version-drift.ts`.
 
@@ -62,7 +62,7 @@ and `src/commands/health/version-drift.ts`.
 | `type-directory-disagreement` | `warn`: an indexed asset's resolved type differs from the type its directory declares. Each line gives the file, both types, and the classifier signal that won (`winner`). | Review the listed files. Intended overrides (for example a `knowledge/` file containing `$ARGUMENTS`) are marked `known-good override`. |
 | `memory-cleanup-archive` | `pass` with size and file count when the working bundle has `.akm/memory-cleanup/archive` content and no git history (the purge does not run there). `warn` when a git-backed bundle has archived files the purge cannot remove (untracked, modified, or unverifiable in git). | Commit the archived files so the purge can remove them once they age out. |
 | `data-dir-usage` | `warn`: the data directory is over 1 GB and either more than 3 times the size of `state.db`, `index.db`, and `logs.db` (with their WAL and SHM files), or one top-level subdirectory holds more than half of it. The message names that subdirectory and its size. | Inspect the named subdirectory. `backups/tasks/` holds task-file snapshots written by `akm migrate apply`. |
-| `plugin-version` | One row per installed Claude Code harness plugin: its version and whether its declared `AKM_VERSION_RANGE` admits the running CLI. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. The newest-tag lookup is `--probe`-gated: with `--no-probe` the row is `unknown` ("not probed") and only the local range check still runs. `warn`: the plugin is stale, or its range does not admit the running CLI. | Run the `claude plugin update <ref>` command in the message. |
+| `plugin-version` | One row per native `claude plugin list --json` AKM installation, with scope, enabled state and install path; cached versions are never used to choose an installation. `AKM_MIN_VERSION` takes precedence over legacy `AKM_VERSION_RANGE`. Disabled and other-project installations are inert. Missing metadata or multiple applicable paths/versions produce `unknown`, since the native list does not identify which conflicting installation a running session loaded. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. The newest-tag lookup is `--probe`-gated: with `--no-probe` the row is `unknown` ("not probed") and only the local range check still runs. `warn`: the plugin is stale, or its range does not admit the running CLI. | Run the `claude plugin update <ref>` command in the message. |
 | `opencode-plugin-version` | The same check for the OpenCode plugin's own bundled `akm-cli` (read from its `package.json`, never executed): it runs in-process and shares the host's databases, so its lag matters the same way. OpenCode 1 caches each spec in its own folder, so it reads the one folder of the spec the global OpenCode config names under `plugin` (`akm-opencode`, read as `akm-opencode@latest`, or `akm-opencode@next`), and for `akm-opencode@<version>` reports the plugin as pinned with no staleness verdict; with no entry, or no folder for it, it reads `packages/akm-opencode`, and it never scans the other cached specs. It reads local files only and is never `--probe`-gated. `warn`: the bundled version differs from the running CLI. Omitted when the OpenCode plugin is not installed. | Update the OpenCode plugin. |
 | `state-db-readable` | `fail`: `state.db` cannot be read, or is missing in a read-only run (which does not create it). Every other check is skipped, because none of them can read it. | Check the owner and mode of the data directory (or point `AKM_DATA_DIR` / `XDG_DATA_HOME` at one you own); run any akm command that records state, such as `akm health`, to create it. |
 

package/docs/architecture/testing/testing-workflow.md

@@ -439,18 +439,24 @@ orchestration, checksum, and failure paths.
 
 `tests/integration/upgrade-rehearsal/` runs once per origin in
 `KNOWN_UPGRADE_ORIGINS` (`previous-release.ts`): `previous`, the highest stable
-release below the candidate's `package.json` version, and `0.9.15`, a fixed
-older release. For each origin it installs that release as a real global npm
+release below the candidate's `package.json` version; `0.9.32`, which keeps the
+full engines migration covered after `previous` advances to 0.10; and `0.9.15`,
+which covers scheduler rows installed before host-local activation was recorded.
+Each origin installs that release as a real global npm
 package (a real `npm pack` / `npm install --global` into a throwaway prefix, see
-`scripts/package-install.ts`), uses it to build a realistic home — filesystem,
+`scripts/package-install.ts`). The `previous` and `0.9.32` origins build a full
+home — filesystem,
 git (with an in-bundle symlink at its root), website, and npm bundles, scheduled
-tasks, a synced native (fake) crontab, and the 0.9 `engines` form the release
-itself writes (an llm engine with an `apiKeyFile`, an agent engine, a
-`models.json`, a command and a task source that name an engine) — then installs
+tasks, a synced native (fake) crontab, and model configuration the release
+itself writes: native connections/harnesses on 0.10+, or the full 0.9 `engines`
+form (an llm engine with an `apiKeyFile`, agent engines, a `models.json`, and a
+command and task that name an engine). The `0.9.15` origin uses a smaller home
+with one directly installed scheduled task. Each then installs
 the CANDIDATE build OVER it in the SAME prefix: an in-place swap, the same thing
 a real `npm i -g akm-cli@…` or `bun add -g` upgrade does. It then runs the
 candidate against that home (`migrate status` / `apply`, which converts the
-`engines` form, files its key and rewrites the `engine:` keys, `bundle list`,
+`engines` form, files its key and rewrites the `engine:` keys, or preserves
+native connections/harnesses, `bundle list`,
 `search` / `show`, `task sync` dry-run and real — plain, no `--rebind`, as an
 upgrading user runs it — executing the generated cron command and confirming it
 ran the candidate, `task run`, `health`, `improve --dry-run`), and finally runs a

package/docs/migration/README.md

@@ -5,7 +5,7 @@ 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
+- [v0.10.0 release note](release-notes/0.10.261019.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

package/docs/migration/release-notes/{0.10.0.md → 0.10.261019.md}

@@ -1,4 +1,4 @@
-# akm v0.10.0 migration notes
+# akm v0.10 migration notes (0.10.261019, the first stable 0.10 release)
 
 0.10 is a clean-up and tuning release. It covers the daily alphas
 0.10.26101001 through 0.10.26101202 and the monthly releases that follow
@@ -87,7 +87,10 @@ not offer it.
   config keys, paths and dotted references such as `process.env.CI` in a fenced
   block now reach the `content` search text; quoted strings, assignment values,
   URLs and long token-like strings still do not. Search results, fragments and
-  `akm show` are unchanged. On the first run after upgrading, `akm index` (and
+  `akm show` are unchanged. It lifts code lookups and keyword library search
+  in akm-eval and costs about 2 NDCG points on the SkillRet skill-selection
+  benchmark, where long, code-heavy skills now outrank short, code-free ones;
+  tuning is tracked in #1284. On the first run after upgrading, `akm index` (and
   the index `akm upgrade` runs, which `akm upgrade` waits for) re-reads every
   bundle directory and re-embeds only the entries whose embedded text changed.
   Text past `embedding.maxInputTokens` (default 512, about 2,048 characters) is

package/docs/migration/release-notes/0.10.261020.md

@@ -0,0 +1,22 @@
+# akm v0.10.261020 migration notes
+
+This beta fixes Claude plugin health reporting, adds coordinated channel
+switching, and reduces repeated fenced identifiers in search content.
+
+The next index pass refreshes existing content projections and changed embedding
+inputs automatically. No manual database or configuration migration is required
+when upgrading from 0.10.261019.
+
+After installing this beta, `akm upgrade --channel next` switches the CLI and
+installed Claude, Codex and OpenCode plugins together. The existing `--next`
+flag keeps its prior behavior. To return to stable, use
+`akm upgrade --channel latest`; if the target version is older, add
+`--allow-downgrade`. Changed settings receive backups, and the command reports
+any harness that could not finish switching. Restart the harness after updates.
+
+Claude health now uses native installation metadata. It reports conflicting or
+incomplete installation selections as unknown instead of choosing a cached
+version. This can change a previous warning without changing the installation.
+
+If upgrading from 0.9, first follow the
+[0.9 to 0.10 migration guide](../v0.9-to-v0.10.md).

package/docs/migration/release-notes/README.md

@@ -7,7 +7,8 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
-- [0.10.0](0.10.0.md) — The 0.10 series: 0.9.15 version floor, merged CLI spellings, `default`/`consolidate` strategies only, OpenCode 2, feedback-scaled ranking, and `0.10.YYMMNN` versions.
+- [0.10.261020](0.10.261020.md) — Coordinated beta/stable channel switching, native Claude health, and automatic search-projection refresh.
+- [0.10.261019](0.10.261019.md) — The 0.10 series: 0.9.15 version floor, merged CLI spellings, `default`/`consolidate` strategies only, OpenCode 2, feedback-scaled ranking, and `0.10.YYMMNN` versions.
 - [0.9.19](0.9.19.md) — Bundle-scoped improve planning, proposal reopen, and consolidate/distill guardrails.
 - [0.9.17](0.9.17.md) — Retire proposals, declared links replacing the LLM entity graph, and scoped improve planning.
 - [0.9.16](0.9.16.md) — Source-bound scheduler grants, local execution authority, and split unsafe overrides.

package/docs/migration/v0.9-to-v0.10.md

@@ -12,7 +12,7 @@ every change that can break a script, a task or a config.
 Checked against build 0.10.261013 with the connections and harnesses rework
 (#1244). The
 user-facing summary of the whole series is the
-[0.10.0 release note](release-notes/0.10.0.md); the per-build detail is in the
+[0.10 release note](release-notes/0.10.261019.md); the per-build detail is in the
 [CHANGELOG](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).
 
 ## What the upgrade preserves
@@ -801,7 +801,7 @@ below every daily alpha. Install the first monthly release explicitly once, for
 example `npm install -g akm-cli@0.10.261001-beta`; `akm upgrade` works normally
 from there.
 
-`akm help migrate 0.10.0` prints the [0.10.0 release note](release-notes/0.10.0.md).
+`akm help migrate 0.10.261019` (or `akm help migrate latest`) prints the [0.10 release note](release-notes/0.10.261019.md).
 The loader looks a note up by its exact file name, so `akm help migrate latest`
 and a release number such as `0.10.261001` print the CHANGELOG section
 only.

package/docs/reference/cli.md

@@ -1537,7 +1537,9 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Install a newer release if there is one, run every pending migration, then update the harness plugins
 akm upgrade --check      # Report pending updates, CLI and plugins, without changing anything (no migration step)
 akm upgrade --force      # Force the install even if already on latest
-akm upgrade --next       # Install the newest prerelease (@next) instead of the latest stable release
+akm upgrade --next       # Include prereleases when selecting the newest CLI release
+akm upgrade --channel next   # Switch CLI and installed harness plugins to next
+akm upgrade --channel latest # Return CLI and installed harness plugins to stable
 ```
 
 | Flag | Description |
@@ -1545,7 +1547,9 @@ akm upgrade --next       # Install the newest prerelease (@next) instead of the
 | `--check` | Report pending updates (CLI and per-harness plugins) without changing anything |
 | `--force` | Force upgrade even if on latest version |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
-| `--next` | Follow the `next` prerelease channel: install the newest prerelease of akm (and of the OpenCode plugin, see the Prereleases section below). Works with `--check`, `--force` and `-q` |
+| `--channel latest\|next` | Switch the CLI and installed Claude, Codex and OpenCode plugins together; works with `--check` |
+| `--allow-downgrade` | Permit an older target version during an explicit `--channel` switch |
+| `--next` | Include prereleases when selecting the newest CLI release; retain configured harness channels (see below). Works with `--check`, `--force` and `-q` |
 
 Offline, or to migrate without a release check, run `akm migrate apply`
 directly: it is the same step.
@@ -1607,7 +1611,7 @@ target is the akm-cli that `akm-opencode@latest` depends on
 The result then carries `lockstep: { plugin, pinnedVersion, newestVersion, heldBack }`,
 `latestVersion` is the pinned version, the install names that exact version
 rather than `@latest`, and the text output says the CLI is held back. The CLI
-is never moved backwards to meet the pin. With both OpenCode plugins present
+is never moved backwards to meet the pin unless an explicit channel switch also names `--allow-downgrade`. With both OpenCode plugins present
 (`akm-opencode` and `akm-opencode-v2`), the CLI is held to the older of their
 two pins, and `lockstep.plugin` names the one that sets it. Claude Code and Codex have no
 in-process copy and are not part of this rule.
@@ -1623,7 +1627,7 @@ retries.
 #### Prereleases (`--next`)
 
 `akm upgrade --next` means "newest available, prereleases included". The result
-carries `channel: "next"` (`"latest"` otherwise); no other field changes.
+carries `channel: "next"` (`"latest"` otherwise), plus the CLI's inferred `currentChannel` and each installed plugin's configured `channel` and `channelMismatch`.
 
 - **CLI.** The target is the `next` dist-tag of `akm-cli` (read from the npm
   registry, so it works for binary installs too) when that is newer than the
@@ -1656,14 +1660,38 @@ carries `channel: "next"` (`"latest"` otherwise); no other field changes.
 - **Claude Code and Codex.** Their plugin comes from the `akm-plugins` git
   marketplace, and the channel is the ref the marketplace follows: the default
   branch is stable, the `next` branch carries prereleases. `akm upgrade` updates
-  whatever ref the marketplace follows and cannot switch it, with or without
-  `--next`. To follow prereleases, add the marketplace as `itlackey/akm-plugins@next`
-  in Claude Code (`extraKnownMarketplaces.akm-plugins.source.ref = "next"` in
-  `settings.json`), or run `codex plugin marketplace add itlackey/akm-plugins --ref next`
-  in Codex. Under `--next` their entries carry a note naming the ref followed.
+  whatever ref the marketplace follows. `--next` alone leaves that ref unchanged;
+  `--channel next` changes it. Under `--next` their entries carry a note naming
+  the ref followed.
   The plugins need akm 0.10.261001 or newer; any newer akm passes.
 - `--check --next` reports all of this and changes nothing.
 
+#### Switching channels together (`--channel`)
+
+`akm upgrade --channel next` selects the actual npm `next` CLI tag and changes
+installed harness plugins to their `next` branch or package tag.
+`--channel latest` selects stable and removes those prerelease refs. An explicit
+switch may replace a pinned plugin spec. The command checks target CLI and plugin
+versions first; if any would go backwards, repeat with `--allow-downgrade`.
+A failed CLI install or migration stops the plugin switch.
+
+Claude and Codex retain their marketplace registrations, plugin enablement,
+`pluginConfigs`, and unrelated settings. akm edits only the marketplace ref,
+then uses the native updater. Claude's installed user, project and local scopes
+are updated explicitly. OpenCode changes only the installed plugin's spec,
+retaining tuple options and JSONC comments, then refreshes the desired cache.
+Every changed config file has a sibling `.akm-channel-*.bak` backup, whose path
+appears in that harness's `backups` result. Restart the harness to load updates.
+
+`--check --channel next` shows `channel`, `targetChannel` and mismatches without
+writing settings or fetching Git marketplaces. The CLI's `currentChannel` is
+inferred from its version: prerelease means `next`, otherwise `latest`.
+A configured channel is distinct from a successful refresh: native update
+failures retain the configured target and backup paths but report `failed`.
+An installed plugin that cannot switch, including OpenCode awaiting shutdown,
+makes an explicit switch exit `1`; retry after resolving its reported cause.
+The switch is coordinated, not a transaction across independent harnesses.
+
 #### Containers
 
 With the plugin step, a container entrypoint needs only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261018-beta",
+  "version": "0.10.261020-beta",
   "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": [
@@ -119,9 +119,11 @@
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",
     "fast-xml-parser": "^5.10.1",
+    "jsonc-parser": "^3.3.1",
     "marked": "^18.1.1",
     "node-html-parser": "^9.0.1",
     "semver": "^7.6.0",
+    "smol-toml": "^1.9.1",
     "turndown": "^7.2.4",
     "yaml": "^2.8.4",
     "zod": "^4.6.6"