clay-server 5.1.0-beta.1 → 5.1.0-beta.3

package/lib/knowledge-markdown.js

@@ -0,0 +1,128 @@
+var path = require("path");
+
+function slug(value) {
+  return String(value || "").trim().toLowerCase().replace(/<[^>]*>/g, "").replace(/[^\p{L}\p{N}\s-]/gu, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+}
+
+function frontmatter(content) {
+  var text = String(content || "");
+  if (text.indexOf("---\n") !== 0) return { properties: {}, tags: [], end: 0, errors: [] };
+  var close = text.indexOf("\n---\n", 4);
+  if (close === -1 || close > 8192) return { properties: {}, tags: [], end: 0, errors: ["Frontmatter is missing its closing --- line."] };
+  var properties = {}; var errors = []; var lines = text.slice(4, close).split("\n");
+  for (var i = 0; i < lines.length; i++) {
+    if (!lines[i].trim() || /^\s*#/.test(lines[i])) continue;
+    var match = /^([A-Za-z][A-Za-z0-9_-]{0,63}):\s*(.*)$/.exec(lines[i]);
+    if (!match) { errors.push("Invalid property on line " + (i + 2) + "."); continue; }
+    var value = match[2].trim();
+    if (value.length > 500) errors.push("Property " + match[1] + " is too long.");
+    else properties[match[1]] = value;
+  }
+  var tags = [];
+  if (properties.tags) {
+    var raw = properties.tags.replace(/^\[/, "").replace(/\]$/, "").split(",");
+    for (var t = 0; t < raw.length; t++) {
+      var tag = raw[t].trim().replace(/^#/, "");
+      if (/^[\p{L}\p{N}_/-]{1,64}$/u.test(tag) && tags.indexOf(tag) === -1) tags.push(tag);
+      else if (tag) errors.push("Invalid tag: " + tag);
+    }
+  }
+  return { properties: properties, tags: tags, end: close + 5, errors: errors };
+}
+
+function ignoredRanges(text) {
+  var ranges = []; var lines = text.split("\n"); var offset = 0; var fence = null;
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i]; var marker = /^( {0,3})(`{3,}|~{3,})(.*)$/.exec(line);
+    if (marker && (!fence || marker[2][0] === fence.marker && marker[2].length >= fence.length && /^\s*$/.test(marker[3]))) {
+      if (!fence) fence = { marker: marker[2][0], length: marker[2].length, start: offset };
+      else { ranges.push([fence.start, offset + line.length]); fence = null; }
+    }
+    if (!fence) {
+      var cursor = 0;
+      while (cursor < line.length) {
+        var opener = /`+/.exec(line.slice(cursor)); if (!opener) break;
+        var start = cursor + opener.index; var run = opener[0]; var close = line.indexOf(run, start + run.length);
+        if (close === -1) { cursor = start + run.length; continue; }
+        ranges.push([offset + start, offset + close + run.length]); cursor = close + run.length;
+      }
+    }
+    offset += line.length + 1;
+  }
+  if (fence) ranges.push([fence.start, text.length]);
+  return ranges;
+}
+
+function escaped(text, start) {
+  var slashes = 0;
+  for (var i = start - 1; i >= 0 && text[i] === "\\"; i--) slashes++;
+  return slashes % 2 === 1;
+}
+
+function inside(ranges, start) {
+  for (var i = 0; i < ranges.length; i++) if (start >= ranges[i][0] && start < ranges[i][1]) return true;
+  return false;
+}
+
+function parse(content) {
+  var text = String(content || ""); var ignored = ignoredRanges(text); var links = []; var headings = []; var match;
+  var headingPattern = /^(#{1,6})\s+(.+?)\s*#*\s*$/gm;
+  while ((match = headingPattern.exec(text))) {
+    if (!inside(ignored, match.index)) headings.push({ depth: match[1].length, text: match[2].trim(), slug: slug(match[2]), offset: match.index });
+  }
+  var wiki = /(!)?\[\[([^\]\n]+)\]\]/g;
+  while ((match = wiki.exec(text))) {
+    if (inside(ignored, match.index) || escaped(text, match.index)) continue;
+    var parts = match[2].split("|"); var target = parts[0].trim(); var alias = parts.length > 1 ? parts.slice(1).join("|").trim() : "";
+    var hash = target.indexOf("#");
+    var wikiTarget = hash === -1 ? target : target.slice(0, hash);
+    links.push({ kind: match[1] ? "embed" : "wiki", target: wikiTarget, heading: hash === -1 ? "" : target.slice(hash + 1), alias: alias,
+      start: match.index, end: match.index + match[0].length, raw: match[0], external: /^[a-z][a-z0-9+.-]*:/i.test(wikiTarget) || wikiTarget.indexOf("//") === 0 });
+  }
+  var markdown = /(!)?\[([^\]\n]*)\]\(([^)\n]+)\)/g;
+  while ((match = markdown.exec(text))) {
+    if (inside(ignored, match.index) || escaped(text, match.index)) continue;
+    var destination = match[3].trim().replace(/^<|>$/g, ""); var hashAt = destination.indexOf("#");
+    links.push({ kind: match[1] ? "image" : "markdown", target: hashAt === -1 ? destination : destination.slice(0, hashAt), heading: hashAt === -1 ? "" : destination.slice(hashAt + 1), alias: match[2],
+      start: match.index, end: match.index + match[0].length, raw: match[0], external: /^[a-z][a-z0-9+.-]*:/i.test(destination) || destination.indexOf("//") === 0 });
+  }
+  links.sort(function (a, b) { return a.start - b.start; });
+  var meta = frontmatter(text); var tags = meta.tags.slice(); var tagPattern = /(^|\s)#([\p{L}\p{N}_/-]{1,64})/gu;
+  while ((match = tagPattern.exec(text))) if (!inside(ignored, match.index) && tags.indexOf(match[2]) === -1) tags.push(match[2]);
+  return { links: links, headings: headings, properties: meta.properties, tags: tags, propertyErrors: meta.errors };
+}
+
+function normalizeTarget(sourceName, target) {
+  var raw = String(target || "").trim();
+  if (!raw || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.indexOf("//") === 0) return null;
+  try { raw = decodeURIComponent(raw); } catch (error) {}
+  raw = raw.replace(/\\/g, "/");
+  if (!/\.md$/i.test(raw)) raw += ".md";
+  return path.posix.normalize(path.posix.join(path.posix.dirname(sourceName), raw)).replace(/^\.\//, "");
+}
+
+function resolveLink(sourceName, link, documents, sourceId) {
+  if (link.external) return null;
+  if (!link.target && link.heading) {
+    var self = documents.filter(function (item) { return sourceId ? item.id === sourceId : item.name === sourceName; });
+    return self.length === 1 ? self[0] : null;
+  }
+  var target = normalizeTarget(sourceName, link.target);
+  if (!target) return null;
+  var exact = documents.filter(function (item) { return item.name.toLowerCase() === target.toLowerCase(); });
+  if (exact.length === 1) return exact[0];
+  if (link.target.indexOf("/") === -1 && link.target.indexOf("\\") === -1) {
+    var base = path.posix.basename(target).toLowerCase();
+    var named = documents.filter(function (item) { return path.posix.basename(item.name).toLowerCase() === base; });
+    if (named.length === 1) return named[0];
+  }
+  return null;
+}
+
+function snippet(content, offset, needle) {
+  var raw = String(content || ""); var at = typeof offset === "number" ? offset : raw.toLowerCase().indexOf(String(needle || "").toLowerCase());
+  if (at < 0) at = 0; var start = Math.max(0, at - 70); var end = Math.min(raw.length, at + 150); var text = raw.slice(start, end).replace(/\s+/g, " ").trim();
+  return (start ? "…" : "") + text + (end < raw.length ? "…" : "");
+}
+
+module.exports = { parse: parse, slug: slug, normalizeTarget: normalizeTarget, resolveLink: resolveLink, snippet: snippet };

package/lib/linear-store.js

@@ -19,34 +19,61 @@ function attachLinearStore(root) {
     catch (error) { if (error.code !== 'EEXIST') throw error; }
     return fs.readFileSync(file);
   }
-  function key(owner) {
+  function record(owner, id) {
     var data = read(owner);
+    return !id || id === "default" ? data : Object.hasOwn(data.connections || {}, id) ? data.connections[id] : {};
+  }
+  function key(owner, id) {
+    var data = record(owner, id);
     if (!data.secret) return null;
     var parts = data.secret.split('.').map(function (part) { return Buffer.from(part, 'base64'); });
     var cipher = crypto.createDecipheriv('aes-256-gcm', masterKey(), parts[0]);
-    cipher.setAAD(Buffer.from(owner)); cipher.setAuthTag(parts[1]);
+    cipher.setAAD(Buffer.from(id && id !== 'default' ? owner + ':' + id : owner)); cipher.setAuthTag(parts[1]);
     return Buffer.concat([cipher.update(parts[2]), cipher.final()]).toString('utf8');
   }
-  function view(owner) {
-    var data = read(owner);
+  function view(owner, id) {
+    var data = record(owner, id);
     return { connected: !!data.secret, workspace: data.workspace || null, revision: data.revision || null };
   }
-  function save(owner, secret, workspace) {
+  function save(owner, secret, workspace, id, name) {
+    if (id && (!/^[a-zA-Z0-9_-]{1,64}$/.test(id) || ['__proto__', 'constructor', 'prototype'].indexOf(id) >= 0)) throw new Error("Invalid connection.");
+    var previous = read(owner);
     var file = filename(owner), data = { revision: crypto.randomBytes(16).toString('hex') };
     if (secret !== null) {
       if (typeof secret !== 'string' || !secret.trim() || secret.length > 4096 || /[\r\n]/.test(secret)) throw new Error('Enter a valid Linear API key.');
       var iv = crypto.randomBytes(12), cipher = crypto.createCipheriv('aes-256-gcm', masterKey(), iv);
-      cipher.setAAD(Buffer.from(owner));
+      cipher.setAAD(Buffer.from(id && id !== 'default' ? owner + ':' + id : owner));
       var bytes = Buffer.concat([cipher.update(secret.trim(), 'utf8'), cipher.final()]);
       data.secret = [iv, cipher.getAuthTag(), bytes].map(function (part) { return part.toString('base64'); }).join('.');
       data.workspace = workspace;
     }
+    if (name !== undefined) {
+      if (typeof name !== 'string' || !name.trim() || name.trim().length > 80) throw new Error('Enter a connection name of up to 80 characters.');
+      data.name = name.trim();
+    } else data.name = record(owner, id).name;
+    if (id && id !== 'default') {
+      previous.connections = previous.connections || {};
+      if (secret === null) delete previous.connections[id];
+      else {
+        if (!previous.connections[id] && Object.keys(previous.connections).length >= 30) throw new Error('Connection limit reached.');
+        previous.connections[id] = data;
+      }
+      data = previous;
+    } else data.connections = previous.connections;
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
     var temp = file + '.' + crypto.randomBytes(8).toString('hex') + '.tmp';
     try { fs.writeFileSync(temp, JSON.stringify(data), { mode: 0o600 }); fs.renameSync(temp, file); }
     finally { try { fs.unlinkSync(temp); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
-    return view(owner);
+    return view(owner, id);
+  }
+  function list(owner) {
+    var data = read(owner), entries = [];
+    if (data.secret) entries.push(Object.assign({ id: 'default', name: data.name || 'Existing connection', legacy: true }, view(owner)));
+    Object.keys(data.connections || {}).forEach(function (id) {
+      entries.push(Object.assign({ id: id, name: data.connections[id].name || 'Linear', legacy: false }, view(owner, id)));
+    });
+    return entries;
   }
-  return { key: key, view: view, save: save };
+  return { key: key, view: view, save: save, list: list };
 }
 module.exports = { attachLinearStore: attachLinearStore };

package/lib/mate-identity-file.js

@@ -0,0 +1,39 @@
+// Resolve the canonical Mate identity without overwriting either document.
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+
+function regularFile(file) {
+  try {
+    var stat = fs.lstatSync(file);
+    if (!stat.isFile()) throw new Error('Mate identity must be a regular file: ' + file);
+    return stat;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function resolveMateIdentityFile(directory) {
+  var canonical = path.join(directory, 'AGENTS.md');
+  var legacy = path.join(directory, 'CLAUDE.md');
+  var current = regularFile(canonical);
+  if (!regularFile(legacy)) return canonical;
+  if (!current) {
+    // Exclusive linking preserves owner, mode and bytes and never replaces a
+    // concurrently created canonical file. Unlink only after publication.
+    try { fs.linkSync(legacy, canonical); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      return resolveMateIdentityFile(directory);
+    }
+  } else if (fs.statSync(canonical).ino !== fs.statSync(legacy).ino) {
+    // Preserve a conflicting legacy document outside instruction discovery.
+    var backup = path.join(directory, '.identity-legacy-' + crypto.randomBytes(12).toString('hex') + '.md');
+    fs.linkSync(legacy, backup);
+  }
+  fs.unlinkSync(legacy);
+  return canonical;
+}
+
+module.exports = {resolveMateIdentityFile: resolveMateIdentityFile};

package/lib/mate-knowledge-mcp-server.js

@@ -46,14 +46,37 @@ function handler(bound, method) {
     if (!bound || typeof bound[method] !== "function") {
       return errorResult(new Error("Knowledge tools require an exact session-bound Mate."));
     }
-    try {
-      return textResult(bound[method](args || {}));
-    } catch (e) {
-      return errorResult(e);
-    }
+    try { return Promise.resolve(bound[method](args || {})).then(textResult, errorResult); } catch (e) { return errorResult(e); }
   };
 }
 
+var ID = { type: "string", description: "Stable opaque id returned by a Knowledge database tool." };
+var REVISION = { type: "number", description: "Revision returned by the most recent read or mutation; stale revisions are rejected." };
+var OPERATION = { type: "string", description: "Stable retry id formatted label_<current epoch milliseconds>_<unique suffix>. Reuse the exact id and payload after an uncertain response; receipts are retained for the documented 24-hour retry window." };
+var FIELD = { type: "object", description: "Field with stable id, name, type, required, and type-specific options or reference target." };
+var FILTER = { type: "object", description: "Validated filter: fieldId, op, and value. Supported ops are eq, neq, contains, gt, gte, lt, lte, empty, not-empty." };
+var SORT = { type: "object", description: "Validated sort with fieldId and asc or desc direction." };
+
+function databaseTools(bound) {
+  return [
+    { name: "list_databases", description: "List canonical Knowledge databases, including archived databases when requested, so the Mate can discover and recover them without relying on summary projection.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
+    { name: "create_database", description: "Create a first-class database in this Mate's Knowledge. Defaults to one required title field and a Table view.", inputSchema: buildShape({ name: { type: "string" }, schema: { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
+    { name: "read_database", description: "Read one Knowledge database's current schema, views, revision, and record count.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
+    { name: "rename_database", description: "Rename a Knowledge database with optimistic revision checking.", inputSchema: buildShape({ databaseId: ID, name: { type: "string" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "name", "expectedRevision", "operationId"]), handler: handler(bound, "renameDatabase") },
+    { name: "archive_database", description: "Recoverably archive a Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabase") },
+    { name: "recover_database", description: "Recover an archived Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabase") },
+    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
+    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
+    { name: "query_database", description: "Query a bounded deterministic page of records using a saved view or explicit validated filters and sorts. Returns count and numeric sums.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: { type: "array", items: FILTER }, sorts: { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
+    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
+    { name: "read_database_record", description: "Read one record with its values, revision, attribution, archive state, and bounded history.", inputSchema: buildShape({ databaseId: ID, recordId: ID }, ["databaseId", "recordId"]), handler: handler(bound, "readDatabaseRecord") },
+    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
+    { name: "archive_database_record", description: "Recoverably archive one record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabaseRecord") },
+    { name: "recover_database_record", description: "Recover one archived record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabaseRecord") },
+    { name: "retry_database_sync", description: "Retry the shared append-only Knowledge summary projection after a canonical database mutation reported projectionPending.", inputSchema: buildShape({ databaseId: ID }, ["databaseId"]), handler: handler(bound, "retryDatabaseSync") },
+  ].map(function (tool) { tool.description = MATE_CONTRACT + " " + tool.description; return tool; });
+}
+
 function mateTools(bound) {
   return [
     {
@@ -87,7 +110,7 @@ function mateTools(bound) {
       }, ["ref"]),
       handler: handler(bound, "readKnowledge"),
     },
-  ];
+  ].concat(databaseTools(bound));
 }
 
 function clayTools(bound) {

package/lib/mate-knowledge-service.js

@@ -393,7 +393,9 @@ function attachMateKnowledgeService(ctx) {
 
     var def = mate.builtinKey ? builtinMates.getBuiltinByKey(mate.builtinKey) : null;
     var isClay = !!(mate.builtinKey === "clay" && def && def.hostAgent === true);
-    return { own: own, isClay: isClay, ownerId: source.projectOwnerId || null };
+    return { own: own, isClay: isClay, ownerId: source.projectOwnerId || null,
+      databaseService: typeof project.getKnowledgeDbService === "function" ? project.getKnowledgeDbService() : null,
+      actor: { type: "user", userId: source.session && source.session.ownerId || source.projectOwnerId || null, displayName: null } };
   }
 
   // A tool handler captured earlier stays valid only while its exact source
@@ -408,7 +410,7 @@ function attachMateKnowledgeService(ctx) {
     function revalidate() {
       var current = resolve(source);
       if (!current) throw new Error("This Knowledge binding is no longer valid for the current session.");
-      if (current.isClay !== initial.isClay || current.own.scopeId !== initial.own.scopeId) {
+      if (current.isClay !== initial.isClay || current.own.scopeId !== initial.own.scopeId || current.databaseService !== initial.databaseService) {
         throw new Error("This Knowledge binding is no longer valid for the current session.");
       }
       return current;
@@ -423,6 +425,10 @@ function attachMateKnowledgeService(ctx) {
     function ownScope() {
       return [revalidate().own];
     }
+    function db(method, args) {
+      var current = revalidate(); if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
+      return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
+    }
     return {
       isClay: false,
       mateId: initial.own.mateId,
@@ -430,6 +436,21 @@ function attachMateKnowledgeService(ctx) {
       listKnowledge: function (args) { return listFor(ownScope(), args || {}, false); },
       searchKnowledge: function (args) { return searchFor(ownScope(), args || {}, false); },
       readKnowledge: function (args) { return readFor(ownScope(), args || {}, false); },
+      listDatabases: function (args) { return db("list", args); },
+      createDatabase: function (args) { return db("create", args); },
+      readDatabase: function (args) { return db("read", args); },
+      renameDatabase: function (args) { return db("rename", args); },
+      archiveDatabase: function (args) { return db("archive", args); },
+      recoverDatabase: function (args) { return db("recover", args); },
+      updateDatabaseSchema: function (args) { return db("updateSchema", args); },
+      saveTableView: function (args) { return db("saveView", args); },
+      queryDatabase: function (args) { return db("query", args); },
+      createDatabaseRecord: function (args) { return db("createRecord", args); },
+      readDatabaseRecord: function (args) { return db("readRecord", args); },
+      updateDatabaseRecord: function (args) { return db("updateRecord", args); },
+      archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
+      recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
+      retryDatabaseSync: function (args) { return db("retryProjection", args); },
     };
   }
 

package/lib/mate-knowledge-sync.js

@@ -12,7 +12,7 @@
 // call idempotent and makes deletions and rewrites work without the call site
 // having to describe what changed.
 //
-// Identity is never mirrored. CLAUDE.md, base-template.md, identity-backup.md,
+// Identity is never mirrored. AGENTS.md, legacy CLAUDE.md, base-template.md, identity-backup.md,
 // and identity-history.jsonl define who a Mate is and remain canonical files.
 // Sticky notes are a separate attention layer and are excluded too.
 
@@ -23,7 +23,7 @@ var config = require("./config");
 var knowledgeImport = require("./knowledge-import");
 
 var SOURCE_NAMESPACE = "mate-knowledge";
-var SOURCE_VERSION = 2;
+var SOURCE_VERSION = 3;
 var MAX_SOURCE_BYTES = 64 * 1024 * 1024;
 
 // Identity and template artifacts. Never mirrored, at any version.
@@ -84,6 +84,13 @@ function sourceKindFor(name) {
   return null;
 }
 
+function safeSourceName(value) {
+  var name = String(value || "").replace(/\\/g, "/").replace(/^\.\//, ""); var parts = name.split("/");
+  if (!name || name[0] === "/" || name.length > 500 || parts.length > 20) return null;
+  if (parts.some(function (part) { return !part || part === "." || part === ".." || part.length > 120; })) return null;
+  return parts.join("/");
+}
+
 function isJournal(name) {
   return !!JOURNAL_KINDS[name] || /\.jsonl$/.test(name);
 }
@@ -133,9 +140,8 @@ function isMateSourceEntry(entry) {
   if (typeof source.sourceVersion !== "number" || source.sourceVersion > SOURCE_VERSION) return false;
   var name = source.fileName;
   if (!name || typeof name !== "string") return false;
-  // The file name and the relative path must agree, so neither field alone is
-  // trusted, and the name must be a plain basename.
-  if (path.basename(name) !== name) return false;
+  // The source name and relative path must agree, so neither field alone is trusted.
+  if (safeSourceName(name) !== name) return false;
   return source.relPath === relativeSource(name);
 }
 
@@ -180,6 +186,18 @@ function readStat(filePath) {
   }
 }
 
+function safeKnowledgeFileStat(root, name) {
+  var parts = name.split("/"); var cursor = root;
+  for (var i = 0; i < parts.length; i++) {
+    cursor = path.join(cursor, parts[i]); var stat;
+    try { stat = fs.lstatSync(cursor); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+    if (stat.isSymbolicLink()) throw new Error("Knowledge source contains a symbolic link.");
+    if (i < parts.length - 1 && !stat.isDirectory()) throw new Error("Knowledge source path is not a directory.");
+    if (i === parts.length - 1 && !stat.isFile()) return null;
+  }
+  return fs.statSync(cursor);
+}
+
 // --- File-addressed sources -------------------------------------------
 
 function syncFile(importer, scope, name, kind, filePath, stat, actor, summary) {
@@ -361,8 +379,8 @@ function syncMateSource(opts) {
     var scope = options.scope || scopeForMateDir(options.mateDir);
     if (!scope) return summary;
     if (options.mateName) scope.mateName = options.mateName;
-    var name = path.basename(String(options.fileName || ""));
-    if (!name) return summary;
+    var rawName = String(options.fileName || ""); var name = safeSourceName(rawName);
+    if (!name) { if (rawName) summary.unsupported++; return summary; }
     if (IDENTITY_FILES.indexOf(name) !== -1) { summary.identitySkipped++; return summary; }
     if (EXCLUDED_FILES.indexOf(name) !== -1) { summary.excluded++; return summary; }
     var kind = sourceKindFor(name);
@@ -370,8 +388,8 @@ function syncMateSource(opts) {
 
     var actor = normalizeActor(options.actor);
     var importer = options.importer || importerFor(scope, options.baseDir);
-    var filePath = path.join(scope.mateDir, "knowledge", name);
-    var stat = readStat(filePath);
+    var knowledgeRoot = path.join(scope.mateDir, "knowledge"); var filePath = path.join(knowledgeRoot, name);
+    var stat = safeKnowledgeFileStat(knowledgeRoot, name);
 
     if (isJournal(name)) syncJournal(importer, scope, name, kind, filePath, stat, actor, summary);
     else syncFile(importer, scope, name, kind, filePath, stat, actor, summary);
@@ -382,19 +400,11 @@ function syncMateSource(opts) {
   return summary;
 }
 
-// Alias that reads better at a call site reacting to a removal or a rewrite.
 function reconcileSource(opts) {
   return syncMateSource(opts);
 }
 
 // Reconcile every durable source in one Mate directory, in both directions.
-//
-// Enumerating the directory alone is not enough. A knowledge file or a whole
-// journal can be deleted while the daemon is stopped, or by direct filesystem
-// tooling, and nothing would ever call syncMateSource for it again. So the
-// scope's own live records are also consulted: any source this module
-// previously imported that is no longer on disk is reconciled, which tombstones
-// a missing file record or every line of a missing journal.
 function reconcileMate(opts) {
   var options = opts || {};
   var summary = options.summary || newSummary();
@@ -404,11 +414,17 @@ function reconcileMate(opts) {
   var knowledgeDir = path.join(scope.mateDir, "knowledge");
   var present = {};
   var entries = [];
-  try {
-    entries = fs.readdirSync(knowledgeDir, { withFileTypes: true });
-  } catch (e) {
-    entries = [];
+  function discover(relative) {
+    var folder = relative ? path.join(knowledgeDir, relative) : knowledgeDir; var children;
+    try { children = fs.readdirSync(folder, { withFileTypes: true }); } catch (error) { return; }
+    for (var d = 0; d < children.length; d++) {
+      var name = relative ? relative + "/" + children[d].name : children[d].name; var stat;
+      try { stat = fs.lstatSync(path.join(knowledgeDir, name)); } catch (error) { continue; }
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) discover(name); else if (stat.isFile()) entries.push({ name: name });
+    }
   }
+  discover("");
   var importer = options.importer || importerFor(scope, options.baseDir);
 
   function reconcileOne(fileName) {
@@ -423,7 +439,6 @@ function reconcileMate(opts) {
   }
 
   for (var i = 0; i < entries.length; i++) {
-    if (!entries[i].isFile()) continue;
     // Recorded as present whatever its kind, so an excluded or unsupported file
     // that still exists is never mistaken for a deleted source.
     present[entries[i].name] = true;

package/lib/mate-ready-creation.js

@@ -1,3 +1,4 @@
+var resolveMateIdentityFile = require('./mate-identity-file').resolveMateIdentityFile;
 // Atomic finalization of an interviewed Mate. No placeholder is exposed unless
 // the complete identity has passed validation and is ready to register.
 
@@ -55,7 +56,7 @@ function createReadyMate(mates, mateCtx, definition) {
       autonomy: ready.autonomy,
     });
     var mateDir = mates.getMateDir(mateCtx, mate.id);
-    var identityPath = path.join(mateDir, "CLAUDE.md");
+    var identityPath = resolveMateIdentityFile(mateDir);
     fs.writeFileSync(identityPath, ready.identityMarkdown + "\n");
     mates.enforceAllSections(identityPath, { ctx: mateCtx, mateId: mate.id });
     fs.mkdirSync(path.join(mateDir, "knowledge"), { recursive: true });

package/lib/mate-workspace-color.js

@@ -0,0 +1,4 @@
+// Only curated pigments may affect a Mate's workspace surface.
+var COLORS = ['mint', 'rose', 'plum', 'coral', 'peach', 'gold', 'sky', 'indigo', 'stone'];
+function valid(value) { return typeof value === 'string' && COLORS.indexOf(value) !== -1; }
+module.exports = { colors: COLORS, valid: valid };

package/lib/mates-identity.js

@@ -2,7 +2,7 @@
  * 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.
+ * system-managed sections in AGENTS.md.
  * Extracted from mates.js to keep module sizes manageable.
  */
 
@@ -18,7 +18,7 @@ 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.
+ * without touching the mate's identity in AGENTS.md.
  */
 function buildPrimaryCapabilitiesSection(mate) {
   if (!mate || !mate.primary) return "";
@@ -52,9 +52,9 @@ function buildPrimaryCapabilitiesSection(mate) {
 }
 
 /**
- * Extract identity content from a CLAUDE.md string.
+ * Extract identity content from a AGENTS.md string.
  * Identity is everything before the first system marker.
- * @param {string} content - full CLAUDE.md content
+ * @param {string} content - full AGENTS.md content
  * @param {string[]} allMarkers - array of all system marker strings
  */
 function extractIdentity(content, allMarkers) {

package/lib/mates-prompts.js

@@ -1,5 +1,5 @@
 /**
- * Mates prompts module -- System section enforcers for mate CLAUDE.md files.
+ * Mates prompts module -- System section enforcers for mate AGENTS.md files.
  *
  * Each enforcer manages a specific system-managed section (team awareness,
  * session memory, sticky notes, project registry, debate awareness).
@@ -20,7 +20,7 @@ var TEAM_SECTION =
   "**This section is managed by the system and cannot be removed.**\n\n" +
   "You are one of several AI Mates in this workspace. Your teammates and their profiles are listed in `../mates.json`. " +
   "Each teammate's identity and working style is described in their own directory:\n\n" +
-  "- `../{mate_id}/CLAUDE.md` -- their identity, personality, and working style\n" +
+  "- `../{mate_id}/AGENTS.md` -- their identity, personality, and working style\n" +
   "- `../{mate_id}/mate.yaml` -- their metadata (name, role, status, activities)\n" +
   "- `../common-knowledge.json` -- shared knowledge registry; files listed here are readable by all mates\n\n" +
   "Check the team registry when it would be relevant to know who else is available or what they do. " +
@@ -31,6 +31,7 @@ var SESSION_MEMORY_MARKER = "<!-- SESSION_MEMORY_MANAGED_BY_SYSTEM -->";
 var SESSION_MEMORY_SECTION =
   "\n\n" + SESSION_MEMORY_MARKER + "\n" +
   "## Session Memory\n\n" +
+  "Your identity is stored in `AGENTS.md` in your Mate directory. Read and edit that file when reshaping your identity; do not create a separate `CLAUDE.md`.\n\n" +
   "**This section is managed by the system and cannot be removed.**\n\n" +
   "Your `knowledge/memory-summary.md` file contains your compressed long-term memory, " +
   "automatically maintained across sessions. Refer to it for context about past " +
@@ -115,7 +116,7 @@ function buildTeamSection(ctx, currentMateId, loadMates) {
 
   section += "\n" +
     "Each teammate's full identity is in their own directory:\n\n" +
-    "- `../{mate_id}/CLAUDE.md` -- identity, personality, working style\n" +
+    "- `../{mate_id}/AGENTS.md` -- identity, personality, working style\n" +
     "- `../{mate_id}/mate.yaml` -- metadata (name, role, status, activities)\n" +
     "- `../common-knowledge.json` -- shared knowledge readable by all mates\n\n" +
     "Use the **ID** (not the name) when referencing teammates in structured data. " +