@klhapp/skillmux 1.10.0 → 1.11.1

package/docs/cli.md

@@ -4,11 +4,11 @@ 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
@@ -161,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.
 
 ---
@@ -230,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
@@ -257,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.
 
@@ -271,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
@@ -358,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,
@@ -383,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
@@ -404,7 +435,7 @@ The HTTP server has two separate surfaces:
 The MCP bearer token applies only to `/mcp`. The administrative bearer token
 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:
 
@@ -456,12 +487,28 @@ 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; consumers should read `context`. It stays in the payload as a compatibility alias so existing automation keeps parsing, and no removal is planned.
+
+`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 stay for the same reason as `target` above, and no removal
+is planned.
+
+`skillmux scan --format json` is the one exception to the envelope. It
+predates this contract and prints a bare `{"scanned": N, "findings": [...]}`
+object instead. It is deprecated and warns on stderr, which leaves stdout
+parseable for existing consumers. Use the global `--json` for anything new,
+and read `data` for the same fields.
+
 ### 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) |
 
@@ -99,7 +99,7 @@ An HTTP server has two separate surfaces:
 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,16 +109,20 @@ 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
-to one target. Gemini CLI, OpenCode, GitHub Copilot, and Windsurf share
+A **target** is a physical directory managed by sync. Several agents can map
+to one target. OpenCode, GitHub Copilot, and Windsurf share
 `~/.agents/skills`, so Skillmux deduplicates that directory.
 
+The mapping is not total. `goose` and `hermes` use full-vault delivery and
+map to no target at all, so commands that take `--agent` as a stand-in for a
+target reject them.
+
 Custom targets let you manage another directory without adding a product
 adapter:
 

package/docs/configuration.md

@@ -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

@@ -296,7 +296,7 @@ Read [CLI reference](cli.md#administrative-http-api-adminv1) for routes and
 
 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 client machines.
+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.

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) |
 
@@ -102,6 +102,10 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
+`install` scans the skill, shows what it found, and asks before writing to
+the vault. Add `--yes` to approve up front, which a non-interactive run
+requires. See [Managing skills](skill-management.md#install-from-git).
+
 Or create a small skill:
 
 ```sh
@@ -122,7 +126,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 +135,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 +149,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 +176,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 +229,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
@@ -266,7 +274,7 @@ The server keeps its two HTTP surfaces separate:
 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 +285,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

package/docs/skill-management.md

@@ -1,11 +1,11 @@
 # Managing skills
 
 Skillmux keeps skill content in a vault checkout and materializes selected
-skills into client directories. The vault source of truth is the logical
+skills into agent 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 checkout and client
+Run these commands on the machine that owns the vault checkout and agent
 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.
@@ -27,20 +27,32 @@ Skillmux clones into a temporary directory, validates the selected skill,
 scans its text files, and copies it to `vault_path`. Existing skill IDs require
 `--force`.
 
-Preview the destination without copying:
+Nothing is written to the vault until you approve it. The scan result prints
+first, then `install` asks for confirmation, so you decide with the findings
+already on screen. Pass `--yes` to approve up front. A non-interactive run
+(no TTY, or `--json`) fails instead of installing unattended, the same way
+`skillmux update` behaves, so scripts and CI must opt in explicitly:
 
 ```sh
-skillmux install owner/repo --dry-run
+skillmux install owner/repo --yes
 ```
 
-Set a scan gate when you want findings to block installation:
+Preview the destination without copying. `--dry-run` writes nothing, so it
+never asks for confirmation:
 
 ```sh
-skillmux install owner/repo --fail-on high
+skillmux install owner/repo --dry-run
 ```
 
 The scanner detects suspicious prompt-injection patterns, secrets, and risky
