akm-cli 0.10.261014-beta → 0.10.261016-beta

package/CHANGELOG.md

@@ -6,6 +6,124 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261016] - 2026-10-27
+
+### Added
+
+- `akm show` returns a Markdown document's outline as `toc` (#1259): one
+  `{ level, text, slug, startLine }` entry per heading, at every `--detail`
+  level. `akm show <ref> --detail brief` is the outline without the body, and
+  every `slug` selects its section with `akm show <ref>#<slug>`, repeated
+  headings included. The outline is read from the file the section is cut
+  from. Fragment shows, non-Markdown assets and documents with no headings
+  carry no `toc`. The knowledge `action`, `akm show --help`, the unmatched
+  fragment error, `akm hints` and the OpenCode runtime's `akm_show` tool (which
+  takes `detail: "brief"`) now point agents at the outline first, then the
+  sections they need.
+
+### Changed
+
+- The Release workflow waits for CI on the commit it publishes, up to 25 minutes,
+  instead of failing when that run has not finished, so Release can be dispatched
+  right after the release commit is pushed. It still fails when CI failed or was
+  cancelled, and only the newest push or manual CI run counts: a pull request's
+  run tests a merge and, on a draft, skips the upgrade rehearsal.
+  `tests/release-check.sh` no longer repeats the upgrade rehearsal that CI runs on
+  the same commit.
+- `bun run check:ci` runs the pre-push check the way CI does (in a Docker
+  container with the Bun and Node versions `ci.yml` pins, a clean frozen install,
+  `CI=true` and four test shards); `.github/CONTRIBUTING.md` says when to run it.
+
+### Fixed
+
+- Two processes fetching the OpenCode binary akm's own runtime runs (or the local
+  embedder's ONNX Runtime files) into an empty cache at once no longer rename
+  their copies over each other (#1266). Each downloaded the package and renamed
+  its file into place, which unlinks a binary the other process is already
+  running (it then fails to start it again). One fetch now runs per cache
+  directory at a time, under a `fetch.lock` file in it (a dead holder's lock is
+  reclaimed); a process that finds the files in place once it holds the lock
+  downloads nothing, and a rename never replaces a file that is already whole.
+- `akm health`'s `plugin-version` advisory no longer reports a Claude Code
+  plugin on the `next` channel as stale against the 0.9 stable release. It read
+  the newest version with a semver rule that skips every prerelease. It now reads
+  the channel the marketplace clone follows: on `next`, the release tag on that
+  branch's head; on the default branch, the newest stable tag; on a marketplace
+  added at a tag, that tag.
+- When `crontab -l` cannot read the crontab spool (permission denied) in a
+  process started with no-new-privileges (an agent sandbox, a container, systemd
+  `NoNewPrivileges=`), akm says why: `crontab` reads the spool through its setgid
+  (or setuid) bit, which such a process does not grant. `akm health` and
+  `akm task` commands run from such a process used to repeat a bare
+  `fopen: Permission denied`. A refusal without no-new-privileges is reported as
+  before.
+- `akm health`'s `opencode-plugin-version` advisory reads the OpenCode 1 plugin
+  cache of the spec the global OpenCode config names (#1265). It read only
+  `packages/akm-opencode`, but OpenCode 1 caches each spec in its own folder, so
+  a host with `"plugin": ["akm-opencode@next"]` (cached in
+  `packages/akm-opencode@next`) showed no row at all. It now reads the one folder
+  of the spec under `plugin`: a bare name is `akm-opencode@latest`, as
+  `akm upgrade` reads it, and `akm-opencode@next` is its own folder. A version
+  pin (`akm-opencode@<version>`) is reported as pinned, with no staleness
+  verdict. With no entry, or no folder for it, the check reads
+  `packages/akm-opencode` as before; other cached specs are not scanned.
+
+### Security
+
+- Zod moves from 3.25.76 to 4.6.7 (`zod` `^4.6.6`), closing GHSA-mrhx-c7xc-m3w5 /
+  CVE-2023-54404 (high): Zod before 4.6.6 can exhaust memory validating a large array,
+  and no Zod 3 release has the fix. akm validates its config files with Zod. Visible
+  changes: an integer above 2^53 - 1 in a config file is now rejected; validation
+  messages are Zod 4's (an unknown enum value reads `Invalid option: expected one of ...`);
+  `schemas/akm-config.json` is generated with `z.toJSONSchema` (the `zod-to-json-schema`
+  dev dependency is gone): `additionalProperties: true` is written `{}` (the same), integers
+  state the new `maximum: 9007199254740991`, and every map states its `propertyNames`.
+
+## [0.10.261015] - 2026-10-27
+
+### Changed
+
+- `akm setup` downloads what the configuration it saves needs (#1254). Choosing the
+  built-in embedder (`--embedding local`, or the wizard's choice) downloads ONNX
+  Runtime 1.24.3 for this platform once from the npm registry (about 86 MB,
+  checked against the registry's sha512 integrity before anything is extracted)
+  into `<cache dir>/onnxruntime/<version>-<platform>-<arch>/`, and the model
+  (about 127 MB), then loads both. The wizard asks first, as before; `--yes`
+  and `--from` do it once the config is saved and report `semanticAssets`
+  (`ready`, `blocked: <reason>`, or `skipped`). `--no-probe` now means nothing
+  is contacted or downloaded; the first `akm index` downloads what setup did
+  not, which is also how an install upgraded from an earlier release gets the
+  runtime: its next `akm index` downloads it once. The vectors are unchanged,
+  so no re-index is needed.
+- Local embeddings are offered on Linux x64 (glibc) and Apple-silicon
+  macOS (#1256). Every other platform uses keyword search or an embedding endpoint:
+  setup offers only those, with one sentence saying why, `--embedding local`
+  warns and saves keyword search, `--from` keeps the file's values, the index
+  reports semantic search unavailable for the platform, and `akm health` warns
+  with the setup arguments for keyword search or an endpoint.
+- When agent work runs on akm's own runtime, the setup wizard offers to download
+  its OpenCode binary now rather than on the first agent run. `--yes` and
+  `--from` leave it to the first run.
+- The npm package installs with no install script anywhere in its tree (#1255), so it
+  works as installed where npm runs none (npm 12 blocks dependency scripts by
+  default). On Node, the SQLite driver is `better-sqlite3` 13.0.3, which ships
+  prebuilt N-API bindings for Linux (glibc and musl) and macOS on x64 and arm64
+  and for Windows on x64 and arm64: a Node upgrade no longer needs
+  `npm rebuild`. 32-bit ARM Linux has no SQLite binding on Node.
+- Standalone binaries carry no native code and are up to 36 MB smaller (Linux
+  x64: 123.6 MB to 88.0 MB). A `noexec` temp directory no longer affects
+  semantic search (#1257); akm's cache directory must still allow executing files.
+
+### Removed
+
+- The `onnxruntime-node` dependency, and with it the install script that
+  downloaded about 317 MB of CUDA providers on every Linux x64 `npm install`
+  (akm uses the CPU only; #1254). akm loads that package's binding from its cache
+  instead.
+- The `preinstall` Node.js version check (#1255). Both launchers and the CLI still
+  refuse Node.js older than 22 when akm starts, and npm warns from
+  `engines.node` at install.
+
 ## [0.10.261014] - 2026-10-27
 
 ### Added

package/README.md

@@ -40,14 +40,13 @@ 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).
+Local semantic search runs its embedding model on ONNX Runtime and is offered on
+Linux x64 (glibc) and Apple-silicon macOS; every other platform uses
+keyword search or an embedding endpoint. Choosing it in `akm setup`
+(`--embedding local`) downloads the runtime (about 86 MB) and the model (about
+127 MB) once into akm's cache: installing the package runs no install script and
+downloads nothing native. See
+[Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/#local-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

package/SECURITY.md

@@ -104,6 +104,6 @@ for assets containing secrets or private notes.
   runtime-free. This is a compatibility limitation, not a security risk.
 - **Workflows can read any file the akm process can read.** This is not a
   bug — see "Threat model" above.
-- **Installing `akm-cli` runs the preinstall hook.** The hook only validates
-  the runtime version and exits non-zero when it is unsupported; it does not
-  phone home or write outside the install directory.
+- **Installing `akm-cli` runs no install script.** Neither `akm-cli` nor any
+  package it depends on declares one. The Node.js version is checked when akm
+  starts, not when it installs.

package/STABILITY.md

@@ -201,7 +201,8 @@ enumeration of the whole `proposal` noun group.
   - `#fragment` is **input-only** and never stored. On markdown-document items
     the core resolves it as a section selector — `akm show <ref>#<heading-slug>`
     returns that one section, no fragment returns the whole item, and an
-    unmatched fragment lists the available slugs. Elsewhere it is an
+    unmatched fragment lists the available slugs. A whole document's `show`
+    carries `toc`, every heading with the slug that selects it. Elsewhere it is an
     adapter-owned selector opaque to the core. See
     [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md).
   - **Refs in prose** must be fully qualified (`bundle//conceptId`) or a native

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

@@ -49,7 +49,9 @@ akm curate "review architecture" --type workflow # Restrict to one asset type
 ## Show
 
 Display an asset by ref from the local index and materialized bundle files only.
-On a markdown document `#fragment` selects one section by heading slug.
+On a markdown document `#fragment` selects one section by heading slug. For a
+large document, `akm show <ref> --detail brief` returns its outline (`toc`, no
+body); then `akm show <ref>#<slug>` reads only the sections you need.
 
 ```sh
 akm show scripts/deploy.sh                    # Show script (returns run command)
@@ -57,9 +59,9 @@ akm show skills/code-review                   # Show skill (returns full content
 akm show commands/release                     # Show command (returns template)
 akm show agents/architect                     # Show agent (returns system prompt)
 akm show workflows/ship-release               # Show parsed workflow steps
-akm show knowledge/guide                      # Whole document
+akm show knowledge/guide                      # Whole document, plus its `toc`
+akm show knowledge/guide --detail brief       # Outline only: `toc` (level, text, slug, startLine), no body
 akm show knowledge/guide#auth                 # Just the "Auth" section
-akm show knowledge/guide#nope                 # Lists the available fragment slugs
 akm show knowledge/my-doc                     # Show materialized local content
 ```
 
@@ -69,7 +71,7 @@ akm show knowledge/my-doc                     # Show materialized local content
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description`, `parameters` |
 | agent | `prompt`, `description`, `modelHint` |
-| knowledge | `content` (whole document, or one section via `#fragment`) |
+| knowledge | `content` (whole document, or one section via `#fragment`); `toc` (each heading's `slug`) on a whole document |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
 | env | `keys` (key names only — values and comment text never returned) |

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

@@ -6,7 +6,7 @@ You have access to a searchable library of scripts, skills, commands, agents, kn
 
 For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
-2. `akm show <ref>` — read the schema (field names and structure)
+2. `akm show <ref>` — read the schema (field names and structure). For a large document, `akm show <ref> --detail brief` returns its outline (`toc`, no body); then `akm show <ref>#<slug>` reads only the sections you need.
 3. Edit the workspace file using schema field names + task-specific values from your README
 4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite). Record negative feedback only when the asset's content is wrong or stale, and say what is wrong and what it should say. `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. A note that simply did not fit your task is not negative feedback: record nothing for it. Once you have verified the correct fact, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A note that is outdated can be marked with `--outdated`, or `--superseded-by <ref>` when another note replaces it. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
@@ -27,6 +27,8 @@ akm search "<query>" --type workflow          # Filter to workflow assets
 akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
+akm show <ref> --detail brief                 # Outline only: a document's `toc` (each heading's slug), no body
+akm show <ref>#<slug>                         # One section of a document
 akm help <command>                            # Show a command's options and subcommands
 akm workflow run <ref>                        # Start a new run and execute it
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
@@ -58,7 +60,7 @@ akm search "<query>" --from registry          # Search all registries (registry
 | skill | Instructions to follow (read the full content) |
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
-| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
+| knowledge | A reference doc; `toc` lists its sections and `<ref>#<slug>` reads one |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
 | env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |

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

@@ -6,11 +6,11 @@
 // 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.
+//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`
+//     (`--detail brief` when akm_show asks for a document's outline). 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.
@@ -59,8 +59,16 @@ const TOOLS = [
     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"] },
+    description:
+      'Read one akm asset by its ref, as returned by akm_curate or akm_search. For a large document, call it with detail "brief" for its outline (toc, no body), then with ref#<slug> for only the sections you need.',
+    input: {
+      type: "object",
+      properties: {
+        ref: { type: "string" },
+        detail: { type: "string", enum: ["brief"], description: "brief: the outline (toc) without the body" },
+      },
+      required: ["ref"],
+    },
   },
 ];
 
@@ -78,7 +86,7 @@ function cliArguments(tool, input) {
     ...(type && tool.positional !== "ref" ? ["--type", type] : []),
     ...(limit && tool.positional !== "ref" ? ["--limit", limit] : []),
     "--detail",
-    "agent",
+    tool.positional === "ref" && input?.detail === "brief" ? "brief" : "agent",
     "--format",
     "json",
   ];

package/dist/assets/prompts/workflow-unit-preamble.md

@@ -9,7 +9,9 @@ Ground rules for this unit:
 
 1. Pull knowledge on demand instead of guessing: `akm search '<query>'` to find
    relevant assets, `akm show <ref>` to read one, `akm curate '<query>'` to let
-   akm select the best match. Only pull what this unit actually needs.
+   akm select the best match. Only pull what this unit actually needs: for a
+   large document, `akm show <ref> --detail brief` returns its outline (`toc`,
+   no body), then `akm show <ref>#<slug>` reads one section.
 2. Environment values and secrets are provided through your process
    environment when the workflow declares them. Never print secret values to
    stdout or embed them in your answer. If you need an env file path, use

package/dist/cli.js

@@ -178,7 +178,7 @@ const setupCommand = defineCommand({
         },
         embedding: {
             type: "string",
-            description: "Embeddings: a model the connection serves, local (the built-in embedder), or off",
+            description: "Embeddings: a model the connection serves, local (the built-in embedder, on the platforms that have it; its runtime and model are downloaded now), or off",
         },
         "embedding-endpoint": {
             type: "string",
@@ -218,7 +218,7 @@ const setupCommand = defineCommand({
         // declaring `no-probe` is what puts the flag in `--help` and keeps the unknown-flag check from refusing it.
         "no-probe": {
             type: "boolean",
-            description: "Offline run: the endpoint is not contacted and its models are not listed. A connection added this way has no model until one is named with `akm models set`; the picks it already has are kept.",
+            description: "Offline run: nothing is contacted or downloaded. The endpoint's models are not listed, so a connection added this way has no model until one is named with `akm models set` (the picks it already has are kept), and the local embedder's runtime and model are fetched by the first `akm index`.",
         },
     },
     async run({ args }) {

package/dist/commands/health/plugin-staleness.js

@@ -35,7 +35,7 @@
  * local marketplace clone is not proof of what is newest upstream — the
  * incident above involved a clone that hadn't seen the fix's tag at all — so
  * the only way to ever detect drift is to ask the remote what tags exist.
- * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
+ * That query is a `git ls-remote --symref` (lists refs; fetches nothing,
  * writes nothing) with a short timeout, and any failure (offline, no
  * remote, timeout) degrades to "installed version reported, no staleness
  * claim" rather than a false positive or a hang. Like `cli-version`, this
@@ -54,7 +54,8 @@ import os from "node:os";
 import path from "node:path";
 import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
 import { opencodeCacheDir } from "../../integrations/harnesses/opencode/roots.js";
-import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+import { highestVersion, isExactSemver, isPrerelease, isSemverRange, satisfiesRange } from "../../registry/semver.js";
+import { openCodeConfigSpec } from "../sources/plugin-upgrade.js";
 /**
  * Root directory holding Claude Code's plugin cache + marketplace clones.
  * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
@@ -78,12 +79,26 @@ function defaultOpencodeCacheRoot() {
 }
 const OPENCODE_PLUGIN_LOCATIONS = [
     {
-        // OpenCode 1: <cache>/packages/akm-opencode/node_modules/akm-cli (the folder read since this check began).
+        // OpenCode 1: <cache>/packages/<spec>/node_modules/akm-cli, the one spec the global config names (#1265).
         flavor: OPENCODE_V1,
         advisory: "opencode-plugin-version",
         label: "OpenCode's",
         remedy: "update the OpenCode plugin",
-        folders: (cacheRoot) => [{ folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(OPENCODE_V1.pkg)) }],
+        folders: (cacheRoot) => {
+            // OpenCode caches each spec in its own folder, and a bare name is its `@latest`, as `akm upgrade` reads it. With
+            // no config entry, or no folder for the spec, the bare `packages/akm-opencode` is read, as this check always has.
+            const { pkg } = OPENCODE_V1;
+            const bare = { folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(pkg)) };
+            const named = openCodeConfigSpec(OPENCODE_V1)?.spec;
+            if (named === undefined)
+                return [bare];
+            const spec = named === pkg ? `${pkg}@latest` : named;
+            const folder = path.join(cacheRoot, OPENCODE_V1.cacheFolder(spec));
+            if (!fs.existsSync(folder))
+                return [bare];
+            const version = spec.slice(pkg.length + 1);
+            return [{ spec, folder, ...(isExactSemver(version) ? { pinned: version } : {}) }];
+        },
     },
     {
         // OpenCode 2: <cache>/npm/akm-opencode-v2@<spec>/<epoch-ms>/node_modules/akm-cli, newest build per spec.
@@ -110,11 +125,11 @@ const OPENCODE_PLUGIN_LOCATIONS = [
  */
 function findBundledAkm(plugin, cacheRoot) {
     const found = [];
-    for (const { spec, folder } of plugin.folders(cacheRoot)) {
+    for (const { spec, pinned, folder } of plugin.folders(cacheRoot)) {
         const nodeModules = plugin.flavor.nodeModulesDir(folder);
         const version = nodeModules && readPackageVersion(path.join(nodeModules, "akm-cli", "package.json"));
         if (version !== undefined)
-            found.push(spec ? { spec, version } : { version });
+            found.push({ ...(spec ? { spec } : {}), ...(pinned ? { pinned } : {}), version });
     }
     return found;
 }
@@ -122,6 +137,17 @@ function buildOpencodeBundledAdvisory(plugin, bundled, cliVersion) {
     const bundledVersion = bundled.version;
     const stale = bundledVersion !== cliVersion;
     const where = bundled.spec ? ` (${bundled.spec})` : "";
+    if (bundled.pinned) {
+        // The config chose this build: there is nothing to update it to, so no staleness verdict.
+        return {
+            name: plugin.advisory,
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `${plugin.label} plugin is pinned to v${bundled.pinned}${where}; its bundled akm-cli is v${bundledVersion}, and a pinned plugin is not compared with the running CLI v${cliVersion}.`,
+            evidence: { bundledVersion, cliVersion, spec: bundled.spec, pinnedVersion: bundled.pinned },
+        };
+    }
     return {
         name: plugin.advisory,
         kind: "deterministic",
@@ -161,7 +187,7 @@ function detectInstalledPlugins(pluginsRoot) {
         }
         if (versions.length === 0)
             continue;
-        const latest = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        const latest = highestVersion(versions);
         if (!latest)
             continue;
         const versionDir = path.join(pluginDir, latest);
@@ -204,16 +230,31 @@ function readVersionRange(pluginDir) {
 }
 const LS_REMOTE_TIMEOUT_MS = 5_000;
 /**
- * `git ls-remote --tags origin` against the marketplace clone's configured
- * remote — lists refs only, fetches no objects, writes no local refs.
- * Returns `undefined` (never throws) when the directory is not a git
- * checkout, has no `origin` remote, or the command fails/times out (e.g.
- * offline) — all "cannot determine availability", not "up to date".
+ * `git ls-remote --symref origin` against the marketplace clone's configured remote (lists refs only, fetches no
+ * objects, writes no local refs), read for the channel the clone follows:
+ *
+ * - **The remote's default branch** (stable): every stable release tag; the newest is the highest of them.
+ * - **Any other branch** (a channel such as `next`): the release tags on that branch's head. A channel branch is
+ *   reset to each build it publishes, so its head IS the newest build of the channel, whatever semver order says
+ *   about other tags (retired build schemes can sort above current builds).
+ * - **No branch** (a marketplace added at a tag ref, which Claude Code clones detached): the release tag the clone
+ *   is pinned to. A pinned marketplace never offers anything newer, so `claude plugin update` could not act on a
+ *   newer tag elsewhere. A detached clone at an untagged commit reads like the default branch.
+ *
+ * Returns `undefined` (never throws) when the directory is not a git checkout, has no `origin` remote, or the
+ * command fails/times out (e.g. offline): all "cannot determine availability", not "up to date". A channel head
+ * with no release tag returns `[]`, which reads the same way.
  */
 const realListRemoteTags = (marketplaceDir) => {
     let result;
+    let branch;
     try {
-        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+        branch =
+            spawnSync("git", ["-C", marketplaceDir, "branch", "--show-current"], {
+                encoding: "utf8",
+                timeout: LS_REMOTE_TIMEOUT_MS,
+            }).stdout?.trim() ?? "";
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--symref", "origin"], {
             encoding: "utf8",
             timeout: LS_REMOTE_TIMEOUT_MS,
         });
@@ -223,16 +264,39 @@ const realListRemoteTags = (marketplaceDir) => {
     }
     if (result.status !== 0 || !result.stdout)
         return undefined;
-    const tags = result.stdout
+    const refs = result.stdout
         .split("\n")
         .map((line) => line.trim())
         .filter(Boolean)
-        .map((line) => line.split("\t")[1])
-        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
-        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
-        .map((tag) => tag.replace(/^v/, ""))
-        .filter(isExactSemver);
-    return [...new Set(tags)];
+        .map((line) => line.split("\t"));
+    const defaultBranch = refs
+        .find(([value, name]) => name === "HEAD" && value?.startsWith("ref: refs/heads/"))?.[0]
+        ?.replace(/^ref: refs\/heads\//, "");
+    const tags = refs
+        .filter(([, name]) => typeof name === "string" && name.startsWith("refs/tags/"))
+        .map(([sha, name]) => ({
+        sha: sha,
+        version: name
+            .replace(/^refs\/tags\//, "")
+            .replace(/\^\{\}$/, "")
+            .replace(/^v/, ""),
+    }))
+        .filter((tag) => isExactSemver(tag.version));
+    const tagsAt = (sha) => [
+        ...new Set(tags.filter((tag) => tag.sha === sha).map((tag) => tag.version)),
+    ];
+    const onChannelBranch = branch !== "" && defaultBranch !== undefined && branch !== defaultBranch;
+    if (onChannelBranch)
+        return tagsAt(refs.find(([, name]) => name === `refs/heads/${branch}`)?.[0]);
+    if (branch === "") {
+        const pinned = tagsAt(spawnSync("git", ["-C", marketplaceDir, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        }).stdout?.trim());
+        if (pinned.length > 0)
+            return pinned;
+    }
+    return [...new Set(tags.map((tag) => tag.version).filter((version) => !isPrerelease(version)))];
 };
 /**
  * Build one `plugin-version` advisory per detected `akm` harness plugin,
@@ -263,14 +327,14 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     let availableVersion;
     try {
         const tags = probe && fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
-        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+        availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
     }
     catch {
         availableVersion = undefined;
     }
     const stale = availableVersion !== undefined &&
         plugin.version !== availableVersion &&
-        maxSatisfying([plugin.version, availableVersion], "*") === availableVersion;
+        highestVersion([plugin.version, availableVersion]) === availableVersion;
     // Point 3: does the plugin's own declared range admit the running CLI?
     const versionRange = readVersionRange(plugin.pluginDir);
     const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);

package/dist/commands/health/semantic-search-check.js

@@ -62,10 +62,10 @@ export function semanticSearchCheck(state) {
     const asOf = builtAt ? ` at the last index (${builtAt})` : " at the last index";
     switch (record.status) {
         case "unavailable":
-            // No native library for this platform is not something to fix: keyword search is the healthy state there.
+            // No local embeddings on this platform is not something to fix: keyword search or a remote endpoint is the default there.
             return record.unavailable === "platform"
                 ? result("warn", `Semantic search is unavailable on this platform: ${record.reason} ` +
-                    'Set semanticSearchMode to "off", or embedding.endpoint to a remote embedding service.', evidence)
+                    "For keyword search run `akm setup --embedding off`; for a remote endpoint, `akm setup --embedding <model> --embedding-endpoint <url>`.", evidence)
                 : result("fail", `Semantic search was unavailable on this machine${asOf}: ${record.reason}`, evidence);
         case "blocked":
             return result("fail", `Semantic search was blocked${asOf}: ${record.reason}`, evidence);

package/dist/commands/read/search-cli.js

@@ -177,7 +177,7 @@ function rejectExtraShowPositionals(positionals, ref) {
     if (extra.length === 0)
         return;
     throw new UsageError(`akm show takes a single ref, but got ${extra.map((token) => `"${token}"`).join(" ")} after "${ref}". ` +
-        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
+        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", `Run \`akm show ${ref} --detail brief\` for the document's outline (\`toc\`, no body).`);
 }
 export const showCommand = defineJsonCommand({
     meta: {
@@ -187,7 +187,7 @@ export const showCommand = defineJsonCommand({
     args: {
         ref: {
             type: "positional",
-            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug, and an unmatched fragment lists the available slugs. Example: `akm show knowledge/guide.md#auth`.",
+            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug; `--detail brief` returns the outline (`toc`, each heading's slug) without the body. Example: `akm show knowledge/guide.md#auth`.",
             required: true,
         },
         filter: {

package/dist/commands/read/show.js

@@ -20,7 +20,7 @@ import { recognizeMatch } from "../../core/adapter/recognize-match.js";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
+import { extractSection, markdownFragmentSlugs, markdownToc } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
 import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
@@ -297,8 +297,10 @@ export async function showLocal(input) {
     const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
     let response;
+    let markdown = false;
     try {
         if (indexedRenderer === null) {
+            markdown = path.extname(assetPath).toLowerCase() === ".md";
             response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragmentContent);
         }
         else {
@@ -315,8 +317,9 @@ export async function showLocal(input) {
             const renderDefaultBundle = config.defaultBundle ?? (source?.isDefault === true ? renderBundle : undefined);
             const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, renderBundle, renderDefaultBundle);
             response = renderer.buildShowResponse(renderCtx);
+            markdown = match.renderer.endsWith("-md");
             if (parsed.fragment !== undefined) {
-                if (!match.renderer.endsWith("-md")) {
+                if (!markdown) {
                     warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
                 }
                 else {
@@ -324,6 +327,13 @@ export async function showLocal(input) {
                 }
             }
         }
+        // The outline is read from the bytes `#<slug>` resolves against, so every
+        // listed slug selects its section even when the index is stale.
+        if (markdown && parsed.fragment === undefined) {
+            const toc = markdownToc(fileCtx.content());
+            if (toc.length > 0)
+                response.toc = toc;
+        }
     }
     catch (error) {
         throwIndexedPathNotFound(error, input.ref);
@@ -598,6 +608,7 @@ function applyMarkdownResponsePayload(response, content) {
     else
         response.content = content;
 }
+const SHOW_OUTLINE_HINT = "Run `akm show <ref> --detail brief` for the document's outline (`toc`, no body), then `akm show <ref>#<slug>` for one section.";
 function requireMarkdownSection(content, fragment, name) {
     const section = extractSection(content, fragment);
     if (section)
@@ -609,7 +620,7 @@ function requireMarkdownSection(content, fragment, name) {
     }
     const available = markdownFragmentSlugs(content);
     throw new NotFoundError(`Fragment "#${fragment}" not found in ${name}.` +
-        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""));
+        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""), "ASSET_NOT_FOUND", SHOW_OUTLINE_HINT);
 }
 /**
  * Build a reduced brief response from a full ShowResponse.
@@ -625,6 +636,7 @@ function buildBriefResponse(full, assetPath) {
         ...(summary.ref ? { ref: summary.ref } : {}),
         ...(summary.description ? { description: summary.description } : {}),
         ...(summary.action ? { action: summary.action } : {}),
+        ...(full.toc ? { toc: full.toc } : {}),
         ...(summary.run ? { run: summary.run } : {}),
         ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),

package/dist/core/asset/markdown.js

@@ -16,6 +16,15 @@ export function markdownHeadingSlug(heading) {
 export function markdownFragmentSlugs(content) {
     return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
 }
+/**
+ * The headings `extractSection` can select, with the slug it resolves each by.
+ * A heading with no sluggable text has no selector, so it is left out.
+ */
+export function markdownToc(content) {
+    const headings = parseMarkdownToc(content).headings;
+    const slugs = uniqueHeadingSlugs(headings);
+    return headings.flatMap((heading, index) => slugs[index] ? [{ level: heading.level, text: heading.text, slug: slugs[index], startLine: heading.line }] : []);
+}
 /** One slug per heading, in order; a heading with no sluggable text gets "". */
 export function uniqueHeadingSlugs(headings) {
     const used = new Set();