@klhapp/skillmux 1.6.0 → 1.7.0

package/docs/schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://klh.app/schemas/skillmux/router-core.json",
   "title": "Skillmux — router-core contract",
-  "description": "Typed contract for the skillmux MCP server: tool inputs/outputs, config.toml, and audit-log rows. The SKILL.md body must appear exactly once on the wire.",
+  "description": "Typed contract for the skillmux MCP server: tool inputs/outputs and config.toml. The SKILL.md body must appear exactly once on the wire.",
   "$defs": {
     "SkillId": {
       "type": "string",
@@ -33,15 +33,26 @@
         "reranker_protocol_error"
       ]
     },
-    "Candidate": {
+    "RankedCandidate": {
       "type": "object",
-      "description": "One shortlist entry in an ambiguous result.",
+      "description": "One ranked candidate in the resolution shortlist.",
       "properties": {
+        "rank": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "One-based position in the returned ranked list."
+        },
         "skill_id": { "$ref": "#/$defs/SkillId" },
-        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
-        "description": { "type": "string", "minLength": 1 }
+        "description": {
+          "type": "string",
+          "description": "Compact skill description used by the caller to choose."
+        },
+        "score": {
+          "type": ["number", "null"],
+          "description": "Final ranking score (null when score values are unavailable for the retrieval lane)."
+        }
       },
-      "required": ["skill_id", "title", "description"],
+      "required": ["rank", "skill_id", "description", "score"],
       "additionalProperties": false
     },
     "ResolveSkillInput": {
@@ -51,89 +62,32 @@
           "type": "string",
           "description": "Natural-language task description to route. Normalized (NFC) by the server; never semantically rewritten.",
           "minLength": 1
-        }
-      },
-      "required": ["query"],
-      "additionalProperties": false
-    },
-    "MatchedResult": {
-      "type": "object",
-      "description": "One reranked candidate clearly dominates. Full SKILL.md is delivered inline.",
-      "properties": {
-        "outcome": { "const": "matched" },
-        "retrieval": { "enum": ["exact", "reranked"] },
-        "degraded_from": { "enum": ["reranked", "hybrid"] },
-        "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
-        "skill_id": { "$ref": "#/$defs/SkillId" },
-        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
-        "content_sha256": { "$ref": "#/$defs/Sha256Hex" },
-        "score": {
-          "type": "number",
-          "description": "Top configured-reranker score. Satisfies score >= config thresholds.match_score."
-        },
-        "margin": {
-          "type": "number",
-          "description": "Top minus second configured-reranker score. Equals score when there is exactly one candidate.",
-          "minimum": 0
-        },
-        "body": {
-          "type": "string",
-          "description": "Verbatim UTF-8 content of SKILL.md. sha256(body bytes) == content_sha256 == hash of the on-disk file read at delivery time.",
-          "minLength": 1
         },
-        "files": {
-          "type": "array",
-          "description": "Relative paths of the skill's supporting files (contents NOT included). Same semantics as FetchSkillResult.files.",
-          "items": { "$ref": "#/$defs/RelativePath" },
-          "uniqueItems": true
+        "top_k": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional maximum number of ranked candidates to return, bounded by server output.max_top_k."
         }
       },
-      "required": ["outcome", "retrieval", "skill_id", "title", "content_sha256", "score", "margin", "body", "files"],
+      "required": ["query"],
       "additionalProperties": false
     },