-instructions. Findings remain advisory unless you pass `--fail-on`.
+instructions. A high-severity finding aborts the install by default. Use
+`--fail-on` to move that threshold, where a lower one is stricter, and
+`--fail-on none` to install despite any finding:
+
+```sh
+skillmux install owner/repo --fail-on low     # also abort on low and medium
+skillmux install owner/repo --fail-on none    # never abort on findings
+```
 
 `install` refuses a `file://` source by default — a `file://` URL reaches the
 local filesystem directly, so honoring one unconditionally would let anything
@@ -74,13 +86,21 @@ Leaving `allowed_hosts` unset (the default) leaves both commands unrestricted.
 ```sh
 skillmux scan
 skillmux scan ~/skills/candidate
-skillmux scan --format json
+skillmux scan --json
 skillmux scan --fail-on medium
 ```
 
 With no path, `scan` checks the configured vault. `--json` wraps the result in
-the standard CLI automation envelope, while `--format json` selects the
-scanner's raw JSON rendering.
+the standard CLI automation envelope.
+
+Unlike `install` and `update`, `scan` has no default threshold: it reports
+what it finds and exits 0 regardless, so adding it to a pipeline never
+changes that pipeline's exit code by itself. Pass `--fail-on` when you want
+it to gate. The value names the lowest severity that still fails, so a lower
+value is stricter.
+
+`--format text|json` is deprecated. It still works, but it prints JSON
+outside the standard envelope and now warns on stderr. Use `--json` instead.
 
 ## Check and pull upstream updates
 
@@ -114,28 +134,28 @@ skill whose on-disk content has drifted from what was last installed —
 someone may have hand-edited it. Pass `--force` to overwrite anyway. Like
 `audit prune`, a non-interactive or `--json` run needs `--yes`.
 
-## Plan client delivery
+## Plan agent delivery
 
-Use product names for common clients:
+Use product names for common agents:
 
 ```sh
-skillmux init --client claude-code --client codex --dry-run
+skillmux init --agent claude-code --agent codex --dry-run
 ```
 
-Use a direct target when you need a known path:
+For a directory that isn't tied to any supported agent, use `target add`
+directly instead of `init`:
 
 ```sh
-skillmux init --target agent-skills --yes
-skillmux init --target custom --dir /srv/my-agent/skills --yes
+skillmux target add my-agent --dir /srv/my-agent/skills --yes
 ```
 
 Skillmux refuses to adopt a target that points to the whole vault because sync
 would reduce its visible skills. Review that migration first:
 
 ```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
 ```
 
@@ -170,7 +190,7 @@ skillmux project list
 skillmux project show my-project
 skillmux project add-path my-project ~/code/my-project --yes
 skillmux project pin my-project code-context --yes
-skillmux project attach my-project --client claude-code --client codex --yes
+skillmux project attach my-project --agent claude-code --agent codex --yes
 skillmux project unpin my-project code-context --yes
 skillmux project detach my-project --target codex --yes
 skillmux project remove-path my-project ~/code/my-project --yes

package/docs/troubleshooting.md

@@ -113,8 +113,8 @@ also reveals local-overlay shadowing.
 Skillmux will not change an existing unmarked directory. Adopt it first:
 
 ```sh
-skillmux init --client claude-code --dry-run
-skillmux init --client claude-code --yes
+skillmux init --agent claude-code --dry-run
+skillmux init --agent claude-code --yes
 ```
 
 ### Target points to the full vault
@@ -122,7 +122,7 @@ skillmux init --client claude-code --yes
 Review the smaller pinned set before converting:
 
 ```sh
-skillmux init --client claude-code \
+skillmux init --agent claude-code \
   --migrate-full-vault \
   --core code-context \
   --dry-run
@@ -239,7 +239,7 @@ skillmux --context prod config status
 An MCP token for `/mcp` cannot authenticate this request, and the administrative
 token cannot authenticate an MCP client. A named context administers the
 deployed server configuration only; use Skillmux CLI on the machine that owns
-client directories for `install`, pinning, or `sync`.
+agent directories for `install`, pinning, or `sync`.
 
 ### Client receives `429`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,