@klhapp/skillmux 0.2.0

package/docs/configuration.md

@@ -0,0 +1,100 @@
+# Configuration
+
+Skillmux defaults to FTS5 plus local GTE-small semantic retrieval. Most users need no config file.
+
+## Local mode
+
+```toml
+[inference]
+mode = "local"
+```
+
+The versioned `gte-small-v1` bundle uses normalized, mean-pooled `Xenova/gte-small` embeddings (384 dimensions), quantized to q8 on CPU. Models are cached in `~/.cache/skillmux/models`. FTS5 and cosine result lists are combined with reciprocal-rank fusion; without a reranker the calling LLM selects from the ordered shortlist.
+
+Advanced local overrides:
+
+```toml
+[inference]
+mode = "local"
+models_dir = "~/.cache/skillmux/models"
+
+[inference.embedding]
+model = "Xenova/gte-small"
+dimension = 384
+device = "cpu"
+dtype = "q8"
+
+```
+
+Use `skillmux models download` to prefetch models and `skillmux doctor` to verify readiness.
+
+## 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`.
+
+Remote embedding `dimension` is required. Changing the provider, model, or dimension invalidates stored vectors and safely rebuilds them.
+
+## Advanced retrieval
+
+Candidate-generation depth is configurable but normally does not need tuning:
+
+```toml
+[recall]
+k_lexical = 20
+k_vector = 20
+
+[thresholds]
+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.
+
+## HTTP server
+
+```toml
+[server]
+hostname = "127.0.0.1"
+auth_enabled = false
+auth_token_env = "SKILLMUX_AUTH_TOKEN"
+allowed_origins = []
+
+[server.rate_limit]
+enabled = false
+requests_per_minute = 60
+trust_proxy = false
+```
+
+Defaults are loopback-only (`hostname = "127.0.0.1"`) with CORS deny-by-default (`allowed_origins = []`) — a zero-config `skillmux serve --transport http` is not reachable from the network or from a browser tab on another origin. Docker sets `hostname` to `0.0.0.0` automatically (`RUNNING_IN_DOCKER=true`) since port-mapping needs the container to accept connections on all interfaces.
+
+Before exposing HTTP beyond localhost, set `hostname` to a reachable interface, `auth_enabled = true` with a token, and populate `allowed_origins` with the specific origins that need browser access. `rate_limit.trust_proxy` should stay `false` unless a trusted reverse proxy sets `X-Forwarded-For` — it's otherwise a client-controlled, spoofable header and trusting it defeats per-client rate limiting.
+
+## Tiers and the manifest
+
+`skillmux init`/`sync` manage an optional second delivery path — pinning a subset of skills as real symlinks inside an agent's own skill directory, instead of routing every request through `resolve_skill`. See the README's [Tiers](../README.md#tiers-routed-vs-pinned) section for the concept and a walkthrough; this is the manifest reference.
+
+### `skillmux.toml`
+
+Lives at the vault root (a legacy `skr.toml` is still read if present, never written):
+
+```toml
+[core]
+skills = ["csv-formatter"]           # pinned into every [targets.*] dir; capped at 25
+
+[project.repo1]
+repos = ["/Users/you/code/repo1"]    # only synced for repos paths that exist locally
+skills = ["pdf-extractor"]           # must not overlap [core]
+
+[targets.claude]
+dir = "/Users/you/.claude/skills"
+project = false                      # true = also apply [project.*] groups scoped to this target
+```
+
+- `[core].skills` — symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
+- `[project.<group>].skills` — symlinked only into `<repo>/<relative path from $HOME to the target dir>`, for each `repos` entry, and only for targets with `project = true`. `repos` 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.
+- `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these; hand-editing is fine as long as `sync` is still allowed to own the directory (see below).
+
+### Ownership marker
+
+Every directory `sync` manages gets a `.skillmux` marker file (`{"managed_by": "skillmux", "target": "<name>", "created_at": ...}`). `sync` refuses to touch a directory that exists but has no marker — run `skillmux init --target <name> --yes` first, which either creates the directory fresh or adopts an existing one in place (contents untouched). This is also why `sync --restore-monolith` (which deletes the marker and replaces the whole directory with one symlink straight to the vault) requires re-running `init` before that target can be `sync`'d again.

package/docs/releasing.md

