@klhapp/skillmux 1.2.0 → 1.3.0

package/config.example.toml

@@ -1,7 +1,8 @@
-# This entire file is optional. Skill Router indexes an externally managed
-# agentskills.io-compatible vault and uses local GTE-small semantic retrieval.
-# vault_path is a neutral path, never a harness's static-loading scan
-# surface (e.g. ~/.agents/skills) — see docs/sdd/skr-cli/think.md.
+# This file is optional. It configures the Skillmux CLI or the full Skillmux
+# server image with local inference. Skillmux manages and indexes an
+# agentskills.io-compatible canonical vault. Keep the vault separate from
+# client skill directories such as ~/.agents/skills; skillmux sync selects
+# which core and project skills appear in those directories.
 vault_path = "~/skills"
 
 # Optional, default []: machine-local override-only vaults, checked before

package/config.remote.example.toml

@@ -1,5 +1,8 @@
-# Connect stronger inference endpoints. The reranker section is optional.
-vault_path = "~/.agents/skills"
+# Configure remote inference endpoints. This describes where inference runs,
+# not where Skillmux runs; local stdio and shared HTTP deployments can both use
+# this file. The reranker section is optional.
+# Keep the canonical vault separate from client skill directories.
+vault_path = "~/skills"
 
 [inference]
 mode = "remote"

package/docs/README.md

