@iseoane/agent-depot 0.6.9 → 0.6.11

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.11] - 2026-11-08
+
+### Changed
+
+- The TUI Updates view is grouped by Source, with Packages and Skills below each
+  Source and Apps last. Groups start collapsed; `Enter` or `→`/`←` expand and
+  collapse them, and `space` on a group marks or clears all its rows (`[x]`, `[-]`,
+  `[ ]`). `u`, or `Enter` on a row, previews exactly the marked rows. `Enter` also
+  folds the "cannot be checked" line.
+- TUI Package labels always name their Source and never show a Source-root Package
+  as `.` or `name@.` (for example `…demo.git::claude#demo`); update results name the
+  Package's Source. CLI selection tokens are unchanged.
+- Profile export and import previews name a Source-root Package as `Package pi from …`
+  instead of `Package pi . from …`, and Package flow failure and approval reasons say
+  `pi from <source>` instead of `pi .`. Profile `--package` filters still accept the
+  previous spelling.
+
+## [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
@@ -503,7 +520,7 @@ Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 | Sources | `j`/`k` move through Git Sources and App recipes. `Enter` opens the Catalog for a Git Source or previews/approves an App recipe. Approval does not install the App. `n` adds a Git Source or guides recipe authoring; `r` refreshes Sources or reloads recipe status; `d` removes. `space`/`a` mark Git Sources only. Refresh previews show every selected Source; review every physical row before `y`. `n` cancels. |
 | Catalog | `Enter`/arrows expand and collapse, `space` marks the highlighted loose Skill, `a` marks or clears the visible loose Skills in its Source, and `i` starts installation for marked Skills or the highlighted Skill, Package, or verified-absent approved App. A Package opens the same paged panel as in Installations; confirm an App install separately with `y`. `/` filters and `s` widens a Source view to all Sources. Marks in other Sources remain unchanged; Skills hidden by the filter are not installed. |
 | Installations | `Enter`/arrows expand and collapse. On user-global rows, `u` starts an App or managed Skill uninstall, or removes an unmanaged Skill; project Skills cannot be removed. `h` or `i` adds Hosts to a user-global Skill installation, and `A` or `Enter` adopts an unmanaged Skill. `space` marks a leaf and `a` marks all visible leaves; bulk actions skip project installations with a reason. On an App row, `u` previews uninstall and `h` selects setup/teardown; changed recipes must be approved again before commands run. On a Package row, `i` previews the frozen install plan and runs it, approving the receipt first when it is missing; `Enter` approves the install declaration only, `U` updates, `u` uninstalls, and `f` forgets the selection record. Each of these opens its own panel, which pages when it is taller than the terminal: arrows or PageUp/PageDown move by a visible page, `j`/`k` by one row, and `Review N of M` with the row window shows where you are. `y` and `n` answer from any page. Package rows are not markable for bulk actions. |