@@ -0,0 +1,62 @@
+# Releasing
+
+Releases are created from version tags after `main` is green.
+
+## Prepare
+
+1. Update `version` in `package.json`.
+2. Move relevant entries from `Unreleased` into a dated version section in `CHANGELOG.md`.
+3. Merge those changes through a pull request and confirm CI passes.
+
+## Publish
+
+Create and push the matching tag:
+
+```bash
+git switch main
+git pull --ff-only
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+The tag must exactly match `v` plus the `package.json` version. A mismatch stops the release.
+
+The release workflow publishes:
+
+- `skillmux-linux-amd64`
+- `skillmux-linux-arm64`
+- `SHA256SUMS`
+- GitHub build provenance attestations when the repository is public
+- Full image: `:<version>`, `:<major>.<minor>`, `:<major>`, and `:latest`
+- Slim image: `:<version>-slim`, `:<major>.<minor>-slim`, `:<major>-slim`, and `:latest-slim`
+- Multi-architecture `linux/amd64` and `linux/arm64` images with SBOM and provenance
+
+Each Docker tag is a multi-architecture manifest. Users run the same tag on AMD64 and ARM64; Docker automatically pulls the matching image.
+
+Container images are published to GitHub Container Registry only; the release workflow does not require external registry credentials.
+Private repositories still publish BuildKit SBOM/provenance with container images, but GitHub artifact attestations are skipped because GitHub does not support them for user-owned private repositories.
+
+Verify downloaded binaries with:
+
+```bash
+sha256sum --check SHA256SUMS
+./skillmux-linux-amd64 config show
+```
+
+Verify release assets from GitHub without cloning the repository:
+
+```bash
+gh release download v0.1.1 --repo klhq/skillmux
+sha256sum --check SHA256SUMS
+```
+
+Verify the container with a read-only vault mount:
+
+```bash
+docker run --rm \
+  -v ~/.agents/skills:/vault:ro \
+  -p 3000:3000 \
+  ghcr.io/klhq/skillmux:latest
+
+curl --fail http://127.0.0.1:3000/health/ready
+```

package/docs/schema.json

@@ -0,0 +1,314 @@
+{
+  "$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.",
+  "$defs": {
+    "SkillId": {
+      "type": "string",
+      "description": "Vault directory name of the skill (~/.agents/skills/<skill_id>/SKILL.md).",
+      "pattern": "^[a-z0-9][a-z0-9-]{1,127}$"
+    },
+    "Sha256Hex": {
+      "type": "string",
+      "description": "Lowercase hex SHA-256 of the exact SKILL.md bytes.",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "RelativePath": {
+      "type": "string",
+      "description": "Path of a supporting file relative to the skill directory (e.g. 'references/palette.md'). Never absolute, never contains '..'.",
+      "pattern": "^(?!/)(?!.*\\.\\.).+$",
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "Candidate": {
+      "type": "object",
+      "description": "One shortlist entry in an ambiguous result.",
+      "properties": {
+        "skill_id": { "$ref": "#/$defs/SkillId" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "description": { "type": "string", "minLength": 1 }
+      },
+      "required": ["skill_id", "title", "description"],
+      "additionalProperties": false
+    },
+    "ResolveSkillInput": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Natural-language task description to route. Normalized (NFC) by the server; never semantically rewritten.",
+          "minLength": 1,
+          "maxLength": 8192
+        }
+      },
+      "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"] },
+        "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
+        }
+      },
+      "required": ["outcome", "retrieval", "skill_id", "title", "content_sha256", "score", "margin", "body", "files"],
+      "additionalProperties": false
+    },
+    "AmbiguousResult": {
+      "type": "object",
+      "description": "Several plausible candidates; the calling LLM picks, then calls fetch_skill.",
+      "properties": {
+        "outcome": { "const": "ambiguous" },
+        "retrieval": { "enum": ["exact", "reranked", "hybrid", "lexical"] },
+        "candidates": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Candidate" },
+          "minItems": 1,
+          "maxItems": 5
+        }
+      },
+      "required": ["outcome", "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"] },
+        "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": {
+        "skill_id": { "$ref": "#/$defs/SkillId" }
+      },
+      "required": ["skill_id"],
+      "additionalProperties": false
+    },
+    "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.",
+      "properties": {
+        "skill_id": { "$ref": "#/$defs/SkillId" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "content_sha256": { "$ref": "#/$defs/Sha256Hex" },
+        "body": { "type": "string", "minLength": 1 },
+        "files": {
+          "type": "array",
+          "description": "Relative paths of supporting files under the skill directory (references/, scripts/, ...). Paths only; callers with filesystem access read contents directly.",
+          "items": { "$ref": "#/$defs/RelativePath" },
+          "uniqueItems": true
+        }
+      },
+      "required": ["skill_id", "title", "content_sha256", "body", "files"],
+      "additionalProperties": false
+    },
+    "ErrorCode": {
+      "type": "string",
+      "description": "Machine-readable code carried in MCP ToolError messages as 'CODE: human message'.",
+      "enum": ["SKILL_NOT_FOUND", "VAULT_UNAVAILABLE", "INTERNAL"]
+    },
+    "Config": {
+      "type": "object",
+      "description": "config.toml, validated at startup. Local ONNX is the default; remote inference is explicit.",
+      "properties": {
+        "vault_path": {
+          "type": "string",
+          "description": "Skill vault root. Default: ~/.agents/skills",
+          "default": "~/.agents/skills"
+        },
+        "state_dir": {
+          "type": "string",
+          "description": "All router writes are confined here (AC9): index SQLite (incl. audit log), vector matrix.",
+          "default": "~/.local/state/skillmux"
+        },
+        "recall": {
+          "type": "object",
+          "properties": {
+            "k_lexical": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+            "k_vector": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
+          },
+          "required": ["k_lexical", "k_vector"],
+          "additionalProperties": false
+        },
+        "thresholds": {
+          "type": "object",
+          "description": "Caller-facing shortlist policy. Reranker thresholds live under inference.thresholds.",
+          "properties": {
+            "candidate_limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50,
+              "default": 5,
+              "description": "Maximum number of candidates returned on ambiguous outcomes (top-k limit)."
+            }
+          },
+          "required": ["candidate_limit"],
+          "additionalProperties": false
+        },
+        "inference": { "$ref": "#/$defs/InferenceConfig" },
+        "server": { "$ref": "#/$defs/ServerConfig" }
+      },
+      "required": ["vault_path", "state_dir", "recall", "thresholds", "inference"],
+      "additionalProperties": false
+    },
+    "InferenceConfig": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "mode": { "const": "local" },
+            "bundle": { "const": "gte-small-v1" },
+            "models_dir": { "type": "string", "default": "~/.cache/skillmux/models" },
+            "embedding": {
+              "type": "object",
+              "properties": {
+                "model": { "const": "Xenova/gte-small" },
+                "dimension": { "const": 384 },
+                "device": { "type": "string" },
+                "dtype": { "type": "string" }
+              },
+              "required": ["model", "dimension"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["mode", "bundle", "models_dir", "embedding"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "mode": { "const": "remote" },
+            "timeout_ms": { "type": "integer", "minimum": 100, "maximum": 30000, "default": 2000 },
+            "embedding": {
+              "type": "object",
+              "properties": {
+                "provider": { "const": "openai" },
+                "base_url": { "type": "string", "format": "uri" },
+                "model": { "type": "string", "minLength": 1 },
+                "dimension": { "type": "integer", "minimum": 1 },
+                "api_key_env": { "type": "string", "minLength": 1 }
+              },
+              "required": ["provider", "base_url", "model", "dimension"],
+              "additionalProperties": false
+            },
+            "reranker": {
+              "type": "object",
+              "properties": {
+                "provider": { "const": "infinity" },
+                "base_url": { "type": "string", "format": "uri" },
+                "model": { "type": "string", "minLength": 1 },
+                "api_key_env": { "type": "string", "minLength": 1 }
+              },
+              "required": ["provider", "base_url", "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"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "ServerConfig": {
+      "type": "object",
+      "properties": {
+        "auth_enabled": { "type": "boolean", "default": false },
+        "auth_token_env": { "type": "string", "default": "SKILLMUX_AUTH_TOKEN" },
+        "allowed_origins": { "type": "array", "items": { "type": "string" }, "default": ["*"] },
+        "rate_limit": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "requests_per_minute": { "type": "integer", "minimum": 1, "default": 60 }
+          },
+          "required": ["enabled", "requests_per_minute"],
+          "additionalProperties": false
+        }
+      },
+      "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"] },
+        "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/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@klhapp/skillmux",
+  "version": "0.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,
+  "author": "Lance Hsu <lance@klh.app>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/klhq/skillmux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/klhq/skillmux/issues"
+  },
+  "homepage": "https://github.com/klhq/skillmux#readme",
+  "bin": {
+    "skillmux": "./src/cli.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "docs/schema.json",
+    "docs/configuration.md",
+    "docs/releasing.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "config.example.toml",
+    "config.remote.example.toml"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "serve": "bun run src/cli.ts serve",
+    "index": "bun run src/cli.ts index",
+    "eval": "bun run src/cli.ts eval",
+    "doctor": "bun run src/cli.ts doctor",
+    "models:download": "bun run src/cli.ts models download",
+    "build": "bun build --compile src/cli.ts --outfile dist/skillmux"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.14"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "trustedDependencies": [
+    "onnxruntime-node",
+    "protobufjs"
+  ]
+}

package/src/audit.ts

@@ -0,0 +1,15 @@
+import type { AuditRow } from "./types";
+
+/** Shape an audit row to exactly the schema's AuditRow fields — nothing extra survives. */
+export function buildAuditRow(row: AuditRow): AuditRow {
+  return {
+    id: row.id,
+    ts: row.ts,
+    query: row.query,
+    outcome: row.outcome,
+    retrieval: row.retrieval,
+    candidates: row.candidates.map((c) => ({ skill_id: c.skill_id, score: c.score })),
+    selected_skill_id: row.selected_skill_id,
+    latency_ms: row.latency_ms,
+  };
+}