@iseoane/agent-depot 0.6.9 → 0.6.10

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.10] - 2026-11-06
+
+### Changed
+
+- Project-scope `install` and `update` previews start with `Project: <absolute path>`,
+  in the CLI and the TUI, and warn without blocking when the directory is inside a Git
+  repository but not its top level, or has no manifest and no Host directory. The new
+  `--project <path>` option (also on `agent-depot tui`) selects the project directory
+  instead of the current one.
+- The Profile import list in the TUI is grouped: additions by Source (App recipes
+  in their own group), then Unchanged items (collapsed) and Conflicts. Rows say
+  what importing does (`Add Skill ask-matt`, `Select Package ...`) and a conflict
+  gives one short reason such as `hosts: would add codex, opencode` instead of raw
+  JSON. Selection, preview and confirmation are unchanged. The App recipe label
+  now says imported recipes are written but not approved and not installed.
+- `agent-depot import` preview and skipped-result conflict lines show the same
+  short reason instead of raw existing/incoming values, and version conflicts say
+  `existing` rather than `installed`. Unchanged and conflicting Skills whose name
+  appears in several Sources name their Source, and in the TUI Enter previews the
+  plan even when nothing is importable.
+
+### Fixed
+
+- A project-scope Skill install no longer reads or locks Package state derived from the
+  project directory, which created `.local/state/agent-depot` inside the project on Linux.
+- A recipe for another platform can be removed even when an App with the same
+  name is tracked on this machine; recipes that apply here keep their
+  protection.
+- In Sources, clashing App recipes show their own file names and the duplicate
+  error names the files to repair; a recipe that does not apply here shows its
+  platform before its status, and approved recipes read `✓ approved`.
+- On Windows, concurrent writes to the same state file (for example two App
+  approvals at once) no longer fail with `EPERM` on rename: the atomic write
+  retries briefly before giving up.
+
 ## [0.6.9] - 2026-11-04
 
 ### Fixed

package/README.md

@@ -342,6 +342,23 @@ the install method; update execution is not part of this lifecycle.
 
 ## Project installation
 
+Project scope acts on one project directory, the current directory unless you pass
+`--project <path>` (`install`, `update` and `tui`). The path must be an existing directory
+without symbolic links in it, and a relative path is resolved against the current
+directory. Every project-scope preview, in the CLI and the TUI, starts with
+`Project: <absolute path>`, so you can see where Skills will be written before
+confirming. Two non-blocking warnings follow it when the directory looks unintended:
+it is inside a Git repository but is not its top level (the warning names the top
+level), or it has no `agent-depot.json` and none of `.agents`, `.claude`, `.codex`,
+`.opencode` or `.pi`. A brand-new project still installs after the warning. Project
+removal does not exist, so this applies to install and update only.
+`agent-depot tui --project <path>` opens the TUI on that directory; a TUI batch
+install shows the project line and warnings once for the whole batch.
+
+```
+agent-depot install --scope project --project ../other-repo --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1
+```
+
 Project installation requires an explicit `--scope project`, Source ID, Skill
 path, one or more `--host` values (`pi`, `claude`, `codex`, or `opencode`), and
 a version policy (`--version latest` or `--version fixed:<value>`). External
@@ -554,8 +571,10 @@ the application supplies another start directory.
    to the Profile view.
 2. The selected file is parsed and previewed. If it is invalid or cannot be
    read, an inline error appears and the picker stays open so you can choose
-   another file. The import list marks entries as **add**, **same** (skipped), or
-   **conflict** (skipped with differences). Only additions can be selected. Use
+   another file. The import list is grouped: additions by Source (App recipes in
+   their own group), then **Unchanged** entries (collapsed, skipped) and
+   **Conflicts** (skipped, each with a one-line reason). Each row says what
+   importing does, and only additions can be selected. Use
    `space` to toggle a row, `a` to select all additions or clear them, and
    `Enter` to preview the selected additions. Press `Esc` to return to the
    Profile view.
