@klhapp/skillmux 1.3.3 → 1.4.0

package/docs/configuration.md

@@ -1,7 +1,9 @@
 # Configuration
 
-Skillmux manages one canonical vault and defaults to FTS5 plus GTE-small
-running in the Skillmux process. Most users need no config file.
+Skillmux manages one configured vault checkout and defaults to FTS5 plus
+GTE-small running in the Skillmux process. The vault source of truth is the
+logical collection; a vault checkout is its physical copy. Most users need no
+config file.
 
 Deployment and inference use separate terms:
 
@@ -13,14 +15,30 @@ Deployment and inference use separate terms:
 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
+Published server images set `SKILLMUX_IMAGE_VARIANT=full` or
+`SKILLMUX_IMAGE_VARIANT=slim` themselves. It is an operational identity value,
+not an inference setting; use `doctor`, `config status`, `/health/ready`, or
+the deployment-info metric to inspect it. Do not put credentials or token
+values in any of those outputs.
+
+Read [Concepts](concepts.md#vault-source-of-truth-and-checkouts) for vault
+terms and the delivery model. For detailed CLI
 commands, target resolution, and automation envelopes, see
-[CLI reference](cli.md). For labelled datasets, threshold certification,
+[CLI reference](cli.md). For Linux CLI installation, see the
+[pinned checksum-verified download](getting-started.md#install-the-cli) or the
+[attested GitHub CLI path](getting-started.md#install-with-github-cli-attestation).
+For labelled datasets, threshold certification,
 reference values, and the apply lifecycle, see
 [Policy calibration](calibration.md).
 
 ## Machine config bootstrap
 
+Configuration is optional: `skillmux serve` and `skillmux serve --transport
+http` start with defaults even when `~/.config/skillmux` does not exist. The
+optional config watcher does not create that directory; reload stays inactive
+until the server starts with a watchable config parent. Once active, malformed
+updates are reported and the last known good configuration remains in use.
+
 Create `~/.config/skillmux/config.toml` from a populated vault:
 
 ```sh
@@ -48,7 +66,7 @@ mode = "local"
 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
+loads it and cache it in `~/.cache/skillmux/models`. The full image
 already contains the model.
 
 Skillmux combines FTS5 and cosine result lists with reciprocal-rank fusion.
@@ -138,6 +156,13 @@ clearly-scoped BGE reference profile for smoke tests.
 
 ## HTTP server
 
+The HTTP server provides separate MCP and administrative 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 |
+
 ```toml
 [server]
 hostname = "127.0.0.1"
@@ -149,12 +174,28 @@ allowed_origins = []
 enabled = false
 requests_per_minute = 60
 trust_proxy = false
+
+[server.admin]
+enabled = false
+token_env = "SKILLMUX_ADMIN_TOKEN"
 ```
 
 Defaults are loopback-only (`hostname = "127.0.0.1"`) with CORS deny-by-default (`allowed_origins = []`) — a zero-config `skillmux serve --transport http` is not reachable from the network or from a browser tab on another origin. Docker sets `hostname` to `0.0.0.0` automatically (`RUNNING_IN_DOCKER=true`) since port-mapping needs the container to accept connections on all interfaces.
 
 Before exposing HTTP beyond localhost, set `hostname` to a reachable interface, `auth_enabled = true` with a token, and populate `allowed_origins` with the specific origins that need browser access. `rate_limit.trust_proxy` should stay `false` unless a trusted reverse proxy sets `X-Forwarded-For` — it's otherwise a client-controlled, spoofable header and trusting it defeats per-client rate limiting.
 
+`server.auth_token_env` names the MCP token for AI clients calling `/mcp`.
+`server.admin.token_env` names a distinct administrative token for operators
+calling `/admin/v1/*` when that API is enabled. Do not reuse or imply either
+token authorizes the other surface. Named CLI contexts use the administrative
+token to inspect or update the deployed server configuration only; they cannot
+install, pin, synchronize, or otherwise manage remote client skill directories.
+Docker images likewise do not manage host agent directories.
+Inside the server image, only read-only `config show`, `get`, `validate`,
+`diff`, and `status` are available. Run `config init` or `config set` with the
+host CLI; the image returns `CONTAINER_COMMAND_UNSUPPORTED` with the exact host
+command to run. See [Deployment](deployment.md#container-command-contract).
+
 ## Tiers and the manifest
 
 `skillmux init` and `skillmux sync` manage native delivery by pinning selected
@@ -205,7 +246,12 @@ Both commands accept one or more `skill_id` arguments per call; all of them are
 >
 > **Breaking change:** `[project.<group>].repos` has been renamed to `paths` — it was never required to be a git repository, just a local directory, and the old name collided in meaning with `skillmux install <repo>`'s unrelated git-source `repo` concept. A manifest still using `repos` fails to parse with an error pointing at `paths`; migrate by renaming the key (values are unchanged).
 
-Every `[core]`/`[project.*]` skill_id must resolve from the canonical `vault_path` — pinning a skill that only exists in a `local_vault_paths` entry (see below) fails `sync` with a distinct error, since the manifest is meant to be portable across machines and a machine-local override wouldn't exist elsewhere. `doctor` validates the manifest as part of its checks, surfacing any violation without writing anything back.
+Every `[core]`/`[project.*]` skill_id must resolve from the configured
+`vault_path` checkout — pinning a skill that only exists in a
+`local_vault_paths` entry (see below) fails `sync` with a distinct error, since
+the manifest is meant to be portable across machines and a machine-local
+override wouldn't exist elsewhere. `doctor` validates the manifest as part of
+its checks, surfacing any violation without writing anything back.
 
 ### Ownership marker
 
@@ -236,7 +282,7 @@ cannot be inferred.
 `local_vault_paths` (in `config.toml`, alongside `vault_path`) lets one machine layer override-only skills on top of the shared vault — a skill being authored locally, a machine-specific script, or a patched copy of an upstream skill — without touching `vault_path` itself:
 
 ```toml
-vault_path = "~/skills"                 # unchanged: canonical, owns skillmux.toml and the sync git hook
+vault_path = "~/skills"                 # configured checkout; owns skillmux.toml and the sync git hook
 local_vault_paths = ["~/skills-local"]   # optional, default []: override-only, checked first
 ```
 

package/docs/deployment.md

@@ -6,12 +6,16 @@ Choose a deployment from the client count and inference source:
 | --- | --- | --- | --- |
 | Native skill management | Skillmux CLI | Filesystem | None required |
 | Local MCP retrieval | Skillmux CLI | stdio | Downloaded GTE-small |
-| Shared MCP with local inference | Full Docker image | Streamable HTTP | Bundled GTE-small |
-| Shared MCP with remote or lexical retrieval | Slim Docker image (advanced) | Streamable HTTP | Remote endpoint or lexical fallback |
+| Shared MCP with local inference | Skillmux server (full image) | Streamable HTTP | Bundled GTE-small |
+| Shared MCP with remote or lexical retrieval | Skillmux server (slim image, advanced) | Streamable HTTP | Remote endpoint or lexical fallback |
 
 Install the CLI with either the Bun package or standalone Linux executable;
-they expose the same commands and can also serve HTTP. Deploy the full Docker
-image for a shared service by default. Docker can serve stdio when a client
+they expose the same commands and can also serve HTTP. The Linux executable
+has a [pinned, checksum-verified download](getting-started.md#install-the-cli)
+that defaults to `~/.local/bin`, plus an
+[attested GitHub CLI path](getting-started.md#install-with-github-cli-attestation).
+Deploy the full image
+for a shared Skillmux server by default. Docker can serve stdio when a client
 requires a container command; use slim only for remote or lexical retrieval.
 
 “Local inference” means the model runs in the Skillmux process. It does not
@@ -36,7 +40,11 @@ skillmux serve --transport http --port 3000
 The native HTTP server binds `127.0.0.1` by default. Configure authentication
 and a reachable hostname before serving other machines.
 
-## Docker images
+Neither native command needs a config file or an existing `~/.config/skillmux`
+directory. They use safe defaults until you add a config for a vault checkout,
+remote inference, or server policy.
+
+## Skillmux server images
 
 Skillmux publishes Linux AMD64 and ARM64 images to GHCR and Docker Hub:
 
@@ -82,6 +90,10 @@ without arguments starts Streamable HTTP MCP on port 3000:
 docker run ghcr.io/klhq/skillmux:latest
 ```
 
+This default works without mounting or creating a config path. The image uses
+`/vault` and `/data`; mount them when you need a persistent vault checkout or
+index state.
+
 Arguments after the image replace that default, so one-shot maintenance and
 stdio use the same image:
 
@@ -105,6 +117,13 @@ context management, calibration, evaluation, and configuration initialization
 or mutation. Install the Skillmux CLI on the host when a command needs to
 manage a local vault or agent directory.
 
+A rejected command exits with code 2 and tells you the exact host command to
+run. In `--json` mode, the error code is
+`CONTAINER_COMMAND_UNSUPPORTED`; `error.details.rejected_command`,
+`recommended_host_command`, and `documentation` are stable automation fields.
+For example, `docker run --rm ghcr.io/klhq/skillmux:latest models download
+--json` recommends `skillmux models download` on the host.
+
 ## Slim image
 
 The slim image stays ready in lexical mode without an inference endpoint.
@@ -154,6 +173,19 @@ docker run --no-healthcheck -i --rm \
 The container must keep standard input open, so use `-i`. Disable the baked
 HTTP health check for stdio because no HTTP listener is started.
 
+## HTTP surfaces
+
+The shared server exposes two distinct 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 |
+
+Configure and distribute separate bearer tokens. An MCP token authenticates an
+AI client to `/mcp` only; an administrative token authenticates an operator to
+`/admin/v1/*` only. Neither token grants access to the other surface.
+
 ## Expose HTTP safely
 
 The Skillmux CLI binds `127.0.0.1`. Docker binds `0.0.0.0` so
@@ -170,24 +202,32 @@ allowed_origins = []
 enabled = true
 requests_per_minute = 60
 trust_proxy = false
+
+[server.admin]
+enabled = true
+token_env = "SKILLMUX_ADMIN_TOKEN"
 ```
 
 Set the token in the process environment:
 
 ```sh
-export SKILLMUX_AUTH_TOKEN="replace-with-a-long-random-token"
+export SKILLMUX_AUTH_TOKEN="replace-with-an-mcp-token"
+export SKILLMUX_ADMIN_TOKEN="replace-with-a-separate-admin-token"
 skillmux serve --transport http
 ```
 
 Clients send:
 
 ```text
-Authorization: Bearer replace-with-a-long-random-token
+Authorization: Bearer replace-with-an-mcp-token
 ```
 
 `allowed_origins` controls browser CORS requests. Requests without an `Origin`
 header, including MCP clients and curl, do not need a CORS entry.
 
+The `Authorization` example above is for an MCP client calling `/mcp`.
+Administrative requests instead use the token named by `server.admin.token_env`.
+
 Keep `trust_proxy = false` unless a trusted reverse proxy overwrites
 `X-Forwarded-For`. A client can spoof that header when it reaches Skillmux
 directly.
@@ -199,22 +239,27 @@ The HTTP server provides:
 | Endpoint | Purpose |
 | --- | --- |
 | `GET /health/live` | Process liveness |
-| `GET /health/ready` | Vault, index, inference, and active capability |
+| `GET /health/ready` | Vault, index, inference, active capability, version, runtime, and image variant |
 | `GET /health` | Compatibility alias for liveness |
 | `GET /metrics` | Prometheus text exposition |
 | `GET /stats` | Aggregated routing outcomes for `skillmux report` |
 | `POST /mcp` | Streamable HTTP MCP transport |
+| `/admin/v1/*` | Administrative configuration API (when enabled) |
 
 The Docker health check calls `/health/ready`.
 
-Prometheus metrics cover request totals, resolve outcomes, latency, errors, and
-rate-limit rejections. Health and metrics do not require bearer authentication,
-but `/stats` does when server authentication is enabled. CORS still applies to
+Prometheus metrics cover request totals, resolve outcomes, latency, errors,
+rate-limit rejections, and a `skill_router_deployment_info` gauge labelled with
+`version`, `runtime`, and `image_variant`. The values match `skillmux doctor`,
+`skillmux config status`, and `/health/ready`; use `image_variant="none"` for
+a host runtime. These operational outputs never include credentials, API keys,
+or token values. Health and metrics do not require bearer authentication, but
+`/stats` does when server authentication is enabled. CORS still applies to
 browser requests.
 
 ## Remote administration
 
-Name a deployed server without storing its token:
+Name a deployed server without storing its **administrative** token:
 
 ```sh
 skillmux context add prod \
@@ -225,17 +270,25 @@ skillmux config status
 ```
 
 The context stores the token environment variable name. Export its value in
-the shell before running admin commands.
+the shell before running admin commands. This token is separate from the MCP
+token configured with `server.auth_token_env`; it does not authenticate MCP
+clients.
 
 Enable the admin API and use a separate admin token in server configuration.
 Read [CLI reference](cli.md#administrative-http-api-adminv1) for routes and
 [Configuration](configuration.md#http-server) for reload behavior.
 
+Named contexts administer the deployed server configuration only. They do not
+install, pin, synchronize, or otherwise manage skill directories on remote
+client machines. Run those filesystem-management commands through Skillmux CLI
+on the machine that owns the directories. The full and slim server images read
+their mounted vault checkout and do not manage host agent directories.
+
 ## Persistent data and backups
 
 Persist `state_dir` to retain the index, audit log, and calibration evidence.
-Skill content remains in the vault and should use its own backup or Git
-workflow.
+Skill content remains in the server's vault checkout and should use its own
+backup or Git workflow.
 
 Treat the state database as sensitive because audit rows can contain raw user
 queries. Stop the process or use SQLite-safe backup tooling before copying a
@@ -243,8 +296,11 @@ live database.
 
 ## Native pins with shared retrieval
 
-For the combined topology, use one Git-backed vault source of truth: each
-machine that manages native skills keeps its own checkout and runs the CLI;
-the shared service mounts its own checkout for retrieval. Skillmux does not
-pull, push, replicate, or otherwise keep those vault checkouts fresh—Git and
-your deployment process own that responsibility.
+For the combined topology, use one Git-backed vault source of truth. A vault
+checkout is a physical copy: each machine that manages native skills keeps its
+own checkout and runs the Skillmux CLI; the shared service mounts its own
+checkout for retrieval. On one machine, `~/skills` can be both the source of
+truth and its checkout. Skillmux does not pull, push, replicate, or determine
+freshness between checkouts; Git and your deployment process own that
+responsibility. The server image reads its mounted checkout and does not manage
+host agent directories.

package/docs/getting-started.md

@@ -7,7 +7,7 @@ an 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 |
+| [Run a shared MCP service](#run-a-shared-mcp-service) | Streamable HTTP MCP | Skillmux server (full 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
@@ -25,23 +25,54 @@ 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:
+Linux users can install the standalone executable without the GitHub CLI or a
+package manager. This example selects AMD64 or ARM64, downloads the pinned
+`v1.3.4` release, verifies the SHA-256 digest published for that release, and
+installs to the user-writable default `~/.local/bin`:
 
 ```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"
 ```
 
-Replace `amd64` with `arm64` on ARM64. The Bun package and standalone Linux
-executable expose the same Skillmux CLI commands.
+Ensure `~/.local/bin` is on `PATH`. To use another user-writable location, set
+`SKILLMUX_BIN_DIR` before the command. A system-wide installation is an
+explicit choice: `sudo install -Dm755 "$asset" /usr/local/bin/skillmux`.
 
-## Prepare a vault
+### Install with GitHub CLI attestation
 
-Skillmux defaults to `~/skills`. Each direct child directory represents one
-skill:
+If you want GitHub build-provenance verification, use the GitHub CLI instead.
+This keeps the same pinned release and user-writable install location:
+
+```sh
+version=v1.3.4
+case "$(uname -m)" in
+  x86_64|amd64) asset=skillmux-linux-amd64 ;;
+  aarch64|arm64) asset=skillmux-linux-arm64 ;;
+  *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
+esac
+bin_dir="${SKILLMUX_BIN_DIR:-$HOME/.local/bin}"
+mkdir -p "$bin_dir"
+gh release download "$version" --repo klhq/skillmux --pattern "$asset" --dir "$bin_dir"
+gh attestation verify "$bin_dir/$asset" --repo klhq/skillmux
+install -m755 "$bin_dir/$asset" "$bin_dir/skillmux"
+```
+
+The Bun package and standalone Linux executable expose the same Skillmux CLI
+commands.
+
+## Prepare a vault checkout
+
+Skillmux defaults to the `~/skills` vault checkout. Each direct child directory
+represents one skill:
 
 ```text
 ~/skills/
@@ -95,9 +126,9 @@ The planner:
 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.
+in the configured vault checkout's `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:
 
@@ -214,13 +245,26 @@ authentication before exposing the service beyond a trusted host. Continue
 with [Deployment](deployment.md) for remote inference, network policy,
 monitoring, and backups.
 
+The server keeps its two HTTP surfaces separate:
+
+| 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 |
+
+Configure separate MCP and administrative bearer tokens; one never grants
+access to the other. Named CLI contexts can administer this deployed server,
+but cannot install, pin, synchronize, or otherwise manage skill directories on
+remote client machines. See [Deployment](deployment.md#http-surfaces).
+
 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:
+shared MCP endpoint. Keep one Git-backed vault source of truth. A vault
+checkout is its physical copy; on one machine, `~/skills` can be both:
 
 - each machine that owns client skill directories keeps its own checkout and
   runs the Skillmux CLI for `init`, pinning, and `sync`;
@@ -228,8 +272,8 @@ shared MCP endpoint. Keep one Git-backed vault as the source of truth:
   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.
+Skillmux does not pull, push, replicate, or determine freshness between
+checkouts. Git and your deployment process own vault replication and freshness.
 
 ## Next steps
 

package/docs/mcp-routing.md

@@ -1,12 +1,13 @@
 # MCP routing
 
-Skillmux exposes one vault through two Model Context Protocol tools. Choose a
-transport based on where the process runs:
+Skillmux exposes its configured vault checkout through two Model Context
+Protocol tools. A vault source of truth is the logical collection; a checkout
+is its physical copy. 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 |
+| Shared Skillmux server | Streamable HTTP | Full image by default; slim image 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.
@@ -55,6 +56,12 @@ The default host accepts loopback connections only. Configure authentication
 and network exposure before serving other machines. See
 [Deployment](deployment.md#expose-http-safely).
 
+This is the MCP surface for AI clients. Its bearer token applies only to
+`/mcp`; server configuration uses the separate operator surface at
+`/admin/v1/*`. AI clients do not need the CLI to use `/mcp`; named CLI contexts
+are for administering the deployed server, not remote client skill directories.
+See [Deployment](deployment.md#http-surfaces).
+
 ## Tool contract
 
 ### `resolve_skill`
@@ -115,7 +122,7 @@ Skillmux builds candidates in stages:
 
 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
+downloaded model under `~/.cache/skillmux/models`; the full image
 includes it. The slim image starts with lexical retrieval and can call an
 OpenAI-compatible embedding endpoint.
 

package/docs/releasing.md

@@ -37,10 +37,11 @@ The release workflow publishes:
 
 - `skillmux-linux-amd64`
 - `skillmux-linux-arm64`
+- SHA-256 digests for the Linux binaries in the GitHub Release asset metadata
 - GitHub build provenance attestations when the repository is public
-- Full image to GHCR and Docker Hub: `:<version>`, `:<major>.<minor>`,
+- Skillmux server full image to GHCR and Docker Hub: `:<version>`, `:<major>.<minor>`,
   and `:latest`; this variant includes GTE-small
-- Slim image to GHCR and Docker Hub: `:<version>-slim`,
+- Skillmux server slim image to GHCR and Docker Hub: `:<version>-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
@@ -75,10 +76,12 @@ Private repositories still publish BuildKit SBOM/provenance with container
 images, but GitHub artifact attestations are skipped because GitHub does not
 support them for user-owned private repositories.
 
-Verify downloaded binaries with build provenance attestation:
+Verify a downloaded binary with its published SHA-256 digest, or use GitHub
+CLI build-provenance attestation. Keep the release tag pinned:
 
 ```bash
-gh release download v0.1.1 --repo klhq/skillmux --pattern 'skillmux-linux-*'
+version=v1.3.4
+gh release download "$version" --repo klhq/skillmux --pattern skillmux-linux-amd64
 gh attestation verify skillmux-linux-amd64 --repo klhq/skillmux
 ./skillmux-linux-amd64 config show
 ```
@@ -93,3 +96,7 @@ docker run --rm \
 
 curl --fail http://127.0.0.1:3000/health/ready
 ```
+
+The image reads this vault checkout for retrieval; it does not manage host
+agent directories. Git and the deployment process own replication and
+freshness across vault checkouts.

package/docs/schema.json

@@ -38,8 +38,7 @@
         "query": {
           "type": "string",
           "description": "Natural-language task description to route. Normalized (NFC) by the server; never semantically rewritten.",
-          "minLength": 1,
-          "maxLength": 8192
+          "minLength": 1
         }
       },
       "required": ["query"],

package/docs/skill-management.md

@@ -1,12 +1,14 @@
 # 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.
+Skillmux keeps skill content in a vault checkout and materializes selected
+skills into client directories. The vault source of truth is the logical
+collection; a checkout is its physical copy. 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.
+Run these commands on the machine that owns the vault checkout and client
+directories. For a retrieval-only Docker service, manage the mounted checkout
+on the host and keep the container mount read-only; the server image does not
+manage host agent directories.
 
 ## Install from Git
 
@@ -129,13 +131,15 @@ 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`:
+Install a vault-checkout 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.
+The hook lives in the configured vault checkout and runs `skillmux sync` after
+a merge. Git and your deployment process, not Skillmux, keep separate
+checkouts replicated and fresh.
 
 ## Inspect active state
 
@@ -145,7 +149,8 @@ Find which vault root serves a skill:
 skillmux skill which code-context
 ```
 
-If a local overlay shadows the canonical copy, the output lists both paths.
+If a local overlay shadows the configured checkout's copy, the output lists
+both paths.
 
 Inspect configuration and readiness: