@klhapp/skillmux 0.2.0

package/src/doctor.ts

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { createClients } from "./clients";
+import { embeddingDimension, expandHome } from "./config";
+import type { Config } from "./types";
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface DoctorReport {
+  mode: Config["inference"]["mode"];
+  capability: "hybrid" | "lexical-only" | "unavailable";
+  checks: DoctorCheck[];
+}
+
+export async function diagnose(config: Config): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = [];
+  checks.push({ name: "vault", ok: existsSync(expandHome(config.vault_path)), detail: expandHome(config.vault_path) });
+
+  try {
+    mkdirSync(expandHome(config.state_dir), { recursive: true });
+    const probe = Bun.file(expandHome(`${config.state_dir}/.doctor`));
+    await probe.write("");
+    await probe.delete();
+    checks.push({ name: "state", ok: true, detail: expandHome(config.state_dir) });
+  } catch (error) {
+    checks.push({ name: "state", ok: false, detail: String(error) });
+  }
+
+  if (config.inference.mode === "local") {
+    try {
+      mkdirSync(expandHome(config.inference.models_dir), { recursive: true });
+      checks.push({ name: "models", ok: true, detail: expandHome(config.inference.models_dir) });
+    } catch (error) {
+      checks.push({ name: "models", ok: false, detail: String(error) });
+    }
+  }
+
+  try {
+    const clients = createClients(config);
+    const vectors = await clients.embed(["skill router diagnostic"]);
+    const actualDimension = vectors[0]?.length ?? 0;
+    checks.push({
+      name: "embedding",
+      ok: actualDimension === embeddingDimension(config),
+      detail: `dimension ${actualDimension}`,
+    });
+    if (clients.rerank) {
+      const scores = await clients.rerank("skill router diagnostic", [
+        { skill_id: "doctor", text: "Routes a task to an appropriate skill." },
+      ]);
+      checks.push({ name: "reranker", ok: scores.length === 1 && Number.isFinite(scores[0]), detail: "one finite score" });
+    }
+  } catch (error) {
+    checks.push({ name: "inference", ok: false, detail: String(error) });
+  }
+
+  const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);
+  const coreReady = checks.some((check) => check.name === "vault" && check.ok)
+    && checks.some((check) => check.name === "state" && check.ok);
+  return {
+    mode: config.inference.mode,
+    capability: !coreReady ? "unavailable" : inferenceReady ? "hybrid" : "lexical-only",
+    checks,
+  };
+}

