@iseoane/agent-depot 0.6.9 → 0.6.11

package/dist/src/profile-export.js

@@ -2,7 +2,7 @@ import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { loadAppOwnedSkillFilter } from "./app-owned-skills.js";
 import { sourceIdForUrl } from "./git-source.js";
-import { bundleRoot, describeCoordinates } from "./package-model.js";
+import { bundleRoot, describeBundleInSource, describeCoordinates } from "./package-model.js";
 import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
 import { parseProfile, PROFILE_FORMAT, PROFILE_FORMAT_V2, serializeProfile } from "./profile.js";
 import { formatVersionPolicy } from "./skill-install.js";
@@ -33,7 +33,7 @@ export function packageFilterNames(selection) {
 }
 /** One Package line, shared by the export preview and the import plan label. */
 export function describeProfilePackage(selection) {
-    return `Package ${describeCoordinates(selection)} from ${profileSourceIdentity(selection.source)} (${formatVersionPolicy(selection.version)}; saved selection)`;
+    return `Package ${describeBundleInSource(selection)} from ${profileSourceIdentity(selection.source)} (${formatVersionPolicy(selection.version)}; saved selection)`;
 }
 export function describeProfileSkill(skill) {
     return `Skill ${skill.path} from ${profileSourceIdentity(skill.source)} (${skill.version.policy})`;
@@ -42,10 +42,10 @@ export function describeProfileReplica(replica) {
     switch (replica.kind) {
         case "skill": return `Installed Skill ${replica.path} from ${profileSourceIdentity(replica.source)}`;
         case "app": return `Installed App ${replica.name} (${replica.platform ?? "all platforms"})`;
-        case "package": return `Installed Package ${describeCoordinates(replica.selection)} from ${profileSourceIdentity(replica.selection.source)}`;
+        case "package": return `Installed Package ${describeBundleInSource(replica.selection)} from ${profileSourceIdentity(replica.selection.source)}`;
     }
 }
-function profileSourceIdentity(source) {
+export function profileSourceIdentity(source) {
     if (source.kind === "builtin")
         return "Agent Depot (built-in Source)";
     if ("url" in source)

package/dist/src/profile-import.js

@@ -4,8 +4,8 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { compareAppVersions } from "./app-version.js";
 import { canonicalizeGitSourceUrl, sourceIdForUrl } from "./git-source.js";
-import { selectionKey } from "./package-model.js";
-import { describeProfilePackage, describeProfileReplica, packageFilterNames, selectProfileItems } from "./profile-export.js";
+import { describeBundleInSource, selectionKey } from "./package-model.js";
+import { describeProfilePackage, describeProfileReplica, packageFilterNames, profileSourceIdentity, selectProfileItems } from "./profile-export.js";
 import { parseProfile, PROFILE_FORMAT } from "./profile.js";
 import { AGENT_DEPOT_PACKAGE_VERSION } from "./project-manifest.js";
 import { defaultProjectSkillTreeAccess, executeSingleInstall, formatVersionPolicy, outputSingleInstallPreview, planSingleInstall } from "./skill-install.js";
@@ -30,16 +30,55 @@ function skillChoices(skill) {
 function recipeIdentity(recipe) {
     return canonical([recipe.name, recipe.platform]);
 }
-function fieldDifferences(existing, incoming) {
+function fieldChanges(existing, incoming) {
     const left = new Map(Object.entries(existing)), right = new Map(Object.entries(incoming));
-    return [...new Set([...left.keys(), ...right.keys()])].sort().flatMap(key => canonical(left.get(key)) === canonical(right.get(key)) ? []
-        : [`${key}: existing ${canonical(left.get(key))} -> incoming ${canonical(right.get(key))}`]);
+    return [...new Set([...left.keys(), ...right.keys()])].sort().flatMap(key => canonical(left.get(key)) === canonical(right.get(key)) ? [] : [{ key, existing: left.get(key), incoming: right.get(key) }]);
+}
+function fieldDifferences(existing, incoming) {
+    return fieldChanges(existing, incoming).map(change => `${change.key}: existing ${canonical(change.existing)} -> incoming ${canonical(change.incoming)}`);
+}
+/** The Hosts the profile would add and the ones it lacks, instead of two raw arrays. */
+function hostChange(existing, incoming) {
+    const before = Array.isArray(existing) ? existing.map(String) : [], after = Array.isArray(incoming) ? incoming.map(String) : [];
+    const added = after.filter(host => !before.includes(host)), missing = before.filter(host => !after.includes(host));
+    return [added.length ? `would add ${added.join(", ")}` : "", missing.length ? `profile lacks ${missing.join(", ")}` : ""]
+        .filter(Boolean).join("; ");
+}
+function isVersionPolicy(value) {
+    if (typeof value !== "object" || value === null || !("policy" in value))
+        return false;
+    return value.policy === "latest" || (value.policy === "fixed" && "version" in value && typeof value.version === "string");
+}
+function shortReason(existing, incoming) {
+    return fieldChanges(existing, incoming).map(change => {
+        if (change.key === "hosts")
+            return `hosts: ${hostChange(change.existing, change.incoming)}`;
+        if (change.key === "version") {
+            return isVersionPolicy(change.existing) && isVersionPolicy(change.incoming)
+                ? `version: existing ${formatVersionPolicy(change.existing)}, profile ${formatVersionPolicy(change.incoming)}` : "version differs";
+        }
+        return `${change.key} differ`;
+    }).join("; ");
 }
 function comparison(existing, incoming) {
     if (existing === undefined)
         return { status: "add" };
     const differences = fieldDifferences(existing, incoming);
-    return differences.length ? { status: "conflict", difference: differences.join("; ") } : { status: "same" };
+    return differences.length
+        ? { status: "conflict", difference: differences.join("; "), reason: shortReason(existing, incoming) }
+        : { status: "same" };
+}
+/** The row text: the effect of importing an addition, or why an existing one is left alone. */
+function summarize(status, thing, addition, reason, note) {
+    if (status === "add")
+        return addition;
+    if (status === "same")
+        return `${thing} — already identical${note ? ` (${note})` : ""}`;
+    return `${thing} — ${reason}`;
+}
+/** Skills, Packages and Sources group under one key whichever way their URL was written. */
+function groupOf(source) {
+    return "url" in source ? canonicalizeGitSourceUrl(source.url) : profileSourceIdentity(source);
 }
 async function loadImportRecipes(apps) {
     const entries = await apps.load();
@@ -69,29 +108,58 @@ async function loadImportRecipes(apps) {
 }
 function classifySource(value, sources) {
     const exists = sources.some(source => source.kind === "git" && canonicalizeGitSourceUrl(source.url) === value.url);
-    return { block: "sources", value, label: `Source ${value.url} (included: ${value.included})`, status: exists ? "same" : "add",
+    const status = exists ? "same" : "add";
+    const note = exists && !value.included ? "discovery inclusion is not imported" : undefined;
+    return { block: "sources", value, label: `Source ${value.url} (included: ${value.included})`, status, group: canonicalizeGitSourceUrl(value.url),
+        summary: summarize(status, `Source ${value.url}`, `Add Source ${value.url}`, undefined, note),
         ...(exists && !value.included ? { difference: "included: existing true -> incoming false (discovery inclusion is not imported)" } : {}) };
 }
-function classifySkill(value, skills) {
+/** A Skill shows its name; `showPath` marks a name two Skills of one Source share, `showSource` one that several Sources share. */
+function classifySkill(value, skills, { showPath = false, showSource = false } = {}) {
     const existing = skills.find(skill => skillIdentity(skill) === skillIdentity(value));
-    return { block: "skills", value, label: `Skill ${value.path}`, ...comparison(existing && skillChoices(existing), skillChoices(value)) };
+    const result = comparison(existing && skillChoices(existing), skillChoices(value));
+    const name = `Skill ${showPath ? value.path : path.posix.basename(value.path)}`;
+    // An addition sits under its Source header; the flat Unchanged and Conflicts sections have no such context.
+    const thing = showSource && result.status !== "add" ? `${name} from ${groupOf(value.source)}` : name;
+    return { block: "skills", value, label: `Skill ${value.path}`, group: groupOf(value.source), ...result,
+        summary: summarize(result.status, thing, `Add ${thing}`, "reason" in result ? result.reason : undefined) };
 }
 /** Identity is the Source and coordinates; only the version policy is a portable choice. */
 function classifyPackage(value, recorded) {
     const existing = recorded.find(record => selectionKey(record.selection) === selectionKey(value));
-    return { block: "packages", value, label: describeProfilePackage(value),
-        ...comparison(existing === undefined ? undefined : { version: existing.selection.version }, { version: value.version }) };
+    const result = comparison(existing === undefined ? undefined : { version: existing.selection.version }, { version: value.version });
+    const thing = `Package ${describeBundleInSource(value)} from ${profileSourceIdentity(value.source)} (${formatVersionPolicy(value.version)})`;
+    return { block: "packages", value, label: describeProfilePackage(value), group: groupOf(value.source), ...result,
+        summary: summarize(result.status, thing, `Select ${thing}`, "reason" in result ? result.reason : undefined) };
+}
+/** The plain reason for a conflict, otherwise the exact comparison. */
+function differenceText(item) {
+    return item.reason ?? item.difference ?? "";
+}
+/** Why a same-name recipe file blocks the import, naming the file and what differs. */
+function recipeConflictReason(existing, value) {
+    const files = existing.map(entry => path.basename(entry.file)).join(", ");
+    if (existing.some(entry => entry.error))
+        return `existing recipe ${files} is invalid but keeps this name`;
+    const keys = [...new Set(existing.flatMap(entry => fieldChanges(entry.content ?? {}, value).map(change => change.key)))];
+    return keys.length ? `existing recipe ${files} differs in ${keys.join(", ")}` : `existing recipe ${files} already has this name`;
 }
 function classifyRecipe(value, recipes) {
     const existing = recipes.filter(entry => entry.name === value.name &&
         (entry.platform === undefined || value.platform === undefined || entry.platform === value.platform));
+    const platform = value.platform ?? "all platforms";
+    // A recipe is written as a file on import; it is never approved and the App is never installed.
+    const label = `App recipe ${value.name} (${platform}; not approved, not installed)`;
+    const thing = `App recipe ${value.name} (${platform})`;
+    const addition = `Add ${thing} — not approved, not installed`;
     if (existing.length === 1 && !existing[0].error &&
         existing[0].platform === value.platform &&
         fieldDifferences(existing[0].content ?? {}, value).length === 0) {
-        return { block: "apps", value, label: `App recipe ${value.name} (${value.platform ?? "all platforms"}; unapproved; Apps are not installed)`, status: "same" };
+        return { block: "apps", value, label, status: "same", summary: summarize("same", thing, addition) };
     }
-    return { block: "apps", value, label: `App recipe ${value.name} (${value.platform ?? "all platforms"}; unapproved; Apps are not installed)`,
-        status: existing.length ? "conflict" : "add",
+    const reason = existing.length ? recipeConflictReason(existing, value) : undefined;
+    return { block: "apps", value, label, summary: summarize(existing.length ? "conflict" : "add", thing, addition, reason),
+        status: existing.length ? "conflict" : "add", ...(reason === undefined ? {} : { reason }),
         ...(existing.length ? { difference: existing.map(entry => `${entry.file}: name ${JSON.stringify(value.name)} already present with overlapping platforms; ${fieldDifferences(entry.content ?? {}, value).join("; ") || "content identical"}`).join("; ") } : {}) };
 }
 /** An external Source that no plan item registers is fetched but never added to Sources. */
@@ -141,8 +209,14 @@ export async function buildProfileImport(input, operations, apps, filters = {},
     const items = [];
     for (const value of selectProfileItems(profile.sources, filters.sources, filters.noSources, source => [source.url, sourceIdForUrl(source.url)], "sources"))
         items.push(classifySource(value, sources));
-    for (const value of selectProfileItems(profile.skills, filters.skills, filters.noSkills, skill => [skill.path, path.posix.basename(skill.path)], "skills"))
-        items.push(classifySkill(value, skills));
+    const chosenSkills = selectProfileItems(profile.skills, filters.skills, filters.noSkills, skill => [skill.path, path.posix.basename(skill.path)], "skills");
+    const baseName = (skill) => path.posix.basename(skill.path);
+    const nameOf = (skill) => `${groupOf(skill.source)}\n${baseName(skill)}`;
+    for (const value of chosenSkills) {
+        const sameName = chosenSkills.filter(other => baseName(other) === baseName(value));
+        items.push(classifySkill(value, skills, { showPath: sameName.filter(other => nameOf(other) === nameOf(value)).length > 1,
+            showSource: new Set(sameName.map(other => groupOf(other.source))).size > 1 }));
+    }
     for (const value of selectProfileItems(profile.apps, filters.apps, filters.noApps, recipe => [recipe.name], "apps")) {
         items.push(classifyRecipe(value, recipes));
     }
@@ -151,7 +225,8 @@ export async function buildProfileImport(input, operations, apps, filters = {},
     const preview = ["Preview: import portable user-global profile", ...entries.flatMap(item => {
             const status = item.block === "sources" && item.status === "same" && !item.value.included
                 ? "same (discovery inclusion is not imported)" : item.status;
-            const lines = [`${status}: ${item.label}${item.difference ? `; ${item.difference}` : ""}`];
+            const text = differenceText(item);
+            const lines = [`${status}: ${item.label}${text ? `; ${text}` : ""}`];
             if (item.block === "skills" && item.status === "add") {
                 const skill = item.value;
                 lines.push(`  Source ${canonical(skill.source)}`, `  hosts: ${skill.hosts.join(",")}; version policy: ${formatVersionPolicy(skill.version)}`);
@@ -218,7 +293,8 @@ export async function applyProfileImport(plan, operations, apps, confirmed, outp
                 classify ??= await loadImportClassifier(group.block, operations, apps, packageOperations);
                 const recheck = classify(item);
                 if (recheck.status !== "add") {
-                    results.push({ item, status: "skipped", detail: `${recheck.status}: ${recheck.label}${recheck.difference ? `; ${recheck.difference}` : ""}` });
+                    const text = differenceText(recheck);
+                    results.push({ item, status: "skipped", detail: `${recheck.status}: ${recheck.label}${text ? `; ${text}` : ""}` });
                     continue;
                 }
                 // Even a failing install method can persist state or change recipe files.

package/dist/src/project-installation.js

@@ -1,6 +1,7 @@
 import { chmod, lstat, mkdir, readFile, readlink, readdir, rename, rmdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { HOST_PROJECT_DIRECTORIES } from "./project-manifest.js";
 import { compareSkillTrees, readExistingSkillTree } from "./skill-adoption.js";
 import { pathsOverlap } from "./path-safety.js";
 import { parseSkillFrontmatter, skillTreeBaseline } from "./skill-discovery.js";
@@ -1433,7 +1434,7 @@ function isPortableV1Tree(files) {
     return files.every((file) => !portableV1ExcludedDirectory(file.relativePath));
 }
 function portableV1ExcludedDirectory(relativePath) {
-    const excludedTopLevelDirectories = new Set([".claude", ".codex", ".opencode", ".pi", "extensions", "plugins", "mcp"]);
+    const excludedTopLevelDirectories = new Set([...Object.values(HOST_PROJECT_DIRECTORIES), "extensions", "plugins", "mcp"]);
     const firstSegment = relativePath.split("/", 1)[0];
     return excludedTopLevelDirectories.has(firstSegment ?? "");
 }

package/dist/src/project-manifest.js

@@ -10,6 +10,13 @@ export const AGENT_DEPOT_PACKAGE_VERSION = readAgentDepotPackageVersion();
 /** The published package name, read from package.json so it is never hard-coded twice. */
 export const AGENT_DEPOT_PACKAGE_NAME = readAgentDepotPackageField("name");
 export const PROJECT_HOSTS = Object.freeze(["pi", "claude", "codex", "opencode"]);
+/** Where each Host keeps project-level configuration, relative to the project root. */
+export const HOST_PROJECT_DIRECTORIES = Object.freeze({
+    pi: ".pi",
+    claude: ".claude",
+    codex: ".codex",
+    opencode: ".opencode",
+});
 const EMPTY_PROJECT_MANIFEST = Object.freeze({
     version: PROJECT_MANIFEST_VERSION,
     skills: Object.freeze([]),

package/dist/src/project-target.js

@@ -0,0 +1,58 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { assertNoSymlinkPath, SymlinkPathError } from "./path-safety.js";
+import { HOST_PROJECT_DIRECTORIES } from "./project-manifest.js";
+import { CliUsageError } from "./usage-error.js";
+/** `.agents` is the canonical Skill location the Hosts share, so it also marks a project that already uses Skills. */
+const PROJECT_DIRECTORIES = [".agents", ...Object.values(HOST_PROJECT_DIRECTORIES)];
+/** The warnings are advisory, so an entry that cannot be read counts as absent. */
+async function exists(candidate) {
+    return stat(candidate).then(() => true, () => false);
+}
+/**
+ * Nearest ancestor-or-self holding a `.git` entry. A file marks a linked
+ * worktree or submodule, so any `.git` entry counts. Walking the filesystem
+ * avoids spawning `git` and cannot reach the network.
+ */
+async function findGitTopLevel(start) {
+    for (let current = start;; current = path.dirname(current)) {
+        if (await exists(path.join(current, ".git")))
+            return current;
+        if (path.dirname(current) === current)
+            return undefined;
+    }
+}
+/**
+ * The lines every project-scope preview starts with: the project root the
+ * Skills are installed into, then non-blocking warnings about a root that is
+ * probably not the intended one. A brand-new project is legitimate, so nothing
+ * here refuses.
+ */
+export async function describeProjectTarget(projectRoot, manifestPath) {
+    const lines = [`Project: ${projectRoot}`];
+    const gitTopLevel = await findGitTopLevel(projectRoot);
+    if (gitTopLevel !== undefined && path.relative(gitTopLevel, projectRoot) !== "") {
+        lines.push(`  WARNING: this directory is inside the Git repository at ${gitTopLevel} but is not its top level; Skills will be installed here, not at the repository root`);
+    }
+    const markers = [manifestPath, ...PROJECT_DIRECTORIES.map((directory) => path.join(projectRoot, directory))];
+    if (!(await Promise.all(markers.map(exists))).some(Boolean)) {
+        lines.push(`  WARNING: this directory has no project manifest (${path.basename(manifestPath)}) and none of ${PROJECT_DIRECTORIES.join(", ")}; confirm it is the intended project directory`);
+    }
+    return lines;
+}
+/** Resolves a `--project` value against the working directory; it must be an existing directory without symbolic links. */
+export async function resolveProjectRootOption(value) {
+    const root = path.resolve(value);
+    const information = await stat(root).catch((error) => {
+        if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            throw new CliUsageError(`--project ${JSON.stringify(value)} does not exist`);
+        }
+        throw error;
+    });
+    if (!information.isDirectory())
+        throw new CliUsageError(`--project ${JSON.stringify(value)} is not a directory`);
+    await assertNoSymlinkPath(root, `--project ${JSON.stringify(value)}`).catch((error) => {
+        throw error instanceof SymlinkPathError ? new CliUsageError(error.message) : error;
+    });
+    return root;
+}

package/dist/src/skill-discovery.js

@@ -13,6 +13,21 @@ export const EXCLUDED_LIFECYCLE_SEGMENTS = Object.freeze([
     "retired",
 ]);
 const excludedLifecycleSegments = new Set(EXCLUDED_LIFECYCLE_SEGMENTS);
+/**
+ * Directories where other coding agents keep generated copies of a Source's
+ * Skills. Agent Depot manages Claude, Codex, Pi and OpenCode only, so a Skill
+ * found below one of these is a mirror of the real one, never a candidate.
+ * `.claude`, `.agents`, `.codex`, `.pi` and `.opencode` are deliberately absent.
+ */
+const UNMANAGED_HOST_MIRROR_SEGMENTS = Object.freeze([
+    ".cursor", "cursor-plugin", ".windsurf", ".gemini", ".github", ".kiro", ".trae", ".trae-cn", ".devin", ".dsh",
+    ".hermes", ".veto", ".cline", ".roo", ".continue", ".augment", ".goose", ".amazonq", ".junie", ".kilocode",
+    ".qwen", ".agent", ".factory", ".crush", ".openhands", ".codebuddy", ".qoder", ".zed",
+]);
+/** Test and fixture trees hold sample Skills; only ancestors count, so a Skill directory may be named `test`. */
+const TEST_TREE_SEGMENTS = Object.freeze(["tests", "test", "__tests__", "fixtures", "__fixtures__"]);
+const unmanagedMirrorSegments = new Set(UNMANAGED_HOST_MIRROR_SEGMENTS);
+const testTreeSegments = new Set(TEST_TREE_SEGMENTS);
 /**
  * The package-owned root used for built-in skills. A missing root is an empty
  * built-in Source, which lets packages ship no built-in skills yet.
@@ -121,6 +136,7 @@ export function skillTreeBaseline(files) {
 export async function discoverSkillsFromSources(sources, contentAccess) {
     const candidates = [];
     for (const source of sources) {
+        const found = [];
         const files = [...await contentAccess.readSnapshot(source)].sort((left, right) => left.path.localeCompare(right.path));
         for (const file of files) {
             const normalizedPath = normalizeSourcePath(file.path);
@@ -129,23 +145,87 @@ export async function discoverSkillsFromSources(sources, contentAccess) {
             }
             const directoryPath = path.posix.dirname(normalizedPath);
             const segments = directoryPath === "." ? [] : directoryPath.split("/");
-            if (segments.some((segment) => excludedLifecycleSegments.has(segment))) {
+            if (segments.some((segment) => excludedLifecycleSegments.has(segment) || unmanagedMirrorSegments.has(segment))
+                || segments.slice(0, -1).some((segment) => testTreeSegments.has(segment))) {
                 continue;
             }
             const metadata = parseSkillFrontmatter(file.content);
             if (!metadata) {
                 continue;
             }
-            candidates.push({
-                sourceId: source.id,
-                path: directoryPath,
-                name: metadata.name,
-                description: metadata.description,
+            found.push({
+                candidate: { sourceId: source.id, path: directoryPath, name: metadata.name, description: metadata.description },
+                digest: createHash("sha256").update(file.content, "utf8").digest("hex"),
             });
         }
+        candidates.push(...await collapseIdenticalSkills(source, found, files, contentAccess));
     }
     return Object.freeze(candidates);
 }
+/**
+ * One candidate per Skill name and whole-directory digest within a Source,
+ * because a repository often repeats the same Skill under several directories.
+ * Only candidates already sharing a name and SKILL.md digest are compared by
+ * their full tree. The canonical copy is the one outside dot-directories, then
+ * the shallowest, then the first by path, so the choice never depends on
+ * snapshot order. Same-named Skills with different content all stay. Survivors
+ * keep their path order.
+ */
+async function collapseIdenticalSkills(source, found, snapshot, contentAccess) {
+    const sameManifest = new Map();
+    for (const { candidate, digest } of found) {
+        const key = `${candidate.name}|${digest}`;
+        sameManifest.set(key, (sameManifest.get(key) ?? 0) + 1);
+    }
+    const best = new Map();
+    for (const { candidate, digest } of found) {
+        const manifestKey = `${candidate.name}|${digest}`;
+        const key = sameManifest.get(manifestKey) > 1
+            ? `${manifestKey}|${await skillDirectoryDigest(source, candidate.path, snapshot, contentAccess)}`
+            : manifestKey;
+        const current = best.get(key);
+        if (current === undefined || compareCanonical(candidate.path, current.path) < 0) {
+            best.set(key, candidate);
+        }
+    }
+    const survivors = new Set(best.values());
+    return found.filter(({ candidate }) => survivors.has(candidate)).map(({ candidate }) => candidate);
+}
+/**
+ * Digest of every file of a Skill directory, by relative path and bytes. Reads
+ * the whole tree from the Source when the access supports it, otherwise uses the
+ * snapshot files. A tree that cannot be read digests to its own path, so it is
+ * never collapsed into another.
+ */
+async function skillDirectoryDigest(source, directory, snapshot, contentAccess) {
+    const prefix = `${directory}/`;
+    try {
+        const files = contentAccess.readSkillTree
+            ? [...await contentAccess.readSkillTree(source, directory)]
+            : snapshot.filter((file) => file.path.startsWith(prefix)).map((file) => ({
+                path: file.path,
+                content: Buffer.from(file.content, "utf8"),
+                executable: false,
+            }));
+        return skillTreeBaseline(files.map((file) => ({ ...file, path: file.path.startsWith(prefix) ? file.path.slice(prefix.length) : file.path }))).digest;
+    }
+    catch {
+        return `unreadable:${directory}`;
+    }
+}
+function compareCanonical(left, right) {
+    const rank = (candidate) => {
+        const segments = candidate.split("/");
+        return [segments.some((segment) => segment.startsWith(".")) ? 1 : 0, segments.length];
+    };
+    const [leftHidden, leftDepth] = rank(left);
+    const [rightHidden, rightDepth] = rank(right);
+    if (leftHidden !== rightHidden)
+        return leftHidden - rightHidden;
+    if (leftDepth !== rightDepth)
+        return leftDepth - rightDepth;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
 /** Collects scalar frontmatter values up to the closing delimiter; undefined when malformed or unclosed. */
 function readFrontmatterValues(lines) {
     const values = new Map();

package/dist/src/skill-install.js

@@ -2,8 +2,9 @@ import path from "node:path";
 import { assertSkillNotAppOwned } from "./app-owned-skills.js";
 import { assertSkillNotPackageOwned, loadPackageOwnedSkillFilter, } from "./package-owned-skills.js";
 import { pathsOverlap } from "./path-safety.js";
+import { describeProjectTarget } from "./project-target.js";
 import { inspectProjectSkillInstallation, installProjectSkillTransaction, validateProjectSkillInstallationPreview, } from "./project-installation.js";
-import { AGENT_DEPOT_PACKAGE_VERSION, parseProjectManifest, } from "./project-manifest.js";
+import { AGENT_DEPOT_PACKAGE_VERSION, defaultProjectManifestPath, parseProjectManifest, } from "./project-manifest.js";
 import { createSourceContentAccess } from "./skill-discovery.js";
 import { relativeProjectPath, selectionWithInstallation } from "./skill-update.js";
 import { executeSourceInstallationMethod, parseSourceInstallationMethod, resolveProjectSource, SourceNotFoundError, } from "./sources.js";
@@ -12,7 +13,7 @@ import { CliUsageError } from "./usage-error.js";
  * Shared install flow for one Skill selection (project or user-global):
  * resolve, inspect, preview, then execute. Used by the CLI and the TUI.
  */
-const INSTALL_USAGE = "Usage: agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--overwrite --yes] [--confirm-additional-host]";
+const INSTALL_USAGE = "Usage: agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--overwrite --yes] [--confirm-additional-host] [--project <path>]";
 export async function selectInstallSource(options, operations) {
     const source = await findSource(operations, options.sourceId);
     const projectSource = projectSourceFromSource(source, options.ref, options.version);
@@ -314,12 +315,17 @@ export async function planSingleInstall(request, context) {
     }
     const { resolvedSource, resolved, installationInspection } = await resolveInstallInspection(selection, source, projectSource, context.root, request, context.operations, context.environment, context.sourceAccess);
     await assertInstallNotAppOwned(request, context, installationInspection);
-    await assertInstallNotPackageOwned(selection, resolvedSource, context);
-    return { request, context, selection, source, resolvedSource, resolved, inspection: installationInspection };
+    await assertInstallNotPackageOwned(request, selection, resolvedSource, context);
+    const projectTarget = request.scope === "project"
+        ? await describeProjectTarget(context.root, context.manifestPath ?? defaultProjectManifestPath(context.root))
+        : [];
+    return { request, context, selection, source, resolvedSource, resolved, inspection: installationInspection, projectTarget };
 }
 /** Prints the preview the user confirms before {@link executeSingleInstall}. */
 export function outputSingleInstallPreview(plan, output) {
-    const { request, context, selection, source, resolved, inspection } = plan;
+    const { request, context, selection, source, resolved, inspection, projectTarget } = plan;
+    for (const line of projectTarget)
+        output(line);
     outputInstallPreview(selection, source, context.root, output, resolved.files, resolved.method, request.scope, inspection, request.overwrite, request.confirmed);
 }
 /**
@@ -329,7 +335,7 @@ export function outputSingleInstallPreview(plan, output) {
 export async function executeSingleInstall(plan, persist, output) {
     const { request, context, selection, resolvedSource, resolved, inspection } = plan;
     await assertInstallNotAppOwned(request, context, inspection);
-    await assertInstallNotPackageOwned(selection, resolvedSource, context);
+    await assertInstallNotPackageOwned(request, selection, resolvedSource, context);
     const protectedPaths = assertNoManagedInstallationOverlap(context.existing, selection, inspection, context.root, request.overwrite);
     rejectInstallationCollision(inspection, request.overwrite);
     const transaction = await installOne(selection, resolvedSource, context.sourceAccess, context.root, context.environment, resolved.method, request.portableV1, resolved.files, resolved.resolvedVersion, request.confirmAdditionalHostExposure, request.overwrite, inspection, protectedPaths);
@@ -375,8 +381,14 @@ async function assertInstallNotAppOwned(request, context, inspection) {
         await assertSkillNotAppOwned(path.basename(location.path), { ...context.environment, homeDirectory: context.root });
     }
 }
-/** Reloads bundle ownership from the selected Source and refuses its own Skill paths. */
-async function assertInstallNotPackageOwned(selection, source, context) {
+/**
+ * Reloads bundle ownership from the selected Source and refuses its own Skill paths.
+ * Package state lives under the user's home, so a project install has nothing to
+ * check and must not read or lock state derived from the project root.
+ */
+async function assertInstallNotPackageOwned(request, selection, source, context) {
+    if (request.scope !== "user-global")
+        return;
     const owned = await loadPackageOwnedSkillFilter({
         sources: [source],
         homeDirectory: context.root,

package/dist/src/tui/app-actions.js

@@ -5,7 +5,10 @@ import { errorText, runBatch } from "./batch.js";
 import { hostChecklistKey, movePreviewCursor } from "./mode-keys.js";
 import { BorderPanel, HostChecklist, PreviewConfirm, Working } from "./panel-parts.js";
 import { previewViewport } from "./preview-window.js";
+import { theme } from "./theme.js";
 import { operationStart } from "./working-model.js";
+/** Finished items shown under a running batch; older ones are counted. */
+const MAX_DONE_LINES = 3;
 export const APP_KINDS = ["app-busy", "app-approve", "app-hosts", "app-confirm", "app-manual"];
 /** Narrows the view's mode without asserting a partial mode is an App mode. */
 export function isAppMode(mode) {
@@ -61,15 +64,21 @@ function appPreviewLines(mode) {
     ];
 }
 /** The busy mode of an App step; `previous` is the busy mode this step continues, so the clock keeps running. */
-function appBusy(label, previous) {
-    return { kind: "app-busy", label, startedAt: operationStart(previous) };
+function appBusy(label, previous, done) {
+    return { kind: "app-busy", label, startedAt: operationStart(previous), ...(done?.length ? { done } : {}) };
+}
+/** `Running App step: name (2/5)…`; the position is left out for a batch of one. */
+function stepLabel(verb, entry, finished, total) {
+    return `${verb} App step: ${appName(entry)}${total > 1 ? ` (${finished + 1}/${total})` : ""}…`;
 }
 async function prepareNext(context, requests, results = [], failures = 0, previous) {
     const { manage, apps } = context;
-    const running = appBusy("Preparing App step…", previous);
-    manage.setMode(running);
     // Independent planning failures never stop the remaining marked Apps.
     const [request, ...remaining] = requests;
+    const running = appBusy(request ? stepLabel("Preparing", request.entry, results.length, results.length + requests.length) : "Finishing App steps…", previous, 
+    // Once the batch is over its results are the Result panel, not a busy line.
+    request ? results : undefined);
+    manage.setMode(running);
     if (!request) {
         await manage.finish({ kind: failures > 0 ? "error" : "ok", text: results.join("\n") });
         return;
@@ -124,7 +133,7 @@ export async function startAppAction(context, entries, input) {
 }
 async function execute(context, mode) {
     const { manage, apps } = context;
-    const running = appBusy("Running App step…");
+    const running = appBusy(stepLabel("Running", mode.plan.entry, mode.results.length, mode.results.length + 1 + mode.remaining.length), undefined, mode.results);
     manage.setMode(running);
     let manualRequired = false;
     const [outcome] = await runBatch([mode.plan], async (plan) => {
@@ -201,8 +210,10 @@ export function handleAppKey(context, mode, input, key) {
 /** Renders App prompts using the existing checklist and preview-confirm panels. */
 export function AppPanel({ mode }) {
     const { rows, columns } = useWindowSize();
-    if (mode.kind === "app-busy")
-        return _jsx(BorderPanel, { title: "App lifecycle", children: _jsx(Working, { label: mode.label, since: mode.startedAt }) });
+    if (mode.kind === "app-busy") {
+        const done = mode.done ?? [];
+        return (_jsxs(BorderPanel, { title: "App lifecycle", children: [_jsx(Working, { label: mode.label, since: mode.startedAt }), done.length > MAX_DONE_LINES ? _jsxs(Text, { color: theme.muted, children: [done.length - MAX_DONE_LINES, " earlier finished"] }) : null, done.slice(-MAX_DONE_LINES).map((line, index) => _jsx(Text, { color: theme.muted, children: line }, index))] }));
+    }
     if (mode.kind === "app-hosts") {
         return (_jsxs(BorderPanel, { title: "App Host steps", children: [_jsx(Text, { children: "Checked = setup. Unchecked = teardown. Wiring is not tracked." }), _jsxs(Text, { children: ["Space/1-", mode.choices.length, " toggle \u00B7 j/k move \u00B7 Enter continue \u00B7 Esc cancel"] }), _jsx(HostChecklist, { choices: mode.choices, cursor: mode.cursor, selected: mode.selected })] }));
     }

package/dist/src/tui/app.js

@@ -10,6 +10,7 @@ import { ProfileView } from "./profile-view.js";
 import { SourcesView, sourceRowHints } from "./sources-view.js";
 import { theme } from "./theme.js";
 import { UpdatesView } from "./updates-view.js";
+import { createViewRetention, invalidateRetention } from "./view-retention.js";
 /** Sources derives its own hints from the selected row, so it is excluded here. */
 function hintsOf(view, catalogFocusedOnSource) {
     switch (view) {
@@ -20,7 +21,7 @@ function hintsOf(view, catalogFocusedOnSource) {
         case "profile":
             return "e export · i import · q quit";
         case "updates":
-            return "j/k move · space mark · a all · Enter preview · u update · r check again · q quit";
+            return "j/k move · space mark · a all · Enter expand · u update · r check again · q quit";
     }
 }
 export function Header({ view, columns }) {
@@ -33,14 +34,28 @@ export function App({ operations, environment, onExit }) {
     const [capturing, setCapturing] = useState(false);
     // Updated synchronously by the views so keys in the same burst never see a stale capturing state.
     const capturingRef = useRef(false);
+    const [view, setView] = useState("sources");
+    // Catalog and Installations unmount on a tab change; this keeps what they loaded, for display only.
+    const [retention] = useState(createViewRetention);
+    // Sources, Updates and Profile may change what the retained data describes. Any mode they capture
+    // keys for (add, refresh, approve, confirm, import) can, so leaving after one drops the retention.
+    const viewRef = useRef(view);
+    const touched = useRef(false);
     const onCapturingChange = useCallback((value) => {
         capturingRef.current = value;
+        if (value && viewRef.current !== "catalog" && viewRef.current !== "installations")
+            touched.current = true;
         setCapturing(value);
     }, []);
-    const [view, setView] = useState("sources");
     const [catalogSourceId, setCatalogSourceId] = useState();
     const [sourcesHints, setSourcesHints] = useState(sourceRowHints(undefined));
-    const showView = (next) => setView(next);
+    const showView = (next) => {
+        if (touched.current)
+            invalidateRetention(retention);
+        touched.current = false;
+        viewRef.current = next;
+        setView(next);
+    };
     useKeys((input, key) => {
         if (capturingRef.current)
             return;
@@ -66,8 +81,8 @@ export function App({ operations, environment, onExit }) {
     });
     return (_jsxs(Box, { flexDirection: "column", height: rows, children: [_jsx(Header, { view: view, columns: columns }), _jsx(Box, { flexDirection: "column", flexGrow: 1, children: view === "sources" ? (_jsx(SourcesView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange, onHintsChange: setSourcesHints, onOpenCatalog: (source) => {
                         setCatalogSourceId(source.id);
-                        setView("catalog");
-                    } })) : view === "installations" ? (_jsx(InstallationsView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange })) : view === "profile" ? (_jsx(ProfileView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange })) : view === "updates" ? (_jsx(UpdatesView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange })) : (_jsx(CatalogView, { operations: operations, sourceId: catalogSourceId, environment: environment, onCapturingChange: onCapturingChange })) }), _jsx(Text, { color: theme.muted, children: capturing
+                        showView("catalog");
+                    } })) : view === "installations" ? (_jsx(InstallationsView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange, retention: retention })) : view === "profile" ? (_jsx(ProfileView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange })) : view === "updates" ? (_jsx(UpdatesView, { operations: operations, environment: environment, onCapturingChange: onCapturingChange })) : (_jsx(CatalogView, { operations: operations, sourceId: catalogSourceId, environment: environment, onCapturingChange: onCapturingChange, retention: retention })) }), _jsx(Text, { color: theme.muted, children: capturing
                     ? columns < 64 ? "Enter submit · Esc cancel" : "Enter submit · Esc cancel · y/n confirm · space toggle"
                     : view === "sources" ? sourcesHints : hintsOf(view, catalogSourceId !== undefined) })] }));
 }

package/dist/src/tui/batch.js

@@ -3,9 +3,10 @@ export const errorText = (error) => (error instanceof Error ? error.message : St
  * Applies the items one after another. A failure is reported for that item and
  * the rest still run, so the outcomes always cover every item in order.
  */
-export async function runBatch(items, run, describeFailure) {
+export async function runBatch(items, run, describeFailure, onStart) {
     const outcomes = [];
     for (const item of items) {
+        onStart?.(item, outcomes.length + 1, items.length, outcomes);
         try {
             outcomes.push({ item, ok: true, line: await run(item) });
         }