@phren/cli 0.0.40 → 0.0.42

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, handlePromoteNamespace, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
 import { handleTaskView, handleSessionsView, handleQuickstart, handleDebugInjection, handleInspectIndex, } from "./ops.js";
 import { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleReview, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
 import { handleGraphNamespace } from "./graph.js";
@@ -107,6 +107,10 @@ export async function runCliCommand(command, args) {
             return handleConsolidationStatus(args);
         case "session-context":
             return handleSessionContext();
+        case "store":
+            return handleStoreNamespace(args);
+        case "promote":
+            return handlePromoteNamespace(args);
         default:
             console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);
             process.exit(1);

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

@@ -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,306 @@ 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");
+    console.log("  phren store activity [--limit N]         Recent team findings");
+}
+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 === "activity") {
+        const stores = resolveAllStores(phrenPath);
+        const teamStores = stores.filter((s) => s.role === "team");
+        if (teamStores.length === 0) {
+            console.log("No team stores registered. Add one with: phren store add <name> --remote <url>");
+            return;
+        }
+        const { readTeamJournalEntries } = await import("../finding/journal.js");
+        const limit = Number(getOptionValue(args.slice(1), "--limit") ?? "20");
+        const allEntries = [];
+        for (const store of teamStores) {
+            if (!fs.existsSync(store.path))
+                continue;
+            const projectDirs = getProjectDirs(store.path);
+            for (const dir of projectDirs) {
+                const projectName = path.basename(dir);
+                const journalEntries = readTeamJournalEntries(store.path, projectName);
+                for (const je of journalEntries) {
+                    for (const entry of je.entries) {
+                        allEntries.push({ store: store.name, project: projectName, date: je.date, actor: je.actor, entry });
+                    }
+                }
+            }
+        }
+        allEntries.sort((a, b) => b.date.localeCompare(a.date));
+        const capped = allEntries.slice(0, limit);
+        if (capped.length === 0) {
+            console.log("No team activity yet.");
+            return;
+        }
+        console.log(`Team activity (${capped.length}/${allEntries.length}):\n`);
+        let lastDate = "";
+        for (const e of capped) {
+            if (e.date !== lastDate) {
+                console.log(`## ${e.date}`);
+                lastDate = e.date;
+            }
+            console.log(`  [${e.store}/${e.project}] ${e.actor}: ${e.entry}`);
+        }
+        return;
+    }
+    if (subcommand === "sync") {
+        const stores = resolveAllStores(phrenPath);
+        let hasErrors = false;
+        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);
+}
+// ── Promote namespace ────────────────────────────────────────────────────────
+export async function handlePromoteNamespace(args) {
+    if (!args[0] || args[0] === "--help" || args[0] === "-h") {
+        console.log("Usage:");
+        console.log('  phren promote <project> "finding text..." --to <store>');
+        console.log("  Copies a finding from the primary store to a team store.");
+        return;
+    }
+    const phrenPath = getPhrenPath();
+    const project = args[0];
+    if (!isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}"`);
+        process.exit(1);
+    }
+    const toStore = getOptionValue(args.slice(1), "--to");
+    if (!toStore) {
+        console.error("--to <store> is required. Specify the target team store.");
+        process.exit(1);
+    }
+    // Everything between project and --to is the finding text
+    const toIdx = args.indexOf("--to");
+    const findingText = args.slice(1, toIdx !== -1 ? toIdx : undefined).join(" ").trim();
+    if (!findingText) {
+        console.error("Finding text is required.");
+        process.exit(1);
+    }
+    const stores = resolveAllStores(phrenPath);
+    const targetStore = stores.find((s) => s.name === toStore);
+    if (!targetStore) {
+        const available = stores.map((s) => s.name).join(", ");
+        console.error(`Store "${toStore}" not found. Available: ${available}`);
+        process.exit(1);
+    }
+    if (targetStore.role === "readonly") {
+        console.error(`Store "${toStore}" is read-only.`);
+        process.exit(1);
+    }
+    if (targetStore.role === "primary") {
+        console.error(`Cannot promote to primary store — finding is already there.`);
+        process.exit(1);
+    }
+    // Find the matching finding in the primary store
+    const { readFindings } = await import("../data/access.js");
+    const findingsResult = readFindings(phrenPath, project);
+    if (!findingsResult.ok) {
+        console.error(`Could not read findings for project "${project}".`);
+        process.exit(1);
+    }
+    const match = findingsResult.data.find((item) => item.text.includes(findingText) || findingText.includes(item.text));
+    if (!match) {
+        console.error(`No finding matching "${findingText.slice(0, 80)}..." found in ${project}.`);
+        process.exit(1);
+    }
+    // Write to target store
+    const targetProjectDir = path.join(targetStore.path, project);
+    fs.mkdirSync(targetProjectDir, { recursive: true });
+    const targetFindingsPath = path.join(targetProjectDir, "FINDINGS.md");
+    const { addFindingToFile } = await import("../shared/content.js");
+    const result = addFindingToFile(targetStore.path, project, match.text);
+    if (!result.ok) {
+        console.error(`Failed to add finding to ${toStore}: ${result.error}`);
+        process.exit(1);
+    }
+    console.log(`Promoted to ${toStore}/${project}:`);
+    console.log(`  "${match.text.slice(0, 120)}${match.text.length > 120 ? "..." : ""}"`);
+}
+function countStoreProjects(store) {
+    if (!fs.existsSync(store.path))
+        return 0;
+    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,8 @@ const CLI_COMMANDS = [
     "review",
     "consolidation-status",
     "session-context",
+    "store",
+    "promote",
 ];
 async function flushTopLevelOutput() {
     await Promise.all([

package/mcp/dist/finding/journal.js

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

package/mcp/dist/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/finding.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";
@@ -84,13 +84,45 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
     });
 }
 // ── Handlers ─────────────────────────────────────────────────────────────────
-async function handleAddFinding(ctx, { project, finding, citation, sessionId, source, findingType, scope }) {
-    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+async function handleAddFinding(ctx, params) {
+    const { finding, citation, sessionId, source, findingType, scope } = params;
+    // Resolve store-qualified project names (e.g., "team/arc" → store path + "arc")
+    let phrenPath;
+    let project;
+    try {
+        const resolved = resolveStoreForProject(ctx, params.project);
+        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 addFindingDenied = permissionDeniedError(phrenPath, "add_finding", project);
     if (addFindingDenied)
         return mcpResponse({ ok: false, error: addFindingDenied });
+    // Team stores: use append-only journal (no FINDINGS.md mutation, no merge conflicts)
+    {
+        const storeResolved = resolveStoreForProject(ctx, params.project);
+        if (storeResolved.storeRole === "team") {
+            const { appendTeamJournal } = await import("../finding/journal.js");
+            const findings = Array.isArray(finding) ? finding : [finding];
+            const added = [];
+            for (const f of findings) {
+                const taggedFinding = findingType ? `[${findingType}] ${f}` : f;
+                const result = appendTeamJournal(phrenPath, project, taggedFinding);
+                if (result.ok)
+                    added.push(taggedFinding);
+            }
+            return mcpResponse({
+                ok: added.length > 0,
+                message: `Added ${added.length} finding(s) to ${params.project} journal`,
+                data: { project: params.project, added, journalMode: true },
+            });
+        }
+    }
     if (Array.isArray(finding)) {
         const findings = finding;
         if (findings.length > 100)

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";
@@ -456,8 +458,28 @@ async function handleSearchKnowledge(ctx, { query, limit, project, type, tag, si
     }
 }
 async function handleGetProjectSummary(ctx, { name }) {
+    // Support store-qualified names (e.g., "team/arc")
+    const { parseStoreQualified } = await import("../store-routing.js");
+    const { storeName, projectName } = parseStoreQualified(name);
+    const lookupName = projectName;
     const db = ctx.db();
-    const docs = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [name]);
+    let docs = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [lookupName]);
+    // If not in primary index and store-qualified, try reading from the store's filesystem
+    if (!docs && storeName) {
+        const store = resolveAllStores(ctx.phrenPath).find((s) => s.name === storeName);
+        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"]]) {
+                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 });
+                }
+            }
+            if (fsDocs.length > 0)
+                docs = fsDocs;
+        }
+    }
     if (!docs) {
         const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
         const names = projectRows ? projectRows.map(row => decodeStringRow(row, 1, "get_project_summary.projects")[0]) : [];
@@ -492,42 +514,83 @@ async function handleGetProjectSummary(ctx, { name }) {
 async function handleListProjects(ctx, { page, page_size }) {
     const { phrenPath, profile } = ctx;
     const db = ctx.db();
+    // Gather projects from primary store index
     const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
-    if (!projectRows)
+    const primaryProjects = projectRows
+        ? projectRows.map(row => decodeStringRow(row, 1, "list_projects.projects")[0])
+        : [];
+    // Gather projects from non-primary stores
+    const { getNonPrimaryStores } = await import("../store-registry.js");
+    const { getProjectDirs } = await import("../phren-paths.js");
+    const nonPrimaryStores = getNonPrimaryStores(phrenPath);
+    const storeProjects = [];
+    for (const store of nonPrimaryStores) {
+        if (!fs.existsSync(store.path))
+            continue;
+        const dirs = getProjectDirs(store.path);
+        for (const dir of dirs) {
+            const projName = path.basename(dir);
+            storeProjects.push({ name: projName, store: store.name });
+        }
+    }
+    // Combine: primary projects (no store prefix) + non-primary (with store prefix)
+    const allProjects = [
+        ...primaryProjects.map((p) => ({ name: p, store: undefined })),
+        ...storeProjects,
+    ];
+    if (allProjects.length === 0)
         return mcpResponse({ ok: true, message: "No projects indexed.", data: { projects: [], total: 0 } });
-    const projects = projectRows.map(row => decodeStringRow(row, 1, "list_projects.projects")[0]);
     const pageSize = page_size ?? 20;
     const pageNum = page ?? 1;
     const start = Math.max(0, (pageNum - 1) * pageSize);
     const end = start + pageSize;
-    const pageProjects = projects.slice(start, end);
-    const totalPages = Math.max(1, Math.ceil(projects.length / pageSize));
+    const pageProjects = allProjects.slice(start, end);
+    const totalPages = Math.max(1, Math.ceil(allProjects.length / pageSize));
     if (pageNum > totalPages) {
         return mcpResponse({ ok: false, error: `Page ${pageNum} out of range. Total pages: ${totalPages}.` });
     }
     const badgeTypes = ["claude", "findings", "summary", "task"];
     const badgeLabels = { claude: "CLAUDE.md", findings: "FINDINGS", summary: "summary", task: "task" };
-    const projectList = pageProjects.map((proj) => {
-        const rows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [proj]) ?? [];
-        const types = rows.map(row => row.type);
-        const summaryRow = rows.find(row => row.type === "summary");
-        const claudeRow = rows.find(row => row.type === "claude");
-        const source = summaryRow?.content ?? claudeRow?.content;
-        let brief = "";
-        if (source) {
-            const firstLine = source.split("\n").find(l => l.trim() && !l.startsWith("#"));
-            brief = firstLine?.trim() || "";
+    const projectList = pageProjects.map((entry) => {
+        // Primary store projects: query the DB for badge info
+        if (!entry.store) {
+            const rows = queryDocRows(db, "SELECT project, filename, type, content, path FROM docs WHERE project = ?", [entry.name]) ?? [];
+            const types = rows.map(row => row.type);
+            const summaryRow = rows.find(row => row.type === "summary");
+            const claudeRow = rows.find(row => row.type === "claude");
+            const source = summaryRow?.content ?? claudeRow?.content;
+            let brief = "";
+            if (source) {
+                const firstLine = source.split("\n").find(l => l.trim() && !l.startsWith("#"));
+                brief = firstLine?.trim() || "";
+            }
+            const badges = badgeTypes.filter(t => types.includes(t)).map(t => badgeLabels[t]);
+            return { name: entry.name, store: undefined, brief, badges, fileCount: rows.length };
         }
-        const badges = badgeTypes.filter(t => types.includes(t)).map(t => badgeLabels[t]);
-        return { name: proj, brief, badges, fileCount: rows.length };
+        // Non-primary store projects: basic info (no DB query, just check file existence)
+        const store = nonPrimaryStores.find((s) => s.name === entry.store);
+        const projDir = store ? path.join(store.path, entry.name) : "";
+        const badges = [];
+        if (projDir) {
+            if (fs.existsSync(path.join(projDir, "CLAUDE.md")))
+                badges.push("CLAUDE.md");
+            if (fs.existsSync(path.join(projDir, "FINDINGS.md")))
+                badges.push("FINDINGS");
+            if (fs.existsSync(path.join(projDir, "summary.md")))
+                badges.push("summary");
+            if (fs.existsSync(path.join(projDir, "tasks.md")))
+                badges.push("task");
+        }
+        return { name: entry.name, store: entry.store, brief: "", badges, fileCount: badges.length };
     });
-    const lines = [`# Phren Projects (${projects.length})`];
+    const lines = [`# Phren Projects (${allProjects.length})`];
     if (profile)
         lines.push(`Profile: ${profile}`);
     lines.push(`Page: ${pageNum}/${totalPages} (page_size=${pageSize})`);
     lines.push(`Path: ${phrenPath}\n`);
     for (const p of projectList) {
-        lines.push(`## ${p.name}`);
+        const storeTag = p.store ? ` (${p.store})` : "";
+        lines.push(`## ${p.name}${storeTag}`);
         if (p.brief)
             lines.push(p.brief);
         lines.push(`[${p.badges.join(" | ")}] - ${p.fileCount} file(s)\n`);
@@ -535,7 +598,7 @@ async function handleListProjects(ctx, { page, page_size }) {
     return mcpResponse({
         ok: true,
         message: lines.join("\n"),
-        data: { projects: projectList, total: projects.length, page: pageNum, totalPages, pageSize },
+        data: { projects: projectList, total: allProjects.length, page: pageNum, totalPages, pageSize },
     });
 }
 async function handleGetFindings(ctx, { project, limit, include_superseded, include_history, status }) {
@@ -610,6 +673,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 +765,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/mcp/dist/tools/tasks.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";
@@ -207,10 +207,21 @@ export function register(server, ctx) {
             ]).describe("The task(s) to add. Pass a string for one task, or an array for bulk."),
             scope: z.string().optional().describe("Optional memory scope label. Defaults to 'shared'. Example: 'researcher' or 'builder'."),
         }),
-    }, async ({ project, item, scope }) => {
+    }, async ({ project: projectInput, item, scope }) => {
+        // Resolve store-qualified project names (e.g., "team/arc")
+        let targetPhrenPath;
+        let project;
+        try {
+            const resolved = resolveStoreForProject(ctx, projectInput);
+            targetPhrenPath = 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 addTaskDenied = permissionDeniedError(phrenPath, "add_task", project);
+        const addTaskDenied = permissionDeniedError(targetPhrenPath, "add_task", project);
         if (addTaskDenied)
             return mcpResponse({ ok: false, error: addTaskDenied });
         const normalizedScope = normalizeMemoryScope(scope ?? "shared");
@@ -218,20 +229,20 @@ export function register(server, ctx) {
             return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
         if (Array.isArray(item)) {
             return withWriteQueue(async () => {
-                const result = addTasksBatch(phrenPath, project, item, { scope: normalizedScope });
+                const result = addTasksBatch(targetPhrenPath, project, item, { scope: normalizedScope });
                 if (!result.ok)
                     return mcpResponse({ ok: false, error: result.error });
                 const { added, errors } = result.data;
                 if (added.length > 0)
-                    refreshTaskIndex(updateFileInIndex, phrenPath, project);
+                    refreshTaskIndex(updateFileInIndex, targetPhrenPath, project);
                 return mcpResponse({ ok: added.length > 0, ...(added.length === 0 ? { error: `No tasks added: ${errors.join("; ")}` } : {}), message: `Added ${added.length} of ${item.length} tasks to ${project}`, data: { project, added, errors } });
             });
         }
         return withWriteQueue(async () => {
-            const result = addTaskStore(phrenPath, project, item, { scope: normalizedScope });
+            const result = addTaskStore(targetPhrenPath, project, item, { scope: normalizedScope });
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
-            refreshTaskIndex(updateFileInIndex, phrenPath, project);
+            refreshTaskIndex(updateFileInIndex, targetPhrenPath, project);
             return mcpResponse({ ok: true, message: `Task added: ${result.data.line}`, data: { project, item, scope: normalizedScope } });
         });
     });

package/mcp/dist/tools/types.js

@@ -1,3 +1,25 @@
+import { parseStoreQualified } from "../store-routing.js";
+import { resolveAllStores } from "../store-registry.js";
+/**
+ * Resolve the effective phrenPath and bare project name for a project input.
+ * Handles store-qualified names ("store/project") by routing to the correct store.
+ * Returns the primary store path for bare names.
+ */
+export function resolveStoreForProject(ctx, projectInput) {
+    const { storeName, projectName } = parseStoreQualified(projectInput);
+    if (!storeName) {
+        return { phrenPath: ctx.phrenPath, project: projectName, storeRole: "primary" };
+    }
+    const stores = resolveAllStores(ctx.phrenPath);
+    const store = stores.find((s) => s.name === storeName);
+    if (!store) {
+        throw new Error(`Store "${storeName}" not found`);
+    }
+    if (store.role === "readonly") {
+        throw new Error(`Store "${storeName}" is read-only`);
+    }
+    return { phrenPath: store.path, project: projectName, storeRole: store.role };
+}
 /**
  * Convert an McpToolResult into the MCP SDK response format.
  * Single shared implementation — replaces the per-file jsonResponse() duplicates.

package/package.json

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