package/src/eval.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { SkillRow } from "./db";
+import { ftsSearch, vectorTopK } from "./db";
+import { reciprocalRankFusion } from "./rrf";
+import { backfillEmbeddings, getRuntime } from "./router-core";
+
+export interface EvalCase {
+  query: string;
+  expected: string[];
+}
+
+const evalCasesSchema = z.array(z.object({
+  query: z.string().min(1),
+  expected: z.array(z.string().min(1)).min(1),
+}).strict());
+
+export interface EvalMetrics {
+  recall_at_3: number;
+  recall_at_5: number;
+  mrr: number;
+}
+
+export interface EvalReport {
+  queries: number;
+  lexical: EvalMetrics;
+  hybrid: EvalMetrics;
+}
+
+function metrics(rankings: string[][], cases: EvalCase[]): EvalMetrics {
+  if (cases.length === 0) return { recall_at_3: 0, recall_at_5: 0, mrr: 0 };
+  let recall3 = 0;
+  let recall5 = 0;
+  let reciprocalRanks = 0;
+  rankings.forEach((ranking, index) => {
+    const expected = new Set(cases[index]!.expected);
+    if (ranking.slice(0, 3).some((id) => expected.has(id))) recall3++;
+    if (ranking.slice(0, 5).some((id) => expected.has(id))) recall5++;
+    const rank = ranking.findIndex((id) => expected.has(id));
+    if (rank >= 0) reciprocalRanks += 1 / (rank + 1);
+  });
+  return {
+    recall_at_3: recall3 / cases.length,
+    recall_at_5: recall5 / cases.length,
+    mrr: reciprocalRanks / cases.length,
+  };
+}
+
+export function loadEvalCases(path = join(import.meta.dir, "..", "eval", "queries.json")): EvalCase[] {
+  return evalCasesSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export async function evalVault(cases = loadEvalCases()): Promise<EvalReport> {
+  const { config, db, clients } = await getRuntime();
+  if (config.inference.mode !== "local") throw new Error('Default evaluation requires inference.mode = "local".');
+  await backfillEmbeddings();
+
+  const lexicalRankings: string[][] = [];
+  const hybridRankings: string[][] = [];
+  for (const evalCase of cases) {
+    const lexical = ftsSearch(db, evalCase.query, config.recall.k_lexical);
+    const vector = (await clients.embed([evalCase.query]))[0]!;
+    const semantic = vectorTopK(db, vector, config.recall.k_vector);
+    lexicalRankings.push(lexical.map((row) => row.skill_id));
+    hybridRankings.push(reciprocalRankFusion<SkillRow>(lexical, semantic).map((row) => row.skill_id));
+  }
+
+  return {
+    queries: cases.length,
+    lexical: metrics(lexicalRankings, cases),
+    hybrid: metrics(hybridRankings, cases),
+  };
+}

package/src/init.ts

@@ -0,0 +1,122 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { serializeManifest, type Manifest, MANIFEST_FILENAME } from "./manifest";
+import { adoptTarget, readSkillmuxMarker } from "./sync";
+import { SKILL_ID_PATTERN } from "./vault";
+
+export const DEFAULT_SURFACE_CANDIDATES = ["~/.claude/skills", "~/.agents/skills"];
+
+/**
+ * Test/ops escape hatch: comma-separated absolute paths overriding
+ * DEFAULT_SURFACE_CANDIDATES. Not part of config.toml — "others as
+ * configured" (spec.md) is deliberately left as an implementation-time
+ * choice, same as the proposal heuristic. Exists primarily so tests never
+ * probe the real $HOME's ~/.claude/skills or ~/.agents/skills.
+ */
+export function surfaceCandidates(): string[] {
+  const override = process.env.SKILLMUX_INIT_SURFACES;
+  return override ? override.split(",").filter((p) => p.length > 0) : DEFAULT_SURFACE_CANDIDATES;
+}
+
+export interface SurfaceCandidate {
+  path: string;
+  exists: boolean;
+  isSymlink: boolean;
+  skillCount: number;
+  alreadyMarked: boolean;
+}
+
+function countSkillDirs(dir: string): number {
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && SKILL_ID_PATTERN.test(entry.name) && existsSync(join(dir, entry.name, "SKILL.md"))) {
+      count++;
+    }
+  }
+  return count;
+}
+
+export function detectSurfaces(candidatePaths: string[]): SurfaceCandidate[] {
+  return candidatePaths.map((path) => {
+    if (!existsSync(path)) {
+      return { path, exists: false, isSymlink: false, skillCount: 0, alreadyMarked: false };
+    }
+    return {
+      path,
+      exists: true,
+      isSymlink: lstatSync(path).isSymbolicLink(),
+      skillCount: countSkillDirs(path),
+      alreadyMarked: readSkillmuxMarker(path) !== null,
+    };
+  });
+}
+
+/**
+ * Conservative default: no slash-command/workflow-router detection heuristic
+ * at TDD time (spec.md, "skr init" AC) — evidence-only, nothing proposed
+ * until a concrete heuristic is agreed.
+ */
+export function proposeManifest(_candidates: SurfaceCandidate[]): Pick<Manifest, "core" | "project"> {
+  return { core: { skills: [] }, project: {} };
+}
+
+/** e.g. ~/.claude/skills -> "claude"; ~/.agents/skills -> "agents". */
+export function deriveTargetName(path: string): string {
+  return basename(dirname(path)).replace(/^\./, "").toLowerCase();
+}
+
+export interface ConfirmedTarget {
+  name: string;
+  dir: string;
+}
+
+/**
+ * Writes skillmux.toml with the conservative-default core/project and the
+ * confirmed targets, then adopts each confirmed dir in place (creating it
+ * first if it doesn't exist yet). Unconfirmed candidates are simply never
+ * passed in — this function never discovers paths on its own.
+ */
+export function applyInit(vaultPath: string, confirmedTargets: ConfirmedTarget[]): Manifest {
+  const manifest: Manifest = {
+    ...proposeManifest([]),
+    targets: Object.fromEntries(
+      confirmedTargets.map((target) => [target.name, { dir: target.dir, project: false }]),
+    ),
+  };
+
+  writeFileSync(join(vaultPath, MANIFEST_FILENAME), serializeManifest(manifest));
+
+  for (const target of confirmedTargets) {
+    if (!existsSync(target.dir)) mkdirSync(target.dir, { recursive: true });
+    adoptTarget(target.dir, target.name);
+  }
+
+  return manifest;
+}
+
+/** Verbatim from docs/sdd/skr-cli/think.md §3.3 — the shared instruction-stack paragraph. */
+export const DISCOVERY_PARAGRAPH =
+  "Skills: only a curated core is loaded statically. Before improvising a " +
+  "multi-step workflow, or when a task smells like a domain you have no loaded " +
+  "skill for (career/resume, trading, SEO, i18n, design, one-off tooling), " +
+  "call `resolve_skill` with a one-line task description. `matched` → follow " +
+  "the returned SKILL.md. `ambiguous` → pick from the candidates and " +
+  "`fetch_skill`. `no_match` → proceed normally; don't force an unrelated " +
+  "skill.";
+
+export const MCP_REGISTRATION_SNIPPET = JSON.stringify(
+  { mcpServers: { "skillmux": { command: "skillmux", args: ["serve"] } } },
+  null,
+  2,
+);
+
+/** §3.4 step 4: "print the last mile" — MCP registration command + discovery paragraph. */
+export function printLastMile(): string {
+  return [
+    "Register with your MCP client:",
+    MCP_REGISTRATION_SNIPPET,
+    "",
+    "Add this paragraph to your shared agent instructions (~80 tokens, the entire T3 discovery mechanism):",
+    DISCOVERY_PARAGRAPH,
+  ].join("\n");
+}

