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

package/lib/public/index.html

@@ -124,6 +124,7 @@
 
   <!-- === Main Area (sidebar + resize-handle + main-column) === -->
   <div id="main-area">
+    <section id="projects-hub" class="hidden" aria-label="Projects"></section>
     <div id="home-hub" class="hidden">
       <div class="home-hub-inner">
         <button id="home-sidebar-backdrop" class="home-sidebar-backdrop" type="button" aria-label="Close Home navigation"></button>
@@ -136,6 +137,7 @@
             </div>
           </div>
           <nav class="home-sidebar-primary-actions" aria-label="Home actions">
+            <button id="home-nav-projects" class="home-sidebar-action" type="button" title="Projects" aria-label="Projects"><span class="home-sidebar-action-icon" aria-hidden="true"><i data-lucide="folder"></i></span><span>Projects</span></button>
             <button id="home-sidebar-new" class="home-sidebar-action home-sidebar-new" type="button" title="New Chat" aria-label="Start a new chat with the current Mate" disabled><span class="home-sidebar-action-icon" aria-hidden="true"><i data-lucide="message-square-plus"></i></span><span>New Chat</span></button>
             <button id="home-sidebar-debate" class="home-sidebar-action" type="button" title="Browse debates" aria-label="Browse debates" aria-pressed="false"><span class="home-sidebar-action-icon" aria-hidden="true"><i data-lucide="messages-square"></i></span><span>Debates</span></button>
             <button id="home-tools-btn" class="home-sidebar-action" type="button" title="Capsules" aria-label="Capsules" aria-expanded="false" aria-controls="home-tool-workbench"><span class="home-sidebar-action-icon" aria-hidden="true"><i data-lucide="box"></i></span><span id="home-tools-label">Capsules</span><span id="home-tools-activity" class="home-tools-activity" aria-hidden="true"></span></button>
@@ -157,7 +159,7 @@
         </aside>
         <div id="home-workspace" class="home-workspace">
           <button id="home-sidebar-expand" class="home-sidebar-expand" type="button" title="Show sidebar" aria-label="Show Home sidebar" aria-describedby="home-sidebar-expand-brand-label"><i data-lucide="panel-left-open"></i><span id="home-sidebar-expand-brand-label" class="home-sidebar-brand-wordmark home-sidebar-expand-wordmark">Clay Studio</span></button>
-          <button id="home-close-control" class="home-close-control hidden" type="button" title="Close Home" aria-label="Close Home"><i data-lucide="x" aria-hidden="true"></i><span>Close</span></button>
+          <button id="home-close-control" class="home-close-control" type="button" title="Projects" aria-label="Projects"><i data-lucide="folder" aria-hidden="true"></i><span>Projects</span></button>
           <div id="home-conversation-region" class="home-conversation-region">
             <div id="home-mate-chat" class="home-mate-chat">
               <div class="home-mate-chat-stage">
@@ -216,19 +218,6 @@
       </div>
     </div>
 
-    <div id="whats-new-article" class="hidden">
-      <header class="wna-toolbar">
-        <button type="button" class="wna-back" id="wna-back">
-          <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="19" y1="12" x2="5" y2="12"></line><polyline points="12 19 5 12 12 5"></polyline></svg>
-          <span>Back</span>
-        </button>
-      </header>
-      <article class="wna-content">
-        <div class="wna-date" id="wna-date"></div>
-        <h1 class="wna-title" id="wna-title"></h1>
-        <div class="wna-body" id="wna-body"></div>
-      </article>
-    </div>
     <div id="sidebar-column">
       <div class="title-bar-sidebar">
         <button class="title-bar-project-dropdown" id="title-bar-project-dropdown">
@@ -646,6 +635,9 @@
           </div>
         </div>
       </div>
+      <div id="generation-stop-row" class="hidden">
+        <button id="generation-stop" type="button" aria-label="Stop generating"><i data-lucide="square"></i><span>Stop</span></button>
+      </div>
     </div>
   </div>
   <!-- Mobile input-more bottom sheet: attach / image + context sources -->

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

