@floless/app 0.54.1 → 0.55.0

package/dist/floless-server.cjs

@@ -52856,7 +52856,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.54.1" : void 0,
+    define: true ? "0.55.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52866,7 +52866,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.54.1" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.55.0" : void 0 });
 }
 
 // workflow-update.ts
@@ -63876,6 +63876,13 @@ async function startServer() {
     broadcast({ type: "request-added", request });
     return { ok: true, request };
   });
+  app.post("/api/guide", async (req, reply) => {
+    const { appId } = req.body ?? {};
+    if (!appId) return reply.status(400).send({ ok: false, error: "appId required" });
+    const request = addRequest({ type: "guide", appId });
+    broadcast({ type: "request-added", request });
+    return { ok: true, request };
+  });
   app.delete("/api/requests/:id", async (req, reply) => {
     if (!deleteRequest(req.params.id)) return reply.status(404).send({ ok: false, error: "request not found" });
     broadcast({ type: "requests-changed" });

package/dist/web/app.css

@@ -479,6 +479,152 @@
   .onb-tour-btn:disabled { cursor: default; opacity: 0.85; box-shadow: none; }
   .onb-tour-ico { font-size: 11px; opacity: 0.7; margin-left: 6px; }
 
+  /* ===== Per-workflow onboarding beacon ("Start here") ===== */
+  /* A header pill in the run cluster. Calm by default (accent-soft, like the
+     wf-update pill); pulses while the open workflow is new to the user. Accent —
+     NOT warn — because it's positive/new, and warn is already the drift colour. */
+  .guide-beacon {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    border: 1px solid var(--accent-dim);
+    background: var(--accent-soft);
+    color: var(--accent-bright);
+    font-family: var(--ui);
+    font-size: 11px;
+    letter-spacing: 0.02em;
+    padding: 3px 11px;
+    border-radius: 999px;
+    cursor: pointer;
+    white-space: nowrap;
+    flex-shrink: 0; /* the workflow picker shrinks first; the beacon never squashes */
+    transition: border-color 0.15s, color 0.15s, background 0.15s;
+  }
+  .guide-beacon[hidden] { display: none; }
+  .guide-beacon:hover { border-color: var(--accent); color: var(--accent); }
+  .guide-beacon:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+  .guide-beacon-ico { font-size: 11px; line-height: 1; }
+  /* "New to you": a slow box-shadow bloom (GPU-composited, no layout repaint) reading
+     as a calm invitation, not an alarm. Same motion dialect as the rest of the app. */
+  .guide-beacon.is-new {
+    border-color: var(--accent);
+    color: var(--accent-bright);
+    animation: guide-pulse 2.8s ease-in-out infinite;
+  }
+  @keyframes guide-pulse {
+    0%, 100% { box-shadow: 0 0 0 0 var(--accent-glow); }
+    50%      { box-shadow: 0 0 0 6px rgba(74, 158, 255, 0); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    /* No pulse — a steady ring (shape + contrast, not colour alone) marks "new". */
+    .guide-beacon.is-new { animation: none; box-shadow: 0 0 0 1px var(--accent-dim); }
+  }
+  /* Spotlit (first-open): raised above the dim, opaque, ringed. The header creates no
+     stacking context, so z-index here lifts it above the fixed spotlight overlay. */
+  .guide-beacon.spotlit {
+    position: relative;
+    z-index: 95;
+    animation: none;
+    background: var(--surface-3);
+    border-color: var(--accent);
+    color: var(--accent-bright);
+    box-shadow: 0 0 0 3px var(--accent-glow), 0 0 20px 4px var(--accent-glow);
+  }
+
+  /* ===== First-open spotlight ===== */
+  .guide-spotlight {
+    position: fixed;
+    inset: 0;
+    z-index: 90; /* below modals (100), above the page; the beacon (.spotlit, 95) sits over it */
+    background: rgba(7, 10, 15, 0.72);
+    backdrop-filter: blur(2px);
+    -webkit-backdrop-filter: blur(2px);
+    display: none;
+  }
+  .guide-spotlight:not([hidden]) { display: block; animation: fade-in 0.18s ease-out; }
+  .guide-spotlight-bubble {
+    position: fixed;
+    z-index: 91;
+    max-width: 280px;
+    background: var(--surface);
+    border: 1px solid var(--accent-dim);
+    border-radius: 8px;
+    padding: 12px 14px;
+    box-shadow: 0 16px 48px rgba(0, 0, 0, 0.5);
+  }
+  .guide-spotlight-text { font-size: 12.5px; line-height: 1.5; color: var(--text); }
+  .guide-spotlight-text strong { color: var(--accent-bright); }
+  .guide-spotlight-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 11px; }
+  .guide-spotlight-actions button { padding: 5px 13px; font-size: 12px; }
+  .guide-spotlight-actions .ghost { background: var(--surface-2); color: var(--text-muted); }
+  .guide-spotlight-actions .ghost:hover { color: var(--text); border-color: var(--accent-dim); }
+  .guide-spotlight-actions .primary { background: var(--accent); color: #fff; border-color: var(--accent); font-weight: 600; }
+  .guide-spotlight-actions .primary:hover { background: var(--accent-bright); box-shadow: 0 0 14px var(--accent-glow); }
+
+  /* ===== Guide panel (modal) ===== */
+  .modal.guide {
+    width: 520px;
+    max-width: 92vw;
+    max-height: 82vh;
+    display: flex;
+    flex-direction: column;
+  }
+  .guide-eyebrow {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.16em;
+    color: var(--accent-bright);
+    margin-bottom: 6px;
+  }
+  /* The body scrolls between the pinned title and the pinned actions; theme its
+     scrollbar so no native white bar leaks against the dark surface. */
+  #guide-body {
+    overflow-y: auto;
+    flex: 1 1 auto;
+    min-height: 0;
+    margin-top: 2px;
+    scrollbar-width: thin;
+    scrollbar-color: var(--border-strong) transparent;
+  }
+  #guide-body::-webkit-scrollbar { width: 7px; }
+  #guide-body::-webkit-scrollbar-thumb { background: var(--border-strong); border-radius: 7px; }
+  #guide-body::-webkit-scrollbar-track { background: transparent; }
+  .guide-section-label {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.14em;
+    color: var(--text-muted);
+    margin: 14px 0 7px;
+  }
+  .guide-section-label:first-child { margin-top: 2px; }
+  .guide-desc { font-size: 12.5px; line-height: 1.55; color: var(--text); }
+  .guide-desc p { margin: 0 0 8px; }
+  .guide-desc p:last-child { margin-bottom: 0; }
+  .guide-desc code { font-family: var(--mono); background: var(--surface-2); padding: 1px 5px; border-radius: 3px; color: var(--text-muted); font-size: 11px; }
+  .guide-desc-empty { color: var(--text-muted); font-style: italic; }
+  .guide-steps { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 9px; }
+  .guide-step { display: flex; gap: 10px; align-items: baseline; }
+  .guide-box { font-family: var(--mono); font-size: 13px; min-width: 16px; color: var(--text-dim); line-height: 1.3; }
+  .guide-step-label { font-size: 12.5px; color: var(--text); }
+  .guide-step-note { font-size: 11px; color: var(--text-dim); font-style: italic; }
+  /* Done: ✓ in ok-green + struck/dimmed label, so the current step stands out on
+     shape + contrast, not colour alone. Current: → in accent + bold label. */
+  .guide-step.done .guide-box { color: var(--ok); }
+  .guide-step.done .guide-step-label { color: var(--text-dim); text-decoration: line-through; text-decoration-color: var(--text-dim); }
+  .guide-step.current .guide-box { color: var(--accent); }
+  .guide-step.current .guide-step-label { color: var(--text); font-weight: 600; }
+  .guide-walk-hint {
+    font-size: 11px;
+    line-height: 1.5;
+    color: var(--text-muted);
+    margin-top: 14px;
+    padding-top: 12px;
+    border-top: 1px solid var(--border);
+  }
+  .guide-walk-hint strong { color: var(--text); font-weight: 600; }
+  .modal.guide .modal-actions { margin-top: 16px; }
+  .modal.guide .modal-actions #guide-got-it { margin-right: auto; }
+
   .agent-card {
     background: var(--surface);
     border: 1px solid var(--border-strong);

package/dist/web/aware.js

@@ -531,11 +531,193 @@
     });
   }
 