-    "AmbiguousResult": {
+    "ResolveSkillResult": {
       "type": "object",
-      "description": "Several plausible candidates; the calling LLM picks, then calls fetch_skill.",
+      "description": "Ranked candidates response from resolve_skill.",
       "properties": {
-        "outcome": { "const": "ambiguous" },
         "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
         "degraded_from": { "enum": ["reranked", "hybrid"] },
         "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
         "candidates": {
           "type": "array",
-          "items": { "$ref": "#/$defs/Candidate" },
-          "minItems": 1,
-          "maxItems": 5
+          "items": { "$ref": "#/$defs/RankedCandidate" },
+          "description": "Shortlist of candidates in descending score order with contiguous 1-based ranks."
         }
       },
-      "required": ["outcome", "retrieval", "candidates"],
+      "required": ["retrieval", "candidates"],
       "additionalProperties": false
     },
-    "NoMatchResult": {
-      "type": "object",
-      "description": "AC4: no skill passed the relevance floor. Caller proceeds under its normal workflow; must not load an unrelated skill.",
-      "properties": {
-        "outcome": { "const": "no_match" },
-        "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
-        "degraded_from": { "enum": ["reranked", "hybrid"] },
-        "degradation_reason": { "$ref": "#/$defs/DegradationReason" },
-        "message": {
-          "type": "string",
-          "description": "Fixed guidance string telling the caller to proceed normally.",
-          "minLength": 1
-        }
-      },
-      "required": ["outcome", "retrieval", "message"],
-      "additionalProperties": false
-    },
-    "ResolveSkillResult": {
-      "description": "AC1: exactly three outcomes, discriminated by 'outcome'.",
-      "oneOf": [
-        { "$ref": "#/$defs/MatchedResult" },
-        { "$ref": "#/$defs/AmbiguousResult" },
-        { "$ref": "#/$defs/NoMatchResult" }
-      ]
-    },
     "FetchSkillInput": {
       "type": "object",
       "properties": {
@@ -144,7 +98,7 @@
     },
     "FetchSkillResult": {
       "type": "object",
-      "description": "AC5: verbatim delivery independent of any prior resolve outcome. Unknown skill_id raises ToolError with code SKILL_NOT_FOUND instead of returning this shape.",
+      "description": "AC5: verbatim delivery independent of any prior resolve_skill call. Unknown skill_id raises ToolError with code SKILL_NOT_FOUND instead of returning this shape.",
       "properties": {
         "skill_id": { "$ref": "#/$defs/SkillId" },
         "title": { "type": "string", "minLength": 1, "maxLength": 512 },
@@ -208,34 +162,26 @@
         "output": {
           "type": "object",
           "properties": {
-            "ambiguous_candidate_limit": {
+            "top_k": {
               "type": "integer",
               "minimum": 1,
-              "maximum": 50,
-              "default": 5,
-              "description": "Maximum number of candidates returned on ambiguous outcomes."
-            }
-          },
-          "additionalProperties": false
-        },
-        "thresholds": {
-          "type": "object",
-          "description": "Caller-facing shortlist policy (deprecated in favor of output.ambiguous_candidate_limit). Reranker thresholds live under inference.thresholds.",
-          "properties": {
-            "candidate_limit": {
+              "default": 10,
+              "description": "Default maximum number of candidates returned by resolve_skill."
+            },
+            "max_top_k": {
               "type": "integer",
               "minimum": 1,
-              "maximum": 50,
-              "default": 5,
-              "description": "Deprecated: use output.ambiguous_candidate_limit instead."
+              "default": 50,
+              "description": "Upper bound for per-request top_k override."
             }
           },
+          "required": ["top_k", "max_top_k"],
           "additionalProperties": false
         },
         "inference": { "$ref": "#/$defs/InferenceConfig" },
         "server": { "$ref": "#/$defs/ServerConfig" }
       },
-      "required": ["vault_path", "state_dir", "recall", "inference"],
+      "required": ["vault_path", "state_dir", "recall", "output", "inference"],
       "additionalProperties": false
     },
     "InferenceConfig": {
@@ -296,17 +242,6 @@
               },
               "required": ["adapter", "endpoint", "model"],
               "additionalProperties": false
-            },
-            "thresholds": {
-              "type": "object",
-              "description": "Model-specific calibrated values; required when reranker is configured.",
-              "properties": {
-                "match_score": { "type": "number" },
-                "match_margin": { "type": "number", "minimum": 0 },
-                "candidate_floor": { "type": "number" }
-              },
-              "required": ["match_score", "match_margin", "candidate_floor"],
-              "additionalProperties": false
             }
           },
           "required": ["mode", "timeout_ms", "embedding"],
@@ -332,43 +267,6 @@
       },
       "required": ["auth_enabled", "auth_token_env", "allowed_origins"],
       "additionalProperties": false
