@phren/cli 0.0.41 → 0.0.43

package/mcp/dist/cli/actions.js

@@ -291,7 +291,7 @@ export async function handleUpdate(args) {
         process.exitCode = 1;
     }
     else {
-        console.log("Run 'npx phren init' to refresh hooks and config.");
+        console.log("Run 'phren init' to refresh hooks and config.");
     }
 }
 export async function handleReview(args) {

package/mcp/dist/cli/cli.js

@@ -7,7 +7,7 @@ import { handleExtractMemories } from "./extract.js";
 import { handleGovernMemories, handlePruneMemories, handleConsolidateMemories, handleMaintain, handleBackgroundMaintenance, } from "./govern.js";
 import { handleConfig, handleIndexPolicy, handleRetentionPolicy, handleWorkflowPolicy, } from "./config.js";
 import { parseSearchArgs } from "./search.js";
-import { handleDetectSkills, handleFindingNamespace, handleHooksNamespace, handleProjectsNamespace, handleSkillsNamespace, handleSkillList, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
+import { handleDetectSkills, handleFindingNamespace, handleHooksNamespace, handleProjectsNamespace, handleSkillsNamespace, handleSkillList, handlePromoteNamespace, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
 import { handleTaskView, handleSessionsView, handleQuickstart, handleDebugInjection, handleInspectIndex, } from "./ops.js";
 import { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleReview, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
 import { handleGraphNamespace } from "./graph.js";
@@ -109,6 +109,8 @@ export async function runCliCommand(command, args) {
             return handleSessionContext();
         case "store":
             return handleStoreNamespace(args);
+        case "promote":
+            return handlePromoteNamespace(args);
         default:
             console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);
             process.exit(1);

package/mcp/dist/cli/hooks-session.js

@@ -86,13 +86,13 @@ export function getUntrackedProjectNotice(phrenPath, cwd) {
     return [
         "<phren-notice>",
         "This project directory is not tracked by phren yet.",
-        "Run `npx phren add` to track it now.",
-        `Suggested command: \`npx phren add \"${projectDir}\"\``,
+        "Run `phren add` to track it now.",
+        `Suggested command: \`phren add \"${projectDir}\"\``,
         "Ask the user whether they want to add it to phren now.",
-        "If they say no, tell them they can always run `npx phren add` later.",
+        "If they say no, tell them they can always run `phren add` later.",
         "If they say yes, also ask whether phren should manage repo instruction files or leave their existing repo-owned CLAUDE/AGENTS files alone.",
-        `Then use the \`add_project\` MCP tool with path="${projectDir}" and ownership="phren-managed"|"detached"|"repo-managed", or run \`npx phren add\` from that directory.`,
-        "After onboarding, run `npx phren doctor` if hooks or MCP tools are not responding.",
+        `Then use the \`add_project\` MCP tool with path="${projectDir}" and ownership="phren-managed"|"detached"|"repo-managed", or run \`phren add\` from that directory.`,
+        "After onboarding, run `phren doctor` if hooks or MCP tools are not responding.",
         "<phren-notice>",
         "",
     ].join("\n");
@@ -127,8 +127,8 @@ export function getSessionStartOnboardingNotice(phrenPath, cwd, activeProject) {
         return [
             "<phren-notice>",
             "Phren onboarding: no tracked projects are active for this workspace yet.",
-            "Start in a project repo and run `npx phren add` so SessionStart can inject project context.",
-            "Run `npx phren doctor` to verify hooks and MCP wiring after setup.",
+            "Start in a project repo and run `phren add` so SessionStart can inject project context.",
+            "Run `phren doctor` to verify hooks and MCP wiring after setup.",
             "<phren-notice>",
             "",
         ].join("\n");
@@ -141,7 +141,7 @@ export function getSessionStartOnboardingNotice(phrenPath, cwd, activeProject) {
         "<phren-notice>",
         `Phren onboarding: project "${activeProject}" is tracked but memory is still empty.`,
         "Capture one finding with `add_finding` and one task with `add_task` to seed future SessionStart context.",
-        "Run `npx phren doctor` if setup seems incomplete.",
+        "Run `phren doctor` if setup seems incomplete.",
         "<phren-notice>",
         "",
     ].join("\n");

package/mcp/dist/cli/namespaces.js

@@ -594,7 +594,7 @@ export async function handleProjectsNamespace(args, profile) {
     }
     if (subcommand === "add") {
         console.error("`phren projects add` has been removed from the supported workflow.");
-        console.error("Use `cd ~/your-project && npx phren add` so enrollment stays path-based.");
+        console.error("Use `cd ~/your-project && phren add` so enrollment stays path-based.");
         process.exit(1);
     }
     if (subcommand === "remove") {
@@ -864,7 +864,7 @@ function handleProjectsList(profile) {
         .filter((name) => name !== "global")
         .sort();
     if (!projects.length) {
-        console.log("No projects found. Run: cd ~/your-project && npx phren add");
+        console.log("No projects found. Run: cd ~/your-project && phren add");
         return;
     }
     console.log(`\nProjects in ${phrenPath}:\n`);
@@ -888,7 +888,7 @@ function handleProjectsList(profile) {
         console.log(`  ${name}${tagStr}`);
     }
     console.log(`\n${projects.length} project(s) total.`);
-    console.log("Add another project: cd ~/your-project && npx phren add");
+    console.log("Add another project: cd ~/your-project && phren add");
 }
 async function handleProjectsRemove(name, profile) {
     if (!isValidProjectName(name)) {
@@ -1509,6 +1509,7 @@ function printStoreUsage() {
     console.log("  phren store add <name> --remote <url>   Add a team store");
     console.log("  phren store remove <name>               Remove a store (local only)");
     console.log("  phren store sync                        Pull all stores");
+    console.log("  phren store activity [--limit N]         Recent team findings");
 }
 export async function handleStoreNamespace(args) {
     const subcommand = args[0];
@@ -1630,6 +1631,47 @@ export async function handleStoreNamespace(args) {
         }
         return;
     }
+    if (subcommand === "activity") {
+        const stores = resolveAllStores(phrenPath);
+        const teamStores = stores.filter((s) => s.role === "team");
+        if (teamStores.length === 0) {
+            console.log("No team stores registered. Add one with: phren store add <name> --remote <url>");
+            return;
+        }
+        const { readTeamJournalEntries } = await import("../finding/journal.js");
+        const limit = Number(getOptionValue(args.slice(1), "--limit") ?? "20");
+        const allEntries = [];
+        for (const store of teamStores) {
+            if (!fs.existsSync(store.path))
+                continue;
+            const projectDirs = getProjectDirs(store.path);
+            for (const dir of projectDirs) {
+                const projectName = path.basename(dir);
+                const journalEntries = readTeamJournalEntries(store.path, projectName);
+                for (const je of journalEntries) {
+                    for (const entry of je.entries) {
+                        allEntries.push({ store: store.name, project: projectName, date: je.date, actor: je.actor, entry });
+                    }
+                }
+            }
+        }
+        allEntries.sort((a, b) => b.date.localeCompare(a.date));
+        const capped = allEntries.slice(0, limit);
+        if (capped.length === 0) {
+            console.log("No team activity yet.");
+            return;
+        }
+        console.log(`Team activity (${capped.length}/${allEntries.length}):\n`);
+        let lastDate = "";
+        for (const e of capped) {
+            if (e.date !== lastDate) {
+                console.log(`## ${e.date}`);
+                lastDate = e.date;
+            }
+            console.log(`  [${e.store}/${e.project}] ${e.actor}: ${e.entry}`);
+        }
+        return;
+    }
     if (subcommand === "sync") {
         const stores = resolveAllStores(phrenPath);
         let hasErrors = false;
@@ -1665,6 +1707,71 @@ export async function handleStoreNamespace(args) {
     printStoreUsage();
     process.exit(1);
 }
+// ── Promote namespace ────────────────────────────────────────────────────────
+export async function handlePromoteNamespace(args) {
+    if (!args[0] || args[0] === "--help" || args[0] === "-h") {
+        console.log("Usage:");
+        console.log('  phren promote <project> "finding text..." --to <store>');
+        console.log("  Copies a finding from the primary store to a team store.");
+        return;
+    }
+    const phrenPath = getPhrenPath();
+    const project = args[0];
+    if (!isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}"`);
+        process.exit(1);
+    }
+    const toStore = getOptionValue(args.slice(1), "--to");
+    if (!toStore) {
+        console.error("--to <store> is required. Specify the target team store.");
+        process.exit(1);
+    }
+    // Everything between project and --to is the finding text
+    const toIdx = args.indexOf("--to");
+    const findingText = args.slice(1, toIdx !== -1 ? toIdx : undefined).join(" ").trim();
+    if (!findingText) {
+        console.error("Finding text is required.");
+        process.exit(1);
+    }
+    const stores = resolveAllStores(phrenPath);
+    const targetStore = stores.find((s) => s.name === toStore);
+    if (!targetStore) {
+        const available = stores.map((s) => s.name).join(", ");
+        console.error(`Store "${toStore}" not found. Available: ${available}`);
+        process.exit(1);
+    }
+    if (targetStore.role === "readonly") {
+        console.error(`Store "${toStore}" is read-only.`);
+        process.exit(1);
+    }
+    if (targetStore.role === "primary") {
+        console.error(`Cannot promote to primary store — finding is already there.`);
+        process.exit(1);
+    }
+    // Find the matching finding in the primary store
+    const { readFindings } = await import("../data/access.js");
+    const findingsResult = readFindings(phrenPath, project);
+    if (!findingsResult.ok) {
+        console.error(`Could not read findings for project "${project}".`);
+        process.exit(1);
+    }
+    const match = findingsResult.data.find((item) => item.text.includes(findingText) || findingText.includes(item.text));
+    if (!match) {
+        console.error(`No finding matching "${findingText.slice(0, 80)}..." found in ${project}.`);
+        process.exit(1);
+    }
+    // Write to target store
+    const targetProjectDir = path.join(targetStore.path, project);
+    fs.mkdirSync(targetProjectDir, { recursive: true });
+    const { addFindingToFile } = await import("../shared/content.js");
+    const result = addFindingToFile(targetStore.path, project, match.text);
+    if (!result.ok) {
+        console.error(`Failed to add finding to ${toStore}: ${result.error}`);
+        process.exit(1);
+    }
+    console.log(`Promoted to ${toStore}/${project}:`);
+    console.log(`  "${match.text.slice(0, 120)}${match.text.length > 120 ? "..." : ""}"`);
+}
 function countStoreProjects(store) {
     if (!fs.existsSync(store.path))
         return 0;

package/mcp/dist/cli-hooks-session-handlers.js

@@ -60,13 +60,13 @@ export function getUntrackedProjectNotice(phrenPath, cwd) {
     return [
         "<phren-notice>",
         "This project directory is not tracked by phren yet.",
-        "Run `npx phren add` to track it now.",
-        `Suggested command: \`npx phren add "${projectDir}"\``,
+        "Run `phren add` to track it now.",
+        `Suggested command: \`phren add "${projectDir}"\``,
         "Ask the user whether they want to add it to phren now.",
-        "If they say no, tell them they can always run `npx phren add` later.",
+        "If they say no, tell them they can always run `phren add` later.",
         "If they say yes, also ask whether phren should manage repo instruction files or leave their existing repo-owned CLAUDE/AGENTS files alone.",
-        `Then use the \`add_project\` MCP tool with path="${projectDir}" and ownership="phren-managed"|"detached"|"repo-managed", or run \`npx phren add\` from that directory.`,
-        "After onboarding, run `npx phren doctor` if hooks or MCP tools are not responding.",
+        `Then use the \`add_project\` MCP tool with path="${projectDir}" and ownership="phren-managed"|"detached"|"repo-managed", or run \`phren add\` from that directory.`,
+        "After onboarding, run `phren doctor` if hooks or MCP tools are not responding.",
         "<phren-notice>",
         "",
     ].join("\n");
@@ -83,8 +83,8 @@ export function getSessionStartOnboardingNotice(phrenPath, cwd, activeProject) {
         return [
             "<phren-notice>",
             "Phren onboarding: no tracked projects are active for this workspace yet.",
-            "Start in a project repo and run `npx phren add` so SessionStart can inject project context.",
-            "Run `npx phren doctor` to verify hooks and MCP wiring after setup.",
+            "Start in a project repo and run `phren add` so SessionStart can inject project context.",
+            "Run `phren doctor` to verify hooks and MCP wiring after setup.",
             "<phren-notice>",
             "",
         ].join("\n");
@@ -97,7 +97,7 @@ export function getSessionStartOnboardingNotice(phrenPath, cwd, activeProject) {
         "<phren-notice>",
         `Phren onboarding: project "${activeProject}" is tracked but memory is still empty.`,
         "Capture one finding with `add_finding` and one task with `add_task` to seed future SessionStart context.",
-        "Run `npx phren doctor` if setup seems incomplete.",
+        "Run `phren doctor` if setup seems incomplete.",
         "<phren-notice>",
         "",
     ].join("\n");

package/mcp/dist/content/dedup.js

@@ -338,12 +338,15 @@ export function isDuplicateFinding(existingContent, newLearning, threshold = 0.6
             return true;
         }
         // Second pass: Jaccard similarity (strip metadata before comparing)
+        // Threshold lowered from 0.55 to 0.40 to catch agent paraphrases —
+        // swarm agents often report the same insight with different wording,
+        // and 0.55 let too many through.
         const newTokens = jaccardTokenize(stripMetadata(newLearning));
         const existingTokens = jaccardTokenize(stripMetadata(bullet));
         if (newTokens.size < 3 || existingTokens.size < 3)
             continue; // too few tokens for reliable Jaccard
         const jaccard = jaccardSimilarity(newTokens, existingTokens);
-        if (jaccard > 0.55) {
+        if (jaccard > 0.40) {
             debugLog(`duplicate-detection: Jaccard ${Math.round(jaccard * 100)}% with existing: "${bullet.slice(0, 80)}"`);
             return true;
         }
@@ -489,7 +492,7 @@ export async function checkSemanticDedup(phrenPath, project, newLearning, signal
         if (tokA.size < 3 || tokB.size < 3)
             continue;
         const jaccard = jaccardSimilarity(tokA, tokB);
-        if (jaccard >= 0.55)
+        if (jaccard >= 0.40)
             continue; // already caught by sync isDuplicateFinding
         if (jaccard >= 0.3) {
             const isDup = await semanticDedup(a, b, phrenPath, signal);

package/mcp/dist/entrypoint.js

@@ -175,6 +175,7 @@ const CLI_COMMANDS = [
     "consolidation-status",
     "session-context",
     "store",
+    "promote",
 ];
 async function flushTopLevelOutput() {
     await Promise.all([
@@ -264,7 +265,7 @@ export async function runTopLevelCommand(argv) {
         const phrenPath = defaultPhrenPath();
         const profile = (process.env.PHREN_PROFILE) || undefined;
         if (!fs.existsSync(phrenPath) || !fs.existsSync(path.join(phrenPath, ".config"))) {
-            console.log("phren is not set up yet. Run: npx phren init");
+            console.log("phren is not set up yet. Run: phren init");
             return finish(1);
         }
         const ownership = ownershipArg
@@ -380,7 +381,7 @@ export async function runTopLevelCommand(argv) {
             const note = getVerifyOutcomeNote(phrenPath, result.checks);
             if (note)
                 console.log(`\nNote: ${note}`);
-            console.log(`\nRun \`npx phren init\` to fix setup issues.`);
+            console.log(`\nRun \`phren init\` to fix setup issues.`);
         }
         return finish(result.ok ? 0 : 1);
     }
@@ -407,7 +408,7 @@ export async function runTopLevelCommand(argv) {
         }
     }
     if (argvCommand === "link") {
-        console.error("`phren link` has been removed. Use `npx phren init` instead.");
+        console.error("`phren link` has been removed. Use `phren init` instead.");
         return finish(1);
     }
     if (argvCommand === "--health") {

package/mcp/dist/finding/context.js

@@ -167,6 +167,7 @@ export function resolveFindingSessionId(phrenPath, project, explicitSessionId) {
         .sort((a, b) => sessionSortValue(b) - sessionSortValue(a));
     if (matchingProject.length > 0)
         return matchingProject[0].sessionId;
-    const sorted = active.sort((a, b) => sessionSortValue(b) - sessionSortValue(a));
-    return sorted[0]?.sessionId;
+    // Do not attribute findings to an unrelated active session from another project.
+    // Missing session provenance is safer than cross-project contamination.
+    return undefined;
 }

package/mcp/dist/finding/journal.js

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
-import { runtimeDir, phrenOk, phrenErr, PhrenError } from "../shared.js";
+import { runtimeDir, phrenOk, phrenErr, PhrenError, atomicWriteText } from "../shared.js";
 import { withFileLock } from "../shared/governance.js";
 import { addFindingToFile } from "../shared/content.js";
 import { isValidProjectName, errorMessage } from "../utils.js";
@@ -120,3 +120,90 @@ export function compactFindingJournals(phrenPath, project) {
     }
     return result;
 }
+// ── Team store journal (append-only markdown, committed to git) ──────────────
+const TEAM_JOURNAL_DIR = "journal";
+/**
+ * Append a finding to a team store's journal.
+ * Each actor gets one file per day — no merge conflicts possible.
+ * These are markdown files committed to git (not runtime JSONL).
+ */
+export function appendTeamJournal(storePath, project, finding, actor) {
+    const resolvedActor = actor || process.env.PHREN_ACTOR || process.env.USER || "unknown";
+    const date = new Date().toISOString().slice(0, 10);
+    const journalDir = path.join(storePath, project, TEAM_JOURNAL_DIR);
+    const journalFile = `${date}-${resolvedActor}.md`;
+    const journalPath = path.join(journalDir, journalFile);
+    try {
+        fs.mkdirSync(journalDir, { recursive: true });
+        const entry = `- ${finding}\n`;
+        if (fs.existsSync(journalPath)) {
+            fs.appendFileSync(journalPath, entry);
+        }
+        else {
+            fs.writeFileSync(journalPath, `## ${date} (${resolvedActor})\n\n${entry}`);
+        }
+        return phrenOk(journalFile);
+    }
+    catch (err) {
+        return phrenErr(`Team journal append failed: ${errorMessage(err)}`, PhrenError.PERMISSION_DENIED);
+    }
+}
+/**
+ * Read all team journal entries for a project, newest first.
+ */
+export function readTeamJournalEntries(storePath, project) {
+    const journalDir = path.join(storePath, project, TEAM_JOURNAL_DIR);
+    if (!fs.existsSync(journalDir))
+        return [];
+    return fs.readdirSync(journalDir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+        .reverse()
+        .map((file) => {
+        const match = file.match(/^(\d{4}-\d{2}-\d{2})-(.+)\.md$/);
+        const date = match?.[1] ?? "unknown";
+        const actor = match?.[2] ?? "unknown";
+        const content = fs.readFileSync(path.join(journalDir, file), "utf8");
+        const entries = content.split("\n")
+            .filter((line) => line.startsWith("- "))
+            .map((line) => line.slice(2).trim());
+        return { file, date, actor, entries };
+    });
+}
+/**
+ * Materialize FINDINGS.md from team journal entries.
+ * Groups by date, includes actor attribution.
+ */
+export function materializeTeamFindings(storePath, project) {
+    const journalEntries = readTeamJournalEntries(storePath, project);
+    if (journalEntries.length === 0) {
+        return phrenErr("No journal entries found", PhrenError.FILE_NOT_FOUND);
+    }
+    // Group by date, chronological order
+    const byDate = new Map();
+    for (const entry of [...journalEntries].reverse()) {
+        if (!byDate.has(entry.date))
+            byDate.set(entry.date, []);
+        byDate.get(entry.date).push({ actor: entry.actor, entries: entry.entries });
+    }
+    const lines = [`# ${project} findings\n`];
+    let count = 0;
+    for (const [date, actors] of byDate) {
+        lines.push(`## ${date}`);
+        for (const { actor, entries } of actors) {
+            for (const entry of entries) {
+                lines.push(`- ${entry} <!-- author:${actor} -->`);
+                count++;
+            }
+        }
+        lines.push("");
+    }
+    const findingsPath = path.join(storePath, project, "FINDINGS.md");
+    try {
+        atomicWriteText(findingsPath, lines.join("\n"));
+        return phrenOk({ entryCount: count });
+    }
+    catch (err) {
+        return phrenErr(`Materialize failed: ${errorMessage(err)}`, PhrenError.PERMISSION_DENIED);
+    }
+}

package/mcp/dist/init/config.js

@@ -207,7 +207,7 @@ export function configureClaude(phrenPath, opts = {}) {
                 eventHooks.push({ matcher: "", hooks: [hookBody] });
             }
         };
-        const toolHookEnabled = hooksEnabled && isFeatureEnabled("PHREN_FEATURE_TOOL_HOOK", false);
+        const toolHookEnabled = hooksEnabled && isFeatureEnabled("PHREN_FEATURE_TOOL_HOOK", true);
         if (hooksEnabled) {
             upsertPhrenHook("UserPromptSubmit", {
                 type: "command",

package/mcp/dist/init/init-configure.js

@@ -89,7 +89,7 @@ export function configureHooksIfEnabled(phrenPath, hooksEnabled, verb) {
         }
     }
     else {
-        log(`  Hooks are disabled by preference (run: npx phren hooks-mode on)`);
+        log(`  Hooks are disabled by preference (run: phren hooks-mode on)`);
     }
     // Install phren CLI wrapper at ~/.local/bin/phren so the bare command works
     const wrapperInstalled = installPhrenCliWrapper(phrenPath);

package/mcp/dist/init/init-hooks-mode.js

@@ -14,7 +14,7 @@ export async function runHooksMode(modeArg) {
     if (!normalizedArg || normalizedArg === "status") {
         const current = getHooksEnabledPreference(phrenPath);
         log(`Hooks mode: ${current ? "on (active)" : "off (disabled)"}`);
-        log(`Change mode: npx phren hooks-mode on|off`);
+        log(`Change mode: phren hooks-mode on|off`);
         return;
     }
     const mode = parseMcpMode(normalizedArg);

package/mcp/dist/init/init-mcp-mode.js

@@ -15,8 +15,8 @@ export async function runMcpMode(modeArg) {
         const hooks = getHooksEnabledPreference(phrenPath);
         log(`MCP mode: ${current ? "on (recommended)" : "off (hooks-only fallback)"}`);
         log(`Hooks mode: ${hooks ? "on (active)" : "off (disabled)"}`);
-        log(`Change mode: npx phren mcp-mode on|off`);
-        log(`Hooks toggle: npx phren hooks-mode on|off`);
+        log(`Change mode: phren mcp-mode on|off`);
+        log(`Hooks toggle: phren hooks-mode on|off`);
         return;
     }
     const mode = parseMcpMode(normalizedArg);

package/mcp/dist/init/init-walkthrough.js

@@ -280,7 +280,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("  phren-managed: Phren may mirror CLAUDE.md / AGENTS.md into the repo");
     log("  detached: Phren keeps its own docs but does not write into the repo");
     log("  repo-managed: keep the repo's existing CLAUDE/AGENTS files as canonical");
-    log("  Change later: npx phren config project-ownership <mode>");
+    log("  Change later: phren config project-ownership <mode>");
     const projectOwnershipDefault = await prompts.select("Default project ownership", [
         { value: "detached", name: "detached (default)" },
         { value: "phren-managed", name: "phren-managed" },
@@ -291,7 +291,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("directly: search memory, manage tasks, save findings, etc.");
     log("  Recommended for: Claude Code, Cursor, Copilot CLI, Codex");
     log("  Alternative: hooks-only mode (read-only context injection, any agent)");
-    log("  Change later: npx phren mcp-mode on|off");
+    log("  Change later: phren mcp-mode on|off");
     const mcp = (await prompts.confirm("Enable MCP?", true)) ? "on" : "off";
     printSection("Hooks");
     log("Hooks run shell commands at session start, prompt submit, and session end.");
@@ -299,7 +299,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("  - UserPromptSubmit: searches phren and injects relevant context");
     log("  - Stop: commits and pushes any new findings after each response");
     log("  What they touch: ~/.claude/settings.json (hooks section only)");
-    log("  Change later: npx phren hooks-mode on|off");
+    log("  Change later: phren hooks-mode on|off");
     const hooks = (await prompts.confirm("Enable hooks?", true)) ? "on" : "off";
     printSection("Semantic Search (Optional)");
     log("Phren can use a local embedding model for semantic (fuzzy) search via Ollama.");
@@ -347,7 +347,7 @@ export async function runWalkthrough(phrenPath, options) {
     let findingsProactivity = "high";
     if (autoCaptureEnabled) {
         log("  Findings capture level controls how eager phren is to save lessons automatically.");
-        log("  Change later: npx phren config proactivity.findings <high|medium|low>");
+        log("  Change later: phren config proactivity.findings <high|medium|low>");
         findingsProactivity = await prompts.select("Findings capture level", [
             { value: "high", name: "high (recommended)" },
             { value: "medium", name: "medium" },
@@ -363,7 +363,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("  suggest: proposes tasks but waits for approval before writing");
     log("  manual: tasks are fully manual — you add them yourself");
     log("  off: never touch tasks automatically");
-    log("  Change later: npx phren config workflow set --taskMode=<mode>");
+    log("  Change later: phren config workflow set --taskMode=<mode>");
     const taskMode = await prompts.select("Task mode", [
         { value: "auto", name: "auto (recommended)" },
         { value: "suggest", name: "suggest" },
@@ -376,7 +376,7 @@ export async function runWalkthrough(phrenPath, options) {
         log("  high (recommended): captures tasks as they come up naturally");
         log("  medium: only when you explicitly mention a task");
         log("  low: minimal auto-capture");
-        log("  Change later: npx phren config proactivity.tasks <high|medium|low>");
+        log("  Change later: phren config proactivity.tasks <high|medium|low>");
         taskProactivity = await prompts.select("Task proactivity", [
             { value: "high", name: "high (recommended)" },
             { value: "medium", name: "medium" },
@@ -387,7 +387,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("Choose how strict review gates should be for risky or low-confidence writes.");
     log("  lowConfidenceThreshold: confidence cutoff used to mark writes as risky");
     log("  riskySections: sections always treated as risky");
-    log("  Change later: npx phren config workflow set --lowConfidenceThreshold=0.7 --riskySections=Stale,Conflicts");
+    log("  Change later: phren config workflow set --lowConfidenceThreshold=0.7 --riskySections=Stale,Conflicts");
     const thresholdAnswer = await prompts.input("Low-confidence threshold [0.0-1.0]", "0.7");
     const lowConfidenceThreshold = parseLowConfidenceThreshold(thresholdAnswer, 0.7);
     const riskySectionsAnswer = await prompts.input("Risky sections [Review,Stale,Conflicts]", "Stale,Conflicts");
@@ -437,7 +437,7 @@ export async function runWalkthrough(phrenPath, options) {
     log("  conservative — decisions and pitfalls only");
     log("  balanced     — non-obvious patterns, decisions, pitfalls, bugs (recommended)");
     log("  aggressive   — everything worth remembering, err on the side of capturing");
-    log("  Change later: npx phren config finding-sensitivity <level>");
+    log("  Change later: phren config finding-sensitivity <level>");
     const findingSensitivity = await prompts.select("Finding sensitivity", [
         { value: "balanced", name: "balanced (recommended)" },
         { value: "conservative", name: "conservative" },
@@ -466,7 +466,7 @@ export async function runWalkthrough(phrenPath, options) {
         bootstrapCurrentProject = await prompts.confirm("Add this project to phren now?", true);
         if (!bootstrapCurrentProject) {
             bootstrapCurrentProject = false;
-            log(style.warning(`  Skipped. Later: cd ${detectedProject} && npx phren add`));
+            log(style.warning(`  Skipped. Later: cd ${detectedProject} && phren add`));
         }
         else {
             bootstrapOwnership = await prompts.select("Ownership for detected project", [

package/mcp/dist/init/init.js

@@ -260,7 +260,7 @@ export async function runInit(opts = {}) {
             shouldBootstrapCurrentProject = await prompts.confirm("Add this project to phren now?", true);
             if (!shouldBootstrapCurrentProject) {
                 shouldBootstrapCurrentProject = false;
-                log(style.warning(`  Skipped. Later: cd ${pendingBootstrap.path} && npx phren add`));
+                log(style.warning(`  Skipped. Later: cd ${pendingBootstrap.path} && phren add`));
             }
             else {
                 bootstrapOwnership = await prompts.select("Ownership for detected project", [
@@ -352,7 +352,7 @@ export async function runInit(opts = {}) {
         const previousVersion = prefs.installedVersion;
         if (isVersionNewer(VERSION, previousVersion)) {
             log(`\n  Starter template update available: v${previousVersion} -> v${VERSION}`);
-            log(`  Run \`npx phren init --apply-starter-update\` to refresh global/CLAUDE.md and global skills.`);
+            log(`  Run \`phren init --apply-starter-update\` to refresh global/CLAUDE.md and global skills.`);
         }
         if (opts.applyStarterUpdate) {
             const updated = applyStarterTemplateUpdates(phrenPath);
@@ -395,8 +395,8 @@ export async function runInit(opts = {}) {
         log(`\n\x1b[95m◆\x1b[0m phren updated successfully`);
         log(`\nNext steps:`);
         log(`  1. Start a new Claude session in your project directory — phren injects context automatically`);
-        log(`  2. Run \`npx phren doctor\` to verify everything is wired correctly`);
-        log(`  3. Change defaults anytime: \`npx phren config project-ownership\`, \`npx phren config workflow\`, \`npx phren config proactivity.findings\`, \`npx phren config proactivity.tasks\``);
+        log(`  2. Run \`phren doctor\` to verify everything is wired correctly`);
+        log(`  3. Change defaults anytime: \`phren config project-ownership\`, \`phren config workflow\`, \`phren config proactivity.findings\`, \`phren config proactivity.tasks\``);
         log(`  4. After your first week, run phren-discover to surface gaps in your project knowledge`);
         log(`  5. After working across projects, run phren-consolidate to find cross-project patterns`);
         log(``);
@@ -581,8 +581,8 @@ export async function runInit(opts = {}) {
     log(`\nNext steps:`);
     let step = 1;
     log(`  ${step++}. Start a new Claude session in your project directory — phren injects context automatically`);
-    log(`  ${step++}. Run \`npx phren doctor\` to verify everything is wired correctly`);
-    log(`  ${step++}. Change defaults anytime: \`npx phren config project-ownership\`, \`npx phren config workflow\`, \`npx phren config proactivity.findings\`, \`npx phren config proactivity.tasks\``);
+    log(`  ${step++}. Run \`phren doctor\` to verify everything is wired correctly`);
+    log(`  ${step++}. Change defaults anytime: \`phren config project-ownership\`, \`phren config workflow\`, \`phren config proactivity.findings\`, \`phren config proactivity.tasks\``);
     const gh = opts._walkthroughGithub;
     if (gh) {
         const remote = gh.username
@@ -607,9 +607,9 @@ export async function runInit(opts = {}) {
         log(`     git remote add origin git@github.com:YOUR_USERNAME/my-phren.git`);
         log(`     git push -u origin main`);
     }
-    log(`  ${step++}. Add more projects: cd ~/your-project && npx phren add`);
+    log(`  ${step++}. Add more projects: cd ~/your-project && phren add`);
     if (!mcpEnabled) {
-        log(`  ${step++}. Turn MCP on: npx phren mcp-mode on`);
+        log(`  ${step++}. Turn MCP on: phren mcp-mode on`);
     }
     log(`  ${step++}. After your first week, run phren-discover to surface gaps in your project knowledge`);
     log(`  ${step++}. After working across projects, run phren-consolidate to find cross-project patterns`);

package/mcp/dist/init/setup.js

@@ -1089,9 +1089,15 @@ export function updateMachinesYaml(phrenPath, machine, profile) {
  */
 export function detectProjectDir(dir, phrenPath) {
     const home = os.homedir();
+    const tmpRoot = path.resolve(os.tmpdir());
     const resolvedPhrenPath = path.resolve(phrenPath);
     let current = path.resolve(dir);
     while (true) {
+        // Never treat the shared OS temp root itself as a project. Tools may drop
+        // global instruction files there, which would otherwise hijack detection
+        // for arbitrary temp subdirectories.
+        if (current === tmpRoot)
+            return null;
         if (current === home || current === resolvedPhrenPath)
             return null;
         if (current.startsWith(resolvedPhrenPath + path.sep))