clay-server 5.2.0-beta.10 → 5.2.0-beta.11

package/lib/public/modules/project-start-folder-view.js

@@ -0,0 +1,190 @@
+// project-start-folder-view.js - Open-folder step: browse_dir navigation and add_project submit
+
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { escapeHtml } from './utils.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { baseName, breadcrumbSegments, initialCandidates } from './project-start-path.js';
+import {
+  beginInitial, beginNavigate, applyBrowseResult, failLocally, canOpenFolder, emptyFolderState,
+} from './project-start-folder-state.js';
+
+var seq = 0;
+var onSubmit = null;
+
+function nextId() { seq += 1; return "browse-" + seq; }
+function folder() { return store.get('projectStartFolder'); }
+function setFolder(next) { store.set({ projectStartFolder: next }); }
+function root() { return document.querySelector('#project-start-body [data-view="open"]'); }
+
+export function resetFolderState() { setFolder(emptyFolderState()); }
+
+function send(path, requestId) {
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) {
+    setFolder(failLocally(folder(), "Not connected to the server."));
+    return;
+  }
+  ws.send(JSON.stringify({ type: "browse_dir", path: path, requestId: requestId }));
+}
+
+export function startFolderBrowse() {
+  var next = beginInitial(initialCandidates(store.snap()), nextId());
+  setFolder(next);
+  send(next.requestedPath, next.requestId);
+}
+
+export function navigateTo(path) {
+  if (!path) return;
+  var next = beginNavigate(folder(), path, nextId());
+  setFolder(next);
+  send(path, next.requestId);
+}
+
+export function handleBrowseDirResult(msg) {
+  if (store.get('projectStart').view !== 'open') return;
+  var out = applyBrowseResult(folder(), msg, nextId());
+  if (out.state === folder()) return;
+  setFolder(out.state);
+  if (out.retryPath) send(out.retryPath, out.state.requestId);
+}
+
+export function folderViewHtml() {
+  return '<div class="project-start-view" data-view="open">' +
+    '<div class="project-start-location">' +
+      '<button type="button" class="project-start-icon-btn" data-ps="up" aria-label="Up one folder">' + iconHtml('arrow-up') + '</button>' +
+      '<nav class="project-start-crumbs" aria-label="Current folder"></nav>' +
+      '<button type="button" class="project-start-link-btn" data-ps="toggle-path" aria-expanded="false" aria-controls="project-start-pathform">Enter path</button>' +
+    '</div>' +
+    '<form class="project-start-pathform" id="project-start-pathform" hidden>' +
+      '<input type="text" class="project-start-input" data-ps="path-input" aria-label="Folder path" placeholder="/path/to/folder" autocomplete="off" spellcheck="false">' +
+      '<button type="submit" class="project-start-secondary">Go</button>' +
+    '</form>' +
+    '<div class="project-start-scroll project-start-list" data-ps="list" tabindex="-1" aria-live="polite"></div>' +
+    '<div class="project-start-footer">' +
+      '<p class="project-start-error" data-ps="error" role="alert" hidden></p>' +
+      '<button type="button" class="project-start-primary" data-ps="open" disabled>Open</button>' +
+    '</div></div>';
+}
+
+function stateBlock(kind, title, text, actions) {
+  return '<div class="project-start-state project-start-state-' + kind + '">' +
+    (kind === 'loading' ? '<span class="project-start-spinner" aria-hidden="true"></span>' : '') +
+    '<strong>' + escapeHtml(title) + '</strong>' + (text ? '<span>' + escapeHtml(text) + '</span>' : '') +
+    (actions || '') + '</div>';
+}
+
+function errorTitle(kind) {
+  if (kind === 'denied') return "You can't open this folder";
+  if (kind === 'missing') return "Folder not found";
+  return "Couldn't load folders";
+}
+
+function listHtml(state) {
+  if (state.status === 'loading') return stateBlock('loading', 'Loading folders…');
+  if (state.status === 'error') {
+    var actions = '<div class="project-start-state-actions">' +
+      '<button type="button" class="project-start-secondary" data-ps="retry">Try again</button>' +
+      (state.dir ? '<button type="button" class="project-start-secondary" data-ps="back-to-dir">Back to ' + escapeHtml(baseName(state.dir)) + '</button>' : '') + '</div>';
+    return stateBlock('error', errorTitle(state.errorKind), state.error, actions);
+  }
+  if (state.status !== 'ready') return '';
+  if (state.entries.length === 0) return stateBlock('empty', 'No folders here', 'This folder has no sub-folders. You can still open it.');
+  var html = '<ul class="project-start-rows" role="list">';
+  for (var i = 0; i < state.entries.length; i++) {
+    html += '<li><button type="button" class="project-start-row project-start-folder-row" data-ps="enter" data-path="' + escapeHtml(state.entries[i].path) + '">' +
+      iconHtml('folder') + '<span class="project-start-row-name">' + escapeHtml(state.entries[i].name) + '</span>' + iconHtml('chevron-right') + '</button></li>';
+  }
+  return html + '</ul>';
+}
+
+function crumbsHtml(state) {
+  if (!state.dir) return '<span class="project-start-crumb-muted">' + (state.status === 'error' ? 'No folder selected' : 'Loading…') + '</span>';
+  var info = breadcrumbSegments(state.dir, 3);
+  var html = info.truncated ? '<span class="project-start-crumb-muted">…</span><span class="project-start-crumb-sep">/</span>' : '';
+  for (var i = 0; i < info.segments.length; i++) {
+    var last = i === info.segments.length - 1;
+    html += '<span class="' + (last ? 'project-start-crumb-current' : 'project-start-crumb') + '"' + (last ? ' aria-current="location"' : '') + '>' + escapeHtml(info.segments[i]) + '</span>';
+    if (!last) html += '<span class="project-start-crumb-sep">/</span>';
+  }
+  return html;
+}
+
+export function renderFolderView() {
+  var view = root();
+  if (!view) return;
+  var state = folder();
+  var crumbs = view.querySelector('.project-start-crumbs');
+  crumbs.innerHTML = crumbsHtml(state);
+  crumbs.title = state.dir || '';
+  view.querySelector('[data-ps="up"]').disabled = !(state.status === 'ready' && state.parent);
+  var list = view.querySelector('[data-ps="list"]');
+  var listHadFocus = list.contains(document.activeElement);
+  list.innerHTML = listHtml(state);
+  if (listHadFocus) list.focus({ preventScroll: true });
+  list.setAttribute('aria-busy', state.status === 'loading' ? 'true' : 'false');
+  var pathInput = view.querySelector('[data-ps="path-input"]');
+  if (state.status === 'ready' && document.activeElement !== pathInput) pathInput.value = state.dir;
+  var submit = store.get('projectStart').submit;
+  var busy = submit.status === 'busy';
+  var open = view.querySelector('[data-ps="open"]');
+  var name = state.dir ? baseName(state.dir) : '';
+  open.innerHTML = busy ? 'Opening…' : 'Open ' + (name ? '<span class="project-start-open-name">' + escapeHtml(name) + '</span>' : 'folder');
+  open.disabled = busy || !canOpenFolder(state);
+  open.title = state.dir && canOpenFolder(state) ? state.dir : '';
+  var error = view.querySelector('[data-ps="error"]');
+  error.textContent = submit.error || '';
+  error.hidden = !submit.error;
+  refreshIcons();
+}
+
+function togglePath(view, force) {
+  var form = view.querySelector('.project-start-pathform');
+  var open = typeof force === 'boolean' ? force : form.hidden;
+  form.hidden = !open;
+  view.querySelector('[data-ps="toggle-path"]').setAttribute('aria-expanded', open ? 'true' : 'false');
+  if (open) {
+    var input = form.querySelector('input');
+    input.value = folder().dir || '';
+    input.focus();
+    input.select();
+  }
+}
+
+export function bindFolderView(submitFolder) {
+  onSubmit = submitFolder;
+  var view = root();
+  view.addEventListener('click', function (event) {
+    var target = event.target.closest('[data-ps]');
+    if (!target || target.disabled) return;
+    var action = target.dataset.ps;
+    var state = folder();
+    if (action === 'up' && state.parent) navigateTo(state.parent);
+    else if (action === 'enter') navigateTo(target.dataset.path);
+    else if (action === 'retry') navigateTo(state.requestedPath);
+    else if (action === 'back-to-dir') navigateTo(state.dir);
+    else if (action === 'toggle-path') togglePath(view);
+    else if (action === 'open' && canOpenFolder(state) && onSubmit) onSubmit(state.dir);
+  });
+  view.querySelector('.project-start-pathform').addEventListener('submit', function (event) {
+    event.preventDefault();
+    var value = view.querySelector('[data-ps="path-input"]').value.trim();
+    if (value) navigateTo(value);
+  });
+  view.addEventListener('keydown', function (event) {
+    if (event.key === 'Escape' && !view.querySelector('.project-start-pathform').hidden) {
+      event.stopPropagation();
+      togglePath(view, false);
+      view.querySelector('[data-ps="toggle-path"]').focus();
+      return;
+    }
+    var rows = view.querySelectorAll('[data-ps="enter"]');
+    var index = Array.prototype.indexOf.call(rows, document.activeElement);
+    if (index < 0 || !rows.length) return;
+    var key = event.key;
+    if (key !== 'ArrowDown' && key !== 'ArrowUp' && key !== 'Home' && key !== 'End') return;
+    event.preventDefault();
+    var next = key === 'Home' ? 0 : key === 'End' ? rows.length - 1 : Math.max(0, Math.min(rows.length - 1, index + (key === 'ArrowDown' ? 1 : -1)));
+    rows[next].focus();
+  });
+}