-    },
-    "AuditRow": {
-      "type": "object",
-      "description": "AC10: one row per resolve_skill call, appended to the audit table in the state-dir SQLite. Raw query stored deliberately (single-user private homelab).",
-      "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "ts": { "type": "string", "format": "date-time" },
-        "query": { "type": "string" },
-        "outcome": { "type": "string", "enum": ["matched", "ambiguous", "no_match"] },
-        "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
-        "degraded_from": {
-          "oneOf": [{ "enum": ["reranked", "hybrid"] }, { "type": "null" }]
-        },
-        "degradation_reason": {
-          "oneOf": [{ "$ref": "#/$defs/DegradationReason" }, { "type": "null" }]
-        },
-        "candidates": {
-          "type": "array",
-          "description": "skill_id + score of every reranked (or FTS5-ranked) candidate considered, best first.",
-          "items": {
-            "type": "object",
-            "properties": {
-              "skill_id": { "$ref": "#/$defs/SkillId" },
-              "score": { "type": ["number", "null"] }
-            },
-            "required": ["skill_id", "score"],
-            "additionalProperties": false
-          }
-        },
-        "selected_skill_id": {
-          "oneOf": [{ "$ref": "#/$defs/SkillId" }, { "type": "null" }],
-          "description": "Set iff outcome=matched."
-        },
-        "latency_ms": { "type": "integer", "minimum": 0 }
-      },
-      "required": ["id", "ts", "query", "outcome", "retrieval", "candidates", "selected_skill_id", "latency_ms"],
-      "additionalProperties": false
     }
   }
 }

package/docs/skill-management.md

@@ -170,8 +170,13 @@ skillmux report --since 7d
 skillmux report --server http://host:3000 --since 7d
 ```
 
-Repeatedly matched skills may belong in core or a project group. Repeated
-`no_match` queries point to missing skills or weak skill descriptions.
+`skillmux report` aggregates total requests, empty shortlist count and rate,
+retrieval totals across lanes (`exact`, `reranked`, `hybrid`, `lexical`), degraded
+request counts, average latency in milliseconds, per-skill `candidate_count`, and
+`top_empty_shortlist_queries`.
+
+Skills with high candidate counts may belong in `[core]` or a project group.
+Top empty shortlist queries point to missing skills or weak skill descriptions.
 
 `--since` accepts windows such as `1h`, `7d`, and `1m`, plus absolute dates and
 timestamps.

package/docs/troubleshooting.md

@@ -17,7 +17,7 @@ file or an existing `~/.config/skillmux` directory. If you need a specific
 vault, remote inference, or HTTP policy, create a config with `skillmux config
 init --vault ~/skills --yes`; otherwise the server uses its defaults. A missing
 optional config parent disables live reload until the next server start. For a
-malformed watched config, check the reported reload error—the running server
+malformed watched config, check the reported reload error: the running server
 continues with its last known good configuration.
 
 ## Docker rejected a CLI command
@@ -25,7 +25,7 @@ continues with its last known good configuration.
 The server image can inspect and serve a mounted vault, but it cannot manage
 agent directories or mutate host configuration. Its help lists the supported
 server commands. For `init`, `sync`, install or pin management, model
-downloads, contexts, calibration, evaluation, project/target/local-vault
+downloads, contexts, evaluation, project/target/local-vault
 management, or `config init`/`config set`, install and use the host CLI:
 
 ```sh
@@ -149,20 +149,15 @@ overlay.
 
 ## Retrieval failures
 
-### `resolve_skill` returns `ambiguous`
+### Candidates are missing or irrelevant
 
-Ambiguity is the expected result without calibrated reranker thresholds. The
-calling model should select a candidate and call `fetch_skill`.
+`resolve_skill` returns ranked candidate summaries for the calling model to
+review. If the shortlist is empty (`candidates: []`) or missing an expected skill:
 
-Improve a weak shortlist by:
-
-- writing a concrete skill description with task vocabulary;
-- enabling embeddings;
-- increasing recall depth when the relevant skill falls outside the fused
-  candidate set.
-
-Use a labelled dataset and [Policy calibration](calibration.md) before enabling
-automatic matches.
+- write a concrete skill description with specific task vocabulary and user intents in `SKILL.md`;
+- verify embeddings are active with `skillmux doctor`;
+- increase candidate recall depth in `[recall]` (`k_lexical`, `k_vector`, or `k_rerank`);
+- evaluate ranking quality against a labelled dataset with `skillmux eval` (see [Ranked-shortlist migration](ranked-shortlist-migration.md)).
 
 ### Server reports lexical mode
 
@@ -256,6 +251,9 @@ checking for a retry loop or shared-token traffic.
 
 Skillmux rejects removed fields with migration guidance:
 
+- replace obsolete `[thresholds]` table and `inference.thresholds` with `[output]` and `top_k`;
+- replace obsolete `output.ambiguous_candidate_limit` with `output.top_k`;
+- remove obsolete `inference.calibration` and use `skillmux eval` for ranking evaluation;
 - replace `[targets.<name>].project` with `project_groups = [...]`;
 - rename `[project.<group>].repos` to `paths`;
 - use `skillmux core pin|unpin` instead of removed `manifest pin|unpin`;

package/package.json

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