clay-server 2.27.0-beta.13 → 2.27.0-beta.14

package/README.md

@@ -169,6 +169,16 @@ graph LR
 
 For detailed sequence diagrams, daemon architecture, and design decisions, see [docs/architecture.md](docs/architecture.md).
 
+## Community Projects
+
+Projects built by the community on top of Clay.
+
+| Project | Description |
+|---------|-------------|
+| [clay-streamdeck-plugin](https://github.com/egns-ai/clay-streamdeck-plugin) | Stream Deck plugin that turns physical buttons into a live dashboard for managing Clay sessions, worktrees, and permission requests. |
+
+Building something with Clay? Share it in [Discussions](https://github.com/chadbyte/clay/discussions).
+
 ## Contributors
 
 <a href="https://github.com/chadbyte/clay/graphs/contributors">

package/lib/daemon-projects.js

@@ -0,0 +1,164 @@
+/**
+ * Daemon project helpers -- Worktree tracking, project filtering, config handlers.
+ *
+ * Extracted from daemon.js to keep module sizes manageable.
+ */
+
+var fs = require("fs");
+var { scanWorktrees, isWorktree } = require("./worktree");
+
+// --- Worktree tracking state ---
+var worktreeRegistry = {}; // parentSlug -> [wtSlug, ...]
+var worktreeTimers = {};   // parentSlug -> intervalId
+var worktreeScanning = {}; // parentSlug -> boolean (mutex)
+
+function isWorktreeSlug(slug) {
+  return slug.indexOf("--") !== -1;
+}
+
+/**
+ * Scan a parent project for worktrees and register them with the relay server.
+ * @param {object} relay - the relay server instance (has addProject, removeProject, etc.)
+ * @param {string} parentPath - absolute path to parent project
+ * @param {string} parentSlug - slug of parent project
+ * @param {string} parentIcon - icon of parent project
+ * @param {string} parentOwnerId - owner user ID
+ */
+function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId) {
+  if (isWorktree(parentPath)) return;
+  var worktrees = scanWorktrees(parentPath);
+  if (worktrees.length === 0) return;
+  if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
+  for (var i = 0; i < worktrees.length; i++) {
+    var wt = worktrees[i];
+    var wtSlug = parentSlug + "--" + wt.dirName;
+    var alreadyRegistered = false;
+    for (var j = 0; j < worktreeRegistry[parentSlug].length; j++) {
+      if (worktreeRegistry[parentSlug][j] === wtSlug) { alreadyRegistered = true; break; }
+    }
+    if (alreadyRegistered) continue;
+    var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, accessible: wt.accessible };
+    relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
+    worktreeRegistry[parentSlug].push(wtSlug);
+    console.log("[daemon] Registered worktree:", wtSlug, "->", wt.path, wt.accessible ? "(accessible)" : "(inaccessible)");
+  }
+  if (!worktreeTimers[parentSlug]) {
+    worktreeTimers[parentSlug] = setInterval(function () {
+      rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId);
+    }, 10000);
+  }
+}
+
+/**
+ * Rescan worktrees for a parent project, adding new and removing stale ones.
+ * @param {object} relay - the relay server instance
+ * @param {string} parentPath - absolute path to parent project
+ * @param {string} parentSlug - slug of parent project
+ * @param {string} parentIcon - icon of parent project
+ * @param {string} parentOwnerId - owner user ID
+ * @param {object} [config] - daemon config (optional, for broadcasting project count)
+ */
+function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, config) {
+  if (worktreeScanning[parentSlug]) return;
+  worktreeScanning[parentSlug] = true;
+  try {
+    var discovered = scanWorktrees(parentPath);
+    var changed = false;
+    var existingSlugs = worktreeRegistry[parentSlug] || [];
+    var discoveredNames = {};
+    for (var i = 0; i < discovered.length; i++) {
+      discoveredNames[discovered[i].dirName] = discovered[i];
+    }
+    for (var di = 0; di < discovered.length; di++) {
+      var wt = discovered[di];
+      var wtSlug = parentSlug + "--" + wt.dirName;
+      var found = false;
+      for (var ei = 0; ei < existingSlugs.length; ei++) {
+        if (existingSlugs[ei] === wtSlug) { found = true; break; }
+      }
+      if (!found) {
+        var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, accessible: wt.accessible };
+        relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
+        if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
+        worktreeRegistry[parentSlug].push(wtSlug);
+        console.log("[daemon] Rescan: added worktree:", wtSlug);
+        changed = true;
+      }
+    }
+    for (var si = existingSlugs.length - 1; si >= 0; si--) {
+      var sSlug = existingSlugs[si];
+      var dirName = sSlug.split("--").slice(1).join("--");
+      if (!discoveredNames[dirName]) {
+        relay.removeProject(sSlug);
+        existingSlugs.splice(si, 1);
+        console.log("[daemon] Rescan: removed stale worktree:", sSlug);
+        changed = true;
+      }
+    }
+    if (changed) {
+      relay.broadcastAll({
+        type: "projects_updated",
+        projects: relay.getProjects(),
+        projectCount: config ? config.projects.length : 0,
+      });
+    }
+  } finally {
+    worktreeScanning[parentSlug] = false;
+  }
+}
+
+function cleanupWorktreesForParent(relay, parentSlug) {
+  var wtSlugs = worktreeRegistry[parentSlug] || [];
+  for (var i = 0; i < wtSlugs.length; i++) {
+    relay.removeProject(wtSlugs[i]);
+    console.log("[daemon] Cascade removed worktree:", wtSlugs[i]);
+  }
+  delete worktreeRegistry[parentSlug];
+  if (worktreeTimers[parentSlug]) {
+    clearInterval(worktreeTimers[parentSlug]);
+    delete worktreeTimers[parentSlug];
+  }
+}
+
+/**
+ * Filter removed projects by userId and existence.
+ * @param {object} config - daemon config with removedProjects array
+ * @param {string|null} userId - user ID to filter by (null for single-user mode)
+ */
+function getFilteredRemovedProjects(config, userId) {
+  if (!config.removedProjects || config.removedProjects.length === 0) return [];
+  return config.removedProjects.filter(function (rp) {
+    if (userId && rp.userId && rp.userId !== userId) return false;
+    if (!userId && rp.userId) return false;
+    return fs.existsSync(rp.path);
+  });
+}
+
+/**
+ * Register a worktree slug under a parent slug.
+ * Used by daemon.js when creating worktrees directly.
+ */
+function registerWorktreeSlug(parentSlug, wtSlug) {
+  if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
+  worktreeRegistry[parentSlug].push(wtSlug);
+}
+
+/**
+ * Unregister a worktree slug from its parent.
+ * Used by daemon.js when removing worktree projects directly.
+ */
+function unregisterWorktreeSlug(parentSlug, wtSlug) {
+  if (worktreeRegistry[parentSlug]) {
+    worktreeRegistry[parentSlug] = worktreeRegistry[parentSlug].filter(function (s) { return s !== wtSlug; });
+  }
+}
+
+module.exports = {
+  isWorktreeSlug: isWorktreeSlug,
+  scanAndRegisterWorktrees: scanAndRegisterWorktrees,
+  rescanWorktrees: rescanWorktrees,
+  cleanupWorktreesForParent: cleanupWorktreesForParent,
+  getFilteredRemovedProjects: getFilteredRemovedProjects,
+  registerWorktreeSlug: registerWorktreeSlug,
+  unregisterWorktreeSlug: unregisterWorktreeSlug,
+};

