@phren/cli 0.0.40 → 0.0.41

package/mcp/dist/cli/cli.js

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

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

@@ -603,6 +603,24 @@ export async function handleHookSessionStart() {
         },
     });
     appendAuditLog(phrenPath, "hook_session_start", `pull=${hasRemote ? (pull.ok ? "ok" : "fail") : "skipped-local"} doctor=${doctor.ok ? "ok" : "issues"} maintenance=${maintenanceScheduled ? "scheduled" : "skipped"}`);
+    // Pull non-primary stores from store registry (best-effort, non-blocking)
+    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 or no stores — skip silently
+    }
     // Sync intent warning: if the user intended sync but remote is missing or pull failed, warn once
     try {
         const syncPrefs = readInstallPreferences(phrenPath);

package/mcp/dist/cli/namespaces.js

@@ -16,6 +16,7 @@ import { addFinding, removeFinding } from "../core/finding.js";
 import { supersedeFinding, retractFinding, resolveFindingContradiction } from "../finding/lifecycle.js";
 import { readCustomHooks, getHookTarget, HOOK_EVENT_VALUES, validateCustomHookCommand } from "../hooks.js";
 import { runtimeFile } from "../shared.js";
+import { resolveAllStores, addStoreToRegistry, removeStoreFromRegistry, generateStoreId, readTeamBootstrap, } from "../store-registry.js";
 const HOOK_TOOLS = ["claude", "copilot", "cursor", "codex"];
 function printSkillsUsage() {
     console.log("Usage:");
@@ -1501,3 +1502,198 @@ export async function handleFindingNamespace(args) {
     printFindingUsage();
     process.exit(1);
 }
+// ── Store namespace ──────────────────────────────────────────────────────────
+function printStoreUsage() {
+    console.log("Usage:");
+    console.log("  phren store list                        List registered stores");
+    console.log("  phren store add <name> --remote <url>   Add a team store");
+    console.log("  phren store remove <name>               Remove a store (local only)");
+    console.log("  phren store sync                        Pull all stores");
+}
+export async function handleStoreNamespace(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        printStoreUsage();
+        return;
+    }
+    const phrenPath = getPhrenPath();
+    if (subcommand === "list") {
+        const stores = resolveAllStores(phrenPath);
+        if (stores.length === 0) {
+            console.log("No stores registered.");
+            return;
+        }
+        console.log(`${stores.length} store(s):\n`);
+        for (const store of stores) {
+            const exists = fs.existsSync(store.path) ? "ok" : "MISSING";
+            const syncInfo = store.remote ?? "(local)";
+            const projectCount = countStoreProjects(store);
+            console.log(`  ${store.name} (${store.role})`);
+            console.log(`    id:       ${store.id}`);
+            console.log(`    path:     ${store.path} [${exists}]`);
+            console.log(`    remote:   ${syncInfo}`);
+            console.log(`    sync:     ${store.sync}`);
+            console.log(`    projects: ${projectCount}`);
+            // Show last sync status if available
+            const health = readHealthForStore(store.path);
+            if (health) {
+                console.log(`    last sync: ${health}`);
+            }
+            console.log();
+        }
+        return;
+    }
+    if (subcommand === "add") {
+        const name = args[1];
+        if (!name) {
+            console.error("Usage: phren store add <name> --remote <url> [--role team|readonly]");
+            process.exit(1);
+        }
+        // Validate store name to prevent path traversal
+        if (!isValidProjectName(name)) {
+            console.error(`Invalid store name: "${name}". Use lowercase letters, numbers, and hyphens.`);
+            process.exit(1);
+        }
+        const remote = getOptionValue(args.slice(2), "--remote");
+        if (!remote) {
+            console.error("--remote <url> is required. Provide the git clone URL for the team store.");
+            process.exit(1);
+        }
+        // Prevent git option injection via --remote
+        if (remote.startsWith("-")) {
+            console.error(`Invalid remote URL: "${remote}". URLs must not start with "-".`);
+            process.exit(1);
+        }
+        const roleArg = getOptionValue(args.slice(2), "--role") ?? "team";
+        if (roleArg !== "team" && roleArg !== "readonly") {
+            console.error(`Invalid role: "${roleArg}". Use "team" or "readonly".`);
+            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);
+        }
+        // Clone the remote
+        console.log(`Cloning ${remote} into ${storePath}...`);
+        try {
+            fs.mkdirSync(storesDir, { recursive: true });
+            execFileSync("git", ["clone", "--", remote, storePath], {
+                stdio: "inherit",
+                timeout: 60_000,
+            });
+        }
+        catch (err) {
+            console.error(`Clone failed: ${errorMessage(err)}`);
+            process.exit(1);
+        }
+        // Read .phren-team.yaml if present
+        const bootstrap = readTeamBootstrap(storePath);
+        const storeName = bootstrap?.name ?? name;
+        const storeRole = bootstrap?.default_role ?? roleArg;
+        const entry = {
+            id: generateStoreId(),
+            name: storeName,
+            path: storePath,
+            role: storeRole === "primary" ? "team" : storeRole, // Never allow adding a second primary
+            sync: storeRole === "readonly" ? "pull-only" : "managed-git",
+            remote,
+        };
+        try {
+            addStoreToRegistry(phrenPath, entry);
+        }
+        catch (err) {
+            console.error(`Failed to register store: ${errorMessage(err)}`);
+            process.exit(1);
+        }
+        console.log(`\nStore "${storeName}" added (${entry.role}).`);
+        console.log(`  id:   ${entry.id}`);
+        console.log(`  path: ${storePath}`);
+        return;
+    }
+    if (subcommand === "remove") {
+        const name = args[1];
+        if (!name) {
+            console.error("Usage: phren store remove <name>");
+            process.exit(1);
+        }
+        try {
+            const removed = removeStoreFromRegistry(phrenPath, name);
+            console.log(`Store "${name}" removed from registry.`);
+            console.log(`  Local directory preserved at: ${removed.path}`);
+            console.log(`  To delete: rm -rf "${removed.path}"`);
+        }
+        catch (err) {
+            console.error(`${errorMessage(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subcommand === "sync") {
+        const stores = resolveAllStores(phrenPath);
+        let hasErrors = false;
+        for (const store of stores) {
+            if (!fs.existsSync(store.path)) {
+                console.log(`  ${store.name}: SKIP (path missing)`);
+                continue;
+            }
+            const gitDir = path.join(store.path, ".git");
+            if (!fs.existsSync(gitDir)) {
+                console.log(`  ${store.name}: SKIP (not a git repo)`);
+                continue;
+            }
+            try {
+                execFileSync("git", ["pull", "--rebase", "--quiet"], {
+                    cwd: store.path,
+                    stdio: "pipe",
+                    timeout: 30_000,
+                });
+                console.log(`  ${store.name}: ok`);
+            }
+            catch (err) {
+                console.log(`  ${store.name}: FAILED (${errorMessage(err).split("\n")[0]})`);
+                hasErrors = true;
+            }
+        }
+        if (hasErrors) {
+            console.error("\nSome stores failed to sync. Run 'phren doctor' for details.");
+        }
+        return;
+    }
+    console.error(`Unknown store subcommand: ${subcommand}`);
+    printStoreUsage();
+    process.exit(1);
+}
+function countStoreProjects(store) {
+    if (!fs.existsSync(store.path))
+        return 0;
+    try {
+        return getProjectDirs(store.path).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function readHealthForStore(storePath) {
+    try {
+        const healthPath = path.join(storePath, ".runtime", "health.json");
+        if (!fs.existsSync(healthPath))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(healthPath, "utf8"));
+        const lastSync = raw?.lastSync;
+        if (!lastSync)
+            return null;
+        const parts = [];
+        if (lastSync.lastPullStatus)
+            parts.push(`pull=${lastSync.lastPullStatus}`);
+        if (lastSync.lastPushStatus)
+            parts.push(`push=${lastSync.lastPushStatus}`);
+        if (lastSync.lastSuccessfulPullAt)
+            parts.push(`at=${lastSync.lastSuccessfulPullAt.slice(0, 16)}`);
+        return parts.join(", ") || null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -485,6 +485,24 @@ 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)
+    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(`hook-stop store-pull ${store.name}: ${errorMessage(err)}`);
+            }
+        }
+    }
+    catch {
+        // store-registry not available or no stores — skip silently
+    }
     // Auto governance scheduling (non-blocking)
     scheduleWeeklyGovernance();
 }

package/mcp/dist/entrypoint.js

@@ -81,6 +81,12 @@ const HELP_TOPICS = {
   phren verify                            Check init completed OK
   phren uninstall                         Remove phren config and hooks
   phren update [--refresh-starter]        Update to latest version
+`,
+    stores: `Stores:
+  phren store list                        List registered stores
+  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
 `,
     env: `Environment variables:
   PHREN_PATH                  Override phren directory (default: ~/.phren)
@@ -168,6 +174,7 @@ const CLI_COMMANDS = [
     "review",
     "consolidation-status",
     "session-context",
+    "store",
 ];
 async function flushTopLevelOutput() {
     await Promise.all([

package/mcp/dist/shared/retrieval.js

@@ -491,39 +491,44 @@ export async function searchKnowledgeRows(db, options) {
     return { safeQuery, rows, usedFallback };
 }
 /**
- * Parse PHREN_FEDERATION_PATHS env var and return valid, distinct paths.
- * Paths are colon-separated. The local phrenPath is excluded to avoid duplicate results.
- */
-function parseFederationPaths(localPhrenPath) {
-    const raw = process.env.PHREN_FEDERATION_PATHS ?? "";
-    if (!raw.trim())
-        return [];
-    return raw
-        .split(":")
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0 && p !== localPhrenPath && fs.existsSync(p));
-}
-/**
- * Search additional phren stores defined in PHREN_FEDERATION_PATHS.
+ * Search additional phren stores defined in the store registry (or PHREN_FEDERATION_PATHS).
  * Returns an array of results tagged with their source store. Read-only — no mutations.
  */
 export async function searchFederatedStores(localPhrenPath, options) {
-    const federationPaths = parseFederationPaths(localPhrenPath);
-    if (federationPaths.length === 0)
+    let nonPrimaryStores;
+    try {
+        const { getNonPrimaryStores } = await import("../store-registry.js");
+        nonPrimaryStores = getNonPrimaryStores(localPhrenPath).map((s) => ({
+            path: s.path, name: s.name, id: s.id,
+        }));
+    }
+    catch {
+        // Fallback: parse PHREN_FEDERATION_PATHS directly (pre-registry compat)
+        const raw = process.env.PHREN_FEDERATION_PATHS ?? "";
+        nonPrimaryStores = raw.split(":").map((p) => p.trim())
+            .filter((p) => p.length > 0 && p !== localPhrenPath && fs.existsSync(p))
+            .map((p) => ({ path: p, name: path.basename(p), id: "" }));
+    }
+    if (nonPrimaryStores.length === 0)
         return [];
     const allRows = [];
-    for (const storePath of federationPaths) {
+    for (const store of nonPrimaryStores) {
         try {
-            const federatedDb = await buildIndex(storePath);
-            const result = await searchKnowledgeRows(federatedDb, { ...options, phrenPath: storePath });
+            const federatedDb = await buildIndex(store.path);
+            const result = await searchKnowledgeRows(federatedDb, { ...options, phrenPath: store.path });
             if (result.rows && result.rows.length > 0) {
                 for (const row of result.rows) {
-                    allRows.push({ ...row, federationSource: storePath });
+                    allRows.push({
+                        ...row,
+                        federationSource: store.path,
+                        storeName: store.name,
+                        storeId: store.id || undefined,
+                    });
                 }
             }
         }
         catch (err) {
-            logger.debug(`federatedSearch storePath=${storePath}`, errorMessage(err));
+            logger.debug(`federatedSearch store=${store.name}`, errorMessage(err));
             // Federation errors are non-fatal — continue with other stores
         }
     }

package/mcp/dist/store-registry.js

@@ -0,0 +1,269 @@
+import * as fs from "fs";
+import * as crypto from "crypto";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { expandHomePath, atomicWriteText } from "./phren-paths.js";
+import { withFileLock } from "./governance/locks.js";
+import { isRecord, PhrenError } from "./phren-core.js";
+// ── Constants ────────────────────────────────────────────────────────────────
+const STORES_FILENAME = "stores.yaml";
+const TEAM_BOOTSTRAP_FILENAME = ".phren-team.yaml";
+const VALID_ROLES = new Set(["primary", "team", "readonly"]);
+const VALID_SYNC_MODES = new Set(["managed-git", "pull-only"]);
+// ── Path helpers ─────────────────────────────────────────────────────────────
+export function storesFilePath(phrenPath) {
+    return path.join(phrenPath, STORES_FILENAME);
+}
+// ── ID generation ────────────────────────────────────────────────────────────
+export function generateStoreId() {
+    return crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+}
+/**
+ * Deterministic ID from a filesystem path — used for PHREN_FEDERATION_PATHS
+ * backward-compat entries so the same path always produces the same ID.
+ */
+function deterministicIdFromPath(storePath) {
+    return crypto.createHash("sha256").update(storePath).digest("hex").slice(0, 8);
+}
+// ── Read / Write ─────────────────────────────────────────────────────────────
+export function readStoreRegistry(phrenPath) {
+    const filePath = storesFilePath(phrenPath);
+    if (!fs.existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return null;
+    }
+    const registry = normalizeRegistry(parsed);
+    if (!registry)
+        return null;
+    // Validate on read too — reject malformed registries before they reach hooks/sync
+    const err = validateRegistry(registry);
+    if (err)
+        return null;
+    return registry;
+}
+export function writeStoreRegistry(phrenPath, registry) {
+    const err = validateRegistry(registry);
+    if (err)
+        throw new Error(`${PhrenError.VALIDATION_ERROR}: ${err}`);
+    // Collapse paths to ~ prefix for portability
+    const portable = {
+        version: 1,
+        stores: registry.stores.map((s) => ({
+            ...s,
+            path: collapsePath(s.path),
+        })),
+    };
+    atomicWriteText(storesFilePath(phrenPath), yaml.dump(portable, { lineWidth: 200 }));
+}
+// ── Resolution ───────────────────────────────────────────────────────────────
+/**
+ * Resolve the full list of stores. This is the **key backward-compat function**:
+ * - If stores.yaml exists → parse and return entries
+ * - If stores.yaml is missing → return a single implicit primary entry for phrenPath
+ * - In both cases, append PHREN_FEDERATION_PATHS entries as readonly stores
+ */
+export function resolveAllStores(phrenPath) {
+    const registry = readStoreRegistry(phrenPath);
+    const stores = registry ? [...registry.stores] : [implicitPrimaryStore(phrenPath)];
+    // Append PHREN_FEDERATION_PATHS entries that aren't already in the registry
+    const knownPaths = new Set(stores.map((s) => s.path));
+    for (const fedPath of parseFederationPathsEnv(phrenPath)) {
+        if (!knownPaths.has(fedPath)) {
+            stores.push({
+                id: deterministicIdFromPath(fedPath),
+                name: path.basename(fedPath),
+                path: fedPath,
+                role: "readonly",
+                sync: "pull-only",
+            });
+            knownPaths.add(fedPath);
+        }
+    }
+    return stores;
+}
+/** The primary store (role=primary). Falls back to implicit entry. */
+export function getPrimaryStore(phrenPath) {
+    const stores = resolveAllStores(phrenPath);
+    return stores.find((s) => s.role === "primary") ?? implicitPrimaryStore(phrenPath);
+}
+/** All stores that can be read (all roles). */
+export function getReadableStores(phrenPath) {
+    return resolveAllStores(phrenPath);
+}
+/** Non-primary stores (for federation search, multi-store sync). */
+export function getNonPrimaryStores(phrenPath) {
+    return resolveAllStores(phrenPath).filter((s) => s.role !== "primary");
+}
+/** Find a store by name. */
+export function findStoreByName(phrenPath, name) {
+    return resolveAllStores(phrenPath).find((s) => s.name === name);
+}
+// ── Team bootstrap ───────────────────────────────────────────────────────────
+export function readTeamBootstrap(storePath) {
+    const filePath = path.join(storePath, TEAM_BOOTSTRAP_FILENAME);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
+        if (!isRecord(parsed) || typeof parsed.name !== "string")
+            return null;
+        return {
+            name: parsed.name,
+            description: typeof parsed.description === "string" ? parsed.description : undefined,
+            default_role: typeof parsed.default_role === "string" && isStoreRole(parsed.default_role)
+                ? parsed.default_role
+                : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Registry mutation helpers ────────────────────────────────────────────────
+/** Add a store entry to the registry. Creates stores.yaml if needed. Uses file locking. */
+export function addStoreToRegistry(phrenPath, entry) {
+    withFileLock(storesFilePath(phrenPath), () => {
+        let registry = readStoreRegistry(phrenPath);
+        if (!registry) {
+            // First time — also add the implicit primary store
+            registry = { version: 1, stores: [implicitPrimaryStore(phrenPath)] };
+        }
+        const existing = registry.stores.find((s) => s.name === entry.name);
+        if (existing)
+            throw new Error(`${PhrenError.VALIDATION_ERROR}: Store "${entry.name}" already exists`);
+        registry.stores.push(entry);
+        writeStoreRegistry(phrenPath, registry);
+    });
+}
+/** Remove a store entry by name. Refuses to remove primary. Uses file locking. */
+export function removeStoreFromRegistry(phrenPath, name) {
+    return withFileLock(storesFilePath(phrenPath), () => {
+        const registry = readStoreRegistry(phrenPath);
+        if (!registry)
+            throw new Error(`${PhrenError.FILE_NOT_FOUND}: No stores.yaml found`);
+        const idx = registry.stores.findIndex((s) => s.name === name);
+        if (idx === -1)
+            throw new Error(`${PhrenError.NOT_FOUND}: Store "${name}" not found`);
+        const entry = registry.stores[idx];
+        if (entry.role === "primary")
+            throw new Error(`${PhrenError.VALIDATION_ERROR}: Cannot remove the primary store`);
+        registry.stores.splice(idx, 1);
+        writeStoreRegistry(phrenPath, registry);
+        return entry;
+    });
+}
+// ── Validation ───────────────────────────────────────────────────────────────
+function validateRegistry(registry) {
+    if (registry.version !== 1)
+        return `Unsupported registry version: ${registry.version}`;
+    if (!Array.isArray(registry.stores) || registry.stores.length === 0)
+        return "Registry must have at least one store";
+    const names = new Set();
+    const ids = new Set();
+    for (const store of registry.stores) {
+        if (!store.id || typeof store.id !== "string")
+            return `Store missing id`;
+        if (!store.name || typeof store.name !== "string")
+            return `Store missing name`;
+        if (!store.path || typeof store.path !== "string")
+            return `Store "${store.name}" missing path`;
+        if (!isStoreRole(store.role))
+            return `Store "${store.name}" has invalid role: ${store.role}`;
+        if (!isStoreSyncMode(store.sync))
+            return `Store "${store.name}" has invalid sync mode: ${store.sync}`;
+        if (names.has(store.name))
+            return `Duplicate store name: "${store.name}"`;
+        if (ids.has(store.id))
+            return `Duplicate store id: "${store.id}"`;
+        names.add(store.name);
+        ids.add(store.id);
+    }
+    const primaryCount = registry.stores.filter((s) => s.role === "primary").length;
+    if (primaryCount !== 1)
+        return `Registry must have exactly one primary store (found ${primaryCount})`;
+    return null;
+}
+// ── Normalization ────────────────────────────────────────────────────────────
+function normalizeRegistry(parsed) {
+    if (!isRecord(parsed))
+        return null;
+    if (parsed.version !== 1)
+        return null;
+    if (!Array.isArray(parsed.stores))
+        return null;
+    const stores = [];
+    for (const raw of parsed.stores) {
+        if (!isRecord(raw))
+            return null;
+        const id = typeof raw.id === "string" ? raw.id : "";
+        const name = typeof raw.name === "string" ? raw.name : "";
+        const rawPath = typeof raw.path === "string" ? raw.path : "";
+        const role = typeof raw.role === "string" && isStoreRole(raw.role) ? raw.role : null;
+        const sync = typeof raw.sync === "string" && isStoreSyncMode(raw.sync) ? raw.sync : "managed-git";
+        const remote = typeof raw.remote === "string" ? raw.remote : undefined;
+        const projects = Array.isArray(raw.projects)
+            ? raw.projects.filter((p) => typeof p === "string")
+            : undefined;
+        if (!id || !name || !rawPath || !role)
+            return null;
+        stores.push({
+            id,
+            name,
+            path: path.resolve(expandHomePath(rawPath)),
+            role,
+            sync,
+            remote,
+            projects: projects && projects.length > 0 ? projects : undefined,
+        });
+    }
+    if (stores.length === 0)
+        return null;
+    return { version: 1, stores };
+}
+// ── Internal helpers ─────────────────────────────────────────────────────────
+function implicitPrimaryStore(phrenPath) {
+    return {
+        id: deterministicIdFromPath(phrenPath),
+        name: "personal",
+        path: phrenPath,
+        role: "primary",
+        sync: "managed-git",
+    };
+}
+function parseFederationPathsEnv(localPhrenPath) {
+    const raw = process.env.PHREN_FEDERATION_PATHS ?? "";
+    if (!raw.trim())
+        return [];
+    return raw
+        .split(":")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .map((p) => path.resolve(expandHomePath(p)))
+        .filter((p) => p !== localPhrenPath && fs.existsSync(p));
+}
+function isStoreRole(value) {
+    return VALID_ROLES.has(value);
+}
+function isStoreSyncMode(value) {
+    return VALID_SYNC_MODES.has(value);
+}
+function collapsePath(absPath) {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    if (home && absPath.startsWith(home + path.sep)) {
+        return "~/" + absPath.slice(home.length + 1);
+    }
+    return absPath;
+}

package/mcp/dist/store-routing.js

@@ -0,0 +1,110 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getProjectDirs } from "./phren-paths.js";
+import { PhrenError } from "./phren-core.js";
+import { isValidProjectName } from "./utils.js";
+import { resolveAllStores } from "./store-registry.js";
+// ── Parsing ──────────────────────────────────────────────────────────────────
+/**
+ * Parse a project reference that may be store-qualified.
+ *
+ * "arc"          → { projectName: "arc" }
+ * "arc-team/arc" → { storeName: "arc-team", projectName: "arc" }
+ */
+export function parseStoreQualified(input) {
+    const trimmed = input.trim();
+    const slashIdx = trimmed.indexOf("/");
+    if (slashIdx === -1) {
+        return { projectName: trimmed };
+    }
+    const storeName = trimmed.slice(0, slashIdx);
+    const projectName = trimmed.slice(slashIdx + 1);
+    // Only treat as store-qualified if both parts are valid names
+    if (storeName && projectName && !projectName.includes("/")) {
+        return { storeName, projectName };
+    }
+    // Malformed — treat whole thing as project name (will fail validation later)
+    return { projectName: trimmed };
+}
+// ── Resolution ───────────────────────────────────────────────────────────────
+/**
+ * Resolve a project reference to a specific store + directory.
+ *
+ * Resolution rules:
+ * 1. If store-qualified ("store/project"), find that store and project within it
+ * 2. If bare ("project"), scan all readable stores for a matching project dir
+ * 3. Exactly one match → return it
+ * 4. Zero matches → throw NOT_FOUND
+ * 5. Multiple matches → throw VALIDATION_ERROR with disambiguation message
+ */
+export function resolveProject(phrenPath, input, profile) {
+    const { storeName, projectName } = parseStoreQualified(input);
+    if (!isValidProjectName(projectName)) {
+        throw new Error(`${PhrenError.VALIDATION_ERROR}: Invalid project name: "${projectName}"`);
+    }
+    if (storeName && !isValidStoreName(storeName)) {
+        throw new Error(`${PhrenError.VALIDATION_ERROR}: Invalid store name: "${storeName}"`);
+    }
+    const stores = resolveAllStores(phrenPath);
+    // Store-qualified: find exact store
+    if (storeName) {
+        const store = stores.find((s) => s.name === storeName);
+        if (!store) {
+            const available = stores.map((s) => s.name).join(", ");
+            throw new Error(`${PhrenError.NOT_FOUND}: Store "${storeName}" not found. Available: ${available}`);
+        }
+        const projectDir = findProjectInStore(store, projectName, profile);
+        if (!projectDir) {
+            throw new Error(`${PhrenError.NOT_FOUND}: Project "${projectName}" not found in store "${storeName}"`);
+        }
+        return { store, projectName, projectDir };
+    }
+    // Bare project: scan all stores
+    const matches = [];
+    for (const store of stores) {
+        const projectDir = findProjectInStore(store, projectName, profile);
+        if (projectDir) {
+            matches.push({ store, projectName, projectDir });
+        }
+    }
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0) {
+        throw new Error(`${PhrenError.NOT_FOUND}: Project "${projectName}" not found in any store`);
+    }
+    // Ambiguous — multiple stores have this project
+    const storeNames = matches.map((m) => `${m.store.name}/${projectName}`).join(", ");
+    throw new Error(`${PhrenError.VALIDATION_ERROR}: Project "${projectName}" exists in multiple stores. ` +
+        `Use store-qualified name to disambiguate: ${storeNames}`);
+}
+/**
+ * List all projects across all readable stores.
+ * Returns entries with store context for display.
+ */
+export function listAllProjects(phrenPath, profile) {
+    const stores = resolveAllStores(phrenPath);
+    const results = [];
+    for (const store of stores) {
+        const dirs = getProjectDirs(store.path, profile);
+        for (const dir of dirs) {
+            const projectName = path.basename(dir);
+            results.push({ store, projectName, projectDir: dir });
+        }
+    }
+    return results;
+}
+// ── Internal helpers ─────────────────────────────────────────────────────────
+const STORE_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+function isValidStoreName(name) {
+    return STORE_NAME_PATTERN.test(name);
+}
+function findProjectInStore(store, projectName, profile) {
+    if (!fs.existsSync(store.path))
+        return null;
+    const dirs = getProjectDirs(store.path, profile);
+    for (const dir of dirs) {
+        if (path.basename(dir) === projectName)
+            return dir;
+    }
+    return null;
+}

package/mcp/dist/tools/search.js

@@ -1,8 +1,10 @@
 import { mcpResponse } from "./types.js";
 import { z } from "zod";
 import * as fs from "fs";
+import * as path from "path";
 import { createHash } from "crypto";
 import { isValidProjectName, errorMessage } from "../utils.js";
+import { resolveAllStores } from "../store-registry.js";
 import { readFindings } from "../data/access.js";
 import { debugLog, runtimeFile, DOC_TYPES, FINDING_TAGS, isMemoryScopeVisible, normalizeMemoryScope, } from "../shared.js";
 import { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, } from "../shared/content.js";
@@ -610,6 +612,40 @@ async function handleGetFindings(ctx, { project, limit, include_superseded, incl
         data: { project, findings: capped, total: filteredItems.length, status: status ?? null, include_history: includeHistory, historyCount: hiddenHistoryCount },
     });
 }
+async function handleStoreList(ctx) {
+    const { phrenPath } = ctx;
+    const stores = resolveAllStores(phrenPath);
+    const storeData = stores.map((store) => {
+        let health = null;
+        try {
+            const healthPath = path.join(store.path, ".runtime", "health.json");
+            if (fs.existsSync(healthPath)) {
+                health = JSON.parse(fs.readFileSync(healthPath, "utf8"))?.lastSync ?? null;
+            }
+        }
+        catch { /* non-critical */ }
+        return {
+            id: store.id,
+            name: store.name,
+            path: store.path,
+            role: store.role,
+            sync: store.sync,
+            remote: store.remote ?? null,
+            exists: fs.existsSync(store.path),
+            projects: store.projects ?? null,
+            lastSync: health,
+        };
+    });
+    const lines = storeData.map((s) => {
+        const status = s.exists ? "ok" : "MISSING";
+        return `- ${s.name} (${s.role}) [${status}] ${s.remote ?? "(local)"}`;
+    });
+    return mcpResponse({
+        ok: true,
+        message: `${storeData.length} store(s):\n${lines.join("\n")}`,
+        data: { stores: storeData },
+    });
+}
 // ── Registration ─────────────────────────────────────────────────────────────
 export function register(server, ctx) {
     server.registerTool("get_memory_detail", {
@@ -668,4 +704,10 @@ export function register(server, ctx) {
             status: z.enum(FINDING_LIFECYCLE_STATUSES).optional().describe("Filter findings by lifecycle status."),
         }),
     }, (params) => handleGetFindings(ctx, params));
+    server.registerTool("store_list", {
+        title: "◆ phren · stores",
+        description: "List all registered phren stores and their sync status. " +
+            "Shows the primary store plus any team or readonly stores from the store registry.",
+        inputSchema: z.object({}),
+    }, () => handleStoreList(ctx));
 }

package/package.json

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