@phren/cli 0.0.10 → 0.0.11

package/mcp/dist/index.js

@@ -48,13 +48,13 @@ function cleanStaleLocks(phrenPath) {
                 }
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                if ((process.env.PHREN_DEBUG))
                     process.stderr.write(`[phren] cleanStaleLocks statFile: ${errorMessage(err)}\n`);
             }
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] cleanStaleLocks readdir: ${errorMessage(err)}\n`);
     }
 }
@@ -88,7 +88,7 @@ async function main() {
             db?.close();
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] rebuildIndex dbClose: ${errorMessage(err)}\n`);
         }
         db = await buildIndex(phrenPath, profile);
@@ -158,7 +158,7 @@ async function main() {
                 trackToolCall(phrenPath, registeredName);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                if ((process.env.PHREN_DEBUG))
                     process.stderr.write(`[phren] trackToolCall: ${errorMessage(err)}\n`);
             }
             return handler(...args);

package/mcp/dist/init-config.js

@@ -4,27 +4,16 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { randomUUID } from "crypto";
-import { execFileSync } from "child_process";
-import { buildLifecycleCommands } from "./hooks.js";
-import { EXEC_TIMEOUT_QUICK_MS, isRecord, hookConfigPath, homePath, readRootManifest, } from "./shared.js";
+import { buildLifecycleCommands, commandExists } from "./hooks.js";
+import { isRecord, hookConfigPath, homePath, readRootManifest, atomicWriteText, } from "./shared.js";
 import { isFeatureEnabled, errorMessage } from "./utils.js";
 import { probeVsCodeConfig, resolveCodexMcpConfig, resolveCopilotMcpConfig, resolveCursorMcpConfig, } from "./provider-adapters.js";
 import { getMcpEnabledPreference, getHooksEnabledPreference } from "./init-preferences.js";
-import { resolveEntryScript, VERSION } from "./init-shared.js";
-function log(msg) {
-    process.stdout.write(msg + "\n");
-}
+import { resolveEntryScript, log, VERSION } from "./init-shared.js";
 function getObjectProp(value, key) {
     const candidate = value[key];
     return isRecord(candidate) ? candidate : undefined;
 }
