@klhapp/skillmux 1.1.0 → 1.3.0

package/docs/cli.md

@@ -0,0 +1,350 @@
+# CLI reference and automation
+
+The Bun package and standalone Linux executable expose the same CLI. Native
+management belongs on the machine that owns the client skill directories:
+use the built-in `local` target for `init`, `install`, pinning, and `sync`.
+Named remote contexts administer shared-server configuration through its
+administrative API only; they do not install, pin, or synchronize skills in
+client directories.
+
+In this guide, **local target** means the filesystem and process selected by
+the built-in CLI context. It does not describe local inference. A local target
+can call remote inference endpoints.
+
+For task-oriented workflows, start with [Getting started](getting-started.md)
+or [Managing skills](skill-management.md).
+
+## Global options and target resolution
+
+Every target-aware command resolves its execution target deterministically in this order:
+
+1. Explicit flags: `--context <name>` or `--server <url>`
+2. Environment variables: `SKILLMUX_CONTEXT` or `SKILLMUX_SERVER`
+3. Default context configured in `~/.config/skillmux/contexts.toml`
+4. Built-in `local` context
+
+> [!IMPORTANT]
+> Supplying both `--context` and `--server` (or both `SKILLMUX_CONTEXT` and `SKILLMUX_SERVER`) is rejected as ambiguous. Plaintext HTTP admin targets on non-loopback addresses are rejected unless `--allow-insecure` is supplied.
+
+| Flag | Description |
+|------|-------------|
+| `--context <name>` | Select a target context stored in `contexts.toml` |
+| `--server <url>` | Select an explicit remote server URL |
+| `--json` | Emit line-stable JSON envelopes (schema version 1) to stdout |
+| `--allow-insecure` | Allow plaintext HTTP admin requests to non-loopback addresses |
+| `--verbose` | Output diagnostic stack traces for errors |
+
+---
+
+## Context management (`skillmux context`)
+
+Contexts store named server targets without embedding raw credentials. Token environment variable names (`token_env`) may be associated with a context.
+
+```sh
+# List all configured contexts (includes reserved 'local' context)
+skillmux context list
+
+# View the currently active context
+skillmux context current
+
+# Add a remote context
+skillmux context add prod --server https://skillmux.internal:3000 --token-env PROD_ADMIN_TOKEN
+
+# Switch default context
+skillmux context use prod
+
+# Remove a context (reserved 'local' context cannot be removed)
+skillmux context remove prod
+```
+
+---
+
+## Configuration management (`skillmux config`)
+
+Local and remote targets share the server configuration read and status
+subcommands. `config init` is local-only because it creates machine
+configuration and selects a local vault.
+
+```sh
+# Create the machine config after validating a populated vault
+skillmux config init --vault ~/skills --yes
+
+# View current configuration and source attribution (default, toml, environment)
+skillmux config show
+
+# Get a specific schema-known dotted key value
+skillmux config get recall.k_lexical
+
+# Validate effective configuration schema and runtime readiness
+skillmux config validate
+
+# View effective configuration diff against defaults
+skillmux config diff
+
+# Set a dotted key value (previews diff and validates before saving)
+skillmux config set recall.k_lexical 30
+
+# Perform dry-run validation without writing or activating changes
+skillmux config set recall.k_lexical 30 --dry-run
+
+# Inspect runtime status, revision hashes, and readiness
+skillmux config status
+```
+
+`config init` writes only `vault_path`. It leaves an existing config unchanged
+and does not add `local_vault_paths`. Remote contexts administer the deployed
+server configuration; they never administer client skill installation, pins,
+or sync.
+
+---
+
+## Setup planner (`skillmux init`)
+
+Run `skillmux init` with no arguments in a terminal to start guided setup.
+Skillmux preselects clients it can detect from filesystem evidence, asks for
+core skills, prints one complete review, and applies after one confirmation.
+The prompt stays line-oriented and does not use an alternate terminal screen.
+
+Select clients by product name:
+
+```sh
+skillmux init --client claude-code --client codex --core csv-formatter --dry-run
+skillmux init --client claude-code --client codex --core csv-formatter --yes
+```
+
+Skillmux supports these client IDs:
+
+| Client | Skill delivery |
+|--------|----------------|
+| `claude-code` | `~/.claude/skills` |
+| `codex` | `$CODEX_HOME/skills`, falling back to `~/.codex/skills` |
+| `gemini-cli`, `opencode`, `github-copilot`, `windsurf` | Shared `~/.agents/skills` surface |
+| `antigravity` | `~/.gemini/config/skills` |
+| `goose`, `hermes` | Manual full-vault configuration |
+| `skillmux-mcp` | Manual MCP registration |
+
+Direct target IDs are `agent-skills`, `claude-code`, `codex`, and `custom`.
+Custom targets require `--dir <dir>`. The legacy `agents` and `claude` IDs
+print deprecation warnings and retain their manifest names.
+
+`--dry-run` prints the config, target, instruction, and core plan without
+prompting or writing. `--json` emits one schema-versioned plan or result
+object. Noninteractive writes require `--yes`. `--interactive` forces the
+wizard and seeds it with supplied flags. `--no-instructions` skips managed
+instruction files; `--no-sync` saves setup without materializing links.
+
+Skillmux rejects a target that currently links to the whole vault. Convert it
+only after reviewing the smaller post-sync skill set:
+
+```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
+```
+
+Client instruction adapters append one managed discovery block and preserve
+the rest of each file. Skillmux uses `.hermes.md` for Hermes and refuses
+`SOUL.md` or Hermes's installed-source `AGENTS.md`. A client without a safe
+user-level convention reports manual setup.
+
+---
+
+## Project setup (`skillmux project init`)
+
+Run the guided flow from a project directory:
+
+```sh
+skillmux project init
+```
+
+Skillmux resolves the project directory from an explicit positional path, then
+the current Git root, then the current directory. It suggests the directory
+basename as the project-group name.
+
+The noninteractive form accepts repeatable client and skill flags:
+
+```sh
+skillmux project init ~/code/skillmux \
+  --name skillmux \
+  --client claude-code \
+  --client codex \
+  --skill sdd-tdd \
+  --skill code-context \
+  --yes
+```
+
+`--client` maps product names to configured, deduplicated targets. Advanced
+callers can attach a configured target with repeated `--target <name>`.
+Re-running the command merges missing paths, skills, and target attachments.
+It validates the complete manifest before an atomic write and runs `sync` by
+default. Use `--no-sync` when another process will materialize the links.
+
+Direct project commands support later maintenance:
+
+```sh
+skillmux project list
+skillmux project show skillmux
+skillmux project add-path skillmux ~/code/skillmux --yes
+skillmux project remove-path skillmux ~/old/skillmux --yes
+skillmux project pin skillmux sdd-tdd code-context --yes
+skillmux project unpin skillmux old-skill --yes
+skillmux project attach skillmux --client claude-code --client codex --yes
+skillmux project detach skillmux --target codex --yes
+```
+
+`add-path` and `remove-path` detect the current Git root when the path is
+omitted. Client attachments map to configured physical targets and deduplicate
+clients that share `~/.agents/skills`. Mutating commands validate the complete
+manifest and replace it atomically. Run `skillmux sync` after direct
+maintenance commands to materialize the new state.
+
+---
+
+## Advanced targets (`skillmux target`)
+
+Most users should select products with `init --client`. Use `target` commands
+for custom delivery directories and manifest inspection:
+
+```sh
+skillmux target list
+skillmux target show claude-code
+skillmux target add custom-agent --dir /srv/custom-agent/skills --yes
+skillmux target remove custom-agent --yes
+```
+
+`target add` uses the same ownership, symlink, full-vault, rollback, and
+current-host scoping checks as `skillmux init`. `target remove` removes the
+manifest entry and preserves the directory, marker, and skill files. The
+command prints the preserved path so cleanup remains an explicit user action.
+
+---
+
+## Core skills (`skillmux core`)
+
+Pin or unpin skills into `[core]` — the tier every target receives by
+default, capped at 25 skills:
+
+```sh
+skillmux core pin csv-formatter --yes
+skillmux core pin csv-formatter pdf-extractor terraform-plans --yes
+skillmux core unpin csv-formatter --yes
+```
+
+One or more `skill_id` arguments are accepted per call and applied
+atomically against a single in-memory manifest: if any one of them is
+already pinned elsewhere (or, for `unpin`, not currently pinned), the
+whole call fails and the manifest file is left untouched. To pin into a
+`[project.<group>]` tier instead, use `skillmux project pin` (see
+[Project Setup](#project-setup-skillmux-project-init)).
+
+### Reloadable and restart-required keys
+
+Config changes are categorized into live-reloadable and restart-required settings:
+
+- **Reloadable**: `vault_path`, `recall.*`, `thresholds.*`, `inference.embedding.*`, `server.rate_limit.*`
+- **Restart Required**: `server.hostname`, `server.auth_enabled`, `server.auth_token_env`, `server.admin.enabled`, `server.admin.token_env`, `inference.mode`, `state_dir`
+
+---
+
+## Skill introspection (`skillmux skill which`)
+
+Show which root actually serves a skill_id, and every root it shadows:
+
+```sh
+skillmux skill which csv-formatter
+```
+
+---
+
+## Policy calibration (`skillmux calibrate`)
+
+Calibrate decision thresholds (`match_score`, `match_margin`, `candidate_floor`) against synthetic or labeled query datasets.
+Calibration is local-only in this release. Remote targets advertise the
+capability as unavailable and return `not_implemented`; a local dataset path is
+never uploaded or represented as remotely executed. See
+[`docs/calibration.md`](calibration.md) for dataset responsibilities,
+certification gates, run evidence, reference values, and the complete operator
+lifecycle.
+
+```sh
+# Run calibration on a dataset
+skillmux calibrate run --dataset ./eval/queries.json
+
+# List stored calibration runs in the evidence store
+skillmux calibrate list
+
+# Inspect detailed metrics and confusion matrix for a run
+skillmux calibrate show <run_id>
+
+# Apply calibrated thresholds to configuration (with fingerprint validation)
+skillmux calibrate apply <run_id>
+
+# Generate a synthetic decision dataset from vault skills
+skillmux calibrate generate-dataset --out ./eval/queries.json
+```
+
+---
+
+## Administrative HTTP API (`/admin/v1/*`)
+
+Remote servers expose administrative control endpoints under `/admin/v1/*` when enabled in configuration:
+
+```toml
+[server.admin]
+enabled = true
+token_env = "SKILLMUX_ADMIN_TOKEN"
+```
+
+Requests require `Authorization: Bearer <token>` where `<token>` matches the environment variable named by `server.admin.token_env`.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/admin/v1/capabilities` | `GET` | Advertises server features (`config_read`, `config_write`, `calibration`, `persistence`) |
+| `/admin/v1/config` | `GET` | Returns desired/effective config, sources, and `ETag` revision hash |
+| `/admin/v1/config` | `PATCH` | Applies dotted-key updates; requires matching `If-Match` header |
+| `/admin/v1/calibrations` | `GET`, `POST` | Returns `501 not_implemented` (calibration is local-only) |
+| `/admin/v1/calibrations/{run_id}` | `GET` | Returns `501 not_implemented`; raw evaluation queries are not exposed |
+| `/admin/v1/calibrations/{run_id}/apply` | `POST` | Returns `501 not_implemented` |
+
+---
+
+## Automation and JSON output (`--json`)
+
+When `--json` or `SKILLMUX_JSON=true` is set, all output is emitted to `stdout` in a stable envelope:
+
+```json
+{
+  "schema_version": 1,
+  "ok": true,
+  "target": "local",
+  "data": { ... },
+  "error": null
+}
+```
+
+### Exit codes
+
+| Code | Meaning | Examples |
+|------|---------|----------|
+| `0` | Success | Command completed cleanly |
+| `2` | Usage / Validation Error | Unknown key, malformed value, missing option, invalid command |
+| `3` | Target Unreachable / Unauthenticated | Connection refused, HTTP 401 Unauthorized, HTTP 403 Forbidden |
+| `4` | Conflict / Governance Gate | HTTP 409 `CONFIG_REVISION_CONFLICT` or `CONFIG_EXTERNALLY_MANAGED` |
+
+---
+
+## Shell completions (`skillmux completions`)
+
+Generate tab-completions for `bash`, `zsh`, or `fish`:
+
+```sh
+# Bash
+skillmux completions bash > ~/.local/share/bash-completion/completions/skillmux
+
+# Zsh
+skillmux completions zsh > ~/.zsh/completion/_skillmux
+
+# Fish
+skillmux completions fish > ~/.config/fish/completions/skillmux.fish
+```

package/docs/concepts.md

@@ -0,0 +1,165 @@
+# Concepts
+
+Skillmux separates three decisions:
+
+| Decision | Choices |
+| --- | --- |
+| Skill delivery | Native core/project pins or routed MCP retrieval |
+| Process location | On the client machine or as a shared HTTP service |
+| Packaging | Skillmux CLI installation or Skillmux server deployment |
+
+Retrieval capability is a fourth, independent concern: lexical, hybrid,
+reranked, or exact retrieval.
+
+These decisions are independent. A local CLI can manage native pins and serve
+stdio MCP at the same time. A shared service uses HTTP MCP and can run local or
+remote inference.
+
+## Canonical vault
+
+The vault is the source collection for Skillmux. Each direct child directory
+represents one skill and contains a `SKILL.md`.
+
+The default path is `~/skills`. Set `vault_path` in
+`~/.config/skillmux/config.toml` when you keep the collection elsewhere.
+
+Skillmux commands interact with the vault in two ways:
+
+- management commands such as `install` and explicit config operations write
+  to documented paths;
+- MCP retrieval reads skill content and stores indexes and audit records under
+  `state_dir`.
+
+MCP delivery reads the current file bytes. It does not copy an indexed
+`SKILL.md` body from the state database.
+
+## Delivery tiers
+
+Skillmux applies three policies to one vault:
+
+| Tier | Scope | Delivery |
+| --- | --- | --- |
+| Core | Each configured target | Native client skill directory |
+| Project | Selected project paths and targets | Project-local native skill directory |
+| Routed | Full indexed vault | MCP on demand |
+
+Core and project skills are **pinned**. `skillmux sync` creates managed
+symlinks for them. Routed skills stay in the vault until an MCP client asks for
+one.
+
+One skill can serve different roles across machines or projects, but the
+shared manifest prevents conflicting core and project assignments. Core stays
+capped at 25 skills to protect client startup context.
+
+Delivery tiers do not select a deployment. A local Skillmux process can serve
+routed skills over stdio, while a shared Skillmux process can serve the same
+vault over HTTP.
+
+## Deployment topologies
+
+| Topology | Process location | Transport | Typical installation |
+| --- | --- | --- | --- |
+| Native management | Client machine | Filesystem links | Skillmux CLI |
+| Local MCP | Beside one client | stdio | Skillmux CLI |
+| Shared MCP | Server or container host | Streamable HTTP | Full Skillmux server image |
+
+The **Skillmux CLI** is available as either the Bun package or the standalone
+Linux executable; both expose the same commands. The **full Skillmux server
+image** is the default shared-service deployment. The **slim image** is an
+advanced variant for configured remote embeddings or intentional lexical-only
+retrieval. The CLI can also serve HTTP, and Docker can serve stdio for clients
+that support a container command. Those combinations use the same MCP tools;
+the table lists the shortest setup for each use case.
+
+The full Docker image bundles GTE-small. The slim image contains no model
+files, so it uses configured remote embeddings or lexical fallback. The Bun
+CLI distributions download and cache GTE-small when local inference
+first loads it; `skillmux models download` prefetches it. Neither Docker image
+bundles a local reranker; configure one remotely when needed.
+
+## Clients and targets
+
+A **client** is a supported product name such as `claude-code` or `codex`.
+Skillmux maps it to the product's skill directory and safe instruction-file
+conventions.
+
+A **target** is a physical directory managed by sync. Several clients can map
+to one target. Gemini CLI, OpenCode, GitHub Copilot, and Windsurf share
+`~/.agents/skills`, so Skillmux deduplicates that directory.
+
+Custom targets let you manage another directory without adding a product
+adapter:
+
+```sh
+skillmux target add custom-agent --dir /srv/custom-agent/skills --yes
+```
+
+## Ownership markers
+
+Each managed target contains a `.skillmux` marker. The marker records the
+target name, vault, schema version, and entries created by Skillmux.
+
+Sync removes only recorded entries. It refuses to adopt an unmarked directory,
+overwrite unmanaged collisions, or treat a local overlay marker as a target
+marker.
+
+Run `skillmux init --dry-run` before changing a target. Read
+[Managing skills](skill-management.md#target-ownership-and-recovery) before
+undoing an adopted target.
+
+## Project groups
+
+A project group connects:
+
+- one or more local project paths;
+- a set of skill IDs;
+- selected targets.
+
+Skillmux materializes each group inside the project using the target's path
+relative to the user's home directory. A shared `skillmux.toml` can list
+checkout paths from several machines. Sync skips paths that do not exist on
+the current machine.
+
+## Local vault overlays
+
+`local_vault_paths` layer machine-specific skill copies over the canonical
+vault. Skillmux checks overlay paths in order, then falls back to `vault_path`.
+
+Use overlays for work in progress or machine-specific variants. Keep portable
+core and project pins in the canonical vault because another machine may not
+have the overlay.
+
+## Inference and retrieval capabilities
+
+Inference location and deployment location use separate settings. Local
+inference runs GTE-small inside the Skillmux process. Remote inference calls
+configured embedding and reranker endpoints. Either inference choice can back
+an HTTP MCP deployment.
+
+Skillmux reports the active retrieval capability:
+
+| Capability | Behavior |
+| --- | --- |
+| `lexical` | SQLite FTS5 and BM25 produce an ordered shortlist |
+| `hybrid` | Reciprocal-rank fusion combines lexical and embedding results |
+| `reranked` | A configured reranker reorders the fused candidates |
+| `exact` | An exact skill ID resolves directly |
+
+A reranker does not enable automatic matches by itself. Skillmux needs
+calibrated `match_score`, `match_margin`, and `candidate_floor` thresholds
+before it returns a semantic result as `matched`.
+
+## Retrieval outcomes
+
+`resolve_skill` returns one of three outcomes:
+
+- `matched`: one skill passed the calibrated policy, so Skillmux delivers its
+  `SKILL.md` body inline;
+- `ambiguous`: Skillmux returns an ordered candidate list and the calling model
+  chooses one with `fetch_skill`;
+- `no_match`: no candidate passed the policy and the agent continues without a
+  skill.
+
+Embedding or reranker failures reduce the active capability. Vault and index
+failures make the server unready because Skillmux can no longer guarantee
+valid retrieval.

package/docs/configuration.md

@@ -1,8 +1,23 @@
 # Configuration
 
-Skillmux defaults to FTS5 plus local GTE-small semantic retrieval. Most users need no config file.
+Skillmux manages one canonical vault and defaults to FTS5 plus GTE-small
+running in the Skillmux process. Most users need no config file.
 
-For detailed CLI command reference, target resolution, policy calibration, and automation envelopes, see [`docs/cli.md`](cli.md).
+Deployment and inference use separate terms:
+
+- **local deployment**: Skillmux runs beside a client, usually over stdio;
+- **shared deployment**: Skillmux serves clients over HTTP;
+- **local inference**: the Skillmux process runs the embedding model;
+- **remote inference**: Skillmux calls configured inference endpoints.
+
+A shared HTTP deployment can use local inference. A local stdio deployment can
+use remote inference.
+
+Read [Concepts](concepts.md) for the vault and delivery model. For detailed CLI
+commands, target resolution, and automation envelopes, see
+[CLI reference](cli.md). For labelled datasets, threshold certification,
+reference values, and the apply lifecycle, see
+[Policy calibration](calibration.md).
 
 ## Machine config bootstrap
 
@@ -23,14 +38,21 @@ It validates that the path resolves to a directory with at least one
 `local_vault_paths` unset. `skillmux init --vault ~/skills --yes` uses the
 same bootstrap when the machine config does not exist.
 
-## Local mode
+## Local inference
 
 ```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.
+The versioned `gte-small-v1` configuration uses normalized, mean-pooled
+`Xenova/gte-small` embeddings with 384 dimensions, quantized to q8 on CPU.
+Skillmux CLI installations download the model when inference first
+loads it and cache it in `~/.cache/skillmux/models`. The full Docker image
+already contains the model.
+
+Skillmux combines FTS5 and cosine result lists with reciprocal-rank fusion.
+Without a reranker, the calling model selects from the ordered shortlist.
 
 Advanced local overrides:
 
@@ -47,9 +69,10 @@ dtype = "q8"
 
 ```
 
-Use `skillmux models download` to prefetch models and `skillmux doctor` to verify readiness.
+Use `skillmux models download` to prefetch the model and `skillmux doctor` to
+verify readiness.
 
-## Remote mode
+## Remote inference
 
 See [`config.remote.example.toml`](../config.remote.example.toml). Embeddings
 must implement the OpenAI-compatible `{ model, input }` contract. Configure the
@@ -105,7 +128,13 @@ candidate list returned to the calling LLM after retrieval, reranking, and
 threshold filtering. It does not change retrieval depth or the matched,
 ambiguous, or no-match classification.
 
-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.
+Reranker thresholds have no universal default because score distributions are
+model-specific. Without `inference.thresholds`, Skillmux still uses the
+reranker to order candidates but keeps outcomes ambiguous rather than
+auto-matching. Use `skillmux calibrate run` to select
+`match_score`, `match_margin`, and `candidate_floor`, then explicitly apply the
+certified run. The [calibration guide](calibration.md) also publishes a
+clearly-scoped BGE reference profile for smoke tests.
 
 ## HTTP server
 
@@ -128,7 +157,11 @@ Before exposing HTTP beyond localhost, set `hostname` to a reachable interface,
 
 ## 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 init` and `skillmux sync` manage native delivery by pinning selected
+skills as symlinks inside an agent's skill directory. Routed skills remain
+available through `resolve_skill`. Read [Concepts](concepts.md#delivery-tiers)
+for the model and [Managing skills](skill-management.md) for the workflow.
+This section defines the manifest.
 
 ### `skillmux.toml`