package/lib/public/modules/project-start-forms.js

@@ -0,0 +1,66 @@
+// project-start-forms.js - Create and clone steps (name or URL only)
+
+import { store } from './store.js';
+import { escapeHtml } from './utils.js';
+import { submitCreate, submitClone } from './project-start-submit.js';
+
+var FORMS = {
+  create: {
+    label: 'Project name', field: 'name', placeholder: 'my-project', action: 'Create project', busy: 'Creating…',
+    hint: 'Letters, numbers, dashes and underscores.', submit: submitCreate,
+  },
+  clone: {
+    label: 'GitHub repository URL', field: 'url', placeholder: 'https://github.com/user/repo', action: 'Clone repository', busy: 'Cloning…',
+    hint: 'Paste the repository address to bring it into Clay.', submit: submitClone,
+  },
+};
+
+export function formViewHtml(kind) {
+  var form = FORMS[kind];
+  return '<form class="project-start-view" data-view="' + kind + '" novalidate>' +
+    '<div class="project-start-scroll project-start-formbody">' +
+      '<label class="project-start-label" for="project-start-field">' + form.label + '</label>' +
+      '<input type="text" id="project-start-field" class="project-start-input" data-ps="field" placeholder="' + form.placeholder + '" autocomplete="off" spellcheck="false" aria-describedby="project-start-hint">' +
+      '<p class="project-start-hint" id="project-start-hint">' + form.hint + '</p>' +
+      '<p class="project-start-progress" data-ps="progress" role="status" hidden><span class="project-start-spinner" aria-hidden="true"></span>Cloning repository…</p>' +
+      '<p class="project-start-error" data-ps="error" role="alert" hidden></p>' +
+    '</div>' +
+    '<div class="project-start-footer"><button type="submit" class="project-start-primary" data-ps="submit">' + escapeHtml(form.action) + '</button></div>' +
+  '</form>';
+}
+
+function root(kind) { return document.querySelector('#project-start-body [data-view="' + kind + '"]'); }
+
+export function renderFormView(kind) {
+  var view = root(kind);
+  if (!view) return;
+  var form = FORMS[kind];
+  var current = store.get('projectStart');
+  var submit = current.submit;
+  var busy = submit.status === 'busy';
+  var field = view.querySelector('[data-ps="field"]');
+  if (field.value !== current[form.field]) field.value = current[form.field];
+  field.readOnly = busy;
+  var button = view.querySelector('[data-ps="submit"]');
+  button.disabled = busy;
+  button.textContent = busy ? form.busy : form.action;
+  view.querySelector('[data-ps="progress"]').hidden = !(busy && kind === 'clone' && submit.cloning);
+  var error = view.querySelector('[data-ps="error"]');
+  error.textContent = submit.error || '';
+  error.hidden = !submit.error;
+  view.setAttribute('aria-busy', busy ? 'true' : 'false');
+}
+
+export function bindFormView(kind) {
+  var view = root(kind);
+  var form = FORMS[kind];
+  view.querySelector('[data-ps="field"]').addEventListener('input', function (event) {
+    var patch = {};
+    patch[form.field] = event.target.value;
+    store.set({ projectStart: Object.assign({}, store.get('projectStart'), patch) });
+  });
+  view.addEventListener('submit', function (event) {
+    event.preventDefault();
+    form.submit();
+  });
+}

