@phren/cli 0.0.28 → 0.0.32

package/mcp/dist/init-bootstrap.js

@@ -0,0 +1,68 @@
+/**
+ * Bootstrap-current-project prompting and execution for init.
+ */
+import * as path from "path";
+import { debugLog } from "./shared.js";
+import { bootstrapFromExisting, } from "./init/setup.js";
+import { PROJECT_OWNERSHIP_MODES, } from "./project-config.js";
+import { createWalkthroughPrompts, createWalkthroughStyle, } from "./init-walkthrough.js";
+import { getPendingBootstrapTarget } from "./init-detect.js";
+import { log } from "./init/shared.js";
+/**
+ * Decide whether to bootstrap the CWD project and with what ownership.
+ * May prompt the user interactively.
+ */
+export async function resolveBootstrapDecision(phrenPath, opts, ownershipDefault, dryRun) {
+    const pendingBootstrap = getPendingBootstrapTarget(phrenPath, opts);
+    let shouldBootstrap = opts._walkthroughBootstrapCurrentProject === true;
+    let ownership = opts._walkthroughBootstrapOwnership ?? ownershipDefault;
+    if (pendingBootstrap && !dryRun) {
+        const walkthroughAlreadyHandled = opts._walkthroughBootstrapCurrentProject !== undefined;
+        if (walkthroughAlreadyHandled) {
+            shouldBootstrap = opts._walkthroughBootstrapCurrentProject === true;
+            ownership = opts._walkthroughBootstrapOwnership ?? ownershipDefault;
+        }
+        else if (opts.yes || !process.stdin.isTTY || !process.stdout.isTTY) {
+            shouldBootstrap = true;
+            ownership = ownershipDefault;
+        }
+        else {
+            const prompts = await createWalkthroughPrompts();
+            const style = await createWalkthroughStyle();
+            const detectedProjectName = path.basename(pendingBootstrap.path);
+            log("");
+            log(style.header("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+            log(style.header("Current Project"));
+            log(style.header("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+            log(`Detected project: ${detectedProjectName}`);
+            shouldBootstrap = await prompts.confirm("Add this project to phren now?", true);
+            if (!shouldBootstrap) {
+                log(style.warning(`  Skipped. Later: cd ${pendingBootstrap.path} && npx phren add`));
+            }
+            else {
+                ownership = await prompts.select("Ownership for detected project", [
+                    { value: ownershipDefault, name: `${ownershipDefault} (default)` },
+                    ...PROJECT_OWNERSHIP_MODES
+                        .filter((mode) => mode !== ownershipDefault)
+                        .map((mode) => ({ value: mode, name: mode })),
+                ], ownershipDefault);
+            }
+        }
+    }
+    return { shouldBootstrap, ownership };
+}
+/**
+ * Bootstrap a project from an existing directory into phren.
+ */
+export function bootstrapProject(phrenPath, projectPath, profile, ownership, label) {
+    try {
+        const created = bootstrapFromExisting(phrenPath, projectPath, {
+            profile,
+            ownership,
+        });
+        log(`\n${label} "${created.project}" (${created.ownership})`);
+    }
+    catch (e) {
+        debugLog(`Bootstrap from CWD failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/mcp/dist/init-detect.js

@@ -0,0 +1,38 @@
+/**
+ * Detection helpers for init: bootstrap target, install markers, path resolution.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { expandHomePath } from "./shared.js";
+import { detectProjectDir, isProjectTracked } from "./init/setup.js";
+import { DEFAULT_PHREN_PATH } from "./init/shared.js";
+export function normalizedBootstrapProjectName(projectPath) {
+    return path.basename(projectPath).toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
+export function getPendingBootstrapTarget(phrenPath, _opts) {
+    const cwdProject = detectProjectDir(process.cwd(), phrenPath);
+    if (!cwdProject)
+        return null;
+    const projectName = normalizedBootstrapProjectName(cwdProject);
+    if (isProjectTracked(phrenPath, projectName))
+        return null;
+    return { path: cwdProject, mode: "detected" };
+}
+export function hasInstallMarkers(phrenPath) {
+    // Require at least two markers to consider this a real install.
+    // A partial clone or failed init may create one directory but not finish.
+    if (!fs.existsSync(phrenPath))
+        return false;
+    let found = 0;
+    if (fs.existsSync(path.join(phrenPath, "machines.yaml")))
+        found++;
+    if (fs.existsSync(path.join(phrenPath, ".config")))
+        found++;
+    if (fs.existsSync(path.join(phrenPath, "global")))
+        found++;
+    return found >= 2;
+}
+export function resolveInitPhrenPath(opts) {
+    const raw = opts._walkthroughStoragePath || process.env.PHREN_PATH || DEFAULT_PHREN_PATH;
+    return path.resolve(expandHomePath(raw));
+}

package/mcp/dist/init-dryrun.js

@@ -0,0 +1,55 @@
+/**
+ * Dry-run output for init.
+ */
+import * as path from "path";
+import { getMachineName } from "./machine-identity.js";
+import { getPendingBootstrapTarget } from "./init-detect.js";
+import { log } from "./init/shared.js";
+export function printDryRun(phrenPath, opts, params) {
+    const { hasExistingInstall, mcpLabel, hooksLabel, hooksEnabled, storageChoice, storageRepoRoot } = params;
+    const pendingBootstrap = getPendingBootstrapTarget(phrenPath, opts);
+    log("\nInit dry run. No files will be written.\n");
+    if (storageChoice) {
+        log(`Storage location: ${storageChoice} (${phrenPath})`);
+        if (storageChoice === "project" && storageRepoRoot) {
+            log(`  Would update ${path.join(storageRepoRoot, ".gitignore")} with .phren/`);
+            log(`  Would set PHREN_PATH in ${path.join(storageRepoRoot, ".env")}`);
+        }
+    }
+    if (hasExistingInstall) {
+        log(`phren install detected at ${phrenPath}`);
+        log(`Would update configuration for the existing install:\n`);
+        log(`  MCP mode: ${mcpLabel}`);
+        log(`  Hooks mode: ${hooksLabel}`);
+        log(`  Reconfigure Claude Code MCP/hooks`);
+        log(`  Reconfigure VS Code, Cursor, Copilot CLI, and Codex MCP targets`);
+        if (hooksEnabled) {
+            log(`  Reconfigure lifecycle hooks for detected tools`);
+        }
+        if (pendingBootstrap?.mode === "detected") {
+            log(`  Would offer to add current project directory (${pendingBootstrap.path})`);
+        }
+        if (opts.applyStarterUpdate) {
+            log(`  Apply starter template updates to global/CLAUDE.md and global skills`);
+        }
+        log(`  Run post-init verification checks`);
+        log(`\nDry run complete.\n`);
+        return;
+    }
+    log(`No existing phren install found at ${phrenPath}`);
+    log(`Would create a new phren install:\n`);
+    log(`  Copy starter files to ${phrenPath} (or create minimal structure)`);
+    log(`  Update machines.yaml for machine "${opts.machine || getMachineName()}"`);
+    log(`  Create/update config files`);
+    log(`  MCP mode: ${mcpLabel}`);
+    log(`  Hooks mode: ${hooksLabel}`);
+    log(`  Configure Claude Code plus detected MCP targets (VS Code/Cursor/Copilot/Codex)`);
+    if (hooksEnabled) {
+        log(`  Configure lifecycle hooks for detected tools`);
+    }
+    if (pendingBootstrap?.mode === "detected") {
+        log(`  Would offer to add current project directory (${pendingBootstrap.path})`);
+    }
+    log(`  Write install preferences and run post-init verification checks`);
+    log(`\nDry run complete.\n`);
+}

package/mcp/dist/init-env.js

@@ -0,0 +1,114 @@
+/**
+ * Environment flags, onboarding preferences, and repair asset helpers for init.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { writeInstallPreferences, writeGovernanceInstallPreferences, } from "./init/preferences.js";
+import { updateWorkflowPolicy } from "./shared/governance.js";
+import { ensureGitignoreEntry, upsertProjectEnvVar, } from "./init/setup.js";
+export function applyOnboardingPreferences(phrenPath, opts) {
+    if (opts.projectOwnershipDefault) {
+        writeInstallPreferences(phrenPath, { projectOwnershipDefault: opts.projectOwnershipDefault });
+    }
+    const runtimePatch = {};
+    if (opts.findingsProactivity)
+        runtimePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        runtimePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(runtimePatch).length > 0) {
+        writeInstallPreferences(phrenPath, runtimePatch);
+    }
+    const governancePatch = {};
+    if (opts.findingsProactivity)
+        governancePatch.proactivityFindings = opts.findingsProactivity;
+    if (opts.taskProactivity)
+        governancePatch.proactivityTask = opts.taskProactivity;
+    if (Object.keys(governancePatch).length > 0) {
+        writeGovernanceInstallPreferences(phrenPath, governancePatch);
+    }
+    const workflowPatch = {};
+    if (typeof opts.lowConfidenceThreshold === "number")
+        workflowPatch.lowConfidenceThreshold = opts.lowConfidenceThreshold;
+    if (Array.isArray(opts.riskySections))
+        workflowPatch.riskySections = opts.riskySections;
+    if (opts.taskMode)
+        workflowPatch.taskMode = opts.taskMode;
+    if (opts.findingSensitivity)
+        workflowPatch.findingSensitivity = opts.findingSensitivity;
+    if (Object.keys(workflowPatch).length > 0) {
+        updateWorkflowPolicy(phrenPath, workflowPatch);
+    }
+}
+export function writeWalkthroughEnvDefaults(phrenPath, opts) {
+    const envFile = path.join(phrenPath, ".env");
+    let envContent = fs.existsSync(envFile) ? fs.readFileSync(envFile, "utf8") : "# phren feature flags — generated by init\n";
+    const envFlags = [];
+    const autoCaptureChoice = opts._walkthroughAutoCapture;
+    const hasAutoCaptureFlag = /^\s*PHREN_FEATURE_AUTO_CAPTURE=.*$/m.test(envContent);
+    if (typeof autoCaptureChoice === "boolean") {
+        envFlags.push({
+            flag: `PHREN_FEATURE_AUTO_CAPTURE=${autoCaptureChoice ? "1" : "0"}`,
+            label: `Auto-capture ${autoCaptureChoice ? "enabled" : "disabled"}`,
+        });
+    }
+    else if (!hasAutoCaptureFlag) {
+        // Default to enabled on fresh installs and non-walkthrough init.
+        envFlags.push({ flag: "PHREN_FEATURE_AUTO_CAPTURE=1", label: "Auto-capture enabled" });
+    }
+    if (opts._walkthroughSemanticDedup)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_DEDUP=1", label: "Semantic dedup" });
+    if (opts._walkthroughSemanticConflict)
+        envFlags.push({ flag: "PHREN_FEATURE_SEMANTIC_CONFLICT=1", label: "Conflict detection" });
+    if (envFlags.length === 0)
+        return [];
+    let changed = false;
+    const enabledLabels = [];
+    for (const { flag, label } of envFlags) {
+        const key = flag.split("=")[0];
+        const lineRe = new RegExp(`^\\s*${key}=.*$`, "m");
+        if (lineRe.test(envContent)) {
+            const before = envContent;
+            envContent = envContent.replace(lineRe, flag);
+            if (envContent !== before) {
+                changed = true;
+                enabledLabels.push(label);
+            }
+        }
+        else {
+            if (!envContent.endsWith("\n"))
+                envContent += "\n";
+            envContent += `${flag}\n`;
+            changed = true;
+            enabledLabels.push(label);
+        }
+    }
+    if (changed) {
+        const tmpPath = `${envFile}.tmp-${crypto.randomUUID()}`;
+        fs.writeFileSync(tmpPath, envContent);
+        fs.renameSync(tmpPath, envFile);
+    }
+    return enabledLabels.map((label) => `${label} (${envFile})`);
+}
+export function collectRepairedAssetLabels(repaired) {
+    const repairedAssets = [];
+    if (repaired.createdContextFile)
+        repairedAssets.push("~/.phren-context.md");
+    if (repaired.createdRootMemory)
+        repairedAssets.push("generated MEMORY.md");
+    repairedAssets.push(...repaired.createdGlobalAssets);
+    repairedAssets.push(...repaired.createdRuntimeAssets);
+    repairedAssets.push(...repaired.createdFeatureDefaults);
+    repairedAssets.push(...repaired.createdSkillArtifacts);
+    return repairedAssets;
+}
+export function applyProjectStorageBindings(repoRoot, phrenPath) {
+    const updates = [];
+    if (ensureGitignoreEntry(repoRoot, ".phren/")) {
+        updates.push(`${path.join(repoRoot, ".gitignore")} (.phren/)`);
+    }
+    if (upsertProjectEnvVar(repoRoot, "PHREN_PATH", phrenPath)) {
+        updates.push(`${path.join(repoRoot, ".env")} (PHREN_PATH=${phrenPath})`);
+    }
+    return updates;
+}

package/mcp/dist/init-fresh.js

@@ -0,0 +1,239 @@
+/**
+ * Fresh install logic: copy starter, scaffold project, write initial config.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { atomicWriteText, debugLog, hookConfigPath, writeRootManifest, } from "./shared.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
+import { getMachineName, persistMachineName } from "./machine-identity.js";
+import { writeInstallPreferences, } from "./init/preferences.js";
+import { ensureGovernanceFiles, repairPreexistingInstall, runPostInitVerify, listTemplates, applyTemplate, ensureProjectScaffold, ensureLocalGitRepo, updateMachinesYaml, detectProjectDir, } from "./init/setup.js";
+import { getWorkflowPolicy } from "./shared/governance.js";
+import { addProjectToProfile } from "./profile-store.js";
+import { STARTER_DIR, VERSION, log, confirmPrompt } from "./init/shared.js";
+import { configureMcpTargets } from "./init-mcp.js";
+import { configureHooksIfEnabled } from "./init-hooks.js";
+import { applyOnboardingPreferences, writeWalkthroughEnvDefaults, collectRepairedAssetLabels, } from "./init-env.js";
+import { warmSemanticSearch } from "./init-semantic.js";
+import { bootstrapProject } from "./init-bootstrap.js";
+import { logger } from "./logger.js";
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (src === STARTER_DIR && entry.isDirectory() && ["my-api", "my-frontend", "my-first-project"].includes(entry.name)) {
+            continue;
+        }
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export async function runFreshInstall(phrenPath, opts, params) {
+    const { mcpEnabled, hooksEnabled, skillsScope, ownershipDefault, syncIntent, shouldBootstrapCurrentProject, bootstrapOwnership, } = params;
+    log("\nSetting up phren...\n");
+    const walkthroughProject = opts._walkthroughProject;
+    if (walkthroughProject) {
+        if (!walkthroughProject.trim()) {
+            console.error("Error: project name cannot be empty.");
+            process.exit(1);
+        }
+        if (walkthroughProject.length > 100) {
+            console.error("Error: project name must be 100 characters or fewer.");
+            process.exit(1);
+        }
+        if (!isValidProjectName(walkthroughProject)) {
+            console.error(`Error: invalid project name "${walkthroughProject}". Use lowercase letters, numbers, and hyphens.`);
+            process.exit(1);
+        }
+    }
+    const cwdProjectPath = !walkthroughProject ? detectProjectDir(process.cwd(), phrenPath) : null;
+    const useTemplateProject = Boolean(walkthroughProject) || Boolean(opts.template);
+    const firstProjectName = walkthroughProject || "my-first-project";
+    const firstProjectDomain = opts._walkthroughDomain ?? "software";
+    if (fs.existsSync(STARTER_DIR)) {
+        copyDir(STARTER_DIR, phrenPath);
+        writeRootManifest(phrenPath, {
+            version: 1,
+            installMode: "shared",
+            syncMode: "managed-git",
+        });
+        if (useTemplateProject) {
+            const targetProject = walkthroughProject || firstProjectName;
+            const projectDir = path.join(phrenPath, targetProject);
+            const templateApplied = Boolean(opts.template && applyTemplate(projectDir, opts.template, targetProject));
+            if (templateApplied) {
+                log(`  Applied "${opts.template}" template to ${targetProject}`);
+            }
+            ensureProjectScaffold(projectDir, targetProject, firstProjectDomain, opts._walkthroughInferredScaffold);
+            const targetProfile = opts.profile || "default";
+            const addToProfile = addProjectToProfile(phrenPath, targetProfile, targetProject);
+            if (!addToProfile.ok) {
+                debugLog(`fresh init addProjectToProfile failed for ${targetProfile}/${targetProject}: ${addToProfile.error}`);
+            }
+            if (opts.template && !templateApplied) {
+                log(`  Template "${opts.template}" not found. Available: ${listTemplates().join(", ") || "none"}`);
+            }
+            log(`  Seeded project "${targetProject}"`);
+        }
+        log(`  Created phren v${VERSION} \u2192 ${phrenPath}`);
+    }
+    else {
+        log(`  Starter not found in package, creating minimal structure...`);
+        writeRootManifest(phrenPath, {
+            version: 1,
+            installMode: "shared",
+            syncMode: "managed-git",
+        });
+        fs.mkdirSync(path.join(phrenPath, "global", "skills"), { recursive: true });
+        fs.mkdirSync(path.join(phrenPath, "profiles"), { recursive: true });
+        atomicWriteText(path.join(phrenPath, "global", "CLAUDE.md"), `# Global Context\n\nThis file is loaded in every project.\n\n## General preferences\n\n<!-- Your coding style, preferred tools, things Claude should always know -->\n`);
+        if (useTemplateProject) {
+            const projectDir = path.join(phrenPath, firstProjectName);
+            if (opts.template && applyTemplate(projectDir, opts.template, firstProjectName)) {
+                log(`  Applied "${opts.template}" template to ${firstProjectName}`);
+            }
+            ensureProjectScaffold(projectDir, firstProjectName, firstProjectDomain, opts._walkthroughInferredScaffold);
+        }
+        const profileName = opts.profile || "default";
+        const profileProjects = useTemplateProject
+            ? `  - global\n  - ${firstProjectName}`
+            : `  - global`;
+        atomicWriteText(path.join(phrenPath, "profiles", `${profileName}.yaml`), `name: ${profileName}\ndescription: Default profile\nprojects:\n${profileProjects}\n`);
+    }
+    // Bootstrap CWD project if opted in
+    if (cwdProjectPath && shouldBootstrapCurrentProject) {
+        bootstrapProject(phrenPath, cwdProjectPath, opts.profile, bootstrapOwnership, "Added current project");
+    }
+    // Persist machine and config
+    const effectiveMachine = opts.machine?.trim() || getMachineName();
+    persistMachineName(effectiveMachine);
+    updateMachinesYaml(phrenPath, effectiveMachine, opts.profile);
+    ensureGovernanceFiles(phrenPath);
+    const repaired = repairPreexistingInstall(phrenPath);
+    applyOnboardingPreferences(phrenPath, opts);
+    const localGitRepo = ensureLocalGitRepo(phrenPath);
+    log(`  Updated machines.yaml with machine "${effectiveMachine}"`);
+    const mcpLabel = mcpEnabled ? "ON (recommended)" : "OFF (hooks-only fallback)";
+    const hooksLabel = hooksEnabled ? "ON (active)" : "OFF (disabled)";
+    log(`  MCP mode: ${mcpLabel}`);
+    log(`  Hooks mode: ${hooksLabel}`);
+    log(`  Default project ownership: ${ownershipDefault}`);
+    log(`  Task mode: ${getWorkflowPolicy(phrenPath).taskMode}`);
+    log(`  Git repo: ${localGitRepo.detail}`);
+    if (repaired.removedLegacyProjects > 0) {
+        log(`  Removed ${repaired.removedLegacyProjects} legacy starter project entr${repaired.removedLegacyProjects === 1 ? "y" : "ies"} from profiles.`);
+    }
+    const repairedAssets = collectRepairedAssetLabels(repaired);
+    if (repairedAssets.length > 0) {
+        log(`  Recreated missing generated assets: ${repairedAssets.join(", ")}`);
+    }
+    // Confirmation prompt before writing agent config
+    if (!opts.yes) {
+        const settingsPath = hookConfigPath("claude");
+        log(`\nWill modify:`);
+        log(`  ${settingsPath}  (add MCP server + hooks)`);
+        const confirmed = await confirmPrompt("\nProceed?");
+        if (!confirmed) {
+            log("Aborted.");
+            return;
+        }
+    }
+    // Configure MCP and hooks
+    configureMcpTargets(phrenPath, { mcpEnabled, hooksEnabled }, "Configured");
+    configureHooksIfEnabled(phrenPath, hooksEnabled, "Configured");
+    writeInstallPreferences(phrenPath, { mcpEnabled, hooksEnabled, skillsScope, installedVersion: VERSION, syncIntent });
+    // Post-init verification
+    log(`\nVerifying setup...`);
+    const verify = runPostInitVerify(phrenPath);
+    for (const check of verify.checks) {
+        log(`  ${check.ok ? "pass" : "FAIL"} ${check.name}: ${check.detail}`);
+    }
+    log(`\nWhat was created:`);
+    log(`  ${phrenPath}/global/CLAUDE.md    Global instructions loaded in every session`);
+    log(`  ${phrenPath}/global/skills/      Phren slash commands`);
+    log(`  ${phrenPath}/profiles/           Machine-to-project mappings`);
+    log(`  ${phrenPath}/.config/        Memory quality settings and config`);
+    // Ollama status summary (skip if already covered in walkthrough)
+    const walkthroughCoveredOllama = Boolean(process.env._PHREN_WALKTHROUGH_OLLAMA_SKIP) || !opts.yes;
+    if (!walkthroughCoveredOllama) {
+        try {
+            const { checkOllamaAvailable, checkModelAvailable, getOllamaUrl } = await import("./shared/ollama.js");
+            if (getOllamaUrl()) {
+                const ollamaUp = await checkOllamaAvailable();
+                if (ollamaUp) {
+                    const modelReady = await checkModelAvailable();
+                    if (modelReady) {
+                        log("\n  Semantic search: Ollama + nomic-embed-text ready.");
+                    }
+                    else {
+                        log("\n  Semantic search: Ollama running, but nomic-embed-text not pulled.");
+                        log("  Run: ollama pull nomic-embed-text");
+                    }
+                }
+                else {
+                    log("\n  Tip: Install Ollama for semantic search (optional).");
+                    log("  https://ollama.com → then: ollama pull nomic-embed-text");
+                    log("  (Set PHREN_OLLAMA_URL=off to hide this message)");
+                }
+            }
+        }
+        catch (err) {
+            logger.debug("init ollamaInstallHint", errorMessage(err));
+        }
+    }
+    for (const envLabel of writeWalkthroughEnvDefaults(phrenPath, opts)) {
+        log(`  ${envLabel}`);
+    }
+    if (opts._walkthroughSemanticSearch) {
+        log(`\nWarming semantic search...`);
+        try {
+            log(`  ${await warmSemanticSearch(phrenPath, opts.profile)}`);
+        }
+        catch (err) {
+            log(`  Semantic search warmup failed: ${errorMessage(err)}`);
+        }
+    }
+    log(`\n\x1b[95m◆\x1b[0m phren initialized`);
+    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\``);
+    const gh = opts._walkthroughGithub;
+    if (gh) {
+        const remote = gh.username
+            ? `git@github.com:${gh.username}/${gh.repo}.git`
+            : `git@github.com:YOUR_USERNAME/${gh.repo}.git`;
+        log(`  ${step++}. Push your phren to GitHub (private repo recommended):`);
+        log(`     cd ${phrenPath}`);
+        log(`     git add . && git commit -m "Initial phren setup"`);
+        if (gh.username) {
+            log(`     gh repo create ${gh.username}/${gh.repo} --private --source=. --push`);
+            log(`     # or manually: git remote add origin ${remote} && git push -u origin main`);
+        }
+        else {
+            log(`     git remote add origin ${remote}`);
+            log(`     git push -u origin main`);
+        }
+    }
+    else {
+        log(`  ${step++}. Push to GitHub for cross-machine sync (private repo recommended):`);
+        log(`     cd ${phrenPath}`);
+        log(`     git add . && git commit -m "Initial phren setup"`);
+        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`);
+    if (!mcpEnabled) {
+        log(`  ${step++}. Turn MCP on: npx 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`);
+    log(`\n  Read ${phrenPath}/README.md for a guided tour of each file.`);
+    log(``);
+}

package/mcp/dist/init-hooks.js

@@ -0,0 +1,26 @@
+/**
+ * Hook configuration helper for init.
+ */
+import { configureAllHooks } from "./hooks.js";
+import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.js";
+import { log } from "./init/shared.js";
+/**
+ * Configure hooks if enabled, or log a disabled message.
+ * @param verb - label used in log messages, e.g. "Updated" or "Configured"
+ */
+export function configureHooksIfEnabled(phrenPath, hooksEnabled, verb) {
+    if (hooksEnabled) {
+        try {
+            const hooked = configureAllHooks(phrenPath, { allTools: true });
+            if (hooked.length)
+                log(`  ${verb} hooks: ${hooked.join(", ")}`);
+        }
+        catch (err) {
+            debugLog(`configureAllHooks failed: ${errorMessage(err)}`);
+        }
+    }
+    else {
+        log(`  Hooks are disabled by preference (run: npx phren hooks-mode on)`);
+    }
+}

package/mcp/dist/init-mcp.js

@@ -0,0 +1,65 @@
+/**
+ * MCP target configuration for all detected AI coding tools.
+ */
+import { configureClaude, configureVSCode, configureCursorMcp, configureCopilotMcp, configureCodexMcp, logMcpTargetStatus, } from "./init/config.js";
+import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.js";
+import { log } from "./init/shared.js";
+/**
+ * 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"
+ */
+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)`);
+        }
+        else {
+            log(`  ${verb} Claude Code MCP + hooks`);
+        }
+    }
+    catch (e) {
+        log(`  Could not configure Claude Code settings (${e}), add manually`);
+    }
+    let vsStatus = "no_vscode";
+    try {
+        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 {
+        cursorStatus = configureCursorMcp(phrenPath, { mcpEnabled: opts.mcpEnabled }) ?? "no_cursor";
+        logMcpTargetStatus("Cursor", cursorStatus, verb);
+    }
+    catch (err) {
+        debugLog(`configureCursorMcp failed: ${errorMessage(err)}`);
+    }
+    let copilotStatus = "no_copilot";
+    try {
+        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 {
+        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;
+}

package/mcp/dist/init-migrate.js

@@ -0,0 +1,51 @@
+/**
+ * Legacy migration helpers for init: directory rename, skill rename.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { homePath } from "./shared.js";
+import { hasInstallMarkers } from "./init-detect.js";
+/**
+ * Migrate the legacy hidden store directory into ~/.phren when upgrading
+ * from the previous product name.
+ * @returns true if migration occurred
+ */
+export function migrateLegacyStore(phrenPath, dryRun) {
+    const legacyPath = path.resolve(homePath(".cortex"));
+    if (legacyPath === phrenPath || !fs.existsSync(legacyPath) || !hasInstallMarkers(legacyPath)) {
+        return false;
+    }
+    if (!dryRun) {
+        fs.renameSync(legacyPath, phrenPath);
+    }
+    console.log(`Migrated legacy store → ~/.phren`);
+    return true;
+}
+/**
+ * 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.
+ */
+export function migrateLegacySkills(phrenPath) {
+    const skillsMigrateDir = path.join(phrenPath, "global", "skills");
+    if (!fs.existsSync(skillsMigrateDir))
+        return;
+    const legacySkillName = "cortex.md";
+    const legacySkillPrefix = "cortex-";
+    for (const entry of fs.readdirSync(skillsMigrateDir)) {
+        if (!entry.endsWith(".md"))
+            continue;
+        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(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);
+            }
+        }
+    }
+}