@klhapp/skillmux 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.1.0](https://github.com/klhq/skillmux/compare/v1.0.1...v1.1.0) (2026-07-28)
+
+
+### Added
+
+* **calibration:** bind runs to reranker identity ([6ad547a](https://github.com/klhq/skillmux/commit/6ad547a97a6657521fd317d946ab941761fa18b3))
+* **calibration:** certify selected policies ([#86](https://github.com/klhq/skillmux/issues/86)) ([2ced660](https://github.com/klhq/skillmux/commit/2ced660504b7d86dcad94e801944c4e5f2c2d8bd))
+* **calibration:** finish optimizer floor sweep ([#87](https://github.com/klhq/skillmux/issues/87)) ([eed9bc3](https://github.com/klhq/skillmux/commit/eed9bc355f354aa23e6b85d157e9147484457052))
+* **calibration:** honor candidate delivery limit ([#84](https://github.com/klhq/skillmux/issues/84)) ([797d144](https://github.com/klhq/skillmux/commit/797d1443fc0d7b179716f789663220449f5c93d4))
+* **calibration:** make bootstrap reachable ([#85](https://github.com/klhq/skillmux/issues/85)) ([a572d47](https://github.com/klhq/skillmux/commit/a572d47f854e7a2be46504d069d21ccdb346d88c))
+* **config:** reload reranker transport settings ([e15c7af](https://github.com/klhq/skillmux/commit/e15c7afa9dd591f7f838c5747e86d33670afefbf))
+* **config:** require exact embedding endpoints ([3df7584](https://github.com/klhq/skillmux/commit/3df7584749cc3646713d1cb70e6901cc5aab37cc))
+* harden remote embedding clients ([11b2852](https://github.com/klhq/skillmux/commit/11b2852f8c4bf29676da168c01804460570d3061))
+* **inference:** add versioned reranker adapters ([40b85a0](https://github.com/klhq/skillmux/commit/40b85a0b4b9e9877c7eae54477f8a708737a8472))
+* **inference:** add versioned reranker protocol adapters ([#81](https://github.com/klhq/skillmux/issues/81)) ([4e44685](https://github.com/klhq/skillmux/commit/4e446857ed906888034943d4a23877f183596c04))
+* **inference:** harden embedding responses ([f850f8a](https://github.com/klhq/skillmux/commit/f850f8acfd4ab9c78e3b254346b9c2027027a04b))
+
+## [Unreleased]
+
+### ⚠ BREAKING CHANGES
+
+* **inference:** reranker configuration now requires a versioned `adapter` and
+  complete `endpoint`; the removed `provider`, `base_url`, and legacy reranker
+  base-URL environment variables fail with migration guidance.
+* **inference:** embedding configuration now requires an exact `endpoint`; the
+  removed `base_url`, `EMBED_BASE_URL`, `SKILLMUX_EMBED_BASE_URL`, and
+  `SKILL_ROUTER_EMBED_BASE_URL` inputs fail with migration guidance.
+
+### Added
+
+* **inference:** add `jina-v1` and `bifrost-v1` reranker wire-protocol adapters
+  with strict indexed-score validation and independent optional Bearer auth.
+* **inference:** validate remote and local embedding vectors before storage and
+  classify embedding and reranker failures as configuration, availability, or
+  protocol errors.
+
+### Changed
+
+* **doctor:** incomplete or malformed reranker responses now report degraded or
+  unavailable instead of silently filling missing scores with zero.
+* **config:** embedding endpoint, credential-name, and timeout changes reload
+  live; model, dimension, device, and dtype changes require restart.
+
 ## [1.0.1](https://github.com/klhq/skillmux/compare/v1.0.0...v1.0.1) (2026-07-24)
 
 

package/README.md

@@ -37,17 +37,17 @@ resolve_skill("convert this spreadsheet to markdown")
 ```
 
 - **matched** — one skill clearly wins: full `SKILL.md` delivered inline, `sha256(body) == content_sha256 ==` hash of the file on disk at delivery time. Stale index? It re-indexes and delivers fresh bytes — never stale ones.
-- **ambiguous** — up to 10 candidates (id, title, description). The calling LLM picks and calls `fetch_skill`.
+- **ambiguous** — up to 5 candidates (id, title, description). The calling LLM picks and calls `fetch_skill`.
 - **no_match** — proceed under your normal workflow; don't load an unrelated skill.
 
 If embeddings are unavailable, the router remains ready with FTS5 lexical retrieval. If an optional reranker is unavailable, it preserves the hybrid shortlist instead of failing.
 
 ### Tools
 
-| Tool | Input | Returns |
-|------|-------|---------|
-| `resolve_skill` | `query` | outcome + metadata in `structuredContent`; on match the verbatim body as text content (exactly once on the wire) |
-| `fetch_skill` | `skill_id` | verbatim body, `content_sha256`, supporting-file paths |
+| Tool            | Input      | Returns                                                                                                          |
+| --------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| `resolve_skill` | `query`    | outcome + metadata in `structuredContent`; on match the verbatim body as text content (exactly once on the wire) |
+| `fetch_skill`   | `skill_id` | verbatim body, `content_sha256`, supporting-file paths                                                           |
 
 The full contract lives in [`docs/schema.json`](docs/schema.json) (JSON Schema 2020-12, language-neutral).
 
@@ -131,12 +131,12 @@ Register with your MCP client directly, e.g.:
 
 ```json
 {
-  "mcpServers": {
-    "skillmux": {
-      "command": "skillmux",
-      "args": ["serve"]
+    "mcpServers": {
+        "skillmux": {
+            "command": "skillmux",
+            "args": ["serve"]
+        }
     }
-  }
 }
 ```
 
@@ -167,9 +167,21 @@ curl -sS -X POST http://127.0.0.1:3000/mcp \
 Against the `csv-formatter` skill authored above, that returns a real match — trimmed here for length:
 
 ```json
-{"result":{"structuredContent":{"outcome":"ambiguous","retrieval":"hybrid","candidates":[
-  {"skill_id":"csv-formatter","title":"CSV Formatter","description":"Converts CSV or spreadsheet data..."}
-]}}}
+{
+    "result": {
+        "structuredContent": {
+            "outcome": "ambiguous",
+            "retrieval": "hybrid",
+            "candidates": [
+                {
+                    "skill_id": "csv-formatter",
+                    "title": "CSV Formatter",
+                    "description": "Converts CSV or spreadsheet data..."
+                }
+            ]
+        }
+    }
+}
 ```
 
 `outcome` is `"ambiguous"` here specifically because the vault only has one skill in it — with more skills installed, a clear top match returns `"matched"` with the full `SKILL.md` body inline instead of a candidate list.
@@ -184,7 +196,7 @@ bun run src/cli.ts serve
 
 ## Pinning skills across surfaces
 
-Optional — skip this if `resolve_skill` alone is enough (most setups). Use it once you want a small set of skills loaded *statically* in every agent that reads from a given directory, instead of routed on demand — see [Tiers](#tiers-routed-vs-pinned).
+Optional — skip this if `resolve_skill` alone is enough (most setups). Use it once you want a small set of skills loaded _statically_ in every agent that reads from a given directory, instead of routed on demand — see [Tiers](#tiers-routed-vs-pinned).
 
 Run `skillmux init` with no arguments in a terminal for guided setup. It checks
 the vault, preselects clients with concrete filesystem evidence, asks for core
@@ -350,7 +362,7 @@ The `skillmux` is packaged and distributed as a Docker image in two variants:
 1. **`skillmux:latest`**: Bundles the small quantized GTE embedding model for local hybrid retrieval.
 2. **`skillmux:latest-slim`**: Excludes model weights and supports configured remote embeddings or lexical fallback.
 
-Both tags are multi-architecture manifests for Linux AMD64 and ARM64; Docker selects the correct image automatically. Images are published to both [`ghcr.io/klhq/skillmux`](https://github.com/klhq/skillmux/pkgs/container/skillmux) and [`docker.io/lazyskyline/skillmux`](https://hub.docker.com/r/lazyskyline/skillmux) — either registry works, examples below use GHCR.
+Both tags are multi-architecture manifests for Linux AMD64 and ARM64; Docker selects the correct image automatically. Images are published to both [`ghcr.io/klhq/skillmux`](https://github.com/klhq/skillmux/pkgs/container/skillmux) and [`docker.io/klhq/skillmux`](https://hub.docker.com/r/klhq/skillmux) — either registry works, examples below use GHCR.
 
 ### Running HTTP Server (Docker Default)
 
@@ -371,11 +383,12 @@ docker run -d \
   -v ~/skills:/vault:ro \
   -v skillmux-data:/data \
   -p 3000:3000 \
-  -e EMBED_BASE_URL="http://embeddings-host:8080" \
+  -e EMBED_ENDPOINT="http://embeddings-host:8080/v1/embeddings" \
   ghcr.io/klhq/skillmux:latest-slim
 ```
 
 Connect your MCP client to the HTTP endpoint (e.g. standard Streamable HTTP transport):
+
 - POST messages to `http://localhost:3000/mcp`
 
 #### HTTP server: auth, CORS, rate limiting
@@ -407,7 +420,7 @@ No config is required for the battery-included local ONNX mode. See [`config.exa
 ### Inference Modes
 
 - The zero-config default combines SQLite FTS5 with the small `Xenova/gte-small` embedding model and returns an ordered shortlist.
-- Configured OpenAI-compatible embeddings replace the local embedder. An optional Infinity-compatible reranker enables confident automatic matches.
+- Configured OpenAI-compatible embeddings replace the local embedder. An optional versioned reranker protocol adapter enables confident automatic matches without coupling configuration to a server product or URL shape.
 
 Run `skillmux doctor` to verify routing capability. Run `skillmux config show` to inspect effective configuration; it prints credential variable names, never values.
 
@@ -428,12 +441,12 @@ skillmux scan --fail-on high           # exit 1 if any finding is high severity
 The v1 rule set covers four categories, each attached to the finding as `rule_id` with a fixed
 `severity`:
 
-| `rule_id` | `severity` | Flags |
-|---|---|---|
-| `prompt-injection-phrase` | `high` | Known instruction-override phrases (e.g. "ignore previous instructions") |
-| `invisible-unicode` | `high` | Zero-width/invisible Unicode code points, including hidden tag-character payloads |
-| `secret-pattern` | `high` | Hardcoded-credential-shaped strings (AWS-style keys, PEM blocks, `api_key=`/`token=` assignments) |
-| `suspicious-url` | `medium` | Bare-IP-address URLs, or URLs paired with exfiltration-suggesting text |
+| `rule_id`                 | `severity` | Flags                                                                                             |
+| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| `prompt-injection-phrase` | `high`     | Known instruction-override phrases (e.g. "ignore previous instructions")                          |
+| `invisible-unicode`       | `high`     | Zero-width/invisible Unicode code points, including hidden tag-character payloads                 |
+| `secret-pattern`          | `high`     | Hardcoded-credential-shaped strings (AWS-style keys, PEM blocks, `api_key=`/`token=` assignments) |
+| `suspicious-url`          | `medium`   | Bare-IP-address URLs, or URLs paired with exfiltration-suggesting text                            |
 
 `skillmux scan` is unrelated to the `audit` SQLite table / `skillmux report` — that's query telemetry (what got
 routed where); `skillmux scan` is content security (what's in the vault).
@@ -462,15 +475,18 @@ core/project/routed tier assignment (that's `skillmux sync`'s domain) — it onl
 once. Use `skillmux sync` afterward if the installed skill needs to be pinned into a tier.
 
 ### Environment Variable Overrides
+
 All core settings can be overridden via environment variables (handy for Docker):
+
 - `VAULT_PATH` — overrides `vault_path` (defaults to `/vault` inside Docker)
 - `STATE_DIR` — overrides `state_dir` (defaults to `/data` inside Docker)
-- `EMBED_BASE_URL` / `SKILLMUX_EMBED_BASE_URL` — overrides remote `inference.embedding.base_url`
+- `EMBED_ENDPOINT` / `SKILLMUX_EMBED_ENDPOINT` — overrides the complete remote `inference.embedding.endpoint`
 - `EMBED_MODEL` / `SKILLMUX_EMBED_MODEL` — overrides `embedding.model`
 - `EMBED_DIMENSION` / `SKILLMUX_EMBED_DIMENSION` — overrides `embedding.dimension`
 - `EMBED_DEVICE` / `EMBED_DTYPE` — overrides local `inference.embedding.device` / `inference.embedding.dtype`
-- `RERANK_BASE_URL` / `SKILLMUX_RERANK_BASE_URL` — overrides remote `inference.reranker.base_url`
-- `RERANK_MODEL` / `SKILLMUX_RERANK_MODEL` — overrides `rerank.model`
+- `RERANK_ENDPOINT` / `SKILLMUX_RERANK_ENDPOINT` — overrides the complete remote `inference.reranker.endpoint`
+- `RERANK_ADAPTER` / `SKILLMUX_RERANK_ADAPTER` — overrides `inference.reranker.adapter`
+- `RERANK_MODEL` / `SKILLMUX_RERANK_MODEL` — overrides `inference.reranker.model`
 - `SKILLMUX_CONFIG` — path to custom `config.toml` (default `~/.config/skillmux/config.toml`)
 - `SKILLMUX_MODELS_DIR` — path to directory storing downloaded local models (default `~/.cache/skillmux/models`, `/models` inside Docker)
 - `PORT` — HTTP listen port (default `3000`, HTTP transport only)
@@ -482,7 +498,40 @@ All core settings can be overridden via environment variables (handy for Docker)
 - `HTTP_RATE_LIMIT_RPM` / `SKILLMUX_HTTP_RATE_LIMIT_RPM` — overrides `server.rate_limit.requests_per_minute`
 - `HTTP_RATE_LIMIT_TRUST_PROXY` / `SKILLMUX_HTTP_RATE_LIMIT_TRUST_PROXY` — overrides `server.rate_limit.trust_proxy` (`"true"` to trust `X-Forwarded-For`)
 
-Remote API keys are read from the environment variables named by `inference.embedding.api_key_env` and `inference.reranker.api_key_env`; no secret ever lives in the config file.
+Remote API keys are read independently from the environment variables named by
+`inference.embedding.api_key_env` and `inference.reranker.api_key_env`. Omit
+`api_key_env` for an intentionally unauthenticated endpoint. If it is present,
+the named variable must be non-empty before clients are created and is sent as
+a Bearer token. Secret values never live in the config file or diagnostics.
+
+Rerankers use an exact endpoint plus an explicit adapter. `jina-v1` sends
+string documents; `bifrost-v1` sends Bifrost document objects. Skillmux never
+infers an adapter from the URL and never adds or removes path components.
+
+Embeddings likewise use an exact endpoint and the OpenAI-compatible
+`{ model, input }` contract. Skillmux never adds `/v1/embeddings` or rewrites
+the configured path or query string. Replace the removed `base_url` setting
+with the complete endpoint, for example `base_url = "http://host"` or
+`base_url = "http://host/v1"` becomes
+`endpoint = "http://host/v1/embeddings"`. The removed `EMBED_BASE_URL`,
+`SKILLMUX_EMBED_BASE_URL`, and `SKILL_ROUTER_EMBED_BASE_URL` variables are
+startup errors with migration guidance.
+
+> **Breaking reranker migration:** replace `provider = "infinity"` with
+> `adapter = "jina-v1"`, and replace `base_url` with the complete `endpoint`.
+> The old client appended `/rerank`. For example,
+> `base_url = "http://host/v1"` becomes
+> `endpoint = "http://host/v1/rerank"`; a bare `http://host` becomes
+> `http://host/rerank`. The removed `RERANK_BASE_URL`,
+> `SKILLMUX_RERANK_BASE_URL`, and `SKILL_ROUTER_RERANK_BASE_URL` variables are
+> startup errors with migration guidance.
+
+Verified reranker contracts:
+
+| Implementation      | Tested version | Endpoint             | Adapter      | Verification                                                      |
+| ------------------- | -------------: | -------------------- | ------------ | ----------------------------------------------------------------- |
+| Bifrost             |          1.6.6 | `/v1/rerank`         | `bifrost-v1` | Live end-to-end request and recorded contract fixture, 2026-07-28 |
+| Jina-style contract |        fixture | exact configured URL | `jina-v1`    | Automated request/response contract suite                         |
 
 ## Benchmarks & Evaluation
 
@@ -506,7 +555,7 @@ Custom policy calibration can also be performed against domain-specific query lo
 
 <br>
 
-The router returns `"outcome": "ambiguous"` when multiple candidate skills meet retrieval confidence thresholds, or when no single candidate dominates by a sufficient score margin. In this state, up to 10 candidate skill summaries (`skill_id`, `title`, `description`) are returned so the calling LLM can choose the exact skill and invoke `fetch_skill`.
+The router returns `"outcome": "ambiguous"` when multiple candidate skills meet retrieval confidence thresholds, or when no single candidate dominates by a sufficient score margin. In this state, up to 5 candidate skill summaries (`skill_id`, `title`, `description`) are returned so the calling LLM can choose the exact skill and invoke `fetch_skill`.
 
 </details>
 

package/config.remote.example.toml

@@ -7,14 +7,14 @@ timeout_ms = 5000
 
 [inference.embedding]
 provider = "openai"
-base_url = "https://embedding.example.com"
+endpoint = "https://embedding.example.com/v1/embeddings"
 model = "your-embedding-model"
 dimension = 1024
 api_key_env = "EMBEDDING_API_KEY"
 
 [inference.reranker]
-provider = "infinity"
-base_url = "https://reranker.example.com"
+adapter = "jina-v1"
+endpoint = "https://reranker.example.com/v1/rerank"
 model = "your-reranker-model"
 api_key_env = "RERANKER_API_KEY"
 

package/docs/configuration.md

@@ -51,13 +51,41 @@ Use `skillmux models download` to prefetch models and `skillmux doctor` to verif
 
 ## Remote mode
 
-See [`config.remote.example.toml`](../config.remote.example.toml). Embeddings must implement the OpenAI-compatible `POST /v1/embeddings` API. Optional reranking must implement Infinity's `POST /rerank` API. Credentials are read from the environment variables named by `api_key_env`.
+See [`config.remote.example.toml`](../config.remote.example.toml). Embeddings
+must implement the OpenAI-compatible `{ model, input }` contract. Configure the
+complete request URL as `inference.embedding.endpoint`; Skillmux does not append
+or rewrite its path or query string. Optional
+reranking uses a versioned wire-protocol adapter and a complete request URL:
 
-Remote embedding `dimension` is required. Changing the provider, model, or dimension invalidates stored vectors and safely rebuilds them.
+```toml
+[inference.reranker]
+adapter = "jina-v1"
+endpoint = "https://reranker.example.com/v1/rerank"
+model = "BAAI/bge-reranker-v2-m3"
+```
+
+`jina-v1` sends documents as strings. `bifrost-v1` sends Bifrost document
+objects and requires a Bifrost-style provider-prefixed model name. Skillmux
+does not append `/rerank`, infer the adapter from the URL, or otherwise rewrite
+the endpoint.
+
+For embeddings and rerankers independently, omitting `api_key_env` sends no
+`Authorization` header. If `api_key_env` is configured, the named environment
+variable must be non-empty when configuration is loaded; Skillmux sends it as
+a Bearer token. The variable name may appear in diagnostics, but its value
+never does.
+
+Remote embedding `dimension` is required. `endpoint`, `api_key_env`, and the
+shared timeout reload live; model, dimension, device, and dtype require a
+restart. Changing only endpoint does not invalidate stored vectors.
+
+Reranker adapter and model form the calibration identity. Moving an unchanged
+deployment to another endpoint does not invalidate calibration; changing the
+adapter or model does.
 
 ## Advanced retrieval
 
-Candidate-generation depth is configurable but normally does not need tuning:
+Candidate-generation depth and agent-context delivery are separate controls:
 
 ```toml
 [recall]
@@ -68,7 +96,14 @@ k_vector = 20
 candidate_limit = 5
 ```
 
-The router considers up to 20 candidates from each retrieval lane but returns at most 5 to the calling LLM.
+`recall.k_lexical` and `recall.k_vector` control retrieval depth and cost. The
+reranker receives the fused union from both retrieval lanes. Increasing these
+values can improve retrieval recall, but costs more work.
+
+`thresholds.candidate_limit` controls agent context: it caps the ambiguous
+candidate list returned to the calling LLM after retrieval, reranking, and
+threshold filtering. It does not change retrieval depth or the matched,
+ambiguous, or no-match classification.
 
 Reranker thresholds have no universal default because score distributions are model-specific. When configuring a reranker, provide calibrated `inference.thresholds.match_score`, `inference.thresholds.match_margin`, and `inference.thresholds.candidate_floor`; otherwise configuration is rejected rather than silently applying unsuitable values.
 

package/docs/schema.json

@@ -224,23 +224,31 @@
               "type": "object",
               "properties": {
                 "provider": { "const": "openai" },
-                "base_url": { "type": "string", "format": "uri" },
+                "endpoint": {
+                  "type": "string",
+                  "format": "uri",
+                  "description": "Complete HTTP(S) OpenAI-compatible embeddings request URL. Skillmux does not modify its path."
+                },
                 "model": { "type": "string", "minLength": 1 },
                 "dimension": { "type": "integer", "minimum": 1 },
                 "api_key_env": { "type": "string", "minLength": 1 }
               },
-              "required": ["provider", "base_url", "model", "dimension"],
+              "required": ["provider", "endpoint", "model", "dimension"],
               "additionalProperties": false
             },
             "reranker": {
               "type": "object",
               "properties": {
-                "provider": { "const": "infinity" },
-                "base_url": { "type": "string", "format": "uri" },
+                "adapter": { "enum": ["jina-v1", "bifrost-v1"] },
+                "endpoint": {
+                  "type": "string",
+                  "format": "uri",
+                  "description": "Complete HTTP(S) rerank request URL. Skillmux does not modify its path."
+                },
                 "model": { "type": "string", "minLength": 1 },
                 "api_key_env": { "type": "string", "minLength": 1 }
               },
-              "required": ["provider", "base_url", "model"],
+              "required": ["adapter", "endpoint", "model"],
               "additionalProperties": false
             },
             "thresholds": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Local read-only MCP server routing natural-language task queries to skills in a SKILL.md vault, with zero-loss delivery",
   "type": "module",
   "private": false,

package/src/adapters.ts

@@ -1,8 +1,9 @@
-import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { applyCalibrationRun, getCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, type CalibrationResult } from "./calibrate";
+import { applyCalibrationRun, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, type CalibrationResult } from "./calibrate";
 import { createClients } from "./clients";
-import { DEFAULT_CONFIG_PATH, expandHome, loadConfig } from "./config";
+import { DEFAULT_CONFIG_PATH, embeddingFingerprint, expandHome, loadConfig, rerankerFingerprint } from "./config";
+import { openIndex } from "./db";
 import { CliError } from "./output";
 import {
   computeHash,
@@ -18,7 +19,7 @@ import {
   type SetConfigResult,
 } from "./config-service";
 import type { ResolvedTarget } from "./context";
-import { resolveSkill } from "./router-core";
+import { configure, retrieveAndRerank } from "./router-core";
 import type { Config } from "./types";
 
 export interface Capabilities {
@@ -43,7 +44,13 @@ export interface TargetAdapter {
   configDiff(): Promise<{ diff: Record<string, { prior: unknown; resulting: unknown }> }>;
   configSet(key: string, rawValStr: string, opts?: { dryRun?: boolean }): Promise<SetConfigResult>;
   configStatus(): Promise<ConfigStatusResponse>;
-  calibrateRun(opts?: { datasetPath?: string }): Promise<{ run_id?: string; result?: CalibrationResult }>;
+  calibrateRun(opts?: {
+    datasetPath?: string;
+    minAutoMatchPrecision?: number;
+    minRetrievalRecallAtK?: number;
+    minDeliveredShortlistRecallAtK?: number;
+    minAutoMatchCount?: number;
+  }): Promise<{ run_id?: string; result?: CalibrationResult }>;
   calibrateList(): Promise<any[]>;
   calibrateShow(runId: string): Promise<any>;
   calibrateApply(runId: string): Promise<any>;
@@ -123,26 +130,85 @@ export class LocalAdapter implements TargetAdapter {
     return getLocalConfigStatus(this.configPath);
   }
 
-  async calibrateRun(opts?: { datasetPath?: string }): Promise<{ run_id?: string; result?: CalibrationResult }> {
+  async calibrateRun(opts?: {
+    datasetPath?: string;
+    minAutoMatchPrecision?: number;
+    minRetrievalRecallAtK?: number;
+    minDeliveredShortlistRecallAtK?: number;
+    minAutoMatchCount?: number;
+  }): Promise<{ run_id?: string; result?: CalibrationResult }> {
     const config = await loadConfig(this.configPath);
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
     const cases = loadDecisionCasesFromFile(datasetFile);
     const clients = createClients(config);
+    configure({ config, clients });
     const result = await runCalibration({
       cases,
-      getCandidates: async (query: string) => {
-        const res = await resolveSkill({ query, forceLexical: false });
-        if (res.outcome === "matched") {
-          return [{ skill_id: res.skill_id, text: `${res.title} ${res.body}` }];
+      getRankedCandidates: async (query: string) => {
+        const result = await retrieveAndRerank({ query, forceLexical: false });
+        if (result.retrieval !== "reranked") {
+          throw new Error(
+            "Calibration requires successful hybrid retrieval and reranking for every query.",
+          );
         }
-        if (res.outcome === "ambiguous") {
-          return res.candidates.map((c) => ({ skill_id: c.skill_id, text: `${c.title} ${c.description}` }));
-        }
-        return [];
+        return result.candidates.map((candidate) => ({
+          skill_id: candidate.skill_id,
+          score: candidate.score ?? 0,
+        }));
       },
       reranker: clients.rerank,
+      candidateLimit: config.thresholds.candidate_limit,
+      minAutoMatchPrecision: opts?.minAutoMatchPrecision,
+      minRetrievalRecallAtK: opts?.minRetrievalRecallAtK,
+      minDeliveredShortlistRecallAtK: opts?.minDeliveredShortlistRecallAtK,
+      minAutoMatchCount: opts?.minAutoMatchCount,
     });
-    return { result };
+    const fingerprint = rerankerFingerprint(config);
+    if (!fingerprint) {
+      throw new Error("A configured remote reranker is required to record calibration.");
+    }
+    const datasetText = await Bun.file(datasetFile).text();
+    const indexDb = openIndex(expandHome(config.state_dir));
+    let corpusFingerprint: string;
+    try {
+      const rows = indexDb
+        .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
+        .all();
+      corpusFingerprint =
+        "vault:" +
+        createHash("sha256").update(JSON.stringify(rows)).digest("hex");
+    } finally {
+      indexDb.close();
+    }
+    const runId = `run_${crypto.randomUUID()}`;
+    const db = openCalibrateDb(expandHome(config.state_dir));
+    try {
+      insertCalibrationRun(db, {
+        run_id: runId,
+        created_at: new Date().toISOString(),
+        status: result.status,
+        reranker_fingerprint: fingerprint,
+        embedding_fingerprint: embeddingFingerprint(config),
+        corpus_fingerprint: corpusFingerprint,
+        dataset_hash: createHash("sha256").update(datasetText).digest("hex"),
+        candidate_limit: config.thresholds.candidate_limit,
+        min_auto_match_precision: opts?.minAutoMatchPrecision ?? 0.99,
+        min_auto_match_count: opts?.minAutoMatchCount ?? 30,
+        min_delivered_shortlist_recall_at_k:
+          opts?.minDeliveredShortlistRecallAtK ??
+          opts?.minRetrievalRecallAtK ??
+          0.95,
+        min_shortlist_recall_at_5: opts?.minRetrievalRecallAtK ?? 0.95,
+        failed_reason: result.failed_reason,
+        selected_thresholds: result.selected_thresholds,
+        tune_metrics: result.tune_metrics,
+        test_metrics: result.test_metrics,
+        observations: result.observations,
+      });
+    } finally {
+      db.close();
+    }
+    return { run_id: runId, result };
   }
 
   async calibrateList(): Promise<any[]> {
@@ -173,7 +239,9 @@ export class LocalAdapter implements TargetAdapter {
     try {
       const run = getCalibrationRun(db, runId);
       if (!run) throw new Error(`Calibration run "${runId}" not found`);
-      await applyCalibrationRun(db, runId, expandHome(this.configPath), {});
+      await applyCalibrationRun(db, runId, expandHome(this.configPath), {
+        currentRerankerFingerprint: rerankerFingerprint(config),
+      });
       return { ok: true, run_id: runId };
     } finally {
       db.close();
@@ -345,11 +413,23 @@ export class RemoteAdapter implements TargetAdapter {
     return data.runtime;
   }
 
-  async calibrateRun(opts?: { datasetPath?: string }): Promise<{ run_id?: string; result?: CalibrationResult }> {
+  async calibrateRun(opts?: {
+    datasetPath?: string;
+    minAutoMatchPrecision?: number;
+    minRetrievalRecallAtK?: number;
+    minDeliveredShortlistRecallAtK?: number;
+    minAutoMatchCount?: number;
+  }): Promise<{ run_id?: string; result?: CalibrationResult }> {
     const { status, data } = await this.fetchJson("/admin/v1/calibrations", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ dataset_path: opts?.datasetPath }),
+      body: JSON.stringify({
+        dataset_path: opts?.datasetPath,
+        min_auto_match_precision: opts?.minAutoMatchPrecision,
+        min_retrieval_recall_at_k: opts?.minRetrievalRecallAtK,
+        min_delivered_shortlist_recall_at_k: opts?.minDeliveredShortlistRecallAtK,
+        min_auto_match_count: opts?.minAutoMatchCount,
+      }),
     });
     if (status !== 202) {
       throw new Error(`Remote calibration start failed (${status}): ${data?.message || data}`);