package/lib/public/modules/project-start-path.js

@@ -0,0 +1,60 @@
+// project-start-path.js - Pure path helpers for the project-start dialog (no DOM, no store)
+
+function trimTrailing(p) {
+  var out = String(p || "");
+  while (out.length > 1 && /[\\/]$/.test(out) && !/^[A-Za-z]:[\\/]$/.test(out)) out = out.slice(0, -1);
+  return out;
+}
+
+export function baseName(dir) {
+  var p = trimTrailing(dir);
+  if (p === "/" || /^[A-Za-z]:[\\/]$/.test(p)) return p;
+  var parts = p.split(/[\\/]/);
+  return parts[parts.length - 1] || p;
+}
+
+export function parentOf(dir) {
+  var p = trimTrailing(dir);
+  var idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+  if (idx < 0) return null;
+  if (idx === 0) return p.length > 1 ? "/" : null;
+  if (/^[A-Za-z]:$/.test(p.slice(0, idx))) return p.slice(0, idx + 1);
+  return p.slice(0, idx);
+}
+
+// Last `max` segments of a directory, with a flag when earlier segments are hidden.
+export function breadcrumbSegments(dir, max) {
+  var p = trimTrailing(dir);
+  var limit = max || 3;
+  var parts = p.split(/[\\/]/).filter(function (part) { return part.length > 0; });
+  if (parts.length === 0) return { truncated: false, segments: [p || "/"] };
+  return { truncated: parts.length > limit, segments: parts.slice(-limit) };
+}
+
+function ordinaryProjectParent(state) {
+  var projects = Array.isArray(state.projectsHubList) ? state.projectsHubList : [];
+  for (var i = 0; i < projects.length; i++) {
+    var project = projects[i];
+    if (project && project.slug === state.currentSlug && !project.isMate && typeof project.path === "string" && project.path) {
+      return parentOf(project.path);
+    }
+  }
+  return null;
+}
+
+// Ordered starting directories to try. Each one is only a request; the server decides whether
+// the signed-in user may list it, and the next candidate is tried when it cannot.
+export function initialCandidates(state) {
+  var out = [];
+  var users = Array.isArray(state.cachedAllUsers) ? state.cachedAllUsers : [];
+  var me = null;
+  for (var i = 0; i < users.length; i++) if (users[i].id === state.myUserId) me = users[i];
+  if (state.isOsUsers && me && me.role !== "admin" && me.linuxUser) {
+    out.push("/home/" + me.linuxUser);
+    return out;
+  }
+  var near = ordinaryProjectParent(state);
+  if (near) out.push(near);
+  out.push("~");
+  return out;
+}

