@klhapp/skillmux 0.2.1 → 0.4.3

package/src/output.ts

@@ -0,0 +1,151 @@
+import type { ResolvedTarget } from "./context";
+
+export interface JsonEnvelope<T = any> {
+  schema_version: 1;
+  ok: boolean;
+  target: string | { name: string; server: string };
+  data: T | null;
+  error: { code: string; message: string; details?: any } | null;
+}
+
+export function formatJsonEnvelope<T>(opts: {
+  ok: boolean;
+  target: ResolvedTarget | string | { name: string; server: string };
+  data?: T;
+  error?: { code: string; message: string; details?: any } | null;
+}): JsonEnvelope<T> {
+  let targetVal: string | { name: string; server: string };
+  if (typeof opts.target === "string" || (typeof opts.target === "object" && "server" in opts.target && !("type" in opts.target))) {
+    targetVal = opts.target as any;
+  } else if (typeof opts.target === "object" && "type" in opts.target) {
+    if (opts.target.type === "local") {
+      targetVal = "local";
+    } else {
+      targetVal = { name: opts.target.name, server: opts.target.server };
+    }
+  } else {
+    targetVal = "local";
+  }
+
+  return {
+    schema_version: 1,
+    ok: opts.ok,
+    target: targetVal,
+    data: opts.data ?? null,
+    error: opts.error ?? null,
+  };
+}
+
+export function mapExitCode(err: unknown): number {
+  if (!err) return 0;
+  const msg = err instanceof Error ? err.message : String(err);
+  const lower = msg.toLowerCase();
+
+  if (
+    lower.includes("conflict") ||
+    lower.includes("revision") ||
+    lower.includes("externally managed") ||
+    lower.includes("config_revision_conflict") ||
+    lower.includes("config_externally_managed")
+  ) {
+    return 4;
+  }
+
+  if (
+    lower.includes("unreachable") ||
+    lower.includes("failed to reach") ||
+    lower.includes("unauthorized") ||
+    lower.includes("unauthenticated") ||
+    lower.includes("401") ||
+    lower.includes("403") ||
+    lower.includes("connection refused")
+  ) {
+    return 3;
+  }
+
+  return 2;
+}
+
+export function levenshteinDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) {
+    if (!dp[i]) dp[i] = [];
+    dp[i]![0] = i;
+  }
+  for (let j = 0; j <= n; j++) {
+    if (!dp[0]) dp[0] = [];
+    dp[0]![j] = j;
+  }
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const prevRow = dp[i - 1]!;
+      const curRow = dp[i]!;
+      curRow[j] = Math.min(
+        prevRow[j]! + 1,
+        curRow[j - 1]! + 1,
+        prevRow[j - 1]! + cost
+      );
+    }
+  }
+  return dp[m]![n]!;
+}
+
+export function suggestCorrection(input: string, candidates: string[]): string | null {
+  let minDistance = Infinity;
+  let bestMatch: string | null = null;
+
+  for (const candidate of candidates) {
+    const dist = levenshteinDistance(input, candidate);
+    if (dist < minDistance && dist <= 2) {
+      minDistance = dist;
+      bestMatch = candidate;
+    }
+  }
+
+  return bestMatch;
+}
+
+export function isInteractive(): boolean {
+  return (
+    process.stdout.isTTY === true &&
+    !process.env.NO_COLOR &&
+    process.env.TERM !== "dumb"
+  );
+}
+
+export function renderTargetBanner(target: ResolvedTarget): void {
+  if (!isInteractive()) return;
+  if (target.type === "local") {
+    console.log(`Target: local`);
+  } else {
+    console.log(`Target: remote (${target.name} -> ${target.server})`);
+  }
+}
+
+export function renderTable(columns: { key: string; header: string }[], rows: Record<string, any>[]): void {
+  if (rows.length === 0) {
+    console.log("(no entries)");
+    return;
+  }
+
+  const widths = new Map<string, number>();
+  for (const col of columns) {
+    const maxLen = Math.max(col.header.length, ...rows.map((r) => String(r[col.key] ?? "").length));
+    widths.set(col.key, maxLen);
+  }
+
+  const headerLine = columns.map((col) => col.header.padEnd(widths.get(col.key) ?? 0)).join("  ");
+  const sepLine = columns.map((col) => "-".repeat(widths.get(col.key) ?? 0)).join("  ");
+
+  console.log(headerLine);
+  console.log(sepLine);
+  for (const row of rows) {
+    const line = columns.map((col) => String(row[col.key] ?? "").padEnd(widths.get(col.key) ?? 0)).join("  ");
+    console.log(line);
+  }
+}

