@klhapp/skillmux 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.2.0](https://github.com/klhq/skillmux/compare/v1.1.0...v1.2.0) (2026-07-28)
+
+
+### Added
+
+* **calibration:** finish remote contract and docs ([f696da2](https://github.com/klhq/skillmux/commit/f696da25094c19537b1291f694114f8e4052ea69))
+* **calibration:** improve dataset quality ([#88](https://github.com/klhq/skillmux/issues/88)) ([e99b764](https://github.com/klhq/skillmux/commit/e99b764ce90b7432fca0b01c22560ba73b401dd2))
+* **calibration:** require labelled audit feedback ([16d9ec8](https://github.com/klhq/skillmux/commit/16d9ec81acbdca0e42a401b9e28f9e3814b3e0ab))
+* **calibration:** require labelled audit feedback ([#89](https://github.com/klhq/skillmux/issues/89)) ([a7a99e2](https://github.com/klhq/skillmux/commit/a7a99e2d82e619255135b1e941c69c8d6653012c))
+
+## [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

@@ -14,6 +14,7 @@ Built for agents that lack native skill triggering (Goose recipe workers, openco
 - [Docker Usage](#docker-usage)
 - [Configuration](#configuration) — inference modes, security scanning, installing skills, env vars
 - [CLI & Automation](docs/cli.md) — context management, remote target resolution, policy calibration, JSON envelopes
+- [Policy Calibration](docs/calibration.md) — labelled datasets, certification, apply lifecycle, and reference profile
 - [Benchmarks & Evaluation](#benchmarks--evaluation)
 - [FAQ & Troubleshooting](#faq--troubleshooting)
 - [Guarantees](#guarantees)
@@ -37,17 +38,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 +132,12 @@ Register with your MCP client directly, e.g.:
 
 ```json
 {
-  "mcpServers": {
-    "skillmux": {
-      "command": "skillmux",
-      "args": ["serve"]
+    "mcpServers": {
+        "skillmux": {
+            "command": "skillmux",
+            "args": ["serve"]
+        }
     }
-  }
 }
 ```
 
@@ -167,9 +168,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 +197,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 +363,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 +384,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 +421,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 +442,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 +476,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 +499,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
 
@@ -497,7 +547,11 @@ bun run src/cli.ts eval
 # hybrid recall@5:  1.000
 ```
 
-Custom policy calibration can also be performed against domain-specific query logs using `skillmux calibrate` (see [`docs/cli.md`](docs/cli.md#policy-calibration-skillmux-calibrate)).
+Custom policy calibration can also be performed against reviewed,
+domain-specific query datasets using `skillmux calibrate`. See the
+[calibration guide](docs/calibration.md) for the full operator lifecycle and
+the [CLI reference](docs/cli.md#policy-calibration-skillmux-calibrate) for
+command syntax.
 
 ## FAQ & Troubleshooting
 
@@ -506,7 +560,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,18 +7,20 @@ 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"
 
-# Required when a reranker is configured. Calibrate these for your model.
+# Optional. Without these values, reranked results remain ambiguous.
+# Calibrate locally against your corpus before enabling automatic matches.
+# See docs/calibration.md; these example values are not universal defaults.
 [inference.thresholds]
 match_score = 0.90
 match_margin = 0.30

package/docs/calibration.md

@@ -0,0 +1,106 @@
+# Policy calibration
+
+Calibration selects the three reranker-score thresholds that turn an ordered
+shortlist into `matched`, `ambiguous`, or `no_match`. It is an operator action,
+not background learning, and it currently runs only against a local Skillmux
+target.
+
+## Lifecycle
+
+The complete workflow is:
+
+```text
+install CLI → configure vault/index/embedding/reranker → obtain labelled dataset
+    → calibrate run → review calibrate show RUN_ID → calibrate apply RUN_ID
+    → live-reloaded policy handles subsequent requests
+```
+
+First configure and index the same vault, embedding model, and reranker that
+will serve requests. Supply a reviewed dataset, or generate a starting point
+and review every label:
+
+```sh
+skillmux calibrate generate-dataset --out ./eval/queries.json
+skillmux calibrate run --dataset ./eval/queries.json
+skillmux calibrate show RUN_ID
+skillmux calibrate apply RUN_ID
+```
+
+Skillmux retrieves candidates and reranks exactly once for each evaluation
+query. It caches those observations, searches thresholds on the `tune` split,
+then certifies the selected policy on the frozen `test` split. Calibration
+starts only when an operator invokes `calibrate run`.
+
+The operator owns the labels: supply or review the cases, start the run,
+inspect its evidence, and explicitly apply an acceptable result. A successful
+run never changes live thresholds by itself.
+
+## Reading a run
+
+A `run_id` identifies one immutable calibration attempt and its evidence.
+`calibrate show RUN_ID` is read-only. It reports:
+
+- selected thresholds and tune/test metrics;
+- auto-match precision confidence and sample counts;
+- retrieval and delivered-shortlist recall;
+- a closed failure reason when certification fails;
+- reranker, embedding, corpus, and dataset fingerprints;
+- dataset provenance and the number of human-labelled cases; and
+- the attempt count for the dataset hash.
+
+`calibrate apply RUN_ID` accepts only a completed, test-certified run. It
+rechecks the reranker fingerprint, rejects thresholds masked by environment
+variables, atomically updates the TOML file, and lets the config watcher
+activate the new snapshot.
+
+## Dataset responsibilities
+
+Each case needs a query, expected outcome, relevant skill ids, and a fixed
+`tune` or `test` split. Unknown skill ids are rejected. Keep a skill entirely
+within one split so the test set measures generalization rather than memorized
+skill wording.
+
+Generated datasets are scaffolding, not ground truth. Review paraphrases,
+near-miss negatives, and ambiguous cases before using them for certification.
+Audit-derived cases require an explicit human label and provenance. Raw audit
+queries are excluded unless the importer is deliberately configured to retain
+them.
+
+## When to recalibrate
+
+Re-run calibration after a material change to the corpus, embedding or
+retrieval behavior, reranker adapter or model, or after collecting enough new
+human-labelled feedback. Do not recalibrate per user request. Every rerun gets
+a new `run_id`; the active policy remains unchanged until one is applied.
+
+## Local and remote targets
+
+Calibration is local-only in this release. Local commands operate on the
+configured local vault, index, inference endpoints, dataset path, evidence
+database, and TOML file. Human output always prints `Target: local`; JSON output
+uses `"target": "local"`.
+
+Remote servers advertise `"calibration": false`. Every
+`/admin/v1/calibrations` route returns HTTP `501` with
+`error: "not_implemented"`, and the CLI rejects remote calibration before
+uploading or claiming to execute a local dataset path. This also prevents raw
+evaluation queries from being exposed through the admin API.
+
+## Reference starting profile
+
+Reranker scores are not portable across models, adapters, model revisions, or
+corpora. The profile below is published only to make the checked-in BGE example
+concrete; it is not a certified substitute for calibration.
+
+| Model | Adapter | `match_score` | `match_margin` | `candidate_floor` |
+|---|---|---:|---:|---:|
+| `BAAI/bge-reranker-v2-m3` | `jina-v1` | `0.90` | `0.20` | `0.40` |
+
+Provenance: the small synthetic corpus and labelled decision cases in
+[`tests/router-core.spec.test.ts`](../tests/router-core.spec.test.ts), with the
+wire contract captured by
+[`tests/fixtures/reranker/jina-v1-request.json`](../tests/fixtures/reranker/jina-v1-request.json).
+That fixture is below the default 30-auto-match certification minimum, so the
+values are a smoke-test/reference profile, not a completed calibration run.
+Run the lifecycle above against the deployment's real corpus before enabling
+automatic matches in production.

package/docs/configuration.md

@@ -2,7 +2,10 @@
 
 Skillmux defaults to FTS5 plus local GTE-small semantic retrieval. Most users need no config file.
 
-For detailed CLI command reference, target resolution, policy calibration, and automation envelopes, see [`docs/cli.md`](cli.md).
+For detailed CLI command reference, target resolution, and automation
+envelopes, see [`docs/cli.md`](cli.md). For labelled datasets, threshold
+certification, reference values, and the apply lifecycle, see
+[`docs/calibration.md`](calibration.md).
 
 ## Machine config bootstrap
 
@@ -51,13 +54,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,9 +99,22 @@ 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.
-
-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.
+`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. Without `inference.thresholds`, Skillmux still uses the
+reranker to order candidates but keeps outcomes ambiguous rather than
+auto-matching. Use `skillmux calibrate run` to select
+`match_score`, `match_margin`, and `candidate_floor`, then explicitly apply the
+certified run. The [calibration guide](calibration.md) also publishes a
+clearly-scoped BGE reference profile for smoke tests.
 
 ## HTTP server
 

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.2.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,
@@ -24,6 +24,7 @@
     "src",
     "docs/schema.json",
     "docs/configuration.md",
+    "docs/calibration.md",
     "docs/releasing.md",
     "README.md",
     "LICENSE",