@phren/cli 0.0.10 → 0.0.12

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)");
@@ -845,9 +845,11 @@ async function runProjectLocalInit(opts = {}) {
  * Configure MCP for all detected AI coding tools (Claude, VS Code, Cursor, Copilot, Codex).
  * @param verb - label used in log messages, e.g. "Updated" or "Configured"
  */
-function configureMcpTargets(phrenPath, opts, verb) {
+export function configureMcpTargets(phrenPath, opts, verb = "Configured") {
+    let claudeStatus = "no_settings";
     try {
         const status = configureClaude(phrenPath, { mcpEnabled: opts.mcpEnabled, hooksEnabled: opts.hooksEnabled });
+        claudeStatus = status ?? "installed";
         if (status === "disabled" || status === "already_disabled") {
             log(`  ${verb} Claude Code hooks (MCP disabled)`);
         }
@@ -858,31 +860,44 @@ function configureMcpTargets(phrenPath, opts, verb) {
     catch (e) {
         log(`  Could not configure Claude Code settings (${e}), add manually`);
     }
+    let vsStatus = "no_vscode";
     try {
-        const vscodeResult = configureVSCode(phrenPath, { mcpEnabled: opts.mcpEnabled });
-        logMcpTargetStatus("VS Code", vscodeResult, verb);
+        vsStatus = configureVSCode(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_vscode";
+        logMcpTargetStatus("VS Code", vsStatus, verb);
     }
     catch (err) {
         debugLog(`configureVSCode failed: ${errorMessage(err)}`);
     }
+    let cursorStatus = "no_cursor";
     try {
-        logMcpTargetStatus("Cursor", configureCursorMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }), verb);
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_cursor";
+        logMcpTargetStatus("Cursor", cursorStatus, verb);
     }
     catch (err) {
         debugLog(`configureCursorMcp failed: ${errorMessage(err)}`);
     }
+    let copilotStatus = "no_copilot";
     try {
-        logMcpTargetStatus("Copilot CLI", configureCopilotMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }), verb);
+        copilotStatus = configureCopilotMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_copilot";
+        logMcpTargetStatus("Copilot CLI", copilotStatus, verb);
     }
     catch (err) {
         debugLog(`configureCopilotMcp failed: ${errorMessage(err)}`);
     }
+    let codexStatus = "no_codex";
     try {
-        logMcpTargetStatus("Codex", configureCodexMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }), verb);
+        codexStatus = configureCodexMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_codex";
+        logMcpTargetStatus("Codex", codexStatus, verb);
     }
     catch (err) {
         debugLog(`configureCodexMcp failed: ${errorMessage(err)}`);
     }