package/lib/public/modules/project-start-state.js

@@ -0,0 +1,54 @@
+// project-start-state.js - Pure state transitions for the project-start dialog
+
+var VIEWS = { choices: true, open: true, create: true, clone: true };
+
+export function idleSubmit() {
+  return { status: 'idle', kind: null, requestId: null, error: null, cloning: false };
+}
+
+export function initialProjectStart() {
+  return { view: null, gen: 0, name: '', url: '', submit: idleSubmit() };
+}
+
+// Deep links: "existing" lands on the folder step, "create"/"clone" on theirs, anything else on the choices.
+export function viewForMode(mode) {
+  if (mode === 'existing') return 'open';
+  return mode === 'create' || mode === 'clone' ? mode : 'choices';
+}
+
+export function openState(prev, mode) {
+  return { view: viewForMode(mode), gen: prev.gen + 1, name: '', url: '', submit: idleSubmit() };
+}
+
+export function closeState(prev) {
+  return { view: null, gen: prev.gen + 1, name: '', url: '', submit: idleSubmit() };
+}
+
+export function selectView(prev, view) {
+  if (!VIEWS[view] || prev.view === null) return prev;
+  return { view: view, gen: prev.gen + 1, name: '', url: '', submit: idleSubmit() };
+}
+
+export function beginSubmit(prev, kind, requestId) {
+  if (prev.view === null || prev.submit.status === 'busy') return prev;
+  return Object.assign({}, prev, { submit: { status: 'busy', kind: kind, requestId: requestId, error: null, cloning: false } });
+}
+
+export function applyProgress(prev, msg) {
+  var s = prev.submit;
+  if (s.status !== 'busy' || s.kind !== 'clone' || !msg || msg.status !== 'cloning' || s.cloning || typeof msg.requestId !== 'string' || msg.requestId !== s.requestId) return prev;
+  return Object.assign({}, prev, { submit: Object.assign({}, s, { cloning: true }) });
+}
+
+// outcome: 'success' | 'error' for the submission this dialog is waiting on,
+// 'orphan' for any other reply (the dialog was closed or moved on), which never touches the dialog.
+export function resolveSubmit(prev, msg) {
+  var s = prev.submit;
+  var matches = prev.view !== null && s.status === 'busy' && msg && typeof msg.requestId === 'string' && msg.requestId === s.requestId;
+  if (!matches) return { state: prev, outcome: 'orphan', kind: null };
+  if (msg.ok) return { state: closeState(prev), outcome: 'success', kind: s.kind };
+  return {
+    state: Object.assign({}, prev, { submit: Object.assign({}, idleSubmit(), { error: msg.error || 'Could not add this project.' }) }),
+    outcome: 'error', kind: s.kind,
+  };
+}