@@ -576,6 +595,9 @@ If the App is installed or tracked, the TUI offers the existing uninstall flow;
 uninstall (or when not installed), a separate preview confirms deletion of only
 the recipe file or symlink. App data and Host configuration are not implicitly
 deleted. Invalid recipes must be repaired before their App state can be checked.
+A recipe for another platform stays removable even when an App with the same
+name is tracked here; only a recipe that applies here, or the exact recipe file the
+App was installed from, is protected by tracked state.
 
 Safety model:
 

package/dist/src/app-flow.js

@@ -52,11 +52,11 @@ export function createAppOperations(environment = {}) {
         const names = new Map();
         for (const entry of entries) {
             if (entry.applicable && entry.recipe) {
-                names.set(entry.recipe.name, (names.get(entry.recipe.name) ?? 0) + 1);
+                names.set(entry.recipe.name, [...(names.get(entry.recipe.name) ?? []), path.basename(entry.file)]);
             }
         }
-        return entries.map((entry) => (entry.applicable && entry.recipe && names.get(entry.recipe.name) > 1
-            ? { ...entry, error: `Duplicate applicable App name: ${entry.recipe.name}` }
+        return entries.map((entry) => (entry.applicable && entry.recipe && names.get(entry.recipe.name).length > 1
+            ? { ...entry, error: `Duplicate applicable App name: ${entry.recipe.name} (repair ${names.get(entry.recipe.name).join(", ")})` }
             : entry));
     }
     async function load(files) {

package/dist/src/app-recipe-removal.js

@@ -27,7 +27,9 @@ export async function planAppRecipeRemoval(apps, entry) {
         throw new Error(`Cannot verify App state: ${current.error ?? "invalid recipe"}. Repair the recipe before removing it.`);
     if (current.hash !== entry.hash || current.canonicalFile !== entry.canonicalFile)
         throw new Error("App recipe changed; review it again");
-    const tracked = (await apps.trackedApps()).find((record) => record.name === current.recipe.name);
+    // A recipe for another platform owns no installation here, so a same-named record counts only when it points at this very file.
+    const tracked = (await apps.trackedApps()).find((record) => record.name === current.recipe.name
+        && (current.applicable || record.recipeFile === current.canonicalFile));
     const inspection = await apps.inspect(current);
     if (inspection.status !== "installed" && inspection.status !== "not installed" && inspection.status !== "not applicable here") {
         throw new Error(`Cannot verify App state (${inspection.status}); approve the recipe before removing it`);

package/dist/src/atomic-file.js

@@ -1,12 +1,35 @@
 import { randomUUID } from "node:crypto";
 import { rename, unlink, writeFile } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+export const WINDOWS_RENAME_ATTEMPTS = 20;
+const WINDOWS_RENAME_RETRY_MS = 5;
+/**
+ * Windows reports EPERM, EACCES or EBUSY when a rename targets a file another rename or reader is
+ * still releasing, so concurrent writers to one destination must retry briefly instead of failing.
+ * The dependencies are injectable only so tests can force the Windows branch on any OS.
+ */
+export async function renameWithWindowsRetry(from, to, deps = { rename, platform: process.platform, delay }) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await deps.rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            const transient = deps.platform === "win32" && ["EPERM", "EACCES", "EBUSY"].includes(code ?? "");
+            if (!transient || attempt >= WINDOWS_RENAME_ATTEMPTS)
+                throw error;
+            await deps.delay(WINDOWS_RENAME_RETRY_MS * attempt);
+        }
+    }
+}
 /** Write a unique temporary sibling, then publish it with rename. */
 export async function writeFileAtomically(file, contents, options = {}) {
     const temporaryPath = `${file}.${process.pid}.${randomUUID()}.tmp`;
     try {
         await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: options.mode });
         try {
-            await rename(temporaryPath, file);
+            await renameWithWindowsRetry(temporaryPath, file);
         }
         catch (error) {
             const code = error.code;

package/dist/src/cli.js

@@ -21,6 +21,7 @@ import { describeUnmanagedRemoval, removeInspectedUnmanagedSkills } from "./unma
 import { executeHostAddition, executeHostRemoval, planHostAddition, planHostRemoval } from "./skill-hosts.js";
 import { executeSkillRemoval, inspectSkillRemovals, planSkillRemoval, describeSkillRemoval, recheckSkillRemoval, removeSkillFiles, removeSkillsAndRecords, assertManagedInstallationRecordsUnchanged, assertRemovalInspectionUnchanged, selectUserGlobalSkills, SkillSelectionError, userGlobalRemovalOptions, } from "./skill-removal.js";
 import { defaultProjectSkillTreeAccess, executeOrRejectMethod, executeSingleInstall, externalMethodFailure, isValidFixedVersion, findSource, installOne, outputInstallationResult, outputInstallPreview, outputSingleInstallPreview, planSingleInstall, refreshResolvedSource, rejectInstallationCollision, resolveSelection, rollbackTransactions, } from "./skill-install.js";
+import { describeProjectTarget, resolveProjectRootOption } from "./project-target.js";
 import { CliUsageError } from "./usage-error.js";
 import { createSelfUpdateOperations } from "./self-update.js";
 import { selectionWithInstallation } from "./skill-update.js";
@@ -34,10 +35,11 @@ const USAGE = [
     "  agent-depot source remove <id> [--skill <id|path>...] [--all] [--yes]",
     "  agent-depot source migrate <old-id> <new-id> (--skill <path>... | --all) [--yes]",
     "  agent-depot discover <source-id> [source-id...]",
-    "  agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--yes] [--confirm-additional-host]",
-    "  agent-depot install --scope project --manifest --portable-v1 [--yes] [--confirm-additional-host]",
-    "  agent-depot update check --scope <project|user-global> [--package <selection>...]",
-    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>... | --package <selection>...) [--yes] [--confirm-path <relative-path>...]",
+    "  agent-depot install --scope <project|user-global> --source <id> --skill <path> --host <host>... --version <latest|version> [--ref <git-ref>] [--method <json>] --portable-v1 [--yes] [--confirm-additional-host] [--project <path>]",
+    "  agent-depot install --scope project --manifest --portable-v1 [--yes] [--confirm-additional-host] [--project <path>]",
+    "  agent-depot update check --scope <project|user-global> [--package <selection>...] [--project <path>]",
+    "  agent-depot update apply --scope <project|user-global> (--all | --skill <id|path>... | --app <name>... | --package <selection>...) [--yes] [--confirm-path <relative-path>...] [--project <path>]",
+    "    --project <path> picks the project directory for --scope project (default: the current directory).",
     "    Apps and Packages run after Skills; --all --scope project skips Apps and Packages.",
     "  agent-depot self update [--yes] (npm global installations only; otherwise prints manual guidance)",
     "  agent-depot skill remove <id|path>... [--yes]",
@@ -57,14 +59,14 @@ const USAGE = [
     "  agent-depot package forget <selection> --host <host> --yes",
     `  ${EXPORT_USAGE}`,
     `  ${IMPORT_USAGE}`,
-    "  agent-depot tui",
+    "  agent-depot tui [--project <path>]",
     "  agent-depot --version",
     "",
     "Options for every command, anywhere on the line:",
     "  --verbose  stream the full child output (npm, pi, git, App commands) to stderr line by line as it runs,",
     "             instead of a spinner and the last few lines; stdout is unchanged.",
 ].join("\n");
-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>]";
 const DISCOVER_USAGE = "Usage: agent-depot discover <source-id> [source-id...]\nSelect at least one Source ID explicitly; run `agent-depot source list` to see registered Sources";
 const REMOVE_SOURCE_USAGE = "Usage: agent-depot source remove <id> [--skill <id|path>...] [--all] [--yes]";
 const MIGRATE_SOURCE_USAGE = "Usage: agent-depot source migrate <old-id> <new-id> (--skill <path>... | --all) [--yes]";
@@ -144,16 +146,17 @@ const COMMANDS = new Map([
             }
             return 0;
         }],
-    ["tui", async (_values, { operations, dependencies }) => {
+    ["tui", async (values, { operations, dependencies }) => {
             const isInteractive = dependencies.isInteractive ?? (() => process.stdin.isTTY === true);
             if (!isInteractive()) {
                 throw new Error("agent-depot tui requires an interactive terminal");
             }
+            const projectRoot = await parseTuiProjectRoot(values, dependencies);
             // Loaded lazily so non-interactive commands never import Ink/React.
             const renderTui = dependencies.renderTui ?? (await import("./tui/render.js")).renderTui;
             await renderTui(operations, {
                 homeDirectory: dependencies.homeDirectory,
-                projectRoot: dependencies.projectRoot,
+                projectRoot,
                 sourceAccess: dependencies.sourceAccess,
                 installationOptions: dependencies.installationOptions,
                 projectManifestStore: dependencies.projectManifestStore,
@@ -169,6 +172,14 @@ const COMMANDS = new Map([
             return 0;
         }],
 ]);
+/** `tui [--project <path>]`: the project directory the TUI acts on; also where its file browser opens. */
+async function parseTuiProjectRoot(values, dependencies) {
+    if (values.length === 0)
+        return dependencies.projectRoot;
+    if (values.length !== 2 || values[0] !== "--project")
+        throw new CliUsageError(USAGE);
+    return resolveProjectRootOption(requireOptionValue(values, 1, "--project"));
+}
 async function runSourceRefresh(values, { operations, output, progress }) {
     if (values.length < 1 || values.length > 2 || (values.length === 2 && values[1] !== "--yes")) {
         throw new CliUsageError("Usage: agent-depot source refresh <id> [--yes]");
@@ -816,6 +827,7 @@ async function runSelfUpdate(argv, dependencies, output, progress) {
 }
 async function runUpdate(argv, operations, dependencies, output, progress) {
     const options = parseUpdateOptions(argv);
+    const projectRoot = options.project === undefined ? dependencies.projectRoot : await resolveProjectRootOption(options.project);
     const apps = dependencies.appOperations ?? createAppOperations({ homeDirectory: dependencies.homeDirectory });
     const packages = packageOperationsFor(dependencies, operations);
     const requestedPackages = options.scope === "user-global" && options.requestedPackages.length > 0
@@ -847,7 +859,7 @@ async function runUpdate(argv, operations, dependencies, output, progress) {
             scope: options.scope,
             operations,
             ...(dependencies.homeDirectory === undefined ? {} : { homeDirectory: dependencies.homeDirectory }),
-            ...(dependencies.projectRoot === undefined ? {} : { projectRoot: dependencies.projectRoot }),
+            ...(projectRoot === undefined ? {} : { projectRoot }),
             ...(dependencies.sourceAccess === undefined ? {} : { sourceAccess: dependencies.sourceAccess }),
             ...(dependencies.projectManifestStore === undefined ? {} : { projectManifestStore: dependencies.projectManifestStore }),
             ...(dependencies.installationOptions?.fileSystem === undefined ? {} : { installationFileSystem: dependencies.installationOptions.fileSystem }),
@@ -857,7 +869,9 @@ async function runUpdate(argv, operations, dependencies, output, progress) {
         output(`Error (Skills, ${options.scope}): ${error instanceof Error ? error.message : String(error)}`);
     }
     if (loaded) {
-        const { assessment, installed, context } = loaded;
+        const { assessment, installed, context, projectTarget } = loaded;
+        for (const line of projectTarget)
+            output(line);
         const userGlobalInventory = options.action === "check" && options.scope === "user-global"
             ? await scanUserGlobalSkillInventory({ homeDirectory: context.projectRoot, managedInstallations: installed, reportWarning: output })
             : undefined;
@@ -874,7 +888,7 @@ async function runUpdate(argv, operations, dependencies, output, progress) {
     if (options.action === "check") {
         return appCheckFailed || packageCheckFailed ? 1 : 0;
     }
-    const { assessment, context } = loaded;
+    const { assessment, context, projectTarget } = loaded;
     const selectedApps = options.all ? appUpdates.filter(item => item.status === "update available")
         : options.requestedApps.map(name => {
             const matches = appUpdates.filter(item => item.entry.recipe?.name === name);
@@ -927,6 +941,10 @@ async function runUpdate(argv, operations, dependencies, output, progress) {
     const { plans, failures: previewFailures, nonCanonicalPaths } = selected.length === 0
         ? await previewUpdateCandidates(selected, context)
         : await progress.run("Previewing Skill updates", () => previewUpdateCandidates(selected, context));
+    // The assessment output above can be long, so the previews restate the target.
+    if (selected.length > 0)
+        for (const line of projectTarget)
+            output(line);
     // Successes and failures are reported in candidate order, as the preview runs.
     const failedIds = new Set(previewFailures.map(({ item }) => item.id));
     const plansById = new Map(plans.map((plan) => [plan.item.id, plan]));
@@ -1049,6 +1067,7 @@ function parseUpdateOptions(argv) {
         throw new CliUsageError(USAGE);
     }
     let scope;
+    let project;
     let all = false;
     let confirmed = false;
     const requested = [];
@@ -1060,6 +1079,9 @@ function parseUpdateOptions(argv) {
             case "--scope":
                 scope = requireOptionValue(argv, ++index, "--scope");
                 break;
+            case "--project":
+                project = requireOptionValue(argv, ++index, "--project");
+                break;
             case "--confirm-path":
                 confirmedPaths.push(normalizeConfirmedPath(requireOptionValue(argv, ++index, "--confirm-path")));
                 break;
@@ -1085,6 +1107,8 @@ function parseUpdateOptions(argv) {
     if (scope !== "project" && scope !== "user-global") {
         throw new CliUsageError("Update scope must be explicit: use --scope project or --scope user-global");
     }
+    if (project !== undefined && scope !== "project")
+        throw new CliUsageError("--project only applies to --scope project");
     if (action === "check" && (all || requested.length > 0 || requestedApps.length > 0 || confirmed || confirmedPaths.length > 0)) {
         throw new CliUsageError("update check only accepts --scope and optional --package filters; use update apply to select and apply updates");
     }
@@ -1111,6 +1135,7 @@ function parseUpdateOptions(argv) {
         requestedPackages: Object.freeze(requestedPackages),
         confirmed,
         confirmedPaths: Object.freeze(confirmedPaths),
+        ...(project === undefined ? {} : { project }),
     };
 }
 /** Normalizes a --confirm-path value like the relative path shown in the preview. */
@@ -1169,7 +1194,9 @@ async function runInstall(argv, operations, dependencies, output, progress) {
         await runUserGlobalInstall(options, operations, dependencies, sourceAccess, output, progress);
         return;
     }
-    const projectRoot = path.resolve(dependencies.projectRoot ?? process.cwd());
+    const projectRoot = options.project === undefined
+        ? path.resolve(dependencies.projectRoot ?? process.cwd())
+        : await resolveProjectRootOption(options.project);
     const manifestStore = dependencies.projectManifestStore ?? new ProjectManifestStore(defaultProjectManifestPath(projectRoot));
     const context = { options, operations, dependencies, sourceAccess, output, progress, projectRoot, manifestStore };
     if (options.fromManifest) {
@@ -1214,6 +1241,8 @@ async function runManifestInstall(context) {
     // Two different manifest selections can have different Source/path
     // identities while still resolving to the same basename directory.
     const inspections = await inspectManifestInstallations(resolved, projectRoot, sourceAccess, dependencies);
+    for (const line of await describeProjectTarget(projectRoot, manifestStore.path))
+        output(line);
     for (let index = 0; index < resolved.length; index += 1) {
         const item = resolved[index];
         outputInstallPreview(item.selection, item.source, projectRoot, output, item.files, item.method, "project", inspections[index], false, options.confirmed);
@@ -1269,7 +1298,7 @@ async function runSingleProjectInstall(context) {
     }
     const existing = await manifestStore.load();
     const request = { ...options, scope: "project", sourceId: options.sourceId, skillPath: options.skillPath, version: options.version };
-    const plan = await progress.run(`Resolving ${options.skillPath}`, () => planSingleInstall(request, { operations, sourceAccess, environment: dependencies, root: projectRoot, existing: existing.skills, recordedIn: manifestStore.path }), { mayPrompt: refreshesSource(options) });
+    const plan = await progress.run(`Resolving ${options.skillPath}`, () => planSingleInstall(request, { operations, sourceAccess, environment: dependencies, root: projectRoot, existing: existing.skills, recordedIn: manifestStore.path, manifestPath: manifestStore.path }), { mayPrompt: refreshesSource(options) });
     outputSingleInstallPreview(plan, output);
     requireConfirmation(options.confirmed, "Installation not confirmed; rerun with --yes to continue");
     await progress.run(`Installing ${options.skillPath}`, () => executeSingleInstall(plan, async (record) => {
@@ -1309,6 +1338,7 @@ function collectHosts(hosts, value) {
 }
 const INSTALL_VALUE_OPTIONS = new Map([
     ["--scope", (draft, value) => { draft.scope = value; }],
+    ["--project", (draft, value) => { draft.project = value; }],
     ["--source", (draft, value) => { draft.sourceId = value; }],
     ["--skill", (draft, value) => { draft.skillPath = value; }],
     ["--host", (draft, value) => { collectHosts(draft.hosts, value); }],
@@ -1353,6 +1383,9 @@ function finalizeInstallOptions(draft) {
     if (scope !== "project" && scope !== "user-global") {
         throw new CliUsageError("Installation scope must be explicit: use --scope project or --scope user-global");
     }
+    if (draft.project !== undefined && scope !== "project") {
+        throw new CliUsageError("--project only applies to --scope project");
+    }
     const selectsSkill = sourceId !== undefined || skillPath !== undefined || ref !== undefined || hosts.length > 0;
     if (fromManifest) {
         if (scope !== "project") {
@@ -1378,6 +1411,7 @@ function finalizeInstallOptions(draft) {
         confirmed: draft.confirmed,
         overwrite,
         confirmAdditionalHostExposure: draft.confirmAdditionalHostExposure,
+        ...(draft.project === undefined ? {} : { project: draft.project }),
     };
 }
 function parseMethodOption(value) {

package/dist/src/path-safety.js

@@ -8,6 +8,9 @@ export function pathsOverlap(left, right) {
         (!relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) ||
         (!reverse.startsWith(`..${path.sep}`) && !path.isAbsolute(reverse));
 }
+/** A path component that is a symbolic link or junction; the message names it. */
+export class SymlinkPathError extends Error {
+}
 /** Walks every existing component of a path and rejects the first symbolic link. */
 export async function assertNoSymlinkPath(candidate, label) {
     const absolute = path.resolve(candidate);
@@ -18,7 +21,7 @@ export async function assertNoSymlinkPath(candidate, label) {
         current = path.join(current, segment);
         try {
             if ((await lstat(current)).isSymbolicLink()) {
-                throw new Error(`${label} contains a symbolic link: ${current}`);
+                throw new SymlinkPathError(`${label} contains a symbolic link: ${current}`);
             }
         }
         catch (error) {

package/dist/src/profile-export.js

@@ -45,7 +45,7 @@ export function describeProfileReplica(replica) {
         case "package": return `Installed Package ${describeCoordinates(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 { describeCoordinates, 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 ${describeCoordinates(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([]),