+  // ── Per-workflow onboarding beacon ──────────────────────────────────────────
+  // "New to you" = the user hasn't completed a first real Run of this workflow and
+  // hasn't dismissed its guide. Three bits per app id, persisted per origin; all
+  // default false, so every workflow starts new. Never touches the .flo or lock.
+  const LS_GUIDE = 'floless:guide';
+  function guideStateAll() {
+    try { const v = JSON.parse(localStorage.getItem(LS_GUIDE) || '{}'); return (v && typeof v === 'object') ? v : {}; }
+    catch { return {}; }
+  }
+  function guideFor(id) { return guideStateAll()[id] || {}; }
+  function setGuide(id, patch) {
+    if (!id) return;
+    try {
+      const all = guideStateAll();
+      all[id] = { ...(all[id] || {}), ...patch };
+      localStorage.setItem(LS_GUIDE, JSON.stringify(all));
+    } catch { /* private mode / quota */ }
+  }
+  // The beacon pulses while a workflow is new to the user.
+  function beaconIsNew(id) { const g = guideFor(id); return !g.firstRunDone && !g.dismissed; }
+
+  function paintBeacon(app) {
+    const $b = document.getElementById('guide-beacon');
+    if (!$b) return;
+    if (!app) { $b.hidden = true; $b.classList.remove('is-new', 'spotlit'); return; }
+    const isNew = beaconIsNew(app.id);
+    $b.hidden = false;
+    $b.classList.toggle('is-new', isNew);
+    const ico = $b.querySelector('.guide-beacon-ico');
+    const label = $b.querySelector('.guide-beacon-label');
+    // Monochrome dingbats (✦ / ?), not colour emoji — the locked baseline uses text
+    // glyphs (★, ▸); the pulse, not an emoji, is the "new" signal.
+    if (ico) ico.textContent = isNew ? '✦' : '?';
+    if (label) label.textContent = isNew ? 'Start here' : 'Guide';
+    $b.dataset.tip = isNew
+      ? 'New here? See what this workflow does and how to run it.'
+      : 'Open the guide for this workflow.';
+    $b.setAttribute('aria-label', (isNew ? 'Start here — guide for ' : 'Guide for ') + (app.displayName || app.id));
+  }
+
+  // Record a completed real run → the workflow is no longer new; calm the beacon (and
+  // refresh an open guide so the Run step ticks). Idempotent.
+  function markFirstRunDone(id) {
+    if (!id || guideFor(id).firstRunDone) return;
+    setGuide(id, { firstRunDone: true });
+    if (id === currentId) {
+      const app = apps.get(id);
+      if (app) paintBeacon(app);
+      const $m = document.getElementById('guide-modal');
+      if ($m && $m.classList.contains('show')) renderGuide();
+    }
+  }
+
+  // The guide panel's live checklist — each step ticks from real app state. The
+  // "Set inputs" row is omitted for a workflow with no declared inputs.
+  function guideSteps(app) {
+    const steps = [];
+    if (Array.isArray(app.inputs) && app.inputs.length) {
+      const vals = currentInputs();
+      const allSet = app.inputs.every((i) => {
+        const v = vals[i.name];
+        return v !== undefined && v !== null && String(v).trim() !== '';
+      });
+      steps.push({ label: 'Set inputs', note: 'the values this workflow runs with', done: allSet });
+    }
+    steps.push({ label: 'Compile', note: 'freeze the approved lock', done: app.runState === 'ready' });
+    steps.push({ label: 'Run', note: 'against the live host — results render here', done: !!guideFor(app.id).firstRunDone });
+    return steps;
+  }
+
+  function renderGuide() {
+    const app = currentId && apps.get(currentId);
+    const $body = document.getElementById('guide-body');
+    const $title = document.getElementById('guide-title');
+    const $eyebrow = document.getElementById('guide-eyebrow');
+    if (!app || !$body) return;
+    if ($title) $title.textContent = app.displayName || app.id;
+    if ($eyebrow) $eyebrow.textContent = beaconIsNew(app.id) ? '✦ Start here' : '✦ Workflow guide';
+    const desc = (app.description || '').trim();
+    const descHtml = desc
+      ? `<div class="guide-desc">${desc.split(/\n{2,}/).map((p) => `<p>${mdInline(escapeHtml(p.trim()))}</p>`).join('')}</div>`
+      : `<div class="guide-desc guide-desc-empty"><p>A ${app.nodes.length}-step workflow. Set its inputs, Compile to freeze the approved lock, then Run it against your live host.</p></div>`;
+    const steps = guideSteps(app);
+    const curIdx = steps.findIndex((s) => !s.done);
+    const stepsHtml = `<ol class="guide-steps" role="list">${steps.map((s, i) => {
+      const state = s.done ? 'done' : i === curIdx ? 'current' : 'todo';
+      // Shape carries state, not colour alone: ✓ done · → current · ☐ to-do.
+      const box = s.done ? '✓' : i === curIdx ? '→' : '☐';
+      const cur = i === curIdx ? ' aria-current="step"' : '';
+      return `<li class="guide-step ${state}"${cur}><span class="guide-box" aria-hidden="true">${box}</span>` +
+        `<span class="guide-step-text"><span class="guide-step-label">${escapeHtml(s.label)}</span> ` +
+        `<span class="guide-step-note">— ${escapeHtml(s.note)}</span></span>` +
+        `<span class="sr-only">${s.done ? '(done)' : i === curIdx ? '(next step)' : '(to do)'}</span></li>`;
+    }).join('')}</ol>`;
+    const walkHint = `<div class="guide-walk-hint">A bigger workflow? <strong>Walk me through it</strong> hands off to your terminal AI for a step-by-step tour using this workflow's own skill.</div>`;
+    $body.innerHTML =
+      `<div class="guide-section-label">What this does</div>` + descHtml +
+      `<div class="guide-section-label">How to go through it</div>` + stepsHtml + walkHint;
+  }
+
+  function openGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    renderGuide();
+    const $m = document.getElementById('guide-modal');
+    showModal($m);
+    // Focus the dialog shell (not a button) so the checklist is read first; Tab then
+    // moves to Got it → Walk me through it. Focus returns to the beacon on close.
+    const shell = $m && $m.querySelector('.modal.guide');
+    if (shell) { try { shell.focus(); } catch { /* not focusable */ } }
+  }
+  // Closing the guide (Got it / backdrop / Esc) marks it seen → the beacon stops
+  // pulsing even before a first run (the user has looked; don't nag).
+  function closeGuide() {
+    if (currentId) {
+      setGuide(currentId, { dismissed: true });
+      const app = apps.get(currentId);
+      if (app) paintBeacon(app);
+    }
+    hideModal(document.getElementById('guide-modal'));
+    const $b = document.getElementById('guide-beacon');
+    if ($b && !$b.hidden) { try { $b.focus(); } catch { /* */ } }
+  }
+
+  // "Walk me through it" → relay the ask to the terminal AI, the house way: queue a
+  // request AND copy the prompt, toast, light the footer requests pill, list it in the
+  // Requests window. The UI never guides itself; it hands intent to the assistant.
+  async function requestGuide() {
+    if (!currentId) { showToast('open a workflow first', 'warn'); return; }
+    try {
+      const { request } = await api('/api/guide', { method: 'POST', body: JSON.stringify({ appId: currentId }) });
+      const copied = await copyToClipboard(markedInstruction(request));
+      showToast(copied ? 'Sent to your assistant · copied to clipboard' : 'Sent to your assistant', 'ok');
+      appendNarration(`Asked your terminal AI to walk you through <code>${escapeHtml(currentId)}</code> — watch the glowing <strong>requests</strong> pill (bottom-right), or switch to your terminal.${copied ? ' The prompt is also on your clipboard.' : ''}`);
+      loadRequests();
+      closeGuide(); // engaging with the guidance also calms the beacon
+    } catch (e) { reportErr(e); }
+  }
+
+  // ── First-open spotlight (one-time per workflow) ────────────────────────────
+  // Dims the canvas, raises the beacon, and points a small caption at it; Esc /
+  // click-away / either button dismiss it for good. Slice 2 of the onboarding beacon.
+  let _spotlightKey = null;
+  function maybeSpotlight(app) {
+    if (!app) return;
+    const g = guideFor(app.id);
+    if (g.spotlightShown || g.dismissed || g.firstRunDone) return;
+    if (document.querySelector('.modal-backdrop.show')) return; // don't pile on a dialog
+    if ($contractEditor && !$contractEditor.hidden) return;
+    setTimeout(() => {
+      if (currentId !== app.id) return; // switched away during the delay
+      if (guideFor(app.id).spotlightShown) return;
+      if (document.querySelector('.modal-backdrop.show')) return;
+      showSpotlight(app);
+    }, 700);
+  }
+  function showSpotlight(app) {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if (!$sp || !$b || $b.hidden) return;
+    setGuide(app.id, { spotlightShown: true });
+    $b.classList.add('spotlit');
+    $sp.hidden = false;
+    // Anchor the caption bubble just under the beacon, right-aligned to it.
+    const bubble = $sp.querySelector('.guide-spotlight-bubble');
+    if (bubble) {
+      const r = $b.getBoundingClientRect();
+      bubble.style.top = (r.bottom + 10) + 'px';
+      bubble.style.right = Math.max(8, window.innerWidth - r.right) + 'px';
+    }
+    _spotlightKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); hideSpotlight(); } };
+    document.addEventListener('keydown', _spotlightKey);
+    if (bubble) { try { bubble.focus(); } catch { /* */ } }
+  }
+  function hideSpotlight() {
+    const $sp = document.getElementById('guide-spotlight');
+    const $b = document.getElementById('guide-beacon');
+    if ($sp) $sp.hidden = true;
+    if ($b) $b.classList.remove('spotlit');
+    if (_spotlightKey) { document.removeEventListener('keydown', _spotlightKey); _spotlightKey = null; }
+  }
+
   // ── load / select / compile / run ───────────────────────────────────────────
 
   let _wfUpdates = []; // workflow updates available, keyed by app id — polled by refreshWorkflowUpdates() below
 
   async function loadApp(id) {
+    hideSpotlight(); // a spotlight pointing at the previous app's beacon must clear on switch
     const { app } = await api(`/api/app/${encodeURIComponent(id)}`);
     apps.set(id, app);
     currentId = id;
@@ -555,8 +737,10 @@
     seedAppInputs(app);
     markSpecialNodes();
     paintGate(app);
+    paintBeacon(app); // pulse "Start here" while this workflow is new to the user
     refreshDirtyIndicator(); // clean app → dot off; switched back to a dirty one → dot on
     renderWfUpdatePill(); // show the "↑ Update to vX" pill when THIS app has a newer published version
+    maybeSpotlight(app); // one-time first-open spotlight pointing at the beacon (slice 2)
   }
 
   async function loadApps() {
@@ -574,6 +758,8 @@
       if ($menuBakeItem) $menuBakeItem.disabled = true;
       if ($wfTrigger) $wfTrigger.disabled = true;
       setComboTriggerLabel('no workflows installed');
+      paintBeacon(null); // no workflow open → hide the per-workflow beacon
+      hideSpotlight();
       renderCanvasPlaceholder('empty');
       return;
     }
