akm-cli 0.10.261014-beta → 0.10.261016-beta

package/dist/setup/semantic-assets.js

@@ -2,14 +2,16 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Semantic-search asset preparation for the setup wizard. The embedding
- * runtime (onnxruntime-node) is a normal package dependency; setup never
- * mutates the installed CLI. This module only prepares the model.
+ * Semantic-search asset preparation for setup. For the built-in local embedder
+ * that is its runtime (onnxruntime-node's binding and library) and its model,
+ * both fetched into akm's cache; for an embedding endpoint, a check that it
+ * answers.
  */
 import * as p from "../cli/clack.js";
 import { isHttpUrl } from "../core/common.js";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL } from "../llm/embedder.js";
 import { effectiveEmbedding } from "../llm/embedders/connection.js";
+import { ONNXRUNTIME_VERSION } from "../llm/embedders/onnx-runtime.js";
 // Approximate first-download size of the default local model (DEFAULT_LOCAL_MODEL), used in the setup note.
 const LOCAL_MODEL_APPROX_SIZE_MB = 127;
 export function isRemoteEmbeddingConfig(embedding) {
@@ -23,7 +25,8 @@ export function describeSemanticSearchAssets(embedding) {
         return [`• Embedding endpoint: ${embedding?.provider ?? "custom"} / ${embedding?.model} (no local model download)`];
     }
     return [
-        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download on first use)`,
+        `• ONNX Runtime ${ONNXRUNTIME_VERSION}, the local embedder's runtime (~86 MB download, once)`,
+        `• Local embedding model: ${embedding?.localModel ?? DEFAULT_LOCAL_MODEL} (~${LOCAL_MODEL_APPROX_SIZE_MB} MB download, once)`,
     ];
 }
 export async function prepareSemanticSearchAssets(config) {
@@ -32,7 +35,7 @@ export async function prepareSemanticSearchAssets(config) {
     const spin = p.spinner();
     spin.start(remote
         ? "Checking remote embedding endpoint..."
-        : `Downloading local embedding model (${embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
+        : `Downloading the local embedder's runtime and model (${embedding?.localModel ?? DEFAULT_LOCAL_MODEL})...`);
     const result = await checkEmbeddingAvailability(embedding);
     if (!result.available) {
         spin.stop("Semantic-search assets could not be prepared.");
@@ -50,6 +53,6 @@ export async function prepareSemanticSearchAssets(config) {
             return { ok: false, reason: "local-model-download", message: result.message };
         }
     }
-    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedding model downloaded and ready.");
+    spin.stop(remote ? "Remote embedding endpoint is ready." : "Local embedder's runtime and model downloaded and ready.");
     return { ok: true };
 }

package/dist/setup/setup.js

@@ -19,7 +19,9 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import * as p from "../cli/clack.js";
 import { akmInit } from "../commands/sources/init.js";
+import { targetRows } from "../commands/targets.js";
 import { deriveBundleIds } from "../core/bundle-id.js";
+import { toErrorMessage } from "../core/common.js";
 import { bundleEntryToSourceEntry, DEFAULT_CONFIG, defaultConnection, loadUserConfig, mutateConfigWithPrecommit, parseAndValidateConfigText, primaryBundlePath, validateCompleteConfig, } from "../core/config/config.js";
 import { readConfigText } from "../core/config/config-io.js";
 import { listTopLevelConfigKeys } from "../core/config/config-schema.js";
@@ -30,6 +32,8 @@ import { getConfigPath, getDefaultStashDir, isTransientStashPath } from "../core
 import { warn, warnOnce } from "../core/warn.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { readLockfile } from "../integrations/lockfile.js";
+import { checkEmbeddingAvailability } from "../llm/embedder.js";
+import { effectiveEmbedding } from "../llm/embedders/connection.js";
 import { detectEnvironment, renderDetectionSummary } from "./detect.js";
 import { bail, prompt } from "./prompt.js";
 import { prepareSemanticSearchAssets } from "./semantic-assets.js";
@@ -305,6 +309,50 @@ function finalizeSetupDraft(draft) {
         delete finalized.defaultBundle;
     return finalized;
 }
+/** Where a process of `config` runs, as `akm info` and `akm health` say it. */
+function processRow(config, process) {
+    return targetRows({ config }).find((row) => row.type === "process" && row.process === process);
+}
+/**
+ * What `--yes` and `--from` do for local embeddings once the config is saved: fetch the local embedder's runtime and
+ * model and load them. Undefined when the saved config does not embed locally.
+ */
+async function prepareLocalEmbeddings(config, noProbe) {
+    if (processRow(config, "embedding")?.kind !== "local")
+        return undefined;
+    if (noProbe)
+        return "skipped";
+    const result = await checkEmbeddingAvailability(effectiveEmbedding(config));
+    if (result.available)
+        return "ready";
+    warn(`[akm setup] Semantic search is blocked: ${result.message}`);
+    return `blocked: ${result.message}`;
+}
+/** The wizard's offer to fetch what akm's own agent runtime runs, when the saved config runs agent work there. */
+async function offerAgentRuntimeFetch(config) {
+    if (processRow(config, "agents")?.kind !== "connection")
+        return;
+    const { agentRuntime } = await import("../integrations/agent/runtime.js");
+    const pending = agentRuntime.pendingFetch();
+    if (pending === undefined)
+        return;
+    const fetchNow = await prompt(() => p.confirm({
+        message: `Agent work runs on akm's own runtime. Fetch ${pending} for it now, rather than on the first agent run?`,
+        initialValue: true,
+    }));
+    if (!fetchNow)
+        return;
+    const spin = p.spinner();
+    spin.start(`Fetching ${pending}...`);
+    try {
+        await agentRuntime.fetch();
+        spin.stop("akm's own agent runtime is ready.");
+    }
+    catch (error) {
+        spin.stop("akm's own agent runtime could not be fetched.");
+        p.log.warn(`${toErrorMessage(error)}\nThe first agent run tries again.`);
+    }
+}
 const NOTHING_DETECTED = {
     harnesses: [],
     localServers: [],
@@ -538,6 +586,8 @@ export async function runSetupWizard(opts) {
     // Non-interactive setup paths never reach this interactive-only step.
     p.log.step("Scheduled Tasks");
     await stepScheduledTasks();
+    if (opts?.noProbe !== true)
+        await offerAgentRuntimeFetch(savedConfig);
     if (semanticSearchMode.mode === "auto") {
         if (semanticSearchMode.prepareAssets) {
             const ready = await prepareSemanticSearchAssets(savedConfig);
@@ -624,12 +674,13 @@ export async function runSetupWithDefaults(opts) {
     const { config, credentials } = await applyNonInteractiveDefaults(current, stashDir, opts);
     const finalConfig = finalizeSetupDraft(config);
     validateCompleteConfig(finalConfig);
-    const { precommit: initResult } = await saveSetupConfig(current, finalConfig, async () => {
+    const { config: savedConfig, precommit: initResult } = await saveSetupConfig(current, finalConfig, async () => {
         storeCredentials(credentials);
         if (opts.noInit)
             return undefined;
         return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
     });
+    const semanticAssets = await prepareLocalEmbeddings(savedConfig, opts.noProbe);
     return {
         configPath: getConfigPath(),
         bundleDir: stashDir,
@@ -637,6 +688,7 @@ export async function runSetupWithDefaults(opts) {
         written: true,
         fields: Object.keys(finalConfig).filter((k) => finalConfig[k] !== undefined),
         runs: describeRuns(finalConfig),
+        ...(semanticAssets ? { semanticAssets } : {}),
     };
 }
 /**
@@ -736,12 +788,13 @@ export async function runSetupFromConfig(opts) {
     const finalizedMerged = finalizeSetupDraft(merged);
     // Reject an invalid merged config before touching the stash.
     validateCompleteConfig(finalizedMerged);
-    const { precommit: initResult } = await saveSetupConfig(current, finalizedMerged, async () => {
+    const { config: savedConfig, precommit: initResult } = await saveSetupConfig(current, finalizedMerged, async () => {
         storeCredentials(credentials);
         if (opts.noInit)
             return undefined;
         return akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
     });
+    const semanticAssets = await prepareLocalEmbeddings(savedConfig, opts.noProbe);
     return {
         configPath: getConfigPath(),
         bundleDir: stashDir,
@@ -749,6 +802,7 @@ export async function runSetupFromConfig(opts) {
         written: true,
         fields: Object.keys(incoming).filter((k) => incoming[k] !== undefined),
         runs: describeRuns(finalizedMerged),
+        ...(semanticAssets ? { semanticAssets } : {}),
     };
 }
 // ── Setup --from <file> bootstrap helper ────────────────────────────────────

package/dist/setup/steps/embeddings.js

@@ -3,7 +3,10 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Setup step 4: embeddings. A model the connection serves, akm's built-in local
- * embedder, another endpoint, or off (which is semantic search off).
+ * embedder, another endpoint, or off (which is semantic search off). The local
+ * embedder is offered only where akm has local embeddings
+ * (`llm/embedders/onnx-runtime.ts`); everywhere else the choice is an endpoint
+ * or keyword search.
  */
 import * as p from "../../cli/clack.js";
 import { defaultConnection, } from "../../core/config/config.js";
@@ -11,6 +14,7 @@ import { apiKeyReference, resolveApiKey, storedCredential } from "../../core/con
 import { sameEndpoint } from "../../core/endpoint-url.js";
 import { UsageError } from "../../core/errors.js";
 import { redactUrlCredentials } from "../../core/redaction.js";
+import { hasLocalEmbeddings, noLocalEmbeddingsReason } from "../../llm/embedders/onnx-runtime.js";
 import { isEmbeddingModel } from "../../llm/model-list.js";
 import { prompt } from "../prompt.js";
 import { describeSemanticSearchAssets, isRemoteEmbeddingConfig } from "../semantic-assets.js";
@@ -45,6 +49,10 @@ function warnOfDroppedKey(current, endpoint, keyGiven, interactive) {
 }
 function fromFlags(input) {
     const { flags } = input;
+    if (flags.embedding === "local" && !hasLocalEmbeddings()) {
+        warnUser(`${noLocalEmbeddingsReason()} --embedding local is ignored: semantic search stays off.`, false);
+        return { kind: "off" };
+    }
     if (flags.embedding === "off" || flags.embedding === "local")
         return { kind: flags.embedding };
     const model = flags.embedding;
@@ -81,9 +89,12 @@ async function askSource(input) {
     const hasServing = servingConnection(input) !== undefined;
     const heldModel = hasServing && current.embedding?.endpoint === undefined ? current.embedding?.model : undefined;
     const connectionModels = [...new Set([...(heldModel ? [heldModel] : []), ...served])];
+    const local = hasLocalEmbeddings();
+    if (!local)
+        p.log.info(noLocalEmbeddingsReason());
     const options = [
         ...connectionModels.map((model) => ({ value: `model:${model}`, label: model, hint: "served by the connection" })),
-        { value: "local", label: "Built-in local embedder", hint: "no server needed" },
+        ...(local ? [{ value: "local", label: "Built-in local embedder", hint: "no server needed" }] : []),
         { value: "endpoint", label: "Another endpoint" },
         { value: "off", label: "Off", hint: "keyword search only" },
     ];
@@ -93,7 +104,9 @@ async function askSource(input) {
             ? `model:${heldModel}`
             : served[0]
                 ? `model:${served[0]}`
-                : "local";
+                : local
+                    ? "local"
+                    : "off";
     const choice = await prompt(() => p.select({ message: "Which embedding source should akm use?", options, initialValue }));
     if (choice === "local" || choice === "off")
         return { kind: choice };
@@ -104,7 +117,7 @@ async function askSource(input) {
         ...(current.embedding?.endpoint ? { initialValue: current.embedding.endpoint } : {}),
     });
     if (endpoint === undefined)
-        return { kind: "local" };
+        return { kind: local ? "local" : "off" };
     // A key belongs to the endpoint it was given for, so the current one is offered for that endpoint alone.
     const unchangedEndpoint = current.embedding?.endpoint !== undefined && sameEndpoint(current.embedding.endpoint, endpoint);
     const held = unchangedEndpoint
@@ -141,6 +154,10 @@ export async function stepEmbeddings(input) {
         return { answer, semantic: { mode: "off", prepareAssets: false } };
     const after = embeddingAfter(input, answer);
     p.note(describeSemanticSearchAssets(after).join("\n"), "Semantic Search Assets");
+    if (!input.probe) {
+        p.log.info("Offline run: semantic search is not checked or prepared now; the first `akm index` does both.");
+        return { answer, semantic: { mode: "auto", prepareAssets: false } };
+    }
     const prepareAssets = await prompt(() => p.confirm({
         message: isRemoteEmbeddingConfig(after)
             ? "Check the embedding endpoint and verify semantic search now?"

package/dist/storage/database.js

@@ -125,66 +125,32 @@ function loadBunSqlite() {
 }
 let betterSqlite3Ctor;
 /**
- * The binding is absent or unbuildable — a toolchain/install problem.
+ * The package is missing, or it carries no binding for this platform. Its N-API
+ * bindings ship prebuilt in the package (see package.json → pinNotes), so neither
+ * a build toolchain nor the Node version decides whether it loads.
  */
-const MISSING_BINDING_REMEDY = "akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.\n" +
-    "  • Reinstall akm with a working C/C++ build toolchain so its optional\n" +
-    "    'better-sqlite3' native binding builds (a global `npm i -g better-sqlite3`\n" +
-    "    will NOT be resolved — Node loads it from akm's own node_modules).\n" +
-    "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native build.";
-/**
- * Recognize a binding built for a DIFFERENT Node ABI than the one now running,
- * and answer with the one command that fixes it.
- *
- * This is the most likely failure a real user hits, and it is not a broken
- * install: a native addon is compiled (or a prebuilt binary is selected) for
- * the Node major present at `npm install` time. Upgrade Node afterwards and the
- * same file no longer loads.
- *
- * It is matched rather than described because the symptom text varies and the
- * previous wording only named ONE of them. The prebuilt-binary path — which is
- * now the normal path, since better-sqlite3 is pinned to a version publishing a
- * prebuild for every supported Node (see package.json → pinNotes) — reports
- * `Module did not self-register`, saying nothing about versions at all. A
- * from-source build reports the explicit `NODE_MODULE_VERSION` mismatch. Asking
- * the user to decide which bullet applies is the step worth deleting.
- */
-export function abiMismatchRemedy(message) {
-    const ABI_MISMATCH_SHAPES = [
-        "did not self-register", // prebuilt binary for another ABI
-        "NODE_MODULE_VERSION", // explicit mismatch, from-source build
-        "was compiled against a different", // same, older phrasing
-        "invalid ELF header", // binary for another platform/arch entirely
-    ];
-    if (!ABI_MISMATCH_SHAPES.some((shape) => message.includes(shape)))
-        return undefined;
-    return ("akm could not load 'better-sqlite3': its native binding was built for a different\n" +
-        `Node.js version than the one now running (this Node is ABI ${process.versions.modules}).\n` +
-        "This is what happens when Node is upgraded after akm is installed. It is NOT a\n" +
-        "broken install, and reinstalling akm is not required.\n" +
-        "  Fix: npm rebuild better-sqlite3        # in akm's install directory\n" +
-        "  Or:  npm install -g akm-cli            # reinstall, rebuilding against this Node\n" +
-        "  Or:  run akm under Bun, whose built-in SQLite driver needs no native binding.");
+function missingBindingRemedy() {
+    return ("akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.\n" +
+        "  • Its package carries prebuilt bindings for Linux and macOS on x64 and arm64 and for\n" +
+        `    Windows on x64 and arm64; this machine is ${process.platform} ${process.arch}.\n` +
+        "  • Reinstall akm (`npm install -g akm-cli`) if the package is missing (a global\n" +
+        "    `npm i -g better-sqlite3` will NOT be resolved — Node loads it from akm's own node_modules).\n" +
+        "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native binding.");
 }
 function loadBetterSqlite3() {
     if (!betterSqlite3Ctor) {
         // Runtime-gated dynamic require: only reached when NOT on Bun, so Bun never
         // resolves or loads the optional `better-sqlite3` native dependency.
         // `better-sqlite3` is an optionalDependency, so `npm i` can succeed without
-        // it (or with a native build that failed). Convert the raw MODULE_NOT_FOUND
-        // into an actionable message instead of a cryptic onboarding crash.
+        // it. Convert the raw MODULE_NOT_FOUND into an actionable message instead of
+        // a cryptic onboarding crash.
         let mod;
         try {
             mod = nodeRequire("better-sqlite3");
         }
         catch (err) {
-            // An ABI mismatch does NOT arrive here — `require` succeeds and the
-            // failure lands at construction (see openNodeDatabase). This path is a
-            // genuinely absent or unresolvable module. `abiMismatchRemedy` is still
-            // consulted because a from-source build CAN fail at load with the
-            // explicit NODE_MODULE_VERSION message.
             const raw = err instanceof Error ? err.message : String(err);
-            throw new Error(`${abiMismatchRemedy(raw) ?? MISSING_BINDING_REMEDY}\n  Underlying load error: ${raw}`);
+            throw new Error(`${missingBindingRemedy()}\n  Underlying load error: ${raw}`);
         }
         betterSqlite3Ctor = mod.default ?? mod;
     }
@@ -201,23 +167,17 @@ function openNodeDatabase(path, opts) {
         options.readonly = opts.readonly;
     if (opts?.create === false)
         options.fileMustExist = true;
-    // Construction, not `require`, is where an ABI mismatch surfaces.
-    // `require("better-sqlite3")` SUCCEEDS against a binding built for another
-    // Node ABI — the package resolves its `.node` file lazily — so the loader's
-    // catch never sees this error and cannot explain it. Verified against a real
-    // ABI-127 binding under Node 24 (ABI 137): `require()` returned a function
-    // and `new Database(...)` threw. Wrapping the require alone left the most
-    // likely real-world failure reported as a bare Node internals message.
     let db;
     try {
         db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
     }
     catch (err) {
+        // The package loads its binding at the first construction, not at `require`, so a platform it carries no
+        // binding for fails here.
         const raw = err instanceof Error ? err.message : String(err);
-        const remedy = abiMismatchRemedy(raw);
-        if (!remedy)
+        if (!raw.includes("better_sqlite3.node"))
             throw err;
-        throw new Error(`${remedy}\n  Underlying error: ${raw}`);
+        throw new Error(`${missingBindingRemedy()}\n  Underlying error: ${raw}`);
     }
     return {
         prepare: db.prepare.bind(db),

package/dist/tasks/backends/cron.js

@@ -438,6 +438,15 @@ function readCrontab(exec) {
     const stderr = (result.stderr ?? "").trim();
     if (((result.stdout ?? "").trim() === "" && stderr === "") || /no crontab/i.test(stderr))
         return "";
+    // `crontab` reads the spool through its setgid `crontab` group (setuid root on some distributions). A process
+    // started with no-new-privileges (an agent sandbox, a container, systemd `NoNewPrivileges=`) runs it without that
+    // privilege, and the spool refuses the read. The crontab itself is fine, so say so instead of passing on a bare
+    // `fopen` error. Without no-new-privileges a refusal has another cause and is reported as what it said.
+    if (result.noNewPrivileges && /permission denied/i.test(stderr)) {
+        throw new ConfigError("crontab -l could not read the crontab spool (permission denied). `crontab` reads it through its setgid " +
+            "(or setuid) bit, which this process, started with no-new-privileges (an agent sandbox, a container, " +
+            "systemd NoNewPrivileges=), does not grant; run this from a normal shell to see the installed tasks.", "INVALID_CONFIG_FILE", "Run the command from a normal login shell or terminal, not from a sandboxed process.");
+    }
     throw new ConfigError(`crontab -l failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "The `crontab` binary ran but did not report success; check its output above.");
 }
 function writeCrontab(exec, content) {
@@ -463,6 +472,15 @@ function replaceCrontab(exec, existing, next) {
         throw err;
     }
 }
+/** Whether this process has Linux's no-new-privileges flag, which every child (`crontab` included) inherits. */
+function hasNoNewPrivileges() {
+    try {
+        return /^NoNewPrivs:\s*1$/m.test(fs.readFileSync("/proc/self/status", "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
 function defaultCronExec() {
     const run = (args, input) => {
         const r = spawnSync("crontab", args, { encoding: "utf8", ...(input !== undefined ? { input } : {}) });
@@ -471,6 +489,7 @@ function defaultCronExec() {
             stdout: r.stdout ?? "",
             stderr: r.stderr ?? "",
             enoent: r.error?.code === "ENOENT",
+            noNewPrivileges: r.status !== 0 && hasNoNewPrivileges(),
         };
     };
     return {

package/docs/architecture/akm-core-principles.md

@@ -225,8 +225,9 @@ Why: an accidental API is a compatibility promise nobody agreed to make.
 
 Enforced by: `tests/contracts/api-surface.test.ts` (the export list),
 `tests/integration/install/package-exports.test.ts` (the `exports` map),
-`package.json` (`engines.node` and the `preinstall` check), and the
-`node-smoke` job in `.github/workflows/ci.yml` (Node 22 and 24).
+`package.json` (`engines.node`), the Node version check in the launchers and
+`src/cli.ts`, and the `node-smoke` job in `.github/workflows/ci.yml` (Node 22
+and 24).
 
 ### 10. Agent harnesses are thin, replaceable internals
 

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

@@ -26,7 +26,7 @@ changes.
 | `connections-and-harnesses` | One table of every configured connection (endpoint, whether its key is held — a `$VAR` set in this shell, a `credentials.json` entry, or none — and whether the endpoint answers) and harness (platform, whether its binary is on `PATH`, and with a probe its `--version`), then the work that runs on them: improve, judges, agents, extract, enrich, index, embedding and curate rerank, each naming the connection or harness and the model it resolves to through the same resolver the calls use (`evidence.rows`, typed `connection`, `harness` or `process`). `warn` when a key variable is unset, an endpoint does not answer, a harness is not installed, several connections (or harnesses) are configured and none is called `default` (said once, with the fix: name one `default`), or a work row cannot resolve because of the config; `unknown` when neither a connection nor a harness is configured; otherwise `pass`. Endpoint reachability is one bounded `GET /models` and the version is the harness's own `--version`; with `--no-probe` neither runs and the message says so. | Correct the named connection, key or harness; run `akm setup` when nothing is configured. A work row whose parts run somewhere other than the row's own target lists them in `overrides`, each with the kind (connection or harness), name and model it runs on: that is a per-process pin, working as set. |
 | `task-fail-rate` | ≥5% of scheduled task runs failed in the window (exit 143/70 recurring), or a single task_id fails at/above the same threshold. (#943) For `command`-kind (agent/LLM dispatch) failures specifically, `evidence.agentFailureReasonCounts` always carries a `detail.reason` breakdown (`timeout`, `non_zero_exit`, `spawn_failed`, …), and the warn message names the dominant reason — e.g. `(timeout-dominant: 9/12 command-task failures)` — when one reason is at least half of the counted command-task failures. | Triage as a bug: `akm task doctor`, inspect failing lane logs. For a native shell/script task, exit-143 = killed/timeout, exit-70 = internal error. For a `command`-kind (agent/LLM) task, read `detail.reason` from `akm task history` instead of the exit code — `timeout` means the dispatch's own deadline (not an outer process kill) expired; `non_zero_exit`/`spawn_failed`/`aborted`/etc. name the other failure shapes. |
 | `data-dir-usage` | The data directory is more than 3× the live databases (`state.db` + `index.db` + `logs.db`), or one top-level subdirectory holds more than half of it; the message names that subdirectory with its size and share. | Look at the named subdirectory. `backups/tasks/` holds one snapshot per `akm migrate apply` run that rewrote a task file; everything under `backups/` is yours to prune. |
-| `semantic-search` | What the last `akm index` recorded about semantic search, with the index's entry and vector counts read now; no model load, no request. `pass` when every entry has a vector (local: on `onnxruntime-node`) or `semanticSearchMode` is `off`; `warn` when vectors lag entries, local embeddings ran on another runtime, or the platform has no native ONNX Runtime library (`unavailable: platform`: Alpine/musl, Intel macOS, where keyword search is the healthy state); `fail` when the last index found it `blocked` (endpoint or model download failed) or `unavailable: load` (the library is there but did not load: a missing package or addon, a `noexec` temp or cache directory), with the reason; `unknown` before the first index. A hard check, so a `fail` fails `akm health`. | `fail`: fix the reason named, then run `akm index`; the check reads the next index's record. `warn` for the platform: set `semanticSearchMode` to `off`, or `embedding.endpoint` to a remote embedding service. |
+| `semantic-search` | What the last `akm index` recorded about semantic search, with the index's entry and vector counts read now; no model load, no request. `pass` when every entry has a vector (local: on `onnxruntime-node`) or `semanticSearchMode` is `off`; `warn` when vectors lag entries, local embeddings ran on another runtime, or akm offers no local embeddings on this platform (`unavailable: platform`, where keyword search or an endpoint is the default); `fail` when the last index found it `blocked` (endpoint or model download failed) or `unavailable: load` (the runtime could not be downloaded or did not load, for example from a `noexec` cache directory), with the reason; `unknown` before the first index. A hard check, so a `fail` fails `akm health`. | `fail`: fix the reason named, then run `akm index`; the check reads the next index's record. `warn` for the platform: `akm setup --embedding off` for keyword search, or `akm setup --embedding <model> --embedding-endpoint <url>` for a remote endpoint. |
 | `stash-git-exposure` | `env/` or `secrets/` assets are git-tracked **and** a remote is set — `git push` can leak keys. | `git rm --cached` the files, add `env/`+`secrets/` to `.gitignore` (a rule alone does not untrack). |
 | `session-extraction` | (#914) Derived from the `extract_sessions_seen` ledger for the last 7 days — not `improve_runs`, which the hook-driven `akm proposal extract --session-id ...` never writes. `unknown` when nothing was recorded; `warn` when every session in the window was skipped for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`), naming the reason and engine; otherwise `pass` with per-outcome counts. | An `unknown` machine may be deliberately not configured for extraction, or may have stopped harvesting — check for recent sessions. A `warn` names the broken engine/reason directly. |
 | `auto-accept-validation` | Proposals passed the confidence gate but failed validation (bad frontmatter, truncation). | Review the affected pending proposals via `akm proposal list`; they were held, not lost. |
@@ -37,7 +37,7 @@ changes.
 | `index-state-generation` | Durable usage links in `state.db` disagree with the current searchable index generation, which an interrupted cross-database update leaves behind. | Stop concurrent writers, then run `akm index --full` to relink state to the current index. |
 | `cli-version` | (#950) Compares the installed akm-cli version against the latest GitHub release (the same source `akm upgrade` trusts). `--probe`-gated: `unknown` "not probed" with `--no-probe`; offline/rate-limited also degrades to `unknown`, never a false `warn`. | Run `akm upgrade` when a newer release is reported. An `unknown` result carries no staleness claim either way — check manually if it matters. |
 | `scheduler-binary` | (#953) Reads the scheduler's recorded akm invocation for the installed tasks (the same binding `task sync`/`task doctor` already read — no crontab/launchd/schtasks text parsing) and runs it with `--version`, compared against the running CLI's version. `--probe`-gated: `unknown` "not probed" with `--no-probe`. `unknown` when no scheduled task is installed or the recorded binary cannot be executed. | A `warn` names both versions — upgrading akm through a different installer than the one active at the last `task sync` left the schedule pointed at the old binary; run `akm task sync` to rebind it. |
-| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same 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. `plugin-version`'s newest-tag lookup is `--probe`-gated: with `--no-probe` its row is `unknown` ("not probed") and only the local range check still runs. `opencode-plugin-version` reads local files only and is never gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
+| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same 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 `opencode-plugin-version` 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. 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. `plugin-version`'s newest-tag lookup is `--probe`-gated: with `--no-probe` its row is `unknown` ("not probed") and only the local range check still runs. `opencode-plugin-version` reads local files only and is never gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
 
 ## Connections, harnesses and the work on them
 

package/docs/architecture/internals/storage-locations.md

@@ -810,6 +810,7 @@ adapter recognizes — `schema.md` + `pages/` is the probe) contains:
 | `$CACHE/tasks/logs/<task-id>/` | Per-run stdout/stderr log files (`<ISO-ts>.log`) | No cleanup |
 | `$CACHE/bin/rg` | Auto-downloaded ripgrep binary | Permanent |
 | `$CACHE/opencode/<version>/opencode` | The OpenCode binary akm's own runtime runs (about 240 MB), fetched from the npm registry on its first use | Permanent; safe to delete (fetched again) |
+| `$CACHE/onnxruntime/<version>-<platform>-<arch>/` | `onnxruntime_binding.node` and the ONNX Runtime library it links, which the local embedder loads; fetched from the npm registry by `akm setup --embedding local` or the first local embedding (about 36 MB kept). Must be on a mount that allows executing files | Permanent; safe to delete (fetched again) |
 | `$CACHE/index/unresolved-sources/<stash>/<name>` | Synthetic placeholder path for a configured source whose content root did not resolve this run; never written to disk, only reported as a `SearchSource.path`. Moved out of `$STASH/.akm/unresolved-sources/` (itlackey/akm#890). | N/A (not a real directory) |
 
 Cache-backed bundles (`git`, `website`, `npm`) are materialised into `$CACHE`

package/docs/architecture/specs/ref.md

@@ -132,8 +132,9 @@ runs collapsed to `-`, trimmed) and match the fragment against those slugs;
 fall back to a case-insensitive match against raw heading text. The selected
 region runs from that heading to the next heading of the same or higher level.
 A fragment that matches no heading is an error that **lists the available
-fragment slugs** — that error is the discovery mechanism, replacing the removed
-`toc` view mode.
+fragment slugs**. The outline itself is `akm show <ref> --detail brief`, whose
+`toc` lists every heading with the slug that selects it; it replaces the
+removed `toc` view mode.
 
 **Every other item kind — adapter-owned selector.** When one item exposes
 multiple exports the adapter MAY append a stable fragment
@@ -157,7 +158,7 @@ is removed. It was a second argv parser (`normalizeShowArgv` rewrote
 | --- | --- |
 | `akm show X section "Auth"` | `akm show X#auth` |
 | `akm show X full` | `akm show X` (no fragment = whole item) |
-| `akm show X toc` | `akm show X#<unmatched>` lists available fragment slugs |
+| `akm show X toc` | `akm show X --detail brief` (its `toc` field) |
 | `akm show X lines 10 30` | removed — every response carries `path`; slice the file |
 | `akm show X frontmatter` | removed — if a raw-YAML projection proves necessary it returns as a `--shape` value, the designated projection axis |
 

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

@@ -240,19 +240,27 @@ sets the same path and restores it from a model/source-identified Actions
 cache. Candidate tags and manual runs are restore-only; only the scheduled
 default-branch run may save a cache entry.
 
-The same gate runs real semantic index/search round-trips on `onnxruntime-node`,
-asserts the `embeddingRuntime` the index reports, and compares the embedder's
-vectors with the Transformers.js reference in
-`tests/fixtures/embedder-reference-vectors.json`. Package acceptance separately
-verifies the ordinary npm package surface; there is no installed-consumer
-compatibility architecture or copied semantic runtime to audit.
+The same gate runs real semantic index/search round-trips on `onnxruntime-node`'s
+binding, asserts the `embeddingRuntime` the index reports, and compares the
+embedder's vectors with the Transformers.js reference in
+`tests/fixtures/embedder-reference-vectors.json`. The binding and its library are
+shared across runs the same way as the model: `tests/_helpers/onnx-runtime-cache.ts`
+copies the repo-local `.ci-cache/akm/onnxruntime/` into each sandbox's akm cache
+and keeps a folder a run fetched there, and gated CI caches that directory under
+a key from `src/llm/embedders/onnx-runtime.ts`, which pins the ONNX Runtime
+version. Package acceptance separately verifies
+the ordinary npm package surface.
 
 `tests/integration/standalone-semantic.test.ts` (the same `AKM_SEMANTIC_TESTS=1`
-gate) builds the host's standalone binary and indexes a small stash with it,
-asserting a ready status, a vector per entry and the native runtime. Gated CI
-runs it in the Semantic Search job (Linux) and in the Native Scheduler job on
-macOS and Windows, the only places the binary's preload of each platform's ONNX
-Runtime library runs.
+gate) builds the host's standalone binary and asserts it embeds no `.node` file.
+Where akm offers local embeddings it runs `akm setup --yes --embedding local`,
+expects the binding and the library in the cache folder, and indexes a small
+stash, asserting a ready status, a vector per entry and the native runtime.
+Everywhere else it asserts the default: setup warns and saves keyword search, an
+index with semantic search on reports it unavailable for the platform, `akm
+health` warns, and search is keyword. Gated CI runs it in the Semantic Search job
+(Linux) and in the Native Scheduler job on macOS (local embeddings) and Windows
+(the default), the only places the binary runs on those platforms.
 
 ### What to test explicitly
 
@@ -282,7 +290,8 @@ This validates three deployment methods across four Linux families:
 - bun-based install: Ubuntu, Debian, Alpine, Fedora
 - compiled binary install: Ubuntu, Debian, Fedora
 - npm install: Debian on `node:24-slim`, which has no compiler, python or make
-  (`npm install -g` of the packed package; the install's exit code is the check)
+  (`npm install -g --ignore-scripts` of the packed package, as npm 12 installs by
+  default; the install's exit code and the smoke test are the check)
 
 Binary validation currently excludes Alpine. The compiled Linux binary used in
 this repo's Docker tests is not packaged for Alpine/musl compatibility, so the
@@ -397,9 +406,9 @@ For a local release gate without Docker, use:
 ./tests/release-check.sh --skip-docker
 ```
 
-That script checks the packaged artifact: bin targets, the migrator, package
-acceptance, and the upgrade rehearsal against the packed tarball. Lint, the
-typecheck and the test suites are `bun run check`.
+That script checks the packaged artifact: bin targets, the migrator and package
+acceptance. Lint, the typecheck and the test suites are `bun run check`; the
+upgrade rehearsal runs in CI.
 
 The Release workflow runs Gated CI (real embeddings, Docker, and the
 Linux/macOS/Windows schedulers) on the commit it publishes and requires CI to
@@ -512,17 +521,16 @@ throws naming the fix instead. Env overrides:
   resolving the highest published stable version below the candidate's
   `package.json` version.
 - `AKM_CANDIDATE_TARBALL=<path>` — use an already-packed candidate tarball
-  (`tests/release-check.sh` passes `$PACKAGE_CANDIDATE`) instead of running
-  `npm pack` on the working tree (which requires `dist/cli.js` — run
-  `bun run build` first).
+  instead of running `npm pack` on the working tree (which requires
+  `dist/cli.js` — run `bun run build` first).
 
 Fetched previous-release tarballs are cached under
 `${TMPDIR:-/tmp}/akm-upgrade-rehearsal/previous-release/<version>/` so repeat
 runs do not re-hit the network. It is wired into CI as the `upgrade-rehearsal`
 job (`.github/workflows/ci.yml`), which runs on pushes to `main` and release
 branches, on manual runs and on every commit of a pull request that is ready
-for review (a draft pull request skips it until it is marked ready), and into
-`tests/release-check.sh` right after packing the release candidate.
+for review (a draft pull request skips it until it is marked ready). The Release
+workflow requires that CI run to pass on the commit it publishes.
 
 ## Coverage Gap Guide
 

package/docs/guides/discover-and-load.md

@@ -73,14 +73,21 @@ lookup to one installed bundle when a conceptId is ambiguous across bundles.
 
 ## 4. Load a document section
 
-Knowledge docs and other markdown assets can be large. Append `#fragment` to
-a ref to return one section by heading slug instead of the whole document:
+Knowledge docs and other markdown assets can be large. Read the outline first,
+then only the sections you need. `--detail brief` returns the document's `toc`
+without the body, and appending `#<slug>` to a ref returns one section:
 
 ```sh
+akm show knowledge/api-guide --detail brief
+# → {"toc": [{"level": 2, "text": "Authentication", "slug": "authentication", "startLine": 12}, ...], ...}
 akm show knowledge/api-guide#authentication
 # → just the "Authentication" section, not the full document
 ```
 
+Every `slug` in `toc` selects its section, including repeated headings, which
+get `-1`, `-2`, ... suffixes. A whole-document show carries the same `toc`
+next to the body.
+
 Search can also return an opaque `#akm-fragment-...` selector for a bounded
 piece of a long document. The exact selector remains the default. For memories
 whose opening context helps interpret a later matching turn, opt into bounded
@@ -96,8 +103,9 @@ reports `contextTruncated` in JSON. The response also distinguishes canonical
 `parentRef` from `selectedRef` and includes fragment position, line bounds,
 neighbors, and separate fragment/parent size estimates.
 
-An unmatched fragment lists the available slugs instead of erroring, so a
-guess that misses still tells you what to try next.
+An unmatched fragment is an error that lists the available slugs, so a guess
+that misses still tells you what to try next; `--detail brief` is the way to
+see them without guessing.
 
 ## 5. Record the outcome