@klhapp/skillmux 1.3.4 → 1.4.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1](https://github.com/klhq/skillmux/compare/v1.4.0...v1.4.1) (2026-08-04)
+
+
+### Fixed
+
+* **ci:** publish npm package to GitHub Packages ([#110](https://github.com/klhq/skillmux/issues/110)) ([5de37f2](https://github.com/klhq/skillmux/commit/5de37f22a658187cd270743b24237844513c1e54))
+
+## [1.4.0](https://github.com/klhq/skillmux/compare/v1.3.4...v1.4.0) (2026-08-04)
+
+
+### Added
+
+* **cli:** add version flag ([a5ca750](https://github.com/klhq/skillmux/commit/a5ca7508b6818764eeeaff4000115ac91769d6c0))
+* **cli:** clarify Docker command guidance ([3fc61b0](https://github.com/klhq/skillmux/commit/3fc61b0d262a20237f38df0a63eca2982aec382d))
+* **cli:** guide unsupported container commands ([9857098](https://github.com/klhq/skillmux/commit/9857098f5ce1ae0436afc23cfec5aba7e0069d8c))
+* **cli:** improve Docker command guidance ([cb1f4b7](https://github.com/klhq/skillmux/commit/cb1f4b707feca49cb7b6a627182bbbab889b8361))
+* **cli:** show Docker-specific help ([b6a7495](https://github.com/klhq/skillmux/commit/b6a74955539aef6613781949df65ffd9c01aade7))
+* **config:** show deployment identity in status ([40b355f](https://github.com/klhq/skillmux/commit/40b355fdea40e78b090faee87d349c364892d956))
+* **docker:** label image variants ([d2db3f5](https://github.com/klhq/skillmux/commit/d2db3f53c16506af65dd89a39b2d05de8f4d905a))
+* **doctor:** report deployment identity ([2db45d6](https://github.com/klhq/skillmux/commit/2db45d62da1be0985d2e8faa7abfa65c2a45f1c9))
+* **doctor:** report healthy slim lexical retrieval ([9cac7e0](https://github.com/klhq/skillmux/commit/9cac7e0f603b07075daf202db19712c0400539a8))
+* **doctor:** show retrieval capability ([5a344e7](https://github.com/klhq/skillmux/commit/5a344e71ebe65ba85353d28207ba3887432d3eff))
+* **ops:** expose deployment identity in metrics ([81f761e](https://github.com/klhq/skillmux/commit/81f761e9ff735c512395b68479f33eb2c3db0352))
+* **status:** expose deployment identity ([d83d22a](https://github.com/klhq/skillmux/commit/d83d22ad84beb39a993b0ade48ebee7e60d87145))
+* **status:** expose remote deployment identity ([e7be736](https://github.com/klhq/skillmux/commit/e7be73656a833057d55146b09f8bfd6d6c3f6a60))
+
+
+### Fixed
+
+* pass configPath to getEffectiveConfig in PATCH /admin/v1/config handler ([f46b7e2](https://github.com/klhq/skillmux/commit/f46b7e2f97167d4c8bb02a56973d6e5325dd55a8))
+* **startup:** allow serving without config paths ([ee98959](https://github.com/klhq/skillmux/commit/ee989596ed569d964eb37303b52b1538f62be39a))
+
 ## [1.3.4](https://github.com/klhq/skillmux/compare/v1.3.3...v1.3.4) (2026-08-02)
 
 

package/README.md

@@ -10,31 +10,47 @@
 </p>
 
 Skillmux manages [`SKILL.md`](https://agentskills.io) collections across AI
-coding clients. Keep one vault source of truth, pin a small set into native
-skill directories, and retrieve the rest through MCP. On one machine, the
-source and checkout can be the same directory. In a shared deployment, each
-machine that manages native skills and the server use their own checkout; Git
-or your deployment process keeps those checkouts current.
+coding clients. Keep one **vault source of truth**—the logical skill
+collection—pin a small set into native skill directories, and retrieve the
+rest through MCP. A **vault checkout** is a physical copy of that collection.
+On one machine, `~/skills` can be both the source of truth and its checkout.
+
+For a shared topology, the Git-backed vault source of truth has a checkout on
+each client machine, where the Skillmux CLI creates native pins, and a checkout
+on the server, where Skillmux server exposes HTTP MCP. Skillmux does not pull,
+push, replicate, or determine freshness between checkouts; Git and the
+deployment process own replication and freshness. See
+[native pins with shared retrieval](docs/deployment.md#native-pins-with-shared-retrieval).
 
 The same Skillmux CLI manages native skills and can serve local stdio MCP.
 Most individual users need only the CLI. Add Docker when you need a shared or
 always-on HTTP service.
 
+`skillmux serve` starts local stdio without a config file. `skillmux serve
+--transport http` likewise starts on loopback with safe defaults; create a
+config only when you need to customize the vault, inference, or server policy.
+See [Configuration](docs/configuration.md#machine-config-bootstrap) and
+[Deployment](docs/deployment.md) for those next steps.
+
 Choose a setup by the job:
 
 1. Need native skills or local MCP for one client? Install the **Skillmux CLI**.
-2. On Linux without Bun? Install the standalone Linux executable instead; it is
-   the same CLI.
-3. Need one shared HTTP MCP service? Deploy the **full Docker image**, the
+2. On Linux when Bun is undesirable? Use the **standalone Linux executable**;
+   it is the same Skillmux CLI.
+3. Need one shared HTTP MCP service? Deploy the **full image**, the
    self-contained default with GTE-small.
 4. Already have remote embeddings, or intentionally want lexical-only
-   retrieval? Use the **slim** image; see [Deployment](docs/deployment.md).
-5. Need native pins and shared retrieval? Run the CLI on the machines that own
+   retrieval? Use the **slim image**; see [Deployment](docs/deployment.md).
+
+For native pins and shared retrieval, run the Skillmux CLI on the machines that own
    client directories and one shared server for routed retrieval. MCP-only
-   clients connect over HTTP and do not need the CLI.
+clients connect over HTTP and do not need the Skillmux CLI.
 
 Manage the server's vault checkout outside the container. Use the CLI for
-Skillmux operations and Git or your deployment process for replication.
+Skillmux operations and Git or your deployment process for replication and
+freshness; server images do not manage host agent directories.
+If a server image rejects a management command, its error names the host CLI
+command to run; see the [container command contract](docs/deployment.md#container-command-contract).
 
 ## One vault source of truth, three ways to use it
 
@@ -58,17 +74,28 @@ skillmux --help
 
 Native target sync needs permission to create directory symlinks on Windows.
 
-On Linux, you can install a standalone AMD64 or ARM64 executable instead:
+On Linux, you can install a standalone executable instead. This path needs no
+GitHub CLI or package manager. It selects AMD64 or ARM64, downloads the pinned
+`v1.3.4` release, and verifies the SHA-256 digest published for that release:
 
 ```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
+version=v1.3.4
+case "$(uname -m)" in
+  x86_64|amd64) asset=skillmux-linux-amd64; sha256=0d0155475748a937ac9b5878c57e1fa14d8fe6957317cb43bbdafd710cbc1966 ;;
+  aarch64|arm64) asset=skillmux-linux-arm64; sha256=8cd186707221a8fefbb79eac46ef14d0c5fdae08a2d76e64a01af17a80af0e06 ;;
+  *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
+esac
+bin_dir="${SKILLMUX_BIN_DIR:-$HOME/.local/bin}"
+curl --fail --location --output "$asset" "https://github.com/klhq/skillmux/releases/download/$version/$asset"
+printf '%s  %s\n' "$sha256" "$asset" | sha256sum --check -
+install -Dm755 "$asset" "$bin_dir/skillmux"
 ```
 
-Use `skillmux-linux-arm64` on ARM64. See [Deployment](docs/deployment.md) for
-the full and slim Docker images.
+Ensure `~/.local/bin` is on `PATH`. To install system-wide, explicitly choose
+the target: `sudo install -Dm755 "$asset" /usr/local/bin/skillmux`. For GitHub
+build-provenance verification, use the [attested GitHub CLI procedure](docs/getting-started.md#install-with-github-cli-attestation).
+See [Deployment](docs/deployment.md) for the full and slim images of Skillmux
+server.
 
 ## Quick starts
 
@@ -148,6 +175,20 @@ under `docker.io/klhq/skillmux`.
 The [getting-started guide](docs/getting-started.md) provides complete recipes
 for all three setups.
 
+### HTTP surfaces
+
+| Surface | User | Purpose | CLI required |
+| --- | --- | --- | --- |
+| `/mcp` | AI clients | Resolve and fetch skills | No |
+| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+
+MCP clients authenticate only to `/mcp` with the MCP bearer token. Operators
+use a separate administrative bearer token for `/admin/v1/*`; neither token
+authorizes the other surface. Named CLI contexts administer the deployed server
+only. They never install, pin, synchronize, or otherwise manage skill
+directories on remote client machines. See [Deployment](docs/deployment.md#http-surfaces)
+for configuration and examples.
+
 ## Add and inspect skills
 
 Install a skill from a Git repository:
@@ -235,11 +276,11 @@ Start with the [documentation hub](docs/README.md).
 | [Concepts](docs/concepts.md) | Delivery tiers, deployment topologies, retrieval modes, and ownership |
 | [Managing skills](docs/skill-management.md) | Install, scan, pin, sync, report, overlays, and recovery |
 | [MCP routing](docs/mcp-routing.md) | Tools, outcomes, transports, retrieval, fallback, and integrity |
-| [Deployment](docs/deployment.md) | Docker, HTTP, auth, CORS, rate limits, health, and metrics |
-| [Configuration](docs/configuration.md) | Machine config, inference, manifests, and overlays |
-| [CLI reference](docs/cli.md) | Commands, contexts, automation, JSON output, and exit codes |
+| [Deployment](docs/deployment.md) | Docker, container command boundaries, HTTP surfaces and auth, CORS, rate limits, and comparable CLI, health, and metrics status |
+| [Configuration](docs/configuration.md) | Machine config, inference, HTTP surfaces, manifests, overlays, and container read-only configuration |
+| [CLI reference](docs/cli.md) | Host and container command surfaces, administrative contexts, automation, JSON output, and exit codes |
 | [Policy calibration](docs/calibration.md) | Labelled datasets, certification, and threshold application |
-| [Troubleshooting](docs/troubleshooting.md) | `doctor`, common failures, and migration notes |
+| [Troubleshooting](docs/troubleshooting.md) | `doctor`, deployment identity, common failures, and migration notes |
 | [MCP schema](docs/schema.json) | JSON Schema 2020-12 tool contract |
 
 ## Development

package/docs/README.md

@@ -1,23 +1,45 @@
 # Skillmux documentation
 
-Skillmux manages one `SKILL.md` vault. Choose a workflow based on where skills
-need to appear and where Skillmux should run.
+Skillmux manages one `SKILL.md` vault source of truth: the logical skill
+collection. A vault checkout is a physical copy used by a client machine or
+server. On one machine, `~/skills` can be both. Choose a workflow based on
+where skills need to appear and where Skillmux should run.
 
-## Choose a use case
+## Choose a setup
 
-| 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 |
+1. [Install the Skillmux CLI](getting-started.md#install-the-cli) for native
+   skills or one local MCP client.
+2. On Linux, use the [standalone executable install](getting-started.md#install-the-cli)
+   when you want a pinned, checksum-verified CLI without `gh`; the
+   [GitHub CLI attestation path](getting-started.md#install-with-github-cli-attestation)
+   is also available for provenance verification.
+3. [Deploy the full image](getting-started.md#run-a-shared-mcp-service) for
+   shared HTTP through Skillmux server.
+4. Choose the **slim image** when using remote embeddings or lexical retrieval.
 
-You can combine native management and local MCP retrieval on one machine. The
-shared service uses the same MCP tools over HTTP.
+You can combine native management and local MCP retrieval on one machine. For
+native pins plus shared retrieval, run Skillmux CLI on each machine that owns
+client directories and deploy Skillmux server for HTTP MCP. The Bun package is
+the cross-platform CLI installation method; the standalone Linux executable is
+its Linux alternative. Git and the deployment process, not Skillmux, replicate
+vault checkouts and determine their freshness; see
+[Deployment](deployment.md#native-pins-with-shared-retrieval).
 
-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.
+Both `skillmux serve` (stdio) and `skillmux serve --transport http` start with
+safe defaults when no config file or config directory exists. Add a config only
+to customize behavior; see [Configuration](configuration.md#machine-config-bootstrap).
+
+## HTTP surfaces
+
+| Surface | User | Purpose | CLI required |
+| --- | --- | --- | --- |
+| `/mcp` | AI clients | Resolve and fetch skills | No |
+| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+
+The MCP and administrative surfaces use separate bearer tokens; possession of
+one does not grant access to the other. A named CLI context administers the
+deployed server only, never remote client skill directories. See
+[Deployment](deployment.md#http-surfaces) for authentication and examples.
 
 ## Learn the model
 
@@ -33,10 +55,13 @@ retrieval.
 ## Operate Skillmux
 
 - [Deployment](deployment.md): deploy the shared server, choose slim only when
-  needed, expose HTTP, and operate the service.
+  needed, understand its container command boundary, separate MCP from
+  administrative HTTP, compare deployment identity across CLI, health, and
+  metrics, 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.
+  server settings, local overlays, and container read-only configuration.
+- [CLI reference](cli.md): use host and container command surfaces,
+  administrative 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

package/docs/assets/architecture.svg

@@ -1,6 +1,6 @@
 <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>
+  <title id="title">One vault source of truth, three ways to use Skillmux</title>
+  <desc id="desc">One Git-backed vault source of truth has a client checkout for Skillmux CLI native management and local MCP retrieval, plus a server checkout for shared Streamable HTTP MCP. Resolve uses retrieval, fusion, and optional reranking; fetch returns the current SKILL.md directly. Git and deployment own checkout replication and freshness.</desc>
 
   <defs>
     <filter id="shadow" x="-15%" y="-15%" width="130%" height="140%">
@@ -64,72 +64,69 @@
   <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>
+  <text x="48" y="50" class="title">One vault source of truth, three ways to use Skillmux</text>
+  <text x="48" y="78" class="subtitle">Git and deployment replicate checkouts; Skillmux uses each checkout where it runs.</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>
+    <text x="408" y="144" class="card-title">Git-backed vault source of truth</text>
+    <text x="408" y="172" class="mono">logical SKILL.md collection</text>
+    <text x="408" y="200" class="body">Git + deployment own replication and freshness</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="M520 224V252H410V277" fill="none" stroke="#0f766e" stroke-width="3" marker-end="url(#arrow-teal)"/>
   <path d="M720 224V252H980V277" fill="none" stroke="#7c3aed" stroke-width="3" marker-end="url(#arrow-violet)"/>
+  <text x="394" y="270" text-anchor="end" class="body">client checkout</text>
+  <text x="996" y="270" text-anchor="start" class="body">server checkout</text>
 
   <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>
+    <rect x="40" y="284" width="740" height="302" rx="18" fill="#ffffff" stroke="#99d5cc" stroke-width="2"/>
+    <rect x="62" y="306" width="124" height="26" rx="13" fill="#ccfbf1"/>
+    <text x="124" y="324" text-anchor="middle" class="chip" fill="#115e59">SKILLMUX CLI</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>
+    <text x="62" y="390" class="body">A client-machine checkout supports native management and/or local MCP.</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>
+    <text x="200" y="435" text-anchor="middle" class="label">Native management</text>
+    <text x="200" y="453" 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>
+    <text x="62" y="570" class="body">Install Skillmux CLI with</text>
+    <rect x="270" y="550" width="85" height="27" rx="8" fill="#0f172a"/>
+    <text x="312.5" y="568" text-anchor="middle" class="chip" style="font-size: 10px" fill="#ffffff">BUN PACKAGE</text>
+    <rect x="361" y="550" width="87" height="27" rx="8" fill="#f1f5f9" stroke="#cbd5e1"/>
+    <text x="404.5" y="561" text-anchor="middle" class="chip" style="font-size: 10px" fill="#334155"><tspan x="404.5">LINUX</tspan><tspan x="404.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>
+    <rect x="420" y="414" width="338" height="128" rx="10" fill="#eff6ff" stroke="#93c5fd"/>
+    <text x="442" y="441" class="label">Local MCP retrieval</text>
+    <text x="442" y="463" class="body">Skillmux CLI beside one MCP client.</text>
+
+    <rect x="442" y="475" width="102" height="48" rx="10" fill="#f8fafc" stroke="#cbd5e1"/>
+    <text x="493" y="505" text-anchor="middle" class="label">AI client</text>
+    <path d="M544 499H573" fill="none" stroke="#2563eb" stroke-width="2.5" marker-end="url(#arrow-blue)"/>
+    <text x="558" y="489" text-anchor="middle" class="body">stdio</text>
+    <rect x="579" y="470" width="157" height="62" rx="10" fill="#ffffff" stroke="#93c5fd"/>
+    <text x="657.5" y="492" text-anchor="middle" class="label">Skillmux CLI</text>
+    <text x="657.5" y="511" text-anchor="middle" class="body">default: FTS5 +</text>
+    <text x="657.5" y="527" text-anchor="middle" class="body">local GTE-small</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>
+    <rect x="822" y="306" width="136" height="26" rx="13" fill="#ede9fe"/>
+    <text x="890" y="324" text-anchor="middle" class="chip" fill="#6d28d9">SKILLMUX SERVER</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>
+    <text x="822" y="390" class="body">Read a server checkout to serve several clients.</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>
@@ -138,7 +135,7 @@
     <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>
+    <text x="1048.5" y="453" text-anchor="middle" class="body" style="font-size: 13px">Streamable HTTP /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>
@@ -150,7 +147,8 @@
     <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>
+  <rect x="420" y="608" width="740" height="82" rx="14" fill="#0f172a"/>
+  <text x="444" y="633" class="chip" fill="#cbd5e1">MCP TOOL CONTRACT · STDIO + HTTP</text>
+  <text x="444" y="655" class="mono mono-light" style="font-size: 12px">resolve_skill → retrieve + fuse → optional rerank → matched / ambiguous / no_match</text>
+  <text x="444" y="677" class="mono mono-light" style="font-size: 12px">fetch_skill → exact current SKILL.md + SHA-256</text>
 </svg>

package/docs/cli.md

@@ -1,11 +1,14 @@
 # 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:
+The Bun package and standalone Linux executable expose the same Skillmux CLI.
+For Linux installation, use the [pinned checksum-verified download](getting-started.md#install-the-cli)
+or, when provenance verification is required, the
+[attested GitHub CLI path](getting-started.md#install-with-github-cli-attestation).
+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.
+administrative API only; they do not install, pin, synchronize, or otherwise
+manage skill directories on remote client machines.
 
 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
@@ -14,6 +17,20 @@ can call remote inference endpoints.
 For task-oriented workflows, start with [Getting started](getting-started.md)
 or [Managing skills](skill-management.md).
 
+## Running inside the Skillmux server image
+
+The Docker image is a shared-server runtime, not a replacement for the host
+CLI. Its `skillmux --help` surface is intentionally limited to `serve`,
+`index`, `doctor`, `report`, `scan`, `skill which`, and read-only `config`
+inspection (`show`, `get`, `validate`, `diff`, and `status`). Run `init`,
+`install`, pinning, `sync`, project or target management, model downloads,
+contexts, calibration, evaluation, and configuration changes on the host.
+
+When the image rejects one of those commands, it exits with code 2. JSON mode
+uses `CONTAINER_COMMAND_UNSUPPORTED` and includes `rejected_command`,
+`recommended_host_command`, and a deployment-guide URL. See [the container
+command contract](deployment.md#container-command-contract) for examples.
+
 ## Global options and target resolution
 
 Every target-aware command resolves its execution target deterministically in this order:
@@ -38,7 +55,10 @@ Every target-aware command resolves its execution target deterministically in th
 
 ## 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.
+Contexts store named deployed-server targets without embedding raw credentials.
+An associated token environment variable name (`token_env`) supplies only the
+administrative bearer token; it is not an MCP token and cannot authenticate an
+AI client to `/mcp`.
 
 ```sh
 # List all configured contexts (includes reserved 'local' context)
@@ -87,14 +107,19 @@ 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
+# Inspect runtime status, deployment identity, revision hashes, and readiness
 skillmux config status
 ```
 
+`config status` reports the service runtime separately from the deployment
+identity: `runtime` says whether the target is running, while
+`deployment_runtime` and `image_variant` match `doctor` and `/health/ready`.
+The JSON response contains no credential, API-key, or token values.
+
 `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.
+sync, or any other remote-client directory operation.
 
 ---
 
@@ -245,6 +270,11 @@ Config changes are categorized into live-reloadable and restart-required setting
 - **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`
 
+The config file is optional. `skillmux serve` starts with defaults if its
+config path or parent directory is absent. In that case reload is inactive
+until a restart finds a watchable parent directory; malformed updates to an
+active watched config are reported without replacing the last known good values.
+
 ---
 
 ## Skill introspection (`skillmux skill which`)
@@ -288,6 +318,18 @@ skillmux calibrate generate-dataset --out ./eval/queries.json
 
 ## Administrative HTTP API (`/admin/v1/*`)
 
+The HTTP server has two separate surfaces:
+
+| Surface | User | Purpose | CLI required |
+| --- | --- | --- | --- |
+| `/mcp` | AI clients | Resolve and fetch skills | No |
+| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+
+The MCP bearer token applies only to `/mcp`. The administrative bearer token
+below applies only to `/admin/v1/*`; neither credential grants access to the
+other surface. Named contexts use the latter to administer the deployed server,
+not any remote client skill directory.
+
 Remote servers expose administrative control endpoints under `/admin/v1/*` when enabled in configuration:
 
 ```toml

package/docs/concepts.md

@@ -15,15 +15,21 @@ 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
+## Vault source of truth and checkouts
 
-The vault is the source collection for Skillmux. Each direct child directory
-represents one skill and contains a `SKILL.md`.
+A **vault source of truth** is the logical skill collection for Skillmux. Each
+direct child directory represents one skill and contains a `SKILL.md`. A
+**vault checkout** is a physical copy of that collection on a machine.
 
-The default path is `~/skills`. Set `vault_path` in
-`~/.config/skillmux/config.toml` when you keep the collection elsewhere.
+The default vault checkout path is `~/skills`. Set `vault_path` in
+`~/.config/skillmux/config.toml` when its checkout lives elsewhere. On one
+machine, `~/skills` can be both the vault source of truth and its checkout.
+In a shared topology, use a Git-backed vault source of truth, a checkout on
+each client machine for the Skillmux CLI, and a checkout on the server for
+Skillmux server. Skillmux does not pull, push, replicate, or determine
+freshness between checkouts; Git and the deployment process own those jobs.
 
-Skillmux commands interact with the vault in two ways:
+Skillmux commands interact with the configured vault checkout in two ways:
 
 - management commands such as `install` and explicit config operations write
   to documented paths;
@@ -35,7 +41,7 @@ MCP delivery reads the current file bytes. It does not copy an indexed
 
 ## Delivery tiers
 
-Skillmux applies three policies to one vault:
+Skillmux applies three policies to one vault checkout:
 
 | Tier | Scope | Delivery |
 | --- | --- | --- |
@@ -52,8 +58,8 @@ 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.
+routed skills over stdio, while a shared Skillmux process can serve its server
+checkout over HTTP.
 
 ## Deployment topologies
 
@@ -61,20 +67,36 @@ vault over HTTP.
 | --- | --- | --- | --- |
 | 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 |
+| Shared MCP | Server or container host | Streamable HTTP | Skillmux server (full 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
+Linux executable; both expose the same commands. The **full image** is the
+default Skillmux server 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
+### HTTP surfaces
+
+An HTTP server has two separate surfaces:
+
+| Surface | User | Purpose | CLI required |
+| --- | --- | --- | --- |
+| `/mcp` | AI clients | Resolve and fetch skills | No |
+| `/admin/v1/*` | Operators | Inspect or update server configuration | Yes, when using named CLI contexts |
+
+MCP authentication protects `/mcp`; administrative authentication protects
+`/admin/v1/*`. Their bearer tokens are distinct and do not grant access across
+surfaces. A named CLI context is an operator connection to the deployed server,
+not a way to manage skill directories on remote client machines. The server
+and its full/slim images never manage host agent directories. See
+[Deployment](deployment.md#http-surfaces).
+
+The full 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
+package downloads and caches GTE-small when local inference first loads it;
+`skillmux models download` prefetches it. Neither Skillmux server image
 bundles a local reranker; configure one remotely when needed.
 
 ## Clients and targets
@@ -122,12 +144,13 @@ 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`.
+`local_vault_paths` layer machine-specific skill copies over the configured
+vault checkout. 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.
+core and project pins in the configured vault checkout because another machine
+may not have the overlay.
 
 ## Inference and retrieval capabilities