@@ -151,7 +151,19 @@ function suspendSocketWatchdogs() {
   watchdog.suspend();
 }
 
+function refreshBackgroundPane() {
+  if (document.hidden || !store.get('paneNeedsSnapshot')) return false;
+  store.set({ paneNeedsSnapshot: false });
+  if (!store.get('paneMode') || !store.get('paneSessionId') || lifecycle.isOffline()) return false;
+  // A fresh socket discards browser-queued deltas and re-pins the exact pane.
+  // Server replay supplies current history, status and pending interactions.
+  watchdog.resume();
+  connect();
+  return true;
+}
+
 function resumeSocketWatchdogs(reason) {
+  if (refreshBackgroundPane()) return;
   var resumed = watchdog.resume();
   var socket = getWs();
   if (socket && socket.readyState === 1 && resumed) startHeartbeat(socket, lifecycle.getEpoch());
@@ -178,10 +190,13 @@ export function initConnection() {
     });
   });
   document.addEventListener("visibilitychange", function () {
-    if (document.hidden) suspendSocketWatchdogs();
-    else resumeSocketWatchdogs("visible");
+    if (document.hidden) {
+      if (store.get('paneMode') && store.get('paneSessionId')) store.set({ paneNeedsSnapshot: true });
+      suspendSocketWatchdogs();
+    } else resumeSocketWatchdogs("visible");
   });
   document.addEventListener("freeze", function () {
+    if (store.get('paneMode') && store.get('paneSessionId')) store.set({ paneNeedsSnapshot: true });
     suspendSocketWatchdogs();
   });
   document.addEventListener("resume", function () {
@@ -387,6 +402,12 @@ export function connect() {
 
   newWs.onmessage = function (event) {
     if (getWs() !== newWs || !lifecycle.current(attemptEpoch)) return;
+    // Hidden pane deltas are replaced by a current server snapshot on return.
+    if (store.get('paneMode') && store.get('paneSessionId') && document.hidden) {
+      store.set({ paneNeedsSnapshot: true });
+      return;
+    }
+    if (refreshBackgroundPane()) return;
     // Backup: if we're receiving messages, we're connected
     if (!store.get('connected')) {
       setStatus("connected");

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

@@ -83,6 +83,7 @@ export function drawFaviconAnimFrame() {
 
 export function setSendBtnMode(mode) {
   var sendBtn = getSendBtn();
+  sendBtn.setAttribute("aria-label", mode === "stop" ? "Stop generating" : "Send");
   if (mode === "stop") {
     sendBtn.disabled = false;
     sendBtn.classList.add("stop");

package/lib/public/modules/app-home-hub.js

@@ -1,5 +1,6 @@
 // app-home-hub.js - Home work hub navigation and first-depth Mate list.
 
+import { showProjectsHub, hideProjectsHub } from './projects-hub.js';
 import { store } from './store.js';
 import { getWs } from './ws-ref.js';
 import { getCachedProjects, switchProject } from './app-projects.js';
@@ -42,7 +43,7 @@ function syncHomePresentation() {
 function syncHomeCloseControl() {
   var close = document.getElementById("home-close-control");
   if (!close) return;
-  close.classList.toggle("hidden", !getHomeReturnSlug());
+  close.classList.remove("hidden");
 }
 
 function getHomeReturnSlug() {
@@ -245,7 +246,8 @@ export function initHomeHub() {
   initHomeDock();
   initHomeDebatesArchive();
   document.getElementById("home-mate-list").addEventListener("keydown", handleMateListKeydown);
-  document.getElementById("home-close-control").addEventListener("click", minimizeHomeHub);
+  document.getElementById("home-close-control").addEventListener("click", function () { showProjectsHub(); });
+  document.getElementById("home-nav-projects").addEventListener("click", function () { showProjectsHub(); });
   window.addEventListener("clay:home-debate", function () { hideHomeHub(); });
   document.addEventListener("visibilitychange", syncHomePresentation);
 
@@ -349,6 +351,8 @@ export function updateHomeIconBadge() {
 }
 
 export function showHomeHub(fromHistory) {
+  hideProjectsHub();
+  store.set({ pendingHomeProjectSlug: null });
   if (store.get('dmMode')) exitDmMode();
   var activeMateId = store.get('homeChatMateId');
   var resume = homeHubSuspended || homeHubVisible;
@@ -399,7 +403,8 @@ export function hideHomeHub() {
 
 export function minimizeHomeHub() {
   var slug = getHomeReturnSlug();
-  if (!slug || !homeHubVisible) return;
+  if (!homeHubVisible) return;
+  if (!slug) { showProjectsHub(); return; }
   switchProject(slug);
   var projectInput = document.getElementById("input");
   if (projectInput && !projectInput.disabled) projectInput.focus({ preventScroll: true });

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

@@ -66,11 +66,9 @@ import { renderGeneratedImage, renderImageGenerationProgress, clearImageGenerati
 import { clearPairResultStatus, handlePairResultStatus } from './pair-result-status.js';
 
 // --- App module imports ---
-import { scrollToBottom, addToMessages, addUserMessage, addSystemMessage, removeMatePreThinking, appendDelta, finalizeAssistantBlock, addConflictMessage, addContextOverflowMessage, showSuggestionChips, armStickyBottom, VENDOR_AVATARS, VENDOR_NAMES } from './app-rendering.js';
+import { scrollToBottom, addToMessages, addUserMessage, addSystemMessage, removeMatePreThinking, resetStreamBuffer, appendDelta, finalizeAssistantBlock, addConflictMessage, addContextOverflowMessage, showSuggestionChips, armStickyBottom, VENDOR_AVATARS, VENDOR_NAMES } from './app-rendering.js';
 import { setActivity, startUrgentBlink, stopUrgentBlink, blinkSessionDot, updateCrossProjectBlink } from './app-favicon.js';
 import { setStatus } from './app-connection.js';
-import { handleWhatsNewState, handleWhatsNewSeenResult, setKnownEntries as setWhatsNewKnownEntries } from './whats-new.js';
-import { closeArticle as closeWhatsNewArticle } from './whats-new-article.js';
 import { resolvePaneSession, resolveSwitchedVendor } from './pane-session.js';
 import { markProjectSessionListHydrated, applyProjectSplitGroups, clearProjectSplitState } from './split-session-boundary.js';
 import { selectDefaultVendorForBlankSession } from './vendor-selection.js';
@@ -836,8 +834,8 @@ export function processMessage(msg) {
 
       case "session_switched":
         clearPairResultStatus();
+        resetStreamBuffer();
         syncAutonomousRunForSession(msg.autonomousRun || null);
-        closeWhatsNewArticle();
         // Save draft from outgoing session
         var _prevSid = store.get('activeSessionId');
         if (_prevSid && inputEl.value) {
@@ -2127,18 +2125,6 @@ export function processMessage(msg) {
         handleAutoContinueChanged(msg);
         break;
 
-      case "whats_new_state":
-        // Keep a known-entries cache for the home page feed (which shows
-        // both seen and unseen entries), then queue unseen ones for the
-        // carousel.
-        if (msg && Array.isArray(msg.entries)) setWhatsNewKnownEntries(msg.entries);
-        handleWhatsNewState(msg);
-        break;
-
-      case "whats_new_seen_result":
-        handleWhatsNewSeenResult(msg);
-        break;
-
       case "set_claude_open_mode_result":
       case "claude_open_mode_changed":
         if (msg.claudeOpenMode === "tui" || msg.claudeOpenMode === "gui") {

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

@@ -1,6 +1,7 @@
 // app-projects.js - Project list, switching, add/remove project modals
 // Extracted from app.js (PR-29)
 
+import { showProjectsHub, hideProjectsHub, completeProjectsOnboarding } from './projects-hub.js';
 import { escapeHtml, showToast } from './utils.js';
 import { refreshIcons } from './icons.js';
 import { parseEmojis } from './markdown.js';
@@ -17,7 +18,6 @@ import { spawnDustParticles } from './sidebar.js';
 import { isSearchOpen, closeSearch } from './session-search.js';
 import { exitDmMode } from './app-dm.js';
 import { isHomeHubVisible, hideHomeHub, showHomeHub } from './app-home-hub.js';
-import { closeArticle as closeWhatsNewArticle } from './whats-new-article.js';
 import { resetFileBrowser } from './filebrowser.js';
 import { closeNotesBrowser } from './sticky-notes-browser.js';
 import { hideMemory } from './mate-memory.js';
@@ -203,7 +203,7 @@ export function initProjects() {
 // --- State accessors ---
 
 export function getCachedProjects() { return cachedProjects; }
-export function setCachedProjects(v) { cachedProjects = v; }
+export function setCachedProjects(v) { cachedProjects = v; store.set({ projectsHubList: v, projectListLoaded: true }); }
 export function getCachedProjectCount() { return cachedProjectCount; }
 export function setCachedProjectCount(v) { cachedProjectCount = v; }
 export function getCachedRemovedProjects() { return cachedRemovedProjects; }
@@ -223,6 +223,7 @@ export function updateProjectList(msg) {
       _lastProjectsJson = projectsJson;
     }
     cachedProjects = msg.projects;
+    store.set({ projectsHubList: cachedProjects, projectListLoaded: true });
   }
   if (msg.removedProjects) cachedRemovedProjects = msg.removedProjects;
   else if (msg.removedProjects === undefined) { /* keep cached */ }
@@ -424,15 +425,16 @@ export function switchProject(slug) {
   var st = store.snap();
   var ws = getWs();
   var targetWsPath = projectWsPath(slug);
-  var homeVisible = isHomeHubVisible();
+  var homeVisible = isHomeHubVisible() || store.get('projectsHubVisible');
   var alreadyInProject = isProjectActivated(st, slug, ws);
   var wasDm = st.dmMode;
   var wasMate = st.dmMode && st.dmTargetUser && st.dmTargetUser.isMate;
   if (st.dmMode) exitDmMode(wasMate);
-  closeWhatsNewArticle();
   if (homeVisible && alreadyInProject) {
     rememberHomePrimarySurface("project", slug);
     hideHomeHub();
+    hideProjectsHub();
+    completeProjectsOnboarding();
     if (document.documentElement.classList.contains("pwa-standalone")) {
       history.replaceState(null, "", "/p/" + slug + "/");
     } else {
@@ -473,6 +475,8 @@ export function completePendingProjectActivation() {
   var slug = store.get('pendingHomeProjectSlug');
   if (!slug || !isProjectActivated(store.snap(), slug, getWs())) return false;
   store.set({ pendingHomeProjectSlug: null });
+  hideProjectsHub();
+  completeProjectsOnboarding();
   rememberHomePrimarySurface("project", slug);
   if (document.documentElement.classList.contains("pwa-standalone")) {
     history.replaceState(null, "", "/p/" + slug + "/");
@@ -492,7 +496,7 @@ export function confirmCurrentProjectSessionActivation() {
 export function finishProjectSessionActivation() {
   var confirmed = confirmCurrentProjectSessionActivation();
   if (!confirmed) return false;
-  if (!store.get('pendingHomeProjectSlug')) return true;
+  if (!store.get('pendingHomeProjectSlug')) return !isHomeHubVisible() && !store.get('projectsHubVisible');
   return completePendingProjectActivation();
 }
 
@@ -639,7 +643,7 @@ export function handleRemoveProjectResult(msg) {
           });
         }
       }
-      cachedProjects = cachedProjects.filter(function (p) { return p.slug !== msg.slug; });
+      setCachedProjects(cachedProjects.filter(function (p) { return p.slug !== msg.slug; }));
       cachedProjectCount = cachedProjects.length;
       store.set({ currentSlug: null });
       renderProjectList();
@@ -648,7 +652,9 @@ export function handleRemoveProjectResult(msg) {
       if (targetSlug) {
         switchProject(targetSlug);
       } else {
-        showHomeHub();
+        store.set({ wsPath: "/ws", basePath: "/", activeProjectSlug: null });
+        showProjectsHub();
+        connect();
       }
     } else {
       showToast(msg.slug.indexOf("--") !== -1 ? "Worktree removed" : "Project removed", "success");
@@ -698,7 +704,7 @@ function switchAddProjectMode(mode) {
   }, 50);
 }
 
-export function openAddProjectModal() {
+export function openAddProjectModal(mode) {
   addProjectModal.classList.remove("hidden");
   addProjectCreateInput.value = "";
   addProjectCloneInput.value = "";
@@ -738,6 +744,7 @@ export function openAddProjectModal() {
     existingBtn.disabled = false;
     switchAddProjectMode("existing");
   }
+  if (mode === "create" || mode === "clone") switchAddProjectMode(mode);
   renderRemovedProjectsList();
 }
 
@@ -855,10 +862,8 @@ export function handleAddProjectResult(msg) {
     } else {
       var toastMsg = addProjectMode === "create" ? "Project created" : addProjectMode === "clone" ? "Project cloned" : "Project added";
       showToast(toastMsg, "success");
-      if (msg.slug) {
-        switchProject(msg.slug);
-      }
     }
+    if (msg.slug) switchProject(msg.slug);
   } else {
     addProjectError.textContent = msg.error || "Failed to add project";
     addProjectError.classList.remove("hidden");

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

@@ -45,6 +45,11 @@ export function addCopyHandler(msgEl, rawText) {
 export function appendDelta(text) {
   ensureAssistantBlock();
   streamBuffer += text;
+  if (store.get('replayingHistory')) {
+    store.set({ currentFullText: store.get('currentFullText') + streamBuffer });
+    streamBuffer = "";
+    return;
+  }
   if (!streamDrainTimer) {
     streamDrainTimer = requestAnimationFrame(drainStreamTick);
   }
@@ -55,16 +60,9 @@ function drainStreamTick() {
   var _s = store.snap();
   if (!_s.currentMsgEl || streamBuffer.length === 0) return;
 
-  var n;
-  var len = streamBuffer.length;
-  if (len > 200) { n = Math.ceil(len / 4); }
-  else if (len > 80) { n = 8; }
-  else if (len > 30) { n = 5; }
-  else if (len > 10) { n = 2; }
-  else { n = 1; }
-
-  var chunk = streamBuffer.slice(0, n);
-  streamBuffer = streamBuffer.slice(n);
+  // Render everything received by this frame; never replay a typing backlog.
+  var chunk = streamBuffer;
+  streamBuffer = "";
   var newText = _s.currentFullText + chunk;
   store.set({ currentFullText: newText });
 
@@ -82,6 +80,14 @@ function drainStreamTick() {
   }
 }
 
+export function resetStreamBuffer() {
+  if (streamDrainTimer) cancelAnimationFrame(streamDrainTimer);
+  if (highlightTimer) clearTimeout(highlightTimer);
+  streamDrainTimer = null;
+  highlightTimer = null;
+  streamBuffer = "";
+}
+
 export function flushStreamBuffer() {
   if (streamDrainTimer) { cancelAnimationFrame(streamDrainTimer); streamDrainTimer = null; }
   if (streamBuffer.length > 0) {

package/lib/public/modules/generation-stop.js

@@ -0,0 +1,24 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+
+// This control lives outside the composer so drafts and Worker locks cannot
+// take away the human's ability to stop the displayed session.
+export function initGenerationStop() {
+  var row = document.getElementById('generation-stop-row');
+  var button = document.getElementById('generation-stop');
+  if (!row || !button) return;
+  function sync() {
+    row.classList.toggle('hidden', !store.get('processing'));
+    button.disabled = !store.get('connected');
+    button.title = store.get('connected') ? 'Stop generating' : 'Reconnect to stop generating';
+  }
+  button.addEventListener('click', function () {
+    var ws = getWs();
+    if (!store.get('processing') || !store.get('connected') || !ws || ws.readyState !== 1) return;
+    ws.send(JSON.stringify({ type: 'stop' }));
+  });
+  store.subscribe(function (state, previous) {
+    if (state.processing !== previous.processing || state.connected !== previous.connected) sync();
+  });
+  sync();
+}

package/lib/public/modules/home-surface-boot.js

@@ -12,13 +12,18 @@ function explicitProjectPath(pathname) {
 export function resolveHomeBootDestination(options) {
   if (!options) return "wait";
   if (options.paneMode || explicitProjectPath(options.pathname)) return "project";
+  if (/^\/projects\/?$/.test(options.pathname || "")) return "projects";
   // The server-selected project embedded in the root shell is authoritative.
   // Home is entered only through an explicit in-app action; reloading `/`
   // returns to the project workspace even if Home was the last open surface.
   if (options.currentSlug) return "project";
   if (options.surfaceLoaded !== true) return "wait";
-  if (options.dockLoaded !== true) return "wait";
-  return "home";
+  if (options.projectsLoaded !== true) return "wait";
+  if (options.surface === "home") {
+    if (options.dockLoaded !== true) return "wait";
+    return "home";
+  }
+  return "projects";
 }
 
 function finishPendingShell() {
@@ -35,6 +40,7 @@ function settleBoot(state) {
   if (resolved) return;
   var destination = resolveHomeBootDestination({
     surfaceLoaded: state.homeSurfaceLoaded,
+    projectsLoaded: state.projectListLoaded,
     dockLoaded: state.homeDockPreferenceLoaded,
     surface: state.homePrimarySurface,
     currentSlug: state.currentSlug,
@@ -55,7 +61,8 @@ function settleBoot(state) {
     if (input && !input.disabled) input.focus({ preventScroll: true });
     return;
   }
-  store.set({ homeSurfaceBootResolved: true, homeSurfaceRestoreRequested: true });
+  if (destination === "projects") store.set({ homeSurfaceBootResolved: true, projectsHubRestoreRequested: true });
+  else store.set({ homeSurfaceBootResolved: true, homeSurfaceRestoreRequested: true });
   finishPendingShell();
 }
 

package/lib/public/modules/home-surface.js

@@ -21,7 +21,7 @@ function normalizeSessions(value) {
 }
 
 function normalizePrimarySurface(value) {
-  return value === "home" || value === "project" ? value : null;
+  return value === "home" || value === "project" || value === "projects" ? value : null;
 }
 
 function normalizeProjectSlug(value) {
@@ -51,6 +51,7 @@ export function updateHomeSurfacePreference(patch) {
     matesCollapsed: state.homeMatesCollapsed === true,
     chatScope: normalizeChatScope(state.homeChatScope),
     subSurface: normalizeSubSurface(state.homeSubSurface),
+    onboardingStep: state.onboardingStep || "welcome",
   };
   if (patch && Object.prototype.hasOwnProperty.call(patch, "surface")) next.surface = normalizePrimarySurface(patch.surface);
   if (patch && Object.prototype.hasOwnProperty.call(patch, "projectSlug")) next.projectSlug = normalizeProjectSlug(patch.projectSlug);
@@ -60,7 +61,12 @@ export function updateHomeSurfacePreference(patch) {
   if (patch && Object.prototype.hasOwnProperty.call(patch, "matesCollapsed")) next.matesCollapsed = patch.matesCollapsed === true;
   if (patch && Object.prototype.hasOwnProperty.call(patch, "chatScope")) next.chatScope = normalizeChatScope(patch.chatScope);
   if (patch && Object.prototype.hasOwnProperty.call(patch, "subSurface")) next.subSurface = normalizeSubSurface(patch.subSurface);
+  if (patch && ["welcome", "project", "complete"].indexOf(patch.onboardingStep) !== -1) {
+    next.onboardingStep = patch.onboardingStep;
+    store.set({ onboardingIntent: patch.onboardingStep });
+  }
   store.set({
+    onboardingStep: next.onboardingStep,
     homePrimarySurface: next.surface,
     homeSurfaceProjectSlug: next.projectSlug,
     homeActiveSessionByMate: normalizeSessions(next.activeSessionByMate),
@@ -78,6 +84,7 @@ export function updateHomeSurfacePreference(patch) {
   if (patch && Object.prototype.hasOwnProperty.call(patch, "matesCollapsed")) outgoing.matesCollapsed = next.matesCollapsed;
   if (patch && Object.prototype.hasOwnProperty.call(patch, "chatScope")) outgoing.chatScope = next.chatScope;
   if (patch && Object.prototype.hasOwnProperty.call(patch, "subSurface")) outgoing.subSurface = next.subSurface;
+  if (patch && Object.prototype.hasOwnProperty.call(patch, "onboardingStep")) outgoing.onboardingStep = next.onboardingStep;
   return send({ type: "home_surface_set", preference: outgoing });
 }
 
@@ -127,7 +134,11 @@ export function handleHomeSurfaceState(msg) {
   var savedSurface = normalizePrimarySurface(preference.surface);
   var savedProject = normalizeProjectSlug(preference.projectSlug);
   var intentConfirmed = !!intent && intent === savedSurface && intendedProject === savedProject;
+  var onboardingIntent = store.get('onboardingIntent');
+  var savedStep = ["welcome", "project", "complete"].indexOf(preference.onboardingStep) !== -1 ? preference.onboardingStep : "welcome";
   var update = {
+    onboardingStep: onboardingIntent || savedStep,
+    onboardingIntent: onboardingIntent === savedStep ? null : onboardingIntent,
     homeSurfaceLoaded: true,
     homePrimarySurface: intent || savedSurface,
     homeSurfaceProjectSlug: intent ? intendedProject : savedProject,
@@ -142,5 +153,6 @@ export function handleHomeSurfaceState(msg) {
     update.homePreferredMateId = store.get('homePreferredMateId') || preference.activeMateId || store.get('homeChatMateId') || null;
   }
   store.set(update);
+  if (onboardingIntent && onboardingIntent !== savedStep) send({ type: "home_surface_set", preference: { onboardingStep: onboardingIntent } });
   if (intent && !intentConfirmed) send({ type: "home_surface_set", preference: { surface: intent, projectSlug: intendedProject } });
 }

package/lib/public/modules/projects-hub-view.js

@@ -0,0 +1,62 @@
+import { escapeHtml } from './utils.js';
+import { iconHtml } from './icons.js';
+
+export function ordinaryProjects(projects) {
+  return (Array.isArray(projects) ? projects : []).filter(function (project) {
+    return project && !project.isMate && project.slug;
+  });
+}
+
+function button(action, label, extra) {
+  return '<button type="button" class="projects-button ' + (extra || '') + '" data-projects-action="' + action + '">' + label + '</button>';
+}
+
+function setupAction(mode, icon, title, text, disabled) {
+  return '<button type="button" class="projects-setup-action" data-projects-mode="' + mode + '"' + (disabled ? ' disabled' : '') + '>' +
+    '<span class="projects-action-icon">' + iconHtml(icon) + '</span><span><strong>' + title + '</strong><span>' + text + '</span></span>' + iconHtml('arrow-up-right') + '</button>';
+}
+
+export function projectsHubContent(state) {
+  var projects = ordinaryProjects(state.projectsHubList);
+  var ready = state.projectListLoaded && state.homeSurfaceLoaded;
+  var welcome = ready && (state.projectsShowGuide || (!projects.length && (state.onboardingStep || 'welcome') === 'welcome'));
+  var allowed = state.projectsAccessLoaded && (!state.permissions || state.permissions.createProject === true);
+  var available = allowed && state.connected && !state.pendingHomeProjectSlug;
+  var html = '<header class="projects-header"><a class="projects-brand" href="/" data-projects-action="home"><img src="/clay-studio-symbol.png" alt="">Clay Studio</a>' +
+    '<nav aria-label="Workspace navigation">' + button('home', 'Home', 'projects-button-quiet') + button('settings', 'Settings', 'projects-button-quiet') + '</nav></header>';
+  html += '<main class="projects-main" aria-labelledby="projects-title">';
+  if (!ready) return html + '<div class="projects-loading" role="status"><h1 id="projects-title" tabindex="-1">Your projects</h1><p>Loading your workspace…</p></div></main>';
+  if (welcome) {
+    return html + '<section class="projects-welcome"><div class="projects-eyebrow">WELCOME TO CLAY</div>' +
+      '<h1 id="projects-title" tabindex="-1">A place for<br>your next idea.</h1>' +
+      '<p class="projects-lead">Bring a project. Describe what you want to build.<br>Your AI Driver helps you take it from there.</p>' +
+      '<div class="projects-intro-grid"><div><span>01 / PROJECTS</span><h2>Work on something real.</h2><p>Open a folder, start fresh, or clone a repository. Your conversations and tools stay with the project.</p></div>' +
+      '<div><span>02 / HOME</span><h2>Make room to think.</h2><p>Talk with Clay and your Mates, explore ideas, and return to your projects whenever you’re ready.</p></div></div>' +
+      '<div class="projects-welcome-actions">' + button('start', projects.length ? 'Explore your projects ' + iconHtml('arrow-right') : 'Set up your first project ' + iconHtml('arrow-right'), 'projects-button-primary') +
+      button('skip', 'Explore Home first', 'projects-button-quiet') + '</div>' +
+      '<p class="projects-footnote">You can revisit this guide from Projects at any time.</p></section></main>';
+  }
+  html += '<div class="projects-heading"><div><div class="projects-eyebrow">YOUR WORKSPACE</div><h1 id="projects-title" tabindex="-1">' + (projects.length ? 'Projects' : 'Start with a project.') + '</h1>' +
+    '<p class="projects-lead">' + (projects.length ? 'Pick up where you left off, or begin something new.' : 'Choose where your work will live. You can add more projects later.') + '</p></div>' + button('guide', 'Getting started', 'projects-button-quiet') + '</div>';
+  if (state.pendingHomeProjectSlug) html += '<p class="projects-status" role="status">Opening your project…</p>';
+  if (projects.length) {
+    html += '<div class="projects-list" aria-label="Your projects">';
+    projects.forEach(function (project) {
+      html += '<button type="button" class="projects-list-item" data-project-slug="' + escapeHtml(project.slug) + '"' + (!state.connected || state.pendingHomeProjectSlug ? ' disabled' : '') + '>' +
+        '<span class="projects-action-icon">' + iconHtml(project.isWorktree ? 'git-branch' : 'folder') + '</span><span><strong>' + escapeHtml(project.title || project.project || project.slug) + '</strong>' +
+        '<span>' + escapeHtml(project.branch || project.path || project.slug) + '</span></span>' + iconHtml('arrow-right') + '</button>';
+    });
+    html += '</div><h2 class="projects-section-title">Add a project</h2>';
+  }
+  if (!state.projectsAccessLoaded) html += '<p class="projects-status" role="status">Checking project access…</p>';
+  else if (!allowed) html += '<p class="projects-status">Ask an administrator to create or share a project with you.</p>';
+  else {
+    html += '<div class="projects-setup-actions">' +
+      setupAction('existing', 'folder-open', 'Open a folder', 'Use a directory on the machine running Clay.', !available) +
+      setupAction('create', 'plus', 'Create a project', 'Start in a new, empty project directory.', !available) +
+      setupAction('clone', 'git-branch', 'Clone a repository', 'Bring an existing Git repository into Clay.', !available) + '</div>';
+    if (!projects.length) html += '<p class="projects-next-step"><span>UP NEXT</span> Choose your AI in the workspace, then tell your Driver what you want to build or fix.</p>';
+  }
+  if (!state.connected) html += '<p class="projects-status" role="status">Reconnecting… Project actions will be available when the connection returns.</p>';
+  return html + '</main><footer class="projects-footer">Your projects, conversations, and tools. One workspace.</footer>';
+}