@klhapp/skillmux 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.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)
+
+
+### Fixed
+
+* connect stdio transport before blocking on runtime init ([#54](https://github.com/klhq/skillmux/issues/54)) ([847af1c](https://github.com/klhq/skillmux/commit/847af1c39265937701e432b631710fc0a2aa9ea0))
+
 ## [0.4.3](https://github.com/klhq/skillmux/compare/v0.4.2...v0.4.3) (2026-07-23)
 
 

package/README.md

@@ -208,7 +208,7 @@ This writes `skillmux.toml` at the vault root and marks `~/.claude/skills` as sk
 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:
 
@@ -221,7 +221,7 @@ dir = "/Users/you/.claude/skills"
 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
 

package/docs/configuration.md

@@ -85,7 +85,7 @@ 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]
@@ -94,7 +94,8 @@ 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 `<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.
+- `[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; 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.
 
 **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:
@@ -102,14 +103,16 @@ project_groups = ["repo1"]           # which [project.*] groups materialize into
 ```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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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,

package/src/cli.ts

@@ -148,6 +148,10 @@ async function main() {
         };
         process.once("SIGTERM", shutdown);
         process.once("SIGINT", shutdown);
+        if (transport === "stdio") {
+          process.stdin.on("close", shutdown);
+          process.stdin.on("end", shutdown);
+        }
         break;
       }
       case "index":
@@ -571,14 +575,14 @@ async function runWhich(args: string[]): Promise<void> {
   for (const shadowedRoot of roots.slice(1)) console.log(`  shadows: ${shadowedRoot}`);
 }
 
-const MANIFEST_USAGE = "usage: skillmux manifest <pin|unpin> <skill_id> (--core | --project <group> [--repo <path>...])";
+const MANIFEST_USAGE = "usage: skillmux manifest <pin|unpin> <skill_id> (--core | --project <group> [--path <path>...])";
 
-function parseManifestPinArgs(args: string[]): { skillId: string; core: boolean; project?: string; repos: string[] } {
+function parseManifestPinArgs(args: string[]): { skillId: string; core: boolean; project?: string; paths: string[] } {
   const skillId = args[0];
   if (!skillId) throw new Error(MANIFEST_USAGE);
   let core = false;
   let project: string | undefined;
-  const repos: string[] = [];
+  const paths: string[] = [];
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--core") core = true;
@@ -586,19 +590,19 @@ function parseManifestPinArgs(args: string[]): { skillId: string; core: boolean;
       const value = args[++i];
       if (!value) throw new Error("--project requires a group name");
       project = value;
-    } else if (arg === "--repo") {
+    } else if (arg === "--path") {
       const value = args[++i];
-      if (!value) throw new Error("--repo requires a path");
-      repos.push(value);
+      if (!value) throw new Error("--path requires a path");
+      paths.push(value);
     } else throw new Error(`unknown manifest option: ${arg}`);
   }
   if (core === (project !== undefined)) throw new Error(MANIFEST_USAGE);
-  return { skillId, core, project, repos };
+  return { skillId, core, project, paths };
 }
 
 async function runManifest(subCommand: string, args: string[]): Promise<void> {
   if (subCommand !== "pin" && subCommand !== "unpin") throw new Error(MANIFEST_USAGE);
-  const { skillId, core, project, repos } = parseManifestPinArgs(args);
+  const { skillId, core, project, paths } = parseManifestPinArgs(args);
   const config = await loadConfig();
   const vaultPath = expandHome(config.vault_path);
   const localVaultPaths = config.local_vault_paths.map(expandHome);
@@ -612,7 +616,7 @@ async function runManifest(subCommand: string, args: string[]): Promise<void> {
   } else {
     updated =
       subCommand === "pin"
-        ? pinProject(manifest, skillId, project!, repos)
+        ? pinProject(manifest, skillId, project!, paths)
         : unpinProject(manifest, skillId, project!);
   }
   validateManifest(updated, vaultPath, localVaultPaths);

package/src/manifest.ts

@@ -19,7 +19,7 @@ const groupNameSchema = z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64);
 const skillIdSchema = z.string().regex(SKILL_ID_PATTERN);
 
 const projectGroupSchema = z.object({
-  repos: z.array(z.string().min(1)),
+  paths: z.array(z.string().min(1)),
   skills: z.array(skillIdSchema),
 }).strict();
 
@@ -54,6 +54,15 @@ export function parseManifest(toml: string): Manifest {
             `[targets.${String(issue.path[1])}] uses the removed field "project" (boolean) — replace it with "project_groups" (an array of [project.<group>] names).`,
           );
         }
+        if (
+          issue.code === "unrecognized_keys" &&
+          issue.path[0] === "project" &&
+          issue.keys.includes("repos")
+        ) {
+          throw new Error(
+            `[project.${String(issue.path[1])}] uses the removed field "repos" — replace it with "paths".`,
+          );
+        }
       }
     }
     throw error;
@@ -70,7 +79,7 @@ export function serializeManifest(manifest: Manifest): string {
 
   for (const [name, group] of Object.entries(manifest.project ?? {})) {
     sections.push(
-      `[project.${name}]\nrepos = ${tomlStringArray(group.repos)}\nskills = ${tomlStringArray(group.skills)}`,
+      `[project.${name}]\npaths = ${tomlStringArray(group.paths)}\nskills = ${tomlStringArray(group.skills)}`,
     );
   }
 
@@ -106,15 +115,15 @@ export function unpinCore(manifest: Manifest, skillId: string): Manifest {
   return { ...manifest, core: { skills: manifest.core.skills.filter((id) => id !== skillId) } };
 }
 
-export function pinProject(manifest: Manifest, skillId: string, group: string, repos?: string[]): Manifest {
+export function pinProject(manifest: Manifest, skillId: string, group: string, paths?: string[]): Manifest {
   if (!groupNameSchema.safeParse(group).success) {
     throw new Error(`invalid group name "${group}" — must match /^[a-z][a-z0-9_-]*$/ (max 64 chars)`);
   }
   const existingGroup = manifest.project?.[group];
 
   if (!existingGroup) {
-    if (!repos || repos.length === 0) {
-      throw new Error(`group "${group}" does not exist — pass --repo <path> at least once to create it`);
+    if (!paths || paths.length === 0) {
+      throw new Error(`group "${group}" does not exist — pass --path <path> at least once to create it`);
     }
     const existing = findExistingPin(manifest, skillId);
     if (existing) {
@@ -122,12 +131,12 @@ export function pinProject(manifest: Manifest, skillId: string, group: string, r
     }
     return {
       ...manifest,
-      project: { ...manifest.project, [group]: { repos, skills: [skillId] } },
+      project: { ...manifest.project, [group]: { paths, skills: [skillId] } },
     };
   }
 
-  if (repos && repos.length > 0) {
-    throw new Error(`group "${group}" already exists — --repo is only used when creating a new group`);
+  if (paths && paths.length > 0) {
+    throw new Error(`group "${group}" already exists — --path is only used when creating a new group`);
   }
   const existing = findExistingPin(manifest, skillId);
   if (existing) {
@@ -208,9 +217,9 @@ export function validateManifest(
         throw new Error(`skill "${skillId}" appears in both [core] and [project.${groupName}]`);
       }
     }
-    for (const repo of group.repos) {
-      if (!existsSync(expandHome(repo))) {
-        notes.push(`[project.${groupName}] repos path not found locally, skipped: ${repo}`);
+    for (const path of group.paths) {
+      if (!existsSync(expandHome(path))) {
+        notes.push(`[project.${groupName}] paths entry not found locally, skipped: ${path}`);
       }
     }
   }

package/src/server.ts

@@ -60,9 +60,10 @@ export async function startServer(opts?: {
 }): Promise<ServerHandle> {
   const config = opts?.config ?? await loadConfig();
   configure({ config, clients: opts?.clients ?? createClients(config) });
-  await initializeRuntime(readinessState);
-  metricsRegistry.setReadiness(readinessState.get());
   const stopWatcher = await startVaultWatcher();
+  const initPromise = initializeRuntime(readinessState)
+    .then(() => metricsRegistry.setReadiness(readinessState.get()))
+    .catch((err) => console.error("skillmux runtime init error:", err));
 
   const server = new McpServer({ name: "skillmux", version: "0.1.0" });
 
@@ -403,6 +404,7 @@ export async function startServer(opts?: {
       },
     });
     let stopped = false;
+    await initPromise;
     console.log(`skillmux serving over HTTP on ${hostname}:${bunServer.port}`);
     return {
       port: bunServer.port,

package/src/sync.ts

@@ -129,18 +129,18 @@ export function restoreMonolith(targetDir: string, vaultPath: string): RestoreMo
   return { restored: true };
 }
 
-export function resolveProjectPinDir(targetDir: string, repo: string): string {
+export function resolveProjectPinDir(targetDir: string, path: string): string {
   const rel = relative(homedir(), targetDir);
   if (rel === "" || rel.startsWith("..")) {
     throw new Error(
       `target dir "${targetDir}" must be inside $HOME to compute a project pin dir (got relative path "${rel}")`,
     );
   }
-  return join(repo, rel);
+  return join(path, rel);
 }
 
 export interface ProjectGroupInput {
-  repos: string[];
+  paths: string[];
   skills: string[];
 }
 
@@ -154,7 +154,7 @@ export interface SyncProjectTargetsParams {
 
 export interface ProjectPinSyncResult extends SyncTargetResult {
   group: string;
-  repo: string;
+  path: string;
   pinDir: string;
 }
 
@@ -166,14 +166,14 @@ export function syncProjectTargets(
   const results: ProjectPinSyncResult[] = [];
 
   for (const [group, projectGroup] of Object.entries(projectGroups)) {
-    for (const repo of projectGroup.repos) {
-      if (!existsSync(repo)) continue;
-      const pinDir = resolveProjectPinDir(targetDir, repo);
+    for (const path of projectGroup.paths) {
+      if (!existsSync(path)) continue;
+      const pinDir = resolveProjectPinDir(targetDir, path);
       const result = syncTarget(
         { vaultPath, targetDir: pinDir, targetName, coreSkillIds: projectGroup.skills, localVaultPaths },
         options,
       );
-      results.push({ group, repo, pinDir, ...result });
+      results.push({ group, path, pinDir, ...result });
     }
   }