@skaile/workspaces 5.6.1 → 5.8.0

package/dist/{chunk-PTO2YDDG.js → chunk-H7QUDDKH.js}

@@ -1,20 +1,20 @@
-import { getStoreManifestsDir } from './chunk-MX3UQXLU.js';
-import { readManifestSourceConfig, discoverAssetsInTree } from './chunk-XOGG7VDZ.js';
-import { installAgent, installTargetOf, deployAll, removeAsset, canonicalEntryRef, createScaffold } from './chunk-2KOKBTR4.js';
+import { getStoreManifestsDir } from './chunk-4MQS7CAF.js';
+import { readManifestSourceConfig, isManifestMode, discoverAssetsInTree } from './chunk-Y7QA2OLD.js';
+import { installAgent, installTargetOf, canonicalEntryRef, deployAll, removeAsset, createScaffold } from './chunk-YSHVQGUS.js';
 import { appendHistory, getRecentHistory, clearHistory } from './chunk-KTBKW2FI.js';
 import { commitChanges } from './chunk-UQ6LFBPZ.js';
-import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-VKSXST23.js';
-import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, writeLock, buildLockFile, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch } from './chunk-TZCQ7ZWQ.js';
-import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-BF33SCLY.js';
-import { deployedBase, deployedDir, isDeployed } from './chunk-46OVMT76.js';
-import { resolveSkWorkspaceConfig, effectiveAgentInstances, resolveAgentDefinitionDir, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, coerceVersion, resolveAll, buildProvenanceIndex, ensureRepo, sourceShortName, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAsset, readLinks, storeManifestSlug } from './chunk-2W4LBLIN.js';
-import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-MFHKHXDE.js';
+import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-EF7NPDDU.js';
+import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch } from './chunk-36AFURKZ.js';
+import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-GB7WDMH2.js';
+import { deployedBase, deployedDir, isDeployed, deployedPaths } from './chunk-PMECEZK3.js';
+import { resolveSkWorkspaceConfig, effectiveAgentInstances, resolveAgentDefinitionDir, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, resolveAll, buildProvenanceIndex, ensureRepo, sourceShortName, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, coerceVersion, resolveAsset, readLinks, MAX_PRESET_DEPTH, PresetDepthError, storeManifestSlug } from './chunk-JAKOMFC6.js';
+import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-L5VSIPQD.js';
 import { DRIVER_TARGETS } from './chunk-CPSIPIX7.js';
-import { scanDirectory, parseRequires } from './chunk-PA7WLID3.js';
-import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName } from './chunk-AO7VJ6G6.js';
+import { scanDirectory, parseRequires } from './chunk-GTILM2CI.js';
+import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr } from './chunk-QVNRCDTV.js';
 import { spawnSync } from 'child_process';
 import { existsSync, rmSync, readdirSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import path, { join, resolve, dirname, sep, posix } from 'path';
+import path, { join, resolve, dirname, sep, relative, posix } from 'path';
 import { gt } from 'semver';
 import { stringify, parse } from 'yaml';
 import fs from 'fs/promises';
@@ -336,6 +336,25 @@ function indexLockByKindName(lock) {
   }
   return lockByKindName;
 }
