@phren/cli 0.0.42 → 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/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)) {
@@ -1763,7 +1763,6 @@ export async function handlePromoteNamespace(args) {
     // Write to target store
     const targetProjectDir = path.join(targetStore.path, project);
     fs.mkdirSync(targetProjectDir, { recursive: true });
-    const targetFindingsPath = path.join(targetProjectDir, "FINDINGS.md");
     const { addFindingToFile } = await import("../shared/content.js");
     const result = addFindingToFile(targetStore.path, project, match.text);
     if (!result.ok) {

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

@@ -265,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
@@ -381,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);
     }
@@ -408,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/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))

package/mcp/dist/init-fresh.js

@@ -197,8 +197,8 @@ export async function runFreshInstall(phrenPath, opts, params) {
     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
@@ -223,9 +223,9 @@ export async function runFreshInstall(phrenPath, opts, params) {
         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-hooks.js

@@ -21,6 +21,6 @@ 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)`);
     }
 }

package/mcp/dist/init-modes.js

@@ -24,8 +24,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);
@@ -93,7 +93,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-update.js

@@ -53,7 +53,7 @@ export async function runExistingInstallUpdate(phrenPath, opts, params) {
     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);
@@ -88,8 +88,8 @@ export async function runExistingInstallUpdate(phrenPath, opts, params) {
     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(``);

package/mcp/dist/init-walkthrough.js

@@ -269,7 +269,7 @@ export async function runWalkthrough(phrenPath) {
     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" },
@@ -280,7 +280,7 @@ export async function runWalkthrough(phrenPath) {
     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.");
@@ -288,7 +288,7 @@ export async function runWalkthrough(phrenPath) {
     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.");
@@ -336,7 +336,7 @@ export async function runWalkthrough(phrenPath) {
     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" },
@@ -352,7 +352,7 @@ export async function runWalkthrough(phrenPath) {
     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" },
@@ -365,7 +365,7 @@ export async function runWalkthrough(phrenPath) {
         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" },
@@ -376,7 +376,7 @@ export async function runWalkthrough(phrenPath) {
     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");
@@ -426,7 +426,7 @@ export async function runWalkthrough(phrenPath) {
     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" },
@@ -455,7 +455,7 @@ export async function runWalkthrough(phrenPath) {
         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/link/link.js

@@ -76,7 +76,7 @@ function maybeOfferStarterTemplateUpdate(phrenPath) {
         const prefs = JSON.parse(fs.readFileSync(prefsPath, "utf8"));
         if (isVersionNewer(current, prefs.installedVersion)) {
             log(`  Starter template update available: v${prefs.installedVersion} -> v${current}`);
-            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.`);
         }
     }
     catch (err) {

package/mcp/dist/phren-paths.js

@@ -209,7 +209,7 @@ export function findPhrenPathWithArg(arg) {
     const existing = findPhrenPath();
     if (existing)
         return existing;
-    throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'npx phren init'.`);
+    throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'phren init'.`);
 }
 export function isProjectLocalMode(phrenPath) {
     try {
@@ -513,7 +513,7 @@ export function getPhrenPath() {
     if (!lazyPhrenPath) {
         const existing = findPhrenPath();
         if (!existing)
-            throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'npx phren init'.`);
+            throw new Error(`${PhrenError.NOT_FOUND}: phren root not found. Run 'phren init'.`);
         lazyPhrenPath = existing;
     }
     return lazyPhrenPath;

package/mcp/dist/profile-store.js

@@ -45,7 +45,7 @@ export function resolveActiveProfile(phrenPath, requestedProfile) {
 export function listMachines(phrenPath) {
     const machinesPath = path.join(phrenPath, "machines.yaml");
     if (!fs.existsSync(machinesPath))
-        return phrenErr(`machines.yaml not found. Run 'npx phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
+        return phrenErr(`machines.yaml not found. Run 'phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
     try {
         const raw = fs.readFileSync(machinesPath, "utf8");
         const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
@@ -205,7 +205,7 @@ export function getActiveProfileDefaults(phrenPath, profile) {
 export function listProfiles(phrenPath) {
     const profilesDir = path.join(phrenPath, "profiles");
     if (!fs.existsSync(profilesDir))
-        return phrenErr(`No profiles/ directory found. Run 'npx phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
+        return phrenErr(`No profiles/ directory found. Run 'phren init' to set up your phren.`, PhrenError.FILE_NOT_FOUND);
     const files = fs.readdirSync(profilesDir).filter((file) => file.endsWith(".yaml")).sort();
     const profiles = [];
     for (const file of files) {

package/mcp/dist/status.js

@@ -53,7 +53,7 @@ function hasCommandHook(value) {
 export async function runStatus() {
     const phrenPath = findPhrenPath();
     if (!phrenPath) {
-        console.log(`${RED}phren not found${RESET}. Run ${CYAN}npx phren init${RESET} to set up.`);
+        console.log(`${RED}phren not found${RESET}. Run ${CYAN}npx @phren/cli init${RESET} to set up.`);
         process.exit(1);
     }
     const cwd = process.cwd();

package/mcp/dist/tools/finding.js

@@ -17,8 +17,8 @@ import { getActiveTaskForSession } from "../task/lifecycle.js";
 import { FINDING_PROVENANCE_SOURCES } from "../content/citation.js";
 import { isInactiveFindingLine, supersedeFinding, retractFinding as retractFindingLifecycle, resolveFindingContradiction, } from "../finding/lifecycle.js";
 import { permissionDeniedError } from "../governance/rbac.js";
-const JACCARD_MAYBE_LOW = 0.30;
-const JACCARD_MAYBE_HIGH = 0.55; // above this isDuplicateFinding already catches it
+const JACCARD_MAYBE_LOW = 0.25;
+const JACCARD_MAYBE_HIGH = 0.40; // above this isDuplicateFinding already catches it
 function findJaccardCandidates(phrenPath, project, finding) {
     try {
         const findingsPath = path.join(phrenPath, project, "FINDINGS.md");

package/mcp/dist/tools/session.js

@@ -18,6 +18,7 @@ import { listTaskCheckpoints, writeTaskCheckpoint } from "../session/checkpoints
 import { markImpactEntriesCompletedForSession } from "../finding/impact.js";
 import { atomicWriteJson, debugError, scanSessionFiles } from "../session/utils.js";
 import { getRuntimeHealth } from "../governance/policy.js";
+import { getProjectSourcePath, readProjectConfig } from "../project-config.js";
 const STALE_SESSION_MS = 24 * 60 * 60 * 1000; // 24 hours
 function collectGitStatusSnapshot(cwd) {
     try {
@@ -221,9 +222,11 @@ function cleanupStaleSessions(phrenPath) {
             // (no endedAt) should never be removed regardless of age.
             if (state && !state.endedAt)
                 continue;
-            // prefer startedAt from the JSON content over mtime (reliable on noatime mounts)
-            const ageMs = state?.startedAt
-                ? Date.now() - new Date(state.startedAt).getTime()
+            // For ended sessions, age out by end time rather than start time so
+            // long-running sessions do not disappear immediately after they finish.
+            const expirationAnchor = state?.endedAt || state?.startedAt;
+            const ageMs = expirationAnchor
+                ? Date.now() - new Date(expirationAnchor).getTime()
                 : Date.now() - fs.statSync(fullPath).mtimeMs;
             if (ageMs > STALE_SESSION_MS) {
                 fs.unlinkSync(fullPath);
@@ -607,7 +610,10 @@ export function register(server, ctx) {
                 })();
                 if (activeTask) {
                     const taskId = activeTask.stableId || activeTask.id;
-                    const { gitStatus, editedFiles } = collectGitStatusSnapshot(process.cwd());
+                    const projectConfig = readProjectConfig(phrenPath, endedState.project);
+                    const snapshotRoot = getProjectSourcePath(phrenPath, endedState.project, projectConfig) ||
+                        path.join(phrenPath, endedState.project);
+                    const { gitStatus, editedFiles } = collectGitStatusSnapshot(snapshotRoot);
                     const resumptionHint = extractResumptionHint(effectiveSummary, activeTask.line, activeTask.context || "No prior attempt captured");
                     writeTaskCheckpoint(phrenPath, {
                         project: endedState.project,

package/mcp/dist/tools/tasks.js

@@ -5,7 +5,7 @@ import * as path from "path";
 import { isValidProjectName } from "../utils.js";
 import { addTask as addTaskStore, addTasks as addTasksBatch, taskMarkdown, completeTask as completeTaskStore, completeTasks as completeTasksBatch, removeTask as removeTaskStore, removeTasks as removeTasksBatch, linkTaskIssue, pinTask, workNextTask, tidyDoneTasks, readTasks, readTasksAcrossProjects, resolveTaskItem, TASKS_FILENAME, updateTask as updateTaskStore, promoteTask, } from "../data/access.js";
 import { applyGravity } from "../data/tasks.js";
-import { parseGithubIssueUrl, } from "../task/github.js";
+import { buildTaskIssueBody, createGithubIssueForTask, parseGithubIssueUrl, resolveProjectGithubRepo, } from "../task/github.js";
 import { clearTaskCheckpoint } from "../session/checkpoints.js";
 import { incrementSessionTasksCompleted } from "./session.js";
 import { normalizeMemoryScope } from "../shared.js";
@@ -366,6 +366,7 @@ export function register(server, ctx) {
                 github_issue: z.union([z.number().int().positive(), z.string()]).optional().describe("GitHub issue number (for example 14 or '#14')."),
                 github_url: z.string().optional().describe("GitHub issue URL to associate with the task item."),
                 unlink_github: z.boolean().optional().describe("If true, remove any linked GitHub issue metadata from the item."),
+                create_issue: z.boolean().optional().describe("If true, create a GitHub issue for this task and link it."),
                 pin: z.boolean().optional().describe("If true, pin the task so it floats to the top of its section."),
                 promote: z.boolean().optional().describe("If true, clear the speculative flag on this task (confirm the user wants it)."),
                 move_to_active: z.boolean().optional().describe("Used with promote: also move the task to the Active section."),
@@ -382,6 +383,25 @@ export function register(server, ctx) {
         if (!updates.work_next && !item) {
             return mcpResponse({ ok: false, error: "item is required unless updates.work_next is true." });
         }
+        if (updates.create_issue) {
+            const extraUpdates = [
+                updates.text,
+                updates.priority,
+                updates.context,
+                updates.section,
+                updates.github_issue,
+                updates.github_url,
+                updates.unlink_github,
+                updates.pin,
+                updates.promote,
+                updates.move_to_active,
+                updates.work_next,
+                updates.replace_context,
+            ].some((value) => value !== undefined);
+            if (extraUpdates) {
+                return mcpResponse({ ok: false, error: "create_issue must be used by itself." });
+            }
+        }
         // Cross-validate github_issue and github_url
         if (updates.github_url) {
             const parsed = parseGithubIssueUrl(updates.github_url);
@@ -423,6 +443,45 @@ export function register(server, ctx) {
                     data: { project, item: result.data },
                 });
             }
+            if (updates.create_issue) {
+                const resolved = resolveTaskItem(phrenPath, project, item);
+                if (!resolved.ok)
+                    return mcpResponse({ ok: false, error: resolved.error });
+                const repo = resolveProjectGithubRepo(phrenPath, project);
+                if (!repo) {
+                    return mcpResponse({
+                        ok: false,
+                        error: "Could not infer a GitHub repo. Add a GitHub URL to CLAUDE.md or summary.md, or link an existing issue instead.",
+                    });
+                }
+                const created = createGithubIssueForTask({
+                    repo,
+                    title: resolved.data.line.replace(/\s*\[(high|medium|low)\]\s*$/i, "").trim(),
+                    body: buildTaskIssueBody(project, resolved.data),
+                });
+                if (!created.ok)
+                    return mcpResponse({ ok: false, error: created.error, errorCode: created.code });
+                const linked = linkTaskIssue(phrenPath, project, item, {
+                    github_issue: created.data.issueNumber,
+                    github_url: created.data.url,
+                });
+                if (!linked.ok)
+                    return mcpResponse({ ok: false, error: linked.error, errorCode: linked.code });
+                refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                return mcpResponse({
+                    ok: true,
+                    message: `Created GitHub issue ${created.data.issueNumber ? `#${created.data.issueNumber}` : created.data.url} for ${project} task.`,
+                    data: {
+                        project,
+                        item,
+                        issue_number: created.data.issueNumber ?? null,
+                        issue_url: created.data.url,
+                        githubIssue: linked.data.githubIssue ?? null,
+                        githubUrl: linked.data.githubUrl || null,
+                        stableId: linked.data.stableId || null,
+                    },
+                });
+            }
             // Handle github issue linking via update_task when github_issue or github_url is set (and no other field updates)
             if ((updates.github_issue !== undefined || updates.github_url || updates.unlink_github) && !updates.text && !updates.priority && !updates.context && !updates.section) {
                 if (updates.unlink_github && (updates.github_issue !== undefined || updates.github_url)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phren/cli",
-  "version": "0.0.42",
+  "version": "0.0.43",
   "description": "Knowledge layer for AI agents. Phren learns and recalls.",
   "type": "module",
   "bin": {

package/skills/sync/SKILL.md

@@ -102,7 +102,7 @@ If this fails (not a git repo, no remote), tell the user. Don't silently skip.
 Run init against the pulled phren repo so hooks, MCP registration, and machine/profile wiring are refreshed:
 
 ```bash
-PHREN_PATH="$PHREN_DIR" npx phren init -y
+PHREN_PATH="$PHREN_DIR" phren init -y
 ```
 
 If the user is in an untracked repo afterward, tell them to open a session there and let the agent ask, or run `phren add` from that directory.

package/starter/README.md

@@ -32,7 +32,7 @@ New to phren? Here's what each file does and when it matters.
 
 **FINDINGS.md** fills itself. As Claude discovers insights, patterns, and decisions during your sessions, it tells phren and entries land here grouped by date. Old entries fade from retrieval over time. Wrong entries can be removed with `remove_finding()`.
 
-**tasks.md** is your task board file. It keeps Active (working now), Queue (up next), and Done (finished) in one place so the work history stays with the project. You can also manage it from `npx phren shell`.
+**tasks.md** is your task board file. It keeps Active (working now), Queue (up next), and Done (finished) in one place so the work history stays with the project. You can also manage it from `phren shell`.
 
 **global/CLAUDE.md** applies everywhere. Your style preferences, tool choices, things Claude should always know regardless of which project you're in.
 
@@ -40,14 +40,14 @@ New to phren? Here's what each file does and when it matters.
 
 ## Getting started
 
-If you got here via `npx phren init`, you're already set up. Restart Claude Code and you're good.
+If you got here via `npx @phren/cli init`, you're already set up. Restart Claude Code and you're good.
 
 If you cloned manually:
 
-1. Add the MCP server: `claude mcp add phren -- npx phren ~/.phren`
+1. Add the MCP server: `claude mcp add phren -- npx @phren/cli ~/.phren`
 2. Install skills: `/plugin marketplace add alaarab/phren` then `/plugin install phren@phren`
 3. Restart Claude Code
-4. Add a project: run `/phren-init my-project` or scaffold one with a template such as `npx phren init --template python-project`
+4. Add a project: run `/phren-init my-project` or scaffold one with a template such as `phren init --template python-project`
 5. Push to a private GitHub repo to sync across machines
 
 ## Day-to-day workflow
@@ -56,7 +56,7 @@ If you cloned manually:
 2. **Work normally**: Claude reads your project docs and builds on what phren remembers
 3. **Fragments accumulate**: tell phren what you learned, or he picks up insights automatically
 4. **Session ends**: phren commits and pushes what he collected
-5. **Review occasionally**: run `npx phren shell` to triage what phren queued, manage tasks, and check health
+5. **Review occasionally**: run `phren shell` to triage what phren queued, manage tasks, and check health
 
 ## Syncing across machines
 
@@ -71,4 +71,4 @@ Each profile in `profiles/` lists which projects that machine should see. After
 
 ## Troubleshooting
 
-Run `npx phren doctor --fix` to check and repair your setup.
+Run `phren doctor --fix` to check and repair your setup.

package/starter/machines.yaml

@@ -5,4 +5,4 @@
 #   work-laptop: work
 #   home-desktop: personal
 #
-# After adding a line, run: npx phren init
+# After adding a line, run: phren init

package/starter/my-first-project/tasks.md

@@ -22,4 +22,4 @@
 
 ## Done
 
-- [x] Run `npx phren init` to set up phren
+- [x] Run `phren init` to set up phren

package/starter/templates/README.md

@@ -1,6 +1,6 @@
 # starter/templates/
 
-Project templates bundled in the npm package, used by `npx phren init --template <name>`.
+Project templates bundled in the npm package, used by `phren init --template <name>`.
 
 Each subdirectory (frontend, library, monorepo, python-project) contains pre-filled project files with sensible defaults for that project type. When a user runs init with `--template`, these files are copied into their `~/.phren/<project>/` directory. For other project types, adaptive init infers topics and structure from repo content.