-| Updates | `space` marks an update, `a` marks all available updates, and `t`/`p`/`g` selects all, project, or user-global scope. `Enter` previews the marked rows; `u` previews the selected batch; neither applies updates. `r` checks again, and left/right arrows fold or unfold the "cannot be checked" group. In a preview, arrows or PageUp/PageDown move by a visible page and `j`/`k` move one row. Review every row before `y`; `n` cancels. Unknown rows are informational. Packages and Apps are user-global only; Packages need action approval before update execution. |
+| Updates | Updates are grouped by Source, with Packages and Skills below each Source and Apps last; every group starts collapsed. `→`/`←` and `Enter` expand and collapse a group, and `←` on a row selects its group. `space` marks an update, or every available update in the highlighted group, even when it is collapsed. `a` marks all available updates, and `t`/`p`/`g` selects all, project, or user-global scope. `u` previews the marked rows from anywhere, and `Enter` on an update row does too; neither applies updates. `r` checks again, and `Enter` or `→`/`←` on the "cannot be checked" line fold or unfold it. In a preview, arrows or PageUp/PageDown move by a visible page and `j`/`k` move one row. Review every row before `y`; `n` cancels. Unknown rows are informational. Packages and Apps are user-global only; Packages need action approval before update execution. |
 | Profile | Press `e` to export or `i` to import. See [Profile workflow](#profile-workflow) for navigation, selection, previews, and cancellation. |
 
 ### Profile workflow
@@ -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

@@ -6,8 +6,8 @@ import path from "node:path";
 import { checkAppUpdates, createAppOperations } from "./app-flow.js";
 import { describeAppResult, describeManualCompletion, runAppCommand } from "./app-cli.js";
 import { createPackageOperations } from "./package-flow.js";
-import { describeLifecyclePlan, describePackageResult, describePackageUpdateCheck, formatPackageSelection, packageSelectionMatches, planWithRefresh, runPackageCommand } from "./package-cli.js";
-import { selectionKey } from "./package-model.js";
+import { describeLifecyclePlan, describePackageResult, describePackageUpdateCheck, packageSelectionMatches, planWithRefresh, runPackageCommand } from "./package-cli.js";
+import { formatPackageSelection, selectionKey } from "./package-model.js";
 import { EXPORT_USAGE, IMPORT_USAGE, runProfileExport, runProfileImport } from "./profile-cli.js";
 import { pathsOverlap } from "./path-safety.js";
 import { withChildOutput } from "./process-runner.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/package-cli.js

@@ -1,5 +1,5 @@
 import { sourceIdForUrl } from "./git-source.js";
-import { PACKAGE_HOSTS, bundleRoot, describeCoordinates, selectionKey } from "./package-model.js";
+import { PACKAGE_HOSTS, bundleRoot, describeCoordinates, describeSelectionCoordinate, displayRoot, formatPackageSelection, selectionKey, sourceToken } from "./package-model.js";
 import { NO_PROGRESS } from "./progress.js";
 import { projectSourceOf } from "./sources.js";
 import { CliUsageError } from "./usage-error.js";
@@ -76,9 +76,6 @@ export async function runPackageCommand(values, packages, sources, output, progr
 export function planWithRefresh(packages, selection, action, progress) {
     return progress.run(`Refreshing Source for Package ${formatPackageSelection(selection)}`, () => packages.planLifecycle(selection, action), { mayPrompt: true });
 }
-export function formatPackageSelection(selection) {
-    return `${sourceToken(selection.source)}::${describeSelectionCoordinate(selection)}`;
-}
 /**
  * The two spellings the CLI prints name the same selection: `discover` prints
  * the registered Source id, and `list` prints the Source's own token. Both are
@@ -295,12 +292,6 @@ function sourceMatchesToken(source, token) {
     }
     return source.kind === "git" && (source.url === token || sourceToken(projectSourceOf(source)) === token);
 }
-function sourceToken(source) {
-    if (source.kind === "builtin") {
-        return source.id;
-    }
-    return "url" in source ? source.url : source.path;
-}
 /** The registered Source id: derived for a Git Source, and its own token otherwise. */
 function sourceIdToken(source) {
     return "url" in source ? sourceIdForUrl(source.url) : sourceToken(source);
@@ -308,11 +299,6 @@ function sourceIdToken(source) {
 function formatDescriptorSelection(sourceId, descriptor) {
     return `${sourceId}::${describeSelectionCoordinate(descriptor.coordinates)}`;
 }
-function describeSelectionCoordinate(coordinates) {
-    return coordinates.host === "pi"
-        ? `pi:${displayRoot(coordinates.root)}`
-        : `claude:${displayRoot(coordinates.marketplaceRoot)}#${coordinates.pluginName}`;
-}
 function formatPackageRecord(record) {
     const verified = record.verified === undefined ? "unknown" : describeVersion(record.verified);
     return `Package ${formatPackageSelection(record.selection)}\tinstallId=${record.installId}\tverified=${verified}\tverifiedAt=${record.verifiedAt}`;
@@ -410,9 +396,6 @@ function packageResultSucceeded(result) {
     return result.status === "installed" || result.status === "updated" || result.status === "removed" ||
         result.status === "selected" || result.status === "forgotten";
 }
-function displayRoot(root) {
-    return root === "" ? "." : root;
-}
 function requireOptionValue(args, index, option) {
     const value = args[index];
     if (!value || value.startsWith("--")) {

package/dist/src/package-flow.js

@@ -7,7 +7,7 @@ import { sourceBundleScope } from "./package-content.js";
 import { affectedBy, classifyUpdate, claudeVersionUpdateNotice, hostInstallId, packageApprovalDigest, planHostSteps, PackagePlanError, } from "./package-host-plans.js";
 import { findInstalledBundle, readHostInstallView } from "./package-host-state.js";
 import { activeBundles as classifyActiveBundles, portableSkillConflicts, } from "./package-owned-skills.js";
-import { bundleRoot, describeCoordinates, selectionKey, } from "./package-model.js";
+import { bundleRoot, describePackageInSource, selectionKey, } from "./package-model.js";
 import { defaultPackageStateDirectory, PackageStateStore, } from "./package-state.js";
 import { runProcess } from "./process-runner.js";
 import { SourceStateStore } from "./source-state.js";
@@ -52,7 +52,7 @@ export function createPackageOperations(environment = {}) {
             return source;
         }
         if (sourceOperations.refreshProjectSource === undefined) {
-            throw new PackagePlanError(`Planning a Package lifecycle for ${describeCoordinates(selection)} requires a Source refresh, but this environment cannot refresh project Sources`);
+            throw new PackagePlanError(`Planning a Package lifecycle for ${describePackageInSource(selection)} requires a Source refresh, but this environment cannot refresh project Sources`);
         }
         return await sourceOperations.refreshProjectSource(selection.source);
     }
@@ -69,7 +69,7 @@ export function createPackageOperations(environment = {}) {
         const descriptor = discoverBundlesInSnapshot(files, sourceBundleScope(source))
             .find((candidate) => sameCoordinates(candidate.coordinates, coordinates));
         if (descriptor === undefined) {
-            throw new PackagePlanError(`Source ${JSON.stringify(source.id)} no longer provides a ${selection.host} Package at ${JSON.stringify(bundleRoot(coordinates))}`);
+            throw new PackagePlanError(`Source ${JSON.stringify(source.id)} no longer provides a ${selection.host} Package ${bundleRoot(coordinates) === "" ? "at its root" : `at ${JSON.stringify(bundleRoot(coordinates))}`}`);
         }
         const resolvedCommit = await readResolvedCommit(source);
         const available = availableEvidence(descriptor, resolvedCommit);
@@ -222,7 +222,7 @@ export function createPackageOperations(environment = {}) {
         switch (context.action) {
             case "install": {
                 if (observed.kind !== "installed") {
-                    return { status: "failed", reason: `The host does not report ${describeCoordinates(context.selection)} installed (${describeEvidence(observed)})` };
+                    return { status: "failed", reason: `The host does not report ${describePackageInSource(context.selection)} installed (${describeEvidence(observed)})` };
                 }
                 const contradiction = pinContradiction(context.selection, observed);
                 if (contradiction !== undefined) {
@@ -233,7 +233,7 @@ export function createPackageOperations(environment = {}) {
             }
             case "update": {
                 if (observed.kind !== "installed") {
-                    return { status: "failed", reason: `The update left no installed ${describeCoordinates(context.selection)} (${describeEvidence(observed)})` };
+                    return { status: "failed", reason: `The update left no installed ${describePackageInSource(context.selection)} (${describeEvidence(observed)})` };
                 }
                 const contradiction = pinContradiction(context.selection, observed);
                 if (contradiction !== undefined) {
@@ -262,7 +262,7 @@ export function createPackageOperations(environment = {}) {
             }
             case "uninstall": {
                 if (observed.kind !== "absent") {
-                    return { status: "failed", reason: `The host still reports ${describeCoordinates(context.selection)} (${describeEvidence(observed)})` };
+                    return { status: "failed", reason: `The host still reports ${describePackageInSource(context.selection)} (${describeEvidence(observed)})` };
                 }
                 await state.drop(context.selection);
                 return Object.freeze({ status: "removed" });
@@ -343,7 +343,7 @@ export function createPackageOperations(environment = {}) {
                 return Object.freeze({ status: "stale plan", reason: difference });
             }
             if (await state.approvalStatus(fresh.digest) !== "approved") {
-                throw new PackagePlanError(`The ${plan.action} plan for ${describeCoordinates(plan.selection)} is not approved; review it and approve the current declaration first`);
+                throw new PackagePlanError(`The ${plan.action} plan for ${describePackageInSource(plan.selection)} is not approved; review it and approve the current declaration first`);
             }
             const previous = findInstalledBundle(await readHostView(), fresh.plan.descriptor, plan.selection);
             const context = contextFromDerived(fresh, plan.action, previous);
@@ -586,7 +586,7 @@ function pinContradiction(selection, observed) {
     if (verdict.kind !== "contradicted") {
         return undefined;
     }
-    return `The host reports ${describeCoordinates(selection)} ${describeEvidence(observed)}, which contradicts the fixed pin ${JSON.stringify(verdict.pin)}`;
+    return `The host reports ${describePackageInSource(selection)} ${describeEvidence(observed)}, which contradicts the fixed pin ${JSON.stringify(verdict.pin)}`;
 }
 /**
  * The record's `verified` field is a claim about the host, so it derives from the

package/dist/src/package-model.js

@@ -20,6 +20,57 @@ export function describeCoordinates(coordinates) {
         ? `pi ${at(coordinates.root)}`
         : `claude ${coordinates.pluginName}@${at(coordinates.marketplaceRoot)}`;
 }
+/**
+ * Like `describeCoordinates` for text that already names the Source: a bundle at the Source root
+ * omits its root instead of showing `.`. Display only; `--package` filters keep `describeCoordinates`.
+ */
+export function describeBundleInSource(coordinates) {
+    return coordinates.host === "pi"
+        ? `pi${coordinates.root === "" ? "" : ` ${coordinates.root}`}`
+        : `claude ${coordinates.pluginName}${coordinates.marketplaceRoot === "" ? "" : `@${coordinates.marketplaceRoot}`}`;
+}
+/** Host, root and Source in prose. Unlike `formatPackageSelection` it cannot be mistaken for a CLI token. */
+export function describePackageInSource(selection) {
+    return `${describeBundleInSource(selection)} from ${sourceToken(selection.source)}`;
+}
+/** The token the CLI prints for a Source: the built-in id, the URL or the local path. */
+export function sourceToken(source) {
+    if (source.kind === "builtin") {
+        return source.id;
+    }
+    return "url" in source ? source.url : source.path;
+}
+/** A root-level bundle shows its root as `.`. */
+export function displayRoot(root) {
+    return root === "" ? "." : root;
+}
+/** `pi:<root>` or `claude:<root>#<plugin>`. */
+export function describeSelectionCoordinate(coordinates) {
+    return coordinates.host === "pi"
+        ? `pi:${displayRoot(coordinates.root)}`
+        : `claude:${displayRoot(coordinates.marketplaceRoot)}#${coordinates.pluginName}`;
+}
+/** Coordinates qualified by the Source they live in, so equal roots of different Sources stay apart. */
+export function formatPackageCoordinates(source, coordinates) {
+    return `${sourceToken(source)}::${describeSelectionCoordinate(coordinates)}`;
+}
+/**
+ * The TUI spelling of coordinates: like the CLI's, but a bundle at the Source root omits its root
+ * segment instead of showing `.`. Display only; the CLI keeps `formatPackageCoordinates`.
+ */
+export function displayPackageCoordinates(source, coordinates) {
+    const root = bundleRoot(coordinates);
+    const at = root === "" ? "" : `:${root}`;
+    return `${sourceToken(source)}::${coordinates.host === "pi" ? `pi${at}` : `claude${at}#${coordinates.pluginName}`}`;
+}
+/** The TUI spelling of a selection. */
+export function displayPackageSelection(selection) {
+    return displayPackageCoordinates(selection.source, selection);
+}
+/** The CLI spelling of a selection. */
+export function formatPackageSelection(selection) {
+    return formatPackageCoordinates(selection.source, selection);
+}
 /**
  * The stable selection identity. Derived from the Source and the coordinates
  * only, so a bundle rename (its manifest name or version) does not move the

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) {