package/lib/public/modules/project-start-submit.js

@@ -0,0 +1,67 @@
+// project-start-submit.js - add_project / create_project / clone_project requests and replies
+
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { showToast } from './utils.js';
+import { switchProject } from './app-projects.js';
+import { beginSubmit, applyProgress, resolveSubmit, idleSubmit } from './project-start-state.js';
+
+var seq = 0;
+
+function state() { return store.get('projectStart'); }
+function setState(next) { store.set({ projectStart: next }); }
+
+function failSubmit(message) {
+  var current = state();
+  setState(Object.assign({}, current, { submit: Object.assign({}, idleSubmit(), { error: message }) }));
+}
+
+function submit(kind, payload) {
+  var begun = beginSubmit(state(), kind, 'start-' + (seq += 1));
+  if (begun === state()) return;
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) {
+    setState(begun);
+    failSubmit('Not connected to the server.');
+    return;
+  }
+  setState(begun);
+  ws.send(JSON.stringify(Object.assign({ requestId: begun.submit.requestId }, payload)));
+}
+
+export function submitFolder(dir) {
+  if (typeof dir !== 'string' || !dir) return;
+  submit('open', { type: 'add_project', path: dir });
+}
+
+export function submitCreate() {
+  var name = state().name.trim();
+  if (name) submit('create', { type: 'create_project', name: name });
+}
+
+export function submitClone() {
+  var url = state().url.trim();
+  if (url) submit('clone', { type: 'clone_project', url: url });
+}
+
+export function handleCloneProgress(msg) {
+  var next = applyProgress(state(), msg);
+  if (next !== state()) setState(next);
+}
+
+var SUCCESS_TOASTS = { open: 'Project added', create: 'Project created', clone: 'Project cloned' };
+
+export function handleAddProjectResult(msg) {
+  var out = resolveSubmit(state(), msg);
+  if (out.outcome === 'orphan') {
+    // The dialog was closed or moved on; report the outcome without touching or reopening it.
+    if (msg.ok) showToast(msg.existing ? 'Project already registered' : 'Project added', msg.existing ? 'info' : 'success');
+    else showToast(msg.error || 'Failed to add project', 'error');
+    return;
+  }
+  setState(out.state);
+  if (out.outcome === 'success') {
+    showToast(msg.existing ? 'Project already registered' : SUCCESS_TOASTS[out.kind], msg.existing ? 'info' : 'success');
+    if (msg.slug) switchProject(msg.slug);
+  }
+}

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