@@ -814,8 +1000,18 @@
       if (v != null) localStorage.setItem(lsInputsKey(toId), v);
     } catch { /* private mode / quota */ }
   }
+  // A rename is the SAME workflow under a new id → carry its onboarding-seen state so it
+  // doesn't re-pulse "Start here" / re-show the spotlight. (Not done on duplicate: a copy
+  // is a genuinely new workflow that the user hasn't run, so it should start new.)
+  function migrateGuideLS(fromId, toId) {
+    try {
+      const all = guideStateAll();
+      if (all[fromId]) { all[toId] = all[fromId]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); }
+    } catch { /* private mode / quota */ }
+  }
   function dropClientAppState(id) {
     try { localStorage.removeItem(lsInputsKey(id)); } catch { /* ignore */ }
+    try { const all = guideStateAll(); if (all[id]) { delete all[id]; localStorage.setItem(LS_GUIDE, JSON.stringify(all)); } } catch { /* ignore */ }
     appInputValues.delete(id); dirtyBaseline.delete(id); apps.delete(id);
   }
 
@@ -843,6 +1039,7 @@
       // so a rename never silently drops the user's inputs (#85 review). loadApp() only seeds
       // inputs when the id is absent, so pre-setting them here preserves unsaved edits.
       migrateInputsLS(oldId, r.id);