+function commitsBetween(repoDir, from, to, cache) {
+  const key = `${from}..${to}`;
+  const hit = cache.get(key);
+  if (hit !== void 0) return hit;
+  let count = 1;
+  if (COMMIT_ID.test(from) && COMMIT_ID.test(to)) {
+    const r = spawnSync("git", ["-C", repoDir, "rev-list", "--count", key], {
+      encoding: "utf8",
+      stdio: "pipe"
+    });
+    if (r.status === 0) {
+      const n = Number.parseInt(r.stdout.trim(), 10);
+      if (Number.isFinite(n) && n >= 0) count = n;
+    }
+  }
+  cache.set(key, count);
+  return count;
+}
+var COMMIT_ID = /^[0-9a-f]{7,64}$/;
 function libraryDiskHashes(libPath, cache, registry) {
   let hashes = cache.get(libPath);
   if (!hashes) {
@@ -356,6 +375,26 @@ function libraryDiskHashes(libPath, cache, registry) {
   }
   return hashes;
 }
+function withLibraryFiles(entry, libPath, cache, registry) {
+  let byManifest = cache.get(libPath);
+  if (!byManifest) {
+    byManifest = /* @__PURE__ */ new Map();
+    const sourceConfig = readManifestSourceConfig(libPath, "library");
+    if (sourceConfig && isManifestMode(sourceConfig)) {
+      for (const a of discoverAssetsInTree(libPath, { sourceConfig, registry }).assets) {
+        const { assetRoot, files: files2 } = a.fileFilter;
+        byManifest.set(
+          resolve(a.manifestPath),
+          filesUnderManifestDir(files2, relative(assetRoot, a.manifestPath).split(sep).join("/"))
+        );
+      }
+    }
+    cache.set(libPath, byManifest);
+  }
+  const files = byManifest.get(resolve(entry.source));
+  if (files) entry.files = files;
+  return entry;
+}
 function newestLibraryDef(snap, libraryName, id) {
   const lib = snap?.libraries.find((l) => l.name === libraryName);
   if (!snap || !lib) return void 0;
@@ -367,6 +406,50 @@ function newestLibraryDef(snap, libraryName, id) {
   }
   return best;
 }
+function libraryPreference(isDefaultLib) {
+  return (a, b) => {
+    const va = coerceVersion(a.entry.version ?? "");
+    const vb = coerceVersion(b.entry.version ?? "");
+    if (gt(va, vb)) return -1;
+    if (gt(vb, va)) return 1;
+    const da = isDefaultLib.get(a.library) ? 0 : 1;
+    const db = isDefaultLib.get(b.library) ? 0 : 1;
+    return da - db || a.library.localeCompare(b.library);
+  };
+}
+function qualifyDepRef(ref, fallback) {
+  const hash = ref.indexOf("#");
+  const head = hash === -1 ? ref : ref.slice(0, hash);
+  if (head.includes("@") || !fallback) return ref;
+  const pin = hash === -1 ? void 0 : ref.slice(hash + 1) || void 0;
+  const colon = head.indexOf(":");
+  return assetRefToStr({
+    kind: colon === -1 ? "skill" : head.slice(0, colon),
+    name: colon === -1 ? head : head.slice(colon + 1),
+    publisher: fallback,
+    pin
+  });
+}
+function libraryEntryDepRefs(e) {
+  const publisher = e.publisher ?? "";
+  const refs = /* @__PURE__ */ new Set();
+  for (const d of e.dependencies ?? []) {
+    if (d) refs.add(qualifyDepRef(d, publisher));
+  }
+  for (const r of e.requires ?? []) {
+    const p = r.publisher ?? publisher;
+    if (p) refs.add(assetRefToStr({ kind: r.kind, name: r.name, publisher: p, pin: r.pin }));
+  }
+  return [...refs];
+}
+function refIdentity(ref) {
+  try {
+    const p = parseAssetRef(ref);
+    return p.publisher ? `${p.publisher}/${p.kind}:${p.name}` : null;
+  } catch {
+    return null;
+  }
+}
 function computeSyncStatus(repoStatus) {
   if (!repoStatus) return "unknown";
   if (repoStatus.kind === "local") return "local";
@@ -437,6 +520,56 @@ function parseRefTolerant(ref) {
     return { kind, name, publisher: void 0 };
   }
 }
+function keptLockEntries(prev, missing) {
+  const out = { assets: {}, sources: [], refs: /* @__PURE__ */ new Set() };
+  if (!prev) return out;
+  for (const ref of missing) {
+    const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+    if (!want) continue;
+    for (const [key, entry] of Object.entries(prev.assets)) {
+      if (entry.library?.installed) continue;
+      const id = parseCanonicalLockKey(key);
+      if (id.kind !== want.kind || id.name !== want.name) continue;
+      if (want.publisher && id.publisher !== want.publisher) continue;
+      out.assets[key] = entry;
+      out.refs.add(ref);
+      const src = entry.source ? prev.sources.find((s) => s.url === entry.source?.url) : void 0;
+      if (src) out.sources.push(src);
+    }
+  }
+  return out;
+}
+function withKeptLockEntries(lock, kept) {
+  if (Object.keys(kept.assets).length === 0) return lock;
+  const sources = new Map(lock.sources.map((s) => [s.url, s]));
+  for (const s of kept.sources) if (!sources.has(s.url)) sources.set(s.url, s);
+  return {
+    ...lock,
+    // v4 once a library-origin entry is present (see buildLockFile).
+    schema_version: lock.schema_version === 4 || Object.values(kept.assets).some((e) => e.library) ? 4 : 3,
+    assets: { ...lock.assets, ...kept.assets },
+    sources: [...sources.values()].sort((a, b) => a.url.localeCompare(b.url))
+  };
+}
+function relockedRefs(prev, next) {
+  if (!prev) return [];
+  const fingerprint = (e) => [e.library?.version ?? "", e.library?.sha256 ?? e.sha256, e.source?.commit ?? ""].join("\0");
+  const out = [];
+  for (const [key, entry] of Object.entries(next.assets)) {
+    if (entry.library?.installed) continue;
+    const id = parseCanonicalLockKey(key);
+    const before = prev.assets[key] ? [key, prev.assets[key]] : Object.entries(prev.assets).find(([k]) => {
+      const o = parseCanonicalLockKey(k);
+      return o.kind === id.kind && o.name === id.name && o.publisher === id.publisher;
+    });
+    if (!before) continue;
+    if (before[0] !== key || fingerprint(before[1]) !== fingerprint(entry)) out.push(key);
+  }
+  return out;
+}
+function unregisteredLibraryFix(library, ref) {
+  return `register library "${library}" again with \`skaile library init ${library} --path <dir>\`, or drop the dependency with \`skaile remove ${ref}\``;
+}
 function memberIdentity(ref) {
   const parsed = parseRefTolerant(ref.trim());
   if (!parsed) return null;
@@ -517,6 +650,8 @@ var AssetManager = class {
   indexPathOverride;
   /** Sink for cross-library collision warnings; else `console.warn`. */
   onLibraryCollision;
+  /** Store URLs whose failed version lookup was already reported (one warning per URL). */
+  warnedStoreVersionLookups = /* @__PURE__ */ new Set();
   constructor(opts) {
     this.projectDir = resolve(opts.projectDir);
     this.global = opts.global ?? false;
@@ -765,13 +900,55 @@ var AssetManager = class {
    * content. The returned `libraryOf` map names the library each entry came from
    * so callers can lock it as library-origin (see {@link libraryLockEntries}).
    *
+   * @param opts.quiet - Skip the cross-library collision warning (a lookup that only
+   *   builds an error hint must not warn).
    * @returns the matched deploy entries, the set of `missing` refs covered, and
    *   each entry's originating library name.
    */
-  async resolveLibraryEntries(missing) {
+  async resolveLibraryEntries(missing, opts = {}) {
     const resolved = /* @__PURE__ */ new Set();
     const libraryOf = /* @__PURE__ */ new Map();
     if (missing.length === 0) return { entries: [], resolved, libraryOf };
+    const scan = await this.scanLibraries();
+    if (!scan) return { entries: [], resolved, libraryOf };
+    const { byKey, isDefaultLib, libraryDir } = scan;
+    const entries = [];
+    const fileSets = /* @__PURE__ */ new Map();
+    const allCandidates = [...byKey.values()].flat();
+    for (const ref of missing) {
+      const parsed = parseRefTolerant(ref);
+      if (!parsed) continue;
+      const hash = ref.indexOf("#");
+      const pin = parsed.pin ?? (hash >= 0 ? ref.slice(hash + 1) : void 0);
+      const key = parsed.publisher ? `${parsed.kind}:@${parsed.publisher}/${parsed.name}` : void 0;
+      const pool = key ? byKey.get(key) ?? [] : allCandidates.filter((c) => c.entry.kind === parsed.kind && c.entry.name === parsed.name);
+      const candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
+      if (candidates.length === 0) continue;
+      candidates.sort(libraryPreference(isDefaultLib));
+      const hit = candidates[0];
+      if (!opts.quiet) {
+        this.warnLibraryCollision(
+          `${hit.entry.kind}:@${hit.entry.publisher}/${hit.entry.name}`,
+          candidates,
+          hit
+        );
+      }
+      withLibraryFiles(hit.entry, libraryDir.get(hit.library), fileSets, this.registry);
+      entries.push(hit.entry);
+      libraryOf.set(hit.entry, hit.library);
+      resolved.add(ref);
+    }
+    return { entries, resolved, libraryOf };
+  }
+  /**
+   * Scan every candidate library (the set {@link resolveLibraryEntries} resolves from)
+   * into `kind:@publisher/name` → every holder, across all libraries and versions.
+   *
+   * @param minRoots - Return `null` without scanning when fewer candidate libraries
+   *   exist (a cross-library question needs at least two).
+   * @returns `null` when there is no candidate library or none holds an asset.
+   */
+  async scanLibraries(minRoots = 1) {
     const roots = [];
     for (const l of (await this.loadLibraryIndex())?.libraries ?? []) {
       if (l.name === GLOBAL_INSTALL_DIR_NAME) continue;
@@ -793,8 +970,9 @@ var AssetManager = class {
       }
     } catch {
     }
-    if (roots.length === 0) return { entries: [], resolved, libraryOf };
+    if (roots.length === 0 || roots.length < minRoots) return null;
     const byKey = /* @__PURE__ */ new Map();
+    const libraryDir = new Map(roots.map((r) => [r.name, r.dir]));
     const isDefaultLib = new Map(roots.map((r) => [r.name, r.isDefault]));
     for (const { name, dir } of roots) {
       const publisher = readDeclaredPublisher(dir) ?? slugifyAssetName(name);
@@ -805,37 +983,142 @@ var AssetManager = class {
         else byKey.set(key, [{ entry, library: name }]);
       }
     }
-    if (byKey.size === 0) return { entries: [], resolved, libraryOf };
-    const entries = [];
-    for (const ref of missing) {
-      let parsed;
-      try {
-        parsed = parseAssetRef(ref);
-      } catch {
-        continue;
-      }
-      if (!parsed.publisher) continue;
-      const key = `${parsed.kind}:@${parsed.publisher}/${parsed.name}`;
-      const candidates = (byKey.get(key) ?? []).filter(
-        (c) => !parsed.pin || matchPin(parsed.pin, c.entry.version ?? "")
+    return byKey.size === 0 ? null : { byKey, isDefaultLib, libraryDir };
+  }
+  /**
+   * Every ref that more than one registered library holds, with one row per holder
+   * (all libraries, all versions) in the order `add` prefers them: the first row is
+   * the one `add <ref>` deploys. The local index keeps a single row per ref and
+   * version, so `search` reads this to show equal-version copies in both libraries.
+   *
+   * @returns `kind:@publisher/name` → holders; refs held by one library are absent.
+   */
+  async libraryHolders() {
+    const out = /* @__PURE__ */ new Map();
+    const scan = await this.scanLibraries(2);
+    if (!scan) return out;
+    for (const [key, candidates] of scan.byKey) {
+      if (new Set(candidates.map((c) => c.library)).size < 2) continue;
+      const sorted = [...candidates].sort(libraryPreference(scan.isDefaultLib));
+      out.set(
+        key,
+        sorted.map((c, i) => ({
+          library: c.library,
+          version: c.entry.version ?? "",
+          description: c.entry.description ?? "",
+          picked: i === 0
+        }))
       );
-      if (candidates.length === 0) continue;
-      candidates.sort((a, b) => {
-        const va = coerceVersion(a.entry.version ?? "");
-        const vb = coerceVersion(b.entry.version ?? "");
-        if (gt(va, vb)) return -1;
-        if (gt(vb, va)) return 1;
-        const da = isDefaultLib.get(a.library) ? 0 : 1;
-        const db = isDefaultLib.get(b.library) ? 0 : 1;
-        return da - db || a.library.localeCompare(b.library);
-      });
-      const hit = candidates[0];
-      this.warnLibraryCollision(key, candidates, hit);
-      entries.push(hit.entry);
-      libraryOf.set(hit.entry, hit.library);
-      resolved.add(ref);
     }
-    return { entries, resolved, libraryOf };
+    return out;
+  }
+  /**
+   * Where each missed publisher-qualified ref went when its publisher changed, for every
+   * ref at once (one library scan, one lock read):
+   * - `moved` when a registered library holds the same kind + name under another publisher;
+   * - `lockedAs` when the lock holds the same kind + name under another publisher, records
+   *   the library it came from, and that library now holds the asset under yet another
+   *   publisher than the locked one. An unrelated asset that merely shares kind + name does
+   *   not qualify.
+   *
+   * @param refs - Missed refs; a trailing `(reason)` after the first space is ignored.
+   * @returns one finding per ref that has one. Never warns.
+   */
+  async publisherChangeFindings(refs) {
+    const out = /* @__PURE__ */ new Map();
+    const wanted = /* @__PURE__ */ new Map();
+    for (const ref of refs) {
+      const parsed = parseRefTolerant(ref.split(" ")[0] ?? ref);
+      if (parsed?.publisher) {
+        wanted.set(ref, { kind: parsed.kind, name: parsed.name, publisher: parsed.publisher });
+      }
+    }
+    if (wanted.size === 0) return out;
+    const lockEntries = Object.entries(this.tryReadLock()?.assets ?? {});
+    const bare = [...new Set([...wanted.values()].map((w) => `${w.kind}:${w.name}`))];
+    const lib = await this.resolveLibraryEntries(bare, { quiet: true });
+    for (const [ref, w] of wanted) {
+      const moved = lib.entries.find((e) => e.kind === w.kind && e.name === w.name);
+      const movedLibrary = moved ? lib.libraryOf.get(moved) : void 0;
+      const finding = {};
+      for (const [key, entry] of lockEntries) {
+        const id = parseCanonicalLockKey(key);
+        if (id.kind === w.kind && id.name === w.name && id.publisher && id.publisher !== w.publisher && entry.library && moved && movedLibrary === entry.library.name && moved.publisher !== id.publisher) {
+          finding.lockedAs = `${id.kind}:@${id.publisher}/${id.name}`;
+          break;
+        }
+      }
+      if (moved && moved.publisher !== w.publisher) {
+        finding.moved = {
+          ref: `${moved.kind}:@${moved.publisher}/${moved.name}`,
+          ...movedLibrary ? { library: movedLibrary } : {}
+        };
+      }
+      if (finding.lockedAs || finding.moved) out.set(ref, finding);
+    }
+    return out;
+  }
+  /**
+   * Explain misses caused by a publisher change, as parenthesized hint text per ref:
+   * `did you mean <ref>?` when a registered library holds the same kind + name under
+   * another publisher, and `locked as <lockRef>; run skaile install to re-resolve` when
+   * the lock holds it under the library's previous publisher (see
+   * {@link AssetManager.publisherChangeFindings}).
+   *
+   * @param refs - Missed refs; a trailing `(reason)` after the first space is ignored.
+   * @returns hint text per ref, only for refs that have one. Never warns.
+   */
+  async publisherChangeHints(refs) {
+    const out = {};
+    for (const [ref, f] of await this.publisherChangeFindings(refs)) {
+      const hints = [];
+      if (f.lockedAs) hints.push(`locked as ${f.lockedAs}; run skaile install to re-resolve`);
+      if (f.moved) hints.push(`did you mean ${f.moved.ref}?`);
+      out[ref] = hints.map((h) => ` (${h})`).join("");
+    }
+    return out;
+  }
+  /**
+   * What the user has to change for each ref that is locked from a library but resolves
+   * nowhere any more, where `skaile install` cannot help: the library is not registered
+   * (renamed away or removed), the library now publishes the asset under another
+   * publisher, or the library no longer holds it. A ref the lock does not tie to a
+   * library has no entry.
+   *
+   * @param refs - Declared or locked refs, `kind:@publisher/name` (a trailing `(reason)`
+   *   after the first space is ignored).
+   * @returns a phrase per ref that follows the ref name, without parentheses.
+   */
+  async unresolvedFixes(refs) {
+    const out = /* @__PURE__ */ new Map();
+    if (refs.length === 0) return out;
+    const lockEntries = Object.entries(this.tryReadLock()?.assets ?? {});
+    const snap = await this.loadLibraryIndex();
+    const findings = await this.publisherChangeFindings(refs);
+    for (const ref of refs) {
+      const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+      if (!want) continue;
+      const origin = lockEntries.map(([key, e]) => ({ id: parseCanonicalLockKey(key), library: e.library })).find(
+        ({ id, library }) => library && !library.installed && id.kind === want.kind && id.name === want.name && (!want.publisher || id.publisher === want.publisher)
+      )?.library;
+      if (!origin) continue;
+      const plain = want.publisher ? `${want.kind}:@${want.publisher}/${want.name}` : `${want.kind}:${want.name}`;
+      const moved = findings.get(ref)?.moved;
+      if (moved?.library && want.publisher) {
+        out.set(
+          ref,
+          `did you mean ${moved.ref}? Change the ref in skaile.yaml to it, or keep the old ref with \`skaile library set ${moved.library} publisher=${want.publisher}\``
+        );
+      } else if (!this.libraryPath(origin.name, snap)) {
+        out.set(ref, unregisteredLibraryFix(origin.name, plain));
+      } else {
+        out.set(
+          ref,
+          `library "${origin.name}" no longer holds it \u2014 restore it there, or drop the dependency with \`skaile remove ${plain}\``
+        );
+      }
+    }
+    return out;
   }
   /** Collision messages already printed by this instance (one warning per ref + library set). */
   warnedLibraryCollisions = /* @__PURE__ */ new Set();
@@ -853,6 +1136,56 @@ var AssetManager = class {
     if (this.onLibraryCollision) this.onLibraryCollision(msg);
     else console.warn(`skaile: ${msg}`);
   }
+  /** Kind, name and bare publisher of a deploy entry; the publisher comes from its canonical ref. */
+  entryIdentity(entry) {
+    const ref = parseAssetRefLoose(canonicalEntryRef(entry));
+    return {
+      kind: entry.kind,
+      name: entry.name,
+      publisher: ref?.publisher ?? entry.publisher?.replace(/^@/, "")
+    };
+  }
+  /**
+   * Refuse assets of one kind and name from different publishers: they deploy into the
+   * same folder, so the later one would silently overwrite the earlier. Throws one line
+   * naming the folder and the asset that holds it.
+   *
+   * @param incoming - Assets about to be deployed. Two of them clashing is refused.
+   * @param held - Assets the project already declares or has locked; one of them
+   *   clashing with an incoming asset is refused when its folder is on disk.
+   */
+  assertNoFolderCollision(incoming, held = []) {
+    const refOf = (a) => assetRefToStr({ kind: a.kind, name: a.name, publisher: a.publisher });
+    const differs = (a, b) => !!a.publisher && !!b.publisher && a.publisher !== b.publisher;
+    const shown = (dir) => this.global ? dir : relative(this.projectDir, dir);
+    const seen = /* @__PURE__ */ new Map();
+    for (const a of incoming) {
+      if (!a.kind || !a.name) continue;
+      const component = installTargetOf(this.registry, a.kind);
+      if (!component) continue;
+      const slot = `${component}/${a.name}`;
+      const prior = seen.get(slot);
+      if (prior && differs(prior, a)) {
+        const dir2 = deployedDir(component, a.name, this.driverTarget, this.global, this.projectDir);
+        throw new Error(
+          `${refOf(prior)} and ${refOf(a)} both deploy to ${shown(dir2)} \u2014 keep only one of them`
+        );
+      }
+      if (!prior) seen.set(slot, a);
+      const holder = held.find(
+        (h) => !!h.kind && h.name === a.name && installTargetOf(this.registry, h.kind) === component && differs(h, a)
+      );
+      if (!holder) continue;
+      const target = this.targetHarnesses().find(
+        (t) => isDeployed(component, a.name, t, this.global, this.projectDir)
+      );
+      if (!target) continue;
+      const dir = deployedDir(component, a.name, target, this.global, this.projectDir);
+      throw new Error(
+        `${refOf(a)} would overwrite ${shown(dir)}, which ${refOf(holder)} already holds \u2014 run skaile remove ${refOf(holder)} first`
+      );
+    }
+  }
   /**
    * Open the local index and snapshot its libraries + asset definitions.
    * Best-effort: no index file (never indexed), or any open/guard failure,
@@ -875,10 +1208,12 @@ var AssetManager = class {
   }
   /**
    * Library-origin lock entries for the assets {@link resolveLibraryEntries}
-   * matched. The locked version comes from the library index when it knows the
-   * asset (its manifest-declared version is authoritative), else from the
-   * on-disk asset. The hash is computed from the files on disk, so it matches
-   * what `install --locked` re-hashes.
+   * matched. The locked version is the one actually deployed: the on-disk
+   * entry's version, falling back to the library index only when the disk entry
+   * carries none — the index lags until the next `skaile library index`, so
+   * preferring it would lock a stale version after an in-place bump. The hash is
+   * computed from the files on disk, so it matches what `install --locked`
+   * re-hashes.
    */
   async libraryLockEntries(lib) {
     if (lib.entries.length === 0) return {};
@@ -895,7 +1230,7 @@ var AssetManager = class {
           kind: e.kind,
           publisher,
           name: e.name,
-          library: { name, version: def?.version || e.version || "0.0.0", sha256 }
+          library: { name, version: e.version || def?.version || "0.0.0", sha256 }
         };
       })
     );
@@ -915,6 +1250,7 @@ var AssetManager = class {
     if (locked.length === 0) return { entries, missing };
     const snap = await this.loadLibraryIndex();
     const diskHashes = /* @__PURE__ */ new Map();
+    const fileSets = /* @__PURE__ */ new Map();
     for (const [ref, e] of locked) {
       const origin = e.library;
       const { publisher, kind, name } = parseCanonicalLockKey(ref);
@@ -925,7 +1261,7 @@ var AssetManager = class {
       const libPath = this.libraryPath(origin.name, snap);
       if (!libPath) {
         missing.push(
-          `${ref} (library "${origin.name}" is not registered \u2014 renamed or removed? re-lock with \`skaile install\`)`
+          `${ref} (library "${origin.name}" is not registered \u2014 renamed or removed? ${unregisteredLibraryFix(origin.name, `${kind}:@${publisher}/${name}`)}; \`skaile install\` re-locks it when another library holds it now)`
         );
         continue;
       }
@@ -937,7 +1273,7 @@ var AssetManager = class {
         continue;
       }
       const def = newestLibraryDef(snap, origin.name, { kind, publisher, name });
-      const current = def?.version || found.version || "0.0.0";
+      const current = found.version || def?.version || "0.0.0";
       if (current !== origin.version) {
         missing.push(
           `${ref} (library "${origin.name}" is at ${current}, locked ${origin.version})`
@@ -953,7 +1289,7 @@ var AssetManager = class {
           continue;
         }
       }
-      entries.push(found);
+      entries.push(withLibraryFiles(found, libPath, fileSets, this.registry));
     }
     return { entries, missing };
   }
@@ -992,7 +1328,8 @@ var AssetManager = class {
       stores: opts.stores,
       storeFetcher: this.storeFetcherFor(opts.stores),
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      declaredRefs: opts.declaredRefs
     });
     if (first.missing.length === 0) return first;
     const fallback = await this.globalStoreFallback(opts.stores);
@@ -1005,13 +1342,135 @@ var AssetManager = class {
         stores,
         storeFetcher: this.storeFetcherFor(stores),
         projectDir: this.projectDir,
-        knownKinds: this.knownKinds
+        knownKinds: this.knownKinds,
+        declaredRefs: opts.declaredRefs
       });
       return retry.missing.length < first.missing.length ? retry : first;
     } catch {
       return first;
     }
   }
+  /**
+   * Resolve `deps` library-first, then walk the dependencies of every library
+   * asset it picks.
+   *
+   * A publisher-qualified ref that no project source declares is looked up in the
+   * registered **libraries** before any store is asked, so a locally authored
+   * asset resolves (and deploys) with the store unreachable and without a
+   * version-discovery round trip. Only refs the libraries did not satisfy go to
+   * {@link resolveWithStores}; its misses get one more library try (a ref a source
+   * knows only under another version). A `#version` pin still selects through
+   * `matchPin` inside {@link resolveLibraryEntries}.
+   *
+   * Library assets declare `dependencies` / `requires`. Those are fed back through
+   * the same resolution with a `seen` identity set (mirrors `resolveAll`), so deps
+   * deploy, get lock entries, and a dependency cycle terminates.
+   *
+   * @returns source/store candidates, still-unresolved refs, applied overrides,
+   *   expanded presets, and the library leg (entries + originating library per entry).
+   */
+  async resolveLibraryFirst(deps, opts) {
+    const resolved = [];
+    const overridesApplied = /* @__PURE__ */ new Set();
+    const presets = [];
+    const lib = { entries: [], resolved: /* @__PURE__ */ new Set(), libraryOf: /* @__PURE__ */ new Map() };
+    const missing = /* @__PURE__ */ new Set();
+    const seen = /* @__PURE__ */ new Set();
+    const covered = /* @__PURE__ */ new Set();
+    const declaredById = /* @__PURE__ */ new Map();
+    for (const d of opts.declaredRefs ?? []) {
+      const id = refIdentity(d);
+      if (id !== null) declaredById.set(id, d);
+    }
+    const presetParent = /* @__PURE__ */ new Map();
+    const absorb = (hit) => {
+      const next = [];
+      for (const e of hit.entries) {
+        const origin = hit.libraryOf.get(e);
+        const id = `${e.publisher}/${e.kind}:${e.name}`;
+        seen.add(id);
+        covered.add(id);
+        const deps2 = libraryEntryDepRefs(e);
+        if (e.kind === "preset") {
+          const chain = [id];
+          for (let up = presetParent.get(id); up !== void 0; up = presetParent.get(up)) {
+            chain.unshift(up);
+          }
+          if (chain.length > MAX_PRESET_DEPTH) {
+            throw new PresetDepthError("depth", canonicalEntryRef(e), chain);
+          }
+          for (const dep of deps2) {
+            const depId = refIdentity(dep);
+            if (depId === null || !depId.includes("/preset:")) continue;
+            if (chain.includes(depId)) throw new PresetDepthError("cycle", dep, [...chain, depId]);
+            if (!presetParent.has(depId)) presetParent.set(depId, id);
+          }
+          presets.push({
+            ref: canonicalEntryRef(e),
+            assets: deps2.filter((d) => !d.startsWith("preset:")).length,
+            skipped: e.skippedItems ?? 0,
+            ...origin ? { library: origin } : {}
+          });
+        } else {
+          lib.entries.push(e);
+          if (origin) lib.libraryOf.set(e, origin);
+        }
+        next.push(
+          ...deps2.map((dep) => {
+            const depId = refIdentity(dep);
+            return depId !== null && declaredById.get(depId) || dep;
+          })
+        );
+      }
+      for (const r of hit.resolved) lib.resolved.add(r);
+      return next;
+    };
+    let wave = deps;
+    while (wave.length > 0) {
+      const fresh = [];
+      for (const ref of wave) {
+        const id = refIdentity(ref);
+        if (id !== null) {
+          if (seen.has(id)) continue;
+          seen.add(id);
+        }
+        fresh.push(ref);
+      }
+      if (fresh.length === 0) break;
+      const libraryTried = new Set(
+        fresh.filter((ref) => {
+          const id = refIdentity(ref);
+          return id !== null && (opts.provenanceIndex.get(id)?.length ?? 0) === 0;
+        })
+      );
+      const hit = await this.resolveLibraryEntries([...libraryTried]);
+      const next = absorb(hit);
+      const rest = fresh.filter((ref) => !hit.resolved.has(ref));
+      if (rest.length > 0) {
+        const r = await this.resolveWithStores(rest, opts);
+        for (const c of r.resolved) {
+          const id = `${c.publisher}/${c.kind}:${c.name}`;
+          if (covered.has(id)) continue;
+          seen.add(id);
+          covered.add(id);
+          resolved.push(c);
+        }
+        for (const o of r.overridesApplied) overridesApplied.add(o);
+        presets.push(...r.presets);
+        const hit2 = await this.resolveLibraryEntries(
+          r.missing.filter((m) => !libraryTried.has(m))
+        );
+        next.push(...absorb(hit2));
+        for (const m of r.missing) if (!hit2.resolved.has(m)) missing.add(m);
+      }
+      wave = next;
+    }
+    const stillMissing = [...missing].filter((m) => {
+      const id = refIdentity(m);
+      return !lib.resolved.has(m) && !(id !== null && covered.has(id));
+    });
+    return { resolved, missing: stillMissing, overridesApplied, lib, presets };
+  }
   /** The catalog fetcher to use: an injected one, else built from `stores`. */
   storeFetcherFor(stores) {
     return this.injectedStoreFetcher ?? this.buildStoreFetcher(stores);
@@ -1177,7 +1636,7 @@ var AssetManager = class {
   async install(opts) {
     const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
     if (opts?.locked) {
-      return this.installLocked(repositories, patches);
+      return this.installLocked(repositories, patches, dependencies);
     }
     const cloneError = this.ensureSourceClones(repositories, sources);
     if (cloneError) return cloneError;
@@ -1185,18 +1644,32 @@ var AssetManager = class {
       projectDir: this.projectDir,
       knownKinds: this.knownKinds
     });
-    const { resolved, missing, overridesApplied, presets } = await this.resolveWithStores(
+    const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
       dependencies,
-      {
-        provenanceIndex,
-        overrides,
-        stores
-      }
+      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
     );
-    const lib = await this.resolveLibraryEntries(missing);
+    this.assertNoFolderCollision([...resolved, ...lib.entries.map((e) => this.entryIdentity(e))]);
+    const stillMissing = missing.filter((m) => !lib.resolved.has(m));
+    const missingHints = await this.publisherChangeHints(stillMissing);
+    const prevLock = this.tryReadLock();
+    const kept = keptLockEntries(prevLock, stillMissing);
+    const fixes = await this.unresolvedFixes(stillMissing);
+    for (const ref of /* @__PURE__ */ new Set([...kept.refs, ...fixes.keys()])) {
+      const fix = fixes.get(ref);
+      const notes = [
+        kept.refs.has(ref) ? "the deployed copy and its lock entry are kept" : void 0,
+        fix
+      ].filter((n) => n !== void 0);
+      missingHints[ref] = `${fix ? "" : missingHints[ref] ?? ""} (${notes.join("; ")})`;
+    }
     const directLock = this.directInstallLockEntries();
     const libraryLock = { ...directLock, ...await this.libraryLockEntries(lib) };
-    const removed = this.reconcileRemovedAssets(resolved, new Set(Object.keys(libraryLock)));
+    const freshLock = buildLockFile(resolved, overridesApplied, libraryLock);
+    await this.keepRequiredByKept(prevLock, kept, Object.keys(freshLock.assets));
+    const removed = this.reconcileRemovedAssets(
+      resolved,
+      /* @__PURE__ */ new Set([...Object.keys(libraryLock), ...Object.keys(kept.assets)])
+    );
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
     const deployed = [
       ...new Set(
@@ -1208,16 +1681,20 @@ var AssetManager = class {
     await this.renderDriverMcpConfig();
     const agentRender = this.renderAgentInstances();
     const lockWritten = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
+    let relocked = [];
     if (lockWritten) {
-      writeLock(this.lockPath, buildLockFile(resolved, overridesApplied, libraryLock));
+      const lockData = withKeptLockEntries(freshLock, kept);
+      relocked = relockedRefs(prevLock, lockData);
+      writeLock(this.lockPath, lockData);
     }
     this.recordInstallHistory(deployed, removed);
     const { npmInstalled, npmFailed } = await this.installRuntimeAssetDeps();
-    const stillMissing = missing.filter((m) => !lib.resolved.has(m));
     return {
       deployed,
       removed,
       missing: stillMissing,
+      ...Object.keys(missingHints).length > 0 ? { missingHints } : {},
+      ...relocked.length > 0 ? { relocked } : {},
       lockWritten,
       npmInstalled,
       npmFailed,
@@ -1225,6 +1702,49 @@ var AssetManager = class {
       ...agentRender
     };
   }
+  /**
+   * Extend `kept` (see {@link keptLockEntries}) with every previous lock entry a kept asset
+   * requires, transitively, that the new lock (`freshKeys`) does not already carry. The lock
+   * records no edges, so they are read from the kept asset's deployed copy, where the
+   * requirement is publisher-qualified the same way a library scan does it. A copy that
+   * cannot be read has no known requirements.
+   */
+  async keepRequiredByKept(prev, kept, freshKeys) {
+    if (!prev) return;
+    const fresh = freshKeys.map(parseCanonicalLockKey);
+    const queue = Object.keys(kept.assets);
+    for (const key of queue) {
+      for (const dep of await this.deployedRequirements(key)) {
+        const want = memberIdentity(dep);
+        if (!want) continue;
+        const matches = (id) => id.kind === want.kind && id.name === want.name && (!want.publisher || !id.publisher || id.publisher === want.publisher);
+        if (fresh.some(matches)) continue;
+        for (const [depKey, entry] of Object.entries(prev.assets)) {
+          if (depKey in kept.assets || entry.library?.installed) continue;
+          if (!matches(parseCanonicalLockKey(depKey))) continue;
+          kept.assets[depKey] = entry;
+          queue.push(depKey);
+          const src = entry.source ? prev.sources.find((s) => s.url === entry.source?.url) : void 0;
+          if (src) kept.sources.push(src);
+        }
+      }
+    }
+  }
+  /** Publisher-qualified refs the deployed copy of the asset behind lock `key` requires. */
+  async deployedRequirements(key) {
+    const { kind, name, publisher } = parseCanonicalLockKey(key);
+    const component = kind ? this.installTarget(kind) : void 0;
+    if (!kind || !name || !component) return [];
+    const dir = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
+    if (!existsSync(dir)) return [];
+    try {
+      const scanned = await scanDirectory(dir, publisher ?? "", { knownKinds: this.knownKinds });
+      const own = scanned.find((e) => e.kind === kind && e.name === name);
+      return own ? libraryEntryDepRefs(own) : [];
+    } catch {
+      return [];
+    }
+  }
   /**
    * Ensure all source clones are present/up to date. Returns an early
    * {@link InstallResult} describing the failed source on the first error, or
@@ -1289,6 +1809,7 @@ var AssetManager = class {
       for (const ref of Object.keys(oldLock.assets)) {
         if (!resolvedRefs.has(ref)) {
           const { kind, name } = parseCanonicalLockKey(ref);
+          if (kind === "preset") continue;
           if (kind && name) {
             for (const t of this.targetHarnesses()) removeAsset(kind, name, this.deployOptsFor(t));
             removed.push(ref);
@@ -1374,7 +1895,10 @@ var AssetManager = class {
         try {
           return await src.listVersions(ref);
         } catch (err) {
-          console.warn(`skaile: store ${storeUrl} version lookup for ${ref} failed \u2014 ${err}`);
+          if (!this.warnedStoreVersionLookups.has(storeUrl)) {
+            this.warnedStoreVersionLookups.add(storeUrl);
+            console.warn(`skaile: store ${storeUrl} version lookup for ${ref} failed \u2014 ${err}`);
+          }
           return [];
         }
       }
@@ -1411,11 +1935,12 @@ var AssetManager = class {
     }
     return { npmInstalled, npmFailed };
   }
-  async installLocked(repositories, patches) {
+  async installLocked(repositories, patches, dependencies) {
     const lock = this.tryReadLock();
     if (!lock) {
       throw new Error("No lock file found. Run `skaile install` first.");
     }
+    this.assertNoFolderCollision(Object.keys(lock.assets).map(parseCanonicalLockKey));
     const declBySlug = new Map(Object.entries(repositories));
     const factoryUrl = normalizeRepoUrl(FACTORY_SOURCE_URL);
     const factoryDir = Object.values(repositories).find((d) => d.factory)?.path ?? null;
@@ -1440,6 +1965,16 @@ var AssetManager = class {
       throw new Error(`Lock file verification failed:
   ${issues.join("\n  ")}`);
     }
+    const presetGaps = await this.declaredPresetGaps(dependencies, lock);
+    if (presetGaps.size > 0) {
+      const lines = [...presetGaps].flatMap(
+        ([preset, gaps2]) => gaps2.map((g) => `${preset} item ${g.ref}`)
+      );
+      throw new Error(
+        `Lock file does not pin every item of the declared presets (not resolved by \`skaile install\`):
+  ${lines.join("\n  ")}`
+      );
+    }
     const resolved = [];
     for (const [ref, entry] of Object.entries(lock.assets)) {
       if (!entry.source) continue;
@@ -1478,10 +2013,20 @@ var AssetManager = class {
     ];
     await this.renderDriverMcpConfig();
     const agentRender = this.renderAgentInstances();
+    const alreadyMissing = new Set(
+      library.missing.map((m) => {
+        const p = parseRefTolerant(m.split(" ")[0] ?? m);
+        return p ? `${p.kind}:${p.name}` : m;
+      })
+    );
+    const gaps = (await this.lockGaps()).filter((g) => {
+      const p = parseRefTolerant(g.ref);
+      return !(p && alreadyMissing.has(`${p.kind}:${p.name}`));
+    }).map((g) => g.message);
     return {
       deployed,
       removed: [],
-      missing: library.missing,
+      missing: [...library.missing, ...gaps],
       lockWritten: false,
       ...agentRender
     };
@@ -1499,26 +2044,44 @@ var AssetManager = class {
    *   store/factory sources. Defaults to copy.
    * @param opts.onLibraryOrigin - Called once per deployed library-origin asset with its
    *   canonical ref and the name of the library it was resolved from.
+   * @param opts.onPresets - Called once with the presets expanded into this add (the
+   *   added preset and any it nests); a library-held preset names its library.
    * @returns Array of asset refs that were deployed in this call.
-   * @throws When the asset cannot be found in any configured repository.
+   * @throws When the asset cannot be found in any configured repository, or when a
+   *   preset's items do not all resolve (nothing is deployed or recorded then).
    */
   async add(ref, opts) {
-    const { repositories, sources, stores, overrides, patches } = this.loadConfig();
-    parseAssetRef(ref);
+    const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
+    const parsed = parseAssetRef(ref);
     this.ensureSourceClonesQuiet(repositories, sources);
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
       knownKinds: this.knownKinds
     });
-    const { resolved, missing, overridesApplied } = await this.resolveWithStores([ref], {
-      provenanceIndex,
-      overrides,
-      stores
-    });
-    const lib = await this.resolveLibraryEntries(missing);
-    if (resolved.length === 0 && lib.entries.length === 0) {
+    const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
+      [ref],
+      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
+    );
+    if (resolved.length === 0 && lib.entries.length === 0 && presets.length === 0) {
       throw new Error(
-        `Asset not found: ${ref}${missing.length ? ` (missing: ${missing.join(", ")})` : ""}`
+        `Asset not found: ${ref}${(await this.publisherChangeHints([ref]))[ref] ?? ""}${missing.length ? ` (missing: ${missing.join(", ")})` : ""}`
+      );
+    }
+    if (parsed.kind === "preset" && missing.length > 0) {
+      throw new Error(
+        `Preset ${ref} has items that do not resolve: ${missing.join(", ")} \u2014 nothing was added`
+      );
+    }
+    this.assertNoFolderCollision(
+      [...resolved, ...lib.entries.map((e) => this.entryIdentity(e))],
+      [
+        ...Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey),
+        ...dependencies.map((d) => parseAssetRefLoose(d) ?? {})
+      ]
+    );
+    if (missing.length > 0) {
+      console.warn(
+        `skaile: ${ref} was added without unresolved dependencies: ${missing.join(", ")}`
       );
     }
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
@@ -1536,6 +2099,7 @@ var AssetManager = class {
         if (origin && deployed.includes(deployedRef)) opts.onLibraryOrigin(deployedRef, origin);
       }
     }
+    if (presets.length > 0) opts?.onPresets?.(presets);
     this.addDependencyToConfig(ref);
     await this.renderDriverMcpConfig();
     this.renderAgentInstances();
@@ -1604,7 +2168,7 @@ var AssetManager = class {
       const out = [];
       const seen = /* @__PURE__ */ new Set();
       for (const p of await this.search(void 0, "preset")) {
-        const members = [...p.dependencies, ...p.requires.map((d) => `${d.kind}:${d.name}`)];
+        const members = [...p.dependencies, ...p.requires.map(depToStr)];
         if (!members.some((m) => sameAsset(memberIdentity(m), target))) continue;
         const publisher = p.publisher?.replace(/^@/, "");
         const presetId = { kind: "preset", name: p.name, publisher };
@@ -1784,7 +2348,14 @@ var AssetManager = class {
     return refs;
   }
   /**
-   * Remove a deployed asset and unregister it from `skaile.yaml`.
+   * Remove a deployed asset and unregister it from `skaile.yaml` and the lock.
+   *
+   * A declared asset is always unregistered, even when nothing is deployed any
+   * more (e.g. its library file was deleted): the declaration and lock entry
+   * would otherwise be stuck behind a "not deployed" refusal.
+   *
+   * Removes only `ref` itself; use {@link removeWithDependencies} to also drop the
+   * dependencies it leaves orphaned.
    *
    * Deliberately does NOT re-render the driver target's MCP config: the render
    * step is async (the declaration resolver is), and making this synchronous
@@ -1792,38 +2363,153 @@ var AssetManager = class {
    * generated entry is dropped by the next {@link AssetManager.install} — see
    * {@link renderMcpServerConfig}.
    *
-   * @param ref - Asset ref in `kind:name` form (e.g. `skill:my-skill`).
-   * @returns `true` if the asset was found and removed, `false` if it was not deployed.
-   *   A `preset:` ref has no deployed files: it is found when declared in `skaile.yaml`, and
-   *   only its declaration goes — its expanded items leave with the next `skaile install`.
+   * @param ref - Asset ref: `kind:@publisher/name`, or the short `kind:name` /
+   *   `name` form when exactly one declared, locked or deployed asset matches it.
+   * @returns `true` if anything changed (files undeployed, declaration or lock
+   *   entry removed), `false` if the asset was neither deployed nor declared.
+   *   A `preset:` ref has no deployed files: only its declaration goes — its
+   *   expanded items leave with the next `skaile install`.
+   * @throws When `ref` is malformed, or a short ref matches several assets (the
+   *   message lists them).
    */
   remove(ref) {
-    const parsed = parseAssetRef(ref);
-    let ok = parsed.kind === "preset" ? this.removeDependencyFromConfig(parsed) : false;
+    const target = this.resolveRemoveTarget(ref);
+    return target ? this.removeResolved(target) : false;
+  }
+  /**
+   * {@link remove} `ref`, then drop the dependencies that removal left orphaned:
+   * locked assets `ref` required (directly or through one another) that
+   * `skaile.yaml` no longer declares and no remaining locked asset requires. A
+   * preset's items count as its requirements. They are undeployed and unlocked;
+   * a dependency still declared or required elsewhere stays.
+   *
+   * @returns `changed` as {@link remove}; `pruned` the canonical refs
+   *   (`kind:@publisher/name`) of the dependencies dropped as well.
+   */
+  async removeWithDependencies(ref) {
+    const target = this.resolveRemoveTarget(ref);
+    if (!target) return { changed: false, pruned: [] };
+    const asked = target.publisher ? assetRefToStr({ kind: target.kind, name: target.name, publisher: target.publisher }) : `${target.kind}:${target.name}`;
+    let entry = null;
+    try {
+      entry = await this.info(asked);
+    } catch {
+    }
+    const requiredRefs = entry ? libraryEntryDepRefs(entry) : [];
+    const changed = this.removeResolved(target);
+    if (!changed || requiredRefs.length === 0) return { changed, pruned: [] };
+    return { changed, pruned: await this.pruneOrphans(requiredRefs) };
+  }
+  /**
+   * Resolve the identity {@link remove} acts on. A publisher-qualified ref is taken
+   * as written; a short ref (`kind:name`, or just `name`) is matched on kind + name
+   * against the declared dependencies, the lock and the deployed assets, like
+   * `why` / `diff` do.
+   *
+   * @returns the identity, or `null` when a name-only ref matches nothing.
+   * @throws On a malformed ref, or when a short ref matches more than one asset.
+   */
+  resolveRemoveTarget(ref) {
+    const trimmed = ref.trim();
+    try {
+      return parseAssetRef(trimmed);
+    } catch (err) {
+      if (!(err instanceof Error) || !err.message.startsWith("publisher required")) throw err;
+      const colon = trimmed.indexOf(":");
+      const rawKind = colon === -1 ? void 0 : trimmed.slice(0, colon).trim();
+      const kind = rawKind === "mcp" ? "mcp-server" : rawKind;
+      const hash = trimmed.indexOf("#", colon + 1);
+      const name = trimmed.slice(colon + 1, hash === -1 ? void 0 : hash).trim();
+      if (!name || /[@/\s]/.test(name)) throw err;
+      const found = [];
+      const note = (id) => {
+        if (!id?.kind || id.name !== name || kind && id.kind !== kind) return;
+        found.push({ kind: id.kind, name: id.name, publisher: id.publisher });
+      };
+      try {
+        for (const dep of this.loadConfig().dependencies) note(memberIdentity(dep));
+      } catch {
+      }
+      for (const key of Object.keys(this.tryReadLock()?.assets ?? {})) {
+        note(parseCanonicalLockKey(key));
+      }
+      for (const e of this.listDeployed()) note(e);
+      const qualified = found.filter((f) => f.publisher);
+      const distinct = /* @__PURE__ */ new Map();
+      for (const f of found) {
+        if (!f.publisher && qualified.some((q) => q.kind === f.kind)) continue;
+        distinct.set(`${f.kind}:${f.publisher ?? ""}/${f.name}`, f);
+      }
+      const matches = [...distinct.values()];
+      if (matches.length > 1) {
+        const list = matches.map((m) => m.publisher ? `${m.kind}:@${m.publisher}/${m.name}` : `${m.kind}:${m.name}`).join(", ");
+        throw new Error(`"${ref}" matches several assets (${list}) \u2014 name one with its full ref.`);
+      }
+      if (matches.length === 1) return matches[0];
+      return kind ? { kind, name } : null;
+    }
+  }
+  /** Undeploy `parsed` from every target harness and drop its declaration and lock entry. */
+  removeResolved(parsed) {
+    let undeployed = false;
     for (const t of this.targetHarnesses()) {
-      if (removeAsset(parsed.kind, parsed.name, this.deployOptsFor(t))) ok = true;
+      if (removeAsset(parsed.kind, parsed.name, this.deployOptsFor(t))) undeployed = true;
     }
-    if (ok) {
-      const depRef = `${parsed.kind}:${parsed.name}`;
-      this.removeDependencyFromConfig(parsed);
-      this.pruneLockEntry(parsed);
+    const undeclared = this.removeDependencyFromConfig(parsed);
+    const unlocked = undeployed || undeclared ? this.pruneLockEntry(parsed) : false;
+    const changed = undeployed || undeclared || unlocked;
+    if (changed) {
       appendHistory(this.projectDir, {
-        ref: depRef,
+        ref: `${parsed.kind}:${parsed.name}`,
         action: "remove",
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         context: this.global ? "global" : "project"
       });
     }
-    return ok;
+    return changed;
+  }
+  /**
+   * Drop the locked assets among `requiredRefs` (and what they require in turn) that
+   * nothing needs any more: not declared in `skaile.yaml`, not required by a locked
+   * asset outside that set. Call after the requiring asset is gone.
+   *
+   * @returns the canonical refs of the assets dropped.
+   */
+  async pruneOrphans(requiredRefs) {
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const { requires, roots, findKey } = await this.lockedGraph(lock);
+    const closure = (seeds) => {
+      const out = new Set(seeds);
+      for (const node of out) for (const dep of requires.get(node) ?? []) out.add(dep);
+      return out;
+    };
+    const candidates = closure(requiredRefs.map(findKey).filter((k) => !!k));
+    const needed = closure([
+      ...roots,
+      ...Object.keys(lock.assets).filter((k) => !candidates.has(k))
+    ]);
+    const pruned = [];
+    for (const key of candidates) {
+      if (needed.has(key) || !lock.assets[key]) continue;
+      const { kind, name, publisher } = parseCanonicalLockKey(key);
+      if (!kind || !name) continue;
+      this.removeResolved({ kind, name, publisher });
+      this.pruneLockEntry({ kind, name, publisher });
+      pruned.push(publisher ? assetRefToStr({ kind, name, publisher }) : `${kind}:${name}`);
+    }
+    return pruned;
   }
   /**
    * Drop every lock entry matching a removed asset's identity, version-agnostic so
    * a content-sha pseudo-version key is pruned too. Symmetric with {@link add}'s
    * lock-merge — stops a stale entry reporting a phantom "removed" on next install.
+   *
+   * @returns `true` when at least one lock entry was dropped.
    */
   pruneLockEntry(parsed) {
     const lock = this.tryReadLock();
-    if (!lock) return;
+    if (!lock) return false;
     let changed = false;
     for (const key of Object.keys(lock.assets)) {
       const id = parseCanonicalLockKey(key);
@@ -1833,6 +2519,7 @@ var AssetManager = class {
       }
     }
     if (changed) writeLock(this.lockPath, lock);
+    return changed;
   }
   // ── Query ──────────────────────────────────────────────────────────────
   /**
@@ -1993,9 +2680,15 @@ var AssetManager = class {
     for (const { kind, name, component: k } of tracked.values()) {
       const legacy = deployedDir(k, name, "claude-code", false, this.projectDir);
       if (legacy === deployedDir(k, name, this.driverTarget, false, this.projectDir)) continue;
-      if (isDeployed(k, name, "claude-code", false, this.projectDir)) {
-        out.push({ kind, name, path: legacy });
-      }
+      const found = deployedPaths(k, name, "claude-code", false, this.projectDir).find((p) => {
+        try {
+          lstatSync(p);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+      if (found) out.push({ kind, name, path: found });
     }
     return out.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
   }
@@ -2029,6 +2722,7 @@ var AssetManager = class {
     const dependencies = resolveSkWorkspaceConfig(this.projectDir).dependencies ?? [];
     const lock = this.tryReadLock();
     const lockKeys = lock ? Object.keys(lock.assets).map(parseCanonicalLockKey) : [];
+    const presetGaps = await this.declaredPresetGaps(dependencies, lock);
     let wiredMcps;
     const wiredMcpNames = async () => {
       if (wiredMcps === void 0) {
@@ -2051,7 +2745,7 @@ var AssetManager = class {
         continue;
       }
       if (kind && parsed.kind !== kind) continue;
-      const locked = parsed.kind === "preset" ? lock !== null : lockKeys.some(
+      const locked = parsed.kind === "preset" ? lock !== null && !presetGaps.get(ref)?.length : lockKeys.some(
         (k) => k.kind === parsed.kind && k.name === parsed.name && (!parsed.publisher || k.publisher === parsed.publisher)
       );
       let state;
@@ -2079,6 +2773,38 @@ var AssetManager = class {
     }
     return out;
   }
+  /**
+   * Library-locked assets whose deployed directory lacks files the deploy writes —
+   * a deleted `build.py` / `scripts/` helper next to an intact `SKILL.md`. The
+   * expected set is the library entry's file set (every file under its manifest
+   * `root:`), the same bytes the lock hashes; only presence is checked, so a
+   * local edit never counts. An asset with no deployed directory is not listed
+   * (`listDeclared` reports it as drift); an agent is rendered, not copied, so it
+   * has no file mirror to compare. `skaile install` restores what is listed.
+   *
+   * @returns One {@link IncompleteDeploy} per affected asset; empty when healthy
+   *   or when the project has no lock.
+   */
+  async incompleteDeploys() {
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const locked = Object.entries(lock.assets).filter(([, e]) => e.library !== void 0 && !e.library.installed).map(([key]) => key);
+    if (locked.length === 0) return [];
+    const lib = await this.resolveLibraryEntries(locked, { quiet: true });
+    const out = [];
+    for (const entry of lib.entries) {
+      const component = this.installTarget(entry.kind);
+      if (!entry.files || !component || component === "agent") continue;
+      const dest = join(
+        deployedBase(component, this.driverTarget, this.global, this.projectDir),
+        entry.name
+      );
+      if (!existsSync(dest)) continue;
+      const missing = entry.files.filter((rel) => !existsSync(join(dest, rel)));
+      if (missing.length > 0) out.push({ ref: canonicalEntryRef(entry), missing });
+    }
+    return out;
+  }
   /**
    * Per-harness reconciliation of the **global** declared deps
    * (`~/.skaile/skaile.yaml`) against each global harness's deploy dir. The
@@ -2176,70 +2902,197 @@ var AssetManager = class {
     }
     return repoStatuses;
   }
+  /**
+   * Requirement graph of the locked assets, for {@link tree} / {@link why} / removal pruning.
+   *
+   * The lock records no edges, so they are rebuilt from each locked asset's own
+   * declaration (`requires`, manifest `dependencies`, a preset's items) — the same
+   * source the install walk reads, via {@link info}. An asset that no source or
+   * library can be found for has no known requirements. Nodes are lock keys, plus
+   * each declared `preset:` that the lock does not carry (a preset is expanded at
+   * install, never locked), keyed by its declared ref.
+   *
+   * @returns `requires` (node → the lock keys it requires), `roots` (nodes
+   *   `skaile.yaml` declares) and `findKey` (a ref → its lock key, version-agnostic).
+   */
+  async lockedGraph(lock) {
+    const locked = Object.keys(lock.assets).map((key) => ({ key, ...parseCanonicalLockKey(key) }));
+    const findKey = (ref) => {
+      const id = memberIdentity(ref);
+      if (!id) return void 0;
+      return locked.find(
+        (l) => l.kind === id.kind && l.name === id.name && (!id.publisher || !l.publisher || l.publisher === id.publisher)
+      )?.key;
+    };
+    const requires = /* @__PURE__ */ new Map();
+    const link = async (node, ref) => {
+      const out = [];
+      try {
+        const entry = await this.info(ref);
+        for (const dep of entry ? libraryEntryDepRefs(entry) : []) {
+          const key = findKey(dep);
+          if (key && key !== node && !out.includes(key)) out.push(key);
+        }
+      } catch {
+      }
+      requires.set(node, out);
+    };
+    for (const l of locked) {
+      await link(
+        l.key,
+        l.publisher ? `${l.kind}:@${l.publisher}/${l.name}` : `${l.kind}:${l.name}`
+      );
+    }
+    const roots = [];
+    let declared = [];
+    try {
+      declared = this.loadConfig().dependencies;
+    } catch {
+    }
+    for (const dep of declared) {
+      const key = findKey(dep);
+      if (key) {
+        if (!roots.includes(key)) roots.push(key);
+      } else if (memberIdentity(dep)?.kind === "preset" && !roots.includes(dep)) {
+        await link(dep, dep);
+        roots.push(dep);
+      }
+    }
+    return { requires, roots, findKey };
+  }
   /**
    * Build the resolved dependency tree from the lock file.
    *
+   * Required assets nest under the asset that requires them (see {@link lockedGraph});
+   * an asset required by several parents appears under each, and a dependency cycle
+   * is cut where it would repeat.
+   *
    * @returns Root {@link DependencyNode} with `ref === "project"` whose children
-   *   are the directly-declared dependencies, each with their own transitive subtrees.
+   *   are the directly-declared assets, followed by locked assets nothing requires,
+   *   each with the assets it requires as children.
    *   Returns a single node with `ref === "(no lock file)"` when no lock exists.
    */
-  tree() {
+  async tree() {
     const lock = this.tryReadLock();
     if (!lock) return { ref: "(no lock file)", children: [] };
-    return {
-      ref: "project",
-      children: Object.keys(lock.assets).map((ref) => ({ ref, children: [] }))
+    const { requires, roots } = await this.lockedGraph(lock);
+    const required = new Set([...requires.values()].flat());
+    const build = (ref, path2) => ({
+      ref,
+      children: (requires.get(ref) ?? []).filter((child) => !path2.has(child)).map((child) => build(child, /* @__PURE__ */ new Set([...path2, child])))
+    });
+    const shown = /* @__PURE__ */ new Set();
+    const top = [];
+    const addTop = (ref) => {
+      const node = build(ref, /* @__PURE__ */ new Set([ref]));
+      top.push(node);
+      const walk = (n) => {
+        shown.add(n.ref);
+        for (const c of n.children) walk(c);
+      };
+      walk(node);
     };
+    const lockKeys = Object.keys(lock.assets);
+    for (const ref of roots) addTop(ref);
+    for (const ref of lockKeys) if (!roots.includes(ref) && !required.has(ref)) addTop(ref);
+    for (const ref of lockKeys) if (!shown.has(ref)) addTop(ref);
+    return { ref: "project", children: top };
   }
   /**
-   * Explain why an asset is installed by tracing its dependency chain in the lock file.
+   * Explain why an asset is installed by tracing its dependency chain.
+   *
+   * The chain is read from the requirement graph ({@link lockedGraph}): the asset,
+   * then the asset that requires it, and so on up to a dependency `skaile.yaml`
+   * declares (the shortest such path; cycles are not followed twice).
    *
    * @param ref - Asset ref in `kind:name` form.
-   * @returns Chain of refs from the asset back to `"direct (skaile.yaml)"`, or `[]` when
-   *   the asset is not in the lock file.
+   * @returns Chain of refs from the asset back to `"direct (skaile.yaml)"`; an asset
+   *   no declared dependency reaches ends in `"not required by a declared dependency"`
+   *   instead. `[]` when the asset is not in the lock file.
    */
-  why(ref) {
+  async why(ref) {
     const lock = this.tryReadLock();
     if (!lock) return [];
     const bare = (s) => s.includes("#") ? s.slice(0, s.indexOf("#")) : s;
-    const key = lock.assets[ref] ? ref : Object.keys(lock.assets).find((k) => bare(k) === bare(ref));
+    const asked = parseRefTolerant(ref);
+    const matchesIdentity = (k) => {
+      if (bare(k) === bare(ref)) return true;
+      if (!asked || asked.publisher) return false;
+      const locked = parseCanonicalLockKey(k);
+      return locked.kind === asked.kind && locked.name === asked.name;
+    };
+    const key = lock.assets[ref] ? ref : Object.keys(lock.assets).find(matchesIdentity);
     if (!key) return [];
-    return [key, "direct (skaile.yaml)"];
+    const { requires, roots } = await this.lockedGraph(lock);
+    if (roots.includes(key)) return [key, "direct (skaile.yaml)"];
+    const requirers = /* @__PURE__ */ new Map();
+    for (const [node, deps] of requires) {
+      for (const dep of deps) requirers.set(dep, [...requirers.get(dep) ?? [], node]);
+    }
+    const child = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set([key]);
+    const queue = [key];
+    for (let node = queue.shift(); node !== void 0; node = queue.shift()) {
+      for (const parent of requirers.get(node) ?? []) {
+        if (seen.has(parent)) continue;
+        seen.add(parent);
+        child.set(parent, node);
+        if (roots.includes(parent)) {
+          const chain = [];
+          for (let c = parent; c !== void 0; c = child.get(c)) chain.push(c);
+          return [...chain.reverse(), "direct (skaile.yaml)"];
+        }
+        queue.push(parent);
+      }
+    }
+    return [key, "not required by a declared dependency"];
   }
   /**
    * List installed assets that have a newer upstream available.
    *
    * Two kinds of staleness are reported:
    * - **Source assets** — only remote repositories (not local paths) are checked;
-   *   `behind` is the number of commits the local clone is missing.
-   * - **Library assets** — a library-origin lock entry whose library index now
-   *   offers a newer version than the locked one; `behind` is 0, `latestVersion`
-   *   and `library` are set. A library not indexed (or removed) is not reported.
+   *   `behind` counts the commits the clone is missing from the remote plus the
+   *   commits the clone moved past the locked commit (`source sync` after `add`).
+   * - **Library assets** — a library-origin lock entry whose library files on disk
+   *   (not the index, which lags until `skaile library index`) hold a newer version
+   *   than the locked one (`latestVersion`, `library` set), or the same version with
+   *   different bytes (`contentChanged`). `behind` is 0. An unregistered library is a
+   *   `problem` row.
+   * - **Lock gaps** — every {@link AssetManager.lockGaps} gap (a declared dependency or a
+   *   deployed asset's `requires` with no lock entry, a lock that contradicts a
+   *   `skaile.yaml` pin) as a `problem` row, so `outdated` agrees with `check`.
    *
    * @returns Array of {@link OutdatedEntry} objects.
    */
   async outdated() {
     const { repositories } = this.loadConfig();
     const lock = this.tryReadLock();
-    if (!lock) return [];
+    if (!lock) return this.addLockGapRows([]);
     const result = [];
     const reported = /* @__PURE__ */ new Set();
+    const commitCounts = /* @__PURE__ */ new Map();
     for (const src of lock.sources) {
       const slug = sourceCacheKey(src.url);
       const decl = repositories[slug];
       if (!decl) continue;
       const status = checkRepoStatus(decl, slug, this.reposDir);
-      if (status.behind <= 0) continue;
+      if (status.kind !== "remote" || !status.localHead) continue;
+      const clone = decl.path ?? join(this.reposDir, slug);
       for (const [ref, entry] of Object.entries(lock.assets)) {
         if (entry.source?.url !== src.url) continue;
         const { publisher, kind, name, version } = parseCanonicalLockKey(ref);
         if (!kind || !name) continue;
+        const lockedCommit = entry.source.commit || src.commit;
+        const moved = lockedCommit && !/^0+$/.test(lockedCommit) && lockedCommit !== status.localHead ? commitsBetween(clone, lockedCommit, status.localHead, commitCounts) : 0;
+        const behind = status.behind + moved;
+        if (behind <= 0) continue;
         result.push({
           kind,
           name,
           publisher: publisher ?? sourceShortName(src.url),
           currentVersion: version ?? "",
-          behind: status.behind
+          behind
         });
         reported.add(ref);
       }
@@ -2249,11 +3102,17 @@ var AssetManager = class {
     );
     if (libraryAssets.length > 0) {
       const snap = await this.loadLibraryIndex();
+      const diskHashes = /* @__PURE__ */ new Map();
+      const scans = /* @__PURE__ */ new Map();
       for (const [ref, entry] of libraryAssets) {
         const origin = entry.library;
         const { publisher, kind, name } = parseCanonicalLockKey(ref);
         if (!publisher || !kind || !name) continue;
-        if (!this.libraryPath(origin.name, snap)) {
+        const libPath = this.libraryPath(origin.name, snap);
+        if (!libPath) {
+          const canonical = `${kind}:@${publisher}/${name}`;
+          const heldElsewhere = (await this.resolveLibraryEntries([canonical], { quiet: true })).resolved.size > 0;
+          const fix = heldElsewhere ? void 0 : (await this.unresolvedFixes([canonical])).get(canonical) ?? unregisteredLibraryFix(origin.name, canonical);
           result.push({
             kind,
             name,
@@ -2261,23 +3120,55 @@ var AssetManager = class {
             currentVersion: origin.version,
             behind: 0,
             library: origin.name,
-            problem: `library "${origin.name}" is not registered (renamed or removed?)`
+            ...fix === void 0 ? {
+              problem: `library "${origin.name}" is not registered (renamed?) \u2014 run \`skaile install\` to re-lock it against the library that holds it now`
+            } : {
+              problem: `library "${origin.name}" is not registered (renamed or removed?) \u2014 ${fix}`,
+              manualFix: true
+            }
           });
           reported.add(ref);
           continue;
         }
-        const def = newestLibraryDef(snap, origin.name, { kind, publisher, name });
-        if (!def || !gt(coerceVersion(def.version), coerceVersion(origin.version))) continue;
-        result.push({
-          kind,
-          name,
-          publisher,
-          currentVersion: origin.version,
-          behind: 0,
-          latestVersion: def.version,
-          library: origin.name
-        });
-        reported.add(ref);
+        const scanKey = `${libPath}\0${publisher}`;
+        let scanned = scans.get(scanKey);
+        if (!scanned) {
+          scanned = await scanDirectory(libPath, publisher, { knownKinds: this.knownKinds });
+          scans.set(scanKey, scanned);
+        }
+        const found = scanned.find((x) => x.kind === kind && x.name === name);
+        if (!found) continue;
+        const diskVersion = found.version || newestLibraryDef(snap, origin.name, { kind, publisher, name })?.version;
+        if (diskVersion && gt(coerceVersion(diskVersion), coerceVersion(origin.version))) {
+          result.push({
+            kind,
+            name,
+            publisher,
+            currentVersion: origin.version,
+            behind: 0,
+            latestVersion: diskVersion,
+            library: origin.name
+          });
+          reported.add(ref);
+          continue;
+        }
+        if (origin.sha256) {
+          const onDisk = libraryDiskHashes(libPath, diskHashes, this.registry).get(
+            `${kind}:${name}`
+          );
+          if (onDisk !== void 0 && onDisk !== origin.sha256) {
+            result.push({
+              kind,
+              name,
+              publisher,
+              currentVersion: origin.version,
+              behind: 0,
+              library: origin.name,
+              contentChanged: true
+            });
+            reported.add(ref);
+          }
+        }
       }
     }
     for (const [ref, entry] of Object.entries(lock.assets)) {
@@ -2298,7 +3189,30 @@ var AssetManager = class {
         problem: "deployed copy missing"
       });
     }
-    return result;
+    return this.addLockGapRows(result);
+  }
+  /**
+   * Append one `problem` row per {@link AssetManager.lockGaps} gap whose asset is not
+   * listed yet, so `outdated` reports the same set `check` and `install --locked` fail on.
+   */
+  async addLockGapRows(rows) {
+    const listed = new Set(rows.map((r) => `${r.kind}:${r.name}`));
+    for (const gap of await this.lockGaps()) {
+      const parsed = parseRefTolerant(gap.ref);
+      const id = parsed ? `${parsed.kind}:${parsed.name}` : gap.ref;
+      if (listed.has(id)) continue;
+      listed.add(id);
+      rows.push({
+        kind: parsed?.kind ?? "",
+        name: parsed?.name ?? gap.ref,
+        publisher: parsed?.publisher ?? "",
+        currentVersion: "",
+        behind: 0,
+        problem: gap.reason,
+        ...gap.manualFix ? { manualFix: true } : {}
+      });
+    }
+    return rows;
   }
   /**
    * Produce a unified diff from the deployed asset to its catalog source: `-` lines
@@ -2315,7 +3229,8 @@ var AssetManager = class {
    * @throws When `diff(1)` itself fails (exit status other than 0/1).
    */
   async diff(ref) {
-    const parsed = parseAssetRef(ref);
+    const parsed = parseRefTolerant(ref);
+    if (!parsed) return { status: "not-found" };
     const entry = await this.info(ref);
     if (!entry || !existsSync(entry.source)) return { status: "not-found" };
     const component = this.installTarget(parsed.kind);
@@ -2325,10 +3240,20 @@ var AssetManager = class {
       parsed.name
     );
     if (!existsSync(deployedPath)) return { status: "not-deployed" };
-    const r = spawnSync("diff", ["-ruN", deployedPath, entry.source], { encoding: "utf8" });
-    if (r.status === 1) return { status: "differs", diff: r.stdout };
-    if (r.status === 0) return { status: "identical" };
-    throw new Error(`diff failed for ${ref}: ${r.stderr || r.error?.message || "unknown error"}`);
+    const pairs = entry.files ? entry.files.map((rel) => [join(deployedPath, rel), join(dirname(entry.source), rel)]) : [[deployedPath, entry.source]];
+    const diffs = [];
+    for (const [from, to] of pairs) {
+      const r = spawnSync("diff", [entry.files ? "-uN" : "-ruN", from, to], {
+        encoding: "utf8"
+      });
+      if (r.status === 1) diffs.push(r.stdout);
+      else if (r.status !== 0) {
+        throw new Error(
+          `diff failed for ${ref}: ${r.stderr || r.error?.message || "unknown error"}`
+        );
+      }
+    }
+    return diffs.length > 0 ? { status: "differs", diff: diffs.join("") } : { status: "identical" };
   }
   // ── Lock ───────────────────────────────────────────────────────────────
   /**
@@ -2346,12 +3271,13 @@ var AssetManager = class {
       projectDir: this.projectDir,
       knownKinds: this.knownKinds
     });
-    const { resolved, missing, overridesApplied } = await this.resolveWithStores(dependencies, {
+    const { resolved, overridesApplied, lib } = await this.resolveLibraryFirst(dependencies, {
       provenanceIndex,
       overrides,
-      stores
+      stores,
+      declaredRefs: dependencies
     });
-    const libraryLock = await this.libraryLockEntries(await this.resolveLibraryEntries(missing));
+    const libraryLock = await this.libraryLockEntries(lib);
     const lockData = buildLockFile(resolved, overridesApplied, libraryLock);
     writeLock(this.lockPath, lockData);
     return lockData;
@@ -2445,37 +3371,245 @@ var AssetManager = class {
    *
    * For each deployed asset, checks that all entries in its `requires` list are
    * also deployed. Returns a list of issues with a flag indicating whether the
-   * missing dependency can be resolved from a configured repository.
+   * missing dependency can be resolved from a configured repository or library.
+   *
+   * A deployed asset is looked up by its publisher-qualified identity taken from
+   * the lock key (`kind:@pub/name`), so library and source assets resolve alike.
+   * A lock-managed asset that no source or library can be found for is reported
+   * as an issue with `unresolved: true` (its `requires` cannot be verified);
+   * unmanaged deployed files carry no declared origin and are skipped.
    *
    * @returns Array of {@link DepIssue} objects. An empty array means the workspace is healthy.
    */
   async doctor() {
-    const { repositories } = this.loadConfig();
+    const { repositories, dependencies } = this.loadConfig();
     const deployed = this.listDeployed();
     const issues = [];
+    const lock = this.tryReadLock();
+    const lockedPublisher = {};
+    for (const key of Object.keys(lock?.assets ?? {})) {
+      const { kind, name, publisher } = parseCanonicalLockKey(key);
+      if (kind && name && publisher) lockedPublisher[`${kind}:${name}`] = publisher;
+    }
     for (const entry of deployed) {
-      const full = await this.info(`${entry.kind}:${entry.name}`);
-      if (!full) continue;
+      const publisher = lockedPublisher[`${entry.kind}:${entry.name}`];
+      const full = await this.info(
+        publisher ? `${entry.kind}:@${publisher}/${entry.name}` : `${entry.kind}:${entry.name}`
+      );
+      if (!full) {
+        if (publisher) {
+          const canonical = `${entry.kind}:@${publisher}/${entry.name}`;
+          const fix = (await this.unresolvedFixes([canonical])).get(canonical);
+          issues.push({
+            assetKind: entry.kind,
+            assetName: entry.name,
+            depKind: entry.kind,
+            depName: entry.name,
+            inRepos: false,
+            unresolved: true,
+            ...fix ? { fix } : {}
+          });
+        }
+        continue;
+      }
+      const gaps = [];
       for (const req of full.requires) {
-        const dep = memberIdentity(`${req.kind}:${req.name}`);
+        const dep = memberIdentity(depToStr(req));
         if (!dep) continue;
         const depComponent = this.installTarget(dep.kind);
         if (depComponent && !isDeployed(depComponent, dep.name, this.driverTarget, this.global, this.projectDir)) {
           const inRepos = await resolveAsset({ kind: dep.kind, name: dep.name }, repositories, this.reposDir, {
             knownKinds: this.knownKinds
           }) !== null;
-          issues.push({
+          const issue = {
             assetKind: entry.kind,
             assetName: entry.name,
             depKind: req.kind,
-            depName: req.name,
+            depName: req.publisher ? `@${req.publisher}/${req.name}` : req.name,
             inRepos
-          });
+          };
+          issues.push(issue);
+          if (!inRepos) gaps.push({ issue, ref: depToStr(req) });
         }
       }
+      const inLibrary = await this.resolveLibraryEntries(gaps.map((g) => g.ref));
+      for (const g of gaps) g.issue.inRepos = inLibrary.resolved.has(g.ref);
+    }
+    for (const [presetRef, gaps] of await this.declaredPresetGaps(dependencies, lock)) {
+      const preset = parseRefTolerant(presetRef);
+      if (!preset) continue;
+      for (const g of gaps) {
+        const item = parseRefTolerant(g.ref);
+        if (!item) continue;
+        issues.push({
+          assetKind: "preset",
+          assetName: preset.name,
+          depKind: item.kind,
+          depName: item.publisher ? `@${item.publisher}/${item.name}` : item.name,
+          inRepos: g.resolvable
+        });
+      }
     }
     return issues;
   }
+  /**
+   * Everything the lock does not cover or contradicts, in one list: the set
+   * `skaile check`, `skaile install --locked` and `skaile outdated` all report.
+   *
+   * - `declared` — a `skaile.yaml` dependency with no lock entry (library or source gone,
+   *   unresolvable ref, never installed);
+   * - `invalid` — a `dependencies:` entry that is not a parseable ref;
+   * - `drift` — declared + locked but its deployed files are missing;
+   * - `pin` — a declared `#pin` that no lock entry for that asset satisfies;
+   * - `requires` — a deployed asset's `requires` that is not deployed (so not locked either);
+   * - `unresolved` — a lock-managed asset that no source or library holds any more.
+   *
+   * Project mode only: a global manager (`global: true`) returns `[]`. A project without
+   * `skaile.yaml` has no declared set, so only the `requires` / `unresolved` gaps of
+   * deployed assets can appear.
+   *
+   * @returns One {@link LockGap} per gap; empty when the lock covers everything declared.
+   */
+  async lockGaps() {
+    if (this.global) return [];
+    const gaps = [];
+    const issues = await this.doctor();
+    for (const i of issues) {
+      if (i.unresolved) {
+        const ref = `${i.assetKind}:${i.assetName}`;
+        const reason = `is locked but no source or library provides it any more \u2014 its requirements cannot be checked${i.fix ? ` (${i.fix})` : ""}`;
+        gaps.push({
+          type: "unresolved",
+          ref,
+          reason,
+          message: `${ref} ${reason}`,
+          ...i.fix ? { manualFix: true } : {}
+        });
+        continue;
+      }
+      const asset = `${i.assetKind}:${i.assetName}`;
+      const dep = `${i.depKind}:${i.depName}`;
+      const fix = i.inRepos ? "fixable" : "not found";
+      gaps.push({
+        type: "requires",
+        ref: dep,
+        reason: `is required by ${asset} but neither deployed nor locked (${fix})`,
+        message: `${asset} requires ${dep} (${fix})`
+      });
+    }
+    let declared = [];
+    try {
+      declared = await this.listDeclared();
+    } catch {
+      return gaps;
+    }
+    const unlocked = declared.filter((d) => d.state === "declared").map((d) => d.ref);
+    const hints = await this.publisherChangeHints(unlocked);
+    const lockKeys = Object.keys(this.tryReadLock()?.assets ?? {});
+    for (const d of declared) {
+      if (d.kind === "preset" && issues.some((i) => i.assetKind === "preset" && i.assetName === d.name)) {
+        continue;
+      }
+      let gap;
+      if (d.state === "invalid") {
+        gap = {
+          type: "invalid",
+          reason: "is not a valid asset ref (expected kind:@<publisher>/<name>#<version>)"
+        };
+      } else if (d.state === "drift") {
+        gap = {
+          type: "drift",
+          reason: "is declared and locked but not materialized \u2014 run `skaile install`"
+        };
+      } else if (d.state === "declared") {
+        const hint = hints[d.ref];
+        gap = hint ? { type: "declared", reason: `is declared but does not resolve${hint}`, manualFix: true } : {
+          type: "declared",
+          reason: "is declared but does not resolve \u2014 run `skaile install`"
+        };
+      } else {
+        const want = parseAssetRef(d.ref);
+        if (!want.pin || want.kind === "preset") continue;
+        const held = lockKeys.map((key) => ({ key, id: parseCanonicalLockKey(key) })).filter(
+          ({ id }) => id.kind === want.kind && id.name === want.name && (!want.publisher || id.publisher === want.publisher)
+        );
+        if (held.length > 0 && !held.some(({ id }) => !id.version || matchPin(want.pin, id.version))) {
+          gap = {
+            type: "pin",
+            reason: `is pinned in skaile.yaml but the lock holds ${held.map((h) => h.key).join(", ")} \u2014 run \`skaile install\``
+          };
+        }
+      }
+      if (gap) gaps.push({ ...gap, ref: d.ref, message: `${d.ref} ${gap.reason}` });
+    }
+    return gaps;
+  }
+  /**
+   * Items of each declared `preset:` dependency that the lock does not cover.
+   *
+   * A preset is never locked itself; the lock lists only its expanded items, so an
+   * item missing from the lock never resolved (or was declared after the last
+   * install). Presets are read from the local sources and libraries (nested presets
+   * followed); one only a store holds cannot be read without the network and
+   * reports no gaps. Without a lock nothing is reported: `list` and `check` already
+   * show a never-installed declaration as `declared`.
+   *
+   * @param declared - The `dependencies:` refs as written in `skaile.yaml`.
+   * @param lock - The current lock, or `null` when none exists.
+   * @returns Declared preset ref → its uncovered items; `resolvable` is `true` when a
+   *   local source or library offers the item (so `skaile install` can fix it).
+   *   Presets without gaps are absent.
+   */
+  async declaredPresetGaps(declared, lock) {
+    const gaps = /* @__PURE__ */ new Map();
+    if (!lock) return gaps;
+    const presetRefs = declared.filter((d) => parseRefTolerant(d)?.kind === "preset");
+    if (presetRefs.length === 0) return gaps;
+    const { repositories } = this.loadConfig();
+    const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
+      projectDir: this.projectDir,
+      knownKinds: this.knownKinds
+    });
+    const lockKeys = Object.keys(lock.assets).map(parseCanonicalLockKey);
+    const sourceCandidate = (ref) => {
+      const p = parseRefTolerant(ref);
+      if (!p?.publisher) return void 0;
+      const hash = ref.indexOf("#");
+      const pin = p.pin ?? (hash >= 0 ? ref.slice(hash + 1) : void 0);
+      return (provenanceIndex.get(`${p.publisher}/${p.kind}:${p.name}`) ?? []).filter((c) => matchPin(pin, c.version)).sort((a, b) => {
+        const va = coerceVersion(a.version);
+        const vb = coerceVersion(b.version);
+        return gt(va, vb) ? -1 : gt(vb, va) ? 1 : 0;
+      })[0];
+    };
+    const itemsOf = async (ref) => {
+      const src = sourceCandidate(ref);
+      if (src) return (src.deps ?? []).map((d) => qualifyDepRef(d, src.publisher));
+      const entry = (await this.resolveLibraryEntries([ref], { quiet: true })).entries[0];
+      return entry ? libraryEntryDepRefs(entry) : null;
+    };
+    const resolvableLocally = async (ref) => sourceCandidate(ref) !== void 0 || (await this.resolveLibraryEntries([ref], { quiet: true })).resolved.has(ref);
+    const isLocked = (item) => lockKeys.some(
+      (k) => k.kind === item.kind && k.name === item.name && (!item.publisher || k.publisher === item.publisher)
+    );
+    for (const presetRef of presetRefs) {
+      const out = [];
+      const visited = /* @__PURE__ */ new Set();
+      const walk = async (ref) => {
+        if (visited.has(ref)) return;
+        visited.add(ref);
+        for (const item of await itemsOf(ref) ?? []) {
+          const p = parseRefTolerant(item);
+          if (!p) continue;
+          if (p.kind === "preset") await walk(item);
+          else if (!isLocked(p)) out.push({ ref: item, resolvable: await resolvableLocally(item) });
+        }
+      };
+      await walk(presetRef);
+      if (out.length > 0) gaps.set(presetRef, out);
+    }
+    return gaps;
+  }
   // ── Scaffold ───────────────────────────────────────────────────────────
   /**
    * Create a minimal asset scaffold directory (delegates to {@link createScaffold}).
@@ -2485,7 +3619,7 @@ var AssetManager = class {
    * @param destDir - Parent directory to create the asset in.
    * @param opts - Optional scaffold content (`description`).
    * @returns `{ ok: true, path }` on success, `{ ok: false, path: errorMessage }` if the
-   *   directory already exists.
+   *   directory already exists or `kind` has no scaffold template.
    */
   create(name, kind, destDir, opts) {
     return createScaffold(name, kind, destDir, opts);
@@ -2544,15 +3678,21 @@ var AssetManager = class {
       const { kind, name } = parseCanonicalLockKey(ref);
       const component = kind ? this.installTarget(kind) : void 0;
       if (!kind || !name || !component) continue;
-      const dest = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
-      try {
-        const stat = lstatSync(dest);
-        if (stat.isSymbolicLink()) unlinkSync(dest);
-        else rmSync(dest, { recursive: true, force: true });
-        removed.push(ref);
-      } catch {
-        removed.push(ref);
+      for (const dest of deployedPaths(
+        component,
+        name,
+        this.driverTarget,
+        this.global,
+        this.projectDir
+      )) {
+        try {
+          const stat = lstatSync(dest);
+          if (stat.isSymbolicLink()) unlinkSync(dest);
+          else rmSync(dest, { recursive: true, force: true });
+        } catch {
+        }
       }
+      removed.push(ref);
     }
     return removed;
   }
@@ -2613,15 +3753,44 @@ var AssetManager = class {
       return;
     }
     const raw = parse(readFileSync(configPath, "utf8")) ?? {};
-    if (!raw.dependencies) raw.dependencies = [];
-    if (!raw.dependencies.includes(ref)) {
-      raw.dependencies.push(ref);
-      writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
+    if (!Array.isArray(raw.dependencies)) raw.dependencies = [];
+    const deps = raw.dependencies;
+    if (deps.includes(ref) && deps.filter((d) => this.sameDeclaredAsset(d, ref)).length === 1) {
+      return;
+    }
+    const next = [];
+    let placed = false;
+    for (const dep of deps) {
+      if (!this.sameDeclaredAsset(dep, ref)) {
+        next.push(dep);
+      } else if (!placed) {
+        next.push(ref);
+        placed = true;
+      }
     }
+    if (!placed) next.push(ref);
+    raw.dependencies = next;
+    writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
+  }
+  /**
+   * Whether the declared `dep` names the same asset (kind, publisher, name) as
+   * `ref`, ignoring the version pin. A publisher must agree on both sides —
+   * unlike {@link removeDependencyFromConfig}, a bare `kind:name` never replaces a
+   * publisher-qualified line. Unparseable entries only match on string equality.
+   */
+  sameDeclaredAsset(dep, ref) {
+    if (typeof dep !== "string") return false;
+    if (dep === ref) return true;
+    const a = parseAssetRefLoose(dep);
+    const b = parseAssetRefLoose(ref);
+    if (!a || !b) return false;
+    return a.kind === b.kind && a.name === b.name && a.publisher?.replace(/^@/, "") === b.publisher?.replace(/^@/, "");
   }
   /**
    * Remove a dependency ref from the manifest `dependencies:`. Targets the same
    * file as {@link addDependencyToConfig} (`~/.skaile/skaile.yaml` in global mode).
+   *
+   * @returns `true` when a declaration was removed.
    */
   removeDependencyFromConfig(target) {
     const configPath = join(this.stateRoot, "skaile.yaml");
@@ -2629,15 +3798,15 @@ var AssetManager = class {
     const raw = parse(readFileSync(configPath, "utf8")) ?? {};
     if (!Array.isArray(raw.dependencies)) return false;
     const wantPub = target.publisher?.replace(/^@/, "");
-    const idx = raw.dependencies.findIndex((dep) => {
-      if (typeof dep !== "string") return false;
+    const before = raw.dependencies.length;
+    raw.dependencies = raw.dependencies.filter((dep) => {
+      if (typeof dep !== "string") return true;
       const p = parseAssetRefLoose(dep);
-      if (!p || p.kind !== target.kind || p.name !== target.name) return false;
+      if (!p || p.kind !== target.kind || p.name !== target.name) return true;
       const havePub = p.publisher?.replace(/^@/, "");
-      return wantPub === void 0 || havePub === void 0 || havePub === wantPub;
+      return !(wantPub === void 0 || havePub === void 0 || havePub === wantPub);
     });
-    if (idx === -1) return false;
-    raw.dependencies.splice(idx, 1);
+    if (raw.dependencies.length === before) return false;
     writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
     return true;
   }
@@ -2659,5 +3828,5 @@ var AssetManager = class {
 };
 
 export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-PTO2YDDG.js.map
-//# sourceMappingURL=chunk-PTO2YDDG.js.map
+//# sourceMappingURL=chunk-H7QUDDKH.js.map
+//# sourceMappingURL=chunk-H7QUDDKH.js.map