@klhapp/skillmux 1.2.0 → 1.3.0

package/docs/getting-started.md

@@ -0,0 +1,239 @@
+# Getting started
+
+Skillmux supports three setup paths. Pick the result you want before choosing
+an installation.
+
+| Goal | Skill delivery | Recommended installation |
+| --- | --- | --- |
+| [Manage native skills](#manage-native-skills) | Managed links in client skill directories | Skillmux CLI |
+| [Add local MCP retrieval](#add-local-mcp-retrieval) | Local stdio MCP | Skillmux CLI |
+| [Run a shared MCP service](#run-a-shared-mcp-service) | Streamable HTTP MCP | Full Docker image |
+
+Native management and local MCP retrieval can run together. Complete both
+recipes if you want pinned skills plus on-demand access to the rest of the
+vault.
+
+## Install the CLI
+
+Use the Bun package on macOS, Linux, or Windows. It requires
+[Bun 1.3 or newer](https://bun.sh/docs/installation):
+
+```sh
+bun add -g @klhapp/skillmux
+skillmux --help
+```
+
+Native target sync needs permission to create directory symlinks on Windows.
+
+Linux users without Bun can install the standalone AMD64 or ARM64 executable
+instead:
+
+```sh
+gh release download --repo klhq/skillmux --pattern 'skillmux-linux-*'
+gh attestation verify skillmux-linux-amd64 --repo klhq/skillmux
+chmod +x skillmux-linux-amd64
+sudo install skillmux-linux-amd64 /usr/local/bin/skillmux
+```
+
+Replace `amd64` with `arm64` on ARM64. The Bun package and standalone Linux
+executable expose the same Skillmux CLI commands.
+
+## Prepare a vault
+
+Skillmux defaults to `~/skills`. Each direct child directory represents one
+skill:
+
+```text
+~/skills/
+├── code-context/
+│   └── SKILL.md
+└── csv-formatter/
+    ├── SKILL.md
+    └── references/
+```
+
+Each `SKILL.md` needs valid Agent Skills frontmatter. With the Skillmux CLI,
+you can install a skill from Git:
+
+```sh
+skillmux install owner/repo
+skillmux install owner/repo/path/to/skill
+```
+
+Or create a small skill:
+
+```sh
+mkdir -p ~/skills/csv-formatter
+cat > ~/skills/csv-formatter/SKILL.md <<'EOF'
+---
+name: CSV Formatter
+description: Convert CSV or spreadsheet data into clean Markdown tables.
+---
+
+# CSV Formatter
+
+Read the first row as headers. Right-align numbers and left-align text.
+EOF
+```
+
+Run `skillmux scan ~/skills` before adopting an existing collection.
+
+## Manage native skills
+
+Run the guided setup on the machine that owns the client skill directories:
+
+```sh
+skillmux init
+```
+
+The planner:
+
+1. validates the vault;
+2. detects clients from filesystem evidence;
+3. asks which skills belong in the core tier;
+4. shows the config, target, instruction, and sync plan;
+5. applies the plan after confirmation.
+
+Skillmux writes machine config under `~/.config/skillmux`, stores tier policy
+in `~/skills/skillmux.toml`, and records its entries in each target's
+`.skillmux` marker. It preserves unmanaged files and existing instruction
+text.
+
+Use explicit flags for automation:
+
+```sh
+skillmux init \
+  --client claude-code \
+  --client codex \
+  --core csv-formatter \
+  --dry-run
+
+skillmux init \
+  --client claude-code \
+  --client codex \
+  --core csv-formatter \
+  --yes
+```
+
+Verify native delivery:
+
+```sh
+skillmux sync
+skillmux doctor
+skillmux skill which csv-formatter
+```
+
+Repeated syncs are idempotent. Add project-specific skills from a repository
+root:
+
+```sh
+skillmux project init
+```
+
+The noninteractive form accepts repeatable client and skill flags:
+
+```sh
+skillmux project init ~/code/my-project \
+  --name my-project \
+  --client claude-code \
+  --client codex \
+  --skill code-context \
+  --yes
+```
+
+Continue with [Managing skills](skill-management.md) for pinning, target
+ownership, overlays, and recovery.
+
+## Add local MCP retrieval
+
+Run this recipe on the same machine as the MCP client. The default inference
+configuration uses quantized GTE-small embeddings on CPU.
+
+Prefetch the model, build the index, and check readiness:
+
+```sh
+skillmux models download
+skillmux index
+skillmux doctor
+```
+
+The model cache lives at `~/.cache/skillmux/models`. If you skip
+`models download`, Skillmux downloads the model when local inference first
+loads it.
+
+Start the stdio server:
+
+```sh
+skillmux serve
+```
+
+Register it with your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "skillmux": {
+      "command": "skillmux",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+The client launches the process and closes it with the MCP session. Continue
+with [MCP routing](mcp-routing.md) for client behavior and retrieval outcomes.
+
+## Run a shared MCP service
+
+Use the full image when you want local embeddings without configuring an
+external inference endpoint:
+
+```sh
+docker run -d \
+  --name skillmux \
+  -v ~/skills:/vault:ro \
+  -v skillmux-data:/data \
+  -p 3000:3000 \
+  ghcr.io/klhq/skillmux:latest
+```
+
+The full image includes GTE-small and is the shared-service default. The slim
+image is an advanced option for configured remote embeddings or intentional
+lexical-only retrieval; it contains no model files. Neither image includes a
+local reranker. Configure remote embeddings on slim when you need hybrid
+retrieval. Docker Hub publishes the same tags under `docker.io/klhq/skillmux`.
+
+Check the service:
+
+```sh
+curl http://127.0.0.1:3000/health/ready
+```
+
+Register `http://127.0.0.1:3000/mcp` as a Streamable HTTP MCP endpoint. Enable
+authentication before exposing the service beyond a trusted host. Continue
+with [Deployment](deployment.md) for remote inference, network policy,
+monitoring, and backups.
+
+Manage the mounted vault on the host. A retrieval-only container should mount
+it read-only.
+
+## Combine native pins with shared retrieval
+
+Use this topology when users need native core or project pins and also one
+shared MCP endpoint. Keep one Git-backed vault as the source of truth:
+
+- each machine that owns client skill directories keeps its own checkout and
+  runs the Skillmux CLI for `init`, pinning, and `sync`;
+- the shared server mounts its own checkout and serves routed retrieval over
+  HTTP;
+- MCP-only clients connect to the shared server and do not need the CLI.
+
+Skillmux does not pull, push, replicate, or make those checkouts fresh. Git
+and your deployment process own vault replication and freshness.
+
+## Next steps
+
+- [Concepts](concepts.md) explains delivery, deployment, and inference terms.
+- [Configuration](configuration.md) documents local and remote inference.
+- [Troubleshooting](troubleshooting.md) lists common `doctor`, model, and
+  transport failures.

package/docs/mcp-routing.md

@@ -0,0 +1,172 @@
+# MCP routing
+
+Skillmux exposes one vault through two Model Context Protocol tools. Choose a
+transport based on where the process runs:
+
+| Topology | Transport | Typical package |
+| --- | --- | --- |
+| Skillmux beside one client | stdio | Skillmux CLI |
+| Shared Skillmux service | Streamable HTTP | Full Docker image by default; slim for remote or lexical retrieval |
+
+Both transports expose the same `resolve_skill` and `fetch_skill` contract.
+Local native pinning is optional and can run beside stdio MCP.
+
+## Register a stdio server
+
+Start the server:
+
+```sh
+skillmux index
+skillmux doctor
+skillmux serve
+```
+
+Register the command in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "skillmux": {
+      "command": "skillmux",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+The default transport is stdio. The process exits when the client closes its
+input stream or sends a termination signal.
+
+## Connect to a shared HTTP service
+
+Start a Streamable HTTP server:
+
+```sh
+skillmux serve --transport http --port 3000
+```
+
+Clients send MCP requests to:
+
+```text
+http://127.0.0.1:3000/mcp
+```
+
+The default host accepts loopback connections only. Configure authentication
+and network exposure before serving other machines. See
+[Deployment](deployment.md#expose-http-safely).
+
+## Tool contract
+
+### `resolve_skill`
+
+Input:
+
+```json
+{
+  "query": "convert this spreadsheet to a Markdown table"
+}
+```
+
+Skillmux returns one outcome:
+
+- `matched`: `structuredContent` contains match metadata and the text content
+  contains the `SKILL.md` body once;
+- `ambiguous`: `structuredContent` contains up to `candidate_limit` candidates;
+- `no_match`: the agent continues with its normal workflow.
+
+### `fetch_skill`
+
+Input:
+
+```json
+{
+  "skill_id": "csv-formatter"
+}
+```
+
+The response contains the current `SKILL.md` body as text content.
+`structuredContent` contains the skill ID, title, content SHA-256, and
+supporting-file paths. Fetch does not depend on an earlier resolve call.
+
+The complete wire contract lives in [schema.json](schema.json).
+
+## Recommended agent behavior
+
+Give the calling client these rules:
+
+1. Call `resolve_skill` when a task may benefit from a specialized workflow.
+2. Follow the delivered skill on `matched`.
+3. On `ambiguous`, choose the best candidate and call `fetch_skill`.
+4. On `no_match`, continue without loading a skill.
+
+Do not treat the first ambiguous candidate as an automatic match. Skillmux
+uses ambiguity to keep the final choice with the calling model when it lacks
+enough confidence.
+
+## Retrieval pipeline
+
+Skillmux builds candidates in stages:
+
+1. SQLite FTS5 ranks lexical matches with BM25.
+2. Local or remote embeddings rank semantic similarity.
+3. Reciprocal-rank fusion combines both lists.
+4. An optional reranker scores the fused candidates.
+5. Calibrated thresholds select `matched`, `ambiguous`, or `no_match`.
+
+The default local inference configuration uses FTS5 and quantized
+`Xenova/gte-small` embeddings. Skillmux CLI installations cache the
+downloaded model under `~/.cache/skillmux/models`; the full Docker image
+includes it. The slim image starts with lexical retrieval and can call an
+OpenAI-compatible embedding endpoint.
+
+Remote inference also supports `jina-v1` or `bifrost-v1` reranker adapters.
+
+Without a reranker, Skillmux returns a shortlist and does not auto-match.
+Without calibrated thresholds, a configured reranker orders the shortlist but
+still does not auto-match.
+
+Read [Configuration](configuration.md#local-inference) for local and remote
+inference settings. Read [Policy calibration](calibration.md) before enabling
+automatic matches.
+
+## Fallback and readiness
+
+Skillmux advertises the capability it can support:
+
+- embedding failure falls back to lexical retrieval;
+- reranker failure preserves the hybrid shortlist;
+- vault or index failure marks the server unready.
+
+Check the active mode:
+
+```sh
+skillmux doctor
+curl http://127.0.0.1:3000/health/ready
+```
+
+A ready server reports `lexical`, `hybrid`, or `reranked` along with skill and
+index status.
+
+## Content integrity
+
+The index stores metadata and retrieval state. Delivery reads the file from
+disk, computes its SHA-256, and returns those current bytes. If indexed
+metadata has gone stale, Skillmux refreshes it before delivery.
+
+Supporting files remain in the vault. `fetch_skill` lists their relative paths
+so the calling workflow can locate them through its configured filesystem
+access.
+
+## Audit data
+
+Each resolve request records:
+
+- timestamp and query;
+- retrieval capability and outcome;
+- candidates with scores;
+- selected skill ID, when present;
+- latency.
+
+Skillmux stores audit rows in the SQLite database under `state_dir`. Use
+`skillmux report` to summarize activity. Treat raw queries as private user
+data when backing up or sharing the database.

package/docs/releasing.md

@@ -39,9 +39,10 @@ The release workflow publishes:
 - `skillmux-linux-arm64`
 - GitHub build provenance attestations when the repository is public
 - Full image to GHCR and Docker Hub: `:<version>`, `:<major>.<minor>`,
-  and `:latest`
+  and `:latest`; this variant includes GTE-small
 - Slim image to GHCR and Docker Hub: `:<version>-slim`,
-  `:<major>.<minor>-slim`, and `:latest-slim`
+  `:<major>.<minor>-slim`, and `:latest-slim`; this variant contains no model
+  files and uses remote embeddings or lexical fallback
 - Multi-architecture `linux/amd64` and `linux/arm64` images with SBOM and
   provenance
 
@@ -86,7 +87,7 @@ Verify the container with a read-only vault mount:
 
 ```bash
 docker run --rm \
-  -v ~/.agents/skills:/vault:ro \
+  -v ~/skills:/vault:ro \
   -p 3000:3000 \
   ghcr.io/klhq/skillmux:latest
 

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.