@klhapp/skillmux 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0](https://github.com/klhq/skillmux/compare/v0.4.5...v0.5.0) (2026-07-24)
+
+
+### Added
+
+* **init:** add named client registry ([e14dc26](https://github.com/klhq/skillmux/commit/e14dc261c51f7235cd7ee2223f49a0ec87668922))
+* **init:** add safe client-aware setup planner ([4a199b7](https://github.com/klhq/skillmux/commit/4a199b76c52819601a5935a7e6ac478aeddce5ca))
+* **init:** add shared setup bootstrap planner ([83ef8de](https://github.com/klhq/skillmux/commit/83ef8de67a1ff8a13de992e26ad5eedb4487509c))
+* **init:** add transactional setup planning ([6fc6f5e](https://github.com/klhq/skillmux/commit/6fc6f5e8d991a6b411c78016f5d0659486daf4d0))
+* **init:** classify and preflight skill surfaces ([b760e93](https://github.com/klhq/skillmux/commit/b760e939a66b49372642109daff6e753d9b99b8b))
+* **init:** harden target setup and host scoping ([8941f59](https://github.com/klhq/skillmux/commit/8941f598b52f73fe204c0705efb2b857b2f3c658))
+* **init:** manage client instruction blocks ([256c7a7](https://github.com/klhq/skillmux/commit/256c7a7f690e14a0e4ea5340536d762dab853bcc))
+* **init:** preflight and commit setup atomically ([9307780](https://github.com/klhq/skillmux/commit/93077809fca4949b1384213a7d8d444cd0da88eb))
+* **sync:** scope manifest targets by host ([1441dea](https://github.com/klhq/skillmux/commit/1441deac95e70df9d97b798cb514f6e7722e24eb))
+* **sync:** track ownership with versioned markers ([ad415b1](https://github.com/klhq/skillmux/commit/ad415b1a5cd8cf5351e6497c42640b624048d001))
+
+
+### Fixed
+
+* **init:** harden no-op plans and symlink checks ([137e050](https://github.com/klhq/skillmux/commit/137e05086e4f6b2d01cfdf6d5e8843f21bc1ae54))
+* **init:** preserve existing setup on reinitialization ([0c1bea9](https://github.com/klhq/skillmux/commit/0c1bea92c1d600679663c853f15bcc5a246109ff))
+
+## [0.4.5](https://github.com/klhq/skillmux/compare/v0.4.4...v0.4.5) (2026-07-24)
+
+
+### Changed
+
+* **manifest:** rename project group repos to paths ([51263f1](https://github.com/klhq/skillmux/commit/51263f175a45b6368509bb3c25ce8dcbeb07d127))
+
 ## [0.4.4](https://github.com/klhq/skillmux/compare/v0.4.3...v0.4.4) (2026-07-23)
 
 

package/README.md

@@ -186,29 +186,74 @@ bun run src/cli.ts serve
 
 Optional — skip this if `resolve_skill` alone is enough (most setups). Use it once you want a small set of skills loaded *statically* in every agent that reads from a given directory, instead of routed on demand — see [Tiers](#tiers-routed-vs-pinned).
 
-### 1. Discover surfaces and adopt one
+### 1. Check the plan
 
 ```sh
-skillmux init
+skillmux init --client claude-code --client codex --core csv-formatter --dry-run
 ```
 
-Lists candidate surfaces (default: `~/.claude/skills`, `~/.agents/skills`) with their dir/symlink status and skill count. Nothing is written until you pass `--target`:
+`--client` names the tool you use. Skillmux maps it to the correct user-level
+skill directory and merges clients that share one directory. Gemini CLI,
+OpenCode, GitHub Copilot, and Windsurf share `~/.agents/skills`. Claude Code
+uses `~/.claude/skills`; Codex uses `$CODEX_HOME/skills` or
+`~/.codex/skills`.
+
+Supported clients are `claude-code`, `codex`, `gemini-cli`, `opencode`,
+`github-copilot`, `windsurf`, `antigravity`, `goose`, `hermes`, and
+`skillmux-mcp`. Goose, Hermes, and Skillmux MCP report the manual registration
+work they need instead of inventing a target directory.
+
+The dry run prints target classification, config changes, instruction-file
+changes, readiness, and core pins. It does not prompt or write.
+
+### 2. Apply the plan
+
+```sh
+skillmux init --client claude-code --client codex --core csv-formatter --yes
+```
+
+Skillmux writes `skillmux.toml`, adds host-scoped targets, adopts each selected
+directory, and installs one managed discovery block in each client's durable
+instruction file. Existing manifest entries and instruction text stay intact.
+Without `--yes`, an interactive terminal asks about each change; a pipe or CI
+job must pass `--yes`.
+
+Use direct targets when you want paths rather than clients:
+
+```sh
+skillmux init --target agent-skills --yes
+skillmux init --target claude-code --yes
+skillmux init --target codex --yes
+skillmux init --target custom --path /srv/my-agent/skills --yes
+```
+
+The old `agents` and `claude` target names still work and print a deprecation
+warning. Skillmux keeps those names in an existing manifest.
+
+If a target points at the whole vault, Skillmux classifies it as `full-vault`
+and refuses managed-pin adoption. Review the visibility change before
+converting it:
 
 ```sh
-skillmux init --target claude --yes
+skillmux init --client claude-code --migrate-full-vault \
+  --core csv-formatter --dry-run
+skillmux init --client claude-code --migrate-full-vault \
+  --core csv-formatter --yes
 ```
 
-This writes `skillmux.toml` at the vault root and marks `~/.claude/skills` as skillmux-owned — a `.skillmux` marker file that `sync` requires before it will touch the directory.
+After conversion and `skillmux sync`, the client sees the selected core pins
+instead of every vault skill.
 
-### 2. Pick which skills are pinned
+### 3. Add or remove pins later
 
-`init` always starts `[core]` empty — there's no heuristic yet for which skills belong there. Pin with the CLI instead of hand-editing `skillmux.toml`:
+`--core` seeds only the skill IDs you name. Without it, `init` preserves
+existing core pins and makes no guesses. Add another pin with:
 
 ```sh
 skillmux manifest pin csv-formatter --core
 ```
 
-Unpin the same way: `skillmux manifest unpin csv-formatter --core`. `--project <group>` pins into a `[project.<group>]` tier instead (add `--repo <path>` the first time, to create the group). Every pin is validated before writing — the skill must actually resolve from the vault, and `[core]` stays under its 25-skill cap.
+Unpin the same way: `skillmux manifest unpin csv-formatter --core`. `--project <group>` pins into a `[project.<group>]` tier instead (add `--path <path>` the first time, to create the group). Every pin is validated before writing — the skill must actually resolve from the vault, and `[core]` stays under its 25-skill cap.
 
 Hand-editing `skillmux.toml` still works if you prefer it:
 
@@ -218,12 +263,13 @@ skills = ["csv-formatter"]
 
 [targets.claude]
 dir = "/Users/you/.claude/skills"
+host = "workhorse" # optional; sync skips this target on every other hostname
 project_groups = []
 ```
 
-Full manifest schema, including `[project.<group>]` pins scoped to one repo and machine-local overlay vaults via `local_vault_paths`, is in [`docs/configuration.md`](docs/configuration.md#tiers-and-the-manifest).
+Full manifest schema, including `[project.<group>]` pins scoped to one or more local paths and machine-local overlay vaults via `local_vault_paths`, is in [`docs/configuration.md`](docs/configuration.md#tiers-and-the-manifest).
 
-### 3. Materialize
+### 4. Materialize
 
 ```sh
 skillmux sync
@@ -240,7 +286,7 @@ skillmux sync --restore-monolith  # undo: replace a target dir with one symlink
 
 `--restore-monolith` drops the `.skillmux` marker along with the per-skill symlinks — re-adopt with `skillmux init --target <name> --yes` before that target can be `sync`'d again.
 
-### 4. See what's actually getting used
+### 5. See what's actually getting used
 
 `skillmux report` reads the same audit log `resolve_skill` writes to (see [Guarantees](#guarantees)) — useful for deciding what belongs in `[core]` versus staying routed:
 

package/docs/configuration.md

@@ -4,6 +4,25 @@ Skillmux defaults to FTS5 plus local GTE-small semantic retrieval. Most users ne
 
 For detailed CLI command reference, target resolution, policy calibration, and automation envelopes, see [`docs/cli.md`](cli.md).
 
+## Machine config bootstrap
+
+Create `~/.config/skillmux/config.toml` from a populated vault:
+
+```sh
+skillmux config init --vault ~/skills --yes
+```
+
+The command writes:
+
+```toml
+vault_path = "/home/you/skills"
+```
+
+It validates that the path resolves to a directory with at least one
+`SKILL.md`, preserves an existing config byte-for-byte, and leaves
+`local_vault_paths` unset. `skillmux init --vault ~/skills --yes` uses the
+same bootstrap when the machine config does not exist.
+
 ## Local mode
 
 ```toml
@@ -85,39 +104,61 @@ Lives at the vault root (a legacy `skr.toml` is still read if present, never wri
 skills = ["csv-formatter"]           # pinned into every [targets.*] dir; capped at 25
 
 [project.repo1]
-repos = ["/Users/you/code/repo1"]    # only synced for repos paths that exist locally
+paths = ["/Users/you/code/repo1"]    # only synced for paths that exist locally
 skills = ["pdf-extractor"]           # must not overlap [core]
 
-[targets.claude]
+[targets.claude-code]
 dir = "/Users/you/.claude/skills"
+host = "workhorse"                    # optional; init adds the current hostname
 project_groups = ["repo1"]           # which [project.*] groups materialize into this target — [] means none
 ```
 
 - `[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 `<repo>/<relative path from $HOME to the target dir>`, for each `repos` entry, and only for targets whose `project_groups` names that group. `repos` 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.
-- `[targets.<name>]` — one entry per adopted surface. `skillmux init --target <name> --yes` writes these; hand-editing is fine as long as `sync` is still allowed to own the directory (see below). `project_groups` is an explicit list, not a boolean — a target only receives the specific groups it names, never every group in the manifest.
+- `[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.
 
 **Pin/unpin without hand-editing.** `skillmux manifest pin`/`unpin` mutate `[core]`/`[project.*]` for you, validating with the same rules `sync`/`doctor` enforce (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
 
 ```sh
 skillmux manifest pin csv-formatter --core                                   # add to [core]
 skillmux manifest pin pdf-extractor --project repo1                          # add to an existing group
-skillmux manifest pin pdf-extractor --project repo2 --repo ~/code/repo2      # create a new group
+skillmux manifest pin pdf-extractor --project repo2 --path ~/code/repo2      # create a new group
 skillmux manifest unpin csv-formatter --core                                 # remove from [core]
 skillmux manifest unpin pdf-extractor --project repo1                        # remove from a group (group stays, even if empty)
 ```
 
-`--repo` is only accepted when `--project <group>` names a group that doesn't exist yet — passing it for an existing group is rejected, since changing an existing group's `repos` isn't this command's job. Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
+`--path` is only accepted when `--project <group>` names a group that doesn't exist yet — passing it for an existing group is rejected, since changing an existing group's `paths` isn't this command's job (append another entry by hand-editing `skillmux.toml` instead). Hand-editing `skillmux.toml` directly is still fully supported; these commands are a convenience layer over the same file, not a replacement for it.
 
 > **Breaking change:** `[targets.<name>].project` (a boolean) has been replaced by `project_groups` (an array of `[project.*]` names). A manifest still using the old field fails to parse with an error pointing at the new one. To migrate, replace `project = true` with `project_groups = [...]` listing every group that target previously received (previously *all* groups, unconditionally); replace `project = false` with `project_groups = []`.
+>
+> **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`/`doctor` with a distinct error, since the manifest is meant to be portable across machines and a machine-local override wouldn't exist elsewhere.
 
 ### Ownership marker
 
-Every directory `sync` manages gets a `.skillmux` marker file (`{"managed_by": "skillmux", "role": "target", "target": "<name>", "created_at": ...}`). `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). This is also why `sync --restore-monolith` (which deletes the marker and replaces the whole directory with one symlink straight to the vault) requires re-running `init` before that target can be `sync`'d again.
-
-The same `.skillmux` marker filename and JSON shape is also used for `local_vault_paths` entries (see below), distinguished by `role: "local_vault"` with a `vault_path` field instead of `target`. Markers written before this `role` field existed have no `role` key at all — they're read back as `role: "target"`, so nothing already on disk needs migrating.
+Every directory `sync` manages gets a versioned `.skillmux` marker. A target
+marker records `schema_version: 1`, `managed_by: "skillmux"`, `role:
+"target"`, its target name, `vault_path`, `created_at`, and
+`managed_entries`. The last field is the exact list of directory entries
+Skillmux created. Sync removes only those tracked entries, preserves unrelated
+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).
+`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.
+
+The same `.skillmux` filename is used for `local_vault_paths` entries (see
+below), distinguished by `role: "local_vault"` and never accepted as target
+ownership. Legacy unversioned markers are read for compatibility. An empty
+legacy target is upgraded safely on its next sync; one containing untracked
+entries is rejected with a migration diagnostic because their ownership
+cannot be inferred.
 
 ### Local vault overlays
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Local read-only MCP server routing natural-language task queries to skills in a SKILL.md vault, with zero-loss delivery",
   "type": "module",
   "private": false,