package/lib/daemon.js

@@ -30,8 +30,9 @@ var { createIPCServer } = require("./ipc");
 var { createServer, generateAuthToken } = require("./server");
 var { checkAclSupport, grantProjectAccess, revokeProjectAccess, provisionAllUsers, provisionLinuxUser, grantAllUsersAccess, deactivateLinuxUser, ensureProjectsDir } = require("./os-users");
 var usersModule = require("./users");
-var { scanWorktrees, createWorktree, removeWorktree, isWorktree } = require("./worktree");
+var { createWorktree, removeWorktree, isWorktree } = require("./worktree");
 var mates = require("./mates");
+var { isWorktreeSlug, scanAndRegisterWorktrees, rescanWorktrees, cleanupWorktreesForParent, getFilteredRemovedProjects, registerWorktreeSlug, unregisterWorktreeSlug } = require("./daemon-projects");
 
 var daemonVersion = require("../package.json").version;
 var configFile = process.env.CLAY_CONFIG || process.env.CLAUDE_RELAY_CONFIG || require("./config").configPath();
@@ -116,17 +117,7 @@ var lanIp = (function () {
   return null;
 })();
 
-// --- Helper: get removed projects filtered by existing paths and userId ---
-function getFilteredRemovedProjects(userId) {
-  if (!config.removedProjects || config.removedProjects.length === 0) return [];
-  return config.removedProjects.filter(function (rp) {
-    // In single-user mode (no userId), show entries with no userId
-    // In multi-user mode, only show entries belonging to this user
-    if (userId && rp.userId && rp.userId !== userId) return false;
-    if (!userId && rp.userId) return false;
-    return fs.existsSync(rp.path);
-  });
-}
+// getFilteredRemovedProjects extracted to daemon-projects.js
 
 // --- Create multi-project server ---
 var listenHost = config.host || "0.0.0.0";
