@klhapp/skillmux 1.9.3 → 1.11.0

package/docs/cli.md

@@ -4,16 +4,19 @@ 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:
+Native management belongs on the machine that owns the agent 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, synchronize, or otherwise
-manage skill directories on remote client machines.
+manage skill directories on remote agent 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
 can call remote inference endpoints.
 
+Run `skillmux --help` for the full command list, or `skillmux <command> --help`
+(`-h` also works) for one command's usage and flags.
+
 For task-oriented workflows, start with [Getting started](getting-started.md)
 or [Managing skills](skill-management.md).
 
@@ -25,13 +28,31 @@ CLI. Its `skillmux --help` surface is intentionally limited to `serve`,
 `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, and bare `eval` (vault ranking
-evaluation, which needs local embeddings and the vault) on the host.
+evaluation, which needs an embeddings client and the vault) 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.
 
+## Local-only commands and remote context rejection
+
+Commands that operate directly on the local vault checkout reject `--context` and
+`--server` (or a configured remote default context) with exit code 2. These 14
+commands are local-only: `install`, `update`, `outdated`, `sync`, `core`,
+`project`, `target`, `local-vault`, `index`, `models`, `scan`, `init`, `serve`,
+and `skill which`.
+
+When one of these commands receives a remote context, it exits with code 2.
+Human-mode output reports:
+
+```
+error: `<command>` operates on the local vault only; --context/--server isn't supported here
+```
+
+In `--json` mode, the CLI emits a structured error envelope with `code: "REMOTE_CONTEXT_UNSUPPORTED"`
+and includes `rejected_command`.
+
 ## Global options and target resolution
 
 Every target-aware command resolves its execution target deterministically in this order:
@@ -52,6 +73,27 @@ Every target-aware command resolves its execution target deterministically in th
 | `--allow-insecure` | Allow plaintext HTTP admin requests to non-loopback addresses |
 | `--verbose` | Output diagnostic stack traces for errors |
 
+`--context`/`--server` selects which Skillmux admin instance a command talks to
+over `/admin/v1/*` — nothing more. That's one of three independent axes in this
+system:
+
+1. Which vault checkout backs Core/Project pinning — always a local Git checkout
+   on the machine running the CLI. `install`/`update`/`sync`/`core`/`project`/
+   `target`/`local-vault`/`index`/`models`/`scan`/`init`/`outdated`/`serve`/
+   `skill which` operate on it. There is no remote version of this — Git and the
+   deployment process move content between checkouts, not Skillmux's own
+   commands.
+2. Which MCP server an agent queries for Routed retrieval — the agent's own MCP
+   client configuration (local stdio vs. remote HTTP), entirely separate from
+   `skillmux context`.
+3. Which Skillmux instance the CLI's admin commands act on — `config`, `report`,
+   `audit prune`, `eval`/`eval promote`, and `doctor`. This is the only thing
+   `--context`/`--server` actually selects.
+
+The commands above belong entirely to axis 1. `--context` has no meaning for
+them — not "risky," a category error, the same way `--context prod` wouldn't
+mean anything on `ls`.
+
 ---
 
 ## Context management (`skillmux context`)
@@ -119,59 +161,79 @@ 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,
-sync, or any other remote-client directory operation.
+server configuration; they never administer agent skill installation, pins,
+sync, or any other remote-agent directory operation.
 
 ---
 
 ## 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.
+On a machine with no config yet, it first asks for the skill vault path
+(defaulting to `~/skills`) rather than assuming it silently — the vault
+must already exist there (`skillmux scan`/`install` create it). Skillmux
+preselects agents 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:
+Select agents 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 init --agent claude-code --agent codex --core csv-formatter --dry-run
+skillmux init --agent claude-code --agent codex --core csv-formatter --yes
 ```
 
-Skillmux supports these client IDs:
+Skillmux supports these agent IDs:
 
-| Client | Skill delivery |
+| Agent | 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 |
+| `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.
+There's no agent ID for "just MCP" — pass `--show-mcp-setup` to also print
+the MCP registration snippet, independent of which (if any) agents you
+select. A tool not in this table isn't supported by `init` yet; for an
+arbitrary directory not tied to any supported agent, use `skillmux target
+add <name> --dir <dir> --yes` directly instead of `init`.
+
+`--show-mcp-setup` only prints the snippet; it never registers anything.
+For `claude-code` and `codex`, `--register-mcp` goes further and runs that
+agent's own CLI (`claude mcp add` / `codex mcp add`) to register skillmux as
+an MCP server directly, so you don't have to paste the snippet yourself. In
+guided mode, if any selected agent supports it, skillmux asks before
+registering; noninteractive runs only register when `--register-mcp` is
+passed explicitly. It is a no-op for agents with no known registration
+command (skip it and use `--show-mcp-setup` instead).
+
+The managed instruction block only teaches an agent to call `resolve_skill`/
+`fetch_skill` (MCP tools), so `init` only writes it for an agent actually
+getting MCP this run — one you passed `--register-mcp` for, or any agent at
+all when `--show-mcp-setup` is set. A purely native run (neither flag) writes
+no instruction files, by design; `--no-instructions` forces that off even
+when MCP flags are present.
 
 `--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.
+wizard and seeds it with supplied flags. `--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 \
+skillmux init --agent claude-code --migrate-full-vault \
   --core csv-formatter --dry-run
-skillmux init --client claude-code --migrate-full-vault \
+skillmux init --agent claude-code --migrate-full-vault \
   --core csv-formatter --yes
 ```
 
-Client instruction adapters append one managed discovery block and preserve
+Agent 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
+`SOUL.md` or Hermes's installed-source `AGENTS.md`. An agent without a safe
 user-level convention reports manual setup.
 
 ---
@@ -188,24 +250,35 @@ 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:
+The noninteractive form accepts repeatable agent and skill flags:
 
 ```sh
 skillmux project init ~/code/skillmux \
   --name skillmux \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --skill sdd-tdd \
   --skill code-context \
   --yes
 ```
 
-`--client` maps product names to configured, deduplicated targets. Advanced
+`--agent` 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.
 
+`--register-mcp` is the project-local counterpart to `skillmux init
+--register-mcp`, narrowed to `claude-code` — the only agent whose own CLI
+has a project MCP scope (`codex mcp add` has no scope flag at all, so codex
+stays global-only regardless). It runs `claude mcp add -s project` with this
+project directory as the working directory, which writes a committed
+`.mcp.json` shared with your team rather than the global, personal
+registration `skillmux init` makes. Same instruction-writing rule as `init`:
+a project-root `CLAUDE.md` is written only for an agent actually getting
+registered this run, never unconditionally. Guided mode asks before
+registering, when the selected agents include one that supports it.
+
 Direct project commands support later maintenance:
 
 ```sh
@@ -215,13 +288,13 @@ 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 attach skillmux --agent claude-code --agent 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
+omitted. Agent attachments map to configured physical targets and deduplicate
+agents 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.
 
@@ -229,7 +302,7 @@ maintenance commands to materialize the new state.
 
 ## Advanced targets (`skillmux target`)
 
-Most users should select products with `init --client`. Use `target` commands
+Most users should select products with `init --agent`. Use `target` commands
 for custom delivery directories and manifest inspection:
 
 ```sh
@@ -286,6 +359,11 @@ Show which root actually serves a skill_id, and every root it shadows:
 skillmux skill which csv-formatter
 ```
 
+> [!NOTE]
+> `skill which` performs local vault-checkout shadow resolution (which root
+> wins on the local filesystem) and is unrelated to semantic MCP skill routing
+> (`resolve_skill`/`fetch_skill`).
+
 ---
 
 ## Observability and evaluation (`skillmux report`, `audit`, `eval`)
@@ -311,7 +389,7 @@ skillmux audit prune --older-than 30d --json
 # Promote observed, correlated fetches into an eval case file
 skillmux eval promote --since 7d --dry-run
 skillmux eval promote --since 7d --yes
-skillmux eval promote --since 7d --target eval/observed.json --yes
+skillmux eval promote --since 7d --out eval/observed.json --yes
 ```
 
 `report` reads `--server <url>`, `--db <path>` (an explicit SQLite file,
@@ -336,7 +414,7 @@ manual pruning is for on-demand cleanup or a tighter window.
 
 `eval promote` reads correlated fetches since `--since`, deduplicates them by
 normalized query, and writes `{ query, split: "observed", relevant_skill_ids
-}` cases to `--target` (default an `eval-observed.json` file under
+}` cases to `--out` (or deprecated alias `--target`; default an `eval-observed.json` file under
 `state_dir`; never the hand-curated `eval/queries.json` unless given
 explicitly). It never rewrites a case for a query already present in the
 target file; skipped counts are reported in the summary. Because promoted
@@ -352,12 +430,12 @@ 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 |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | 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
+below applies only to `/admin/v1/*` (and `GET /stats`); neither credential grants access to the
 other surface. Named contexts use the latter to administer the deployed server,
-not any remote client skill directory.
+not any remote agent skill directory.
 
 Remote servers expose administrative control endpoints under `/admin/v1/*` when enabled in configuration:
 
@@ -374,6 +452,30 @@ Requests require `Authorization: Bearer <token>` where `<token>` matches the env
 | `/admin/v1/capabilities` | `GET` | Advertises server features (`config_read`, `config_write`, `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/audit/prune` | `POST` | Prunes audit/fetch/admin_audit rows older than cutoff; requires `confirm: true` unless `dry_run: true` |
+| `/admin/v1/eval` | `POST` | Runs vault ranking evaluation server-side and returns `EvalReport` |
+| `/admin/v1/eval/promote` | `POST` | Returns candidate promoted eval cases from the server's audit database; requires `since` |
+
+### Remote command capabilities
+
+Named CLI contexts (`--context <name>` or `--server <url>`) support the following administrative and diagnostic operations:
+
+- `skillmux config` (`show`, `get`, `set`, `validate`, `diff`, `status`): inspect and modify remote server configuration over `/admin/v1/*`.
+- `skillmux report --since <window>`: fetches usage and retrieval metrics from the remote server's `GET /stats`.
+- `skillmux audit prune [--older-than <window>] [--dry-run] [--yes]`: prunes or dry-run counts audit records on the remote server via `POST /admin/v1/audit/prune`.
+- `skillmux eval`: executes ranking evaluation against the remote server's in-process runtime via `POST /admin/v1/eval`.
+- `skillmux eval promote --since <window>`: fetches promotable candidates from the remote server's audit db via `POST /admin/v1/eval/promote`, dedups against the local fixture file, and writes locally.
+- `skillmux doctor`: inspects remote server status, readiness, deployment runtime, and capabilities without requiring local vault access.
+
+---
+
+## Color
+
+Interactive terminal output uses a small amount of color: red for error
+messages, yellow for `warning:` lines, green/red for `doctor`'s `ok`/`fail`
+checks, and bold table headers. Color is automatic — it's on only when
+stdout is a TTY and off whenever `NO_COLOR` is set or output is piped or
+redirected. `--json` output never includes color codes.
 
 ---
 
@@ -385,12 +487,21 @@ When `--json` or `SKILLMUX_JSON=true` is set, all output is emitted to `stdout`
 {
   "schema_version": 1,
   "ok": true,
+  "context": "local",
   "target": "local",
   "data": { ... },
   "error": null
 }
 ```
 
+The `context` field identifies the execution context (`"local"` or `{ "name": "<context>", "server": "<url>" }`). The `target` field carries identical content but is deprecated and slated for removal in the next major version; consumers should read `context`.
+
+`skillmux init` additionally repeats its payload as deprecated top-level
+`command`, `phase`, `dry_run`, `applied`, `plan`, and `result` keys, which
+predate this envelope. They carry exactly the same content as `data` and are
+kept only so existing automation keeps working. Read `data` instead; the
+duplicated keys will be removed in the next major version.
+
 ### Exit codes
 
 | Code | Meaning | Examples |

package/docs/concepts.md

@@ -5,7 +5,7 @@ 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 |
+| Process location | On the agent machine or as a shared HTTP service |
 | Packaging | Skillmux CLI installation or Skillmux server deployment |
 
 Retrieval capability is a fourth, independent concern: lexical, hybrid,
@@ -25,7 +25,7 @@ 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
+each agent 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.
 
@@ -45,7 +45,7 @@ Skillmux applies three policies to one vault checkout:
 
 | Tier | Scope | Delivery |
 | --- | --- | --- |
-| Core | Each configured target | Native client skill directory |
+| Core | Each configured target | Native agent skill directory |
 | Project | Selected project paths and targets | Project-local native skill directory |
 | Routed | Full indexed vault | MCP on demand |
 
@@ -55,7 +55,7 @@ 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.
+capped at 25 skills to protect agent 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 its server
@@ -66,7 +66,7 @@ checkout over HTTP.
 ```mermaid
 flowchart TD
     V[Git-backed vault source of truth]
-    V -->|client checkout| CLI[Skillmux CLI]
+    V -->|agent checkout| CLI[Skillmux CLI]
     V -->|server checkout| SRV[Skillmux server]
     CLI --> NM[Native management: filesystem links]
     CLI --> LM[Local MCP: stdio]
@@ -75,7 +75,7 @@ flowchart TD
 
 | Topology | Process location | Transport | Typical installation |
 | --- | --- | --- | --- |
-| Native management | Client machine | Filesystem links | Skillmux CLI |
+| Native management | Agent machine | Filesystem links | Skillmux CLI |
 | Local MCP | Beside one client | stdio | Skillmux CLI |
 | Shared MCP | Server or container host | Streamable HTTP | Skillmux server (full image) |
 
@@ -94,12 +94,12 @@ 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 |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | 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
+not a way to manage skill directories on remote agent machines. The server
 and its full/slim images never manage host agent directories. See
 [Deployment](deployment.md#http-surfaces).
 
@@ -109,13 +109,13 @@ 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
+## Agents and targets
 
-A **client** is a supported product name such as `claude-code` or `codex`.
+An **agent** 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
+A **target** is a physical directory managed by sync. Several agents can map
 to one target. Gemini CLI, OpenCode, GitHub Copilot, and Windsurf share
 `~/.agents/skills`, so Skillmux deduplicates that directory.
 

package/docs/configuration.md

@@ -184,7 +184,7 @@ 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 |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | Yes, when using named CLI contexts |
 
 ```toml
 [server]
@@ -216,7 +216,7 @@ Before exposing HTTP beyond localhost, set `hostname` to a reachable interface,
 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.
+install, pin, synchronize, or otherwise manage remote agent 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
@@ -299,7 +299,7 @@ project_groups = ["repo1"]           # which [project.*] groups materialize into
 - `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
 - `[project.<group>].skills`: symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
 - `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`). `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
-- `[targets.<name>]`: one entry per adopted surface. `skillmux init --target <name> --yes` writes these and scopes newly added targets to the current hostname. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
+- `[targets.<name>]`: one entry per adopted surface. `skillmux init --agent <name> --yes` writes these for each supported agent and scopes newly added targets to the current hostname; `skillmux target add <name> --dir <dir> --yes` writes one directly for a directory not tied to any supported agent. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
 
 **Pin/unpin without hand-editing.** `skillmux core pin`/`unpin` mutate `[core]` for you, and `skillmux project pin`/`unpin` mutate `[project.*]`, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
 
@@ -338,8 +338,10 @@ content, and rejects a desired skill that collides with an unmanaged entry
 before changing anything.
 
 `sync` refuses to touch a directory that exists but has no marker; run
-`skillmux init --target <name> --yes` first, which either creates the
-directory fresh or adopts an existing one in place (contents untouched).
+`skillmux init --agent <name> --yes` (or `skillmux target add <name> --dir
+<dir> --yes` for a directory not tied to any supported agent) first, which
+either creates the directory fresh or adopts an existing one in place
+(contents untouched).
 `sync --restore-monolith` likewise refuses a `local_vault` marker or any
 unmanaged target content before replacing a target directory with a symlink
 to the vault.

package/docs/deployment.md

@@ -180,7 +180,7 @@ 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 |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | 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
@@ -280,6 +280,9 @@ skillmux context add prod \
   --token-env SKILLMUX_PROD_ADMIN_TOKEN
 skillmux context use prod
 skillmux config status
+skillmux --context prod report --since 7d
+skillmux --context prod audit prune --dry-run
+skillmux --context prod doctor
 ```
 
 The context stores the token environment variable name. Export its value in
@@ -291,11 +294,12 @@ 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.
+Named contexts administer the deployed server only — configuration, stats,
+audit prune, evaluation, and remote diagnostics. They do not install, pin,
+synchronize, or otherwise manage skill directories on remote agent 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
 

package/docs/getting-started.md

@@ -6,7 +6,7 @@ an installation.
 ```mermaid
 flowchart LR
     Q{What do you need?}
-    Q -->|Managed links in client skill directories| A[Manage native skills]
+    Q -->|Managed links in agent skill directories| A[Manage native skills]
     Q -->|Local stdio MCP| B[Add local MCP retrieval]
     Q -->|Streamable HTTP MCP for several clients| C[Run a shared MCP service]
     A --> A1[Skillmux CLI]
@@ -16,7 +16,7 @@ flowchart LR
 
 | Goal | Skill delivery | Recommended installation |
 | --- | --- | --- |
-| [Manage native skills](#manage-native-skills) | Managed links in client skill directories | Skillmux CLI |
+| [Manage native skills](#manage-native-skills) | Managed links in agent 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 | Skillmux server (full image) |
 
@@ -122,7 +122,7 @@ Run `skillmux scan ~/skills` before adopting an existing collection.
 
 ## Manage native skills
 
-Run the guided setup on the machine that owns the client skill directories:
+Run the guided setup on the machine that owns the agent skill directories:
 
 ```sh
 skillmux init
@@ -131,7 +131,7 @@ skillmux init
 The planner:
 
 1. validates the vault;
-2. detects clients from filesystem evidence;
+2. detects agents from filesystem evidence;
 3. asks which skills belong in the core tier;
 4. shows the config, target, instruction, and sync plan;
 5. applies the plan after confirmation.
@@ -145,14 +145,14 @@ Use explicit flags for automation:
 
 ```sh
 skillmux init \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --core csv-formatter \
   --dry-run
 
 skillmux init \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --core csv-formatter \
   --yes
 ```
@@ -172,13 +172,13 @@ root:
 skillmux project init
 ```
 
-The noninteractive form accepts repeatable client and skill flags:
+The noninteractive form accepts repeatable agent and skill flags:
 
 ```sh
 skillmux project init ~/code/my-project \
   --name my-project \
-  --client claude-code \
-  --client codex \
+  --agent claude-code \
+  --agent codex \
   --skill code-context \
   --yes
 ```
@@ -225,6 +225,10 @@ Register it with your MCP client:
 The client launches the process and closes it with the MCP session. Continue
 with [MCP routing](mcp-routing.md) for client behavior and ranked candidate retrieval.
 
+For `claude-code` and `codex`, `skillmux init --register-mcp` runs this
+registration for you via the agent's own CLI instead of editing config by
+hand — see [Setup planner](cli.md#setup-planner-skillmux-init).
+
 ## Run a shared MCP service
 
 Use the full image when you want local embeddings without configuring an
@@ -261,12 +265,12 @@ 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 |
+| `/admin/v1/*` (and `GET /stats`) | Operators | Inspect/update config, stats, audit prune, evaluation, and remote diagnostics | 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).
+remote agent machines. See [Deployment](deployment.md#http-surfaces).
 
 Manage the mounted vault on the host. A retrieval-only container should mount
 it read-only.
@@ -277,7 +281,7 @@ Use this topology when users need native core or project pins and also one
 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
+- each machine that owns agent skill directories keeps its own checkout and
   runs the Skillmux CLI for `init`, pinning, and `sync`;
 - the shared server mounts its own checkout and serves routed retrieval over
   HTTP;

package/docs/mcp-routing.md

@@ -59,7 +59,7 @@ and network exposure before serving other machines. See
 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.
+are for administering the deployed server, not remote agent skill directories.
 See [Deployment](deployment.md#http-surfaces).
 
 ## Tool contract