@klhapp/skillmux 1.3.3 → 1.4.0

package/docs/troubleshooting.md

@@ -10,8 +10,67 @@ skillmux config validate
 
 Add `--json` when you need machine-readable diagnostics.
 
+## Startup without configuration
+
+`skillmux serve` and `skillmux serve --transport http` do not require a config
+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
+continues with its last known good configuration.
+
+## Docker rejected a CLI command
+
+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
+management, or `config init`/`config set`, install and use the host CLI:
+
+```sh
+bun add -g @klhapp/skillmux
+skillmux <the-command Docker rejected>
+```
+
+The rejection exits 2. With `--json`, check
+`error.code == "CONTAINER_COMMAND_UNSUPPORTED"`, then use
+`error.details.recommended_host_command`; see the
+[container command contract](deployment.md#container-command-contract).
+
+## Installation failures
+
+### Standalone executable checksum verification fails
+
+Do not install the downloaded file. Confirm that the command still uses the
+pinned release and that the detected architecture is correct:
+
+```sh
+uname -m
+sha256sum skillmux-linux-amd64
+```
+
+Download the file again with the [standalone installation procedure](getting-started.md#install-the-cli).
+For GitHub build-provenance verification instead of the published SHA-256
+digest, use the [GitHub CLI attestation procedure](getting-started.md#install-with-github-cli-attestation).
+
+### `skillmux: command not found` after installation
+
+The standalone installer defaults to `~/.local/bin`. Add it to the shell's
+`PATH`, restart the shell, then run `skillmux --version`. Alternatively,
+install to a user-writable directory already on `PATH` with
+`SKILLMUX_BIN_DIR=/path/on/PATH`; use `sudo install` only when you explicitly
+want a system-wide installation.
+
 ## Vault failures
 
+### Checkouts are out of date
+
+Skillmux reads the configured vault checkout; it does not pull, push,
+replicate, or determine freshness between checkouts. Update the Git-backed
+vault source of truth and use your Git or deployment process to update the
+affected checkout, then rerun `skillmux index` or `skillmux sync` as needed.
+
 ### Vault path does not exist
 
 Check the effective path and its source:
@@ -84,8 +143,9 @@ target for the current machine instead of reusing the other machine's path.
 
 ### A local-overlay skill cannot be pinned
 
-Core and project pins must exist in the canonical `vault_path`. Copy or commit
-the skill there before pinning it. Routed lookup can still serve the overlay.
+Core and project pins must exist in the configured `vault_path` checkout. Copy
+or commit the skill there before pinning it. Routed lookup can still serve the
+overlay.
 
 ## Retrieval failures
 
@@ -112,8 +172,8 @@ step depends on the installation:
 | Installation | Expected action |
 | --- | --- |
 | Skillmux CLI with local inference | Download the local model and rebuild the index |
-| Full Docker image | Confirm the running tag is the full image and inspect `doctor` output |
-| Slim Docker image | Configure remote embeddings or keep lexical fallback |
+| Skillmux server (full image) | Inspect `doctor`, `/health/ready`, or `skill_router_deployment_info` for `image_variant=full`; do not infer it from the tag |
+| Skillmux server (slim image) | Configure remote embeddings or keep lexical fallback |
 
 For a Skillmux CLI installation, run:
 
@@ -158,7 +218,7 @@ Add the browser origin to `server.allowed_origins`. The value must match the
 request's `Origin` header. Curl and server-to-server clients omit this header
 and do not use the CORS list.
 
-### Client receives `401`
+### MCP client receives `401`
 
 Confirm `server.auth_enabled = true`, export the environment variable named by
 `auth_token_env`, and send `Authorization: Bearer <token>`.
@@ -166,6 +226,26 @@ Confirm `server.auth_enabled = true`, export the environment variable named by
 An enabled server with an empty token environment variable returns a server
 configuration error rather than accepting an empty token.
 
+### Operator receives `401` from `/admin/v1/*`
+
+Administrative authentication is separate from MCP authentication. Confirm
+`server.admin.enabled = true`, export the environment variable named by
+`server.admin.token_env`, and configure the named CLI context with that same
+environment-variable name:
+
+```sh
+export SKILLMUX_PROD_ADMIN_TOKEN="replace-with-admin-token"
+skillmux context add prod \
+  --server https://skillmux.example.com \
+  --token-env SKILLMUX_PROD_ADMIN_TOKEN
+skillmux --context prod config status
+```
+
+An MCP token for `/mcp` cannot authenticate this request, and the administrative
+token cannot authenticate an MCP client. A named context administers the
+deployed server configuration only; use Skillmux CLI on the machine that owns
+client directories for `install`, pinning, or `sync`.
+
 ### Client receives `429`
 
 The rate limiter rejected the request. Read `Retry-After` and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.3.3",
+  "version": "1.4.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,

package/src/cli.ts

@@ -97,6 +97,7 @@ import {
 import { createTargetAdapter, type TargetAdapter } from "./adapters";
 import {
   emitSuccess,
+  CliError,
   formatJsonEnvelope,
   isInteractive,
   mapExitCode,
@@ -133,9 +134,6 @@ const KNOWN_COMMANDS = [
   "local-vault",
 ];
 
-const DOCKER_HOST_MANAGEMENT_GUIDANCE =
-  "This command manages local Skillmux or agent directories and is not supported inside the Docker image. Install the Skillmux CLI on the host using the Bun package or standalone Linux executable.";
-
 function isDockerHostManagementCommand(command: string, subCommand: string): boolean {
   if (
     [
@@ -158,6 +156,33 @@ function isDockerHostManagementCommand(command: string, subCommand: string): boo
   return command === "config" && ["init", "set"].includes(subCommand);
 }
 
+function containerCommandUnsupported(command: string, subCommand: string): CliError {
+  const rejectedCommand = [command, subCommand].filter(Boolean).join(" ");
+  const recommendedHostCommand = `skillmux ${rejectedCommand}`;
+  const guide = "docs/deployment.md";
+  const documentation =
+    "https://github.com/klhq/skillmux/blob/main/docs/deployment.md#container-command-contract";
+  return new CliError(
+    `\`skillmux ${rejectedCommand}\` manages host agent directories and cannot run in the Skillmux server image.\n\n` +
+      "Install the host CLI:\n" +
+      "  bun add -g @klhapp/skillmux\n\n" +
+      "Then run:\n" +
+      `  ${recommendedHostCommand}\n\n` +
+      `See ${guide} for server deployment examples.`,
+    2,
+    "CONTAINER_COMMAND_UNSUPPORTED",
+    {
+      // `command` remains for automation written against the first Docker
+      // boundary release. `rejected_command` is the explicit contract name.
+      command: rejectedCommand,
+      rejected_command: rejectedCommand,
+      recommended_host_command: recommendedHostCommand,
+      guide,
+      documentation,
+    },
+  );
+}
+
 async function main() {
   const rawArgv = Bun.argv.slice(2);
 
@@ -167,7 +192,10 @@ async function main() {
   let flagContext: string | undefined;
   let flagServer: string | undefined;
   let isDryRun = false;
-  const subCommand = rawArgv[1] ?? "";
+  // Global flags do not form part of the command identity reported to users.
+  // In particular, `init --json` should recommend `skillmux init`, not a
+  // redundant JSON-only host command.
+  const subCommand = rawArgv[1]?.startsWith("-") ? "" : rawArgv[1] ?? "";
   const commandArgs = rawArgv.slice(2);
 
   const command = rawArgv[0];
@@ -198,7 +226,7 @@ async function main() {
     process.env.RUNNING_IN_DOCKER === "true" &&
     isDockerHostManagementCommand(command, subCommand)
   ) {
-    handleError(new Error(DOCKER_HOST_MANAGEMENT_GUIDANCE), {
+    handleError(containerCommandUnsupported(command, subCommand), {
       target: resolvedTarget,
       isJson,
       isVerbose,
@@ -572,7 +600,11 @@ function handleError(
     const env = formatJsonEnvelope({
       ok: false,
       target: opts.target,
-      error: { code: `EXIT_${code}`, message: msg },
+      error: {
+        code: err instanceof CliError ? err.code : `EXIT_${code}`,
+        message: msg,
+        details: err instanceof CliError ? err.details : undefined,
+      },
     });
     console.log(JSON.stringify(env));
   } else {
@@ -590,6 +622,23 @@ function handleError(
 }
 
 function printHelp(): void {
+  if (process.env.RUNNING_IN_DOCKER === "true") {
+    console.log(`Skillmux server image
+
+Default:
+  serve --transport http
+
+Supported commands:
+  serve, index, doctor, report, scan, skill which
+  config show|get|validate|diff|status
+
+Native skill management:
+  Install the Skillmux CLI on the host for init, install, pinning, and sync.
+
+See docs/deployment.md for server deployment examples.`);
+    return;
+  }
+
   console.log(`usage: skillmux <command> [options]
 
 Setup:
@@ -698,8 +747,14 @@ async function runEval(options: { isJson: boolean }): Promise<void> {
 async function runDoctor(options: { isJson: boolean }): Promise<void> {
   const report = await diagnose(await loadConfig());
   emitSuccess({ isJson: options.isJson }, report, () => {
+    console.log(`version: ${report.version}`);
+    console.log(`runtime: ${report.runtime}`);
+    console.log(`image variant: ${report.image_variant ?? "none"}`);
+    console.log(`vault path: ${report.vault_path}`);
+    console.log(`state directory: ${report.state_dir}`);
     console.log(`inference mode: ${report.mode}`);
     console.log(`routing capability: ${report.capability}`);
+    console.log(`retrieval capability: ${report.retrieval_capability}`);
     for (const check of report.checks)
       console.log(
         `${check.ok ? "ok" : "fail"}: ${check.name} - ${check.detail}`,

package/src/commands/config.ts

@@ -192,6 +192,8 @@ export async function handleConfigCommand(
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Runtime: ${res.runtime}`);
+      console.log(`Deployment runtime: ${res.deployment_runtime}`);
+      console.log(`Image variant: ${res.image_variant ?? "none"}`);
       console.log(`Active revision: ${res.active_revision}`);
       console.log(`Readiness: ${res.readiness.status}`);
     });

package/src/config-service.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { DEFAULT_CONFIG_PATH, expandHome, loadConfig } from "./config";
+import { describeDeployment } from "./deployment";
 import type { Config } from "./types";
 
 export type ConfigSource = "default" | "toml" | "environment";
@@ -32,6 +33,9 @@ export interface ConfigStatusResponse {
   readiness: { status: "ready" | "degraded" | "not_ready" | "stopping"; capability: string };
   restart_required_keys: string[];
   runtime: "running" | "not_running";
+  version: string;
+  deployment_runtime: "host" | "docker";
+  image_variant: "full" | "slim" | null;
 }
 
 export const RESTART_REQUIRED_KEYS = [
@@ -409,6 +413,7 @@ function formatTomlVal(v: unknown): string {
 export async function getLocalConfigStatus(configPath?: string): Promise<ConfigStatusResponse> {
   const { effective } = await getEffectiveConfig(configPath);
   const hash = computeHash(effective);
+  const deployment = describeDeployment(effective);
 
   return {
     target: "local",
@@ -421,5 +426,8 @@ export async function getLocalConfigStatus(configPath?: string): Promise<ConfigS
     readiness: { status: "ready", capability: "hybrid" },
     restart_required_keys: [],
     runtime: "not_running",
+    version: deployment.version,
+    deployment_runtime: deployment.runtime,
+    image_variant: deployment.image_variant,
   };
 }

package/src/config-watcher.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, watch } from "node:fs";
+import { existsSync, watch } from "node:fs";
 import { dirname } from "node:path";
 import { loadConfig } from "./config";
 import type { Config } from "./types";
@@ -123,7 +123,7 @@ export class ConfigWatcher {
   };
   private stopped = false;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private watcher: ReturnType<typeof watch>;
+  private watcher: ReturnType<typeof watch> | undefined;
 
   private constructor(
     private readonly tomlPath: string,
@@ -133,11 +133,13 @@ export class ConfigWatcher {
     const dir = dirname(tomlPath);
     const filename = tomlPath.split(/[/\\]/).pop()!;
 
-    // A config file is optional. Ensure its parent exists so zero-config
-    // startup is safe and later config writes are still observed.
-    mkdirSync(dir, { recursive: true });
+    // A config file is optional. Do not create its parent just to enable
+    // reloads: a native zero-config server must also work with a read-only or
+    // entirely absent config location. Reloads stay inactive until a future
+    // server start finds a watchable parent directory.
+    if (!existsSync(dir)) return;
 
-    this.watcher = watch(dir, { recursive: false }, (_event, changedName) => {
+    const watcher = watch(dir, { recursive: false }, (_event, changedName) => {
       if (this.stopped) return;
       // Fire for: the config file itself, or any .tmp variant of it (handles
       // pid-numbered atomics: config.toml.12345.tmp → rename → config.toml).
@@ -151,8 +153,9 @@ export class ConfigWatcher {
       }
       this.scheduleReload();
     });
+    this.watcher = watcher;
 
-    this.watcher.on("error", (err) => {
+    watcher.on("error", (err) => {
       if (!this.stopped) {
         this.status = { ...this.status, last_reload_error: String(err) };
         this.opts.onError(err);
@@ -243,7 +246,7 @@ export class ConfigWatcher {
       this.debounceTimer = null;
     }
     try {
-      this.watcher.close();
+      this.watcher?.close();
     } catch {
       // already closed
     }

package/src/deployment.ts

@@ -0,0 +1,39 @@
+import packageJson from "../package.json" with { type: "json" };
+import { expandHome } from "./config";
+import type { Config } from "./types";
+
+export interface DeploymentIdentity {
+  version: string;
+  runtime: "host" | "docker";
+  image_variant: "full" | "slim" | null;
+  vault_path: string;
+  state_dir: string;
+  inference_mode: Config["inference"]["mode"];
+  local_embedding_bundle: string | null;
+  remote_embedding_configured: boolean;
+  remote_reranker_configured: boolean;
+}
+
+export function describeDeployment(
+  config: Config,
+  environment: Record<string, string | undefined> = process.env,
+): DeploymentIdentity {
+  const runtime = environment.RUNNING_IN_DOCKER === "true" ? "docker" : "host";
+  const variant = environment.SKILLMUX_IMAGE_VARIANT;
+  const imageVariant = runtime === "docker" && (variant === "full" || variant === "slim")
+    ? variant
+    : null;
+
+  return {
+    version: packageJson.version,
+    runtime,
+    image_variant: imageVariant,
+    vault_path: expandHome(config.vault_path),
+    state_dir: expandHome(config.state_dir),
+    inference_mode: config.inference.mode,
+    local_embedding_bundle: config.inference.mode === "local" ? config.inference.bundle : null,
+    remote_embedding_configured: config.inference.mode === "remote",
+    remote_reranker_configured:
+      config.inference.mode === "remote" && !!config.inference.reranker,
+  };
+}

package/src/doctor.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { computeCorpusFingerprint, getCalibrationRun, openCalibrateDb } from "./calibrate";
 import { createClients, RemoteInferenceError } from "./clients";
 import { embeddingDimension, embeddingFingerprint, expandHome, rerankerFingerprint } from "./config";
+import { describeDeployment, type DeploymentIdentity } from "./deployment";
 import { openIndex } from "./db";
 import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
@@ -18,6 +19,16 @@ export interface DoctorCheck {
 export interface DoctorReport {
   mode: Config["inference"]["mode"];
   capability: "hybrid" | "lexical-only" | "unavailable";
+  retrieval_capability: "lexical" | "hybrid" | "reranked";
+  version: DeploymentIdentity["version"];
+  runtime: DeploymentIdentity["runtime"];
+  image_variant: DeploymentIdentity["image_variant"];
+  vault_path: DeploymentIdentity["vault_path"];
+  state_dir: DeploymentIdentity["state_dir"];
+  inference_mode: DeploymentIdentity["inference_mode"];
+  local_embedding_bundle: DeploymentIdentity["local_embedding_bundle"];
+  remote_embedding_configured: DeploymentIdentity["remote_embedding_configured"];
+  remote_reranker_configured: DeploymentIdentity["remote_reranker_configured"];
   checks: DoctorCheck[];
 }
 
@@ -93,7 +104,12 @@ function checkCalibration(config: Config): DoctorCheck {
   return { name: "calibration", ok: true, detail: `thresholds from applied calibration run "${runId}"` };
 }
 
-export async function diagnose(config: Config): Promise<DoctorReport> {
+export { describeDeployment };
+
+export async function diagnose(
+  config: Config,
+  environment: Record<string, string | undefined> = process.env,
+): Promise<DoctorReport> {
   const checks: DoctorCheck[] = [];
   checks.push({ name: "vault", ok: existsSync(expandHome(config.vault_path)), detail: expandHome(config.vault_path) });
 
@@ -179,27 +195,37 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
       ? { detail: error.message, failure_kind: error.kind }
       : { detail: "unexpected inference failure", failure_kind: "unexpected" };
 
-  const clients = createClients(config);
-  try {
-    const vectors = await clients.embed(["skill router diagnostic"]);
-    const actualDimension = vectors[0]?.length ?? 0;
+  const deployment = describeDeployment(config, environment);
+  const lexicalOnlySlim = deployment.image_variant === "slim" && config.inference.mode === "local";
+  if (lexicalOnlySlim) {
     checks.push({
-      name: "embedding",
-      ok: actualDimension === embeddingDimension(config),
-      detail: `dimension ${actualDimension}`,
+      name: "retrieval",
+      ok: true,
+      detail: "lexical retrieval; Configure remote embeddings for hybrid retrieval",
     });
-  } catch (error) {
-    checks.push({ name: "embedding", ok: false, ...inferenceFailure(error) });
-  }
-
-  if (clients.rerank) {
+  } else {
+    const clients = createClients(config);
     try {
-      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" });
+      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}`,
+      });
     } catch (error) {
-      checks.push({ name: "reranker", ok: false, ...inferenceFailure(error) });
+      checks.push({ name: "embedding", ok: false, ...inferenceFailure(error) });
+    }
+
+    if (clients.rerank) {
+      try {
+        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: "reranker", ok: false, ...inferenceFailure(error) });
+      }
     }
   }
 
@@ -208,11 +234,14 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
   }
 
   const inferenceReady = checks.some((check) => check.name === "embedding" && check.ok);
+  const rerankerReady = checks.some((check) => check.name === "reranker" && check.ok);
   const coreReady = checks.some((check) => check.name === "vault" && check.ok)
     && checks.some((check) => check.name === "state" && check.ok);
   return {
+    ...deployment,
     mode: config.inference.mode,
     capability: !coreReady ? "unavailable" : inferenceReady ? "hybrid" : "lexical-only",
+    retrieval_capability: rerankerReady ? "reranked" : inferenceReady ? "hybrid" : "lexical",
     checks,
   };
 }

package/src/metrics.ts

@@ -1,4 +1,10 @@
 import type { ReadinessSnapshot } from "./readiness";
+import type { DeploymentIdentity } from "./deployment";
+
+type MetricsDeploymentIdentity = Pick<
+  DeploymentIdentity,
+  "version" | "runtime" | "image_variant"
+>;
 
 export class MetricsRegistry {
   private requests = new Map<string, number>();
@@ -13,11 +19,16 @@ export class MetricsRegistry {
   private errors = 0;
   private rateLimitsExceeded = 0;
   private readiness: ReadinessSnapshot | null = null;
+  private deployment: MetricsDeploymentIdentity | null = null;
 
   setReadiness(readiness: ReadinessSnapshot) {
     this.readiness = readiness;
   }
 
+  setDeployment(deployment: MetricsDeploymentIdentity) {
+    this.deployment = deployment;
+  }
+
   recordRequest(method: string) {
     this.requests.set(method, (this.requests.get(method) || 0) + 1);
   }
@@ -96,6 +107,13 @@ export class MetricsRegistry {
       lines.push(`skill_router_retrieval_capability{capability="${capability}"} ${this.readiness?.retrieval === capability ? 1 : 0}`);
     }
 
+    if (this.deployment) {
+      const imageVariant = this.deployment.image_variant ?? "none";
+      lines.push("# HELP skill_router_deployment_info Immutable deployment identity for operator comparison.");
+      lines.push("# TYPE skill_router_deployment_info gauge");
+      lines.push(`skill_router_deployment_info{version="${this.deployment.version}",runtime="${this.deployment.runtime}",image_variant="${imageVariant}"} 1`);
+    }
+
     return lines.join("\n") + "\n";
   }
 }

package/src/output.ts

@@ -38,11 +38,15 @@ export function formatJsonEnvelope<T>(opts: {
 
 export class CliError extends Error {
   exitCode: number;
+  code: string;
+  details?: unknown;
 
-  constructor(message: string, exitCode: number) {
+  constructor(message: string, exitCode: number, code = `EXIT_${exitCode}`, details?: unknown) {
     super(message);
     this.name = "CliError";
     this.exitCode = exitCode;
+    this.code = code;
+    this.details = details;
   }
 }
 

package/src/router-core.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { watch } from "node:fs";
+import { existsSync, watch } from "node:fs";
 import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
@@ -334,6 +334,11 @@ export async function startVaultWatcher(): Promise<() => void> {
   const vaultPath = expandHome(config.vault_path);
   const timers = new Map<string, ReturnType<typeof setTimeout>>();
 
+  // A fresh installation may not have a vault checkout yet. Serving an empty
+  // vault is valid; leave live indexing inactive until the next server start
+  // finds a checkout rather than failing startup with ENOENT.
+  if (!existsSync(vaultPath)) return () => {};
+
   const watcher = watch(vaultPath, { recursive: true }, (_event, filename) => {
     const skillId = filename?.split(/[\\/]/)[0];
     if (!skillId || !SKILL_ID_PATTERN.test(skillId)) return;