@@ -7,8 +7,25 @@ export function ordinaryProjects(projects) {
   });
 }
 
-function button(action, label, extra) {
-  return '<button type="button" class="projects-button ' + (extra || '') + '" data-projects-action="' + action + '">' + label + '</button>';
+// Zero ordinary projects (once the list is known): the welcome renders inside the normal app shell.
+export function isShellWelcome(state) {
+  return !!state.projectListLoaded && ordinaryProjects(state.projectsHubList).length === 0;
+}
+
+function button(action, label, extra, disabled) {
+  return '<button type="button" class="projects-button ' + (extra || '') + '" data-projects-action="' + action + '"' + (disabled ? ' disabled' : '') + '>' + label + '</button>';
+}
+
+// Mate creation starts with the built-in Clay Mate, so the CTA waits until it is in the loaded Mate list.
+export function clayMateReady(state) {
+  var mates = Array.isArray(state.cachedMatesList) ? state.cachedMatesList : [];
+  for (var i = 0; i < mates.length; i++) if (mates[i] && mates[i].builtinKey === 'clay') return true;
+  return false;
+}
+
+function welcomeCard(label, title, text, action, artwork) {
+  return '<div class="projects-intro-card"><div class="projects-intro-art"><img src="/welcome-art/' + artwork + '.png" width="1536" height="1024" alt="" decoding="async"></div>' +
+    '<span class="projects-intro-label">' + label + '</span><h2>' + title + '</h2><p>' + text + '</p><div class="projects-intro-action">' + action + '</div></div>';
 }
 
 function setupAction(mode, icon, title, text, disabled) {
@@ -19,24 +36,27 @@ function setupAction(mode, icon, title, text, disabled) {
 export function projectsHubContent(state) {
   var projects = ordinaryProjects(state.projectsHubList);
   var ready = state.projectListLoaded;
-  var welcome = ready && (state.projectsShowGuide || (!projects.length && (state.onboardingStep || 'welcome') === 'welcome'));
+  var welcome = ready && (state.projectsShowGuide || !projects.length);
   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="/projects"><img src="/clay-studio-symbol.png" alt="">Clay Studio</a>' +
+  var html = isShellWelcome(state) ? '' : '<header class="projects-header"><a class="projects-brand" href="/projects"><img src="/clay-studio-symbol.png" alt="">Clay Studio</a>' +
     '<nav aria-label="Workspace navigation">' + 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 / MATES</span><h2>Bring in the right perspective.</h2><p>Your Mates live beside projects and open their conversations in the same focused workspace.</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') + '</div>' +
-      '<p class="projects-footnote">You can revisit this guide from Projects at any time.</p></section></main>';
+    var mateReady = !!state.connected && clayMateReady(state);
+    return html + '<section class="projects-welcome"><div class="projects-eyebrow">WELCOME TO</div>' +
+      '<h1 id="projects-title" tabindex="-1"><span class="projects-wordmark" role="img" aria-label="Clay Studio"></span></h1>' +
+      '<p class="projects-lead">Where the minds work together</p>' +
+      '<div class="projects-intro-grid">' +
+      welcomeCard('01 / PROJECTS', 'Work together on a project.', 'Bring a codebase or a folder of files, and work through it together with Clay Studio.',
+        button(projects.length ? 'start' : 'create-project', projects.length ? 'Explore your projects ' + iconHtml('arrow-right') : 'Start a project ' + iconHtml('arrow-right'), 'projects-button-primary', !projects.length && !available), 'project-clay') +
+      welcomeCard('02 / MATES', 'Create your own specialist.', 'Create a Mate with the expertise you need, and work together on your ideas and tasks.',
+        button('mate', 'Create a Mate ' + iconHtml('arrow-right'), 'projects-button-secondary', !mateReady), 'mate-clay') +
+      '</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>';
+  html += '<div class="projects-heading"><div><div class="projects-eyebrow">YOUR WORKSPACE</div><h1 id="projects-title" tabindex="-1">Projects</h1>' +
+    '<p class="projects-lead">Pick up where you left off, or begin something new.</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">';
@@ -54,7 +74,6 @@ export function projectsHubContent(state) {
       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>';

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

@@ -1,9 +1,11 @@
 import { store } from './store.js';
 import { getWs } from './ws-ref.js';
-import { openAddProjectModal, switchProject } from './app-projects.js';
+import { switchProject } from './app-projects.js';
+import { openAddProjectModal } from './project-start-dialog.js';
+import { startClayMateCreation } from './project-mate-creation-workspace.js';
 import { openUserSettings } from './user-settings.js';
 import { rememberHomePrimarySurface, updateHomeSurfacePreference } from './home-surface.js';
-import { projectsHubContent } from './projects-hub-view.js';
+import { projectsHubContent, isShellWelcome, clayMateReady } from './projects-hub-view.js';
 import { refreshIcons } from './icons.js';
 
 function root() { return document.getElementById('projects-hub'); }
@@ -11,6 +13,7 @@ function root() { return document.getElementById('projects-hub'); }
 function render() {
   var element = root();
   if (!element || !store.get('projectsHubVisible')) return;
+  document.body.classList.toggle('projects-shell', isShellWelcome(store.snap()));
   var html = projectsHubContent(store.snap());
   if (store.get('projectsHubMarkup') === html) return;
   store.set({ projectsHubMarkup: html });
@@ -51,7 +54,7 @@ export function showProjectsHub(fromHistory) {
 export function hideProjectsHub() {
   if (!store.get('projectsHubVisible')) return;
   store.set({ projectsHubVisible: false, projectsShowGuide: false });
-  document.body.classList.remove('projects-active');
+  document.body.classList.remove('projects-active', 'projects-shell');
   if (root()) root().classList.add('hidden');
 }
 
@@ -75,10 +78,11 @@ function handleClick(event) {
   }
   var ws = getWs();
   if (!ws || ws.readyState !== 1) return;
+  if (action === 'mate') { if (clayMateReady(store.snap())) startClayMateCreation(); return; }
   if (button.dataset.projectSlug) { switchProject(button.dataset.projectSlug); return; }
-  if (button.dataset.projectsMode) {
+  if (action === 'create-project' || button.dataset.projectsMode) {
     var permissions = store.get('permissions');
-    if (!store.get('projectsAccessLoaded') || (permissions && permissions.createProject !== true)) return;
+    if (!store.get('projectsAccessLoaded') || store.get('pendingHomeProjectSlug') || (permissions && permissions.createProject !== true)) return;
     openAddProjectModal(button.dataset.projectsMode);
   }
 }
@@ -96,6 +100,6 @@ export function initProjectsHub() {
     if (state.projectsHubList !== previous.projectsHubList || state.projectListLoaded !== previous.projectListLoaded ||
         state.homeSurfaceLoaded !== previous.homeSurfaceLoaded || state.onboardingStep !== previous.onboardingStep ||
         state.projectsAccessLoaded !== previous.projectsAccessLoaded || state.permissions !== previous.permissions ||
-        state.connected !== previous.connected || state.pendingHomeProjectSlug !== previous.pendingHomeProjectSlug) render();
+        state.connected !== previous.connected || state.cachedMatesList !== previous.cachedMatesList || state.pendingHomeProjectSlug !== previous.pendingHomeProjectSlug) render();
   });
 }