@phren/cli 0.0.43 → 0.0.45

package/mcp/dist/cli/actions.js

@@ -63,6 +63,29 @@ export async function handlePinCanonical(project, memory) {
     const result = upsertCanonical(getPhrenPath(), project, memory);
     console.log(result.ok ? result.data : result.error);
 }
+export async function handleTruths(project) {
+    if (!project) {
+        console.error("Usage: phren truths <project>");
+        process.exit(1);
+    }
+    const phrenPath = getPhrenPath();
+    const truthsPath = path.join(phrenPath, project, "truths.md");
+    if (!fs.existsSync(truthsPath)) {
+        console.log(`No truths pinned for "${project}" yet.`);
+        console.log(`\nPin one: phren pin ${project} "your truth here"`);
+        return;
+    }
+    const content = fs.readFileSync(truthsPath, "utf8");
+    const truths = content.split("\n").filter((line) => line.startsWith("- "));
+    if (truths.length === 0) {
+        console.log(`No truths pinned for "${project}" yet.`);
+        return;
+    }
+    console.log(`${truths.length} truth(s) for "${project}":\n`);
+    for (const truth of truths) {
+        console.log(`  ${truth}`);
+    }
+}
 export async function handleDoctor(args) {
     const profile = resolveRuntimeProfile(getPhrenPath());
     const fix = args.includes("--fix");

package/mcp/dist/cli/cli.js

@@ -8,8 +8,9 @@ import { handleGovernMemories, handlePruneMemories, handleConsolidateMemories, h
 import { handleConfig, handleIndexPolicy, handleRetentionPolicy, handleWorkflowPolicy, } from "./config.js";
 import { parseSearchArgs } from "./search.js";
 import { handleDetectSkills, handleFindingNamespace, handleHooksNamespace, handleProjectsNamespace, handleSkillsNamespace, handleSkillList, handlePromoteNamespace, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
+import { handleTeamNamespace } from "./team.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 { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handleTruths, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleReview, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
 import { handleGraphNamespace } from "./graph.js";
 import { resolveRuntimeProfile } from "../runtime-profile.js";
 // ── CLI router ───────────────────────────────────────────────────────────────
@@ -107,8 +108,12 @@ export async function runCliCommand(command, args) {
             return handleConsolidationStatus(args);
         case "session-context":
             return handleSessionContext();
+        case "truths":
+            return handleTruths(args[0]);
         case "store":
             return handleStoreNamespace(args);
+        case "team":
+            return handleTeamNamespace(args);
         case "promote":
             return handlePromoteNamespace(args);
         default:

package/mcp/dist/cli/team.js

@@ -0,0 +1,301 @@
+/**
+ * Team store CLI commands: init, join, add-project.
+ * Creates and manages shared phren stores for team collaboration.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { getPhrenPath } from "../shared.js";
+import { isValidProjectName } from "../utils.js";
+import { addStoreToRegistry, findStoreByName, generateStoreId, readTeamBootstrap, updateStoreProjects, } from "../store-registry.js";
+const EXEC_TIMEOUT_MS = 30_000;
+function getOptionValue(args, name) {
+    const exactIdx = args.indexOf(name);
+    if (exactIdx !== -1)
+        return args[exactIdx + 1];
+    const prefixed = args.find((arg) => arg.startsWith(`${name}=`));
+    return prefixed ? prefixed.slice(name.length + 1) : undefined;
+}
+function getPositionalArgs(args, optionNames) {
+    const positions = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (optionNames.includes(arg)) {
+            i++;
+            continue;
+        }
+        if (optionNames.some((name) => arg.startsWith(`${name}=`)))
+            continue;
+        if (!arg.startsWith("--"))
+            positions.push(arg);
+    }
+    return positions;
+}
+function atomicWriteText(filePath, content) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = filePath + ".tmp." + process.pid;
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, filePath);
+}
+// ── phren team init <name> [--remote <url>] [--description <desc>] ──────────
+async function handleTeamInit(args) {
+    const phrenPath = getPhrenPath();
+    const positional = getPositionalArgs(args, ["--remote", "--description"]);
+    const name = positional[0];
+    const remote = getOptionValue(args, "--remote");
+    const description = getOptionValue(args, "--description");
+    if (!name) {
+        console.error("Usage: phren team init <name> [--remote <url>] [--description <text>]");
+        process.exit(1);
+    }
+    if (!isValidProjectName(name)) {
+        console.error(`Invalid store name: "${name}". Use lowercase letters, numbers, hyphens.`);
+        process.exit(1);
+    }
+    // Check if store already exists
+    const existing = findStoreByName(phrenPath, name);
+    if (existing) {
+        console.error(`Store "${name}" already exists at ${existing.path}`);
+        process.exit(1);
+    }
+    const storesDir = path.join(path.dirname(phrenPath), ".phren-stores");
+    const storePath = path.join(storesDir, name);
+    if (fs.existsSync(storePath)) {
+        console.error(`Directory already exists: ${storePath}`);
+        process.exit(1);
+    }
+    // Create the team store directory
+    fs.mkdirSync(storePath, { recursive: true });
+    // Write .phren-team.yaml
+    const bootstrap = {
+        name,
+        description: description || `${name} team knowledge`,
+        default_role: "team",
+    };
+    atomicWriteText(path.join(storePath, ".phren-team.yaml"), `name: ${bootstrap.name}\ndescription: ${bootstrap.description}\ndefault_role: team\n`);
+    // Write .gitignore
+    atomicWriteText(path.join(storePath, ".gitignore"), ".runtime/\n.sessions/\n*.lock\n");
+    // Create global directory with starter files
+    const globalDir = path.join(storePath, "global");
+    fs.mkdirSync(globalDir, { recursive: true });
+    atomicWriteText(path.join(globalDir, "CLAUDE.md"), `# ${name} Team Store\n\nShared knowledge for the ${name} team.\n`);
+    atomicWriteText(path.join(globalDir, "FINDINGS.md"), `# global findings\n`);
+    // Initialize git repo
+    execFileSync("git", ["init"], {
+        cwd: storePath,
+        stdio: "pipe",
+        timeout: EXEC_TIMEOUT_MS,
+    });
+    // Initial commit
+    execFileSync("git", ["add", "-A"], { cwd: storePath, stdio: "pipe", timeout: EXEC_TIMEOUT_MS });
+    execFileSync("git", ["commit", "-m", "phren: initialize team store"], {
+        cwd: storePath,
+        stdio: "pipe",
+        timeout: EXEC_TIMEOUT_MS,
+    });
+    // Add remote if provided
+    if (remote) {
+        execFileSync("git", ["remote", "add", "origin", remote], {
+            cwd: storePath,
+            stdio: "pipe",
+            timeout: EXEC_TIMEOUT_MS,
+        });
+        try {
+            execFileSync("git", ["push", "-u", "origin", "main"], {
+                cwd: storePath,
+                stdio: "pipe",
+                timeout: EXEC_TIMEOUT_MS,
+            });
+            console.log(`  Pushed to ${remote}`);
+        }
+        catch {
+            // Try HEAD branch name
+            try {
+                execFileSync("git", ["push", "-u", "origin", "HEAD"], {
+                    cwd: storePath,
+                    stdio: "pipe",
+                    timeout: EXEC_TIMEOUT_MS,
+                });
+                console.log(`  Pushed to ${remote}`);
+            }
+            catch {
+                console.log(`  Remote added but push failed. Push manually: cd ${storePath} && git push -u origin main`);
+            }
+        }
+    }
+    // Register in primary store's stores.yaml
+    const entry = {
+        id: generateStoreId(),
+        name,
+        path: storePath,
+        role: "team",
+        sync: "managed-git",
+        ...(remote ? { remote } : {}),
+    };
+    addStoreToRegistry(phrenPath, entry);
+    console.log(`\nCreated team store: ${name}`);
+    console.log(`  Path: ${storePath}`);
+    console.log(`  Role: team`);
+    console.log(`  ID: ${entry.id}`);
+    if (!remote) {
+        console.log(`\nNext: add a remote and push`);
+        console.log(`  cd ${storePath}`);
+        console.log(`  git remote add origin <your-git-url>`);
+        console.log(`  git push -u origin main`);
+    }
+    console.log(`\nAdd projects: phren team add-project ${name} <project-name>`);
+}
+// ── phren team join <url> [--name <name>] ───────────────────────────────────
+async function handleTeamJoin(args) {
+    const phrenPath = getPhrenPath();
+    const positional = getPositionalArgs(args, ["--name"]);
+    const remote = positional[0];
+    const nameOverride = getOptionValue(args, "--name");
+    if (!remote) {
+        console.error("Usage: phren team join <git-url> [--name <name>]");
+        process.exit(1);
+    }
+    const storesDir = path.join(path.dirname(phrenPath), ".phren-stores");
+    // Infer name from URL if not provided
+    const inferredName = nameOverride || path.basename(remote, ".git").toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+    if (!isValidProjectName(inferredName)) {
+        console.error(`Invalid store name: "${inferredName}". Use --name to specify a valid name.`);
+        process.exit(1);
+    }
+    const existing = findStoreByName(phrenPath, inferredName);
+    if (existing) {
+        console.error(`Store "${inferredName}" already exists at ${existing.path}`);
+        process.exit(1);
+    }
+    const storePath = path.join(storesDir, inferredName);
+    if (fs.existsSync(storePath)) {
+        console.error(`Directory already exists: ${storePath}`);
+        process.exit(1);
+    }
+    // Clone the remote
+    console.log(`Cloning ${remote}...`);
+    fs.mkdirSync(storesDir, { recursive: true });
+    execFileSync("git", ["clone", "--", remote, storePath], {
+        stdio: "inherit",
+        timeout: 60_000,
+    });
+    // Read .phren-team.yaml if present
+    const bootstrap = readTeamBootstrap(storePath);
+    const finalName = bootstrap?.name || inferredName;
+    const finalRole = bootstrap?.default_role === "primary" ? "team" : (bootstrap?.default_role || "team");
+    const entry = {
+        id: generateStoreId(),
+        name: finalName,
+        path: storePath,
+        role: finalRole,
+        sync: finalRole === "readonly" ? "pull-only" : "managed-git",
+        remote,
+    };
+    addStoreToRegistry(phrenPath, entry);
+    console.log(`\nJoined team store: ${finalName}`);
+    console.log(`  Path: ${storePath}`);
+    console.log(`  Role: ${finalRole}`);
+    console.log(`  ID: ${entry.id}`);
+    if (bootstrap?.description) {
+        console.log(`  Description: ${bootstrap.description}`);
+    }
+}
+// ── phren team add-project <store> <project> ────────────────────────────────
+async function handleTeamAddProject(args) {
+    const phrenPath = getPhrenPath();
+    const positional = getPositionalArgs(args, []);
+    const storeName = positional[0];
+    const projectName = positional[1];
+    if (!storeName || !projectName) {
+        console.error("Usage: phren team add-project <store-name> <project-name>");
+        process.exit(1);
+    }
+    if (!isValidProjectName(projectName)) {
+        console.error(`Invalid project name: "${projectName}"`);
+        process.exit(1);
+    }
+    const store = findStoreByName(phrenPath, storeName);
+    if (!store) {
+        console.error(`Store "${storeName}" not found. Run 'phren store list' to see available stores.`);
+        process.exit(1);
+    }
+    if (store.role === "readonly") {
+        console.error(`Store "${storeName}" is read-only. Cannot add projects.`);
+        process.exit(1);
+    }
+    // Create project directory in the store
+    const projectDir = path.join(store.path, projectName);
+    const journalDir = path.join(projectDir, "journal");
+    fs.mkdirSync(journalDir, { recursive: true });
+    // Scaffold project files
+    if (!fs.existsSync(path.join(projectDir, "FINDINGS.md"))) {
+        atomicWriteText(path.join(projectDir, "FINDINGS.md"), `# ${projectName} findings\n`);
+    }
+    if (!fs.existsSync(path.join(projectDir, "tasks.md"))) {
+        atomicWriteText(path.join(projectDir, "tasks.md"), `# ${projectName} tasks\n\n## Active\n\n## Queue\n\n## Done\n`);
+    }
+    if (!fs.existsSync(path.join(projectDir, "summary.md"))) {
+        atomicWriteText(path.join(projectDir, "summary.md"), `# ${projectName}\n**What:** \n`);
+    }
+    // Update store's project claims in registry
+    const currentProjects = store.projects || [];
+    if (!currentProjects.includes(projectName)) {
+        updateStoreProjects(phrenPath, storeName, [...currentProjects, projectName]);
+    }
+    console.log(`Added project "${projectName}" to team store "${storeName}"`);
+    console.log(`  Path: ${projectDir}`);
+    console.log(`  Journal: ${journalDir}`);
+    console.log(`\nWrites to "${projectName}" will now route to "${storeName}" automatically.`);
+}
+// ── phren team list ─────────────────────────────────────────────────────────
+async function handleTeamList() {
+    const phrenPath = getPhrenPath();
+    const { resolveAllStores } = await import("../store-registry.js");
+    const stores = resolveAllStores(phrenPath);
+    const teamStores = stores.filter((s) => s.role === "team");
+    if (teamStores.length === 0) {
+        console.log("No team stores registered.");
+        console.log("\nCreate one:  phren team init <name> [--remote <url>]");
+        console.log("Join one:    phren team join <git-url>");
+        return;
+    }
+    console.log(`${teamStores.length} team store(s):\n`);
+    for (const store of teamStores) {
+        const exists = fs.existsSync(store.path);
+        console.log(`  ${store.name} (${store.id}) ${exists ? "" : "[missing]"}`);
+        console.log(`    path: ${store.path}`);
+        if (store.remote)
+            console.log(`    remote: ${store.remote}`);
+        if (store.projects?.length)
+            console.log(`    projects: ${store.projects.join(", ")}`);
+        console.log();
+    }
+}
+// ── Entry point ─────────────────────────────────────────────────────────────
+export async function handleTeamNamespace(args) {
+    const subcommand = args[0];
+    const subArgs = args.slice(1);
+    switch (subcommand) {
+        case "init":
+            return handleTeamInit(subArgs);
+        case "join":
+            return handleTeamJoin(subArgs);
+        case "add-project":
+            return handleTeamAddProject(subArgs);
+        case "list":
+            return handleTeamList();
+        default:
+            console.log(`phren team — manage shared team stores
+
+  phren team init <name> [--remote <url>]     Create a new team store
+  phren team join <git-url> [--name <name>]   Join an existing team store
+  phren team add-project <store> <project>    Add a project to a team store
+  phren team list                             List team stores
+`);
+            if (subcommand) {
+                console.error(`Unknown subcommand: ${subcommand}`);
+                process.exit(1);
+            }
+    }
+}

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

@@ -273,6 +273,24 @@ export async function handleHookSessionStart() {
     catch (err) {
         logger.debug("hookSessionStart trackSession", errorMessage(err));
     }
+    // Pull non-primary stores (team + readonly) so session starts with fresh data
+    try {
+        const { getNonPrimaryStores } = await import("./store-registry.js");
+        const otherStores = getNonPrimaryStores(phrenPath);
+        for (const store of otherStores) {
+            if (!fs.existsSync(store.path) || !fs.existsSync(path.join(store.path, ".git")))
+                continue;
+            try {
+                await runBestEffortGit(["pull", "--rebase", "--quiet"], store.path);
+            }
+            catch (err) {
+                debugLog(`session-start store-pull ${store.name}: ${errorMessage(err)}`);
+            }
+        }
+    }
+    catch {
+        // store-registry not available — skip silently
+    }
     updateRuntimeHealth(phrenPath, {
         lastSessionStartAt: startedAt,
         lastSync: {

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

@@ -485,18 +485,48 @@ export async function handleHookStop() {
         });
         appendAuditLog(phrenPath, "hook_stop", `status=saved-local detail=${JSON.stringify(syncDetail)}`);
     }); // end withFileLock(gitOpLockPath)
-    // Pull non-primary stores (best-effort, non-blocking)
+    // Sync non-primary stores: commit+push team stores, pull-only readonly stores
     try {
         const { getNonPrimaryStores } = await import("./store-registry.js");
         const otherStores = getNonPrimaryStores(phrenPath);
         for (const store of otherStores) {
             if (!fs.existsSync(store.path) || !fs.existsSync(path.join(store.path, ".git")))
                 continue;
-            try {
-                await runBestEffortGit(["pull", "--rebase", "--quiet"], store.path);
+            if (store.role === "team" && store.sync !== "pull-only") {
+                // Team stores with managed-git sync: stage team-safe files, commit, and push
+                try {
+                    const storeStatus = await runBestEffortGit(["status", "--porcelain"], store.path);
+                    if (storeStatus.ok && storeStatus.output) {
+                        // Only stage journal/, tasks.md, truths.md, FINDINGS.md, summary.md — NOT .runtime/
+                        await runBestEffortGit(["add", "--", "*/journal/*", "*/tasks.md", "*/truths.md", "*/FINDINGS.md", "*/summary.md", ".phren-team.yaml"], store.path);
+                        const actor = process.env.PHREN_ACTOR || process.env.USER || "unknown";
+                        const teamCommit = await runBestEffortGit(["commit", "-m", `phren: ${actor} team sync`], store.path);
+                        if (teamCommit.ok) {
+                            // Check for remote before pushing
+                            const storeRemotes = await runBestEffortGit(["remote"], store.path);
+                            if (storeRemotes.ok && storeRemotes.output?.trim()) {
+                                const teamPush = await runBestEffortGit(["push"], store.path);
+                                if (!teamPush.ok) {
+                                    // Try pull-rebase then push
+                                    await runBestEffortGit(["pull", "--rebase", "--quiet"], store.path);
+                                    await runBestEffortGit(["push"], store.path);
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    debugLog(`hook-stop team-store-sync ${store.name}: ${errorMessage(err)}`);
+                }
             }
-            catch (err) {
-                debugLog(`hook-stop store-pull ${store.name}: ${errorMessage(err)}`);
+            else {
+                // Readonly stores: pull only
+                try {
+                    await runBestEffortGit(["pull", "--rebase", "--quiet"], store.path);
+                }
+                catch (err) {
+                    debugLog(`hook-stop store-pull ${store.name}: ${errorMessage(err)}`);
+                }
             }
         }
     }

package/mcp/dist/entrypoint.js

@@ -87,6 +87,12 @@ const HELP_TOPICS = {
   phren store add <name> --remote <url>   Add a team store
   phren store remove <name>               Remove a store (local only)
   phren store sync                        Pull all stores
+`,
+    team: `Team:
+  phren team init <name> [--remote <url>]     Create a new team store
+  phren team join <git-url> [--name <name>]   Join an existing team store
+  phren team add-project <store> <project>    Add a project to a team store
+  phren team list                             List team stores
 `,
     env: `Environment variables:
   PHREN_PATH                  Override phren directory (default: ~/.phren)
@@ -174,7 +180,9 @@ const CLI_COMMANDS = [
     "review",
     "consolidation-status",
     "session-context",
+    "truths",
     "store",
+    "team",
     "promote",
 ];
 async function flushTopLevelOutput() {

package/mcp/dist/init/setup.js

@@ -278,6 +278,7 @@ export function repairPreexistingInstall(phrenPath) {
     const profileRepair = pruneLegacySampleProjectsFromProfiles(phrenPath);
     const preferredHome = resolvePreferredHomeDir(phrenPath);
     const createdSkillArtifacts = ensureGeneratedSkillArtifacts(phrenPath, preferredHome);
+    const repairedGlobalSymlink = repairGlobalClaudeSymlink(phrenPath);
     return {
         profileFilesUpdated: profileRepair.filesUpdated,
         removedLegacyProjects: profileRepair.removed,
@@ -287,8 +288,46 @@ export function repairPreexistingInstall(phrenPath) {
         createdRuntimeAssets,
         createdFeatureDefaults,
         createdSkillArtifacts,
+        repairedGlobalSymlink,
     };
 }
+/** Re-create ~/.claude/CLAUDE.md symlink if the source exists but the link is missing/broken. */
+function repairGlobalClaudeSymlink(phrenPath) {
+    const src = path.join(phrenPath, "global", "CLAUDE.md");
+    if (!fs.existsSync(src))
+        return false;
+    const dest = homePath(".claude", "CLAUDE.md");
+    try {
+        const stat = fs.lstatSync(dest);
+        if (stat.isSymbolicLink()) {
+            const target = path.resolve(path.dirname(dest), fs.readlinkSync(dest));
+            if (target === path.resolve(src))
+                return false; // already correct
+            // Stale symlink pointing elsewhere — managed by phren, safe to replace
+            if (target.includes(".phren"))
+                fs.unlinkSync(dest);
+            else
+                return false; // not ours, don't touch
+        }
+        else {
+            return false; // regular file exists, don't clobber
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            return false;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.symlinkSync(src, dest);
+        debugLog(`repaired global CLAUDE.md symlink: ${dest} -> ${src}`);
+        return true;
+    }
+    catch (err) {
+        debugLog(`failed to repair global CLAUDE.md symlink: ${errorMessage(err)}`);
+        return false;
+    }
+}
 function isExpectedVerifyFailure(phrenPath, check) {
     if (check.ok)
         return false;
@@ -1312,7 +1351,7 @@ export function runPostInitVerify(phrenPath) {
         ok: true, // always pass — wrapper is optional (global install or npx work too)
         detail: cliWrapperOk
             ? `CLI wrapper exists: ${cliWrapperPath}`
-            : `CLI wrapper not found (optional — use 'npm i -g @phren/cli' or 'npx @phren/cli' instead)`,
+            : `CLI wrapper not found (optional — use 'npx @phren/cli' instead)`,
     });
     const ok = checks.every((c) => c.ok);
     return { ok, checks };

package/mcp/dist/link/doctor.js

@@ -409,7 +409,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         ok: phrenCliActive,
         detail: phrenCliActive
             ? "phren CLI wrapper active via ~/.local/bin/phren"
-            : "phren CLI wrapper missing — run init to install, or npm i -g @phren/cli",
+            : "phren CLI wrapper missing — run 'npx @phren/cli init' to install",
     });
     if (fix) {
         const repaired = repairPreexistingInstall(phrenPath);

package/mcp/dist/shared/index.js

@@ -4,6 +4,46 @@ import * as os from "os";
 import * as crypto from "crypto";
 import { globSync } from "glob";
 import { debugLog, appendIndexEvent, getProjectDirs, collectNativeMemoryFiles, runtimeFile, homeDir, readRootManifest, } from "../shared.js";
+/**
+ * Cached store project dirs to avoid repeated dynamic imports in sync code paths.
+ * Populated by `refreshStoreProjectDirs()`, consumed by `getAllStoreProjectDirs()`.
+ */
+let _cachedStoreProjectDirs = null;
+let _cachedStorePhrenPath = null;
+/**
+ * Gather project directories from the primary store AND all non-primary stores.
+ * This enables the FTS5 index to include team store projects alongside personal ones.
+ * Uses a sync cache populated by the async buildIndex path.
+ */
+function getAllStoreProjectDirs(phrenPath, profile) {
+    const dirs = [...getProjectDirs(phrenPath, profile)];
+    if (_cachedStoreProjectDirs && _cachedStorePhrenPath === phrenPath) {
+        dirs.push(..._cachedStoreProjectDirs);
+    }
+    return dirs;
+}
+/**
+ * Refresh the store project dirs cache. Called from async contexts (buildIndex, etc.)
+ * before sync code paths that need getAllStoreProjectDirs.
+ */
+async function refreshStoreProjectDirs(phrenPath, profile) {
+    try {
+        const { getNonPrimaryStores } = await import("../store-registry.js");
+        const otherStores = getNonPrimaryStores(phrenPath);
+        const dirs = [];
+        for (const store of otherStores) {
+            if (!fs.existsSync(store.path))
+                continue;
+            dirs.push(...getProjectDirs(store.path, profile));
+        }
+        _cachedStoreProjectDirs = dirs;
+        _cachedStorePhrenPath = phrenPath;
+    }
+    catch {
+        _cachedStoreProjectDirs = [];
+        _cachedStorePhrenPath = phrenPath;
+    }
+}
 import { getIndexPolicy, withFileLock } from "./governance.js";
 import { stripTaskDoneSection } from "./content.js";
 import { isInactiveFindingLine } from "../finding/lifecycle.js";
@@ -191,7 +231,7 @@ function touchSentinel(phrenPath) {
 function computePhrenHash(phrenPath, profile, preGlobbed) {
     const policy = getIndexPolicy(phrenPath);
     const hash = crypto.createHash("sha1");
-    const topicConfigEntries = getProjectDirs(phrenPath, profile)
+    const topicConfigEntries = getAllStoreProjectDirs(phrenPath, profile)
         .map((dir) => path.join(dir, "topic-config.json"))
         .filter((configPath) => fs.existsSync(configPath));
     if (preGlobbed) {
@@ -215,9 +255,9 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
         }
     }
     else {
-        const projectDirs = getProjectDirs(phrenPath, profile);
+        const allProjectDirs = getAllStoreProjectDirs(phrenPath, profile);
         const files = [];
-        for (const dir of projectDirs) {
+        for (const dir of allProjectDirs) {
             const projectName = path.basename(dir);
             const config = readProjectConfig(phrenPath, projectName);
             const ownership = getProjectOwnershipMode(phrenPath, projectName, config);
@@ -399,7 +439,7 @@ function getRepoManagedInstructionEntries(phrenPath, project) {
     return entries;
 }
 function globAllFiles(phrenPath, profile) {
-    const projectDirs = getProjectDirs(phrenPath, profile);
+    const projectDirs = getAllStoreProjectDirs(phrenPath, profile);
     const indexPolicy = getIndexPolicy(phrenPath);
     const entries = [];
     const allAbsolutePaths = [];
@@ -826,7 +866,8 @@ function mergeManualLinks(db, phrenPath) {
 }
 async function buildIndexImpl(phrenPath, profile) {
     const t0 = Date.now();
-    const projectDirs = getProjectDirs(phrenPath, profile);
+    await refreshStoreProjectDirs(phrenPath, profile);
+    const projectDirs = getAllStoreProjectDirs(phrenPath, profile);
     beginUserFragmentBuildCache(phrenPath, projectDirs.map(dir => path.basename(dir)));
     try {
         // ── Cache dir + hash sentinel ─────────────────────────────────────────────
@@ -1348,12 +1389,16 @@ export function detectProject(phrenPath, cwd, profile) {
     if (manifest?.installMode === "project-local") {
         return manifest.primaryProject || null;
     }
-    const projectDirs = getProjectDirs(phrenPath, profile);
+    const projectDirs = getAllStoreProjectDirs(phrenPath, profile);
     const resolvedCwd = path.resolve(cwd);
     let bestMatch = null;
     for (const dir of projectDirs) {
         const projectName = path.basename(dir);
-        const sourcePath = getProjectSourcePath(phrenPath, projectName);
+        // Try the project's own store path first (handles team store projects),
+        // then fall back to primary phrenPath
+        const storePhrenPath = path.dirname(dir);
+        const sourcePath = getProjectSourcePath(storePhrenPath, projectName)
+            || getProjectSourcePath(phrenPath, projectName);
         if (!sourcePath)
             continue;
         const matches = resolvedCwd === sourcePath || resolvedCwd.startsWith(sourcePath + path.sep);

package/mcp/dist/shared/retrieval.js

@@ -627,9 +627,15 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
             }
             return false;
         });
-        const canonicalRows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ? AND type = 'canonical' LIMIT 1", [detectedProject]);
-        if (canonicalRows)
-            ranked = [...canonicalRows, ...ranked];
+        // Always-inject: truths for detected project are prepended regardless of search
+        // relevance. Dedup against rows already in the result set.
+        const canonicalRows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ? AND type = 'canonical'", [detectedProject]);
+        if (canonicalRows) {
+            const existingPaths = new Set(ranked.map((r) => r.path));
+            const newCanonicals = canonicalRows.filter((r) => !existingPaths.has(r.path));
+            if (newCanonicals.length > 0)
+                ranked = [...newCanonicals, ...ranked];
+        }
     }
     const entityBoost = query ? getFragmentBoostDocs(db, query) : new Set();
     const entityBoostPaths = new Set();

package/mcp/dist/store-registry.js

@@ -165,6 +165,19 @@ export function removeStoreFromRegistry(phrenPath, name) {
         return entry;
     });
 }
+/** Update the projects[] claim list for a store. Uses file locking. */
+export function updateStoreProjects(phrenPath, storeName, projects) {
+    withFileLock(storesFilePath(phrenPath), () => {
+        const registry = readStoreRegistry(phrenPath);
+        if (!registry)
+            throw new Error(`${PhrenError.FILE_NOT_FOUND}: No stores.yaml found`);
+        const store = registry.stores.find((s) => s.name === storeName);
+        if (!store)
+            throw new Error(`${PhrenError.NOT_FOUND}: Store "${storeName}" not found`);
+        store.projects = projects.length > 0 ? projects : undefined;
+        writeStoreRegistry(phrenPath, registry);
+    });
+}
 // ── Validation ───────────────────────────────────────────────────────────────
 function validateRegistry(registry) {
     if (registry.version !== 1)
@@ -247,8 +260,9 @@ function parseFederationPathsEnv(localPhrenPath) {
     const raw = process.env.PHREN_FEDERATION_PATHS ?? "";
     if (!raw.trim())
         return [];
+    // Use path.delimiter (';' on Windows, ':' on Unix) so Windows drive letters aren't split
     return raw
-        .split(":")
+        .split(path.delimiter)
         .map((p) => p.trim())
         .filter((p) => p.length > 0)
         .map((p) => path.resolve(expandHomePath(p)))

package/mcp/dist/tools/finding.js

@@ -263,22 +263,52 @@ async function handleAddFinding(ctx, params) {
         }
     });
 }
-async function handleSupersedeFinding(ctx, { project, finding_text, superseded_by }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleSupersedeFinding(ctx, { project: projectInput, finding_text, superseded_by }) {
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, projectInput);
+        phrenPath = resolved.phrenPath;
+        project = resolved.project;
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    const { withWriteQueue, updateFileInIndex } = ctx;
     return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => supersedeFinding(phrenPath, project, finding_text, superseded_by), (data) => ({
         message: `Marked finding as superseded in ${project}.`,
         data: { project, finding: data.finding, status: data.status, superseded_by: data.superseded_by },
     }));
 }
-async function handleRetractFinding(ctx, { project, finding_text, reason }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleRetractFinding(ctx, { project: projectInput, finding_text, reason }) {
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, projectInput);
+        phrenPath = resolved.phrenPath;
+        project = resolved.project;
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    const { withWriteQueue, updateFileInIndex } = ctx;
     return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => retractFindingLifecycle(phrenPath, project, finding_text, reason), (data) => ({
         message: `Retracted finding in ${project}.`,
         data: { project, finding: data.finding, status: data.status, reason: data.reason },
     }));
 }
-async function handleResolveContradiction(ctx, { project, finding_text, finding_text_other, finding_a, finding_b, resolution }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleResolveContradiction(ctx, { project: projectInput, finding_text, finding_text_other, finding_a, finding_b, resolution }) {
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, projectInput);
+        phrenPath = resolved.phrenPath;
+        project = resolved.project;
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    const { withWriteQueue, updateFileInIndex } = ctx;
     const findingText = (finding_text ?? finding_a)?.trim();
     const findingTextOther = (finding_text_other ?? finding_b)?.trim();
     if (!findingText || !findingTextOther) {
@@ -342,8 +372,18 @@ async function handleGetContradictions(ctx, { project, finding_text }) {
         },
     });
 }
-async function handleEditFinding(ctx, { project, old_text, new_text }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleEditFinding(ctx, { project: projectInput, old_text, new_text }) {
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, projectInput);
+        phrenPath = resolved.phrenPath;
+        project = resolved.project;
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    const { withWriteQueue, updateFileInIndex } = ctx;
     if (!isValidProjectName(project))
         return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
     const editDenied = permissionDeniedError(phrenPath, "edit_finding", project);
@@ -363,8 +403,18 @@ async function handleEditFinding(ctx, { project, old_text, new_text }) {
         });
     });
 }
-async function handleRemoveFinding(ctx, { project, finding }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleRemoveFinding(ctx, { project: projectInput, finding }) {
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, projectInput);
+        phrenPath = resolved.phrenPath;
+        project = resolved.project;
+    }
+    catch (err) {
+        return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    const { withWriteQueue, updateFileInIndex } = ctx;
     if (!isValidProjectName(project))
         return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
     const removeDenied = permissionDeniedError(phrenPath, "remove_finding", project);
@@ -494,6 +544,58 @@ async function handlePushChanges(ctx, { message }) {
         catch (err) {
             return mcpResponse({ ok: false, error: `Save failed: ${errorMessage(err)}`, errorCode: "INTERNAL_ERROR" });
         }
+        // Sync team stores: commit and push journal/tasks/truths changes
+        try {
+            const { getNonPrimaryStores } = await import("../store-registry.js");
+            const teamStores = getNonPrimaryStores(phrenPath).filter((s) => s.role === "team");
+            const teamResults = [];
+            for (const store of teamStores) {
+                if (!fs.existsSync(store.path) || !fs.existsSync(path.join(store.path, ".git")))
+                    continue;
+                const runStoreGit = (args, opts = {}) => execFileSync("git", args, {
+                    cwd: store.path,
+                    encoding: "utf8",
+                    timeout: opts.timeout ?? EXEC_TIMEOUT_MS,
+                    env: opts.env,
+                    stdio: ["ignore", "pipe", "pipe"],
+                }).trim();
+                try {
+                    const storeStatus = runStoreGit(["status", "--porcelain"]);
+                    if (!storeStatus) {
+                        teamResults.push({ store: store.name, pushed: false });
+                        continue;
+                    }
+                    // Only stage team-safe files: journal/, tasks.md, truths.md, FINDINGS.md, summary.md
+                    runStoreGit(["add", "--", "*/journal/*", "*/tasks.md", "*/truths.md", "*/FINDINGS.md", "*/summary.md"]);
+                    const actor = process.env.PHREN_ACTOR || process.env.USER || "unknown";
+                    runStoreGit(["commit", "-m", `phren: ${actor} team sync`]);
+                    try {
+                        runStoreGit(["push"], { timeout: 15000 });
+                        teamResults.push({ store: store.name, pushed: true });
+                    }
+                    catch {
+                        try {
+                            runStoreGit(["pull", "--rebase", "--quiet"], { timeout: 15000 });
+                            runStoreGit(["push"], { timeout: 15000 });
+                            teamResults.push({ store: store.name, pushed: true });
+                        }
+                        catch (retryErr) {
+                            teamResults.push({ store: store.name, pushed: false, error: errorMessage(retryErr) });
+                        }
+                    }
+                }
+                catch (storeErr) {
+                    teamResults.push({ store: store.name, pushed: false, error: errorMessage(storeErr) });
+                }
+            }
+            // Team store results are best-effort — don't fail the primary push for them
+            if (teamResults.length > 0) {
+                debugLog(`push_changes team stores: ${JSON.stringify(teamResults)}`);
+            }
+        }
+        catch {
+            // store-registry not available — skip silently
+        }
     });
 }
 // ── Registration ─────────────────────────────────────────────────────────────

package/mcp/dist/tools/memory.js

@@ -1,4 +1,4 @@
-import { mcpResponse } from "./types.js";
+import { mcpResponse, resolveStoreForProject } from "./types.js";
 import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
@@ -7,7 +7,7 @@ import { recordFeedback, flushEntryScores, } from "../shared/governance.js";
 import { upsertCanonical } from "../shared/content.js";
 import { isValidProjectName } from "../utils.js";
 export function register(server, ctx) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    const { withWriteQueue, updateFileInIndex } = ctx;
     server.registerTool("pin_memory", {
         title: "◆ phren · pin memory",
         description: "Write a truth — a high-confidence, always-inject entry in truths.md that never decays.",
@@ -15,19 +15,63 @@ export function register(server, ctx) {
             project: z.string().describe("Project name."),
             memory: z.string().describe("Truth text."),
         }),
-    }, async ({ project, memory }) => {
+    }, async ({ project: projectInput, memory }) => {
+        let phrenPath;
+        let project;
+        try {
+            const resolved = resolveStoreForProject(ctx, projectInput);
+            phrenPath = resolved.phrenPath;
+            project = resolved.project;
+        }
+        catch (err) {
+            return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
         if (!isValidProjectName(project))
             return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
         return withWriteQueue(async () => {
             const result = upsertCanonical(phrenPath, project, memory);
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
-            // Update FTS index so newly added truth is immediately searchable
             const canonicalPath = path.join(phrenPath, project, "truths.md");
             updateFileInIndex(canonicalPath);
             return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
         });
     });
+    server.registerTool("get_truths", {
+        title: "◆ phren · truths",
+        description: "Read all pinned truths for a project. Truths are high-confidence entries in truths.md that never decay.",
+        inputSchema: z.object({
+            project: z.string().describe("Project name."),
+        }),
+    }, async ({ project: projectInput }) => {
+        let phrenPath;
+        let project;
+        try {
+            const resolved = resolveStoreForProject(ctx, projectInput);
+            phrenPath = resolved.phrenPath;
+            project = resolved.project;
+        }
+        catch (err) {
+            return mcpResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        if (!isValidProjectName(project))
+            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+        const truthsPath = path.join(phrenPath, project, "truths.md");
+        if (!fs.existsSync(truthsPath)) {
+            return mcpResponse({ ok: true, message: `No truths pinned for "${project}" yet.`, data: { project, truths: [], count: 0 } });
+        }
+        const content = fs.readFileSync(truthsPath, "utf8");
+        const truths = content.split("\n")
+            .filter((line) => line.startsWith("- "))
+            .map((line) => line.slice(2).trim());
+        return mcpResponse({
+            ok: true,
+            message: truths.length > 0
+                ? `${truths.length} truth(s) pinned for "${project}".`
+                : `No truths pinned for "${project}" yet.`,
+            data: { project, truths, count: truths.length },
+        });
+    });
     server.registerTool("memory_feedback", {
         title: "◆ phren · feedback",
         description: "Record feedback on whether an injected memory was helpful or noisy/regressive.",
@@ -36,6 +80,7 @@ export function register(server, ctx) {
             feedback: z.enum(["helpful", "reprompt", "regression"]).describe("Feedback type."),
         }),
     }, async ({ key, feedback }) => {
+        const phrenPath = ctx.phrenPath;
         return withWriteQueue(async () => {
             recordFeedback(phrenPath, key, feedback);
             flushEntryScores(phrenPath);

package/mcp/dist/tools/search.js

@@ -470,7 +470,7 @@ async function handleGetProjectSummary(ctx, { name }) {
         if (store && fs.existsSync(path.join(store.path, lookupName))) {
             const projDir = path.join(store.path, lookupName);
             const fsDocs = [];
-            for (const [file, type] of [["summary.md", "summary"], ["CLAUDE.md", "claude"], ["FINDINGS.md", "findings"], ["tasks.md", "task"]]) {
+            for (const [file, type] of [["summary.md", "summary"], ["CLAUDE.md", "claude"], ["FINDINGS.md", "findings"], ["tasks.md", "task"], ["truths.md", "canonical"]]) {
                 const filePath = path.join(projDir, file);
                 if (fs.existsSync(filePath)) {
                     fsDocs.push({ filename: file, type, content: fs.readFileSync(filePath, "utf8").slice(0, 8000), path: filePath });
@@ -487,6 +487,7 @@ async function handleGetProjectSummary(ctx, { name }) {
     }
     const summaryDoc = docs.find(doc => doc.type === "summary");
     const claudeDoc = docs.find(doc => doc.type === "claude");
+    const canonicalDoc = docs.find(doc => doc.type === "canonical");
     const indexedFiles = docs.map(doc => ({ filename: doc.filename, type: doc.type, path: doc.path }));
     const parts = [`# ${name}`];
     if (summaryDoc) {
@@ -498,6 +499,13 @@ async function handleGetProjectSummary(ctx, { name }) {
     if (claudeDoc) {
         parts.push(`\n## CLAUDE.md path\n\`${claudeDoc.path}\``);
     }
+    // Show truths if they exist
+    if (canonicalDoc) {
+        const truthLines = canonicalDoc.content.split("\n").filter((l) => l.startsWith("- "));
+        if (truthLines.length > 0) {
+            parts.push(`\n## Truths (${truthLines.length})\n${truthLines.join("\n")}`);
+        }
+    }
     const fileList = indexedFiles.map((f) => `- ${f.filename} (${f.type})`).join("\n");
     parts.push(`\n## Indexed files\n${fileList}`);
     return mcpResponse({
@@ -507,6 +515,7 @@ async function handleGetProjectSummary(ctx, { name }) {
             name,
             summary: summaryDoc?.content ?? null,
             claudeMdPath: claudeDoc?.path ?? null,
+            truthsPath: canonicalDoc?.path ?? null,
             files: indexedFiles,
         },
     });

package/mcp/dist/tools/types.js

@@ -8,6 +8,16 @@ import { resolveAllStores } from "../store-registry.js";
 export function resolveStoreForProject(ctx, projectInput) {
     const { storeName, projectName } = parseStoreQualified(projectInput);
     if (!storeName) {
+        // Check if any non-readonly store claims this project via projects[] array.
+        // This enables automatic write routing: once a project is claimed by a team
+        // store (via `phren team add-project`), writes go there without needing the
+        // store-qualified prefix.
+        const stores = resolveAllStores(ctx.phrenPath);
+        for (const store of stores) {
+            if (store.role !== "readonly" && store.role !== "primary" && store.projects?.includes(projectName)) {
+                return { phrenPath: store.path, project: projectName, storeRole: store.role };
+            }
+        }
         return { phrenPath: ctx.phrenPath, project: projectName, storeRole: "primary" };
     }
     const stores = resolveAllStores(ctx.phrenPath);

package/package.json

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