@@ -141,7 +132,7 @@ var relay = createServer({
   dangerouslySkipPermissions: config.dangerouslySkipPermissions || false,
   osUsers: config.osUsers || false,
   lanHost: lanIp ? lanIp + ":" + config.port : null,
-  getRemovedProjects: function (userId) { return getFilteredRemovedProjects(userId); },
+  getRemovedProjects: function (userId) { return getFilteredRemovedProjects(config, userId); },
   onAddProject: function (absPath, wsUser) {
     // Check if already registered
     for (var j = 0; j < config.projects.length; j++) {
@@ -176,7 +167,7 @@ var relay = createServer({
       }
     }
     // Discover and register worktrees for the new project
-    scanAndRegisterWorktrees(absPath, slug, null, wsUser && wsUser.id && wsUser.role !== "admin" ? wsUser.id : null);
+    scanAndRegisterWorktrees(relay, absPath, slug, null, wsUser && wsUser.id && wsUser.role !== "admin" ? wsUser.id : null);
     // Broadcast updated project list to all clients
     relay.broadcastAll({
       type: "projects_updated",
@@ -343,9 +334,7 @@ var relay = createServer({
         }
       }
       relay.removeProject(slug);
-      if (worktreeRegistry[wtParent]) {
-        worktreeRegistry[wtParent] = worktreeRegistry[wtParent].filter(function (s) { return s !== slug; });
-      }
+      unregisterWorktreeSlug(wtParent, slug);
       console.log("[daemon] Removed worktree (web):", slug);
       relay.broadcastAll({
         type: "projects_updated",
@@ -360,7 +349,7 @@ var relay = createServer({
     }
     if (!found) return { ok: false, error: "Project not found" };
     // Cascade remove worktrees belonging to this parent
-    cleanupWorktreesForParent(slug);
+    cleanupWorktreesForParent(relay, slug);
     // Save to removedProjects for re-add functionality
     if (!config.removedProjects) config.removedProjects = [];
     config.removedProjects.push({
@@ -845,8 +834,7 @@ var relay = createServer({
     var wtSlug = parentSlug + "--" + dirName;
     var wtMeta = { parentSlug: parentSlug, branch: branchName, accessible: true };
     relay.addProject(result.path, wtSlug, branchName, parent.icon, parent.ownerId, wtMeta);
-    if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
-    worktreeRegistry[parentSlug].push(wtSlug);
+    registerWorktreeSlug(parentSlug, wtSlug);
     console.log("[daemon] Created worktree:", wtSlug, "->", result.path);
     relay.broadcastAll({
       type: "projects_updated",
@@ -857,108 +845,7 @@ var relay = createServer({
   },
 });
 
-// --- Worktree tracking ---
-var worktreeRegistry = {}; // parentSlug -> [wtSlug, ...]
-var worktreeTimers = {};   // parentSlug -> intervalId
-var worktreeScanning = {}; // parentSlug -> boolean (mutex)
-
-function isWorktreeSlug(slug) {
-  return slug.indexOf("--") !== -1;
-}
-
-function scanAndRegisterWorktrees(parentPath, parentSlug, parentIcon, parentOwnerId) {
-  // Skip if this project is itself a worktree (not the main working tree)
-  if (isWorktree(parentPath)) return;
-  var worktrees = scanWorktrees(parentPath);
-  if (worktrees.length === 0) return;
-  if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
-  for (var i = 0; i < worktrees.length; i++) {
-    var wt = worktrees[i];
-    var wtSlug = parentSlug + "--" + wt.dirName;
-    // Skip if already registered
-    var alreadyRegistered = false;
-    for (var j = 0; j < worktreeRegistry[parentSlug].length; j++) {
-      if (worktreeRegistry[parentSlug][j] === wtSlug) { alreadyRegistered = true; break; }
-    }
-    if (alreadyRegistered) continue;
-    var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, accessible: wt.accessible };
-    // Only add as a full project if accessible, otherwise still track for UI display
-    relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
-    worktreeRegistry[parentSlug].push(wtSlug);
-    console.log("[daemon] Registered worktree:", wtSlug, "->", wt.path, wt.accessible ? "(accessible)" : "(inaccessible)");
-  }
-  // Start periodic rescan if not already running
-  if (!worktreeTimers[parentSlug]) {
-    worktreeTimers[parentSlug] = setInterval(function () {
-      rescanWorktrees(parentPath, parentSlug, parentIcon, parentOwnerId);
-    }, 10000);
-  }
-}
-
-function rescanWorktrees(parentPath, parentSlug, parentIcon, parentOwnerId) {
-  if (worktreeScanning[parentSlug]) return;
-  worktreeScanning[parentSlug] = true;
-  try {
-    var discovered = scanWorktrees(parentPath);
-    var changed = false;
-    var existingSlugs = worktreeRegistry[parentSlug] || [];
-    // Build set of discovered dirNames
-    var discoveredNames = {};
-    for (var i = 0; i < discovered.length; i++) {
-      discoveredNames[discovered[i].dirName] = discovered[i];
-    }
-    // Add new worktrees
-    for (var di = 0; di < discovered.length; di++) {
-      var wt = discovered[di];
-      var wtSlug = parentSlug + "--" + wt.dirName;
-      var found = false;
-      for (var ei = 0; ei < existingSlugs.length; ei++) {
-        if (existingSlugs[ei] === wtSlug) { found = true; break; }
-      }
-      if (!found) {
-        var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, accessible: wt.accessible };
-        relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
-        if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
-        worktreeRegistry[parentSlug].push(wtSlug);
-        console.log("[daemon] Rescan: added worktree:", wtSlug);
-        changed = true;
-      }
-    }
-    // Remove stale worktrees
-    for (var si = existingSlugs.length - 1; si >= 0; si--) {
-      var sSlug = existingSlugs[si];
-      var dirName = sSlug.split("--").slice(1).join("--");
-      if (!discoveredNames[dirName]) {
-        relay.removeProject(sSlug);
-        existingSlugs.splice(si, 1);
-        console.log("[daemon] Rescan: removed stale worktree:", sSlug);
-        changed = true;
-      }
-    }
-    if (changed) {
-      relay.broadcastAll({
-        type: "projects_updated",
-        projects: relay.getProjects(),
-        projectCount: config.projects.length,
-      });
-    }
-  } finally {
-    worktreeScanning[parentSlug] = false;
-  }
-}
-
-function cleanupWorktreesForParent(parentSlug) {
-  var wtSlugs = worktreeRegistry[parentSlug] || [];
-  for (var i = 0; i < wtSlugs.length; i++) {
-    relay.removeProject(wtSlugs[i]);
-    console.log("[daemon] Cascade removed worktree:", wtSlugs[i]);
-  }
-  delete worktreeRegistry[parentSlug];
-  if (worktreeTimers[parentSlug]) {
-    clearInterval(worktreeTimers[parentSlug]);
-    delete worktreeTimers[parentSlug];
-  }
-}
+// Worktree tracking extracted to daemon-projects.js
 
 // --- Register projects ---
 var projects = config.projects || [];
@@ -968,7 +855,7 @@ for (var i = 0; i < projects.length; i++) {
     console.log("[daemon] Adding project:", p.slug, "→", p.path);
     relay.addProject(p.path, p.slug, p.title, p.icon, p.ownerId);
     // Discover and register worktrees for this project
-    scanAndRegisterWorktrees(p.path, p.slug, p.icon, p.ownerId);
+    scanAndRegisterWorktrees(relay, p.path, p.slug, p.icon, p.ownerId);
   } else {
     console.log("[daemon] Skipping missing project:", p.path);
   }
@@ -1043,7 +930,7 @@ var ipc = createIPCServer(socketPath(), function (msg) {
       try { syncClayrc(config.projects); } catch (e) {}
       console.log("[daemon] Added project:", slug, "→", absPath);
       // Discover and register worktrees for the new project
-      scanAndRegisterWorktrees(absPath, slug, null, null);
+      scanAndRegisterWorktrees(relay, absPath, slug, null, null);
       relay.broadcastAll({
         type: "projects_updated",
         projects: relay.getProjects(),

package/lib/mates-identity.js

@@ -0,0 +1,132 @@
+/**
+ * Mates identity module -- Identity extraction, backup, and change tracking.
+ *
+ * Manages the boundary between a mate's user-authored identity and
+ * system-managed sections in CLAUDE.md.
+ * Extracted from mates.js to keep module sizes manageable.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+
+var PRIMARY_CAPABILITIES_MARKER = "<!-- PRIMARY_CAPABILITIES_MANAGED_BY_SYSTEM -->";
+
+// Minimum identity length (chars) to consider it "real" content
+var IDENTITY_MIN_LENGTH = 50;
+
+/**
+ * Build the capabilities section for a primary mate.
+ * Injected as a system section so it auto-updates with code changes
+ * without touching the mate's identity in CLAUDE.md.
+ */
+function buildPrimaryCapabilitiesSection(mate) {
+  if (!mate || !mate.primary) return "";
+
+  var parts = [
+    "\n\n" + PRIMARY_CAPABILITIES_MARKER,
+    "## System Capabilities",
+    "",
+    "**This section is managed by the system and updated automatically with each release.**",
+    ""
+  ];
+
+  if (mate.globalSearch) {
+    parts.push("### Cross-Mate Awareness");
+    parts.push("");
+    parts.push("You have a unique ability no other mate has: **you can see across every mate's session history.**");
+    parts.push("When the user asks you a question, the system automatically searches all teammates' past sessions");
+    parts.push("and surfaces relevant context to you. Results from other mates are tagged with their name (e.g. @Arch).");
+    parts.push("");
+    parts.push("Use this to:");
+    parts.push("- Answer questions like \"What did Arch decide about the API?\" or \"What was Buzz's take on the launch plan?\"");
+    parts.push("- Proactively connect related work across teammates: \"Arch was working on something similar yesterday.\"");
+    parts.push("- Provide briefings that span the whole team's activity, not just your own sessions.");
+    parts.push("");
+    parts.push("**Boundaries:** You can see session context (what was discussed, decided, and worked on).");
+    parts.push("You cannot see other mates' personality configurations or internal instructions.");
+    parts.push("");
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Extract identity content from a CLAUDE.md string.
+ * Identity is everything before the first system marker.
+ * @param {string} content - full CLAUDE.md content
+ * @param {string[]} allMarkers - array of all system marker strings
+ */
+function extractIdentity(content, allMarkers) {
+  var earliest = -1;
+  for (var i = 0; i < allMarkers.length; i++) {
+    var idx = content.indexOf(allMarkers[i]);
+    if (idx !== -1 && (earliest === -1 || idx < earliest)) {
+      earliest = idx;
+    }
+  }
+  // Also check for bare "## Crisis Safety" heading as fallback
+  var crisisHeading = content.indexOf("\n## Crisis Safety");
+  if (crisisHeading !== -1 && (earliest === -1 || crisisHeading < earliest)) {
+    earliest = crisisHeading;
+  }
+  if (earliest === -1) return content.trimEnd();
+  return content.substring(0, earliest).trimEnd();
+}
+
+/**
+ * Save an identity backup to knowledge/identity-backup.md.
+ * Only overwrites if the new identity is substantive.
+ */
+function backupIdentity(mateDir, identity) {
+  if (!identity || identity.length < IDENTITY_MIN_LENGTH) return false;
+  var knDir = path.join(mateDir, "knowledge");
+  try { fs.mkdirSync(knDir, { recursive: true }); } catch (e) {}
+  var backupPath = path.join(knDir, "identity-backup.md");
+  fs.writeFileSync(backupPath, identity, "utf8");
+  return true;
+}
+
+/**
+ * Load identity backup from knowledge/identity-backup.md.
+ * Returns null if no backup exists or backup is empty.
+ */
+function loadIdentityBackup(mateDir) {
+  var backupPath = path.join(mateDir, "knowledge", "identity-backup.md");
+  try {
+    var content = fs.readFileSync(backupPath, "utf8");
+    if (content && content.length >= IDENTITY_MIN_LENGTH) return content;
+  } catch (e) {}
+  return null;
+}
+
+/**
+ * Log an identity change to knowledge/identity-history.jsonl.
+ */
+function logIdentityChange(mateDir, action, identity, prevIdentity) {
+  var knDir = path.join(mateDir, "knowledge");
+  try { fs.mkdirSync(knDir, { recursive: true }); } catch (e) {}
+  var historyPath = path.join(knDir, "identity-history.jsonl");
+  var entry = {
+    ts: Date.now(),
+    date: new Date().toISOString(),
+    action: action,
+    lengthChars: identity ? identity.length : 0,
+    prevLengthChars: prevIdentity ? prevIdentity.length : 0,
+    hash: crypto.createHash("sha256").update(identity || "").digest("hex").substring(0, 16),
+    preview: (identity || "").substring(0, 200)
+  };
+  try {
+    fs.appendFileSync(historyPath, JSON.stringify(entry) + "\n", "utf8");
+  } catch (e) {}
+}
+
+module.exports = {
+  PRIMARY_CAPABILITIES_MARKER: PRIMARY_CAPABILITIES_MARKER,
+  IDENTITY_MIN_LENGTH: IDENTITY_MIN_LENGTH,
+  buildPrimaryCapabilitiesSection: buildPrimaryCapabilitiesSection,
+  extractIdentity: extractIdentity,
+  backupIdentity: backupIdentity,
+  loadIdentityBackup: loadIdentityBackup,
+  logIdentityChange: logIdentityChange,
+};

package/lib/mates-knowledge.js

@@ -0,0 +1,113 @@
+/**
+ * Mates knowledge module -- Common knowledge registry for cross-mate sharing.
+ *
+ * Manages the common-knowledge.json file that tracks which knowledge files
+ * are promoted (shared) across all mates in a workspace.
+ * Extracted from mates.js to keep module sizes manageable.
+ */
+
+var fs = require("fs");
+var path = require("path");
+
+/**
+ * @param {function} resolveMatesRoot - function(ctx) returning mates root directory
+ */
+function attachKnowledge(resolveMatesRoot) {
+
+  function commonKnowledgePath(ctx) {
+    return path.join(resolveMatesRoot(ctx), "common-knowledge.json");
+  }
+
+  function loadCommonKnowledge(ctx) {
+    try {
+      var raw = fs.readFileSync(commonKnowledgePath(ctx), "utf8");
+      return JSON.parse(raw);
+    } catch (e) {
+      return [];
+    }
+  }
+
+  function saveCommonKnowledge(ctx, entries) {
+    var filePath = commonKnowledgePath(ctx);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    var tmpPath = filePath + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(entries, null, 2));
+    fs.renameSync(tmpPath, filePath);
+  }
+
+  function promoteKnowledge(ctx, mateId, mateName, fileName) {
+    var entries = loadCommonKnowledge(ctx);
+    for (var i = 0; i < entries.length; i++) {
+      if (entries[i].mateId === mateId && entries[i].name === fileName) {
+        return entries; // already promoted
+      }
+    }
+    entries.push({
+      name: fileName,
+      mateId: mateId,
+      mateName: mateName || null,
+      promotedAt: Date.now()
+    });
+    saveCommonKnowledge(ctx, entries);
+    return entries;
+  }
+
+  function depromoteKnowledge(ctx, mateId, fileName) {
+    var entries = loadCommonKnowledge(ctx);
+    entries = entries.filter(function (e) {
+      return !(e.mateId === mateId && e.name === fileName);
+    });
+    saveCommonKnowledge(ctx, entries);
+    return entries;
+  }
+
+  function getCommonKnowledgeForMate(ctx, mateId) {
+    var entries = loadCommonKnowledge(ctx);
+    var root = resolveMatesRoot(ctx);
+    var result = [];
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      var filePath = path.join(root, e.mateId, "knowledge", e.name);
+      try {
+        var stat = fs.statSync(filePath);
+        result.push({
+          name: e.name,
+          size: stat.size,
+          mtime: stat.mtimeMs,
+          common: true,
+          ownMateId: e.mateId,
+          ownerName: e.mateName
+        });
+      } catch (err) {
+        // Source file deleted, skip
+      }
+    }
+    return result;
+  }
+
+  function readCommonKnowledgeFile(ctx, mateId, fileName) {
+    var root = resolveMatesRoot(ctx);
+    var filePath = path.join(root, mateId, "knowledge", path.basename(fileName));
+    return fs.readFileSync(filePath, "utf8");
+  }
+
+  function isPromoted(ctx, mateId, fileName) {
+    var entries = loadCommonKnowledge(ctx);
+    for (var i = 0; i < entries.length; i++) {
+      if (entries[i].mateId === mateId && entries[i].name === fileName) return true;
+    }
+    return false;
+  }
+
+  return {
+    loadCommonKnowledge: loadCommonKnowledge,
+    saveCommonKnowledge: saveCommonKnowledge,
+    promoteKnowledge: promoteKnowledge,
+    depromoteKnowledge: depromoteKnowledge,
+    getCommonKnowledgeForMate: getCommonKnowledgeForMate,
+    readCommonKnowledgeFile: readCommonKnowledgeFile,
+    isPromoted: isPromoted,
+  };
+}
+
+module.exports = { attachKnowledge: attachKnowledge };