package/src/install.ts

@@ -0,0 +1,113 @@
+import { cpSync, existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { type ScanFinding, readTextFileOrNull, scanContent } from "./scan";
+import { decodeUtf8Strict, listSupportingFiles, parseSkillMd } from "./vault";
+
+export interface RepoSource {
+  url: string;
+  skillPath?: string;
+}
+
+const GIT_URL_PREFIXES = ["http://", "https://", "git://", "ssh://", "file://"];
+const SCP_LIKE_URL_PATTERN = /^[^/\s]+@[^/\s]+:/;
+
+function isGitUrl(repo: string): boolean {
+  return GIT_URL_PREFIXES.some((prefix) => repo.startsWith(prefix)) || SCP_LIKE_URL_PATTERN.test(repo);
+}
+
+export function resolveRepoSource(repo: string): RepoSource {
+  if (isGitUrl(repo)) return { url: repo };
+
+  const [owner, name, ...rest] = repo.split("/");
+  if (!owner || !name) {
+    throw new Error(`invalid repo "${repo}": expected owner/repo, owner/repo/path, or a git URL`);
+  }
+  const url = `https://github.com/${owner}/${name}.git`;
+  return rest.length > 0 ? { url, skillPath: rest.join("/") } : { url };
+}
+
+export function deriveRepoName(url: string): string {
+  const cleaned = url.replace(/\.git$/, "");
+  const segment = cleaned.split(/[/:]/).filter(Boolean).pop();
+  if (!segment) throw new Error(`could not derive a repo name from "${url}"`);
+  return segment;
+}
+
+export async function cloneToTemp(url: string): Promise<string> {
+  const dir = mkdtempSync(join(tmpdir(), "skillmux-install-"));
+  const proc = Bun.spawn(["git", "clone", "--quiet", "--depth", "1", url, dir], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    rmSync(dir, { recursive: true, force: true });
+    throw new Error(`git clone failed for ${url}: ${stderr.trim()}`);
+  }
+  return dir;
+}
+
+export interface ValidationResult {
+  findings: ScanFinding[];
+}
+
+export async function validateSkillCandidate(skillId: string, dir: string): Promise<ValidationResult> {
+  const bytes = await Bun.file(join(dir, "SKILL.md")).bytes();
+  const body = decodeUtf8Strict(bytes);
+  parseSkillMd(skillId, body);
+
+  const findings: ScanFinding[] = scanContent(body).map((match) => ({
+    ...match,
+    skill_id: skillId,
+    file: "SKILL.md",
+  }));
+
+  const vaultPath = dirname(dir);
+  const dirName = basename(dir);
+  for (const rel of listSupportingFiles(vaultPath, dirName)) {
+    const content = await readTextFileOrNull(join(dir, rel));
+    if (content === null) continue;
+    for (const match of scanContent(content)) {
+      findings.push({ ...match, skill_id: skillId, file: rel });
+    }
+  }
+
+  return { findings };
+}
+
+export function installIntoVault(vaultPath: string, skillId: string, sourceDir: string, force = false): string {
+  const targetDir = join(vaultPath, skillId);
+  if (existsSync(targetDir)) {
+    if (!force) {
+      throw new Error(`skill "${skillId}" already exists in the vault at ${targetDir} — pass --force to overwrite`);
+    }
+    rmSync(targetDir, { recursive: true, force: true });
+  }
+  cpSync(sourceDir, targetDir, { recursive: true, filter: (src) => basename(src) !== ".git" });
+  return targetDir;
+}
+
+export interface ResolvedSkillDir {
+  skillId: string;
+  dir: string;
+}
+
+export function resolveSkillDir(cloneDir: string, fallbackName: string, skillPath?: string): ResolvedSkillDir {
+  if (skillPath) {
+    return { skillId: basename(skillPath), dir: join(cloneDir, skillPath) };
+  }
+  if (existsSync(join(cloneDir, "SKILL.md"))) {
+    return { skillId: fallbackName, dir: cloneDir };
+  }
+  const discovered = readdirSync(cloneDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(cloneDir, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .sort();
+  throw new Error(
+    discovered.length > 0
+      ? `no SKILL.md at repo root; found skill dirs: ${discovered.join(", ")} — pass a path to select one, e.g. owner/repo/${discovered[0]}`
+      : "no SKILL.md at repo root and no skill dirs found under it",
+  );
+}

package/src/lifecycle.ts

@@ -0,0 +1,51 @@
+import { expandHome } from "./config";
+import type { ReadinessState } from "./readiness";
+import { backfillEmbeddings, getRuntime, rebuildIndex } from "./router-core";
+import { getVaultMaxMtime } from "./vault";
+
+export async function initializeRuntime(state: ReadinessState): Promise<void> {
+  try {
+    const { config, db, clients } = await getRuntime();
+    const vaultPath = expandHome(config.vault_path);
+    const report = await rebuildIndex();
+    let embedding: "ready" | "unavailable" = "ready";
+    try {
+      await backfillEmbeddings();
+      await clients.embed(["skill router readiness probe"]);
+    } catch {
+      embedding = "unavailable";
+    }
+
+    let reranker: "not_configured" | "ready" | "unavailable" = "not_configured";
+    if (clients.rerank) {
+      try {
+        await clients.rerank("skill router readiness probe", [
+          { skill_id: "readiness", text: "Routes tasks to relevant skills." },
+        ]);
+        reranker = "ready";
+      } catch {
+        reranker = "unavailable";
+      }
+    }
+
+    state.set({
+      status: "ready",
+      retrieval: reranker === "ready" ? "reranked" : embedding === "ready" ? "hybrid" : "lexical",
+      skills: report.indexed,
+      index_current: getVaultMaxMtime(vaultPath) >= 0 && db.query("SELECT COUNT(*) AS count FROM skills").get() !== null,
+      embedding,
+      reranker,
+    });
+  } catch (error) {
+    state.set({
+      status: "not_ready",
+      retrieval: null,
+      skills: 0,
+      index_current: false,
+      embedding: "unavailable",
+      reranker: "not_configured",
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { expandHome } from "./config";
+import { SKILL_ID_PATTERN } from "./vault";
+
+export const MANIFEST_FILENAME = "skillmux.toml";
+export const LEGACY_MANIFEST_FILENAME = "skr.toml";
+
+export function resolveManifestPath(vaultPath: string): string | null {
+  const newPath = join(vaultPath, MANIFEST_FILENAME);
+  if (existsSync(newPath)) return newPath;
+  const legacyPath = join(vaultPath, LEGACY_MANIFEST_FILENAME);
+  if (existsSync(legacyPath)) return legacyPath;
+  return null;
+}
+
+const groupNameSchema = z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64);
+const skillIdSchema = z.string().regex(SKILL_ID_PATTERN);
+
+const projectGroupSchema = z.object({
+  repos: z.array(z.string().min(1)),
+  skills: z.array(skillIdSchema),
+}).strict();
+
+const targetSchema = z.object({
+  dir: z.string().min(1),
+  project: z.boolean().default(false),
+}).strict();
+
+const manifestSchema = z.object({
+  core: z.object({ skills: z.array(skillIdSchema) }).strict(),
+  project: z.record(groupNameSchema, projectGroupSchema).optional(),
+  targets: z.record(groupNameSchema, targetSchema),
+}).strict();
+
+export type ProjectGroup = z.infer<typeof projectGroupSchema>;
+export type Target = z.infer<typeof targetSchema>;
+export type Manifest = z.infer<typeof manifestSchema>;
+
+export function parseManifest(toml: string): Manifest {
+  const parsed = Bun.TOML.parse(toml) as Record<string, unknown>;
+  return manifestSchema.parse(parsed);
+}
+
+function tomlStringArray(values: string[]): string {
+  return `[${values.map((v) => JSON.stringify(v)).join(", ")}]`;
+}
+
+/** Purpose-built serializer for this manifest's fixed shape — not a general TOML writer. */
+export function serializeManifest(manifest: Manifest): string {
+  const sections: string[] = [`[core]\nskills = ${tomlStringArray(manifest.core.skills)}`];
+
+  for (const [name, group] of Object.entries(manifest.project ?? {})) {
+    sections.push(
+      `[project.${name}]\nrepos = ${tomlStringArray(group.repos)}\nskills = ${tomlStringArray(group.skills)}`,
+    );
+  }
+
+  for (const [name, target] of Object.entries(manifest.targets)) {
+    sections.push(`[targets.${name}]\ndir = ${JSON.stringify(target.dir)}\nproject = ${target.project}`);
+  }
+
+  return `${sections.join("\n\n")}\n`;
+}
+
+export interface ManifestValidationResult {
+  notes: string[];
+}
+
+const CORE_SKILL_LIMIT = 25;
+
+export function validateManifest(manifest: Manifest, vaultSkillIds: Set<string>): ManifestValidationResult {
+  if (manifest.core.skills.length > CORE_SKILL_LIMIT) {
+    throw new Error(
+      `[core] has ${manifest.core.skills.length} skills, exceeding the limit of ${CORE_SKILL_LIMIT}`,
+    );
+  }
+
+  const coreSet = new Set(manifest.core.skills);
+  for (const skillId of manifest.core.skills) {
+    if (!vaultSkillIds.has(skillId)) {
+      throw new Error(`[core] skill "${skillId}" does not exist in the vault`);
+    }
+  }
+
+  const notes: string[] = [];
+  for (const [groupName, group] of Object.entries(manifest.project ?? {})) {
+    for (const skillId of group.skills) {
+      if (!vaultSkillIds.has(skillId)) {
+        throw new Error(`[project.${groupName}] skill "${skillId}" does not exist in the vault`);
+      }
+      if (coreSet.has(skillId)) {
+        throw new Error(`skill "${skillId}" appears in both [core] and [project.${groupName}]`);
+      }
+    }
+    for (const repo of group.repos) {
+      if (!existsSync(expandHome(repo))) {
+        notes.push(`[project.${groupName}] repos path not found locally, skipped: ${repo}`);
+      }
+    }
+  }
+
+  return { notes };
+}

package/src/metrics.ts

@@ -0,0 +1,101 @@
+import type { ReadinessSnapshot } from "./readiness";
+
+export class MetricsRegistry {
+  private requests = new Map<string, number>();
+  private outcomes = new Map<string, number>();
+  
+  private buckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0];
+  private latencyBuckets = new Array(this.buckets.length).fill(0);
+  private latencyInf = 0;
+  private latencySum = 0;
+  private latencyCount = 0;
+
+  private errors = 0;
+  private rateLimitsExceeded = 0;
+  private readiness: ReadinessSnapshot | null = null;
+
+  setReadiness(readiness: ReadinessSnapshot) {
+    this.readiness = readiness;
+  }
+
+  recordRequest(method: string) {
+    this.requests.set(method, (this.requests.get(method) || 0) + 1);
+  }
+
+  recordResolveOutcome(outcome: string) {
+    this.outcomes.set(outcome, (this.outcomes.get(outcome) || 0) + 1);
+  }
+
+  recordResolveLatencySeconds(seconds: number) {
+    this.latencySum += seconds;
+    this.latencyCount++;
+    for (let i = 0; i < this.buckets.length; i++) {
+      if (seconds <= this.buckets[i]!) {
+        this.latencyBuckets[i]++;
+      }
+    }
+    this.latencyInf++;
+  }
+
+  recordError() {
+    this.errors++;
+  }
+
+  recordRateLimitExceeded() {
+    this.rateLimitsExceeded++;
+  }
+
+  render(): string {
+    const lines: string[] = [];
+
+    // Requests total
+    lines.push("# HELP skill_router_requests_total Total count of incoming MCP requests.");
+    lines.push("# TYPE skill_router_requests_total counter");
+    for (const [method, count] of this.requests) {
+      lines.push(`skill_router_requests_total{method="${method}"} ${count}`);
+    }
+
+    // Resolve outcomes total
+    lines.push("# HELP skill_router_resolve_outcomes_total Total count of resolve_skill query outcomes.");
+    lines.push("# TYPE skill_router_resolve_outcomes_total counter");
+    for (const [outcome, count] of this.outcomes) {
+      lines.push(`skill_router_resolve_outcomes_total{outcome="${outcome}"} ${count}`);
+    }
+
+    // Latency histogram
+    lines.push("# HELP skill_router_resolve_latency_seconds Latency histogram of resolve_skill executions.");
+    lines.push("# TYPE skill_router_resolve_latency_seconds histogram");
+    for (let i = 0; i < this.buckets.length; i++) {
+      let le = this.buckets[i]!.toString();
+      // Format to remove trailing .0 if integer to match test
+      if (Number.isInteger(this.buckets[i]!)) {
+        le = this.buckets[i]!.toFixed(0);
+      }
+      lines.push(`skill_router_resolve_latency_seconds_bucket{le="${le}"} ${this.latencyBuckets[i]}`);
+    }
+    lines.push(`skill_router_resolve_latency_seconds_bucket{le="+Inf"} ${this.latencyInf}`);
+    lines.push(`skill_router_resolve_latency_seconds_sum ${this.latencySum}`);
+    lines.push(`skill_router_resolve_latency_seconds_count ${this.latencyCount}`);
+
+    // Errors total
+    lines.push("# HELP skill_router_errors_total Total count of server and query routing errors.");
+    lines.push("# TYPE skill_router_errors_total counter");
+    lines.push(`skill_router_errors_total ${this.errors}`);
+
+    // Rate limits exceeded
+    lines.push("# HELP skill_router_rate_limits_exceeded_total Total count of HTTP requests rejected by rate limiting.");
+    lines.push("# TYPE skill_router_rate_limits_exceeded_total counter");
+    lines.push(`skill_router_rate_limits_exceeded_total ${this.rateLimitsExceeded}`);
+
+    lines.push("# HELP skill_router_ready Whether the service is ready to route requests.");
+    lines.push("# TYPE skill_router_ready gauge");
+    lines.push(`skill_router_ready ${this.readiness?.status === "ready" ? 1 : 0}`);
+    lines.push("# HELP skill_router_retrieval_capability Active retrieval capability.");
+    lines.push("# TYPE skill_router_retrieval_capability gauge");
+    for (const capability of ["exact", "reranked", "hybrid", "lexical"]) {
+      lines.push(`skill_router_retrieval_capability{capability="${capability}"} ${this.readiness?.retrieval === capability ? 1 : 0}`);
+    }
+
+    return lines.join("\n") + "\n";
+  }
+}

package/src/models.ts

@@ -0,0 +1,20 @@
+import { expandHome } from "./config";
+import type { Config } from "./types";
+
+export async function downloadLocalModels(config: Config): Promise<string> {
+  if (config.inference.mode !== "local") {
+    throw new Error("models download is only available for inference.mode = \"local\".");
+  }
+
+  const cacheDir = expandHome(config.inference.models_dir);
+  process.env.HF_HUB_CACHE = cacheDir;
+  process.env.HF_HOME = cacheDir;
+  const { env, pipeline } = await import("@huggingface/transformers");
+  env.cacheDir = cacheDir;
+
+  await pipeline("feature-extraction", config.inference.embedding.model, {
+    device: config.inference.embedding.device ?? "cpu",
+    dtype: config.inference.embedding.dtype ?? "q8",
+  });
+  return cacheDir;
+}