+      migrateGuideLS(oldId, r.id); // carry onboarding-seen state so the renamed workflow doesn't re-pulse
       if (appInputValues.has(oldId)) appInputValues.set(r.id, appInputValues.get(oldId));
       if (dirtyBaseline.has(oldId)) dirtyBaseline.set(r.id, dirtyBaseline.get(oldId));
       const wasOpen = currentId === oldId;
@@ -1767,6 +1964,7 @@
         $reportSub.innerHTML = `Live 3D view from <code>${escapeHtml(nodeId)}</code>${inputBadge ? ' · ' + escapeHtml(inputBadge) : ''} — drag to orbit, scroll to zoom, click an element to inspect.`;
       }
       paintReport(html, interactive);
+      markFirstRunDone(app.id); // a real run rendered → this workflow is no longer "new" (app captured pre-await; a mid-run switch must not mark the wrong workflow)
       lastReportByApp.set(currentId, { nodeId, label: inputBadge, html, interactive });
       $reportModal.dataset.html = '1';
       appendNarration(`Rendered the ${interactive ? '3D view' : 'report'} from <strong>${escapeHtml(nodeId)}</strong>${inputBadge ? ' (' + escapeHtml(inputBadge) + ')' : ''} — live run against the model.`);
@@ -3215,6 +3413,7 @@
       appendNarration(simulate
         ? `Simulated run complete · ${steps} node${steps === 1 ? '' : 's'} stubbed (no host needed) · see the <strong>Execution</strong> tab.`
         : `Run complete · ${steps} node${steps === 1 ? '' : 's'} against the live model · see the <strong>Execution</strong> tab.`);