-function atomicWriteText(filePath, content) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const tmpPath = `${filePath}.tmp-${randomUUID()}`;
-    fs.writeFileSync(tmpPath, content);
-    fs.renameSync(tmpPath, filePath);
-}
 export function patchJsonFile(filePath, patch) {
     let data = {};
     if (fs.existsSync(filePath)) {
@@ -44,16 +33,6 @@ export function patchJsonFile(filePath, patch) {
     patch(data);
     atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
 }
-function commandExists(cmd) {
-    try {
-        const whichCmd = process.platform === "win32" ? "where.exe" : "which";
-        execFileSync(whichCmd, [cmd], { stdio: ["ignore", "ignore", "ignore"], timeout: EXEC_TIMEOUT_QUICK_MS });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function buildMcpServerConfig(phrenPath) {
     const entryScript = resolveEntryScript();
     if (entryScript && fs.existsSync(entryScript)) {

package/mcp/dist/init-setup.js

@@ -1087,14 +1087,14 @@ export function updateMachinesYaml(phrenPath, machine, profile) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] updateMachinesYaml parse: ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] updateMachinesYaml parse: ${errorMessage(err)}\n`);
     }
     // Passive init/link refreshes should keep an existing mapping; explicit overrides can remap.
     if (hasExistingMapping && !machine && !profile)
         return;
     const mapping = setMachineProfile(phrenPath, machineName, profileName);
-    if (!mapping.ok && (process.env.PHREN_DEBUG || process.env.PHREN_DEBUG)) {
+    if (!mapping.ok && (process.env.PHREN_DEBUG)) {
         process.stderr.write(`[phren] updateMachinesYaml setMachineProfile: ${mapping.error}\n`);
     }
 }
@@ -1289,8 +1289,8 @@ export function runPostInitVerify(phrenPath) {
         ftsOk = entries.some(d => d.isDirectory() && !d.name.startsWith("."));
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] runPostInitVerify projectScan: ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] runPostInitVerify projectScan: ${errorMessage(err)}\n`);
         ftsOk = false;
     }
     checks.push({

package/mcp/dist/init.js

@@ -8,7 +8,7 @@ import * as crypto from "crypto";
 import { execFileSync } from "child_process";
 import { configureAllHooks } from "./hooks.js";
 import { getMachineName, machineFilePath, persistMachineName } from "./machine-identity.js";
-import { atomicWriteText, debugLog, isRecord, hookConfigPath, homeDir, homePath, expandHomePath, findPhrenPath, readRootManifest, writeRootManifest, } from "./shared.js";
+import { atomicWriteText, debugLog, isRecord, hookConfigPath, homeDir, homePath, expandHomePath, findPhrenPath, getProjectDirs, readRootManifest, writeRootManifest, } from "./shared.js";
 import { isValidProjectName, errorMessage } from "./utils.js";
 import { codexJsonCandidates, copilotMcpCandidates, cursorMcpCandidates, vscodeMcpCandidates, } from "./provider-adapters.js";
 export { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, resetVSCodeProbeCache, patchJsonFile, } from "./init-config.js";
@@ -406,7 +406,7 @@ async function runWalkthrough(phrenPath) {
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] init ollamaCheck: ${errorMessage(err)}\n`);
     }
     printSection("Auto-Capture (Optional)");
@@ -910,32 +910,36 @@ export async function runInit(opts = {}) {
     }
     let phrenPath = resolveInitPhrenPath(opts);
     const dryRun = Boolean(opts.dryRun);
-    // Migrate ~/.cortex → ~/.phren when upgrading from the old name.
-    // Only runs when the resolved phrenPath doesn't exist yet but ~/.cortex does.
+    // Migrate the legacy hidden store directory into ~/.phren when upgrading
+    // from the previous product name. Only runs when the resolved phrenPath
+    // doesn't exist yet but the legacy directory does.
     if (!opts._walkthroughStoragePath && !fs.existsSync(phrenPath)) {
-        const cortexPath = path.resolve(homePath(".cortex"));
-        if (cortexPath !== phrenPath && fs.existsSync(cortexPath) && hasInstallMarkers(cortexPath)) {
+        // Pre-rebrand directory name — kept as literal for migration
+        const legacyPath = path.resolve(homePath(".cortex"));
+        if (legacyPath !== phrenPath && fs.existsSync(legacyPath) && hasInstallMarkers(legacyPath)) {
             if (!dryRun) {
-                fs.renameSync(cortexPath, phrenPath);
+                fs.renameSync(legacyPath, phrenPath);
             }
-            console.log(`Migrated ~/.cortex → ~/.phren`);
+            console.log(`Migrated legacy store → ~/.phren`);
         }
     }
-    // Rename stale cortex-*.md skill files left over from the rebrand.
-    // Runs on every init so users who already migrated the directory still get the fix.
+    // Rename stale legacy skill names left over from the rebrand. Runs on every
+    // init so users who already migrated the directory still get the fix.
     const skillsMigrateDir = path.join(phrenPath, "global", "skills");
     if (!dryRun && fs.existsSync(skillsMigrateDir)) {
+        const legacySkillName = "cortex.md";
+        const legacySkillPrefix = "cortex-";
         for (const entry of fs.readdirSync(skillsMigrateDir)) {
             if (!entry.endsWith(".md"))
                 continue;
-            if (entry === "cortex.md") {
+            if (entry === legacySkillName) {
                 const dest = path.join(skillsMigrateDir, "phren.md");
                 if (!fs.existsSync(dest)) {
                     fs.renameSync(path.join(skillsMigrateDir, entry), dest);
                 }
             }
-            else if (entry.startsWith("cortex-")) {
-                const newName = entry.replace(/^cortex-/, "phren-");
+            else if (entry.startsWith(legacySkillPrefix)) {
+                const newName = `phren-${entry.slice(legacySkillPrefix.length)}`;
                 const dest = path.join(skillsMigrateDir, newName);
                 if (!fs.existsSync(dest)) {
                     fs.renameSync(path.join(skillsMigrateDir, entry), dest);
@@ -1381,7 +1385,7 @@ export async function runInit(opts = {}) {
             }
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] init ollamaInstallHint: ${errorMessage(err)}\n`);
         }
     }
@@ -1554,7 +1558,122 @@ export async function runHooksMode(modeArg) {
     log(`Claude status: ${claudeStatus}`);
     log(`Restart your agent to apply changes.`);
 }
-export async function runUninstall() {
+// Agent skill directories to sweep for symlinks during uninstall
+function agentSkillDirs() {
+    const home = homeDir();
+    return [
+        homePath(".claude", "skills"),
+        path.join(home, ".cursor", "skills"),
+        path.join(home, ".copilot", "skills"),
+        path.join(home, ".codex", "skills"),
+    ];
+}
+// Remove skill symlinks that resolve inside phrenPath. Only touches symlinks, never regular files.
+function sweepSkillSymlinks(phrenPath) {
+    const resolvedPhren = path.resolve(phrenPath);
+    for (const dir of agentSkillDirs()) {
+        if (!fs.existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            debugLog(`sweepSkillSymlinks: readdirSync failed for ${dir}: ${errorMessage(err)}`);
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isSymbolicLink())
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            try {
+                const target = fs.realpathSync(fullPath);
+                if (target.startsWith(resolvedPhren + path.sep) || target === resolvedPhren) {
+                    fs.unlinkSync(fullPath);
+                    log(`  Removed skill symlink: ${fullPath}`);
+                }
+            }
+            catch (err) {
+                debugLog(`sweepSkillSymlinks: could not check/remove ${fullPath}: ${errorMessage(err)}`);
+            }
+        }
+    }
+}
+// Filter phren hook entries from an agent hooks file. Returns true if the file was changed.
+// Deletes the file if no hooks remain. `commandField` is the JSON key holding the command
+// string in each hook entry (e.g. "bash" for Copilot, "command" for Codex).
+function filterAgentHooks(filePath, commandField) {
+    if (!fs.existsSync(filePath))
+        return false;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (!isRecord(raw) || !isRecord(raw.hooks))
+            return false;
+        const hooks = raw.hooks;
+        let changed = false;
+        for (const event of Object.keys(hooks)) {
+            const entries = hooks[event];
+            if (!Array.isArray(entries))
+                continue;
+            const filtered = entries.filter((e) => !(isRecord(e) && typeof e[commandField] === "string" && isPhrenCommand(e[commandField])));
+            if (filtered.length !== entries.length) {
+                hooks[event] = filtered;
+                changed = true;
+            }
+        }
+        if (!changed)
+            return false;
+        // Remove empty hook event keys
+        for (const event of Object.keys(hooks)) {
+            if (Array.isArray(hooks[event]) && hooks[event].length === 0) {
+                delete hooks[event];
+            }
+        }
+        if (Object.keys(hooks).length === 0) {
+            fs.unlinkSync(filePath);
+        }
+        else {
+            atomicWriteText(filePath, JSON.stringify(raw, null, 2));
+        }
+        return true;
+    }
+    catch (err) {
+        debugLog(`filterAgentHooks: failed for ${filePath}: ${errorMessage(err)}`);
+        return false;
+    }
+}
+async function promptUninstallConfirm(phrenPath) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return true;
+    // Show summary of what will be deleted
+    try {
+        const projectDirs = getProjectDirs(phrenPath);
+        const projectCount = projectDirs.length;
+        let findingCount = 0;
+        for (const dir of projectDirs) {
+            const findingsFile = path.join(dir, "FINDINGS.md");
+            if (fs.existsSync(findingsFile)) {
+                const content = fs.readFileSync(findingsFile, "utf8");
+                findingCount += content.split("\n").filter((l) => l.startsWith("- ")).length;
+            }
+        }
+        log(`\n  Will delete: ${phrenPath}`);
+        log(`  Contains: ${projectCount} project(s), ~${findingCount} finding(s)`);
+    }
+    catch (err) {
+        debugLog(`promptUninstallConfirm: summary failed: ${errorMessage(err)}`);
+        log(`\n  Will delete: ${phrenPath}`);
+    }
+    const readline = await import("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`\nThis will permanently delete ${phrenPath} and all phren data. Type 'yes' to confirm: `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === "yes");
+        });
+    });
+}
+export async function runUninstall(opts = {}) {
     const phrenPath = findPhrenPath();
     const manifest = phrenPath ? readRootManifest(phrenPath) : null;
     if (manifest?.installMode === "project-local" && phrenPath) {
@@ -1575,6 +1694,27 @@ export async function runUninstall() {
         return;
     }
     log("\nUninstalling phren...\n");
+    // Confirmation prompt (shared-mode only — project-local is low-stakes)
+    if (!opts.yes) {
+        const confirmed = phrenPath
+            ? await promptUninstallConfirm(phrenPath)
+            : (process.stdin.isTTY && process.stdout.isTTY
+                ? await (async () => {
+                    const readline = await import("readline");
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                    return new Promise((resolve) => {
+                        rl.question("This will remove all phren config and hooks. Type 'yes' to confirm: ", (answer) => {
+                            rl.close();
+                            resolve(answer.trim().toLowerCase() === "yes");
+                        });
+                    });
+                })()
+                : true);
+        if (!confirmed) {
+            log("Uninstall cancelled.");
+            return;
+        }
+    }
     const home = homeDir();
     const machineFile = machineFilePath();
     const settingsPath = hookConfigPath("claude");
@@ -1677,12 +1817,11 @@ export async function runUninstall() {
             debugLog(`uninstall: cleanup failed for ${mcpFile}: ${errorMessage(err)}`);
         }
     }
-    // Remove Copilot hooks file (written by configureAllHooks)
+    // Remove phren entries from Copilot hooks file (filter, don't bulk-delete)
     const copilotHooksFile = hookConfigPath("copilot", (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
     try {
-        if (fs.existsSync(copilotHooksFile)) {
-            fs.unlinkSync(copilotHooksFile);
-            log(`  Removed Copilot hooks file (${copilotHooksFile})`);
+        if (filterAgentHooks(copilotHooksFile, "bash")) {
+            log(`  Removed phren entries from Copilot hooks (${copilotHooksFile})`);
         }
     }
     catch (err) {
@@ -1709,13 +1848,12 @@ export async function runUninstall() {
     catch (err) {
         debugLog(`uninstall: cleanup failed for ${cursorHooksFile}: ${errorMessage(err)}`);
     }
-    // Remove Codex hooks file in phren path
+    // Remove phren entries from Codex hooks file (filter, don't bulk-delete)
     const uninstallPhrenPath = (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
     const codexHooksFile = hookConfigPath("codex", uninstallPhrenPath);
     try {
-        if (fs.existsSync(codexHooksFile)) {
-            fs.unlinkSync(codexHooksFile);
-            log(`  Removed Codex hooks file (${codexHooksFile})`);
+        if (filterAgentHooks(codexHooksFile, "command")) {
+            log(`  Removed phren entries from Codex hooks (${codexHooksFile})`);
         }
     }
     catch (err) {
@@ -1748,6 +1886,15 @@ export async function runUninstall() {
     catch (err) {
         debugLog(`uninstall: cleanup failed for ${machineFile}: ${errorMessage(err)}`);
     }
+    // Sweep agent skill directories for symlinks pointing into the phren store
+    if (phrenPath) {
+        try {
+            sweepSkillSymlinks(phrenPath);
+        }
+        catch (err) {
+            debugLog(`uninstall: skill symlink sweep failed: ${errorMessage(err)}`);
+        }
+    }
     if (phrenPath && fs.existsSync(phrenPath)) {
         try {
             fs.rmSync(phrenPath, { recursive: true, force: true });

package/mcp/dist/link-checksums.js

@@ -3,6 +3,7 @@ import * as path from "path";
 import * as crypto from "crypto";
 import { getProjectDirs } from "./shared.js";
 import { TASK_FILE_ALIASES } from "./data-tasks.js";
+import { errorMessage } from "./utils.js";
 function fileChecksum(filePath) {
     const content = fs.readFileSync(filePath);
     return crypto.createHash("sha256").update(content).digest("hex");
@@ -18,8 +19,8 @@ function loadChecksums(phrenPath) {
         return JSON.parse(fs.readFileSync(file, "utf8"));
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] loadChecksums: ${err instanceof Error ? err.message : String(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] loadChecksums: ${errorMessage(err)}\n`);
         return {};
     }
 }

package/mcp/dist/link-context.js

@@ -4,7 +4,7 @@ import * as yaml from "js-yaml";
 import { isValidProjectName } from "./utils.js";
 import { homeDir, homePath } from "./shared.js";
 import { resolveTaskFilePath } from "./data-tasks.js";
-function log(msg) { process.stdout.write(msg + "\n"); }
+import { log } from "./init-shared.js";
 function contextFilePath() {
     return homePath(".phren-context.md");
 }

package/mcp/dist/link-doctor.js

@@ -199,14 +199,14 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         fsMs = Date.now() - t0;
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] doctor fsBenchmark: ${errorMessage(err)}\n`);
         fsMs = -1;
         try {
             fs.unlinkSync(fsBenchFile);
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] doctor fsBenchmarkCleanup: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
         }
     }
@@ -329,7 +329,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
             runtime = JSON.parse(fs.readFileSync(runtimeHealthPath, "utf8"));
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] doctor runtimeHealth: ${errorMessage(err)}\n`);
             runtime = null;
         }

package/mcp/dist/link-skills.js

@@ -108,7 +108,75 @@ export function readSkillManifestHooks(phrenPath) {
     }
     return Object.keys(result).length > 0 ? result : null;
 }
-// ── Skill linking helpers ───────────────────────────────────────────────────
+/**
+ * Returns true if `destPath` is a symlink whose resolved target lives under
+ * `managedRoot`.  Used to decide whether phren owns a symlink.
+ */
+export function isManagedSymlink(destPath, managedRoot) {
+    try {
+        const stat = fs.lstatSync(destPath);
+        if (!stat.isSymbolicLink())
+            return false;
+        const target = fs.readlinkSync(destPath);
+        const resolvedTarget = path.resolve(path.dirname(destPath), target);
+        const managedPrefix = path.resolve(managedRoot) + path.sep;
+        return resolvedTarget.startsWith(managedPrefix);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns true if `destPath` exists and is NOT a symlink that points into
+ * managedRoot — i.e. it's a file/dir the user owns.
+ */
+function isUserOwnedFile(destPath, managedRoot) {
+    try {
+        fs.lstatSync(destPath);
+    }
+    catch {
+        return false; // doesn't exist
+    }
+    return !isManagedSymlink(destPath, managedRoot);
+}
+/**
+ * Scan destDir for files that phren would want to link (based on srcDir) but
+ * can't because a user-owned file already occupies the destination slot.
+ */
+export function detectSkillCollisions(srcDir, destDir, managedRoot) {
+    if (!fs.existsSync(srcDir) || !fs.existsSync(destDir))
+        return [];
+    const collisions = [];
+    for (const entry of fs.readdirSync(srcDir)) {
+        const srcPath = path.join(srcDir, entry);
+        const stat = fs.statSync(srcPath);
+        if (stat.isFile() && entry.endsWith(".md")) {
+            const destPath = path.join(destDir, entry);
+            if (isUserOwnedFile(destPath, managedRoot)) {
+                const skillName = entry.replace(/\.md$/, "");
+                collisions.push({
+                    skillName,
+                    destPath,
+                    message: `Skill '${skillName}' — user file already exists at ${destPath}. Rename or remove it to use phren's version.`,
+                });
+            }
+        }
+        else if (stat.isDirectory()) {
+            const skillFile = path.join(srcPath, "SKILL.md");
+            if (fs.existsSync(skillFile)) {
+                const destPath = path.join(destDir, entry);
+                if (isUserOwnedFile(destPath, managedRoot)) {
+                    collisions.push({
+                        skillName: entry,
+                        destPath,
+                        message: `Skill '${entry}' — user directory already exists at ${destPath}. Rename or remove it to use phren's version.`,
+                    });
+                }
+            }
+        }
+    }
+    return collisions;
+}
 function cleanupManagedSkillLinks(destDir, expectedNames, managedRoot) {
     if (!fs.existsSync(destDir))
         return;
@@ -117,27 +185,22 @@ function cleanupManagedSkillLinks(destDir, expectedNames, managedRoot) {
             continue;
         const destPath = path.join(destDir, entry);
         try {
-            const stat = fs.lstatSync(destPath);
-            if (!stat.isSymbolicLink())
-                continue;
-            const target = fs.readlinkSync(destPath);
-            const resolvedTarget = path.resolve(path.dirname(destPath), target);
-            const managedPrefix = path.resolve(managedRoot) + path.sep;
-            if (!resolvedTarget.startsWith(managedPrefix))
+            if (!isManagedSymlink(destPath, managedRoot))
                 continue;
             fs.unlinkSync(destPath);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] cleanupManagedSkillLinks: ${errorMessage(err)}\n`);
         }
     }
 }
 export function linkSkillsDir(srcDir, destDir, managedRoot, symlinkFile, opts) {
     if (!fs.existsSync(srcDir))
-        return;
+        return [];
     fs.mkdirSync(destDir, { recursive: true });
     const expectedNames = new Set();
+    const collisions = [];
     for (const entry of fs.readdirSync(srcDir)) {
         const srcPath = path.join(srcDir, entry);
         const stat = fs.statSync(srcPath);
@@ -146,20 +209,43 @@ export function linkSkillsDir(srcDir, destDir, managedRoot, symlinkFile, opts) {
             continue;
         }
         if (stat.isFile() && entry.endsWith(".md")) {
+            const destPath = path.join(destDir, entry);
+            if (isUserOwnedFile(destPath, managedRoot)) {
+                const collision = {
+                    skillName,
+                    destPath,
+                    message: `Skipping skill '${skillName}' — user skill already exists at ${destPath}. To use phren's version, rename or remove your skill first.`,
+                };
+                collisions.push(collision);
+                process.stderr.write(`[phren] ${collision.message}\n`);
+                continue;
+            }
             expectedNames.add(entry);
-            symlinkFile(srcPath, path.join(destDir, entry), managedRoot);
+            symlinkFile(srcPath, destPath, managedRoot);
         }
         else if (stat.isDirectory()) {
             const skillFile = path.join(srcPath, "SKILL.md");
             if (fs.existsSync(skillFile)) {
+                const destPath = path.join(destDir, entry);
+                if (isUserOwnedFile(destPath, managedRoot)) {
+                    const collision = {
+                        skillName,
+                        destPath,
+                        message: `Skipping skill '${skillName}' — user skill already exists at ${destPath}. To use phren's version, rename or remove your skill first.`,
+                    };
+                    collisions.push(collision);
+                    process.stderr.write(`[phren] ${collision.message}\n`);
+                    continue;
+                }
                 expectedNames.add(entry);
                 // Symlink the entire skill directory so bundled scripts and assets are accessible.
                 // Relative paths in the skill body remain valid because the directory structure is preserved.
-                symlinkFile(srcPath, path.join(destDir, entry), managedRoot);
+                symlinkFile(srcPath, destPath, managedRoot);
             }
         }
     }
     cleanupManagedSkillLinks(destDir, expectedNames, managedRoot);
+    return collisions;
 }
 export function writeSkillMd(phrenPath) {
     const lifecycle = buildSharedLifecycleCommands();