+    const allStatuses = [claudeStatus, vsStatus, cursorStatus, copilotStatus, codexStatus];
+    if (allStatuses.some((s) => s === "installed" || s === "already_configured"))
+        return "installed";
+    if (allStatuses.some((s) => s === "disabled" || s === "already_disabled"))
+        return "disabled";
+    return claudeStatus;
 }
 /**
  * Configure hooks if enabled, or log a disabled message.
@@ -910,32 +925,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 +1400,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 +1573,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 +1709,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 +1832,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 +1863,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 +1901,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");
 }
@@ -38,7 +38,7 @@ function writeContextFile(managedContent) {
         const existing = fs.readFileSync(contextFile, "utf8");
         if (existing.includes("<!-- phren-managed -->")) {
             const startIdx = existing.indexOf("<!-- phren-managed -->");
-            const endIdx = existing.indexOf("<!-- phren-managed -->");
+            const endIdx = existing.indexOf("<!-- phren-managed -->", startIdx + "<!-- phren-managed -->".length);
             const before = startIdx > 0 ? existing.slice(0, startIdx).trimEnd() : "";
             const after = endIdx !== -1 ? existing.slice(endIdx + "<!-- phren-managed -->".length).trimStart() : "";
             const parts = [before, wrapped, after].filter(Boolean);

package/mcp/dist/link-doctor.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
 import { debugLog, EXEC_TIMEOUT_QUICK_MS, getProjectDirs, isRecord, homeDir, homePath, hookConfigPath, runtimeHealthFile, } from "./shared.js";
+import { commandVersion, versionAtLeast, nearestWritableTarget } from "./init-shared.js";
 import { validateGovernanceJson } from "./shared-governance.js";
 import { errorMessage } from "./utils.js";
 import { buildIndex, queryRows } from "./shared-index.js";
@@ -34,53 +35,6 @@ function isWrapperActive(tool) {
         return false;
     }
 }
-function commandVersion(cmd, args = ["--version"]) {
-    try {
-        return execFileSync(cmd, args, {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: EXEC_TIMEOUT_QUICK_MS,
-        }).trim();
-    }
-    catch (err) {
-        debugLog(`doctor: commandVersion ${cmd} failed: ${errorMessage(err)}`);
-        return null;
-    }
-}
-function parseSemverTriple(raw) {
-    const match = raw.match(/(\d+)\.(\d+)\.(\d+)/);
-    if (!match)
-        return null;
-    return [Number.parseInt(match[1], 10), Number.parseInt(match[2], 10), Number.parseInt(match[3], 10)];
-}
-function versionAtLeast(raw, major, minor = 0) {
-    if (!raw)
-        return false;
-    const parsed = parseSemverTriple(raw);
-    if (!parsed)
-        return false;
-    const [m, n] = parsed;
-    if (m !== major)
-        return m > major;
-    return n >= minor;
-}
-function nearestWritableTarget(filePath) {
-    let probe = fs.existsSync(filePath) ? filePath : path.dirname(filePath);
-    while (!fs.existsSync(probe)) {
-        const parent = path.dirname(probe);
-        if (parent === probe)
-            return false;
-        probe = parent;
-    }
-    try {
-        fs.accessSync(probe, fs.constants.W_OK);
-        return true;
-    }
-    catch (err) {
-        debugLog(`doctor: writable check failed for ${filePath}: ${errorMessage(err)}`);
-        return false;
-    }
-}
 function gitRemoteStatus(phrenPath) {
     try {
         execFileSync("git", ["-C", phrenPath, "rev-parse", "--is-inside-work-tree"], {
@@ -199,14 +153,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 +283,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;
         }
@@ -375,6 +329,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
     const detected = detectInstalledTools();
     if (detected.has("copilot")) {
         const copilotHooks = hookConfigPath("copilot", phrenPath);
+        const copilotWritable = nearestWritableTarget(copilotHooks);
         checks.push({
             name: "copilot-hooks",
             ok: fs.existsSync(copilotHooks),
@@ -382,12 +337,13 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "copilot-config-writable",
-            ok: nearestWritableTarget(copilotHooks),
-            detail: nearestWritableTarget(copilotHooks) ? `writable: ${copilotHooks}` : `not writable: ${copilotHooks}`,
+            ok: copilotWritable,
+            detail: copilotWritable ? `writable: ${copilotHooks}` : `not writable: ${copilotHooks}`,
         });
     }
     if (detected.has("cursor")) {
         const cursorHooks = hookConfigPath("cursor", phrenPath);
+        const cursorWritable = nearestWritableTarget(cursorHooks);
         checks.push({
             name: "cursor-hooks",
             ok: fs.existsSync(cursorHooks),
@@ -395,12 +351,13 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "cursor-config-writable",
-            ok: nearestWritableTarget(cursorHooks),
-            detail: nearestWritableTarget(cursorHooks) ? `writable: ${cursorHooks}` : `not writable: ${cursorHooks}`,
+            ok: cursorWritable,
+            detail: cursorWritable ? `writable: ${cursorHooks}` : `not writable: ${cursorHooks}`,
         });
     }
     if (detected.has("codex")) {
         const codexHooks = hookConfigPath("codex", phrenPath);
+        const codexWritable = nearestWritableTarget(codexHooks);
         checks.push({
             name: "codex-hooks",
             ok: fs.existsSync(codexHooks),
@@ -408,8 +365,8 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         });
         checks.push({
             name: "codex-config-writable",
-            ok: nearestWritableTarget(codexHooks),
-            detail: nearestWritableTarget(codexHooks) ? `writable: ${codexHooks}` : `not writable: ${codexHooks}`,
+            ok: codexWritable,
+            detail: codexWritable ? `writable: ${codexHooks}` : `not writable: ${codexHooks}`,
         });
     }
     for (const tool of ["copilot", "cursor", "codex"]) {
@@ -446,7 +403,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
     }
     else {
         // Read-only mode: just check if hook configs exist, don't write anything
-        const detectedTools = detectInstalledTools();
+        const detectedTools = detected;
         const hookChecks = [];
         const missing = [];
         for (const tool of detectedTools) {

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();