@klhapp/skillmux 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0](https://github.com/klhq/skillmux/compare/v1.12.0...v1.13.0) (2026-09-13)
+
+
+### Added
+
+* **cli:** ship native launcher and platform packages ([#193](https://github.com/klhq/skillmux/issues/193)) ([87701d4](https://github.com/klhq/skillmux/commit/87701d44d1b647501d1dff9d205da8ffbe6a3c05))
+* **sync:** make pins reach their targets, and report drift when they have not ([#192](https://github.com/klhq/skillmux/issues/192)) ([5f9c6ec](https://github.com/klhq/skillmux/commit/5f9c6ecaaaf216e4d01fa4a521ac686ae43681d3))
+
 ## [1.12.0](https://github.com/klhq/skillmux/compare/v1.11.2...v1.12.0) (2026-09-12)
 
 

package/README.md

@@ -41,8 +41,8 @@ See [Configuration](docs/configuration.md#machine-config-bootstrap) and
 Choose a setup by the job:
 
 1. Need native skills or local MCP for one agent? Install the **Skillmux CLI**.
-2. On Linux when Bun is undesirable? Use the **standalone Linux executable**;
-   it is the same Skillmux CLI.
+2. Want a single file and no package manager? Download the **standalone
+   executable**; it is the same Skillmux CLI.
 3. Need one shared HTTP MCP service? Deploy the **full image**, the
    self-contained default with GTE-small.
 4. Already have remote embeddings, or intentionally want lexical-only
@@ -73,19 +73,28 @@ model runs in the Skillmux process. Both stdio and HTTP expose the same
 
 ## Install the CLI
 
-The Bun package supports macOS, Linux, and Windows and requires
-[Bun 1.3 or newer](https://bun.sh/docs/installation):
+Skillmux ships as a native executable, so there is no runtime to install
+alongside it. Any of these works on macOS, Linux, and Windows:
 
 ```sh
+npm install -g @klhapp/skillmux
 bun add -g @klhapp/skillmux
-skillmux --help
+npx @klhapp/skillmux --help
 ```
 
-Native target sync needs permission to create directory symlinks on Windows.
+Installing pulls exactly one platform-specific executable through
+`optionalDependencies`, so you download the build for your machine and not the
+other four. Native target sync needs permission to create directory symlinks
+on Windows.
 
-On Linux, you can install a standalone executable instead. This path needs no
-GitHub CLI or package manager. It selects AMD64 or ARM64, downloads the pinned
-`v1.3.4` release, and verifies the SHA-256 digest published for that release:
+Local embedding inference is included on every platform except Intel macOS.
+See [platform support](docs/getting-started.md#platform-support) for what that
+costs and why.
+
+You can also install a standalone executable and skip package managers
+entirely. Every release attaches one per platform. This path needs no GitHub
+CLI. It selects AMD64 or ARM64, downloads the pinned `v1.3.4` release, and
+verifies the SHA-256 digest published for that release:
 
 ```sh
 version=v1.3.4

package/bin/skillmux.js

@@ -0,0 +1,89 @@
+#!/bin/sh
+// 2>/dev/null; exec "$(command -v bun || command -v node)" "$0" "$@"
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+// `new URL(...).pathname` yields "/C:/..." on Windows; fileURLToPath does not.
+const here = dirname(fileURLToPath(import.meta.url));
+
+const platformPackage = `@klhapp/skillmux-${process.platform}-${process.arch}`;
+const executableName = process.platform === "win32" ? "skillmux.exe" : "skillmux";
+
+/**
+ * Resolves the platform package directory.
+ *
+ * The search paths matter: a globally installed launcher resolves from its own
+ * directory, while a linked or hoisted layout can leave the real path outside
+ * the install tree, which is what the working directory covers.
+ */
+function resolvePackageDir() {
+  try {
+    return dirname(
+      require.resolve(`${platformPackage}/package.json`, {
+        paths: [here, dirname(process.argv[1] ?? "."), process.cwd()],
+      }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+const packageDir = resolvePackageDir();
+
+if (!packageDir && !process.env.SKILLMUX_BINARY) {
+  process.stderr.write(
+    `skillmux: no native executable for ${process.platform}-${process.arch}.\n` +
+      `The package ${platformPackage} is not installed.\n\n` +
+      "Reinstall without skipping optional dependencies:\n" +
+      "  npm install -g @klhapp/skillmux\n\n" +
+      "Or install a standalone executable:\n" +
+      "  https://github.com/klhq/skillmux/releases\n",
+  );
+  process.exit(1);
+}
+
+const executable = process.env.SKILLMUX_BINARY || join(packageDir, executableName);
+
+// The compiled binary embeds onnxruntime's addon but not the library it links
+// against, so without this the local embedding pipeline dies on a dlopen of
+// @rpath/libonnxruntime. Platforms onnxruntime does not publish, such as Intel
+// macOS, ship no lib directory and fall back to lexical recall.
+const LIBRARY_PATH_VARIABLES = {
+  darwin: "DYLD_FALLBACK_LIBRARY_PATH",
+  linux: "LD_LIBRARY_PATH",
+  win32: "PATH",
+};
+
+const env = { ...process.env };
+const libraryDir = packageDir ? join(packageDir, "lib") : null;
+const libraryVariable = LIBRARY_PATH_VARIABLES[process.platform];
+
+if (libraryDir && libraryVariable && existsSync(libraryDir)) {
+  const existing = env[libraryVariable];
+  env[libraryVariable] = existing ? `${libraryDir}${delimiter}${existing}` : libraryDir;
+}
+
+const child = spawn(executable, process.argv.slice(2), { stdio: "inherit", env });
+
+// Without this the launcher would absorb the signal and leave the executable
+// running, which matters most for `serve`: a container stop sends SIGTERM and
+// expects the HTTP server itself to shut down.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  });
+}
+
+child.on("error", (error) => {
+  process.stderr.write(`skillmux: cannot run ${executable}: ${error.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  process.exit(signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1));
+});

package/docs/README.md

@@ -9,7 +9,7 @@ where skills need to appear and where Skillmux should run.
 
 1. [Install the Skillmux CLI](getting-started.md#install-the-cli) for native
    skills or one local MCP client.
-2. On Linux, use the [standalone executable install](getting-started.md#install-the-cli)
+2. Use the [standalone executable install](getting-started.md#standalone-executable)
    when you want a pinned, checksum-verified CLI without `gh`; the
    [GitHub CLI attestation path](getting-started.md#install-with-github-cli-attestation)
    is also available for provenance verification.
@@ -19,9 +19,9 @@ where skills need to appear and where Skillmux should run.
 
 You can combine native management and local MCP retrieval on one machine. For
 native pins plus shared retrieval, run Skillmux CLI on each machine that owns
-agent directories and deploy Skillmux server for HTTP MCP. The Bun package is
-the cross-platform CLI installation method; the standalone Linux executable is
-its Linux alternative. Git and the deployment process, not Skillmux, replicate
+agent directories and deploy Skillmux server for HTTP MCP. The CLI installs
+through npm or bun on every supported platform, with a direct executable
+download as the package-manager-free alternative. Git and the deployment process, not Skillmux, replicate
 vault checkouts and determine their freshness; see
 [Deployment](deployment.md#native-pins-with-shared-retrieval).
 

package/docs/cli.md

@@ -1,7 +1,7 @@
 # CLI reference and automation
 
-The Bun package and standalone Linux executable expose the same Skillmux CLI.
-For Linux installation, use the [pinned checksum-verified download](getting-started.md#install-the-cli)
+Every installation path delivers the same Skillmux CLI executable. For a
+package-manager-free install, use the [pinned checksum-verified download](getting-started.md#standalone-executable)
 or, when provenance verification is required, the
 [attested GitHub CLI path](getting-started.md#install-with-github-cli-attestation).
 Native management belongs on the machine that owns the agent skill directories:
@@ -315,7 +315,10 @@ skillmux target remove custom-agent --yes
 `target add` uses the same ownership, symlink, full-vault, rollback, and
 current-host scoping checks as `skillmux init`. `target remove` removes the
 manifest entry and preserves the directory, marker, and skill files. The
-command prints the preserved path so cleanup remains an explicit user action.
+command prints the preserved path so cleanup remains an explicit user action. `target add` syncs once the
+target is recorded, so the new directory is populated in one command; the
+approval just given named that exact directory, so it carries through. Pass
+`--no-sync` to record the target without populating it.
 
 ---
 
@@ -328,12 +331,17 @@ default, capped at 25 skills unless `[core].limit` raises it:
 skillmux core pin csv-formatter --yes
 skillmux core pin csv-formatter pdf-extractor terraform-plans --yes
 skillmux core unpin csv-formatter --yes
+skillmux core pin csv-formatter --yes --no-sync   # manifest only; sync later
 ```
 
 One or more `skill_id` arguments are accepted per call and applied
 atomically against a single in-memory manifest: if any one of them is
 already pinned elsewhere (or, for `unpin`, not currently pinned), the
-whole call fails and the manifest file is left untouched. To pin into a
+whole call fails and the manifest file is left untouched. Both commands
+then sync, so a pin reaches every target directory in one command; `--json`
+returns the per-target result in the same envelope. Pass `--no-sync` to
+write the manifest alone. A target directory this machine has never synced
+still needs its own approval, so a pin never creates one. To pin into a
 `[project.<group>]` tier instead, use `skillmux project pin` (see
 [Project Setup](#project-setup-skillmux-project-init)).
 
@@ -467,6 +475,8 @@ Named CLI contexts (`--context <name>` or `--server <url>`) support the followin
 - `skillmux eval promote --since <window>`: fetches promotable candidates from the remote server's audit db via `POST /admin/v1/eval/promote`, dedups against the local fixture file, and writes locally.
 - `skillmux doctor`: inspects remote server status, readiness, deployment runtime, and capabilities without requiring local vault access.
 
+Run on a host, `doctor` also reports `sync_drift`: a planned-but-never-performed sync naming every target directory whose contents no longer match what the manifest pins. Targets scoped to another `host` are excluded, and the check is omitted altogether in a container, which serves skills without owning a target directory.
+
 ---
 
 ## Color

package/docs/concepts.md

@@ -80,8 +80,8 @@ flowchart TD
 | Local MCP | Beside one client | stdio | Skillmux CLI |
 | Shared MCP | Server or container host | Streamable HTTP | Skillmux server (full image) |
 
-The **Skillmux CLI** is available as either the Bun package or the standalone
-Linux executable; both expose the same commands. The **full image** is the
+The **Skillmux CLI** is one native executable per platform, installed through
+npm, bun, or a direct download; every path exposes the same commands. The **full image** is the
 default Skillmux server deployment. The **slim image** is an
 advanced variant for configured remote embeddings or intentional lexical-only
 retrieval. The CLI can also serve HTTP, and Docker can serve stdio for clients

package/docs/configuration.md

@@ -297,7 +297,7 @@ project_groups = ["repo1"]           # which [project.*] groups materialize into
 ```
 
 - `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills unless `[core].limit` says otherwise; `sync` fails if a listed skill id isn't actually in the vault.
-- `[core].limit` (optional, positive integer): the cap on `[core].skills`. Absent means 25. It lives in the manifest rather than machine config so the same manifest validates identically on every machine.
+- `[core].limit` (optional, positive integer): the cap on `[core].skills`. Absent means 25. Exceeding it fails with an error naming this key, because the cap is a budget on how much skill frontmatter every agent carries in its system prompt, not a structural limit. It lives in the manifest rather than machine config so the same manifest validates identically on every machine.
 - `[project.<group>].skills`: symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
 - `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`). `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
 - `[targets.<name>]`: one entry per adopted surface. Built-in names (`agent-skills`, `claude-code`, and `codex`) derive their directories from the name and omit `dir`. A custom target requires `dir`; create one with `skillmux target add <name> --dir <dir> --yes`. `skillmux target migrate --yes` removes legacy built-in `dir` fields without touching target files. An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
@@ -313,7 +313,15 @@ skillmux core unpin csv-formatter pdf-extractor --yes                    # unpin
 skillmux project unpin repo1 pdf-extractor --yes                         # remove from a group (group stays, even if empty)
 ```
 
-Both commands accept one or more `skill_id` arguments per call; all of them are validated and applied against a single in-memory manifest before anything is written, so if any one of them is already pinned elsewhere (or, for unpin, not currently pinned), the whole call fails and the manifest file is left untouched: no partial pins. To pin into a `[project.<group>]` tier that doesn't exist yet, create it first with `skillmux project add-path <group> <path> --yes`. Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
+Both commands accept one or more `skill_id` arguments per call; all of them are validated and applied against a single in-memory manifest before anything is written, so if any one of them is already pinned elsewhere (or, for unpin, not currently pinned), the whole call fails and the manifest file is left untouched: no partial pins.
+
+Pinning syncs. Writing the manifest is only half the job, since the pin stays invisible to
+every agent until the symlinks move, so both commands run the sync themselves and report
+what each target gained or lost. Under `--json` that arrives inside the same envelope as a
+`targets` array, never as a second document. Pass `--no-sync` to write the manifest alone,
+which is what you want when batching several pins before one sync. The pin's own `--yes`
+answers "pin this skill" and is deliberately not forwarded: a target directory this machine
+has never synced still needs its own approval, so a pin can never silently create one. To pin into a `[project.<group>]` tier that doesn't exist yet, create it first with `skillmux project add-path <group> <path> --yes`. Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
 
 > **Breaking change:** `skillmux manifest pin`/`unpin` is removed. `[core]` pinning is now `skillmux core pin`/`unpin`; `[project.*]` pinning was already available as `skillmux project pin`/`unpin` and is now the only way to do it. There's no more `--path`-based inline group creation from a pin call; use `project add-path` to create the group first.
 >
@@ -326,7 +334,14 @@ Every `[core]`/`[project.*]` skill_id must resolve from the configured
 `local_vault_paths` entry (see below) fails `sync` with a distinct error, since
 the manifest is meant to be portable across machines and a machine-local
 override wouldn't exist elsewhere. `doctor` validates the manifest as part of
-its checks, surfacing any violation without writing anything back.
+its checks, surfacing any violation without writing anything back. Its `sync_drift` check
+goes one step further and plans (never performs) the sync this machine would run, naming
+every target directory whose contents no longer match what the manifest pins. A manifest
+pulled in from another machine, a `--no-sync` pin, and a hand-edit can all produce that
+gap. A target scoped to another `host` is left out, since this machine is not the one that
+syncs it, and the check is omitted entirely in a container: targets are a local delivery
+concern, and a container serving the MCP surface reads the vault to answer `resolve_skill`
+and `fetch_skill` without owning a target directory at all.
 
 ### Ownership marker
 

package/docs/deployment.md

@@ -9,9 +9,9 @@ Choose a deployment from the client count and inference source:
 | Shared MCP with local inference | Skillmux server (full image) | Streamable HTTP | Bundled GTE-small |
 | Shared MCP with remote or lexical retrieval | Skillmux server (slim image, advanced) | Streamable HTTP | Remote endpoint or lexical fallback |
 
-Install the CLI with either the Bun package or standalone Linux executable;
-they expose the same commands and can also serve HTTP. The Linux executable
-has a [pinned, checksum-verified download](getting-started.md#install-the-cli)
+Install the CLI with npm, bun, or a direct executable download; every path
+delivers the same commands and can also serve HTTP. The direct download has a
+[pinned, checksum-verified procedure](getting-started.md#standalone-executable)
 that defaults to `~/.local/bin`, plus an
 [attested GitHub CLI path](getting-started.md#install-with-github-cli-attestation).
 Deploy the full image

package/docs/getting-started.md

@@ -26,18 +26,44 @@ vault.
 
 ## Install the CLI
 
-Use the Bun package on macOS, Linux, or Windows. It requires
-[Bun 1.3 or newer](https://bun.sh/docs/installation):
+Skillmux ships as a native executable for each supported platform, so no
+runtime needs to be present. Use whichever package manager you already have:
 
 ```sh
+npm install -g @klhapp/skillmux
 bun add -g @klhapp/skillmux
-skillmux --help
+npx @klhapp/skillmux --help
 ```
 
+The package declares one `optionalDependencies` entry per platform, each
+marked with its `os` and `cpu`. npm and bun install the single entry that
+matches the current machine and skip the rest, so an install fetches one
+executable rather than five.
+
 Native target sync needs permission to create directory symlinks on Windows.
 
-Linux users can install the standalone executable without the GitHub CLI or a
-package manager. This example selects AMD64 or ARM64, downloads the pinned
+### Platform support
+
+| Platform | Executable | Local embedding inference |
+| --- | --- | --- |
+| macOS Apple Silicon | Yes | Yes |
+| macOS Intel | Yes | No, lexical recall only |
+| Linux x86-64 | Yes | Yes |
+| Linux ARM64 | Yes | Yes |
+| Windows x86-64 | Yes | Yes |
+
+Intel macOS is the one gap, and it is not a deliberate one. `onnxruntime-node`
+stopped shipping its Intel macOS binding in the 1.23 series, so there is no
+ONNX Runtime to embed for that platform. Everything else works there; only the
+embedding lane falls back to lexical recall. Configure
+[remote inference](configuration.md) if you need ranked retrieval on an Intel
+Mac. Skillmux detects the binding at build time rather than consulting a fixed
+list, so the platform regains local inference as soon as upstream restores it.
+
+### Standalone executable
+
+Every release also attaches one executable per platform, which skips package
+managers entirely. This example selects AMD64 or ARM64, downloads the pinned
 `v1.3.4` release, verifies the SHA-256 digest published for that release, and
 installs to the user-writable default `~/.local/bin`:
 
@@ -77,8 +103,7 @@ gh attestation verify "$bin_dir/$asset" --repo klhq/skillmux
 install -m755 "$bin_dir/$asset" "$bin_dir/skillmux"
 ```
 
-The Bun package and standalone Linux executable expose the same Skillmux CLI
-commands.
+Every installation path delivers the same executable and the same commands.
 
 ## Prepare a vault checkout
 

package/docs/releasing.md

@@ -35,11 +35,16 @@ accidentally republish an existing npm version.
 
 The release workflow publishes:
 
+- `@klhapp/skillmux-<platform>-<arch>` for each of the five supported
+  platforms, published before the root package
 - `@klhapp/skillmux` to the public npm registry
 - `@klhq/skillmux` to GitHub Packages, linked to this repository
 - `skillmux-linux-amd64`
 - `skillmux-linux-arm64`
-- SHA-256 digests for the Linux binaries in the GitHub Release asset metadata
+- `skillmux-darwin-arm64`
+- `skillmux-darwin-x64`
+- `skillmux-win32-x64.exe`
+- SHA-256 digests for the binaries in the GitHub Release asset metadata
 - GitHub build provenance attestations when the repository is public
 - Skillmux server full image to GHCR and Docker Hub: `:<version>`, `:<major>.<minor>`,
   and `:latest`; this variant includes GTE-small
@@ -72,7 +77,17 @@ The `production-release` GitHub environment provides the
 `DOCKERHUB_USERNAME` variable and `DOCKERHUB_TOKEN` secret. The npmjs job also
 uses this environment as its Trusted Publisher identity; configure npm with
 workflow `release-please.yml` and environment `production-release`. No
-long-lived npm token is required. The GitHub Packages job uses the workflow's
+long-lived npm token is required.
+
+The `npm-platform` job publishes the five platform packages under the same
+identity, so each of those package names needs its own Trusted Publisher entry
+with the same workflow and environment. Configure all five before the first
+release that includes them. A package name npm has never seen may need one
+manual publish before its Trusted Publisher can be configured; if so, publish
+that first version by hand and let the workflow take over from the next
+release. Order matters at publish time as well as at install time: the root
+package pins the platform packages exactly, so publishing it first would leave
+every install resolving a version that does not exist yet. The GitHub Packages job uses the workflow's
 scoped `GITHUB_TOKEN` and changes only its runner-local package name to
 `@klhq/skillmux`; the source package remains `@klhapp/skillmux` for npmjs.