+      if (!simulate) markFirstRunDone(app.id); // a real run completed → calm the beacon (app captured pre-await)
     } catch (e) {
       const msg = (e && e.message) ? e.message : String(e);
       if (cancelRequested) {
@@ -4116,6 +4315,9 @@
         : '';
       return `In floless app "${req.appId}", re-read & re-bake${where} per the floless-app-rebake skill: ${req.instruction}${snaps}`;
     }
+    if (req.type === 'guide') {
+      return `Walk me through the floless workflow "${req.appId}" — explain in plain English what it does and how to run it (set its inputs → Compile → ▶ Run). Use your floless-app-${req.appId} skill if one exists; otherwise read the workflow's own description and node notes from GET /api/app/${req.appId} and explain from those. This is a guided explanation — don't change anything.`;
+    }
     return '';
   }
 
@@ -4126,6 +4328,9 @@
     tweak: 'floless-app-workflows',
     'ui-customize': 'floless-app-ui',
     rebake: 'floless-app-rebake',
+    // The guided-tour ask is picked up by onboarding; the instruction body names the
+    // per-app floless-app-<appId> skill for depth when one exists.
+    guide: 'floless-app-onboarding',
   };
 
   // The COPIED form of a request: instructionFor() prefixed with a self-identifying
@@ -4220,7 +4425,7 @@
       return;
     }
     $list.innerHTML = pendingRequests.map((r) => {
-      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : 'tweak';
+      const label = r.type === 'use-template' ? 'template' : r.type === 'ui-customize' ? 'dashboard' : r.type === 'rebake' ? 're-bake' : r.type === 'guide' ? 'guide' : 'tweak';
       const badgeCls = r.type === 'tweak' || r.type === 'ui-customize' || r.type === 'rebake' ? 'req-type req-type-tweak' : 'req-type';
       const target = r.type === 'tweak' && r.nodeId
         ? ` · node <code>${escapeHtml(r.nodeId)}</code>`
@@ -5034,6 +5239,7 @@
     try {
       const res = await api('/api/trigger-run', { method: 'POST', body: JSON.stringify({ id, inputs: currentInputs() }) });
       foregroundTrigger = { appId: id, sessionId: res.sessionId, firedCount: 0 };
+      markFirstRunDone(id); // a real live session started → a streaming workflow's "first run" is no longer new
       syncRunControls(); // header ■ Stop run becomes reachable; Run disabled while live
       paintForegroundListening();
       appendNarration(`Live session started for <strong>${escapeHtml(id)}</strong> — the report updates on every event. Click <strong>■ Stop run</strong> (top right) to end it.`);
@@ -5718,6 +5924,25 @@
     if (e.key === 'Escape' && $reqModal && $reqModal.classList.contains('show')) $reqModal.classList.remove('show');
   });
 
+  // Per-workflow onboarding beacon + guide panel + first-open spotlight.
+  const $guideBeaconBtn = document.getElementById('guide-beacon');
+  if ($guideBeaconBtn) $guideBeaconBtn.onclick = () => { hideSpotlight(); openGuide(); };
+  const $guideModal = document.getElementById('guide-modal');
+  const $guideGot = document.getElementById('guide-got-it');
+  if ($guideGot) $guideGot.onclick = () => closeGuide();
+  const $guideWalk = document.getElementById('guide-walk');
+  if ($guideWalk) $guideWalk.onclick = () => requestGuide();
+  if ($guideModal) onBackdropDismiss($guideModal, () => closeGuide());
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape' && $guideModal && $guideModal.classList.contains('show')) closeGuide();
+  });
+  const $spotGot = document.getElementById('guide-spotlight-got');
+  if ($spotGot) $spotGot.onclick = () => hideSpotlight();
+  const $spotShow = document.getElementById('guide-spotlight-show');
+  if ($spotShow) $spotShow.onclick = () => { hideSpotlight(); openGuide(); };
+  const $spotlightEl = document.getElementById('guide-spotlight');
+  if ($spotlightEl) $spotlightEl.onclick = (e) => { if (e.target === $spotlightEl) hideSpotlight(); };
+
   // Pull all workspace data (agents/templates/requests + the apps list). Factored
   // out of bootWorkspace so the health poll can re-pull it after the server comes
   // back from a boot-time outage (setServerStatus → recovery).