@@ -0,0 +1,52 @@
+# Skillmux documentation
+
+Skillmux manages one `SKILL.md` vault. Choose a workflow based on where skills
+need to appear and where Skillmux should run.
+
+## Choose a use case
+
+| Goal | Start with | Recommended installation |
+| --- | --- | --- |
+| Put a small skill set in native client directories | [Manage native skills](getting-started.md#manage-native-skills) | Skillmux CLI |
+| Let one client search the full vault through MCP | [Add local MCP retrieval](getting-started.md#add-local-mcp-retrieval) | Skillmux CLI |
+| Serve the vault to several MCP clients | [Run a shared MCP service](getting-started.md#run-a-shared-mcp-service) | Full Skillmux server image |
+
+You can combine native management and local MCP retrieval on one machine. The
+shared service uses the same MCP tools over HTTP.
+
+Install the CLI with the Bun package, or use the standalone Linux executable
+when Bun is unavailable. The full server image is the shared-service default;
+the slim image is an advanced choice for remote embeddings or lexical-only
+retrieval.
+
+## Learn the model
+
+- [Getting started](getting-started.md): choose an installation, prepare a
+  vault, and follow one of three setup recipes.
+- [Concepts](concepts.md): separate delivery tiers, deployment topology, and
+  retrieval capability.
+- [Managing skills](skill-management.md): install, scan, pin, sync, inspect,
+  and recover skills.
+- [MCP routing](mcp-routing.md): register stdio or HTTP MCP and understand
+  retrieval outcomes.
+
+## Operate Skillmux
+
+- [Deployment](deployment.md): deploy the shared server, choose slim only when
+  needed, expose HTTP, and operate the service.
+- [Configuration reference](configuration.md): configure inference, manifests,
+  server settings, and local overlays.
+- [CLI reference](cli.md): use commands, contexts, JSON output, and exit codes.
+- [Policy calibration](calibration.md): create labelled datasets and certify
+  reranker thresholds.
+- [Troubleshooting](troubleshooting.md): diagnose vault, sync, model, and server
+  problems.
+
+## Integrate and contribute
+
+- [MCP contract](schema.json): JSON Schema 2020-12 definitions for tool inputs
+  and results.
+- [Contributing](../CONTRIBUTING.md): development setup, tests, and pull request
+  conventions.
+- [Releasing](releasing.md): maintainer release procedure.
+- [Security](../SECURITY.md): vulnerability reporting.

package/docs/assets/architecture.svg

@@ -0,0 +1,156 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 720" role="img" aria-labelledby="title desc">
+  <title id="title">Three ways to use Skillmux</title>
+  <desc id="desc">One canonical skill vault supports native skill management and local MCP retrieval through the Skillmux CLI, plus a shared HTTP MCP service through the full or slim Skillmux server image.</desc>
+
+  <defs>
+    <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
+      <feDropShadow dx="0" dy="5" stdDeviation="8" flood-color="#0f172a" flood-opacity="0.10"/>
+    </filter>
+    <marker id="arrow-teal" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#0f766e"/>
+    </marker>
+    <marker id="arrow-blue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#2563eb"/>
+    </marker>
+    <marker id="arrow-violet" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M0 0L10 5L0 10Z" fill="#7c3aed"/>
+    </marker>
+    <style>
+      text {
+        font-family: "DejaVu Sans", Arial, sans-serif;
+      }
+      .title {
+        font-size: 27px;
+        font-weight: 750;
+        fill: #0f172a;
+      }
+      .subtitle {
+        font-size: 16px;
+        font-weight: 400;
+        fill: #475569;
+      }
+      .card-title {
+        font-size: 21px;
+        font-weight: 750;
+        fill: #0f172a;
+      }
+      .label {
+        font-size: 15px;
+        font-weight: 650;
+        fill: #1e293b;
+      }
+      .body {
+        font-size: 14px;
+        font-weight: 400;
+        fill: #475569;
+      }
+      .mono {
+        font-family: "DejaVu Sans Mono", Consolas, monospace;
+        font-size: 14px;
+        font-weight: 650;
+        fill: #1e293b;
+      }
+      .mono-light {
+        fill: #ffffff;
+      }
+      .chip {
+        font-size: 12px;
+        font-weight: 750;
+        letter-spacing: .5px;
+      }
+    </style>
+  </defs>
+
+  <rect width="1200" height="720" rx="24" fill="#f8fafc"/>
+  <rect x="1" y="1" width="1198" height="718" rx="23" fill="none" stroke="#e2e8f0" stroke-width="2"/>
+
+  <text x="48" y="50" class="title">One vault, three ways to use Skillmux</text>
+  <text x="48" y="78" class="subtitle">Choose a local workflow or serve the same retrieval contract to several clients.</text>
+
+  <g filter="url(#shadow)">
+    <rect x="330" y="106" width="540" height="118" rx="18" fill="#ffffff" stroke="#cbd5e1" stroke-width="2"/>
+    <circle cx="374" cy="147" r="18" fill="#0f172a"/>
+    <path d="M364 141H377L383 147L377 153H364M370 135V159" fill="none" stroke="#ffffff" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+    <text x="408" y="144" class="card-title">Canonical skill vault</text>
+    <text x="408" y="172" class="mono">~/skills/&lt;skill-id&gt;/SKILL.md</text>
+    <text x="408" y="200" class="body">Install · scan · pin · index · inspect usage</text>
+    <rect x="701" y="139" width="137" height="34" rx="9" fill="#f1f5f9" stroke="#cbd5e1"/>
+    <text x="769.5" y="161" text-anchor="middle" class="mono">skillmux.toml</text>
+  </g>
+
+  <path d="M480 224V252H220V277" fill="none" stroke="#0f766e" stroke-width="3" marker-end="url(#arrow-teal)"/>
+  <path d="M600 224V277" fill="none" stroke="#2563eb" stroke-width="3" marker-end="url(#arrow-blue)"/>
+  <path d="M720 224V252H980V277" fill="none" stroke="#7c3aed" stroke-width="3" marker-end="url(#arrow-violet)"/>
+
+  <g filter="url(#shadow)">
+    <rect x="40" y="284" width="360" height="302" rx="18" fill="#ffffff" stroke="#99d5cc" stroke-width="2"/>
+    <rect x="62" y="306" width="91" height="26" rx="13" fill="#ccfbf1"/>
+    <text x="107.5" y="324" text-anchor="middle" class="chip" fill="#115e59">USE CASE 1</text>
+    <text x="62" y="365" class="card-title">Skillmux CLI</text>
+    <text x="62" y="390" class="body">Manage native skills on the client machine.</text>
+
+    <rect x="62" y="414" width="276" height="48" rx="10" fill="#f0fdfa" stroke="#99d5cc"/>
+    <text x="200" y="444" text-anchor="middle" class="mono">skillmux init · sync</text>
+    <path d="M200 462V487" fill="none" stroke="#0f766e" stroke-width="2.5" marker-end="url(#arrow-teal)"/>
+    <rect x="62" y="493" width="276" height="49" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="200" y="514" text-anchor="middle" class="label">Native skill directories</text>
+    <text x="200" y="533" text-anchor="middle" class="body">managed core and project links</text>
+
+    <text x="62" y="570" class="body">Install with</text>
+    <rect x="160" y="550" width="85" height="27" rx="8" fill="#0f172a"/>
+    <text x="202.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#ffffff">BUN PACKAGE</text>
+    <rect x="251" y="550" width="87" height="27" rx="8" fill="#f1f5f9" stroke="#cbd5e1"/>
+    <text x="294.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#334155"><tspan x="294.5">LINUX</tspan><tspan x="294.5" dy="11">EXECUTABLE</tspan></text>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="420" y="284" width="360" height="302" rx="18" fill="#ffffff" stroke="#93c5fd" stroke-width="2"/>
+    <rect x="442" y="306" width="91" height="26" rx="13" fill="#dbeafe"/>
+    <text x="487.5" y="324" text-anchor="middle" class="chip" fill="#1d4ed8">USE CASE 2</text>
+    <text x="442" y="365" class="card-title">Add local MCP retrieval</text>
+    <text x="442" y="390" class="body">Run Skillmux beside one MCP client.</text>
+
+    <rect x="442" y="414" width="102" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="493" y="444" text-anchor="middle" class="label">AI client</text>
+    <path d="M544 438H573" fill="none" stroke="#2563eb" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
+    <text x="558" y="428" text-anchor="middle" class="body">stdio</text>
+    <rect x="579" y="414" width="179" height="48" rx="10" fill="#eff6ff" stroke="#93c5fd"/>
+    <text x="668.5" y="444" text-anchor="middle" class="label">Local Skillmux</text>
+
+    <rect x="442" y="484" width="316" height="58" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="600" y="507" text-anchor="middle" class="label">FTS5 + local GTE-small</text>
+    <text x="600" y="530" text-anchor="middle" class="body">downloaded and cached on this machine</text>
+
+    <text x="442" y="570" class="body">Skillmux CLI: Bun package or Linux executable</text>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="800" y="284" width="360" height="302" rx="18" fill="#ffffff" stroke="#c4b5fd" stroke-width="2"/>
+    <rect x="822" y="306" width="91" height="26" rx="13" fill="#ede9fe"/>
+    <text x="867.5" y="324" text-anchor="middle" class="chip" fill="#6d28d9">USE CASE 3</text>
+    <text x="822" y="365" class="card-title">Run a shared MCP service</text>
+    <text x="822" y="390" class="body">Serve several clients from one deployment.</text>
+
+    <rect x="822" y="414" width="102" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="873" y="435" text-anchor="middle" class="label">AI clients</text>
+    <text x="873" y="453" text-anchor="middle" class="body">one or more</text>
+    <path d="M924 438H953" fill="none" stroke="#7c3aed" stroke-width="2.5" marker-end="url(#arrow-violet)"/>
+    <text x="938" y="428" text-anchor="middle" class="body">HTTP</text>
+    <rect x="959" y="414" width="179" height="48" rx="10" fill="#f5f3ff" stroke="#c4b5fd"/>
+    <text x="1048.5" y="435" text-anchor="middle" class="label">Skillmux server</text>
+    <text x="1048.5" y="453" text-anchor="middle" class="mono">POST /mcp</text>
+
+    <rect x="822" y="484" width="148" height="58" rx="10" fill="#f5f3ff" stroke="#c4b5fd"/>
+    <text x="896" y="507" text-anchor="middle" class="label">Full image</text>
+    <text x="896" y="530" text-anchor="middle" class="body">GTE-small included</text>
+    <rect x="982" y="484" width="156" height="58" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="1060" y="507" text-anchor="middle" class="label">Slim image</text>
+    <text x="1060" y="530" text-anchor="middle" class="body">remote or lexical</text>
+
+    <text x="822" y="570" class="body">Recommended for a shared HTTP deployment</text>
+  </g>
+
+  <rect x="420" y="616" width="740" height="66" rx="14" fill="#0f172a"/>
+  <text x="444" y="643" class="chip" fill="#cbd5e1">SHARED MCP CONTRACT</text>
+  <text x="444" y="667" class="mono mono-light">retrieve → rerank → resolve_skill / fetch_skill → verified SKILL.md</text>
+</svg>

package/docs/calibration.md

@@ -5,6 +5,9 @@ shortlist into `matched`, `ambiguous`, or `no_match`. It is an operator action,
 not background learning, and it currently runs only against a local Skillmux
 target.
 
+Read [MCP routing](mcp-routing.md#retrieval-pipeline) before calibrating a new
+retrieval deployment.
+
 ## Lifecycle
 
 The complete workflow is:
@@ -75,7 +78,9 @@ a new `run_id`; the active policy remains unchanged until one is applied.
 
 ## Local and remote targets
 
-Calibration is local-only in this release. Local commands operate on the
+Here, `local` and `remote` name CLI administration targets, not inference
+locations or MCP transports. Calibration is local-target-only in this release.
+Local commands operate on the
 configured local vault, index, inference endpoints, dataset path, evidence
 database, and TOML file. Human output always prints `Target: local`; JSON output
 uses `"target": "local"`.

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
+```