@papillon6814/copi 0.2.1 → 0.4.0

package/README.md

@@ -26,7 +26,11 @@ copi migrate --resolve [--dry-run]
 copi help
 ```
 
-`setup` requires an interactive terminal. It asks which locations may be searched and asks for explicit authorization before searching. Selecting the entire `HOME` is broad: it can inspect supported resources throughout that directory, including Pi profiles and the configured Pi agent directory. Selecting the current project scopes discovery to that project. The wizard then lets you choose individual resources, review masked previews, assign each saved resource to one or more groups, and confirm before anything is copied into the library. Declining authorization performs no search.
+`setup` requires an interactive terminal. It first asks where copi may look: only the Pi agent directories (`~/.pi/agent`, `~/.pi/agent-*`, `~/.pi/agent_*` and `~/.agents`; the default and usually fast), your whole `HOME` (this can take a minute or more; a progress bar advances per top-level folder), this project only, or both. Selecting the entire `HOME` is broad: it can inspect supported resources throughout that directory, including Pi profiles and the configured Pi agent directory, but skips worktree checkout copies (`.worktrees`, `.claude/worktrees`, `.config/superpowers/worktrees`, `.treehouse`). Selecting the current project scopes discovery to that project. Candidates with the same kind, name and content are merged into one row marked `(+N identical copies)`; the kept row prefers a source under `~/.pi` or `~/.agents`. Copi then asks for explicit authorization before searching; declining performs no search. Search warnings are summarized (for example, resources found outside the selected roots are counted rather than listed one by one), and missing files are skipped silently.
+
+Candidates are listed with a source label, size and modification date, and entries whose name matches an already saved resource are marked `already saved`. After you select resources, name conflicts are resolved right away, before any preview: keep one of the same-named selections, rename the display name only (the files, body and destination are not changed), skip the resource (keeping the saved copy), or go back to the list.
+
+A group is a named set of saved resources that you later apply together with `copi apply <group> <project>`. If no group exists yet, setup asks you to create the first one. With several resources, setup asks once how to group them: by default all of them go into the same group(s); you can instead choose groups for each resource. Each resource is then reviewed in turn with a masked preview titled with its progress (for example `1/3`) and its source directory. A suspected sensitive file needs its own approval; answering No means that resource is not saved at all. Finally, one confirmation lists everything that will be copied into the library; the original files are never changed. When it is done, setup prints the next step, for example `copi apply <group> <project> --dry-run`.
 
 `manage` requires both stdin and stdout to be an interactive TTY. Choose saved resources and groups by name; UUID input is not required and normal screens identify resources by display name, kind, groups and destination. It provides masked viewing, terminal text editing, display-name changes, separate destination changes, source refresh, group management and apply. Running without arguments, or with `help`, `--help` or `-h`, still shows help.
 

package/dist/src/discovery.d.ts

@@ -2,6 +2,8 @@ import type { DiscoveryResult } from "./types.ts";
 export interface DiscoveryScopes {
     home: boolean;
     project: boolean;
+    /** Only the Pi agent directories under HOME (`~/.pi/agent`, `~/.pi/agent-*`, `~/.pi/agent_*`, `~/.agents`); ignored when `home` is set. */
+    piDirs?: boolean;
 }
 export interface DiscoveryOptions {
     homeDir: string;
@@ -9,4 +11,21 @@ export interface DiscoveryOptions {
     projectDir: string;
     scopes?: DiscoveryScopes;
 }
-export declare function discoverResources(options: DiscoveryOptions): Promise<DiscoveryResult>;
+export declare function shouldExclude(relativePath: string): boolean;
+/** Git worktrees and similar checkout copies duplicate their main repository, so whole-HOME searches skip them. */
+export declare function isWorktreeCopy(relativePath: string): boolean;
+/**
+ * The Pi agent directories searched by the `piDirs` scope, sorted. Symlinks are never followed: a symlinked
+ * `~/.pi`, profile directory or `~/.agents` is reported in `symlinks` instead (callers warn about it).
+ */
+export declare function piAgentDirectories(homeDir: string): Promise<{
+    directories: string[];
+    symlinks: string[];
+}>;
+/** HOME search progress: `total` top-level directories, `done` finished so far, `current` the one being searched. */
+export interface DiscoveryProgress {
+    done: number;
+    total: number;
+    current?: string;
+}
+export declare function discoverResources(options: DiscoveryOptions, onProgress?: (progress: DiscoveryProgress) => void): Promise<DiscoveryResult>;

package/dist/src/discovery.js

@@ -17,12 +17,50 @@ function isWithin(root, target) {
     const relative = path.relative(root, target);
     return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
 }
-function shouldExclude(relativePath) {
+export function shouldExclude(relativePath) {
     return relativePath.split(path.sep).some((part) => {
         const lower = part.toLowerCase();
         return excludedNames.has(lower) || lower === "auth.json" || lower === "mcp-auth.json" || lower === "oauth.json" || lower.startsWith(".env");
     });
 }
+/** Git worktrees and similar checkout copies duplicate their main repository, so whole-HOME searches skip them. */
+export function isWorktreeCopy(relativePath) {
+    const parts = relativePath.split(path.sep);
+    return parts.some((part, index) => part === ".worktrees" || part === ".treehouse"
+        || (part === "worktrees" && (parts[index - 1] === ".claude" || (parts[index - 1] === "superpowers" && parts[index - 2] === ".config"))));
+}
+const piProfilePattern = /^agent([-_].+)?$/;
+/**
+ * The Pi agent directories searched by the `piDirs` scope, sorted. Symlinks are never followed: a symlinked
+ * `~/.pi`, profile directory or `~/.agents` is reported in `symlinks` instead (callers warn about it).
+ */
+export async function piAgentDirectories(homeDir) {
+    const directories = [];
+    const symlinks = [];
+    const kind = (p) => lstat(p).then((stat) => stat.isSymbolicLink() ? "link" : stat.isDirectory() ? "dir" : "other").catch(() => "missing");
+    const piDir = path.join(homeDir, ".pi");
+    const piKind = await kind(piDir);
+    if (piKind === "link")
+        symlinks.push(piDir);
+    if (piKind === "dir") {
+        for (const entry of await readdir(piDir, { withFileTypes: true }).catch(() => [])) {
+            if (!piProfilePattern.test(entry.name))
+                continue;
+            if (entry.isSymbolicLink())
+                symlinks.push(path.join(piDir, entry.name));
+            else if (entry.isDirectory())
+                directories.push(path.join(piDir, entry.name));
+        }
+    }
+    const shared = path.join(homeDir, ".agents");
+    const sharedKind = await kind(shared);
+    if (sharedKind === "link")
+        symlinks.push(shared);
+    if (sharedKind === "dir")
+        directories.push(shared);
+    const byPath = (left, right) => left.localeCompare(right);
+    return { directories: directories.sort(byPath), symlinks: symlinks.sort(byPath) };
+}
 function displayRelative(root, target) {
     return path.relative(root, target) || path.basename(target);
 }
@@ -117,19 +155,24 @@ async function canonicalDirectory(directory) {
         return undefined;
     }
 }
-export async function discoverResources(options) {
+/** False only when the entry itself does not exist (lstat ENOENT); dangling symlinks count as existing. */
+async function exists(target) {
+    return lstat(target).then(() => true, (error) => error.code !== "ENOENT");
+}
+export async function discoverResources(options, onProgress) {
     const scopes = options.scopes ?? inferSearchScopes(options);
-    if (!scopes.home && !scopes.project)
+    const piOnly = Boolean(scopes.piDirs) && !scopes.home;
+    if (!scopes.home && !scopes.project && !piOnly)
         return { candidates: [], warnings: [], excludedPaths: [] };
     const warnings = [];
     const excludedPaths = new Set();
     const candidates = [];
     const candidateKeys = new Set();
-    const home = scopes.home ? await canonicalDirectory(options.homeDir) : undefined;
-    const agent = scopes.home ? await canonicalDirectory(options.agentDir) : undefined;
+    const home = scopes.home || piOnly ? await canonicalDirectory(options.homeDir) : undefined;
+    const agent = scopes.home || piOnly ? await canonicalDirectory(options.agentDir) : undefined;
     const project = scopes.project ? await canonicalDirectory(options.projectDir) : undefined;
     const packageAgentDir = agent;
-    if (scopes.home && !home)
+    if ((scopes.home || piOnly) && !home)
         addWarning(warnings, "unavailable-root", options.homeDir, "The explicitly selected home directory is unavailable.");
     if (scopes.home && !agent)
         addWarning(warnings, "unavailable-root", options.agentDir, "The explicitly selected Pi agent directory is unavailable.");
@@ -143,6 +186,8 @@ export async function discoverResources(options) {
     if (project)
         roots.push({ path: project, scope: "project", source: "project", destinationRoot: ".pi/skills", destinationKind: "project" });
     const addCandidate = async (kind, root, sourcePath, name, scope, source, destination) => {
+        if (!(await exists(sourcePath)))
+            return;
         const canonicalSource = await realpath(sourcePath).catch(() => undefined);
         const canonicalRoot = await realpath(root).catch(() => undefined);
         if (!canonicalSource || !canonicalRoot || !isWithin(canonicalRoot, canonicalSource)) {
@@ -172,11 +217,11 @@ export async function discoverResources(options) {
             destination,
         });
     };
-    const walk = async (root, startPath, onFile) => {
+    const walk = async (root, startPath, onFile, progress) => {
         const canonicalRoot = await canonicalDirectory(root);
         if (!canonicalRoot)
             return;
-        const visit = async (directory) => {
+        const visit = async (directory, topLevel = false) => {
             let entries;
             try {
                 entries = await readdir(directory, { withFileTypes: true });
@@ -186,9 +231,19 @@ export async function discoverResources(options) {
                 addWarning(warnings, code === "EACCES" ? "permission-denied" : "scan-error", directory, code === "EACCES" ? "Permission denied while searching this directory." : "Unable to search this directory.");
                 return;
             }
+            const tracked = topLevel && progress
+                ? entries.filter((entry) => entry.isDirectory() && !entry.isSymbolicLink() && !shouldExclude(path.relative(canonicalRoot, path.join(directory, entry.name))))
+                : [];
+            let done = 0;
+            if (topLevel && progress)
+                progress({ done, total: tracked.length });
             for (const entry of entries) {
                 const child = path.join(directory, entry.name);
                 const relative = path.relative(canonicalRoot, child);
+                if (entry.isDirectory() && isWorktreeCopy(relative)) {
+                    excludedPaths.add(child);
+                    continue;
+                }
                 if (shouldExclude(relative)) {
                     excludedPaths.add(child);
                     if (relative.split(path.sep).some((part) => part.toLowerCase() === "auth")) {
@@ -201,14 +256,22 @@ export async function discoverResources(options) {
                     addWarning(warnings, target && isWithin(canonicalRoot, target) ? "symlink-skipped" : "external-symlink", child, "Symbolic links are not followed during resource discovery.");
                     continue;
                 }
-                if (entry.isDirectory())
+                if (entry.isDirectory()) {
+                    const isTracked = tracked.includes(entry);
+                    if (isTracked)
+                        progress({ done, total: tracked.length, current: child });
                     await visit(child);
+                    if (isTracked)
+                        progress({ done: ++done, total: tracked.length });
+                }
                 else if (entry.isFile())
                     await onFile(child);
             }
         };
         const canonicalStart = await realpath(startPath).catch(() => undefined);
         if (!canonicalStart || !isWithin(canonicalRoot, canonicalStart)) {
+            if (!(await exists(startPath)))
+                return;
             addWarning(warnings, "resource-outside-root", startPath, "A configured resource root resolves outside its allowed search root.");
             return;
         }
@@ -226,7 +289,7 @@ export async function discoverResources(options) {
         if (stat.isFile())
             await onFile(canonicalStart);
         else if (stat.isDirectory())
-            await visit(canonicalStart);
+            await visit(canonicalStart, true);
     };
     const addSkillRoot = async (root, startPath, scope, source, destinationRoot) => {
         await walk(root, startPath, async (file) => {
@@ -482,7 +545,7 @@ export async function discoverResources(options) {
     const homeProjects = new Set();
     const homeProfiles = new Set();
     if (home) {
-        await walk(home, home, async (file) => {
+        const classifyHomeFile = async (file) => {
             const relativeParts = path.relative(home, file).split(path.sep);
             const base = path.basename(file);
             const piIndex = relativeParts.indexOf(".pi");
@@ -561,7 +624,21 @@ export async function discoverResources(options) {
                     homeProjects.add(projectRoot);
                 await addCandidate("instruction", home, file, base, "project", "project-instructions", { kind: "project", path: base });
             }
-        });
+        };
+        if (scopes.home) {
+            await walk(home, home, classifyHomeFile, onProgress);
+        }
+        else {
+            const { directories: starts, symlinks } = await piAgentDirectories(home);
+            for (const link of symlinks)
+                addWarning(warnings, "symlink-skipped", link, "Symbolic links are not followed during resource discovery.");
+            onProgress?.({ done: 0, total: starts.length });
+            for (const [index, start] of starts.entries()) {
+                onProgress?.({ done: index, total: starts.length, current: start });
+                await walk(home, start, classifyHomeFile);
+                onProgress?.({ done: index + 1, total: starts.length });
+            }
+        }
         for (const profileRoot of homeProfiles) {
             await scanSettings(path.join(profileRoot, "settings.json"), "user", [profileRoot, home], profileRoot);
         }

package/dist/src/setup-display.d.ts

@@ -0,0 +1,67 @@
+import type { ResourceCandidate } from "./types.ts";
+/** Replace a leading home directory with `~` (only on a path-segment boundary). */
+export declare function displayPath(p: string, home: string): string;
+/** Keep head and tail joined by `…`; return `s` unchanged when `max` is missing, tiny, or not smaller than the length. */
+export declare function truncateMiddle(s: string, max: number | undefined): string;
+export declare function formatBytes(n: number): string;
+/** Summarize skipped out-of-root resources into one note (undefined when none). */
+export declare function formatOutsideRootSummary(paths: readonly string[], home: string): {
+    title: string;
+    body: string;
+} | undefined;
+export interface CandidateStats {
+    size?: string;
+    mtime?: Date;
+}
+/**
+ * `[kind] name — ~/source/dir`, plus `(already saved)`. Shared with conflict-resolution options.
+ * When `columns` is given the source directory is middle-truncated (tail kept) so the row does not wrap.
+ */
+export declare function candidateLabel(c: ResourceCandidate, home: string, alreadySaved: boolean, columns?: number): string;
+/**
+ * Labels for a whole list. Rows sharing kind + nameKey must stay distinguishable: when truncation makes their
+ * source labels collide, that group falls back to whole trailing segments (`…/a/b`), widened until they differ.
+ */
+export declare function candidateLabels(list: readonly ResourceCandidate[], home: string, isSaved: (c: ResourceCandidate) => boolean, columns?: number): Map<string, string>;
+/** Sort by kind, then nameKey, then source path (new array). */
+export declare function sortCandidates(list: readonly ResourceCandidate[]): ResourceCandidate[];
+export declare function formatLocalDate(d: Date): string;
+/** `<size> · modified <date> · <destination>`; missing parts are omitted. Truncated to the terminal width minus label and prompt chrome. */
+export declare function candidateHint(c: ResourceCandidate, stats: CandidateStats, home: string, columns: number | undefined, labelLength: number): string;
+/** Cheap, never-throwing stats for the shown candidates, gathered in parallel. */
+export declare function gatherCandidateStats(list: readonly ResourceCandidate[]): Promise<Map<string, CandidateStats>>;
+/** Groups of 2+ selected candidates sharing a `nameKey` (any kind), each in input order; groups ordered by first member. */
+export declare function findSelectionConflicts(list: readonly ResourceCandidate[]): ResourceCandidate[][];
+/**
+ * Suggested rename `<name> (<segment>)`. Within a conflict group the segment is the nearest ancestor directory
+ * (walking up from the source's parent) whose name tells this member apart from the others — unique if possible,
+ * otherwise the first level where the members differ at all. Without such a level (or alone), the segment is the
+ * grandparent of the source, falling back to its parent, e.g. `jandel.md (agent-rbx)`.
+ */
+export declare function defaultRenameName(c: ResourceCandidate, group?: readonly ResourceCandidate[]): string;
+/** Validation message for a new display name, or undefined when it is non-empty and its `nameKey` is not taken. */
+export declare function pendingNameError(name: string | undefined, taken: ReadonlySet<string>): string | undefined;
+/** Bar message for the HOME search: `14/36  ~/Library`, or just the count between directories. */
+export declare function formatSearchProgress(progress: {
+    done: number;
+    total: number;
+    current?: string;
+}, home: string): string;
+/**
+ * SHA-256 over what saving would copy: for a file its mode and bytes, for a directory every regular file's
+ * relative path, mode and bytes (sorted, same exclusions as discovery), each field length-prefixed.
+ * `undefined` (never merged) when unreadable, too large, or containing a symlink, which saving refuses.
+ */
+export declare function contentFingerprint(c: ResourceCandidate): Promise<string | undefined>;
+/**
+ * Collapse candidates with the same kind, display name (nameKey) and content fingerprint into one row.
+ * The kept row prefers a source under `~/.pi` or `~/.agents`, then the shortest path; input order is preserved.
+ * `copies` maps a kept candidate id to how many identical candidates it stands for (besides itself).
+ */
+export declare function collapseIdenticalCandidates(list: readonly ResourceCandidate[], fingerprints: ReadonlyMap<string, string | undefined>, home: string): {
+    kept: ResourceCandidate[];
+    copies: Map<string, number>;
+};
+export declare function identicalCopiesSuffix(count: number | undefined): string;
+/** Map with at most `limit` operations in flight, preserving input order. */
+export declare function mapWithLimit<T, R>(items: readonly T[], limit: number, operation: (item: T) => Promise<R>): Promise<R[]>;

package/dist/src/setup-display.js

@@ -0,0 +1,306 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { shouldExclude } from "./discovery.js";
+import { nameKey } from "./names.js";
+/** Replace a leading home directory with `~` (only on a path-segment boundary). */
+export function displayPath(p, home) {
+    if (!home)
+        return p;
+    const base = home.length > 1 && home.endsWith(path.sep) ? home.slice(0, -1) : home;
+    if (p === base)
+        return "~";
+    if (p.startsWith(base + path.sep))
+        return `~${p.slice(base.length)}`;
+    return p;
+}
+/** Keep head and tail joined by `…`; return `s` unchanged when `max` is missing, tiny, or not smaller than the length. */
+export function truncateMiddle(s, max) {
+    if (max === undefined || !Number.isFinite(max) || max < 4 || s.length <= max)
+        return s;
+    const keep = max - 1;
+    const head = Math.ceil(keep / 2);
+    const tail = keep - head;
+    return `${s.slice(0, head)}…${tail > 0 ? s.slice(s.length - tail) : ""}`;
+}
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+const outsideRootPreview = 5;
+/** Summarize skipped out-of-root resources into one note (undefined when none). */
+export function formatOutsideRootSummary(paths, home) {
+    if (paths.length === 0)
+        return undefined;
+    const lines = paths.slice(0, outsideRootPreview).map((p) => displayPath(p, home));
+    if (paths.length > outsideRootPreview)
+        lines.push(`+${paths.length - outsideRootPreview} more`);
+    return { title: `Skipped ${paths.length} resource(s) outside the selected locations`, body: lines.join("\n") };
+}
+/**
+ * `[kind] name — ~/source/dir`, plus `(already saved)`. Shared with conflict-resolution options.
+ * When `columns` is given the source directory is middle-truncated (tail kept) so the row does not wrap.
+ */
+export function candidateLabel(c, home, alreadySaved, columns) {
+    const head = `[${c.kind}] ${c.name} \u2014 `;
+    const tail = alreadySaved ? " (already saved)" : "";
+    let dir = displayPath(path.dirname(c.sourcePath), home);
+    if (columns !== undefined && Number.isFinite(columns))
+        dir = truncateMiddle(dir, Math.max(columns - head.length - tail.length - 6, 8));
+    return `${head}${dir}${tail}`;
+}
+/**
+ * Labels for a whole list. Rows sharing kind + nameKey must stay distinguishable: when truncation makes their
+ * source labels collide, that group falls back to whole trailing segments (`…/a/b`), widened until they differ.
+ */
+export function candidateLabels(list, home, isSaved, columns) {
+    const out = new Map();
+    const groups = new Map();
+    for (const c of list) {
+        out.set(c.id, candidateLabel(c, home, isSaved(c), columns));
+        const key = `${c.kind}\0${nameKey(c.name)}`;
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        const labels = group.map((c) => out.get(c.id));
+        if (new Set(labels).size === labels.length)
+            continue;
+        const dirs = group.map((c) => displayPath(path.dirname(c.sourcePath), home));
+        const segs = dirs.map((d) => d.split(path.sep));
+        const max = Math.max(...segs.map((x) => x.length));
+        for (let k = 1; k <= max; k += 1) {
+            const cut = segs.map((x, i) => (x.length <= k ? dirs[i] : `\u2026${path.sep}${x.slice(-k).join(path.sep)}`));
+            const rendered = group.map((c, i) => `[${c.kind}] ${c.name} \u2014 ${cut[i]}${isSaved(c) ? " (already saved)" : ""}`);
+            if (new Set(rendered).size === rendered.length || k === max) {
+                group.forEach((c, i) => out.set(c.id, rendered[i]));
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** Sort by kind, then nameKey, then source path (new array). */
+export function sortCandidates(list) {
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return [...list].sort((a, b) => cmp(a.kind, b.kind) || cmp(nameKey(a.name), nameKey(b.name)) || cmp(a.sourcePath, b.sourcePath));
+}
+export function formatLocalDate(d) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+/** `<size> · modified <date> · <destination>`; missing parts are omitted. Truncated to the terminal width minus label and prompt chrome. */
+export function candidateHint(c, stats, home, columns, labelLength) {
+    const parts = [];
+    if (stats.size !== undefined)
+        parts.push(stats.size);
+    if (stats.mtime !== undefined)
+        parts.push(`modified ${formatLocalDate(stats.mtime)}`);
+    parts.push(c.destination.kind === "global-only" ? "save only" : displayPath(c.destination.path, home));
+    const hint = parts.join(" · ");
+    if (columns === undefined || !Number.isFinite(columns))
+        return hint;
+    return truncateMiddle(hint, Math.max(columns - labelLength - 10, 12));
+}
+const countCap = 1000;
+async function countFiles(dir, budget) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (budget.left <= 0)
+            return;
+        if (entry.isDirectory())
+            await countFiles(path.join(dir, entry.name), budget);
+        else if (entry.isFile())
+            budget.left -= 1;
+    }
+}
+async function hasMoreFiles(dir, cap) {
+    const budget = { left: cap + 1 };
+    await countFiles(dir, budget);
+    return budget.left <= 0;
+}
+async function statOne(c) {
+    try {
+        const st = await lstat(c.sourcePath);
+        if (st.isDirectory()) {
+            const budget = { left: countCap };
+            await countFiles(c.sourcePath, budget);
+            const n = countCap - budget.left;
+            return { size: budget.left <= 0 && (await hasMoreFiles(c.sourcePath, countCap)) ? `${countCap}+ files` : `${n} file${n === 1 ? "" : "s"}`, mtime: st.mtime };
+        }
+        return { size: formatBytes(st.size), mtime: st.mtime };
+    }
+    catch {
+        return {};
+    }
+}
+/** Cheap, never-throwing stats for the shown candidates, gathered in parallel. */
+export async function gatherCandidateStats(list) {
+    const entries = await Promise.all(list.map(async (c) => [c.id, await statOne(c)]));
+    return new Map(entries);
+}
+/** Groups of 2+ selected candidates sharing a `nameKey` (any kind), each in input order; groups ordered by first member. */
+export function findSelectionConflicts(list) {
+    const groups = new Map();
+    for (const c of list) {
+        const key = nameKey(c.name);
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    return [...groups.values()].filter((group) => group.length > 1);
+}
+/**
+ * Suggested rename `<name> (<segment>)`. Within a conflict group the segment is the nearest ancestor directory
+ * (walking up from the source's parent) whose name tells this member apart from the others — unique if possible,
+ * otherwise the first level where the members differ at all. Without such a level (or alone), the segment is the
+ * grandparent of the source, falling back to its parent, e.g. `jandel.md (agent-rbx)`.
+ */
+export function defaultRenameName(c, group = [c]) {
+    const ancestors = (x) => {
+        const out = [];
+        for (let dir = path.dirname(x.sourcePath); path.basename(dir); dir = path.dirname(dir))
+            out.push(path.basename(dir));
+        return out;
+    };
+    const mine = ancestors(c);
+    const others = group.filter((x) => x.id !== c.id).map(ancestors);
+    let segment;
+    if (others.length > 0) {
+        const unique = mine.findIndex((name, level) => others.every((other) => other[level] !== name));
+        const differing = mine.findIndex((name, level) => others.some((other) => other[level] !== name));
+        const level = unique !== -1 ? unique : differing;
+        if (level !== -1)
+            segment = mine[level];
+    }
+    segment ??= mine[1] ?? mine[0];
+    return segment ? `${c.name} (${segment})` : c.name;
+}
+/** Validation message for a new display name, or undefined when it is non-empty and its `nameKey` is not taken. */
+export function pendingNameError(name, taken) {
+    let key;
+    try {
+        key = nameKey(name ?? "");
+    }
+    catch {
+        return "Enter a non-empty display name.";
+    }
+    return taken.has(key) ? "That name is already used by a saved or selected resource; choose another." : undefined;
+}
+/** Bar message for the HOME search: `14/36  ~/Library`, or just the count between directories. */
+export function formatSearchProgress(progress, home) {
+    const count = `${progress.done}/${progress.total}`;
+    return progress.current === undefined ? `${count}  Searching` : `${count}  ${displayPath(progress.current, home)}`;
+}
+const fingerprintMaxFiles = 2000;
+const fingerprintMaxBytes = 50 * 1024 * 1024;
+/**
+ * SHA-256 over what saving would copy: for a file its mode and bytes, for a directory every regular file's
+ * relative path, mode and bytes (sorted, same exclusions as discovery), each field length-prefixed.
+ * `undefined` (never merged) when unreadable, too large, or containing a symlink, which saving refuses.
+ */
+export async function contentFingerprint(c) {
+    try {
+        const field = (hash, value) => {
+            const bytes = typeof value === "string" ? Buffer.from(value) : value;
+            hash.update(`${bytes.length}:`).update(bytes);
+        };
+        const stat = await lstat(c.sourcePath);
+        if (stat.isFile()) {
+            if (stat.size > fingerprintMaxBytes)
+                return undefined;
+            const hash = createHash("sha256");
+            field(hash, (stat.mode & 0o777).toString(8));
+            field(hash, await readFile(c.sourcePath));
+            return hash.digest("hex");
+        }
+        if (!stat.isDirectory())
+            return undefined;
+        const files = [];
+        let bytes = 0;
+        const visit = async (dir) => {
+            for (const entry of await readdir(dir, { withFileTypes: true })) {
+                const child = path.join(dir, entry.name);
+                const relative = path.relative(c.sourcePath, child);
+                if (shouldExclude(relative))
+                    continue;
+                if (entry.isSymbolicLink())
+                    return false;
+                if (entry.isDirectory()) {
+                    if (!(await visit(child)))
+                        return false;
+                }
+                else if (entry.isFile()) {
+                    files.push(relative);
+                    bytes += (await lstat(child)).size;
+                    if (files.length > fingerprintMaxFiles || bytes > fingerprintMaxBytes)
+                        return false;
+                }
+            }
+            return true;
+        };
+        if (!(await visit(c.sourcePath)))
+            return undefined;
+        const hash = createHash("sha256");
+        for (const relative of files.sort()) {
+            const file = path.join(c.sourcePath, relative);
+            field(hash, relative);
+            field(hash, ((await lstat(file)).mode & 0o777).toString(8));
+            field(hash, await readFile(file));
+        }
+        return hash.digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Collapse candidates with the same kind, display name (nameKey) and content fingerprint into one row.
+ * The kept row prefers a source under `~/.pi` or `~/.agents`, then the shortest path; input order is preserved.
+ * `copies` maps a kept candidate id to how many identical candidates it stands for (besides itself).
+ */
+export function collapseIdenticalCandidates(list, fingerprints, home) {
+    const preferred = (c) => [".pi", ".agents"].some((dir) => c.sourcePath.startsWith(path.join(home, dir) + path.sep)) ? 0 : 1;
+    const better = (a, b) => preferred(a) - preferred(b) || a.sourcePath.length - b.sourcePath.length || a.sourcePath.localeCompare(b.sourcePath);
+    const groups = new Map();
+    for (const c of list) {
+        const fingerprint = fingerprints.get(c.id);
+        const key = fingerprint === undefined ? `unique\0${c.id}` : JSON.stringify([c.kind, c.name, c.scope, c.destination, fingerprint]);
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    const representative = new Map();
+    const copies = new Map();
+    for (const group of groups.values()) {
+        const best = [...group].sort(better)[0];
+        for (const c of group)
+            representative.set(c.id, best);
+        if (group.length > 1)
+            copies.set(best.id, group.length - 1);
+    }
+    const kept = list.filter((c) => representative.get(c.id).id === c.id);
+    return { kept, copies };
+}
+export function identicalCopiesSuffix(count) {
+    return count ? ` (+${count} identical ${count === 1 ? "copy" : "copies"})` : "";
+}
+/** Map with at most `limit` operations in flight, preserving input order. */
+export async function mapWithLimit(items, limit, operation) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await operation(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}

package/dist/src/wizard.d.ts

@@ -17,6 +17,7 @@ export interface SearchRoots {
 export interface SearchScopes {
     home: boolean;
     project: boolean;
+    piDirs?: boolean;
 }
 export declare function buildSearchOptions(roots: SearchRoots, scopes: SearchScopes): DiscoveryOptions | undefined;
 export declare function formatMaskedPreview(relativePath: string, content: string): string;
@@ -30,6 +31,14 @@ export declare function prepareCandidateForReview(candidate: ResourceCandidate):
 export declare function saveReviewedCandidate(libraryDir: string, review: CandidateReview, groupIds: string[], approvedSensitivePaths: string[], confirmed: boolean): Promise<SavedItem | null>;
 /** Resolve all staged conflicts in one name-only catalog save; cancellation writes nothing. */
 export declare function resolveNameConflicts(libraryDir: string): Promise<void>;
+/**
+ * Rename prompt text. The suggestion is prefilled only when it renders unchanged through `safeDisplay`
+ * (`initialValue` is echoed raw); otherwise the field stays empty and the masked suggestion is shown in the message.
+ */
+export declare function renamePrompt(name: string, sourceDir: string, suggestion: string): {
+    message: string;
+    initialValue?: string;
+};
 export declare function runSetup(libraryDir: string, roots: SearchRoots): Promise<void>;
 export declare function runGroupManager(libraryDir: string): Promise<void>;
 export declare function printGroups(catalog: StoredCatalog): void;

package/dist/src/wizard.js

@@ -1,9 +1,10 @@
-import { autocompleteMultiselect as clackMultiselect, cancel as clackCancel, confirm as clackConfirm, intro as clackIntro, isCancel, log, note as clackNote, outro as clackOutro, select as clackSelect, spinner as clackSpinner, text as clackText } from "@clack/prompts";
+import { autocompleteMultiselect as clackMultiselect, cancel as clackCancel, confirm as clackConfirm, intro as clackIntro, isCancel, log, note as clackNote, outro as clackOutro, progress as clackProgress, select as clackSelect, spinner as clackSpinner, text as clackText } from "@clack/prompts";
 import { lstat } from "node:fs/promises";
 import path from "node:path";
 import { assertModernCatalog, importPreparedResource, loadCatalog, prepareResource, readPreparedResource, readSnapshotFiles, saveCatalog, saveNameChanges } from "./catalog.js";
-import { discoverResources } from "./discovery.js";
+import { discoverResources, isWorktreeCopy, piAgentDirectories } from "./discovery.js";
 import { createGroup, renameGroup, setGroupItems } from "./groups.js";
+import { candidateHint, candidateLabels, collapseIdenticalCandidates, contentFingerprint, defaultRenameName, displayPath, findSelectionConflicts, formatSearchProgress, formatOutsideRootSummary, gatherCandidateStats, identicalCopiesSuffix, mapWithLimit, pendingNameError, sortCandidates } from "./setup-display.js";
 import { inspectPreparedResource, maskSensitiveText } from "./inspect.js";
 import { assertNameAvailable, assertNoNameConflicts, findNameConflicts, nameKey } from "./names.js";
 import { executeApply, planApply } from "./apply.js";
@@ -89,11 +90,11 @@ const previewMaxBytes = 1_000_000;
 const previewMaxFiles = 12;
 const previewMaxLines = 24;
 export function buildSearchOptions(roots, scopes) {
-    if (!scopes.home && !scopes.project)
+    if (!scopes.home && !scopes.project && !scopes.piDirs)
         return undefined;
     return {
         ...roots,
-        scopes: { home: scopes.home, project: scopes.project },
+        scopes: { home: scopes.home, project: scopes.project, ...(scopes.piDirs ? { piDirs: true } : {}) },
     };
 }
 export function formatMaskedPreview(relativePath, content) {
@@ -133,6 +134,12 @@ export async function saveReviewedCandidate(libraryDir, review, groupIds, approv
         approvedSensitivePaths,
     });
 }
+function showSearchWarnings(warnings, home) {
+    const summary = formatOutsideRootSummary(warnings.filter((warning) => warning.code === "resource-outside-root" && warning.path !== undefined).map((warning) => warning.path), home);
+    if (summary)
+        note(summary.body, summary.title);
+    showWarnings(warnings.filter((warning) => warning.code !== "resource-outside-root" || warning.path === undefined), "Search warnings");
+}
 function showWarnings(warnings, title) {
     if (warnings.length === 0)
         return;
@@ -267,12 +274,17 @@ async function handleNameConflicts(libraryDir) {
             await resolveNameConflicts(libraryDir);
     }
 }
-function groupOptions(groups) {
-    return groups.map((group) => ({ value: group.id, label: group.name, hint: `${group.itemIds.length} saved resources` }));
+function groupOptions(groups, pendingCounts) {
+    return groups.map((group) => ({
+        value: group.id,
+        label: group.name,
+        hint: pendingCounts ? `${group.itemIds.length} saved \u00b7 ${pendingCounts.get(group.id) ?? 0} pending` : `${group.itemIds.length} saved resources`,
+    }));
 }
-async function askForGroupName(message) {
+async function askForGroupName(message, placeholder) {
     const value = await text({
         message,
+        ...(placeholder !== undefined ? { placeholder } : {}),
         validate: (name) => {
             try {
                 nameKey(name ?? "");
@@ -285,6 +297,106 @@ async function askForGroupName(message) {
     });
     return isCancel(value) ? undefined : value.trim();
 }
+/**
+ * Rename prompt text. The suggestion is prefilled only when it renders unchanged through `safeDisplay`
+ * (`initialValue` is echoed raw); otherwise the field stays empty and the masked suggestion is shown in the message.
+ */
+export function renamePrompt(name, sourceDir, suggestion) {
+    const message = `New display name for ${name} \u2014 ${sourceDir} (display name only; files are not changed)`;
+    return safeDisplay(suggestion) === suggestion
+        ? { message, initialValue: suggestion }
+        : { message: `${message}. Suggestion: ${suggestion}` };
+}
+/**
+ * Resolve display-name conflicts right after selection (#9): within the selection first, one group at a time,
+ * then against saved library names. Returns the candidates to review (renamed ones are copies with a new
+ * display name only), "back" to re-show the list, or "cancel".
+ */
+async function resolveSelectedNames(selection, library, labels, homeDir) {
+    let pending = [...selection];
+    const libraryKeys = new Set(library.items.map((item) => nameKey(item.name)));
+    const askNewName = async (candidate, group = [candidate]) => {
+        // Taken: every saved name and every other pending name (assertNameAvailable semantics for the library).
+        const taken = new Set([...libraryKeys, ...pending.filter((other) => other.id !== candidate.id).map((other) => nameKey(other.name))]);
+        const value = await text({
+            ...renamePrompt(candidate.name, displayPath(path.dirname(candidate.sourcePath), homeDir), defaultRenameName(candidate, group)),
+            validate: (name) => {
+                const error = pendingNameError(name, taken);
+                if (error)
+                    return error;
+                try {
+                    assertNameAvailable(library, "item", name ?? "");
+                    return undefined;
+                }
+                catch {
+                    return "That name is already used by a saved or selected resource; choose another.";
+                }
+            },
+        });
+        return isCancel(value) ? undefined : value.trim();
+    };
+    const rename = (candidate, name) => {
+        pending = pending.map((entry) => (entry.id === candidate.id ? { ...entry, name } : entry));
+    };
+    for (const group of findSelectionConflicts(pending)) {
+        const choice = await select({
+            message: `${group.length} selected resources share the name ${group[0].name}; choose what to save`,
+            options: [
+                ...group.map((candidate) => ({ value: `keep:${candidate.id}`, label: `Keep ${labels.get(candidate.id) ?? candidate.name}` })),
+                { value: "rename", label: "Keep all and rename the others" },
+                { value: "back", label: "Go back to the list" },
+            ],
+        });
+        if (isCancel(choice))
+            return "cancel";
+        if (choice === "back")
+            return "back";
+        if (choice === "rename") {
+            for (const candidate of group.slice(1)) {
+                const name = await askNewName(pending.find((entry) => entry.id === candidate.id), group);
+                if (name === undefined)
+                    return "cancel";
+                rename(candidate, name);
+            }
+        }
+        else {
+            const kept = choice.slice("keep:".length);
+            const dropped = new Set(group.filter((candidate) => candidate.id !== kept).map((candidate) => candidate.id));
+            pending = pending.filter((candidate) => !dropped.has(candidate.id));
+        }
+    }
+    for (const candidate of [...pending]) {
+        if (!libraryKeys.has(nameKey(candidate.name)))
+            continue;
+        const choice = await select({
+            message: `${candidate.name} \u2014 ${displayPath(path.dirname(candidate.sourcePath), homeDir)}: a saved resource already uses this name. To update the saved copy, use Refresh in copi manage.`,
+            options: [
+                { value: "skip", label: "Skip (keep the saved copy)" },
+                { value: "rename", label: "Rename" },
+                { value: "back", label: "Go back to the list" },
+            ],
+        });
+        if (isCancel(choice))
+            return "cancel";
+        if (choice === "back")
+            return "back";
+        if (choice === "skip") {
+            pending = pending.filter((entry) => entry.id !== candidate.id);
+            continue;
+        }
+        const name = await askNewName(candidate);
+        if (name === undefined)
+            return "cancel";
+        rename(candidate, name);
+    }
+    return pending;
+}
+/** Quote for POSIX shells only when needed (single quotes, embedded quotes escaped as '\\''). */
+function shellQuote(value) {
+    if (value === "<group>" || /^[A-Za-z0-9_.\/@%+=:,-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
 export async function runSetup(libraryDir, roots) {
     if (await handleNameConflicts(libraryDir))
         return;
@@ -292,36 +404,39 @@ export async function runSetup(libraryDir, roots) {
     assertModernCatalog(initial);
     assertNoNameConflicts(initial);
     intro("copi setup");
-    const scopeOptions = [];
-    if (roots.homeDir) {
-        scopeOptions.push({
-            value: "home",
-            label: `Search entire HOME: ${roots.homeDir}`,
-            hint: `Includes supported Pi resources under HOME and Pi agent directory ${roots.agentDir}`,
-        });
-    }
-    scopeOptions.push({ value: "project", label: `Search current project: ${roots.projectDir}`, hint: "Supported Pi resources and instruction files in this project" });
-    const selectedScopes = await autocompleteMultiselect({
+    const homeDir = roots.homeDir;
+    const projectLabel = displayPath(roots.projectDir, homeDir);
+    const homeBase = homeDir.length > 1 && homeDir.endsWith(path.sep) ? homeDir.slice(0, -1) : homeDir;
+    const projectIsHome = Boolean(homeDir) && roots.projectDir === homeBase;
+    const projectInsideHome = Boolean(homeDir) && !projectIsHome && roots.projectDir.startsWith(homeBase + path.sep);
+    const locationOptions = [];
+    if (homeDir) {
+        locationOptions.push({ value: "pi", label: "Pi agent directories only \u2014 ~/.pi/agent, ~/.pi/agent-*, ~/.agents (fast)" });
+        locationOptions.push({ value: "home", label: "All of HOME \u2014 ~ (can take a minute or more; worktree copies skipped)" });
+    }
+    if (!projectIsHome)
+        locationOptions.push({ value: "project", label: `This project only \u2014 ${projectLabel} (fast)` });
+    if (homeDir && !projectIsHome && !projectInsideHome)
+        locationOptions.push({ value: "both", label: "Both" });
+    locationOptions.push({ value: "cancel", label: "Cancel" });
+    const choice = await select({
         message: "Choose the locations copi may inspect",
-        options: scopeOptions,
-        required: false,
-        placeholder: "Search locations...",
+        options: locationOptions,
+        initialValue: locationOptions[0].value,
     });
-    if (isCancel(selectedScopes)) {
+    if (isCancel(choice) || choice === "cancel") {
         cancel("Setup cancelled.");
         return;
     }
-    const scopes = { home: selectedScopes.includes("home"), project: selectedScopes.includes("project") };
-    const searchOptions = buildSearchOptions(roots, scopes);
-    if (!searchOptions) {
-        outro("No locations selected; nothing was searched or saved.");
-        return;
-    }
+    const scopes = { home: choice === "home" || choice === "both", project: choice === "project" || choice === "both", ...(choice === "pi" ? { piDirs: true } : {}) };
+    const piDirectories = choice === "pi" ? (await piAgentDirectories(homeDir)).directories : [];
+    const searchOptions = buildSearchOptions(roots, scopes); // every non-cancel choice enables at least one scope
     note([
-        `HOME: ${scopes.home ? roots.homeDir : "not selected"}`,
-        `Pi agent directory: ${scopes.home ? roots.agentDir : "not selected"}`,
-        `Project: ${scopes.project ? roots.projectDir : "not selected"}`,
-        "Always excluded: entire directories named auth (authentication-specific code may be missing), auth.json, mcp-auth.json, oauth.json, .env* paths, history, cache/caches, .cache, .npm, node_modules, and .git.",
+        `HOME: ${scopes.home ? displayPath(roots.homeDir, homeDir) : "not selected"}`,
+        `Pi agent directory: ${scopes.home ? displayPath(roots.agentDir, homeDir) : choice === "pi" ? (piDirectories.map((dir) => displayPath(dir, homeDir)).join(", ") || "none found") : "not selected"}`,
+        `Project: ${scopes.project ? projectLabel : "not selected"}`,
+        "Always excluded: entire directories named auth (authentication-specific code may be missing), auth.json, mcp-auth.json, oauth.json, .env* paths, history, cache/caches, .cache, .npm, node_modules, and .git. Folder searches also skip worktree copies (.worktrees, .claude/worktrees, .config/superpowers/worktrees, .treehouse).",
+        ...(choice === "pi" ? ["Settings and packages declared by these Pi profiles may point elsewhere under HOME; those configured paths are read too."] : []),
         "Secret detection is heuristic and cannot guarantee completeness. Preview text is masked by default.",
     ].join("\n"), "Search scope and exclusions");
     const authorized = await confirm({
@@ -332,46 +447,90 @@ export async function runSetup(libraryDir, roots) {
         outro("Search not authorized; no resources were inspected or saved.");
         return;
     }
-    const progress = clackSpinner(inheritedSignal());
-    progress.start("Searching selected locations (searching all of HOME can take a minute or more)");
+    // A spinner covers the quick phases; once HOME's top-level directories are known, a bar fills one step per directory.
+    let indicator = clackSpinner(inheritedSignal());
+    indicator.start("Searching selected locations (searching all of HOME can take a minute or more)");
+    let bar;
+    let barDone = 0;
+    const onProgress = (event) => {
+        if (!bar) {
+            if (event.total === 0)
+                return;
+            indicator.clear();
+            bar = clackProgress({ ...inheritedSignal(), max: event.total });
+            indicator = bar;
+            bar.start(safeDisplay(formatSearchProgress(event, homeDir)));
+            return;
+        }
+        const step = event.done - barDone;
+        barDone = event.done;
+        bar.advance(step, safeDisplay(formatSearchProgress(event, homeDir)));
+    };
     let discovery;
     try {
-        discovery = await discoverResources(searchOptions);
+        discovery = await discoverResources(searchOptions, onProgress);
     }
     catch (error) {
-        progress.error("Search failed");
+        indicator.error("Search failed");
         throw error;
     }
-    progress.stop(`Search complete: ${discovery.candidates.length} supported resource(s) found`);
-    showWarnings(discovery.warnings, "Search warnings");
-    if (discovery.excludedPaths.length > 0)
-        note(discovery.excludedPaths.join("\n"), "Excluded paths");
+    indicator.stop(`Search complete: ${discovery.candidates.length} supported resource(s) found`);
+    showSearchWarnings(discovery.warnings, roots.homeDir);
+    const worktreeCopies = discovery.excludedPaths.filter((excluded) => isWorktreeCopy(path.relative(homeDir || path.sep, excluded)));
+    const otherExcluded = discovery.excludedPaths.filter((excluded) => !worktreeCopies.includes(excluded));
+    if (worktreeCopies.length > 0)
+        log.info(safeDisplay(`Skipped ${worktreeCopies.length} worktree copy folder(s).`));
+    if (otherExcluded.length > 0)
+        note(otherExcluded.map((excluded) => displayPath(excluded, homeDir)).join("\n"), "Excluded paths");
     if (discovery.candidates.length === 0) {
         outro("No supported resources were found.");
         return;
     }
-    const selectedIds = await autocompleteMultiselect({
-        message: "Select resources to review and save as copied snapshots",
-        options: discovery.candidates.map((candidate) => ({
-            value: candidate.id,
-            label: `[${candidate.kind}] ${candidate.name}`,
-            hint: `${candidate.scope} · ${candidate.sourcePath} · ${candidate.destination.kind === "global-only" ? "save only" : candidate.destination.path}`,
-        })),
-        required: false,
-        placeholder: "Filter resources...",
-    });
-    if (isCancel(selectedIds)) {
-        cancel("Setup cancelled; no resources were saved.");
-        return;
+    const allSorted = sortCandidates(discovery.candidates);
+    const fingerprints = new Map(await mapWithLimit(allSorted, 16, async (candidate) => [candidate.id, await contentFingerprint(candidate)]));
+    const { kept: sortedCandidates, copies: identicalCopies } = collapseIdenticalCandidates(allSorted, fingerprints, homeDir);
+    const merged = allSorted.length - sortedCandidates.length;
+    if (merged > 0)
+        log.info(safeDisplay(`Merged ${merged} identical copies; ${sortedCandidates.length} distinct resource(s) to choose from.`));
+    const candidateStats = await gatherCandidateStats(sortedCandidates);
+    const savedNames = new Set(initial.items.map((item) => nameKey(item.name)));
+    const candidateLabelMap = candidateLabels(sortedCandidates, homeDir, (candidate) => savedNames.has(nameKey(candidate.name)), process.stdout.columns);
+    let previousSelection = [];
+    let resolvedCandidates;
+    while (true) {
+        const selectedIds = await autocompleteMultiselect({
+            message: "Select resources to review and save as copied snapshots",
+            options: sortedCandidates.map((candidate) => {
+                const label = candidateLabelMap.get(candidate.id) + identicalCopiesSuffix(identicalCopies.get(candidate.id));
+                return { value: candidate.id, label, hint: candidateHint(candidate, candidateStats.get(candidate.id) ?? {}, homeDir, process.stdout.columns, label.length) };
+            }),
+            required: false,
+            initialValues: previousSelection,
+            placeholder: "Filter resources...",
+        });
+        if (isCancel(selectedIds)) {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        previousSelection = selectedIds;
+        const outcome = await resolveSelectedNames(sortedCandidates.filter((candidate) => selectedIds.includes(candidate.id)), initial, candidateLabelMap, homeDir);
+        if (outcome === "cancel") {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        if (outcome === "back")
+            continue;
+        resolvedCandidates = outcome;
+        break;
     }
-    if (selectedIds.length === 0) {
+    if (resolvedCandidates.length === 0) {
         outro("No resources selected; nothing was saved.");
         return;
     }
     const catalog = await loadCatalog(libraryDir);
     assertModernCatalog(catalog);
     if (catalog.groups.length === 0) {
-        const name = await askForGroupName("Create the first resource group");
+        const name = await askForGroupName("Create the first resource group \u2014 used later with: copi apply <group>", "e.g. game-review");
         if (name === undefined) {
             cancel("Setup cancelled; no resources were saved.");
             return;
@@ -395,12 +554,53 @@ export async function runSetup(libraryDir, roots) {
             createGroup(catalog, name);
         }
     }
-    const selectedCandidates = discovery.candidates.filter((candidate) => selectedIds.includes(candidate.id));
+    // Keep discovery order for review; renamed copies replace their originals by id.
+    const resolvedById = new Map(resolvedCandidates.map((candidate) => [candidate.id, candidate]));
+    const selectedCandidates = discovery.candidates.flatMap((candidate) => resolvedById.get(candidate.id) ?? []);
     const approvedCandidates = [];
-    for (const candidate of selectedCandidates) {
+    // Decide the assignment mode once; "bulk" assigns every approved resource to bulkGroupIds.
+    let bulkGroupIds;
+    const count = selectedCandidates.length;
+    const onlyGroup = catalog.groups.length === 1 ? catalog.groups[0] : undefined;
+    let bulk = count === 1;
+    if (count >= 2) {
+        const mode = await select({
+            message: "How should these resources be grouped?",
+            options: [
+                { value: "all", label: onlyGroup ? `Put all ${count} resources in "${onlyGroup.name}"` : `Put all ${count} resources in the same groups` },
+                { value: "each", label: "Choose groups for each resource" },
+            ],
+            initialValue: "all",
+        });
+        if (isCancel(mode)) {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        bulk = mode === "all";
+    }
+    if (bulk) {
+        if (onlyGroup)
+            bulkGroupIds = [onlyGroup.id];
+        else {
+            const chosen = await autocompleteMultiselect({
+                message: count === 1 ? `Assign ${selectedCandidates[0].name} to one or more groups` : `Put all ${count} resources in these groups`,
+                options: groupOptions(catalog.groups),
+                required: true,
+                placeholder: "Filter groups...",
+            });
+            if (isCancel(chosen)) {
+                cancel("Setup cancelled; no resources were saved.");
+                return;
+            }
+            bulkGroupIds = chosen;
+        }
+    }
+    for (const [index, candidate] of selectedCandidates.entries()) {
         const review = await prepareCandidateForReview(candidate);
-        note(review.preview.length > 0 ? review.preview.join("\n\n") : "No previewable files.", `Masked preview: ${review.candidate.name}`);
-        showWarnings(review.inspection.warnings, `${review.candidate.name} inspection warnings`);
+        const previewTitle = `Masked preview (${index + 1}/${count}): ${review.candidate.name} \u2014 ${displayPath(path.dirname(candidate.sourcePath), homeDir)}`;
+        note(review.preview.length > 0 ? review.preview.join("\n\n") : "No previewable files.", previewTitle);
+        // The heuristic caveat is stated once in the scope note and the summary; per-resource it would only repeat.
+        showWarnings(review.inspection.warnings.filter((warning) => warning.code !== "secret-detection-limited"), `${review.candidate.name} inspection warnings`);
         if (review.inspection.excludedPaths.length > 0) {
             note(review.inspection.excludedPaths.join("\n"), `${review.candidate.name} excluded paths`);
         }
@@ -408,7 +608,7 @@ export async function runSetup(libraryDir, roots) {
         const approvedSensitivePaths = [];
         for (const relativePath of review.inspection.sensitivePaths) {
             const approval = await confirm({
-                message: `Save suspected sensitive file ${relativePath} from ${review.candidate.name}? Detection is heuristic; the file content remains masked in previews.`,
+                message: `Save suspected sensitive file ${relativePath} from ${review.candidate.name}? Detection is heuristic; the file content remains masked in previews. No = ${review.candidate.name} will not be saved at all.`,
                 initialValue: false,
             });
             if (isCancel(approval)) {
@@ -424,9 +624,17 @@ export async function runSetup(libraryDir, roots) {
             log.warn(safeDisplay(`${review.candidate.name} was not selected for saving because a suspected sensitive file was not approved.`));
             continue;
         }
+        if (bulkGroupIds) {
+            approvedCandidates.push({ review, groupIds: bulkGroupIds, approvedSensitivePaths });
+            continue;
+        }
+        const pendingCounts = new Map();
+        for (const approved of approvedCandidates)
+            for (const id of approved.groupIds)
+                pendingCounts.set(id, (pendingCounts.get(id) ?? 0) + 1);
         const groupIds = await autocompleteMultiselect({
             message: `Assign ${review.candidate.name} to one or more groups`,
-            options: groupOptions(catalog.groups),
+            options: groupOptions(catalog.groups, pendingCounts),
             required: true,
             placeholder: "Filter groups...",
         });
@@ -444,9 +652,10 @@ export async function runSetup(libraryDir, roots) {
         const names = groupIds.map((id) => catalog.groups.find((group) => group.id === id)?.name ?? "Unavailable group").join(", ");
         return `${review.candidate.name} → ${names}`;
     }).join("\n");
-    note(summary, "Resources ready to copy");
+    note(`${summary}\n\nSecret detection is heuristic and cannot guarantee completeness.`, "Resources ready to copy");
+    const libraryLabel = displayPath(libraryDir, homeDir);
     const save = await confirm({
-        message: `Save ${approvedCandidates.length} copied resource(s) in ${libraryDir}? Original files will not be changed.`,
+        message: `Save ${approvedCandidates.length} copied resource(s) in ${libraryLabel}? Original files will not be changed.`,
         initialValue: false,
     });
     if (isCancel(save) || !save) {
@@ -469,7 +678,10 @@ export async function runSetup(libraryDir, roots) {
     for (const { review, groupIds, approvedSensitivePaths } of approvedCandidates) {
         await saveReviewedCandidate(libraryDir, review, groupIds, approvedSensitivePaths, true);
     }
-    outro(`Saved ${approvedCandidates.length} copied resource(s) in ${libraryDir}.`);
+    const usedGroupIds = new Set(approvedCandidates.flatMap(({ groupIds }) => groupIds));
+    const usedGroups = catalog.groups.filter((group) => usedGroupIds.has(group.id)).map((group) => group.name);
+    log.info(safeDisplay(`Saved ${approvedCandidates.length} copied resource(s) in ${libraryLabel} (group: ${usedGroups.join(", ")}).`));
+    outro(`Next: copi apply ${shellQuote(usedGroups[0] ?? "<group>")} <project> --dry-run   (edit or rename: copi manage)`);
 }
 export async function runGroupManager(libraryDir) {
     if (await handleNameConflicts(libraryDir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papillon6814/copi",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Collect and organize reusable Pi coding-agent resources",
   "license": "MIT",
   "type": "module",