@klhapp/skillmux 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.3.2](https://github.com/klhq/skillmux/compare/v1.3.1...v1.3.2) (2026-07-31)
+
+
+### Added
+
+* **doctor:** flag uncalibrated or stale inference thresholds ([#99](https://github.com/klhq/skillmux/issues/99)) ([c8f684b](https://github.com/klhq/skillmux/commit/c8f684b6aedf6788def4cdc0fe49fff233569844))
+
+
+### Chores
+
+* pin next release to 1.3.2 instead of 1.4.0 (take 2) ([#102](https://github.com/klhq/skillmux/issues/102)) ([bbbb7dd](https://github.com/klhq/skillmux/commit/bbbb7dd838d691735e797f39de7d4277b95f5187))
+
+## [1.3.1](https://github.com/klhq/skillmux/compare/v1.3.0...v1.3.1) (2026-07-31)
+
+
+### Fixed
+
+* **cli:** parse calibrate run flags correctly ([#97](https://github.com/klhq/skillmux/issues/97)) ([95d6b19](https://github.com/klhq/skillmux/commit/95d6b19272c34f7c8269cb354b7751f0fdd9ad75))
+
 ## [1.3.0](https://github.com/klhq/skillmux/compare/v1.2.0...v1.3.0) (2026-07-29)
 
 

package/README.md

@@ -10,26 +10,33 @@
 </p>
 
 Skillmux manages [`SKILL.md`](https://agentskills.io) collections across AI
-coding clients. Keep one canonical vault, pin a small set into native skill
-directories, and retrieve the rest through MCP.
+coding clients. Keep one vault source of truth, pin a small set into native
+skill directories, and retrieve the rest through MCP. On one machine, the
+source and checkout can be the same directory. In a shared deployment, each
+machine that manages native skills and the server use their own checkout; Git
+or your deployment process keeps those checkouts current.
 
 The same Skillmux CLI manages native skills and can serve local stdio MCP.
+Most individual users need only the CLI. Add Docker when you need a shared or
+always-on HTTP service.
+
 Choose a setup by the job:
 
 1. Need native skills or local MCP for one client? Install the **Skillmux CLI**.
 2. On Linux without Bun? Install the standalone Linux executable instead; it is
    the same CLI.
-3. Need one shared HTTP MCP service? Deploy the **full Docker image**—the
+3. Need one shared HTTP MCP service? Deploy the **full Docker image**, the
    self-contained default with GTE-small.
 4. Already have remote embeddings, or intentionally want lexical-only
    retrieval? Use the **slim** image; see [Deployment](docs/deployment.md).
 5. Need native pins and shared retrieval? Run the CLI on the machines that own
-   client directories and one shared server for routed retrieval.
+   client directories and one shared server for routed retrieval. MCP-only
+   clients connect over HTTP and do not need the CLI.
 
-A shared service focuses on routed retrieval; manage its mounted vault on the
-host with the CLI.
+Manage the server's vault checkout outside the container. Use the CLI for
+Skillmux operations and Git or your deployment process for replication.
 
-## One vault, three ways to use it
+## One vault source of truth, three ways to use it
 
 <p align="center">
   <img src="docs/assets/architecture.svg" alt="Three ways to use Skillmux: manage native skills, add local MCP retrieval, or run a shared MCP service" width="100%">
@@ -51,7 +58,7 @@ skillmux --help
 
 Native target sync needs permission to create directory symlinks on Windows.
 
-On Linux, you can install a compiled AMD64 or ARM64 binary instead:
+On Linux, you can install a standalone AMD64 or ARM64 executable instead:
 
 ```sh
 gh release download --repo klhq/skillmux --pattern 'skillmux-linux-*'
@@ -211,7 +218,7 @@ Skillmux preserves existing instruction files and unmanaged target content. Run
 
 ## Guarantees
 
-- **Controlled sources:** pins come from the canonical vault, while routed delivery follows the configured overlay order.
+- **Controlled sources:** pins come from the configured vault checkout, while routed delivery follows the configured overlay order.
 - **Scoped writes:** management commands write only to documented config, vault, state, and adopted target paths.
 - **Managed ownership:** sync removes only entries recorded in the target's `.skillmux` marker.
 - **Current bytes:** MCP delivery hashes the file on disk and never serves a stale indexed body.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/adapters.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { applyCalibrationRun, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
+import { applyCalibrationRun, computeCorpusFingerprint, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
 import { createClients } from "./clients";
 import { DEFAULT_CONFIG_PATH, embeddingFingerprint, expandHome, loadConfig, rerankerFingerprint } from "./config";
 import { openIndex } from "./db";
@@ -141,10 +141,12 @@ export class LocalAdapter implements TargetAdapter {
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
     const indexDb = openIndex(expandHome(config.state_dir));
     let indexedSkills: Array<{ skill_id: string; content_sha256: string }>;
+    let corpusFingerprint: string;
     try {
       indexedSkills = indexDb
         .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
         .all() as Array<{ skill_id: string; content_sha256: string }>;
+      corpusFingerprint = computeCorpusFingerprint(indexDb);
     } finally {
       indexDb.close();
     }
@@ -180,9 +182,6 @@ export class LocalAdapter implements TargetAdapter {
       throw new Error("A configured remote reranker is required to record calibration.");
     }
     const datasetText = await Bun.file(datasetFile).text();
-    const corpusFingerprint =
-      "vault:" +
-      createHash("sha256").update(JSON.stringify(indexedSkills)).digest("hex");
     const runId = `run_${crypto.randomUUID()}`;
     const db = openCalibrateDb(expandHome(config.state_dir));
     try {

package/src/calibrate.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
@@ -900,6 +901,18 @@ export interface CalibrationRunSummary {
   failed_reason?: CalibrationFailureReason;
 }
 
+/**
+ * Fingerprint the indexed vault content so calibration runs can detect
+ * corpus drift. Must match how `insertCalibrationRun` computes it at
+ * `calibrate run` time.
+ */
+export function computeCorpusFingerprint(indexDb: Database): string {
+  const indexedSkills = indexDb
+    .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
+    .all() as Array<{ skill_id: string; content_sha256: string }>;
+  return "vault:" + createHash("sha256").update(JSON.stringify(indexedSkills)).digest("hex");
+}
+
 /**
  * Open (or create) the calibration evidence database in `stateDir`.
  * Uses a separate `calibrate.sqlite3` file — never the index.sqlite3 used

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import packageJson from "../package.json" with { type: "json" };
 import { Database } from "bun:sqlite";
 import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
@@ -170,6 +171,11 @@ async function main() {
   const commandArgs = rawArgv.slice(2);
 
   const command = rawArgv[0];
+  if (command === "--version" || command === "-V") {
+    console.log(packageJson.version);
+    return;
+  }
+
   if (!command || command === "--help" || command === "-h") {
     printHelp();
     return;
@@ -446,7 +452,7 @@ async function handleCalibrateCommand(
       if (!Number.isFinite(value)) throw new Error(`${flag} must be a number`);
       return value;
     };
-    for (let i = 0; i < args.length; i++) {
+    for (let i = 1; i < args.length; i++) {
       const option = args[i];
       if (option === "--dataset") {
         datasetPath = args[++i];

package/src/doctor.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync } from "node:fs";
+import { computeCorpusFingerprint, getCalibrationRun, openCalibrateDb } from "./calibrate";
 import { createClients, RemoteInferenceError } from "./clients";
-import { embeddingDimension, expandHome } from "./config";
+import { embeddingDimension, embeddingFingerprint, expandHome, rerankerFingerprint } from "./config";
+import { openIndex } from "./db";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
 import type { Config } from "./types";
@@ -19,6 +21,78 @@ export interface DoctorReport {
   checks: DoctorCheck[];
 }
 
+/**
+ * Warn when live `inference.thresholds` didn't come from an applied
+ * `skillmux calibrate` run — e.g. hand-copied from an example config.
+ * Reranker score scales are not portable across models/adapters/corpora,
+ * so uncalibrated thresholds routinely make automatic matching unreachable
+ * without any visible error.
+ */
+function checkCalibration(config: Config): DoctorCheck {
+  const inference = config.inference;
+  if (inference.mode !== "remote") throw new Error("checkCalibration requires remote inference mode");
+  const runId = inference.calibration?.run_id;
+  if (!runId) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: "inference.thresholds are set but were never produced by `skillmux calibrate apply` — " +
+        "likely copied from an example config. Reranker scores are not portable across models, " +
+        "adapters, or corpora, so automatic matching may never trigger (or may trigger incorrectly). " +
+        "Run `skillmux calibrate`.",
+    };
+  }
+
+  const calibrateDb = openCalibrateDb(expandHome(config.state_dir));
+  let run;
+  try {
+    run = getCalibrationRun(calibrateDb, runId);
+  } finally {
+    calibrateDb.close();
+  }
+  if (!run) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `inference.calibration.run_id "${runId}" was not found in the local calibration ` +
+        "evidence store (state_dir may differ from where it was calibrated). Recalibrate.",
+    };
+  }
+  if (run.status !== "completed") {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `inference.calibration.run_id "${runId}" has status "${run.status}" and should never ` +
+        "have been applied. Recalibrate.",
+    };
+  }
+
+  const indexDb = openIndex(expandHome(config.state_dir));
+  let currentCorpusFingerprint: string;
+  try {
+    currentCorpusFingerprint = computeCorpusFingerprint(indexDb);
+  } finally {
+    indexDb.close();
+  }
+
+  const stale = [
+    rerankerFingerprint(config) !== run.reranker_fingerprint ? "reranker" : null,
+    embeddingFingerprint(config) !== run.embedding_fingerprint ? "embedding" : null,
+    currentCorpusFingerprint !== run.corpus_fingerprint ? "vault contents" : null,
+  ].filter((part): part is string => part !== null);
+
+  if (stale.length > 0) {
+    return {
+      name: "calibration",
+      ok: false,
+      detail: `applied calibration run "${runId}" is stale — ${stale.join(", ")} changed since it was ` +
+        "calibrated. Recalibrate.",
+    };
+  }
+
+  return { name: "calibration", ok: true, detail: `thresholds from applied calibration run "${runId}"` };
+}
+
 export async function diagnose(config: Config): Promise<DoctorReport> {
   const checks: DoctorCheck[] = [];
   checks.push({ name: "vault", ok: existsSync(expandHome(config.vault_path)), detail: expandHome(config.vault_path) });
@@ -129,6 +203,10 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     }
   }
 
+  if (config.inference.mode === "remote" && config.inference.reranker && config.inference.thresholds) {
+    checks.push(checkCalibration(config));
+  }
+
   const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);
   const coreReady = checks.some((check) => check.name === "vault" && check.ok)
     && checks.some((check) => check.name === "state" && check.ok);

package/src/types.ts

@@ -73,6 +73,7 @@ export interface RemoteInferenceConfig {
   embedding: RemoteEmbeddingConfig;
   reranker?: RemoteRerankerConfig;
   thresholds?: Required<Omit<Thresholds, "candidate_limit">>;
+  calibration?: { run_id: string };
 }
 
 export type InferenceConfig = LocalInferenceConfig | RemoteInferenceConfig;