clay-server 2.34.1-beta.3 → 2.35.0-beta.1

package/lib/daemon.js

@@ -681,6 +681,7 @@ var relay = createServer({
       keepAwake: !!config.keepAwake,
       autoContinueOnRateLimit: !!config.autoContinueOnRateLimit,
       chatLayout: config.chatLayout || "channel",
+      matesEnabled: config.matesEnabled !== false,
       pinEnabled: !!config.pinHash,
       platform: process.platform,
       hostname: os2.hostname(),
@@ -739,6 +740,13 @@ var relay = createServer({
     console.log("[daemon] Auto-continue on rate limit:", want, "(web)");
     return { ok: true, autoContinueOnRateLimit: want };
   },
+  onSetMatesEnabled: function (value) {
+    var want = !!value;
+    config.matesEnabled = want;
+    saveConfig(config);
+    console.log("[daemon] Mates UI:", want ? "on" : "off", "(web)");
+    return { ok: true, matesEnabled: want };
+  },
   onGetToolPalettes: function () {
     return config.toolPalettes || {};
   },

package/lib/public/app.js

@@ -285,6 +285,7 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     cachedMatesList: [],
     cachedDmFavorites: [],
     cachedAvailableBuiltins: [],
+    matesEnabled: true,
     returningFromMateDm: false,
     pendingMateInterview: null,
     pendingTermCommand: null,
@@ -788,7 +789,13 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     get projectList() { return getCachedProjects(); },
   });
   fetch("/api/me").then(function (r) { return r.json(); }).then(function (d) {
-    if (d.multiUser) { store.set({ isMultiUserMode: true }); }
+    if (d.multiUser) {
+      store.set({ isMultiUserMode: true });
+      // Body class lets CSS treat single-user / multi-user differently for
+      // the Mates UI gate: single-user collapses the whole mate section,
+      // multi-user keeps it visible (still hosts other users' avatars).
+      if (document.body) document.body.classList.add('is-multi-user');
+    }
     if (d.user && d.user.id) { store.set({ myUserId: d.user.id }); }
     if (d.permissions) store.set({ permissions: d.permissions });
     if (d.mustChangePin) showForceChangePinOverlay();

package/lib/public/css/mates.css

@@ -3104,3 +3104,106 @@ body.mate-dm-active .activity-inline:not(.mention-activity-bar):not(.mate-pre-ac
     flex: 1;
   }
 }
+
+/* === Mates UI gate === */
+/* body.mates-disabled is set when the user flips the Mates toggle off in
+   User Settings → Mates. body.is-multi-user is set when the deploy hosts
+   more than one user. Single-user collapses the whole Mates surface;
+   multi-user keeps Mates-adjacent containers visible (they still host
+   other users) but greys out and disables the Mates-specific bits. */
+
+/* Always hide pure-Mates UI: rotating switch hint, individual mate
+   avatars in the icon strip, the home-hub mates strip, and the
+   "Ask Mate" button in the chat input. These never contain anything
+   but mates, so they collapse in both modes. */
+body.mates-disabled .icon-strip-mate,
+body.mates-disabled #icon-strip-hint-mate,
+body.mates-disabled #home-hub-mates,
+body.mates-disabled #ask-mate-btn {
+  display: none !important;
+}
+
+/* Single-user only: collapse the whole icon-strip mate wrapper since it
+   shares space with the user-strip but has no other users to display in
+   single-user mode. The DM picker stays visible in both modes so the
+   user always has a way to discover the toggle (single-user can't reach
+   the picker today since the + button lives inside the wrapper, but if
+   that ever changes the same disabled UX applies). */
+body.mates-disabled:not(.is-multi-user) #icon-strip-mate-section {
+  display: none !important;
+}
+
+/* === Mates discovery promo (DM picker, disabled state) === */
+/* Shown in both modes when Mates is off. Replaces the old "greyed mate
+   list with trash icons" pattern with a softer invitation: section
+   label, an animated avatar marquee that loops left, a value-prop
+   sentence, and a CTA that deep-links into User Settings → Mates. */
+
+.dm-picker-mates-promo {
+  padding: 0 12px 8px;
+}
+
+.dm-picker-mates-promo .dm-user-picker-section {
+  margin-top: 0;
+}
+
+.dm-picker-mates-marquee {
+  position: relative;
+  height: 28px;
+  margin: 4px -12px;
+  overflow: hidden;
+  -webkit-mask-image: linear-gradient(to right, transparent, black 12%, black 88%, transparent);
+  mask-image: linear-gradient(to right, transparent, black 12%, black 88%, transparent);
+}
+
+.dm-picker-mates-marquee-track {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: max-content;
+  height: 100%;
+  padding: 0 12px;
+  animation: dm-picker-mates-marquee-flow 22s linear infinite;
+}
+
+.dm-picker-mates-marquee-avatar {
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  opacity: 0.85;
+  background: var(--bg-alt, rgba(255, 255, 255, 0.04));
+}
+
+@keyframes dm-picker-mates-marquee-flow {
+  from { transform: translateX(0); }
+  to   { transform: translateX(-50%); }
+}
+
+.dm-picker-mates-promo-text {
+  font-size: 11px;
+  color: var(--text-dimmer, #888);
+  line-height: 1.5;
+  margin: 4px 0 8px;
+}
+
+.dm-picker-mates-promo-cta {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  width: 100%;
+  padding: 6px 10px;
+  border: 1px solid var(--border, #2a2a2a);
+  background: var(--bg-alt, rgba(255, 255, 255, 0.04));
+  color: var(--text);
+  font-size: 11px;
+  cursor: pointer;
+  border-radius: 6px;
+  transition: background 0.15s, border-color 0.15s;
+}
+
+.dm-picker-mates-promo-cta:hover {
+  background: var(--bg-hover, rgba(255, 255, 255, 0.08));
+  border-color: var(--accent, #6366f1);
+}

package/lib/public/index.html

@@ -909,12 +909,14 @@
           <option value="us-account" selected>Account</option>
           <option value="us-appearance">Appearance</option>
           <option value="us-chat">Chat</option>
+          <option value="us-mates">Mates</option>
           <option value="us-email">Email</option>
         </select>
         <div class="us-modal-nav-items">
           <button class="us-nav-item active" data-section="us-account"><span>Account</span></button>
           <button class="us-nav-item" data-section="us-appearance"><span>Appearance</span></button>
           <button class="us-nav-item" data-section="us-chat"><span>Chat</span></button>
+          <button class="us-nav-item" data-section="us-mates"><span>Mates</span></button>
           <button class="us-nav-item" data-section="us-email"><span>Email</span></button>
           <div class="us-nav-separator"></div>
           <button class="us-nav-item us-nav-danger" data-section="us-logout"><span>Log Out</span></button>
@@ -1037,6 +1039,22 @@
           </div>
         </div>
 
+        <!-- Mates section -->
+        <div class="us-section" data-section="us-mates">
+          <h2>Mates</h2>
+          <p class="settings-hint">Specialist AI teammates with assigned roles and long-term memory across sessions. They carry context forward and push back when a session drifts. Use the built-ins or design your own.</p>
+          <div class="settings-card">
+            <label class="settings-toggle-row">
+              <div>
+                <span class="settings-label">Use Mates</span>
+                <div class="settings-hint">Off hides every Mates surface in Clay. Existing Mates and their memory are preserved.</div>
+              </div>
+              <input type="checkbox" id="us-mates-enabled">
+              <span class="toggle-track"><span class="toggle-thumb"></span></span>
+            </label>
+          </div>
+        </div>
+
         <!-- Email section -->
         <div class="us-section" data-section="us-email">
           <h2>Email Accounts</h2>

package/lib/public/modules/app-messages.js

@@ -356,6 +356,16 @@ export function processMessage(msg) {
         break;
 
       case "model_info": {
+        // Drop stale model_info from a vendor that doesn't match the active
+        // session's vendor. On high-latency connections, the server's default-
+        // adapter model_info can arrive after session_switched has already
+        // bound the session to a different vendor. Applying it would replace
+        // currentModels with the wrong vendor's list and trigger app-panels
+        // to request models for the "wrong" vendor, which feeds back into a
+        // ping-pong loop of vendor flapping. See issue #336.
+        var _curV = store.get('currentVendor');
+        if (msg.vendor && _curV && msg.vendor !== _curV) break;
+
         var _modelVal = msg.model;
         if (_modelVal && typeof _modelVal === "object") _modelVal = _modelVal.value || _modelVal.displayName || "";
         var _miUpdate = { currentModels: msg.models || [] };
@@ -530,8 +540,12 @@ export function processMessage(msg) {
           if (!store.get('vendorSelectionLocked') || msg.hasHistory) {
             store.set({ currentVendor: msg.vendor });
           }
+          // Sessions with history have their vendor structurally bound to
+          // the session: lock so a late-arriving default-adapter model_info
+          // can't flip the UI back. Previously this branch unlocked, which
+          // is what allowed the feedback loop in issue #336.
           if (msg.hasHistory) {
-            store.set({ vendorSelectionLocked: false });
+            store.set({ vendorSelectionLocked: true });
           }
         } else if (msg.hasHistory) {
           // Existing session without explicit vendor: reset to claude

package/lib/public/modules/app-skills-install.js

@@ -18,6 +18,11 @@ var pendingSkillInstalls = [];
 var skillInstallCallback = null;
 var skillInstalling = false;
 var skillInstallDone = false;
+// True when the modal contains only "outdated" skills (no "missing"). In that
+// case the user is allowed to skip the update and continue with the original
+// action; the dismissal is remembered for the rest of the browser session so
+// we don't re-prompt on every reconnect / DM open.
+var skillInstallSkippable = false;
 
 export function initSkillInstall() {
   skillInstallModal = document.getElementById("skill-install-modal");
@@ -28,8 +33,8 @@ export function initSkillInstall() {
   skillInstallCancel = document.getElementById("skill-install-cancel");
   skillInstallStatus = document.getElementById("skill-install-status");
 
-  skillInstallCancel.addEventListener("click", hideSkillInstallModal);
-  skillInstallModal.querySelector(".confirm-backdrop").addEventListener("click", hideSkillInstallModal);
+  skillInstallCancel.addEventListener("click", onSkillInstallDismiss);
+  skillInstallModal.querySelector(".confirm-backdrop").addEventListener("click", onSkillInstallDismiss);
 
   skillInstallOk.addEventListener("click", function () {
     if (skillInstallDone) {
@@ -106,6 +111,11 @@ function renderSkillInstallDialog(opts, missing) {
   if (hasMissing && hasOutdated) btnLabel = "Install / Update";
   skillInstallOk.textContent = btnLabel;
   skillInstallOk.className = "confirm-btn confirm-delete";
+  // When only outdated skills are pending, the feature still works on the
+  // current version. Let the user skip and continue; surface that as a
+  // distinct cancel label so it's clear this won't abort the action.
+  skillInstallSkippable = hasOutdated && !hasMissing;
+  skillInstallCancel.textContent = skillInstallSkippable ? "Skip" : "Cancel";
   skillInstallModal.classList.remove("hidden");
 }
 
@@ -115,6 +125,45 @@ function hideSkillInstallModal() {
   pendingSkillInstalls = [];
   skillInstalling = false;
   skillInstallDone = false;
+  skillInstallSkippable = false;
+}
+
+// Cancel/backdrop click handler. For "missing" skills the feature genuinely
+// cannot run without them, so dismiss = drop the callback (existing behavior).
+// For "outdated"-only prompts the feature still works on the old version, so
+// dismiss = remember the choice for this browser session and proceed with cb.
+function onSkillInstallDismiss() {
+  if (skillInstallSkippable) {
+    rememberOutdatedDismissal(pendingSkillInstalls);
+    var proceedCb = skillInstallCallback;
+    skillInstallCallback = null;
+    hideSkillInstallModal();
+    if (proceedCb) proceedCb();
+    return;
+  }
+  hideSkillInstallModal();
+}
+
+function dismissalKey(name, remoteVersion) {
+  return "clay-skill-update-dismissed:" + name + ":" + (remoteVersion || "");
+}
+
+function rememberOutdatedDismissal(items) {
+  try {
+    for (var i = 0; i < items.length; i++) {
+      var it = items[i];
+      if (it.status !== "outdated") continue;
+      sessionStorage.setItem(dismissalKey(it.name, it.remoteVersion), "1");
+    }
+  } catch (e) {}
+}
+
+function isOutdatedDismissed(name, remoteVersion) {
+  try {
+    return sessionStorage.getItem(dismissalKey(name, remoteVersion)) === "1";
+  } catch (e) {
+    return false;
+  }
 }
 
 function updateSkillInstallProgress(done, total) {
@@ -197,29 +246,31 @@ export function requireSkills(opts, cb) {
     .then(function (res) { return res.json(); })
     .then(function (data) {
       var results = data.results || [];
-      // Only "missing" skills block the feature. "outdated" skills already
-      // function — an available update should not hard-gate with a modal
-      // every time a user opens a DM or refreshes the page. Callers can
-      // surface outdated versions elsewhere (e.g. settings / notifications).
+      // "missing" skills hard-block: the feature cannot run without them.
+      // "outdated" skills are surfaced too because skills look like a single
+      // user-facing feature but call vendor-specific tools (codex vs claude)
+      // internally — version drift breaks that consistency. The modal is
+      // skippable for outdated-only cases, and a session-scoped dismissal
+      // suppresses re-prompts so reconnect/refresh doesn't re-fire it.
       var actionable = [];
       for (var i = 0; i < results.length; i++) {
         var r = results[i];
-        if (r.status === "missing") {
-          var orig = null;
-          for (var j = 0; j < opts.skills.length; j++) {
-            if (opts.skills[j].name === r.name) { orig = opts.skills[j]; break; }
-          }
-          if (!orig) continue;
-          actionable.push({
-            name: r.name,
-            url: orig.url,
-            scope: orig.scope || "global",
-            installed: false,
-            status: r.status,
-            installedVersion: r.installedVersion,
-            remoteVersion: r.remoteVersion,
-          });
+        if (r.status !== "missing" && r.status !== "outdated") continue;
+        if (r.status === "outdated" && isOutdatedDismissed(r.name, r.remoteVersion)) continue;
+        var orig = null;
+        for (var j = 0; j < opts.skills.length; j++) {
+          if (opts.skills[j].name === r.name) { orig = opts.skills[j]; break; }
         }
+        if (!orig) continue;
+        actionable.push({
+          name: r.name,
+          url: orig.url,
+          scope: orig.scope || "global",
+          installed: false,
+          status: r.status,
+          installedVersion: r.installedVersion,
+          remoteVersion: r.remoteVersion,
+        });
       }
       if (actionable.length === 0) { cb(); return; }
       pendingSkillInstalls = actionable;

package/lib/public/modules/mate-wizard.js

@@ -102,6 +102,13 @@ export function initMateWizard(sendWs, onMateCreated) {
 }
 
 export function openMateWizard() {
+  // Defensive: if the user has turned off the Mates UI in User Settings,
+  // do not open the wizard even if it gets fired programmatically (e.g.
+  // via a stale event handler). The CSS gate hides the entry point but
+  // we still short-circuit here so JS calls become no-ops.
+  if (typeof document !== "undefined" && document.body && document.body.classList.contains("mates-disabled")) {
+    return;
+  }
   mateWizardStep = 0;
   mateWizardData = {
     relationship: null,

package/lib/public/modules/mention.js

@@ -54,6 +54,15 @@ export function checkForMention(value, cursorPos) {
 
 // --- Autocomplete dropdown ---
 export function showMentionMenu(query) {
+  // Mates UI gate: if the user has turned Mates off in User Settings,
+  // the @-mention dropdown is the entry point for sending a message to a
+  // mate from the regular session input, so suppress it entirely. Once
+  // we surface user-to-user DMs from this dropdown we can scope this
+  // check tighter, but for now the dropdown is mate-only.
+  if (store.get('matesEnabled') === false) {
+    hideMentionMenu();
+    return;
+  }
   var mates = ctx.matesList ? ctx.matesList() : [];
   if (!mates || mates.length === 0) {
     hideMentionMenu();

package/lib/public/modules/profile.js

@@ -5,6 +5,7 @@
 import { iconHtml, refreshIcons } from './icons.js';
 import { setSTTLang } from './stt.js';
 import { avatarUrl, mateAvatarUrl, AVATAR_STYLES } from './avatar.js';
+import { store } from './store.js';
 
 var ctx;
 var profile = { name: '', lang: 'en-US', avatarStyle: 'thumbs', avatarSeed: '', avatarColor: '#7c3aed', avatarCustom: '' };
@@ -577,6 +578,13 @@ export function initProfile(_ctx) {
     if (profile.lang) {
       setSTTLang(profile.lang);
     }
+
+    // Apply Mates UI gate at boot so the sidebar avatars / DM picker
+    // entry / home-hub strip are hidden before the user opens settings.
+    // Default true: only flip the body class off when explicitly false.
+    var matesOn = data.matesEnabled !== false;
+    store.set({ matesEnabled: matesOn });
+    if (document.body) document.body.classList.toggle('mates-disabled', !matesOn);
   }).catch(function(err) {
     console.warn('[Profile] Failed to load:', err);
   });

package/lib/public/modules/sidebar-mates.js

@@ -11,6 +11,7 @@ import { closeProjectCtxMenu } from './sidebar-projects.js';
 import { spawnDustParticles } from './sidebar.js';
 import { openDm } from './app-dm.js';
 import { openMateWizard } from './mate-wizard.js';
+import { openUserSettings } from './user-settings.js';
 import { getCachedProjects } from './app-projects.js';
 
 function sendWs(msg) {
@@ -376,11 +377,14 @@ export function renderUserStrip(allUsers, onlineUserIds, myUserId, dmFavorites,
     }
   }
 
-  // Render mates (favorites + unread in multi-user, all in single-user)
-  var singleUser = allOthers.length === 0;
+  // Render mates: only favorited or unread, regardless of mode. Previously
+  // single-user mode short-circuited to "show all", which meant users who
+  // never engaged with Mates still saw 6 permanent avatars in the rail
+  // with no way to thin them out (#341). Applying the same filter as
+  // multi-user lets users curate the icon strip via favorites; the full
+  // mate list is still reachable from the DM picker.
   var favoriteMates = cachedMates.filter(function (m) {
     if (cachedDmRemovedUsers[m.id]) return false;
-    if (singleUser) return true;
     if (cachedDmFavorites.indexOf(m.id) !== -1) return true;
     if (cachedDmUnread[m.id] && cachedDmUnread[m.id] > 0) return true;
     return false;
@@ -511,11 +515,17 @@ function toggleDmUserPicker(anchorEl) {
   picker.className = "dm-user-picker";
   picker.id = "dm-user-picker";
 
+  // Mates enabled flag is consulted up here so the search input can drop
+  // mates from its placeholder copy when the section is hidden.
+  var matesEnabled = store.get('matesEnabled') !== false;
+
   // Search input
   var searchInput = document.createElement("input");
   searchInput.className = "dm-user-picker-search";
   searchInput.type = "text";
-  searchInput.placeholder = "Search mates and users...";
+  searchInput.placeholder = matesEnabled
+    ? "Search mates and users..."
+    : "Search users...";
   picker.appendChild(searchInput);
 
   // User list element (appended later, after USERS label)
@@ -575,35 +585,51 @@ function toggleDmUserPicker(anchorEl) {
     }
   }
 
-  // --- MATES section ---
-  var matesSectionLabel = document.createElement("div");
-  matesSectionLabel.className = "dm-user-picker-section";
-  matesSectionLabel.textContent = "Mates";
-  picker.appendChild(matesSectionLabel);
-
-  var matesListEl = document.createElement("div");
-  matesListEl.className = "dm-user-picker-list dm-mates-list";
-  picker.appendChild(matesListEl);
-
-  // Update scroll gradient hint
-  function updateMatesScrollHint() {
-    var isOverflow = matesListEl.scrollHeight > matesListEl.clientHeight + 2;
-    if (!isOverflow) {
-      matesListEl.classList.add("no-overflow");
-      matesListEl.classList.remove("scrolled-bottom");
-      return;
-    }
-    matesListEl.classList.remove("no-overflow");
-    var atBottom = matesListEl.scrollTop + matesListEl.clientHeight >= matesListEl.scrollHeight - 4;
-    if (atBottom) {
-      matesListEl.classList.add("scrolled-bottom");
-    } else {
-      matesListEl.classList.remove("scrolled-bottom");
+  // --- Layout depends on whether Mates is enabled ---
+  // When enabled: Mates section first, then Users. Mates list is fully
+  // rendered with delete buttons, create-mate entry, etc.
+  // When disabled: Users first, then a Mates discovery promo (animated
+  // avatar marquee + value prop + a single CTA that deep-links into
+  // User Settings → Mates). We deliberately don't render the actual
+  // mate list when off — showing real mates with greyed-out trash icons
+  // is visually heavy and contradicts the user's choice to hide them.
+  // (matesEnabled is computed earlier near the search input.)
+
+  // matesListEl + renderMatesList are only used in the enabled layout.
+  // Declared up-front so the search handler can reference renderMatesList
+  // safely; renderMatesList stays a no-op in disabled mode.
+  var matesListEl = null;
+  var renderMatesList = function () {};
+
+  function renderMatesEnabledSection() {
+    var matesSectionLabel = document.createElement("div");
+    matesSectionLabel.className = "dm-user-picker-section";
+    matesSectionLabel.textContent = "Mates";
+    picker.appendChild(matesSectionLabel);
+
+    matesListEl = document.createElement("div");
+    matesListEl.className = "dm-user-picker-list dm-mates-list";
+    picker.appendChild(matesListEl);
+
+    // Update scroll gradient hint
+    function updateMatesScrollHint() {
+      var isOverflow = matesListEl.scrollHeight > matesListEl.clientHeight + 2;
+      if (!isOverflow) {
+        matesListEl.classList.add("no-overflow");
+        matesListEl.classList.remove("scrolled-bottom");
+        return;
+      }
+      matesListEl.classList.remove("no-overflow");
+      var atBottom = matesListEl.scrollTop + matesListEl.clientHeight >= matesListEl.scrollHeight - 4;
+      if (atBottom) {
+        matesListEl.classList.add("scrolled-bottom");
+      } else {
+        matesListEl.classList.remove("scrolled-bottom");
+      }
     }
-  }
-  matesListEl.addEventListener("scroll", updateMatesScrollHint);
+    matesListEl.addEventListener("scroll", updateMatesScrollHint);
 
-  function renderMatesList(filter) {
+    renderMatesList = function (filter) {
     matesListEl.innerHTML = "";
     var allMates = cachedMates || [];
     if (filter) {
@@ -752,42 +778,129 @@ function toggleDmUserPicker(anchorEl) {
       emptyEl.textContent = "No mates found";
       matesListEl.appendChild(emptyEl);
     }
-    refreshIcons();
-    requestAnimationFrame(updateMatesScrollHint);
+      refreshIcons();
+      requestAnimationFrame(updateMatesScrollHint);
+    };
+
+    // Create Mate option
+    var createMateEl = document.createElement("div");
+    createMateEl.className = "dm-user-picker-create-mate";
+    var hasCustomMates = (cachedMates || []).some(function (m) { return !m.builtinKey; });
+    var createMateLabel = hasCustomMates ? "Create a Mate" : "Create a Mate for what you're doing";
+    createMateEl.innerHTML = iconHtml("bot") + " <span>" + createMateLabel + "</span>";
+    createMateEl.addEventListener("click", function () {
+      closeDmUserPicker();
+      if (openMateWizard) openMateWizard();
+    });
+    picker.appendChild(createMateEl);
+
+    // Divider
+    var divider = document.createElement("div");
+    divider.style.borderTop = "1px solid var(--border, #333)";
+    divider.style.margin = "4px 0";
+    picker.appendChild(divider);
+
+    // Users section
+    var usersLabelEnabled = document.createElement("div");
+    usersLabelEnabled.className = "dm-user-picker-section";
+    usersLabelEnabled.textContent = "Users";
+    picker.appendChild(usersLabelEnabled);
+    picker.appendChild(listEl);
   }
 
-  // Create Mate option
-  var createMateEl = document.createElement("div");
-  createMateEl.className = "dm-user-picker-create-mate";
-  var hasCustomMates = (cachedMates || []).some(function (m) { return !m.builtinKey; });
-  var createMateLabel = hasCustomMates ? "Create a Mate" : "Create a Mate for what you're doing";
-  createMateEl.innerHTML = iconHtml("bot") + " <span>" + createMateLabel + "</span>";
-  createMateEl.addEventListener("click", function () {
-    closeDmUserPicker();
-    if (openMateWizard) openMateWizard();
-  });
-  picker.appendChild(createMateEl);
-
-  // Divider
-  var divider = document.createElement("div");
-  divider.style.borderTop = "1px solid var(--border, #333)";
-  divider.style.margin = "4px 0";
-  picker.appendChild(divider);
-
-  // Section label for users
-  var sectionLabel = document.createElement("div");
-  sectionLabel.className = "dm-user-picker-section";
-  sectionLabel.textContent = "Users";
-  picker.appendChild(sectionLabel);
-  picker.appendChild(listEl);
-
-  renderMatesList("");
-  renderPickerList("");
-  searchInput.addEventListener("input", function () {
-    var val = searchInput.value;
-    renderMatesList(val);
-    renderPickerList(val);
-  });
+  function renderMatesDisabledLayout() {
+    // Users section first when Mates is off — they are the only thing
+    // a user can actually act on, so they lead.
+    var usersLabel = document.createElement("div");
+    usersLabel.className = "dm-user-picker-section";
+    usersLabel.textContent = "Users";
+    picker.appendChild(usersLabel);
+    picker.appendChild(listEl);
+
+    // Divider
+    var divider = document.createElement("div");
+    divider.style.borderTop = "1px solid var(--border, #333)";
+    divider.style.margin = "8px 0 4px";
+    picker.appendChild(divider);
+
+    // Mates discovery promo: animated avatar marquee + value prop + CTA.
+    // The marquee uses real cached mate avatars purely as decoration; we
+    // never attach click handlers, never show delete buttons, and never
+    // render a list view — turning the section into a soft invitation
+    // rather than a "list with everything greyed out" tease.
+    var promo = document.createElement("div");
+    promo.className = "dm-picker-mates-promo";
+
+    var promoLabel = document.createElement("div");
+    promoLabel.className = "dm-user-picker-section";
+    promoLabel.textContent = "Mates";
+    promo.appendChild(promoLabel);
+
+    var marqueeWrap = document.createElement("div");
+    marqueeWrap.className = "dm-picker-mates-marquee";
+    var marqueeTrack = document.createElement("div");
+    marqueeTrack.className = "dm-picker-mates-marquee-track";
+    var marqueeSource = (cachedMates && cachedMates.length > 0)
+      ? cachedMates.slice(0, 8)
+      : (store.get('cachedAvailableBuiltins') || []).slice(0, 6);
+    // Duplicate the avatar set so the keyframe loop wraps seamlessly.
+    for (var copy = 0; copy < 2; copy++) {
+      for (var mi = 0; mi < marqueeSource.length; mi++) {
+        var src = marqueeSource[mi];
+        var avEl = document.createElement("img");
+        avEl.className = "dm-picker-mates-marquee-avatar";
+        avEl.alt = "";
+        avEl.setAttribute("aria-hidden", "true");
+        if (src.id) {
+          avEl.src = mateAvatarUrl(src, 32);
+        } else {
+          avEl.src = mateAvatarUrl({
+            avatarCustom: src.avatarCustom,
+            avatarStyle: src.avatarStyle || "bottts",
+            avatarSeed: src.displayName,
+            id: src.key,
+          }, 32);
+        }
+        marqueeTrack.appendChild(avEl);
+      }
+    }
+    marqueeWrap.appendChild(marqueeTrack);
+    promo.appendChild(marqueeWrap);
+
+    var promoText = document.createElement("div");
+    promoText.className = "dm-picker-mates-promo-text";
+    promoText.textContent = "Specialist AI teammates with long-term memory across sessions. Mention with @ for design, engineering, strategy, or marketing, or build your own.";
+    promo.appendChild(promoText);
+
+    var cta = document.createElement("button");
+    cta.type = "button";
+    cta.className = "dm-picker-mates-promo-cta";
+    cta.textContent = "Click here to enable Mates";
+    cta.addEventListener("click", function () {
+      closeDmUserPicker();
+      openUserSettings('us-mates');
+    });
+    promo.appendChild(cta);
+
+    picker.appendChild(promo);
+  }
+
+  if (matesEnabled) {
+    renderMatesEnabledSection();
+    renderMatesList("");
+    renderPickerList("");
+    searchInput.addEventListener("input", function () {
+      var val = searchInput.value;
+      renderMatesList(val);
+      renderPickerList(val);
+    });
+  } else {
+    renderMatesDisabledLayout();
+    renderPickerList("");
+    searchInput.addEventListener("input", function () {
+      renderPickerList(searchInput.value);
+    });
+  }
 
   // Focus search
   setTimeout(function () { searchInput.focus(); }, 50);

package/lib/public/modules/user-settings.js

@@ -7,6 +7,7 @@ import { toggleDarkMode, getCurrentTheme, getChatLayout, setChatLayout } from '.
 import { showEmailSetupModal, getEmailAccountListCache } from './context-sources.js';
 import { setSTTLang } from './stt.js';
 import { userAvatarUrl } from './avatar.js';
+import { store } from './store.js';
 
 var ctx = null;
 var settingsEl = null;
@@ -166,6 +167,26 @@ export function initUserSettings(appCtx) {
     });
   }
 
+  // Mates UI toggle. Default-on, so flipping off hides every Mates
+  // surface in the app (sidebar avatars, DM picker entry, home-hub strip)
+  // via the body.mates-disabled CSS gate. Flipping back on restores the
+  // surface; existing Mate data is never deleted.
+  var matesEnabledToggle = document.getElementById('us-mates-enabled');
+  if (matesEnabledToggle) {
+    matesEnabledToggle.addEventListener('change', function () {
+      var want = !!this.checked;
+      applyMatesEnabledClass(want);
+      store.set({ matesEnabled: want });
+      fetch('/api/user/mates-enabled', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ enabled: want }),
+      }).then(function (r) { return r.json(); }).then(function (data) {
+        if (data.ok) showToast(data.matesEnabled ? 'Mates on' : 'Mates off');
+      }).catch(function () {});
+    });
+  }
+
   // Theme switcher (Light / Dark)
   var themeSwitcher = document.getElementById('us-theme-switcher');
   if (themeSwitcher) {
@@ -225,13 +246,16 @@ export function initUserSettings(appCtx) {
   }
 }
 
-function openUserSettings() {
+// Optional `initialSection` lets callers deep-link directly into a specific
+// settings tab (e.g. the disabled-Mates picker button passing 'us-mates').
+// Falls back to Account so existing callers and the icon click are unchanged.
+export function openUserSettings(initialSection) {
   settingsEl.classList.remove('hidden');
   openBtn.classList.add('active');
   refreshIcons(settingsEl);
   populateAccount();
   hidePinForm();
-  switchSection('us-account');
+  switchSection(initialSection || 'us-account');
 }
 
 export function closeUserSettings() {
@@ -259,6 +283,24 @@ function stopProp(e) {
   e.stopPropagation();
 }
 
+// Mates UI gate. When the toggle is off we add `mates-disabled` to the
+// body so CSS can hide every Mates surface (sidebar avatars, DM picker
+// "Create a Mate" entry, home-hub mates strip) without touching the
+// underlying data. JS code paths that gate on `store.get('matesEnabled')`
+// also short-circuit so we don't, for example, open the mate wizard if
+// someone fires it programmatically.
+function applyMatesEnabledClass(enabled) {
+  if (!document.body) return;
+  document.body.classList.toggle('mates-disabled', !enabled);
+}
+
+export function isMatesEnabled() {
+  // Default to true if the store hasn't received profile yet — populating
+  // the false state happens after /api/profile resolves, so an undefined
+  // value at boot should not hide Mates UI.
+  return store.get('matesEnabled') !== false;
+}
+
 function showPinForm() {
   if (!pinForm) return;
   pinForm.classList.remove('hidden');
@@ -392,6 +434,12 @@ function populateAccount() {
     if (data.mateOnboardingShown) {
       try { localStorage.setItem("clay-mate-onboarding-shown", "1"); } catch (e) {}
     }
+    // Mates UI toggle: default true; treat any missing/non-false value as on
+    var matesOn = data.matesEnabled !== false;
+    var matesToggle = document.getElementById('us-mates-enabled');
+    if (matesToggle) matesToggle.checked = matesOn;
+    store.set({ matesEnabled: matesOn });
+    applyMatesEnabledClass(matesOn);
     if (data.chatLayout) {
       setChatLayout(data.chatLayout); // update local cache + CSS
     }

package/lib/server-settings.js

@@ -29,6 +29,7 @@ function attachSettings(ctx) {
         profile.autoContinueOnRateLimit = !!mu.autoContinueOnRateLimit;
         profile.chatLayout = mu.chatLayout || "channel";
         profile.mateOnboardingShown = !!mu.mateOnboardingShown;
+        profile.matesEnabled = mu.matesEnabled !== false;
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify(profile));
         return true;
@@ -50,6 +51,7 @@ function attachSettings(ctx) {
         profile.autoContinueOnRateLimit = !!dc.autoContinueOnRateLimit;
         profile.chatLayout = dc.chatLayout || "channel";
         profile.mateOnboardingShown = !!dc.mateOnboardingShown;
+        profile.matesEnabled = dc.matesEnabled !== false;
       }
       // Check if custom avatar file exists
       try {
@@ -401,6 +403,50 @@ function attachSettings(ctx) {
       return true;
     }
 
+    // PUT /api/user/mates-enabled
+    if (req.method === "PUT" && fullUrl === "/api/user/mates-enabled") {
+      var mu = getMultiUserFromReq(req);
+      if (!mu) {
+        // Single-user: store on daemon config
+        var body = "";
+        req.on("data", function (chunk) { body += chunk; });
+        req.on("end", function () {
+          try {
+            var data = JSON.parse(body);
+            var want = !!data.enabled;
+            if (typeof opts.onSetMatesEnabled === "function") {
+              opts.onSetMatesEnabled(want);
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true, matesEnabled: want }));
+          } catch (e) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end('{"error":"Invalid request"}');
+          }
+        });
+        return true;
+      }
+      var body = "";
+      req.on("data", function (chunk) { body += chunk; });
+      req.on("end", function () {
+        try {
+          var data = JSON.parse(body);
+          var result = users.setMatesEnabled(mu.id, !!data.enabled);
+          if (result.error) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: result.error }));
+            return;
+          }
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: true, matesEnabled: result.matesEnabled }));
+        } catch (e) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end('{"error":"Invalid request"}');
+        }
+      });
+      return true;
+    }
+
     // PUT /api/user/chat-layout
     if (req.method === "PUT" && fullUrl === "/api/user/chat-layout") {
       var mu = getMultiUserFromReq(req);

package/lib/users-preferences.js

@@ -217,6 +217,36 @@ function attachPreferences(deps) {
     return { error: "User not found" };
   }
 
+  // --- Per-user Mates UI toggle ---
+  //
+  // When false, the entire Mates surface (sidebar avatars, DM "Create a
+  // Mate" entry, home-hub mates strip) is hidden for this user. Default
+  // is ON: Mates is opt-out, not opt-in. Stored as `matesEnabled`; we
+  // treat any value other than the literal `false` as enabled so brand-
+  // new users (no field set) get the default-on experience.
+
+  function getMatesEnabled(userId) {
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id === userId) {
+        return data.users[i].matesEnabled !== false;
+      }
+    }
+    return true;
+  }
+
+  function setMatesEnabled(userId, enabled) {
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id === userId) {
+        data.users[i].matesEnabled = !!enabled;
+        saveUsers(data);
+        return { ok: true, matesEnabled: !!enabled };
+      }
+    }
+    return { error: "User not found" };
+  }
+
   // --- Per-user tool palette preferences ---
   //
   // Each user can customize the sidebar tool grid by reordering or
@@ -291,6 +321,8 @@ function attachPreferences(deps) {
     setChatLayout: setChatLayout,
     getAutoContinue: getAutoContinue,
     setAutoContinue: setAutoContinue,
+    getMatesEnabled: getMatesEnabled,
+    setMatesEnabled: setMatesEnabled,
     getToolPalettes: getToolPalettes,
     setToolPalette: setToolPalette,
     setMateOnboarded: setMateOnboarded,

package/lib/users.js

@@ -416,6 +416,8 @@ var getChatLayout = preferences.getChatLayout;
 var setChatLayout = preferences.setChatLayout;
 var getAutoContinue = preferences.getAutoContinue;
 var setAutoContinue = preferences.setAutoContinue;
+var getMatesEnabled = preferences.getMatesEnabled;
+var setMatesEnabled = preferences.setMatesEnabled;
 var getToolPalettes = preferences.getToolPalettes;
 var setToolPalette = preferences.setToolPalette;
 var setMateOnboarded = preferences.setMateOnboarded;
@@ -475,6 +477,8 @@ module.exports = {
   setMateOnboarded: setMateOnboarded,
   getAutoContinue: getAutoContinue,
   setAutoContinue: setAutoContinue,
+  getMatesEnabled: getMatesEnabled,
+  setMatesEnabled: setMatesEnabled,
   getToolPalettes: getToolPalettes,
   setToolPalette: setToolPalette,
   getDeletedBuiltinKeys: getDeletedBuiltinKeys,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "2.34.1-beta.3",
+  "version": "2.35.0-beta.1",
   "description": "Self-hosted Claude Code in your browser. Multi-session, multi-user, push notifications.",
   "bin": {
     "clay-server": "./bin/cli.js",