@klhapp/skillmux 1.1.0 → 1.3.0

package/docs/skill-management.md

@@ -0,0 +1,209 @@
+# Managing skills
+
+Skillmux keeps skill content in a canonical vault and materializes selected
+skills into client directories. This guide covers the commands that change or
+inspect that state.
+
+Run these commands on the machine that owns the vault and client directories.
+For a retrieval-only Docker service, manage the mounted vault on the host and
+keep the container mount read-only.
+
+## Install from Git
+
+`skillmux install` accepts a GitHub shorthand or a full Git URL:
+
+```sh
+skillmux install owner/repo
+skillmux install owner/repo/path/to/skill
+skillmux install https://git.example.com/team/skill.git
+```
+
+The repository root must contain `SKILL.md`. If a repository contains several
+skill directories, add the path for the one you want.
+
+Skillmux clones into a temporary directory, validates the selected skill,
+scans its text files, and copies it to `vault_path`. Existing skill IDs require
+`--force`.
+
+Preview the destination without copying:
+
+```sh
+skillmux install owner/repo --dry-run
+```
+
+Set a scan gate when you want findings to block installation:
+
+```sh
+skillmux install owner/repo --fail-on high
+```
+
+The scanner detects suspicious prompt-injection patterns, secrets, and risky
+instructions. Findings remain advisory unless you pass `--fail-on`.
+
+## Scan a vault or candidate
+
+```sh
+skillmux scan
+skillmux scan ~/skills/candidate
+skillmux scan --format json
+skillmux scan --fail-on medium
+```
+
+With no path, `scan` checks the configured vault. `--json` wraps the result in
+the standard CLI automation envelope, while `--format json` selects the
+scanner's raw JSON rendering.
+
+## Plan client delivery
+
+Use product names for common clients:
+
+```sh
+skillmux init --client claude-code --client codex --dry-run
+```
+
+Use a direct target when you need a known path:
+
+```sh
+skillmux init --target agent-skills --yes
+skillmux init --target custom --dir /srv/my-agent/skills --yes
+```
+
+Skillmux refuses to adopt a target that points to the whole vault because sync
+would reduce its visible skills. Review that migration first:
+
+```sh
+skillmux init --client claude-code --migrate-full-vault \
+  --core csv-formatter --dry-run
+skillmux init --client claude-code --migrate-full-vault \
+  --core csv-formatter --yes
+```
+
+## Manage core pins
+
+Core skills go to each configured target:
+
+```sh
+skillmux core pin csv-formatter --yes
+skillmux core pin code-context systematic-debugging --yes
+skillmux core unpin csv-formatter --yes
+```
+
+One command can change several skill IDs. Skillmux validates the complete
+change before writing, so a conflict prevents the whole operation. Core stays
+capped at 25 skills.
+
+Run `skillmux sync` after a direct pin or unpin command.
+
+## Manage project groups
+
+Create a group with the guided command:
+
+```sh
+skillmux project init
+```
+
+Maintain it with explicit commands:
+
+```sh
+skillmux project list
+skillmux project show my-project
+skillmux project add-path my-project ~/code/my-project --yes
+skillmux project pin my-project code-context --yes
+skillmux project attach my-project --client claude-code --client codex --yes
+skillmux project unpin my-project code-context --yes
+skillmux project detach my-project --target codex --yes
+skillmux project remove-path my-project ~/code/my-project --yes
+```
+
+Create the group with `project init` or `project add-path` before pinning.
+Project setup syncs by default. Direct maintenance commands update the
+manifest but leave materialization to the next `skillmux sync`.
+
+## Synchronize targets
+
+```sh
+skillmux sync --dry-run
+skillmux sync
+```
+
+Sync compares the manifest with entries recorded in each target's `.skillmux`
+marker. It creates missing symlinks and removes stale managed links.
+
+Install a vault Git hook when merges can change `skillmux.toml`:
+
+```sh
+skillmux sync --install-hook
+```
+
+The hook lives in the canonical vault and runs `skillmux sync` after a merge.
+
+## Inspect active state
+
+Find which vault root serves a skill:
+
+```sh
+skillmux skill which code-context
+```
+
+If a local overlay shadows the canonical copy, the output lists both paths.
+
+Inspect configuration and readiness:
+
+```sh
+skillmux config show
+skillmux config diff
+skillmux config status
+skillmux doctor
+```
+
+## Use routing data to tune tiers
+
+`resolve_skill` writes an audit row for each request. Summarize recent usage:
+
+```sh
+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.
+
+`--since` accepts windows such as `1h`, `7d`, and `1m`, plus absolute dates and
+timestamps.
+
+## Target ownership and recovery
+
+`skillmux target remove <name> --yes` removes the manifest record and preserves
+the target directory, marker, and files. Cleanup stays under your control.
+
+Restore a managed target to one symlink that exposes the full vault:
+
+```sh
+skillmux sync --restore-monolith
+```
+
+This operation removes the target marker and per-skill links. It refuses to
+run when unmanaged content makes the replacement unsafe. Re-adopt the target
+with `skillmux init` before running managed sync again.
+
+Do not delete `.skillmux` markers by hand. The marker gives sync the ownership
+record it needs to preserve unrelated content.
+
+## Local overlays
+
+Configure machine-specific override roots:
+
+```toml
+vault_path = "~/skills"
+local_vault_paths = ["~/skills-local"]
+```
+
+Then record the relationship:
+
+```sh
+skillmux local-vault init ~/skills-local --yes
+skillmux skill which my-skill
+```
+
+Read [Configuration](configuration.md#local-vault-overlays) for precedence,
+pinning restrictions, and watcher behavior.

package/docs/troubleshooting.md

@@ -0,0 +1,199 @@
+# Troubleshooting
+
+Start with:
+
+```sh
+skillmux doctor
+skillmux config show
+skillmux config validate
+```
+
+Add `--json` when you need machine-readable diagnostics.
+
+## Vault failures
+
+### Vault path does not exist
+
+Check the effective path and its source:
+
+```sh
+skillmux config show
+```
+
+Create the directory or initialize config against a populated vault:
+
+```sh
+skillmux config init --vault ~/skills --yes
+```
+
+`config init` requires at least one valid `SKILL.md`.
+
+### A skill does not appear
+
+Each skill must sit one directory below the vault:
+
+```text
+~/skills/<skill-id>/SKILL.md
+```
+
+Run:
+
+```sh
+skillmux scan ~/skills/<skill-id>
+skillmux index
+skillmux skill which <skill-id>
+```
+
+The scanner reports invalid frontmatter and unreadable content. `skill which`
+also reveals local-overlay shadowing.
+
+## Sync failures
+
+### Target has no ownership marker
+
+Skillmux will not change an existing unmarked directory. Adopt it first:
+
+```sh
+skillmux init --client claude-code --dry-run
+skillmux init --client claude-code --yes
+```
+
+### Target points to the full vault
+
+Review the smaller pinned set before converting:
+
+```sh
+skillmux init --client claude-code \
+  --migrate-full-vault \
+  --core code-context \
+  --dry-run
+```
+
+Apply the same command with `--yes` after checking the plan.
+
+### Unmanaged file collides with a pin
+
+Skillmux preserves unmanaged target content. Rename or remove the conflicting
+entry yourself, then rerun `skillmux sync`.
+
+### Target belongs to another host
+
+New targets include the current hostname. `sync` skips a target when its
+manifest `host` differs. Run `skillmux target show <name>` and add a separate
+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.
+
+## Retrieval failures
+
+### `resolve_skill` returns `ambiguous`
+
+Ambiguity is the expected result without calibrated reranker thresholds. The
+calling model should select a candidate and call `fetch_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.
+
+### Server reports lexical mode
+
+Lexical mode means Skillmux can query FTS5 but cannot use embeddings. The next
+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 |
+
+For a Skillmux CLI installation, run:
+
+```sh
+skillmux doctor
+skillmux models download
+skillmux index
+```
+
+For remote inference, verify the endpoint, model, dimension, API-key
+environment variable, and network path. The slim image does not contain
+GTE-small, so `models download` is not its recovery path.
+
+### Reranker is unavailable
+
+Skillmux keeps the hybrid shortlist when a reranker probe or request fails.
+Check `inference.reranker.endpoint`, `adapter`, `model`, and the environment
+variable named by `api_key_env`.
+
+Use the complete request URL. Skillmux does not append `/rerank` or infer an
+adapter from the endpoint.
+
+### Delivered content changed after indexing
+
+Skillmux checks the file before delivery and refreshes stale metadata. If a
+skill cannot be parsed during a live edit, the index keeps the previous good
+metadata but does not serve stale body bytes. Finish the write with valid
+frontmatter and retry.
+
+## HTTP failures
+
+### Another machine cannot connect
+
+The Skillmux CLI binds HTTP to `127.0.0.1`. Set `server.hostname` or
+`HTTP_HOSTNAME` to a reachable interface, then restart the server. Docker
+binds `0.0.0.0` inside the container, but the host still needs a published
+port. Enable authentication before exposing either deployment.
+
+### Browser receives `403`
+
+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`
+
+Confirm `server.auth_enabled = true`, export the environment variable named by
+`auth_token_env`, and send `Authorization: Bearer <token>`.
+
+An enabled server with an empty token environment variable returns a server
+configuration error rather than accepting an empty token.
+
+### Client receives `429`
+
+The rate limiter rejected the request. Read `Retry-After` and the
+`X-RateLimit-*` response headers. Increase `requests_per_minute` only after
+checking for a retry loop or shared-token traffic.
+
+## Configuration migration errors
+
+Skillmux rejects removed fields with migration guidance:
+
+- replace `[targets.<name>].project` with `project_groups = [...]`;
+- rename `[project.<group>].repos` to `paths`;
+- use `skillmux core pin|unpin` instead of removed `manifest pin|unpin`;
+- replace legacy reranker base-URL variables with
+  `SKILLMUX_RERANK_ENDPOINT` and `SKILLMUX_RERANK_ADAPTER`.
+
+Run `skillmux config validate` after editing TOML.
+
+## Collect diagnostics
+
+For a bug report, include:
+
+```sh
+skillmux --help
+skillmux config show
+skillmux doctor --json
+```
+
+Remove tokens, private endpoint credentials, local usernames, and raw audit
+queries before posting output. Open an issue at
+<https://github.com/klhq/skillmux/issues>.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.1.0",
-  "description": "Local read-only MCP server routing natural-language task queries to skills in a SKILL.md vault, with zero-loss delivery",
+  "version": "1.3.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,
   "author": "Lance Hsu <lance@klh.app>",
@@ -22,9 +22,7 @@
   },
   "files": [
     "src",
-    "docs/schema.json",
-    "docs/configuration.md",
-    "docs/releasing.md",
+    "docs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",

package/src/adapters.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { applyCalibrationRun, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, type CalibrationResult } from "./calibrate";
+import { applyCalibrationRun, getCalibrationRun, insertCalibrationRun, listCalibrationRuns, loadDecisionCasesFromFile, openCalibrateDb, runCalibration, summarizeDatasetProvenance, type CalibrationResult } from "./calibrate";
 import { createClients } from "./clients";
 import { DEFAULT_CONFIG_PATH, embeddingFingerprint, expandHome, loadConfig, rerankerFingerprint } from "./config";
 import { openIndex } from "./db";
@@ -139,7 +139,19 @@ export class LocalAdapter implements TargetAdapter {
   }): Promise<{ run_id?: string; result?: CalibrationResult }> {
     const config = await loadConfig(this.configPath);
     const datasetFile = opts?.datasetPath ?? join(expandHome(config.state_dir), "queries.json");
-    const cases = loadDecisionCasesFromFile(datasetFile);
+    const indexDb = openIndex(expandHome(config.state_dir));
+    let indexedSkills: Array<{ skill_id: string; content_sha256: string }>;
+    try {
+      indexedSkills = indexDb
+        .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
+        .all() as Array<{ skill_id: string; content_sha256: string }>;
+    } finally {
+      indexDb.close();
+    }
+    const cases = loadDecisionCasesFromFile(
+      datasetFile,
+      indexedSkills.map((skill) => skill.skill_id),
+    );
     const clients = createClients(config);
     configure({ config, clients });
     const result = await runCalibration({
@@ -168,18 +180,9 @@ export class LocalAdapter implements TargetAdapter {
       throw new Error("A configured remote reranker is required to record calibration.");
     }
     const datasetText = await Bun.file(datasetFile).text();
-    const indexDb = openIndex(expandHome(config.state_dir));
-    let corpusFingerprint: string;
-    try {
-      const rows = indexDb
-        .query("SELECT skill_id, content_sha256 FROM skills ORDER BY skill_id")
-        .all();
-      corpusFingerprint =
-        "vault:" +
-        createHash("sha256").update(JSON.stringify(rows)).digest("hex");
-    } finally {
-      indexDb.close();
-    }
+    const corpusFingerprint =
+      "vault:" +
+      createHash("sha256").update(JSON.stringify(indexedSkills)).digest("hex");
     const runId = `run_${crypto.randomUUID()}`;
     const db = openCalibrateDb(expandHome(config.state_dir));
     try {
@@ -191,6 +194,7 @@ export class LocalAdapter implements TargetAdapter {
         embedding_fingerprint: embeddingFingerprint(config),
         corpus_fingerprint: corpusFingerprint,
         dataset_hash: createHash("sha256").update(datasetText).digest("hex"),
+        dataset_provenance: summarizeDatasetProvenance(cases),
         candidate_limit: config.thresholds.candidate_limit,
         min_auto_match_precision: opts?.minAutoMatchPrecision ?? 0.99,
         min_auto_match_count: opts?.minAutoMatchCount ?? 30,
@@ -420,41 +424,30 @@ export class RemoteAdapter implements TargetAdapter {
     minDeliveredShortlistRecallAtK?: number;
     minAutoMatchCount?: number;
   }): Promise<{ run_id?: string; result?: CalibrationResult }> {
-    const { status, data } = await this.fetchJson("/admin/v1/calibrations", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        dataset_path: opts?.datasetPath,
-        min_auto_match_precision: opts?.minAutoMatchPrecision,
-        min_retrieval_recall_at_k: opts?.minRetrievalRecallAtK,
-        min_delivered_shortlist_recall_at_k: opts?.minDeliveredShortlistRecallAtK,
-        min_auto_match_count: opts?.minAutoMatchCount,
-      }),
-    });
-    if (status !== 202) {
-      throw new Error(`Remote calibration start failed (${status}): ${data?.message || data}`);
-    }
-    return data;
+    void opts;
+    throw this.remoteCalibrationNotImplemented();
   }
 
   async calibrateList(): Promise<any[]> {
-    const { status, data } = await this.fetchJson("/admin/v1/calibrations");
-    if (status !== 200) throw new Error(`Remote calibration list failed (${status}): ${data?.message || data}`);
-    return data;
+    throw this.remoteCalibrationNotImplemented();
   }
 
   async calibrateShow(runId: string): Promise<any> {
-    const { status, data } = await this.fetchJson(`/admin/v1/calibrations/${runId}`);
-    if (status !== 200) throw new Error(`Remote calibration show failed (${status}): ${data?.message || data}`);
-    return data;
+    void runId;
+    throw this.remoteCalibrationNotImplemented();
   }
 
   async calibrateApply(runId: string): Promise<any> {
-    const { status, data } = await this.fetchJson(`/admin/v1/calibrations/${runId}/apply`, {
-      method: "POST",
-    });
-    if (status !== 200) throw new Error(`Remote calibration apply failed (${status}): ${data?.message || data}`);
-    return data;
+    void runId;
+    throw this.remoteCalibrationNotImplemented();
+  }
+
+  private remoteCalibrationNotImplemented(): CliError {
+    return new CliError(
+      `Remote calibration is not implemented for target ${this.serverUrl}; ` +
+        "run `skillmux calibrate` against a local target.",
+      2,
+    );
   }
 }