package/src/router-core.ts

@@ -40,11 +40,16 @@ import {
   listSupportingFiles,
   parseSkillMd,
   readSkill,
-  scanVault,
+  scanVaults,
+  vaultResolutionOrder,
   sha256Hex,
   SKILL_ID_PATTERN,
 } from "./vault";
 
+function maxVaultMtime(vaultPath: string, localVaultPaths: string[]): number {
+  return Math.max(getVaultMaxMtime(vaultPath), ...localVaultPaths.map(getVaultMaxMtime));
+}
+
 export { buildAuditRow } from "./audit";
 export { loadConfig } from "./config";
 export { decideResolveOutcome } from "./decision";
@@ -82,8 +87,9 @@ async function getEnv(): Promise<{ config: Config; db: Database }> {
   const db = openIndex(expandHome(config.state_dir));
   if (skillCount(db) === 0) {
     const vaultPath = expandHome(config.vault_path);
-    ingestVault(db, await scanVault(vaultPath));
-    setIndexMeta(db, "last_indexed_mtime", String(getVaultMaxMtime(vaultPath)));
+    const localVaultPaths = config.local_vault_paths.map(expandHome);
+    ingestVault(db, await scanVaults(vaultPath, localVaultPaths));
+    setIndexMeta(db, "last_indexed_mtime", String(maxVaultMtime(vaultPath, localVaultPaths)));
   }
   env = { config, db };
   return env;
@@ -110,16 +116,45 @@ export function closeRuntime(): void {
  */
 async function deliverSkill(db: Database, config: Config, skillId: string): Promise<FetchSkillResult> {
   const vaultPath = expandHome(config.vault_path);
-  const file = Bun.file(join(vaultPath, skillId, "SKILL.md"));
-  if (!(await file.exists())) {
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const candidates = vaultResolutionOrder(vaultPath, localVaultPaths);
+
+  // Existence alone (resolveSkillRoot's check) isn't enough here: an unparseable
+  // local_vault_paths override would otherwise shadow a perfectly valid vault_path
+  // copy of the same skill_id, since it's checked first. Skip a broken override and
+  // fall through to the next root — mirroring scanVault/rebuildIndex's tolerance for
+  // unparseable content. The last candidate (always vault_path) is never skipped on
+  // parse failure, matching the pre-existing single-root behavior where a broken
+  // vault_path copy propagates its parse error rather than being silently swallowed.
+  let root: string | null = null;
+  let bytes: Uint8Array | null = null;
+  let raw = "";
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i]!;
+    const file = Bun.file(join(candidate, skillId, "SKILL.md"));
+    if (!(await file.exists())) continue;
+    const candidateBytes = await file.bytes();
+    const candidateRaw = decodeUtf8Strict(candidateBytes);
+    if (i < candidates.length - 1) {
+      try {
+        parseSkillMd(skillId, candidateRaw);
+      } catch {
+        continue;
+      }
+    }
+    root = candidate;
+    bytes = candidateBytes;
+    raw = candidateRaw;
+    break;
+  }
+
+  if (root === null || bytes === null) {
     // Deleted on disk but the watcher hasn't caught up: drop the stale row and
     // surface the schema's error code rather than a raw ENOENT.
     deleteSkill(db, skillId);
     throw new Error(`SKILL_NOT_FOUND: skill '${skillId}' no longer exists in the vault`);
   }
-  const bytes = await file.bytes();
   const contentSha256 = sha256Hex(bytes);
-  const raw = decodeUtf8Strict(bytes);
   let row = getSkillRow(db, skillId);
   if (row === null || row.content_sha256 !== contentSha256) {
     const fresh = parseSkillMd(skillId, raw);
@@ -131,7 +166,7 @@ async function deliverSkill(db: Database, config: Config, skillId: string): Prom
     title: row.title,
     content_sha256: contentSha256,
     body: raw,
-    files: listSupportingFiles(vaultPath, skillId),
+    files: listSupportingFiles(root, skillId),
   };
 }
 
@@ -153,15 +188,23 @@ export async function rebuildIndex(
 ): Promise<RebuildReport> {
   const { config, db } = await getEnv();
   const vaultPath = expandHome(config.vault_path);
-  const currentMtime = getVaultMaxMtime(vaultPath);
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const currentMtime = maxVaultMtime(vaultPath, localVaultPaths);
   const invalidIds: string[] = [];
-  const skills = await scanVault(vaultPath, (skillId, error) => {
+  const skills = await scanVaults(vaultPath, localVaultPaths, (skillId, error) => {
     invalidIds.push(skillId);
     onInvalid?.(skillId, error);
   });
   const rows = skills.map(toSkillRow);
+  // A skill_id invalid in one root (e.g. a local_vault_paths entry being edited) can
+  // still be valid in another (e.g. vault_path) — scanVaults already resolved that
+  // in `skills`. Only retain the previous row for ids that came back invalid
+  // everywhere; otherwise this duplicates the skill_id and violates the
+  // skills.skill_id PRIMARY KEY on replaceSkills's plain INSERT.
+  const validIds = new Set(skills.map((s) => s.skill_id));
   const retained: string[] = [];
   for (const skillId of invalidIds) {
+    if (validIds.has(skillId)) continue;
     const previous = getSkillRow(db, skillId);
     if (previous) {
       rows.push(previous);
@@ -181,17 +224,22 @@ export async function rebuildIndex(
 export async function syncVaultIfNeeded(): Promise<void> {
   const { config, db } = await getEnv();
   const vaultPath = expandHome(config.vault_path);
-  const currentMtime = getVaultMaxMtime(vaultPath);
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const currentMtime = maxVaultMtime(vaultPath, localVaultPaths);
   const lastIndexed = getIndexMeta(db, "last_indexed_mtime");
 
   if (lastIndexed === null || currentMtime > Number(lastIndexed)) {
     const invalidIds: string[] = [];
-    const skills = await scanVault(vaultPath, (skillId, error) => {
+    const skills = await scanVaults(vaultPath, localVaultPaths, (skillId, error) => {
       invalidIds.push(skillId);
       console.error(`warning: keeping previous index entry for ${skillId}: ${error}`);
     });
     const rows = skills.map(toSkillRow);
+    // See rebuildIndex: a skill_id invalid in one root can still be valid in
+    // another that scanVaults already resolved — don't re-add its previous row.
+    const validIds = new Set(skills.map((s) => s.skill_id));
     for (const skillId of invalidIds) {
+      if (validIds.has(skillId)) continue;
       const previous = getSkillRow(db, skillId);
       if (previous) {
         rows.push(previous);

package/src/server.ts

@@ -13,6 +13,15 @@ import { MetricsRegistry } from "./metrics";
 import { ReadinessState } from "./readiness";
 import { initializeRuntime } from "./lifecycle";
 import type { Clients, Config } from "./types";
+import {
+  computeHash,
+  getEffectiveConfig,
+  getLocalConfigStatus,
+  setDottedKey,
+  RELOADABLE_KEYS,
+  RESTART_REQUIRED_KEYS,
+} from "./config-service";
+import { applyCalibrationRun, getCalibrationRun, listCalibrationRuns } from "./calibrate";
 
 export const metricsRegistry = new MetricsRegistry();
 export const readinessState = new ReadinessState();
@@ -254,6 +263,116 @@ export async function startServer(opts?: {
           return new Response(JSON.stringify(getStats(db, since)), { status: 200, headers });
         }
 
+        // Admin HTTP API (/admin/v1/*)
+        if (url.pathname.startsWith("/admin/v1/")) {
+          if (!serverConfig.admin?.enabled) {
+            return new Response("Admin endpoints disabled", { status: 403 });
+          }
+
+          const adminTokenEnv = serverConfig.admin.token_env || "SKILLMUX_ADMIN_TOKEN";
+          const expectedAdminToken = process.env[adminTokenEnv] || "";
+          const authHeader = req.headers.get("authorization") || "";
+          const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+
+          if (!expectedAdminToken || !token || !safeTokenEquals(token, expectedAdminToken)) {
+            return new Response("Unauthorized", { status: 401 });
+          }
+
+          const headers = new Headers({ "Content-Type": "application/json" });
+          if (allowOriginHeader) headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+
+          if (req.method === "GET" && url.pathname === "/admin/v1/capabilities") {
+            const isExternallyManaged = process.env.SKILLMUX_CONFIG_READONLY === "true";
+            return new Response(
+              JSON.stringify({
+                config_read: true,
+                config_write: !isExternallyManaged,
+                calibration: true,
+                persistence: isExternallyManaged ? "externally_managed" : "writable",
+                reloadable_keys: RELOADABLE_KEYS,
+                restart_required_keys: RESTART_REQUIRED_KEYS,
+              }),
+              { status: 200, headers }
+            );
+          }
+
+          if (req.method === "GET" && url.pathname === "/admin/v1/config") {
+            const { effective, sources } = await getEffectiveConfig();
+            const hash = computeHash(effective);
+            const status = await getLocalConfigStatus();
+            headers.set("ETag", `"${hash}"`);
+            return new Response(
+              JSON.stringify({
+                desired: effective,
+                effective,
+                sources,
+                active_revision: hash,
+                runtime: status,
+              }),
+              { status: 200, headers }
+            );
+          }
+
+          if (req.method === "PATCH" && url.pathname === "/admin/v1/config") {
+            if (process.env.SKILLMUX_CONFIG_READONLY === "true") {
+              return new Response(
+                JSON.stringify({ error: "CONFIG_EXTERNALLY_MANAGED", message: "Configuration is externally managed" }),
+                { status: 409, headers }
+              );
+            }
+
+            const ifMatch = req.headers.get("if-match") || "";
+            const cleanIfMatch = ifMatch.replace(/^"|"$/g, "");
+            const { effective } = await getEffectiveConfig();
+            const currentHash = computeHash(effective);
+
+            if (!ifMatch || cleanIfMatch !== currentHash) {
+              return new Response(
+                JSON.stringify({ error: "CONFIG_REVISION_CONFLICT", message: "Revision conflict" }),
+                { status: 409, headers }
+              );
+            }
+
+            const body = (await req.json()) as { changes: Record<string, string | number | boolean> };
+            let lastResult: any = null;
+            for (const [k, v] of Object.entries(body.changes ?? {})) {
+              lastResult = await setDottedKey(k, String(v), { targetName: "remote" });
+            }
+
+            return new Response(JSON.stringify(lastResult ?? { ok: true }), { status: 200, headers });
+          }
+
+          if (url.pathname.startsWith("/admin/v1/calibrations")) {
+            const { db } = await getRuntime();
+            if (req.method === "GET" && url.pathname === "/admin/v1/calibrations") {
+              const runs = listCalibrationRuns(db);
+              return new Response(JSON.stringify(runs), { status: 200, headers });
+            }
+            const runIdMatch = url.pathname.match(/^\/admin\/v1\/calibrations\/([^\/]+)$/);
+            if (req.method === "GET" && runIdMatch && runIdMatch[1]) {
+              const runId = runIdMatch[1];
+              const run = getCalibrationRun(db, runId);
+              if (!run) return new Response(JSON.stringify({ error: "Calibration run not found" }), { status: 404, headers });
+              return new Response(JSON.stringify(run), { status: 200, headers });
+            }
+            if (req.method === "POST" && url.pathname === "/admin/v1/calibrations") {
+              const runId = "run_" + Math.random().toString(36).slice(2, 10);
+              return new Response(JSON.stringify({ run_id: runId, status: "running" }), { status: 202, headers });
+            }
+            const applyMatch = url.pathname.match(/^\/admin\/v1\/calibrations\/([^\/]+)\/apply$/);
+            if (req.method === "POST" && applyMatch && applyMatch[1]) {
+              const runId = applyMatch[1];
+              const run = getCalibrationRun(db, runId);
+              if (!run) return new Response(JSON.stringify({ error: "Calibration run not found" }), { status: 404, headers });
+              const { DEFAULT_CONFIG_PATH, expandHome } = await import("./config");
+              await applyCalibrationRun(db, runId, expandHome(DEFAULT_CONFIG_PATH), {});
+              return new Response(JSON.stringify({ ok: true, run_id: runId }), { status: 200, headers });
+            }
+          }
+
+          return new Response("Not Found", { status: 404, headers });
+        }
+
         // Record request metrics
         let mcpMethod = "unknown";
         try {

package/src/snapshot.ts

@@ -0,0 +1,135 @@
+import type { Database } from "bun:sqlite";
+import { expandHome } from "./config";
+import { openIndex } from "./db";
+import type { Clients, Config } from "./types";
+
+// ---------------------------------------------------------------------------
+// Immutable runtime snapshot (AC11)
+// ---------------------------------------------------------------------------
+
+/**
+ * An immutable, reference-counted view of runtime resources.
+ * All fields are frozen at construction — callers can never mutate the snapshot.
+ * The underlying db handle is closed only after every holder calls release().
+ */
+export interface RuntimeSnapshot {
+  readonly config: Config;
+  readonly clients: Clients;
+  readonly db: Database;
+}
+
+/**
+ * A handle returned by RuntimeSnapshotManager.acquire().
+ * Call release() exactly once when the request (or operation) is done.
+ */
+export interface SnapshotHandle {
+  readonly snapshot: RuntimeSnapshot;
+  release(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal reference-counted slot
+// ---------------------------------------------------------------------------
+
+class SnapshotSlot {
+  private refCount = 0;
+  private closed = false;
+  readonly snapshot: RuntimeSnapshot;
+
+  constructor(config: Config, clients: Clients) {
+    const stateDir = expandHome(config.state_dir);
+    const db = openIndex(stateDir);
+    // Freeze the snapshot object so callers cannot mutate it
+    this.snapshot = Object.freeze({ config, clients, db });
+  }
+
+  acquire(): SnapshotHandle {
+    this.refCount++;
+    let released = false;
+    return {
+      snapshot: this.snapshot,
+      release: () => {
+        if (released) return; // idempotent
+        released = true;
+        this.refCount--;
+        this.maybeClose();
+      },
+    };
+  }
+
+  /** Signal that no new acquires will come from the manager for this slot. */
+  retire(): void {
+    this.closed = true;
+    this.maybeClose();
+  }
+
+  private maybeClose(): void {
+    if (this.closed && this.refCount === 0) {
+      try {
+        this.snapshot.db.close();
+      } catch {
+        // already closed — idempotent
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public manager
+// ---------------------------------------------------------------------------
+
+/**
+ * RuntimeSnapshotManager holds one active SnapshotSlot at a time.
+ *
+ * - acquire() → returns a SnapshotHandle for the current slot; increments its refcount.
+ * - replace() → installs a new slot; retires the previous one (closed when all
+ *   in-flight holders release, i.e. no handle leak).
+ * - dispose() → retires the current slot and blocks future acquires.
+ */
+export class RuntimeSnapshotManager {
+  private current: SnapshotSlot;
+  private disposed = false;
+
+  private constructor(config: Config, clients: Clients) {
+    this.current = new SnapshotSlot(config, clients);
+  }
+
+  static create(config: Config, clients: Clients): RuntimeSnapshotManager {
+    return new RuntimeSnapshotManager(config, clients);
+  }
+
+  /**
+   * Acquire a handle to the current snapshot.
+   * The caller MUST call release() when done — even on error paths.
+   */
+  acquire(): SnapshotHandle {
+    if (this.disposed) {
+      throw new Error("RuntimeSnapshotManager has been disposed");
+    }
+    return this.current.acquire();
+  }
+
+  /**
+   * Swap in a new configuration and clients.
+   * The previous slot is retired and will close its db handle once all
+   * in-flight holders release.
+   */
+  replace(config: Config, clients: Clients): void {
+    if (this.disposed) {
+      throw new Error("RuntimeSnapshotManager has been disposed");
+    }
+    const outgoing = this.current;
+    this.current = new SnapshotSlot(config, clients);
+    outgoing.retire(); // closes when refCount reaches zero
+  }
+
+  /**
+   * Permanently shut down. Retires the current slot.
+   * Any future acquire() will throw.
+   */
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.current.retire();
+  }
+}

package/src/sync.ts

@@ -1,24 +1,31 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
+import { resolveSkillRoot } from "./vault";
 
 export const SKILLMUX_MARKER_FILENAME = ".skillmux";
 export const LEGACY_MARKER_FILENAME = ".skr";
 
 export interface SkillmuxMarker {
   managed_by: "skillmux" | "skr";
-  target: string;
+  role: "target" | "local_vault";
+  target?: string;
+  vault_path?: string;
   created_at: string;
 }
 
+function normalizeMarker(raw: Omit<SkillmuxMarker, "role"> & { role?: SkillmuxMarker["role"] }): SkillmuxMarker {
+  return { ...raw, role: raw.role ?? "target" };
+}
+
 export function readSkillmuxMarker(dir: string): SkillmuxMarker | null {
   const newPath = join(dir, SKILLMUX_MARKER_FILENAME);
   if (existsSync(newPath)) {
-    return JSON.parse(readFileSync(newPath, "utf-8")) as SkillmuxMarker;
+    return normalizeMarker(JSON.parse(readFileSync(newPath, "utf-8")));
   }
   const legacyPath = join(dir, LEGACY_MARKER_FILENAME);
   if (existsSync(legacyPath)) {
-    return JSON.parse(readFileSync(legacyPath, "utf-8")) as SkillmuxMarker;
+    return normalizeMarker(JSON.parse(readFileSync(legacyPath, "utf-8")));
   }
   return null;
 }
@@ -26,17 +33,29 @@ export function readSkillmuxMarker(dir: string): SkillmuxMarker | null {
 function writeSkillmuxMarker(dir: string, targetName: string): void {
   const marker: SkillmuxMarker = {
     managed_by: "skillmux",
+    role: "target",
     target: targetName,
     created_at: new Date().toISOString(),
   };
   writeFileSync(join(dir, SKILLMUX_MARKER_FILENAME), JSON.stringify(marker, null, 2));
 }
 
+export function writeLocalVaultMarker(dir: string, vaultPath: string): void {
+  const marker: SkillmuxMarker = {
+    managed_by: "skillmux",
+    role: "local_vault",
+    vault_path: vaultPath,
+    created_at: new Date().toISOString(),
+  };
+  writeFileSync(join(dir, SKILLMUX_MARKER_FILENAME), JSON.stringify(marker, null, 2));
+}
+
 export interface SyncTargetParams {
   vaultPath: string;
   targetDir: string;
   targetName: string;
   coreSkillIds: string[];
+  localVaultPaths?: string[];
 }
 
 export interface SyncTargetResult {
@@ -49,14 +68,15 @@ export interface SyncTargetOptions {
 }
 
 export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions = {}): SyncTargetResult {
-  const { vaultPath, targetDir, targetName, coreSkillIds } = params;
+  const { vaultPath, targetDir, targetName, coreSkillIds, localVaultPaths = [] } = params;
   const { dryRun = false } = options;
+  const skillSource = (skillId: string) => resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
 
   if (!existsSync(targetDir)) {
     if (dryRun) return { added: [...coreSkillIds], removed: [] };
     mkdirSync(targetDir, { recursive: true });
     for (const skillId of coreSkillIds) {
-      symlinkSync(join(vaultPath, skillId), join(targetDir, skillId));
+      symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
     }
     writeSkillmuxMarker(targetDir, targetName);
     return { added: [...coreSkillIds], removed: [] };
@@ -74,7 +94,7 @@ export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions
   if (dryRun) return { added, removed };
 
   for (const name of removed) unlinkSync(join(targetDir, name));
-  for (const skillId of added) symlinkSync(join(vaultPath, skillId), join(targetDir, skillId));
+  for (const skillId of added) symlinkSync(join(skillSource(skillId), skillId), join(targetDir, skillId));
 
   return { added, removed };
 }
@@ -129,6 +149,7 @@ export interface SyncProjectTargetsParams {
   targetDir: string;
   targetName: string;
   projectGroups: Record<string, ProjectGroupInput>;
+  localVaultPaths?: string[];
 }
 
 export interface ProjectPinSyncResult extends SyncTargetResult {
@@ -141,7 +162,7 @@ export function syncProjectTargets(
   params: SyncProjectTargetsParams,
   options: SyncTargetOptions = {},
 ): ProjectPinSyncResult[] {
-  const { vaultPath, targetDir, targetName, projectGroups } = params;
+  const { vaultPath, targetDir, targetName, projectGroups, localVaultPaths = [] } = params;
   const results: ProjectPinSyncResult[] = [];
 
   for (const [group, projectGroup] of Object.entries(projectGroups)) {
@@ -149,7 +170,7 @@ export function syncProjectTargets(
       if (!existsSync(repo)) continue;
       const pinDir = resolveProjectPinDir(targetDir, repo);
       const result = syncTarget(
-        { vaultPath, targetDir: pinDir, targetName, coreSkillIds: projectGroup.skills },
+        { vaultPath, targetDir: pinDir, targetName, coreSkillIds: projectGroup.skills, localVaultPaths },
         options,
       );
       results.push({ group, repo, pinDir, ...result });