akm-cli 0.10.261014-beta → 0.10.261015-beta

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/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. |

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/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

package/docs/guides/getting-started.md

@@ -34,23 +34,24 @@ Or download a standalone binary directly from the
 Hitting a PowerShell execution-policy error on Windows? See
 [Troubleshooting](#troubleshooting) at the end of this guide.
 
-### Standalone binary and semantic search
-
-Local semantic search (`semanticSearchMode: auto`) runs its embedding model on
-ONNX Runtime. A standalone binary carries the library for its platform. The
-first time it embeds, it copies that library once into akm's cache directory,
-under `onnxruntime/<version>-<platform>-<arch>/` (18 to 34 MB depending on the
-platform; `akm info` prints the cache directory), and loads it from there. Two
-limits follow:
-
-- A standalone binary writes its native addon to the system temp directory and
-  loads it from there, so a temp directory mounted `noexec` blocks semantic
-  search (`akm index` reports it `blocked`; keyword search works). Set `TMPDIR`
-  to a writable, executable directory. The cache directory must be on
-  an executable mount too.
-- Alpine/musl and Intel macOS have no native ONNX Runtime library. Semantic
-  search is unavailable there: `akm index` reports it `blocked` with the reason
-  and search stays keyword-only. A remote `embedding.endpoint` still works.
+### Local semantic search
+
+Local semantic search runs its embedding model on ONNX Runtime, and akm offers
+it on Linux x64 (glibc) and Apple-silicon macOS; on every other
+platform search is keyword-only or uses an embedding endpoint you configure. Choosing the built-in embedder in
+`akm setup` (or `akm setup --yes --embedding local`) downloads what it needs once
+into akm's cache directory (`akm info` prints it): ONNX Runtime for your platform,
+under `onnxruntime/<version>-<platform>-<arch>/` (about 86 MB downloaded,
+about 36 MB kept), and the model (about 127 MB). Nothing is installed with the npm
+package or carried in a standalone binary, and the first `akm index` downloads
+what setup did not. Two notes:
+
+- The cache directory must be on a mount that allows executing files: the
+  runtime is loaded from there, and on a `noexec` mount `akm index` reports
+  semantic search `blocked` (keyword search works).
+- On a platform without local embeddings, `akm setup` offers an embedding
+  endpoint or keyword search only, and `akm setup --embedding local` warns and
+  keeps keyword search.
 
 ### akm's own agent runtime
 
@@ -60,7 +61,8 @@ is the same for the npm package and the standalone binary: nothing of OpenCode
 is installed with akm, and the first time the runtime runs, akm downloads the
 OpenCode binary for your platform from the npm registry (one package, about
 114 MB, 240 MB on disk), checks it against the registry's integrity hash and
-keeps it in the cache directory under `opencode/<version>/`. It is fetched once.
+keeps it in the cache directory under `opencode/<version>/`. It is fetched once;
+the `akm setup` wizard offers to fetch it then, when agent work runs there.
 Three limits follow:
 
 - That step needs the npm registry. Without network access for it, enable the

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

@@ -54,19 +54,24 @@ it and never appears on the command line:
 akm setup --yes --endpoint https://api.example.com/v1 --api-key-env EXAMPLE_API_KEY
 ```
 
-`--no-probe` keeps the run offline (the endpoint's model list is not fetched), so a
-new connection has no model until `akm models set` names one.
+`--no-probe` keeps the run offline: nothing is contacted or downloaded (the
+endpoint's model list is not fetched, so a new connection has no model until
+`akm models set` names one).
 For the full set of flags, see `akm setup --help`; for the config they write,
 see [configuration.md](../../reference/configuration.md).
 
-**Semantic search.** Headless setups (`--yes` or `--from`, no wizard
-prompts) defer the embedding-model download to the first `akm index` run,
-unlike the interactive wizard which downloads immediately during `akm
-setup`. Set the mode explicitly rather than relying on the implicit default:
+**Semantic search.** `--embedding local` chooses the built-in embedder, offered
+on Linux x64 (glibc) and Apple-silicon macOS; elsewhere it warns and
+keeps keyword search. Once the config is saved, a headless setup (`--yes` or
+`--from`) downloads the embedder's runtime and model into akm's cache and
+reports `semanticAssets` in its result (`ready`, `blocked: <reason>`, or
+`skipped` with `--no-probe`, which leaves the download to the first
+`akm index`). Without the flag, semantic search stays as the config has it
+(`off` by default):
 
 ```sh
-akm config set semanticSearchMode auto   # local embeddings, downloaded on first index
-akm config set semanticSearchMode off    # skip embeddings entirely
+akm setup --yes --embedding local          # local embeddings, downloaded now
+akm config set semanticSearchMode off      # skip embeddings entirely
 ```
 
 For resource requirements and remote-embedding alternatives, see

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

@@ -609,6 +609,23 @@ yours to run it, and its runs are in your OpenCode history, which improve reads.
 - **A transient reflect failure** (transport error, timeout, crash) no longer
   uses up the feedback that planned it; the ref is retried next run.
 
+### Local semantic search and installs
+
+- **akm no longer installs ONNX Runtime through npm.** `akm setup` with the
+  built-in embedder (`--embedding local`), or the first `akm index` after the
+  upgrade, downloads ONNX Runtime 1.24.3 once (about 86 MB) into akm's cache.
+  The vectors are unchanged, so no re-index is needed.
+- **Local embeddings are offered on Linux x64 (glibc) and
+  Apple-silicon macOS.** Every other platform uses keyword search or an
+  embedding endpoint, and `akm setup` offers only those there.
+- **Standalone binaries are up to 36 MB smaller**, and a `noexec` temp directory
+  no longer matters; akm's cache directory must still allow executing files.
+- **On Node, the SQLite driver ships prebuilt for every supported Node
+  version**, so `npm install -g akm-cli` works where npm skips install scripts
+  (npm 12 does by default), and a Node upgrade no longer needs `npm rebuild`.
+  Nothing in the package runs an install script, the Node.js version check
+  included: akm checks the version when it starts.
+
 ### The environment programs run in
 
 A harness (agent tasks and workflow agent steps included) and an `exec` unit's

package/docs/reference/cli.md

@@ -218,9 +218,16 @@ The wizard asks, in order:
    the config as this run will save it: a further `--name` connection does not
    serve embeddings, its models are not offered, and with several connections
    none called `default`, `--embedding <model>` refuses and asks you to name one
-   default or pass `--embedding-endpoint`.
+   default or pass `--embedding-endpoint`. The built-in embedder is offered on
+   Linux x64 (glibc) and Apple-silicon macOS only; elsewhere the step
+   says so in one sentence and offers an endpoint or off, and `--embedding local`
+   warns and saves off.
 5. **Save.** The config is written, the bundle directory initialized, and a
-   summary says what runs where.
+   summary says what runs where. With the built-in embedder chosen, setup then
+   downloads its runtime (ONNX Runtime, about 86 MB) and model (about 127 MB)
+   into akm's cache and loads them; the wizard asks first. When agent work runs
+   on akm's own runtime, the wizard also offers to download its OpenCode binary
+   (about 114 MB) now rather than on the first agent run.
 
 Flags answer one question each; `--yes` takes the detected default for every
 question left, so nothing is prompted. Without a terminal, `akm setup` refuses
@@ -236,7 +243,7 @@ unless `--yes` or `--from` is given.
 | `--embedding-endpoint <url>`, `--embedding-api-key-env <NAME>` | Another endpoint serving the embedding model |
 | `--from <file>` | A config file (JSON or YAML) to merge |
 | `--dir <path>`, `--no-init` | The bundle directory; skip scaffolding it |
-| `--no-probe` | Offline: the endpoint is not contacted and its models are not listed; a connection added this way has no model until `akm models set` names one |
+| `--no-probe` | Offline: nothing is contacted or downloaded. The endpoint's models are not listed, so a connection added this way has no model until `akm models set` names one, and the built-in embedder's runtime and model are downloaded by the first `akm index` |
 
 The detected defaults are: when no agent program is configured yet, every one
 found on `PATH` is enabled and the first found is the default. If no connection
@@ -249,7 +256,11 @@ whose endpoint lists an embedding model.
 
 The wizard also lets you review registries and add bundle sources. A scripted run
 prints its result with a `runs` object saying what runs where: `modelCalls`,
-`agentWork` and `embeddings`.
+`agentWork` and `embeddings`. When the saved config uses the built-in embedder,
+the result also has `semanticAssets`: `ready` once its runtime and model are
+downloaded and load, `blocked: <reason>` when they do not (the config is saved
+all the same), or `skipped` with `--no-probe`. A scripted run does not download
+akm's own agent runtime; its first agent run does.
 
 ### index
 
@@ -464,13 +475,13 @@ search, with the index's entry and vector counts read now. It loads no model and
 sends no request. It `pass`es when every entry has a vector (and a local model
 embedded on `onnxruntime-node`) or `semanticSearchMode` is `off`; `warn`s when
 vectors lag the entries (`akm index` embeds the rest), local embeddings ran on
-another runtime, or this platform has no native ONNX Runtime library
-(Alpine/musl, Intel macOS: keyword search is all there is, so the message says to
-set `semanticSearchMode` to `off` or `embedding.endpoint` to a remote service);
+another runtime, or akm offers no local embeddings on this platform (keyword
+search or an endpoint is the default there, so the message names
+`akm setup --embedding off` and `akm setup --embedding <model> --embedding-endpoint <url>`);
 `fail`s, with the recorded reason, when the last index found semantic search
 `blocked` (an embedding endpoint or model download failed) or `unavailable` for
-a cause that can be fixed (the library is there but did not load: a missing
-package or addon, a `noexec` temp or cache directory); and is `unknown` before
+a cause that can be fixed (the runtime could not be downloaded or did not load,
+for example from a `noexec` cache directory); and is `unknown` before
 the first index. Search never reads this record: a query still
 tries semantic search and falls back to keyword search on its own. A fix shows
 here after the next `akm index`. `evidence` carries the recorded `status`,

package/docs/reference/configuration.md

@@ -690,21 +690,43 @@ semantic search is disabled or has not been built. A read-only sandbox that
 cannot record best-effort usage telemetry does not by itself mark search as
 degraded.
 The local embedder runs its model (`Xenova/bge-small-en-v1.5` unless
-`embedding.localModel` names another) on `onnxruntime-node`, with
-`@huggingface/tokenizers` for the token ids. Both are normal dependencies of the
-package, imported directly; AKM does not carry a copied runtime under `src/` or
-`dist/`. The model's four files (about 127 MB) are fetched from the Hugging Face
-Hub on first use into `$HF_HOME/<repo>/` (default `<cache dir>/models`), and
-`HF_HUB_OFFLINE=1` forbids the fetch. `akm index --format json` reports the
-runtime it embedded with as `verification.embeddingRuntime`.
-If the runtime cannot load, because the dependency is missing or the platform
-has no native ONNX Runtime library (Alpine/musl, Intel macOS), the index reports
-semantic search `blocked` with the reason and search stays keyword-only:
-reinstall `akm-cli` for a missing dependency, or configure a remote
-`embedding.endpoint`. A standalone binary copies the library it embeds once into
-`<cache dir>/onnxruntime/` (see
-[Getting Started](../guides/getting-started.md#standalone-binary-and-semantic-search)).
-Setup does not mutate a global installation to add runtime packages.
+`embedding.localModel` names another) on ONNX Runtime, through
+`onnxruntime-node`'s native binding, with `@huggingface/tokenizers` for the token
+ids. akm offers local embeddings on Linux x64 (glibc) and Apple-silicon
+macOS; on every other platform semantic search uses an embedding endpoint or
+stays keyword-only. akm does not install `onnxruntime-node`:
+`akm setup --embedding local` (or the wizard's built-in embedder) downloads that
+package's binding and library for this platform once from the npm registry
+(about 86 MB; the registry's sha512 integrity is checked before anything is
+extracted) into `<cache dir>/onnxruntime/<version>-<platform>-<arch>/`, and the
+first local embedding downloads them when setup did not. The model's four files
+(about 127 MB) come from the Hugging Face Hub the same way, into
+`$HF_HOME/<repo>/` (default `<cache dir>/models`); `HF_HUB_OFFLINE=1` forbids
+that download. `akm index --format json` reports the runtime it embedded with as
+`verification.embeddingRuntime`. If the runtime cannot be downloaded or does not
+load (the cache directory is mounted `noexec`), the index reports semantic search
+`blocked` with the reason and search stays keyword-only. On a platform without
+local embeddings, `akm setup` offers an endpoint or keyword search,
+`--embedding local` warns and saves keyword search, and a config that turns
+semantic search on anyway gets it reported unavailable for the platform by the
+index and a warning from `akm health`.
+
+**Without network access**, fill akm's cache directory (`akm info` prints
+`cacheDir`; `AKM_CACHE_DIR` moves it) before the first `akm index`:
+
+- `onnxruntime/<version>-<platform>-<arch>/` (for example
+  `onnxruntime/1.24.3-linux-x64/`) holding `onnxruntime_binding.node` and the
+  library it links (`libonnxruntime.so.1` on Linux,
+  `libonnxruntime.1.24.3.dylib` on macOS). Take both from
+  `package/bin/napi-v6/<platform>/<arch>/` in the `onnxruntime-node@1.24.3`
+  tarball (`npm pack onnxruntime-node@1.24.3`), or copy the folder from a
+  connected machine of the same platform after
+  `akm setup --yes --embedding local`.
+- `models/Xenova/bge-small-en-v1.5/` holding `tokenizer.json`,
+  `tokenizer_config.json`, `config.json` and `onnx/model.onnx`, or set `HF_HOME`
+  to a directory that holds them and `HF_HUB_OFFLINE=1`.
+- `opencode/2.1.4/opencode` (`opencode.exe` on Windows) for akm's own agent
+  runtime.
 The default is `"off"` so a bare or headless install (`akm bundle create`, `--yes`,
 `--config`) never silently downloads the local embedding model on first
 index. A config that has an `embedding` block and sets no `semanticSearchMode`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261014-beta",
+  "version": "0.10.261015-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": [
@@ -34,9 +34,8 @@
   },
   "license": "MPL-2.0",
   "pinNotes": {
-    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
+    "better-sqlite3@13.0.3": "Exact pin. The SQLite driver akm loads on Node (src/storage/database.ts); Bun uses bun:sqlite and never loads it. 13.x is built on N-API (node-addon-api), so one binding per platform serves every Node version, and the npm tarball carries those bindings prebuilt in prebuilds/ for Linux (glibc and musl) and macOS on x64 and arm64 and for Windows on x64 and arm64. It declares no install script and sets gypfile: false, so it installs the same where npm runs install scripts and where it does not (npm 12 blocks dependency scripts by default). Not covered: 32-bit ARM Linux (linux-arm, linuxmusl-arm), which 12.x served only through its install script; akm under Node has no SQLite driver there. `bun install` tries to build it anyway (Bun ignores gypfile: false for a trusted package) and, as an optional dependency, drops it silently when that fails, which is why CI installs it with npm. This replaced 12.11.1, whose binding came per Node ABI from its install script (`prebuild-install || node-gyp rebuild`, #790); the earlier note asked for a soak before 13.x, and 13.0.3 soaks through the 0.10 betas instead. Before bumping: the tarball must still carry prebuilds/ for every platform above and declare no install script, and the CI node-smoke job, which installs this exact string read back out of this file (.github/workflows/ci.yml), must pass on every Node major in engines.",
     "@huggingface/tokenizers@0.1.3": "Exact pin: the tokenizer of the local embedding model (src/llm/embedders/local.ts). Pure JS with no dependencies. A different release can change the token ids and with them every stored vector, so re-run the real-model semantic gate (tests/integration/semantic-search-e2e.test.ts, which compares the vectors with tests/fixtures/embedder-reference-vectors.json) before changing it.",
-    "onnxruntime-node@1.24.3": "Exact pin: the local embedding runtime. The standalone binary embeds this version's native library from node_modules/onnxruntime-node/bin/napi-v6/ (src/standalone/native/) and its addon is bound to exactly that library, so a bump moves this pin, the library file names in src/standalone/native/ (the macOS one carries the version), the list of platforms it ships a library for in src/llm/embedders/local.ts and the real-model semantic gate together.",
     "ajv@8.20.0": "Exact pin (devDependency, used only by tests: tests/tasks-schema.test.ts validates task sources against schemas/akm-task.json, tests/contracts/config-schema-drift.test.ts checks schemas/akm-config.json). Pinned in 4d7d77992 without a recorded reason; keep exact until the pin is next reviewed.",
     "cmd-shim@9.0.2": "Exact pin (devDependency), from cd5a3be12 \"pin cmd-shim for launcher tests\": tests/integration/install/package-launcher.test.ts writes the Windows shims npm would write with this package, where it used to load the copy inside the installed npm's own node_modules. That commit records no reason for an exact version over a range; keep exact until the pin is next reviewed."
   },
@@ -72,7 +71,6 @@
     "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -109,7 +107,7 @@
     "zod-to-json-schema": "^3.23.0"
   },
   "optionalDependencies": {
-    "better-sqlite3": "12.11.1",
+    "better-sqlite3": "13.0.3",
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
@@ -123,7 +121,6 @@
     "fast-xml-parser": "^5.10.1",
     "marked": "^18.1.1",
     "node-html-parser": "^9.0.1",
-    "onnxruntime-node": "1.24.3",
     "semver": "^7.6.0",
     "turndown": "^7.2.4",
     "yaml": "^2.8.4",

package/dist/standalone/onnxruntime-library.js

@@ -1,52 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * The ONNX Runtime shared library for a compiled standalone binary.
- *
- * `onnxruntime-node`'s addon links a shared library that sits beside it in the
- * package. A Bun executable extracts an embedded addon at load but not the
- * library it links, so the addon cannot start. The standalone build embeds the
- * library for its target (`src/standalone/native/`, chosen by
- * `scripts/build-standalone.ts`); this copies it once into akm's cache and
- * loads it with `bun:ffi`, after which the addon's own link to it is already
- * satisfied.
- *
- * Outside a standalone binary (`bun src/cli.ts`, the Node build) nothing here
- * is defined and nothing is evaluated: the package's own files are used.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { getCacheDir } from "../core/paths.js";
-/**
- * Put the embedded library on disk and load it, before `onnxruntime-node` is
- * imported. Throws when the library cannot be loaded; the caller reports that
- * as the embedding runtime being unavailable.
- */
-export async function preloadOnnxRuntimeLibrary() {
-    if (typeof AKM_STANDALONE_NATIVE_MODULE === "undefined")
-        return;
-    // The specifier is a build constant, so the standalone build bundles this one module and no other build bundles any.
-    const { embeddedPath, fileName } = (await import(AKM_STANDALONE_NATIVE_MODULE));
-    if (!embeddedPath || !fileName)
-        return;
-    const directory = path.join(getCacheDir(), "onnxruntime", `${AKM_ONNXRUNTIME_VERSION}-${process.platform}-${process.arch}`);
-    const library = path.join(directory, fileName);
-    const size = fs.statSync(embeddedPath).size;
-    if (!fs.existsSync(library) || fs.statSync(library).size !== size) {
-        fs.mkdirSync(directory, { recursive: true });
-        const partial = `${library}.${process.pid}.tmp`;
-        fs.writeFileSync(partial, fs.readFileSync(embeddedPath));
-        try {
-            fs.renameSync(partial, library);
-        }
-        catch (error) {
-            // Another akm process copied it first and has it loaded, which Windows will not replace: use that copy.
-            fs.rmSync(partial, { force: true });
-            if (!fs.existsSync(library) || fs.statSync(library).size !== size)
-                throw error;
-        }
-    }
-    const { dlopen } = await import("bun:ffi");
-    dlopen(library, { OrtGetApiBase: { args: [], returns: "ptr" } });
-}