package/dist/web/index.html

@@ -58,6 +58,13 @@
         <!-- Agents (⊞) and Routines (⏱) buttons moved into the ≡ menu in #149
              (Ctrl+G / Ctrl+R); the toolbar keeps only the run-critical controls. -->
         <span class="ctl-sep" aria-hidden="true"></span>
+        <!-- Per-workflow onboarding beacon. Pulses "✨ Start here" while this workflow is
+             new to the user (no first Run completed, not dismissed); calms to a quiet
+             "❔ Guide" after — always clickable for re-reference. Hidden until an app loads. -->
+        <button id="guide-beacon" class="guide-beacon" type="button" hidden aria-haspopup="dialog" data-tip="New here? See what this workflow does and how to run it.">
+          <span class="guide-beacon-ico" aria-hidden="true">✦</span>
+          <span class="guide-beacon-label">Start here</span>
+        </button>
         <span class="run-state" id="run-state" role="status" aria-live="polite"></span>
         <button id="compile-btn" data-tip="Compile + approve → freeze the .lock">⎙ Compile</button>
         <button id="sim-btn" data-tip="Simulate: stub every node from its output schema — no live host is contacted. Validates the workflow's composition end-to-end, even when the real agents aren't connected yet.">Simulate</button>
@@ -511,6 +518,37 @@
     </div>
   </div>
 
+  <!-- Per-workflow onboarding "Start here" guide. Surfaces the workflow's plain-English
+       description + a live "Set inputs → Compile → Run" checklist (ticks from real state),
+       and relays a "walk me through it" ask to the terminal AI. A styled modal — never a
+       native dialog; body (#guide-body) is rendered per-open in aware.js. -->
+  <div class="modal-backdrop" id="guide-modal">
+    <div class="modal guide" role="dialog" aria-modal="true" aria-labelledby="guide-title" tabindex="-1">
+      <div class="guide-eyebrow" id="guide-eyebrow">✦ Start here</div>
+      <div class="modal-title" id="guide-title">Workflow</div>
+      <div class="modal-sub">What this workflow does, and how to go through it.</div>
+      <div id="guide-body"></div>
+      <div class="modal-actions">
+        <button id="guide-got-it">Got it</button>
+        <button id="guide-walk" class="primary">Walk me through it →</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- One-time first-open spotlight: dims the canvas and points at the "Start here"
+       beacon, then collapses into it. Shown once per workflow; Esc / click-away / either
+       button dismiss it. The beacon gets .spotlit so it sits above the dim. The bubble is
+       positioned next to the beacon at open time (aware.js). -->
+  <div id="guide-spotlight" class="guide-spotlight" hidden>
+    <div class="guide-spotlight-bubble" role="dialog" aria-modal="false" aria-label="New workflow tip" tabindex="-1">
+      <div class="guide-spotlight-text">New to this workflow? <strong>Start here</strong> — see what it does and how to run it.</div>
+      <div class="guide-spotlight-actions">
+        <button type="button" id="guide-spotlight-got" class="ghost">Got it</button>
+        <button type="button" id="guide-spotlight-show" class="primary">Show me</button>
+      </div>
+    </div>
+  </div>
+
   <!-- Routines — scheduled .flo runs. The list; the add/edit form is its own modal. -->
   <div class="modal-backdrop" id="routines-modal">
     <div class="modal routines">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "type": "module",
   "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
   "bin": {